@agent-compose/sdk 0.2.3 → 0.2.4

package/dist/client.d.ts

@@ -10,22 +10,224 @@
  * `register()` accepts pre-built sources — use the CLI (`agent-compose
  * register`) or build sources yourself and pass them directly.
  */
-import type { RunEvent } from "./types/events.js";
 import type { SandboxNetworkPolicy } from "./sandbox.js";
+import type { RunEvent } from "./types/events.js";
+import type { WorkflowPlan } from "./types/workflow-plan.js";
+import type { WorkflowManifest } from "./utils/bundler.js";
 export interface RegisterResult {
     id: string;
     name: string;
     version: string;
-    runtimes?: Array<{
-        name: string;
-        version: string;
-        id: string;
+    runtimes?: RegisteredRuntime[];
+}
+export interface RegisteredRuntime {
+    id: string;
+    name: string;
+    version: string;
+}
+export interface RuntimeSourceInput {
+    name: string;
+    source: string;
+}
+export interface RegisterWorkflowInput {
+    name: string;
+    source: string;
+    /** Structured attestation produced by `bundleWorkflow`. The server
+     *  requires this on every registration; it proves the source was
+     *  bundled by a `defineWorkflow`-aware toolchain. The server validates
+     *  the manifest's shape and verifies `manifest.sourceHash` matches
+     *  sha256(source) — the source bytes themselves are never parsed or
+     *  executed on the server. */
+    manifest: WorkflowManifest;
+    version?: string;
+    schedule?: string;
+    runtimes?: RuntimeSourceInput[];
+    networkPolicy?: unknown;
+    placeholders?: Record<string, string>;
+    /** Reference to a snapshot the runner should boot from at run start. */
+    snapshot?: string;
+    /** If true, runs default to capturing a long-lived sandbox snapshot on success. */
+    saveSnapshot?: boolean;
+    /** Provider-neutral execution plan detected by the CLI bundler. */
+    workflowPlan?: WorkflowPlan;
+    /** Workflow Memory extraction config. Defaults to "default" when omitted. */
+    memory?: "default" | false | {
+        workflow: string;
+    };
+    /** Factory slug. Defaults to `"default"`. */
+    factorySlug?: string;
+}
+export type RunState = "running" | "success" | "failed" | "abandoned" | "canceled";
+export interface InvokeWorkflowOptions {
+    /** Per-invocation snapshot override: run UUID, workflow name, or `name@version`. */
+    snapshot?: string;
+    /** Per-invocation snapshot capture override. */
+    saveSnapshot?: boolean;
+    /** Per-invocation network policy override. Replaces the template-level
+     *  policy for this run only — registered metadata is not mutated. */
+    networkPolicy?: SandboxNetworkPolicy;
+    /** Per-invocation placeholder override. Maps secret names referenced in
+     *  `networkPolicy` ($VAR) to the values the runner should see for env
+     *  vars after brokering. Replaces the template-level placeholders for
+     *  this run only — registered metadata is not mutated. */
+    placeholders?: Record<string, string>;
+    /** Explicit parent run id. Pass `null` to suppress ambient RUN_ID auto-detection. */
+    parentRunId?: string | null;
+    /** Agent loop inside the parent run that caused this invoke, when applicable. */
+    agentId?: string | null;
+    /** Factory slug. Defaults to `"default"`. */
+    factorySlug?: string;
+}
+export interface InvokeAndWaitOptions extends InvokeWorkflowOptions {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}
+export interface InvokeResult {
+    id: string;
+}
+export interface ListSnapshotsOptions {
+    workflow?: string;
+    limit?: number;
+}
+export interface TemplateRow {
+    name: string;
+    version: string;
+    factorySlug: string;
+}
+export interface ListTemplatesOptions {
+    factorySlug?: string;
+}
+export interface CreateFactoryInput {
+    slug: string;
+    name: string;
+    description?: string;
+}
+export interface UpdateFactoryInput {
+    name?: string;
+    description?: string;
+}
+export interface SecretOptions {
+    factorySlug?: string;
+}
+export interface SetSecretResult {
+    key: string;
+}
+export interface SecretListEntry {
+    key: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateApiKeyInput {
+    name?: string;
+    scopes?: string[];
+    expiresAt?: string;
+    factorySlug?: string;
+}
+export interface StreamRunLogsOptions {
+    lastEventId?: number;
+    signal?: AbortSignal;
+}
+export interface RunStatus<TOutput = unknown> {
+    id: string;
+    status: RunState;
+    output?: TOutput;
+}
+export interface RunDetail<TOutput = unknown> {
+    runId: string;
+    title: string;
+    metadata: Record<string, unknown>;
+    outcome: string;
+    startedAt: string;
+    endedAt: string | null;
+    durationMs: number | null;
+    failureReason: string | null;
+    input: unknown;
+    output: TOutput | null;
+    lifecycleEvents: Array<{
+        at: string;
+        type: string;
+        payload: unknown;
     }>;
+    children?: RunDetail[];
 }
-export interface RunStatus {
+export interface TimelineEvent {
+    kind: string;
+    at: string;
+    seq: number;
+    type: string;
+    payload: Record<string, unknown>;
+}
+export type EventSubjectType = "run" | "agent" | "workflow" | "factory";
+export interface EventRow {
     id: string;
-    status: "running" | "success" | "failed" | "abandoned" | "canceled";
-    output?: Record<string, unknown>;
+    teamId: string;
+    subjectType: EventSubjectType | string;
+    subjectId: string;
+    runId: string | null;
+    agentId: string | null;
+    workflowId: string | null;
+    factoryId: string | null;
+    name: string;
+    body: unknown;
+    summary: string | null;
+    confidence: string | null;
+    timestamp: string;
+    attributes: Record<string, unknown>;
+    propagate: boolean;
+    idempotencyKey: string | null;
+    createdAt: string;
+}
+export interface ReportEventInput {
+    name: string;
+    body: unknown;
+    summary?: string;
+    confidence?: number;
+    timestamp?: string | Date;
+    attributes?: Record<string, unknown>;
+    propagate?: boolean;
+    idempotencyKey?: string;
+}
+export interface ListEventsOptions {
+    factorySlug?: string;
+    limit?: number;
+    /** Case-insensitive substring match. Server uses `ILIKE %name%`, so
+     *  `"mem"` matches `memory.fact`, `memory.usage`, etc. Pass the
+     *  full event name for an effectively-exact filter (any string is a
+     *  substring of itself). */
+    name?: string;
+    /** Date-range lower bound: only include events at or after this
+     *  timestamp. Used by the dashboard's range toggle (1h / 24h / 7d
+     *  / 30d). Same semantics as `from` on the runs list endpoint. */
+    from?: string;
+    /** Timestamp cursor for "load older" pagination. Pass the
+     *  `timestamp` of the last row from the previous page; the server
+     *  returns rows strictly older than that. Distinct from `from`:
+     *  `from` filters a date range, `before` walks the page boundary.
+     *  Both can be supplied together for a paginated range-query. */
+    before?: string;
+}
+export interface ListEventsResult {
+    events: EventRow[];
+    has_more: boolean;
+}
+/** One captured stdout or stderr line from a run's sandbox subprocess.
+ *  `id` is per-run monotonically increasing — pass the highest `id`
+ *  you've seen as `afterId` to paginate forward. */
+export interface RunLogLine {
+    id: number;
+    at: string;
+    stream: "stdout" | "stderr";
+    line: string;
+}
+export interface ListRunLogsOptions {
+    /** Return only lines with `id > afterId` (forward pagination). */
+    afterId?: number;
+    /** Max lines (server clamps to [1, 1000], defaults to 200). */
+    limit?: number;
+    /** Stream direction. `"asc"` (default) returns the oldest lines first
+     *  — use with `afterId` to paginate forward. `"desc"` returns the newest
+     *  lines first — use to fetch the last N lines of a finished run. */
+    direction?: "asc" | "desc";
 }
 /** Row shape returned by `GET /api-keys`. */
 export interface ApiKey {
@@ -86,30 +288,7 @@ export declare class AgentComposeClient {
     constructor(baseUrl: string, apiKey: string);
     /** Register (or update) a workflow template inside a factory. Defaults to
      *  the team's `default` factory when `factorySlug` is omitted. */
-    register(payload: {
-        name: string;
-        source: string;
-        version?: string;
-        schedule?: string;
-        runtimes?: Array<{
-            name: string;
-            source: string;
-        }>;
-        networkPolicy?: unknown;
-        placeholders?: Record<string, string>;
-        /** Reference to a snapshot the runner should boot from at run start.
-         *  A run UUID, workflow name, or `name@version`. The referenced
-         *  workflow must have been registered with `--build` (or any prior
-         *  successful run with `saveSnapshot: true`). Per-invocation
-         *  `invoke({ snapshot })` overrides this default. */
-        snapshot?: string;
-        /** If true, runs default to capturing a long-lived sandbox snapshot on
-         *  success. Individual invocations can override via
-         *  `invoke(..., { saveSnapshot })`. */
-        saveSnapshot?: boolean;
-        /** Factory slug. Defaults to `"default"`. */
-        factorySlug?: string;
-    }): Promise<RegisterResult>;
+    register(payload: RegisterWorkflowInput): Promise<RegisterResult>;
     /** Invoke a workflow. Returns run ID immediately — workflow runs asynchronously.
      *
      *  `snapshot`: per-invocation override of the template-level `snapshot`
@@ -132,16 +311,7 @@ export declare class AgentComposeClient {
      *  current run). Explicit non-null wins over auto-detection.
      *
      *  `factorySlug`: defaults to `"default"`. */
-    invoke(name: string, input?: Record<string, unknown>, opts?: {
-        snapshot?: string;
-        saveSnapshot?: boolean;
-        parentRunId?: string | null;
-        factorySlug?: string;
-        networkPolicy?: SandboxNetworkPolicy;
-        placeholders?: Record<string, string>;
-    }): Promise<{
-        id: string;
-    }>;
+    invoke(name: string, input?: Record<string, unknown>, opts?: InvokeWorkflowOptions): Promise<InvokeResult>;
     /** Invoke a workflow and wait for it to settle (success / failed / abandoned).
      *  Polls `getStatus` on a fixed interval. Rejects with `AgentComposeError`
      *  if the run settles non-success, or a plain `Error` on timeout.
@@ -149,85 +319,66 @@ export declare class AgentComposeClient {
      *  Defaults: `timeoutMs = 30min`, `pollIntervalMs = 1000ms`. Tune down for
      *  tests, tune up for long-running workflows. The parent-child auto-
      *  detection from `invoke()` applies here too. */
-    invokeAndWait(name: string, input?: Record<string, unknown>, opts?: {
-        snapshot?: string;
-        saveSnapshot?: boolean;
-        parentRunId?: string | null;
-        factorySlug?: string;
-        networkPolicy?: SandboxNetworkPolicy;
-        placeholders?: Record<string, string>;
-        timeoutMs?: number;
-        pollIntervalMs?: number;
-    }): Promise<RunStatus>;
+    invokeAndWait<TOutput = unknown>(name: string, input?: Record<string, unknown>, opts?: InvokeAndWaitOptions): Promise<RunStatus<TOutput>>;
     /** List runs this account has captured snapshots for. */
-    listSnapshots(opts?: {
-        workflow?: string;
-        limit?: number;
-    }): Promise<SnapshotListEntry[]>;
+    listSnapshots(opts?: ListSnapshotsOptions): Promise<SnapshotListEntry[]>;
     /** Delete the snapshot captured by a specific run. Frees Vercel storage. */
     deleteSnapshot(runId: string): Promise<void>;
     /** Poll run status. */
-    getStatus(runId: string): Promise<RunStatus>;
+    getStatus<TOutput = unknown>(runId: string): Promise<RunStatus<TOutput>>;
+    /** Full run detail, including input/output and lifecycle events. */
+    getRun<TOutput = unknown>(runId: string): Promise<RunDetail<TOutput>>;
+    /** Ordered lifecycle timeline for one run. */
+    getRunTimeline(runId: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<TimelineEvent[]>;
+    /** Report a durable event against a run. Events are late-binding facts
+     * like quality.accepted, defect.regression, or intervention.override. */
+    reportEvent(runId: string, input: ReportEventInput): Promise<EventRow>;
+    listRunEvents(runId: string): Promise<EventRow[]>;
+    /** List events ingested into a factory, newest first. Supports
+     *  case-insensitive substring filter (`name`) and timestamp-cursor
+     *  pagination (`before`). Returns `{ events, has_more }` — the
+     *  `has_more` flag is the signal to render a "load more" affordance
+     *  or fire a follow-up request with `before = events.at(-1).timestamp`. */
+    listFactoryEvents(opts?: ListEventsOptions): Promise<ListEventsResult>;
+    /** Fetch captured stdout / stderr lines for a run, ordered by insertion
+     *  sequence. Pass `afterId` (the highest `id` from a prior page) for
+     *  forward pagination — useful for tail-style polling without
+     *  re-fetching the whole stream. `limit` defaults to 200 server-side and
+     *  is clamped to [1, 1000]. */
+    listRunLogs(runId: string, opts?: ListRunLogsOptions): Promise<RunLogLine[]>;
     /** List registered workflow templates. When `factorySlug` is supplied,
      *  scopes to that factory; otherwise returns every template the team can
      *  see across every factory in one round trip — each row carries its
      *  `factorySlug` so callers can route per-template actions to the right
      *  factory. */
-    listTemplates(opts?: {
-        factorySlug?: string;
-    }): Promise<Array<{
-        name: string;
-        version: string;
-        factorySlug: string;
-    }>>;
+    listTemplates(opts?: ListTemplatesOptions): Promise<TemplateRow[]>;
     /** List factories for the caller's team. */
     listFactories(): Promise<FactoryRow[]>;
     /** Create a factory. `slug` must be lowercase kebab-case and unique
      *  within the team. */
-    createFactory(payload: {
-        slug: string;
-        name: string;
-        description?: string;
-    }): Promise<FactoryRow>;
+    createFactory(payload: CreateFactoryInput): Promise<FactoryRow>;
     /** Get a factory by slug. */
     getFactory(slug: string): Promise<FactoryRow>;
     /** Rename or describe a factory. */
-    updateFactory(slug: string, updates: {
-        name?: string;
-        description?: string;
-    }): Promise<FactoryRow>;
+    updateFactory(slug: string, updates: UpdateFactoryInput): Promise<FactoryRow>;
     /** Delete a factory. Refuses `default` and any factory still
      *  containing workflows. */
     deleteFactory(slug: string): Promise<void>;
     /** Create or update a workflow secret. Value is stored in GCP Secret Manager. */
-    setSecret(workflowName: string, key: string, value: string, opts?: {
-        factorySlug?: string;
-    }): Promise<{
-        key: string;
-    }>;
+    setSecret(workflowName: string, key: string, value: string, opts?: SecretOptions): Promise<SetSecretResult>;
     /** List secret keys registered for a workflow (metadata only — values are never returned). */
-    listSecrets(workflowName: string, opts?: {
-        factorySlug?: string;
-    }): Promise<Array<{
-        key: string;
-        createdAt: string;
-        updatedAt: string;
-    }>>;
+    listSecrets(workflowName: string, opts?: SecretOptions): Promise<SecretListEntry[]>;
     /** Delete a workflow secret. */
-    deleteSecret(workflowName: string, key: string, opts?: {
-        factorySlug?: string;
-    }): Promise<void>;
+    deleteSecret(workflowName: string, key: string, opts?: SecretOptions): Promise<void>;
     /** Create a new API key on the caller's team. The plaintext `key` is
      *  returned once — it cannot be retrieved later.
      *
      *  When `factorySlug` is set, the new key is restricted to that factory.
      *  Factory-scoped keys can only mint other keys bound to the same factory. */
-    createApiKey(input: {
-        name?: string;
-        scopes?: string[];
-        expiresAt?: string;
-        factorySlug?: string;
-    }): Promise<ApiKeyCreated>;
+    createApiKey(input: CreateApiKeyInput): Promise<ApiKeyCreated>;
     /** List API keys on the caller's team (metadata only — plaintext keys are
      *  never returned). */
     listApiKeys(): Promise<ApiKey[]>;
@@ -244,16 +395,13 @@ export declare class AgentComposeClient {
      *  `lastEventId` enables resume — pass the highest `seq` you've already
      *  processed to receive only events you missed.
      *
-     *  `signal` can be used to abort the stream from the caller side.
+     *  `event` can be used to abort the stream from the caller side.
      *
      *  Uses raw `fetch` (not ofetch) because SSE requires access to the
      *  response's `ReadableStream`, which ofetch consumes when parsing. Auth
      *  + base URL are still sourced from the same constructor inputs, and
      *  non-2xx responses throw the same `AgentComposeError`. */
-    streamRunLogs(runId: string, opts?: {
-        lastEventId?: number;
-        signal?: AbortSignal;
-    }): AsyncGenerator<RunEvent>;
+    streamRunLogs(runId: string, opts?: StreamRunLogsOptions): AsyncGenerator<RunEvent>;
 }
 /** A factory: a project-level grouping of workflows inside a team. */
 export interface FactoryRow {

package/dist/index.d.ts

@@ -3,11 +3,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";
  * ```
  */
 export { defineRuntime } from "./types/runtime.js";
@@ -15,30 +15,45 @@ export { defineWorkflow } from "./types/workflow.js";
 export type { WorkflowDefinition } from "./types/workflow.js";
 export { defineSandboxEnvironment } from "./types/sandbox-environment.js";
 export type { SandboxEnvironmentDefinition } from "./types/sandbox-environment.js";
-export type { AgentRuntime, McpServerConfig, ModelExecutionContract, RuntimeOptions, } from "./types/runtime.js";
+export type { AgentRuntime, McpServerConfig, ModelExecutionContract, ToolCallGateResult, RuntimeOptions, } from "./types/runtime.js";
 export type { WorkflowFn, WorkflowCtx, WorkflowRun, AgentBudget, WorkflowHooks, } from "./types/workflow.js";
+export type { WorkflowPlan, WorkflowStepPlan } from "./types/workflow-plan.js";
+export type { BaseExecutionContext, InvokeChild } from "./types/execution-context.js";
+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";
+export { Verdict, runProcessorChain, denyTools, requireScope, redactPattern, } from "./processors/index.js";
+export type { Processor, ProcessorContext, ProcessorVerdict, ToolCall, } from "./processors/index.js";
 export type { AgentMessage, AgentMessageInit, AgentMessageText, AgentMessageThinking, AgentMessageToolUse, AgentMessageToolResult, AgentMessageDone, AgentMessageError, AgentMessageUsage, AgentStatus, } from "./types/protocol.js";
 export type { SandboxProvider, DesktopSandboxProvider, } from "./types/sandbox.js";
 export { AgentComposeClient } from "./client.js";
-export type { RegisterResult, RunStatus, FactoryRow, SnapshotListEntry, ApiKey, ApiKeyCreated, UsageRollupRow, UsageResponse, CancelRunResponse, } from "./client.js";
+export type { 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, } from "./client.js";
 export { parseSseStream } from "./sse.js";
 export { AgentComposeError } from "./errors.js";
 export { formatError } from "./utils/errors.js";
 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";
 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";
+export { bashTool, codingTools, editTool, readTool, writeTool } from "./tools/index.js";
+export type { CodingTool } from "./tools/index.js";
 export type { RunEvent } from "./types/events.js";
 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";
 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";
+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";
+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";
 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";