@agent-compose/sdk 0.2.3 → 0.2.5

package/src/index.ts

@@ -5,11 +5,11 @@
  *
  * Tools for defining runtimes and workflows, registering/invoking them
  * against an agent-compose server, and running LLM agent loops inside a
- * workflow via `runAgent(opts)`.
+ * workflow via `agent(opts)`.
  *
  * @example
  * ```typescript
- * import { defineWorkflow, runAgent, AgentComposeClient } from "@agent-compose/sdk";
+ * import { defineWorkflow, agent, AgentComposeClient } from "@agent-compose/sdk";
  * ```
  */
 
@@ -25,6 +25,7 @@ export type {
   AgentRuntime,
   McpServerConfig,
   ModelExecutionContract,
+  ToolCallGateResult,
   RuntimeOptions,
 } from "./types/runtime.js";
 
@@ -36,6 +37,42 @@ export type {
   AgentBudget,
   WorkflowHooks,
 } from "./types/workflow.js";
+export type { WorkflowPlan, WorkflowStepPlan } from "./types/workflow-plan.js";
+export type { BaseExecutionContext, InvokeChild } from "./types/execution-context.js";
+
+// Request context — per-run typed bag (tenant identity + freeform).
+export {
+  RequestContext,
+  ReservedKeyError,
+  NonSerialisableValueError,
+  AC_RESERVED_PREFIX,
+  AC_TEAM_ID,
+  AC_RUN_ID,
+  AC_WORKFLOW_ID,
+  AC_FACTORY_ID,
+  AC_API_KEY_SCOPES,
+  AC_PARENT_RUN_ID,
+  AC_ABORT_SIGNAL,
+} from "./request-context/index.js";
+export type {
+  RequestContextReserved,
+  RequestContextWire,
+} from "./request-context/index.js";
+
+// Processors — typed pre/post pipeline around the agent loop.
+export {
+  Verdict,
+  runProcessorChain,
+  denyTools,
+  requireScope,
+  redactPattern,
+} from "./processors/index.js";
+export type {
+  Processor,
+  ProcessorContext,
+  ProcessorVerdict,
+  ToolCall,
+} from "./processors/index.js";
 
 // Protocol types (agent-loop input/output shapes)
 export type {
@@ -60,7 +97,15 @@ export type {
 // HTTP client
 export { AgentComposeClient } from "./client.js";
 export type {
-  RegisterResult, RunStatus, FactoryRow, SnapshotListEntry,
+  RegisterResult, RegisterWorkflowInput, RuntimeSourceInput,
+  InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult,
+  ListSnapshotsOptions, TemplateRow, ListTemplatesOptions,
+  CreateFactoryInput, UpdateFactoryInput,
+  SecretOptions, SetSecretResult, SecretListEntry,
+  CreateApiKeyInput, StreamRunLogsOptions,
+  EventSubjectType, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult,
+  RunLogLine, ListRunLogsOptions,
+  RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry,
   ApiKey, ApiKeyCreated,
   UsageRollupRow, UsageResponse,
   CancelRunResponse,
@@ -75,8 +120,13 @@ export { formatError } from "./utils/errors.js";
 
 // Source discovery + bundling utilities
 export { discoverRuntimeName } from "./utils/discovery.js";
-export { bundleWorkflow } from "./utils/bundler.js";
-export type { BundledWorkflow } from "./utils/bundler.js";
+export {
+  bundleWorkflow,
+  BUNDLER_VERSION,
+  WorkflowSourceValidationError,
+  assertDefaultExportIsDefineWorkflow,
+} from "./utils/bundler.js";
+export type { BundledWorkflow, WorkflowManifest } from "./utils/bundler.js";
 
 // Zod schemas
 export { AgentStatusSchema } from "./utils/schemas.js";
@@ -87,6 +137,12 @@ export { AgentStatusSchema } from "./utils/schemas.js";
 export { createClaudeRuntime, ClaudeRunner } from "./runtimes/claude.js";
 export type { ClaudeRuntimeConfig } from "./runtimes/claude.js";
 export { default as claudeRuntime } from "./runtimes/claude.js";
+export { createVercelRuntime, VercelRunner } from "./runtimes/vercel.js";
+export type { VercelRuntimeConfig } from "./runtimes/vercel.js";
+
+// Built-in coding tools for Vercel AI SDK runtime.
+export { bashTool, codingTools, editTool, readTool, writeTool } from "./tools/index.js";
+export type { CodingTool } from "./tools/index.js";
 
 // Streaming event contract
 export type { RunEvent } from "./types/events.js";
@@ -96,16 +152,74 @@ export { createSandbox, reconnectSandbox, killAllSandboxes, killSandboxById,
   getSandboxQuotas, listOwnedSandboxes, deleteSandboxSnapshot,
   makeSandboxProvider, makeDesktopSandboxProvider,
   parseSseExecStream, AGENT_COMPOSE_TAG } from "./sandbox.js";
-export type { SandboxCreateOpts, SandboxNetworkPolicy, OwnedSandbox } from "./sandbox.js";
+export type {
+  SandboxCreateOpts, SandboxNetworkPolicy, SandboxNetworkHeaderTransform,
+  SandboxNetworkAllowRule, SandboxNetworkSubnetPolicy, SandboxProviderName,
+  SandboxQuotaResult, OwnedSandboxResult, OwnedSandbox,
+  ParseSseExecStreamOptions, SandboxCommandRunOptions, SandboxCommandResult,
+} from "./sandbox.js";
 
 // Workflow engine
 export { runWorkflow, WorkflowError, EngineError, classifyError, parseNameVersion } from "./workflows/engine.js";
-export type { WorkflowResult, EngineSubsystem } from "./workflows/engine.js";
+export type { WorkflowResult, RunWorkflowOptions, EngineSubsystem } from "./workflows/engine.js";
+export { buildInvokeChild } from "./workflows/invoke-child.js";
+
+// Step-based workflows — use `defineWorkflow({ id, inputSchema,
+// outputSchema }).step(...).build()` for durable, replayable execution.
+export {
+  defineStep,
+  isWorkflow,
+  runWorkflowSteps,
+  runWorkflowSingleStep,
+  StepValidationError,
+  WorkflowInputValidationError,
+  WorkflowOutputValidationError,
+} from "./workflow-steps/index.js";
+export type {
+  Step,
+  StepContext,
+  StepRunResult,
+  Workflow,
+  DefineStepOpts,
+  StepWorkflowDefinition,
+  WorkflowBuilder,
+  RunWorkflowStepsOpts,
+  RunWorkflowStepsResult,
+  RunWorkflowSingleStepOpts,
+  RunWorkflowSingleStepResult,
+  StepObservability,
+  SubStepEvent,
+} from "./workflow-steps/index.js";
+
+// StepInvocation — wire protocol that lets a server-side activity drive
+// one workflow step inside an existing runner sandbox. Two halves:
+// `invokeStep` (server) and `serveStep` (runner).
+export {
+  invokeStep,
+  serveStep,
+  parseStepResult,
+  buildStepEnvs,
+  StepExecutionError,
+  STEP_RESULT_PREFIX,
+  STEP_ENV,
+  RUNNER_BUNDLE_PATH,
+  RUNNER_COMMAND,
+  stepInputPath,
+  requestContextPath,
+} from "./step-invocation/index.js";
+export type {
+  StepRequest,
+  StepResult,
+  StepInvocationError,
+  StepHandler,
+  StepHandlerResult,
+  ServeStepRequest,
+} from "./step-invocation/index.js";
 
 // Agent loop — for workflows that embed an LLM agent in their run() body.
 export { agentLoop, parseAgentStatus, DEFAULT_CLAUDE_MODEL } from "./agent/agent-loop.js";
-export type { AgentLoopResult } from "./agent/agent-loop.js";
-export { runAgent } from "./agent/run-agent.js";
-export type { RunAgentOpts } from "./agent/run-agent.js";
+export type { AgentLifecycleEvent, AgentLoopOpts, AgentLoopResult } from "./agent/agent-loop.js";
+export { agent } from "./agent/run-agent.js";
+export type { AgentOpts } from "./agent/run-agent.js";
 export { AgentMessageSchema, parseAgentResponse } from "./agent/protocol.js";
 export { importSourceModule, TMP_DIR, LATEST_VERSION } from "./utils/source-loader.js";

package/src/processors/builtins.ts

@@ -0,0 +1,72 @@
+/**
+ * Built-in processors — minimal set that exercises all three hooks and
+ * covers the most common gating needs. More can be authored by users; these
+ * exist as load-bearing examples and as defaults for common policies.
+ */
+
+import type { Processor } from "./processor.js";
+import { Verdict } from "./processor.js";
+
+/**
+ * Reject any tool call whose name appears in `names`. The reason is returned
+ * to the model as the tool result, so the model can react and try a
+ * different approach.
+ *
+ * Dormant in runtimes that don't support pre-tool gating (current Claude CLI
+ * runtime). Becomes active when a runtime that wires `processToolCall` lands
+ * (candidate #1).
+ */
+export function denyTools(names: readonly string[]): Processor {
+  const banned = new Set(names);
+  return {
+    name: "denyTools",
+    processToolCall: (call) =>
+      banned.has(call.toolName)
+        ? Verdict.deny(`tool "${call.toolName}" is denied by policy`)
+        : Verdict.continue(call),
+  };
+}
+
+/**
+ * Require the calling API key to carry every scope in `required`. Aborts the
+ * agent loop with a clear reason if any are missing — defence-in-depth on
+ * top of the server's per-call scope checks.
+ *
+ * Runs as `processInput` so the violation is caught before the model is
+ * invoked, not after work has happened.
+ */
+export function requireScope(required: readonly string[]): Processor {
+  return {
+    name: "requireScope",
+    processInput: (prompt, ctx) => {
+      const missing = required.filter((s) => !ctx.requestContext.hasScope(s));
+      return missing.length === 0
+        ? Verdict.continue(prompt)
+        : Verdict.abort(`API key is missing required scopes: ${missing.join(", ")}`);
+    },
+  };
+}
+
+/**
+ * Redact substrings matching `pattern` from each emitted text/thinking
+ * message before downstream observability sees it. Useful for stripping
+ * accidental secret echoes (e.g. a model that pasted an env var into its
+ * reasoning).
+ *
+ * Tool result and tool use messages are passed through unchanged — those
+ * paths have their own redaction story (network policy + secret brokering).
+ */
+export function redactPattern(pattern: RegExp, replacement = "[REDACTED]"): Processor {
+  return {
+    name: "redactPattern",
+    processOutput: (message) => {
+      if (message.type === "text" || message.type === "thinking") {
+        const redacted = message.text.replace(pattern, replacement);
+        if (redacted !== message.text) {
+          return Verdict.continue({ ...message, text: redacted });
+        }
+      }
+      return Verdict.continue(message);
+    },
+  };
+}

package/src/processors/index.ts

@@ -0,0 +1,15 @@
+export type {
+  Processor,
+  ProcessorContext,
+  ProcessorVerdict,
+  ToolCall,
+} from "./processor.js";
+export { Verdict } from "./processor.js";
+
+export { runProcessorChain } from "./runner.js";
+
+export {
+  denyTools,
+  requireScope,
+  redactPattern,
+} from "./builtins.js";

package/src/processors/processor.ts

@@ -0,0 +1,103 @@
+/**
+ * Processor — typed pre/post pipeline around the agent loop.
+ *
+ * One generic shape across three hook points:
+ *
+ *   - processInput(prompt, ctx)     → before each iteration's model call
+ *   - processOutput(message, ctx)   → after each emitted message
+ *   - processToolCall(call, ctx)    → before each tool call (runtime-driven)
+ *
+ * Why this exists: the user's "pre-tool-use hook", "policy", "falsifier", and
+ * "classifier" requirements are all the same shape — a typed step around the
+ * agent loop with access to RequestContext, an abort channel, and the
+ * ability to mutate or reject. Inventing four parallel APIs is the smell;
+ * one Processor interface is the cure.
+ *
+ * Verdict semantics differ by hook:
+ *
+ *   processInput deny    → agent loop ends with WorkflowError(reason)
+ *   processOutput deny   → message dropped; loop continues
+ *   processToolCall deny → tool short-circuited; reason returned to the
+ *                          model as the tool result; loop continues
+ *
+ *   abort (any hook)     → whole agent loop ends with WorkflowError(reason)
+ *
+ * Composition: workflow-level processors run first, then agent-level. First
+ * non-`continue` verdict short-circuits the chain for that hook target.
+ *
+ * Built-ins live in ./builtins.ts; chain executor lives in ./runner.ts.
+ */
+
+import type { AgentMessage } from "../types/protocol.js";
+import type { RequestContext } from "../request-context/request-context.js";
+
+/** Proposed tool call. Mirrors the relevant fields of AgentMessageToolUse but
+ *  lives as its own type so runtime adapters (candidate #1) can populate it
+ *  from their internal call shape without coupling to the agent message protocol. */
+export interface ToolCall {
+  toolName:   string;
+  toolInput:  Record<string, unknown>;
+  toolUseId:  string;
+}
+
+/** Per-hook context. Minimal by design — observability sinks and stream
+ *  writers are NOT shipped in v1; add when concrete need shows up. */
+export interface ProcessorContext {
+  /** Per-run typed bag (tenant identity + freeform). */
+  requestContext: RequestContext;
+  /** Parent-loop cancellation — long-running processors should pass to fetch/etc. */
+  abortSignal:    AbortSignal;
+  /** How many times processors have triggered retry for this generation. */
+  retryCount:     number;
+  /** Which agent loop triggered this hook. */
+  agentId:        string;
+  /** Iteration of the agent loop (1-based). */
+  iteration:      number;
+}
+
+/**
+ * Verdict returned by every processor method.
+ * `continue` carries the (possibly mutated) value forward.
+ * `deny` and `abort` short-circuit the chain; their loop-level effect is
+ * defined per hook (see file header).
+ */
+export type ProcessorVerdict<T> =
+  | { kind: "continue"; value: T }
+  | { kind: "deny";     reason: string }
+  | { kind: "abort";    reason: string };
+
+/** Construction helpers — keep call sites readable. */
+export const Verdict = {
+  continue: <T>(value: T): ProcessorVerdict<T> => ({ kind: "continue", value }),
+  deny:     <T = never>(reason: string): ProcessorVerdict<T> => ({ kind: "deny", reason }),
+  abort:    <T = never>(reason: string): ProcessorVerdict<T> => ({ kind: "abort", reason }),
+} as const;
+
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * A Processor implements zero or more of the three hook methods. Methods
+ * may be sync or async. Omit a method to opt out of that hook.
+ *
+ * Processors should be cheap and deterministic where possible — the chain
+ * runs sequentially and gating is order-sensitive.
+ */
+export interface Processor {
+  /** Stable name for logging / metrics. Defaults to constructor / class name. */
+  readonly name?: string;
+
+  processInput?(
+    prompt: string,
+    ctx:    ProcessorContext,
+  ): MaybePromise<ProcessorVerdict<string>>;
+
+  processOutput?(
+    message: AgentMessage,
+    ctx:     ProcessorContext,
+  ): MaybePromise<ProcessorVerdict<AgentMessage>>;
+
+  processToolCall?(
+    call: ToolCall,
+    ctx:  ProcessorContext,
+  ): MaybePromise<ProcessorVerdict<ToolCall>>;
+}

package/src/processors/runner.ts

@@ -0,0 +1,42 @@
+/**
+ * Processor chain runner — sequentially applies a list of processors to a
+ * value at one hook point, threading the (possibly mutated) value through
+ * each step. First non-`continue` verdict short-circuits the rest of the
+ * chain for that target.
+ *
+ * The chain is hook-agnostic: caller passes a `select` function that picks
+ * the relevant method off each Processor. Returns the final verdict — the
+ * agent loop interprets it per-hook semantics.
+ */
+
+import type {
+  Processor,
+  ProcessorContext,
+  ProcessorVerdict,
+} from "./processor.js";
+
+type HookSelector<T> = (
+  p: Processor,
+) => ((value: T, ctx: ProcessorContext) => ProcessorVerdict<T> | Promise<ProcessorVerdict<T>>) | undefined;
+
+/**
+ * Run a chain of processors against `initial`. Skips processors that don't
+ * implement the selected hook. Returns the final verdict; for `continue`
+ * the `value` is the threaded-through (possibly mutated) result.
+ */
+export async function runProcessorChain<T>(
+  processors: readonly Processor[],
+  selectHook: HookSelector<T>,
+  initial:    T,
+  ctx:        ProcessorContext,
+): Promise<ProcessorVerdict<T>> {
+  let current = initial;
+  for (const p of processors) {
+    const fn = selectHook(p);
+    if (!fn) continue;
+    const verdict = await fn.call(p, current, ctx);
+    if (verdict.kind !== "continue") return verdict;
+    current = verdict.value;
+  }
+  return { kind: "continue", value: current };
+}

package/src/request-context/index.ts

@@ -0,0 +1,17 @@
+export {
+  RequestContext,
+  ReservedKeyError,
+  NonSerialisableValueError,
+  AC_RESERVED_PREFIX,
+  AC_TEAM_ID,
+  AC_RUN_ID,
+  AC_WORKFLOW_ID,
+  AC_FACTORY_ID,
+  AC_API_KEY_SCOPES,
+  AC_PARENT_RUN_ID,
+  AC_ABORT_SIGNAL,
+} from "./request-context.js";
+export type {
+  RequestContextReserved,
+  RequestContextWire,
+} from "./request-context.js";