Steadlake AI SDK

@steadlake/ai provides explicit tool(), agent(), step(), and workflow() definitions. Durable definitions compile onto @steadlake/task; the AI package does not own a scheduler, queue, event store, or retry loop.

Public contract

import { agent, step, tool, workflow } from "@steadlake/ai";
import { z } from "zod";

const lookup = tool({
  id: "lookup",
  input: z.object({ query: z.string() }),
  output: z.object({ answer: z.string() }),
  recovery: "read-only",
  execute: async ({ query }) => ({ answer: `Result for ${query}` }),
});

const researcher = agent({
  id: "researcher",
  input: z.object({ query: z.string() }),
  instructions: "Answer using the lookup tool.",
  model: "configured-model",
  tools: { lookup },
  durability: { retry: { maxAttempts: 3 } },
});

const answer = step({
  id: "answer",
  input: z.object({ query: z.string() }),
  output: z.object({ answer: z.string() }),
  execute: async ({ input }) => ({ answer: input.query }),
});

const flow = workflow({
  id: "answer-flow",
  input: z.object({ query: z.string() }),
  output: z.object({ answer: z.string() }),
  durability: {},
})
  .then(answer)
  .commit();

• tool() validates input and output. It is the only model-facing capability boundary. recovery is "read-only", "idempotent-write", or conservatively defaults to "unknown-outcome".
• agent() supports direct generate()/stream(), and durable trigger()/triggerAndWait() when configured with durability.
• step() is a typed application-controlled workflow node.
• workflow() composes finite .then(), .branch(), .parallel(), .foreach(), and explicit .invoke() graph nodes. Durable workflows compile to Task definitions.
• Generic and Next adapters accept raw Task definitions plus durable AI agents and workflows.
• subscribeAgentEvents(run) consumes persisted ai timeline events and resumes by cursor.

Durable replay matrix

| Capability | Durable behavior | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Model turns | Normalized model response, tool-call envelope, usage, and structured output checkpointed per turn. Replays start from the last completed checkpoint, not an in-flight provider socket. | | Tool results | Validated full output and compact model-visible output are checkpointed separately. Completed tool checkpoint results are reused. | | Tool identity | Durable callbacks receive stable toolCallId and idempotencyKey derived from run, turn, and call ID. | | Tool recovery | Unknown-outcome tools execute only through a platform-persisted activity permit; a lost post-start response becomes a reconciliation result and is not silently retried. Read-only and idempotent-write tools retain their stable idempotency key. | | Approvals | Durable tools suspend through Task approval and replay the persisted decision. Approval timeline records contain only bounded, caller-redacted metadata and opaque artifact references. | | Artifacts | Large output, attachments, and traces are represented in AI events/checkpoints by opaque { id, mediaType, sizeBytes?, sha256? } references; the SDK does not embed artifact content. | | Authorization | Platform keys can independently grant runs:trigger, runs:cancel, runs:approve, runs:inspect, runs:send-input, and runs:stream; legacy executions keys remain an umbrella capability. | | Cancellation | Task dispatch AbortSignal is supplied to agents and tools; child invocation metadata requests cascade cancellation. A cancellation observed before a durable checkpoint leaves the run terminally cancelled; an already-started unknown-outcome activity remains a reconciliation case. | | Child invocation | workflow.invoke() creates an isolated durable child run. Requested child ai events are relayed as typed child-event records on the parent stream. | | Workflow state | Schema-validated state is checkpointed after each graph node. Concurrent foreach workers cannot mutate shared workflow state. | | Dynamic fan-out | Durable workflow.foreach() uses Task step.map() and stable generated worker task IDs. | | Streams and channels | Task run events support cursor reconnection. Run.sendChannel() and step.readChannel() define ordered durable input batches. |

Direct execution tests and durable execution tests are intentionally independent. A direct-runtime behavior is not a durable guarantee unless it is represented in the table above and tested through Task redispatch.

Known limits

• Artifact references are a storage contract, not an SDK-managed blob store: applications choose the backing store and must authorize resolution of each opaque reference.
• Redacted approval metadata is caller-provided. The SDK bounds its shape but cannot determine whether an application’s text contains a secret.
• The SDK has no built-in memory, RAG, vector store, sandbox, MCP integration, channel adapter, credential vault, evaluation product, prompt manager, provider router, model-invoked subagent, or stable interactive session identity.
• Skills and context-compaction policies are not yet implemented; durable runs therefore do not support versioned Markdown skill assets or registered context policies.