@agent-compose/sdk 0.2.3 → 0.2.4

package/src/client.ts

@@ -14,8 +14,10 @@
 import { ofetch } from "ofetch";
 import { AgentComposeError } from "./errors.js";
 import { parseSseStream } from "./sse.js";
-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";
 
 /** UUID-v4-ish — matches the server-side predicate. Used to auto-detect
  *  that `process.env.RUN_ID` was injected by the runner sandbox (rather
@@ -48,13 +50,237 @@ 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`. */
@@ -133,27 +359,7 @@ export class AgentComposeClient {
 
   /** 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> {
     const { factorySlug = DEFAULT_FACTORY, ...body } = payload;
     return this.fetch(templatePath(factorySlug), { method: "POST", body });
   }
@@ -183,15 +389,8 @@ export class AgentComposeClient {
   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 }> {
+    opts?: InvokeWorkflowOptions,
+  ): Promise<InvokeResult> {
     const parentRunId = opts?.parentRunId === undefined
       ? detectAmbientParentRunId()
       : opts.parentRunId;
@@ -200,11 +399,12 @@ export class AgentComposeClient {
       method: "POST",
       body: {
         input,
-        ...(opts?.snapshot     !== undefined ? { snapshot:     opts.snapshot }     : {}),
-        ...(opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {}),
-        ...(parentRunId                      ? { parentRunId }                     : {}),
+        ...(opts?.snapshot      !== undefined ? { snapshot:      opts.snapshot }      : {}),
+        ...(opts?.saveSnapshot  !== undefined ? { saveSnapshot:  opts.saveSnapshot }  : {}),
         ...(opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {}),
         ...(opts?.placeholders  !== undefined ? { placeholders:  opts.placeholders }  : {}),
+        ...(parentRunId                       ? { parentRunId }                       : {}),
+        ...(opts?.agentId                     ? { agentId: opts.agentId }             : {}),
       },
     });
   }
@@ -216,33 +416,20 @@ export 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. */
-  async invokeAndWait(
+  async invokeAndWait<TOutput = unknown>(
     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> {
+    opts?: InvokeAndWaitOptions,
+  ): Promise<RunStatus<TOutput>> {
     const timeoutMs = opts?.timeoutMs ?? 30 * 60 * 1000;
     const pollMs    = opts?.pollIntervalMs ?? 1000;
-    const { id: runId } = await this.invoke(name, input, {
-      ...(opts?.snapshot     !== undefined ? { snapshot:     opts.snapshot }     : {}),
-      ...(opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {}),
-      ...(opts?.parentRunId  !== undefined ? { parentRunId:  opts.parentRunId }  : {}),
-      ...(opts?.factorySlug  !== undefined ? { factorySlug:  opts.factorySlug }  : {}),
-      ...(opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {}),
-      ...(opts?.placeholders  !== undefined ? { placeholders:  opts.placeholders }  : {}),
-    });
+    // InvokeAndWaitOptions extends InvokeWorkflowOptions, so we can forward
+    // `opts` directly — invoke() picks only the fields it sends, so the
+    // extra `timeoutMs` / `pollIntervalMs` never leak into the request body.
+    const { id: runId } = await this.invoke(name, input, opts);
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-      const status = await this.getStatus(runId);
+      const status = await this.getStatus<TOutput>(runId);
       if (status.status === "success" || status.status === "failed" || status.status === "abandoned") {
         return status;
       }
@@ -255,7 +442,7 @@ export class AgentComposeClient {
   }
 
   /** List runs this account has captured snapshots for. */
-  async listSnapshots(opts?: { workflow?: string; limit?: number }): Promise<SnapshotListEntry[]> {
+  async listSnapshots(opts?: ListSnapshotsOptions): Promise<SnapshotListEntry[]> {
     const q = new URLSearchParams();
     if (opts?.workflow) q.set("workflow", opts.workflow);
     if (opts?.limit    != null) q.set("limit", String(opts.limit));
@@ -271,20 +458,88 @@ export class AgentComposeClient {
   }
 
   /** Poll run status. */
-  getStatus(runId: string): Promise<RunStatus> {
+  getStatus<TOutput = unknown>(runId: string): Promise<RunStatus<TOutput>> {
     return this.fetch(`/api/v1/workflows/${runId}/status`);
   }
 
+  /** Full run detail, including input/output and lifecycle events. */
+  getRun<TOutput = unknown>(runId: string): Promise<RunDetail<TOutput>> {
+    return this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}`);
+  }
+
+  /** Ordered lifecycle timeline for one run. */
+  async getRunTimeline(runId: string, opts?: { limit?: number; offset?: number }): Promise<TimelineEvent[]> {
+    const q = new URLSearchParams();
+    if (opts?.limit !== undefined) q.set("limit", String(opts.limit));
+    if (opts?.offset !== undefined) q.set("offset", String(opts.offset));
+    const body = await this.fetch<{ events: TimelineEvent[] }>(
+      `/api/v1/workflows/${encodeURIComponent(runId)}/timeline${q.toString() ? `?${q}` : ""}`,
+    );
+    return body.events;
+  }
+
+  /** Report a durable event against a run. Events are late-binding facts
+   * like quality.accepted, defect.regression, or intervention.override. */
+  async reportEvent(runId: string, input: ReportEventInput): Promise<EventRow> {
+    const body = {
+      ...input,
+      ...(input.timestamp instanceof Date ? { timestamp: input.timestamp.toISOString() } : {}),
+    };
+    const response = await this.fetch<{ event: EventRow }>(`/api/v1/workflows/${encodeURIComponent(runId)}/events`, {
+      method: "POST",
+      body,
+    });
+    return response.event;
+  }
+
+  async listRunEvents(runId: string): Promise<EventRow[]> {
+    const body = await this.fetch<{ events: EventRow[] }>(`/api/v1/workflows/${encodeURIComponent(runId)}/events`);
+    return body.events;
+  }
+
+  /** 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`. */
+  async listFactoryEvents(opts?: ListEventsOptions): Promise<ListEventsResult> {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const q = new URLSearchParams();
+    if (opts?.limit  != null) q.set("limit",  String(opts.limit));
+    if (opts?.name)           q.set("name",   opts.name);
+    if (opts?.from)           q.set("from",   opts.from);
+    if (opts?.before)         q.set("before", opts.before);
+    return this.fetch<ListEventsResult>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/events${q.toString() ? `?${q}` : ""}`,
+    );
+  }
+
+  /** 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]. */
+  async listRunLogs(runId: string, opts?: ListRunLogsOptions): Promise<RunLogLine[]> {
+    const q = new URLSearchParams();
+    if (opts?.afterId   !== undefined) q.set("afterId",   String(opts.afterId));
+    if (opts?.limit     !== undefined) q.set("limit",     String(opts.limit));
+    if (opts?.direction !== undefined) q.set("direction", opts.direction);
+    const body = await this.fetch<{ logs: RunLogLine[] }>(
+      `/api/v1/workflows/${encodeURIComponent(runId)}/logs${q.toString() ? `?${q}` : ""}`,
+    );
+    return body.logs;
+  }
+
   /** 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. */
-  async listTemplates(opts?: { factorySlug?: string }): Promise<Array<{ name: string; version: string; factorySlug: string }>> {
+  async listTemplates(opts?: ListTemplatesOptions): Promise<TemplateRow[]> {
     const path = opts?.factorySlug
       ? templatePath(opts.factorySlug)
       : "/api/v1/templates";
-    const body = await this.fetch<{ templates: Array<{ name: string; version: string; factorySlug: string }> }>(path);
+    const body = await this.fetch<{ templates: TemplateRow[] }>(path);
     return body.templates;
   }
 
@@ -299,7 +554,7 @@ export class AgentComposeClient {
 
   /** 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> {
     return this.fetch<FactoryRow>("/api/v1/factories", { method: "POST", body: payload });
   }
 
@@ -309,7 +564,7 @@ export class AgentComposeClient {
   }
 
   /** Rename or describe a factory. */
-  updateFactory(slug: string, updates: { name?: string; description?: string }): Promise<FactoryRow> {
+  updateFactory(slug: string, updates: UpdateFactoryInput): Promise<FactoryRow> {
     return this.fetch<FactoryRow>(`/api/v1/factories/${encodeURIComponent(slug)}`, { method: "PATCH", body: updates });
   }
 
@@ -324,7 +579,7 @@ export class AgentComposeClient {
   // `factorySlug` defaults to `"default"`.
 
   /** 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> {
     const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
     return this.fetch(templatePath(factorySlug, workflowName, "secrets"), {
       method: "POST",
@@ -333,7 +588,7 @@ export class AgentComposeClient {
   }
 
   /** List secret keys registered for a workflow (metadata only — values are never returned). */
-  async listSecrets(workflowName: string, opts?: { factorySlug?: string }): Promise<Array<{ key: string; createdAt: string; updatedAt: string }>> {
+  async listSecrets(workflowName: string, opts?: SecretOptions): Promise<SecretListEntry[]> {
     const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
     const body = await this.fetch<{ secrets: Array<{ secretKey: string; createdAt: string; updatedAt: string }> }>(
       templatePath(factorySlug, workflowName, "secrets"),
@@ -342,7 +597,7 @@ export class AgentComposeClient {
   }
 
   /** Delete a workflow secret. */
-  deleteSecret(workflowName: string, key: string, opts?: { factorySlug?: string }): Promise<void> {
+  deleteSecret(workflowName: string, key: string, opts?: SecretOptions): Promise<void> {
     const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
     return this.fetch(templatePath(factorySlug, workflowName, "secrets", key), { method: "DELETE" });
   }
@@ -355,12 +610,7 @@ export class AgentComposeClient {
    *
    *  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> {
     return this.fetch<ApiKeyCreated>("/api-keys", { method: "POST", body: input });
   }
 
@@ -398,7 +648,7 @@ export 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
@@ -406,7 +656,7 @@ export class AgentComposeClient {
    *  non-2xx responses throw the same `AgentComposeError`. */
   async *streamRunLogs(
     runId: string,
-    opts?: { lastEventId?: number; signal?: AbortSignal },
+    opts?: StreamRunLogsOptions,
   ): AsyncGenerator<RunEvent> {
     const headers: Record<string, string> = { Authorization: `Bearer ${this.apiKey}` };
     if (opts?.lastEventId && opts.lastEventId > 0) {