@blacklake-systems/depth-sdk

⚠️ Deprecated. This package is now part of the unified blacklake npm package. Install blacklake and import { workflow, step } from 'blacklake'. See the migration doc for sed-style search-and-replace examples. This package will continue to ship as a thin re-export through the next two minor versions.

Durable workflows for BlackLake — long-running AI work 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. Now part of the unified blacklake package.

BlackLake is AI control infrastructure and analytics. Surface evaluates tool calls against your policies and budgets before they execute, routes approvals, records cost, and signs receipts. Run Surface at console.blacklake.systems or locally via npx blacklake serve; run Depth workflows from the npm package and connect them to whichever Surface control plane you use.

Install

npm install @blacklake-systems/depth-sdk

Quick Start

Sign up at console.blacklake.systems for hosted Surface when you need shared controls, 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 connect the workflow to hosted Surface at console.blacklake.systems.

Local 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.