@blacklake-systems/depth-sdk

@blacklake-systems/depth-sdk

Depth is the durable-execution half of the BlackLake platform. It runs AI agent workflows as TypeScript async functions, persisting each step to a local SQLite database so runs can resume from where they left off after a crash or restart.

The other half of the platform is Surface — the governance control plane. Surface evaluates every tool call against your policies before it executes. It runs either at console.blacklake.systems or self-hosted via npx @blacklake-systems/surface-cli.

Install

npm install @blacklake-systems/depth-sdk

Quick Start

Sign up at console.blacklake.systems for the hosted Surface control plane, then write a workflow:

import { workflow, step } from '@blacklake-systems/depth-sdk';

export default workflow('expense-report', async (ctx) => {
  const summary = await step(ctx, 'summarise', async () => {
    return await ctx.llm('anthropic:claude-sonnet-4-6', {
      prompt: 'Summarise this month\'s expenses.',
    });
  });

  await step(ctx, 'file-report', async () => {
    // tool calls route through Surface for governance automatically
    await ctx.tool('filesystem.writeFile', {
      path: './report.md',
      content: summary,
    });
  });

  return { summary };
});

Run it with the CLI:

npx @blacklake-systems/depth-cli run workflow.ts

Or use the hosted version at console.blacklake.systems

Self-hosted Surface

If you prefer to run Surface locally, start it first:

npx @blacklake-systems/surface-cli

Depth detects Surface at localhost:3100 automatically — no additional configuration needed.

Surface Integration

When Surface is reachable, Depth automatically:

• Routes tool calls through Surface's governance engine
• Creates approvals in Surface's console for human review
• Tracks costs in Surface's usage dashboard

When Surface is not reachable, tool calls execute directly.

API Reference

workflow(name, fn)

Define a durable workflow.

import { workflow } from '@blacklake-systems/depth-sdk';

export default workflow('my-workflow', async (ctx, input: { topic: string }) => {
  // ctx.llm, ctx.tool, and step() are available here
  return { result: 'done' };
});

step(ctx, name, fn)

Wrap a unit of work in a durable step. The return value is persisted; on replay the function is skipped and the stored value is returned.

import { step } from '@blacklake-systems/depth-sdk';

const result = await step(ctx, 'step-name', async () => {
  return await someExpensiveOperation();
});

ctx.llm(model, options)

Call a language model. Supported prefixes: anthropic:, openai:, ollama:.

const text = await ctx.llm('anthropic:claude-sonnet-4-6', {
  prompt: 'Write a haiku about durable execution.',
});

ctx.tool(name, args)

Invoke a tool. When Surface is running, the call is governed before execution.

await ctx.tool('filesystem.writeFile', { path: './out.md', content: text });

Documentation

Full documentation at blacklake.systems/docs.