@agent-compose/sdk 0.1.0 → 0.2.0

package/dist/client.d.ts

@@ -1,9 +1,16 @@
 /**
  * AgentComposeClient — HTTP client for the agent-compose server API.
  *
- * register() accepts pre-built sources — use the CLI (agent-compose register)
- * or build sources yourself and pass them directly.
+ * Templates always live inside a factory (project). Methods that touch a
+ * specific template (`register`, `invoke`, `setSecret`, `listSecrets`,
+ * `deleteSecret`) take an optional `factorySlug`; when omitted, they target
+ * the team's auto-created `default` factory. There is no second URL space
+ * for "templates without a factory" — every workflow belongs to exactly one.
+ *
+ * `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";
 export interface RegisterResult {
     id: string;
     name: string;
@@ -16,9 +23,54 @@ export interface RegisterResult {
 }
 export interface RunStatus {
     id: string;
-    status: "running" | "success" | "failed" | "abandoned";
+    status: "running" | "success" | "failed" | "abandoned" | "canceled";
     output?: Record<string, unknown>;
 }
+/** Row shape returned by `GET /api-keys`. */
+export interface ApiKey {
+    object: "api_key";
+    id: string;
+    name: string | null;
+    last4: string | null;
+    scopes: string[];
+    teamId: string;
+    createdByUserId: string | null;
+    /** Non-null when the key is restricted to a single factory. */
+    factoryId: string | null;
+    createdAt: string;
+    expiresAt: string | null;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+}
+/** Response from `POST /api-keys`. The `key` field is the plaintext token —
+ *  shown once at creation, never retrievable again. */
+export interface ApiKeyCreated extends ApiKey {
+    key: string;
+}
+/** Single rollup row from `GET /api/v1/usage`. */
+export interface UsageRollupRow {
+    eventType: string;
+    unit: string;
+    total: number;
+    tags: Record<string, unknown>;
+}
+/** Response from `GET /api/v1/usage`. */
+export interface UsageResponse {
+    object: "list";
+    data: UsageRollupRow[];
+    has_more: boolean;
+    from: string | null;
+    to: string | null;
+}
+/** Response from `POST /api/v1/workflows/:id/cancel`. The endpoint is
+ *  idempotent: cancelling a run that's already terminal returns its current
+ *  outcome verbatim (rather than throwing or pretending it just canceled),
+ *  so `status` widens to every terminal value the server might surface. */
+export interface CancelRunResponse {
+    runId: string;
+    status: "canceled" | "success" | "failed" | "abandoned";
+    canceledAt: string;
+}
 export interface SnapshotListEntry {
     runId: string;
     workflow: string | null;
@@ -28,8 +80,11 @@ export interface SnapshotListEntry {
 }
 export declare class AgentComposeClient {
     private readonly fetch;
+    private readonly baseUrl;
+    private readonly apiKey;
     constructor(baseUrl: string, apiKey: string);
-    /** Register a workflow with pre-built sources. */
+    /** 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;
@@ -41,19 +96,31 @@ export declare class AgentComposeClient {
         }>;
         networkPolicy?: unknown;
         placeholders?: Record<string, string>;
-        /** Name (or `name@version`) of another workflow whose snapshot this
-         *  workflow's runner boots from. Must reference a workflow previously
-         *  registered with `--build`. */
-        sandboxEnvironment?: 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(..., { snapshot })`. */
-        snapshot?: boolean;
+         *  success. Individual invocations can override via
+         *  `invoke(..., { saveSnapshot })`. */
+        saveSnapshot?: boolean;
+        /** Factory slug. Defaults to `"default"`. */
+        factorySlug?: string;
     }): Promise<RegisterResult>;
     /** Invoke a workflow. Returns run ID immediately — workflow runs asynchronously.
      *
-     *  `snapshot`: `true` overrides the workflow default; `false` opts out. When
-     *  the run captures a snapshot, its id is stamped on the row and can be
-     *  referenced as `sandboxEnvironment` by other workflows.
+     *  `snapshot`: per-invocation override of the template-level `snapshot`
+     *  field. Same forms — a run UUID, a workflow name, or `name@version`.
+     *  Use this when one template needs to boot from many different
+     *  snapshots (e.g. a benchmark workflow running against a different
+     *  starting state per invocation). Does not change the template's
+     *  registered default; only affects this run.
+     *
+     *  `saveSnapshot`: `true` overrides the workflow default; `false` opts
+     *  out. When the run captures a snapshot, its id is stamped on the row
+     *  and can be referenced as the `snapshot` field on other workflows.
      *
      *  `parentRunId`: links the new run to another of the same account's
      *  currently-running runs. When omitted, the client auto-detects from
@@ -61,10 +128,14 @@ export declare class AgentComposeClient {
      *  so workflows invoking other workflows get the parent/child tree for
      *  free. Pass `null` to suppress auto-detection (e.g. invoking a top-level
      *  sibling workflow from inside a runner for a reason unrelated to the
-     *  current run). Explicit non-null wins over auto-detection. */
+     *  current run). Explicit non-null wins over auto-detection.
+     *
+     *  `factorySlug`: defaults to `"default"`. */
     invoke(name: string, input?: Record<string, unknown>, opts?: {
-        snapshot?: boolean;
+        snapshot?: string;
+        saveSnapshot?: boolean;
         parentRunId?: string | null;
+        factorySlug?: string;
     }): Promise<{
         id: string;
     }>;
@@ -76,8 +147,10 @@ export declare class AgentComposeClient {
      *  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?: boolean;
+        snapshot?: string;
+        saveSnapshot?: boolean;
         parentRunId?: string | null;
+        factorySlug?: string;
         timeoutMs?: number;
         pollIntervalMs?: number;
     }): Promise<RunStatus>;
@@ -90,21 +163,100 @@ export declare class AgentComposeClient {
     deleteSnapshot(runId: string): Promise<void>;
     /** Poll run status. */
     getStatus(runId: string): Promise<RunStatus>;
-    /** List registered workflow templates. */
-    listTemplates(): Promise<Array<{
+    /** 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;
     }>>;
+    /** 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>;
+    /** 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>;
+    /** 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): Promise<{
+    setSecret(workflowName: string, key: string, value: string, opts?: {
+        factorySlug?: string;
+    }): Promise<{
         key: string;
     }>;
     /** List secret keys registered for a workflow (metadata only — values are never returned). */
-    listSecrets(workflowName: string): Promise<Array<{
+    listSecrets(workflowName: string, opts?: {
+        factorySlug?: string;
+    }): Promise<Array<{
         key: string;
         createdAt: string;
         updatedAt: string;
     }>>;
     /** Delete a workflow secret. */
-    deleteSecret(workflowName: string, key: string): Promise<void>;
+    deleteSecret(workflowName: string, key: string, opts?: {
+        factorySlug?: string;
+    }): 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>;
+    /** List API keys on the caller's team (metadata only — plaintext keys are
+     *  never returned). */
+    listApiKeys(): Promise<ApiKey[]>;
+    /** Billable usage rollup for the caller's team over the [from, to) window. */
+    getUsage(from: Date, to: Date): Promise<UsageResponse>;
+    /** Cancel an in-progress run. Idempotent: cancelling an already-terminal
+     *  run returns the current state without throwing. The server stamps the
+     *  run as `canceled` and kills any live sandboxes. */
+    cancelRun(runId: string): Promise<CancelRunResponse>;
+    /** Stream lifecycle events for a run as an async iterable. Yields parsed
+     *  `RunEvent` payloads in order; caller breaks on terminal events
+     *  (`run_complete`, `run_failed`, `run_canceled`).
+     *
+     *  `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.
+     *
+     *  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>;
+}
+/** A factory: a project-level grouping of workflows inside a team. */
+export interface FactoryRow {
+    id: string;
+    teamId: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    createdAt: string;
+    updatedAt: string;
 }

package/dist/index.d.ts

@@ -20,7 +20,8 @@ export type { WorkflowFn, WorkflowCtx, WorkflowRun, AgentBudget, WorkflowHooks,
 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 } from "./client.js";
+export type { RegisterResult, 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";

package/dist/index.js

@@ -28,8 +28,8 @@ function defineWorkflow(def) {
   return Object.assign(def.run, {
     networkPolicy: def.networkPolicy,
     placeholders: def.placeholders,
-    sandboxEnvironment: def.sandboxEnvironment,
-    snapshot: def.snapshot
+    snapshot: def.snapshot,
+    saveSnapshot: def.saveSnapshot
   });
 }
 // src/sandbox.ts
@@ -350,7 +350,7 @@ function defineSandboxEnvironment(env) {
     throw new Error(`defineSandboxEnvironment(${env.name}): 'setup' must be a function`);
   }
   return defineWorkflow({
-    snapshot: env.snapshot ?? true,
+    saveSnapshot: env.saveSnapshot ?? true,
     run: () => env.setup(makeLocalSandboxProvider())
   });
 }
@@ -367,18 +367,74 @@ class AgentComposeError extends Error {
   }
 }
 
+// src/sse.ts
+async function* parseSseStream(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder;
+  let buffer = "";
+  let event = "";
+  let seq = 0;
+  let dataLines = [];
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split(`
+`);
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line.startsWith("id:")) {
+          seq = Number(line.slice(3).trim());
+          continue;
+        }
+        if (line.startsWith("event:")) {
+          event = line.slice(6).trim();
+          continue;
+        }
+        if (line.startsWith("data:")) {
+          dataLines.push(line.slice(5).trim());
+          continue;
+        }
+        if (line === "" && dataLines.length > 0) {
+          try {
+            const data = JSON.parse(dataLines.join(`
+`));
+            yield { id: seq, event, data };
+          } catch {}
+          event = "";
+          seq = 0;
+          dataLines = [];
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
 // src/client.ts
 var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var DEFAULT_FACTORY = "default";
 function detectAmbientParentRunId() {
   const envRunId = typeof process !== "undefined" ? process.env?.RUN_ID : undefined;
   return envRunId && UUID_REGEX.test(envRunId) ? envRunId : null;
 }
+function templatePath(factorySlug, ...rest) {
+  const tail = rest.length > 0 ? "/" + rest.map(encodeURIComponent).join("/") : "";
+  return `/api/v1/factories/${encodeURIComponent(factorySlug)}/templates${tail}`;
+}
 
 class AgentComposeClient {
   fetch;
+  baseUrl;
+  apiKey;
   constructor(baseUrl, apiKey) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.apiKey = apiKey;
     this.fetch = ofetch.create({
-      baseURL: baseUrl.replace(/\/$/, ""),
+      baseURL: this.baseUrl,
       headers: { Authorization: `Bearer ${apiKey}` },
       async onResponseError({ response }) {
         const body = response._data;
@@ -387,15 +443,18 @@ class AgentComposeClient {
     });
   }
   register(payload) {
-    return this.fetch("/api/v1/templates", { method: "POST", body: payload });
+    const { factorySlug = DEFAULT_FACTORY, ...body } = payload;
+    return this.fetch(templatePath(factorySlug), { method: "POST", body });
   }
   invoke(name, input, opts) {
     const parentRunId = opts?.parentRunId === undefined ? detectAmbientParentRunId() : opts.parentRunId;
-    return this.fetch(`/api/v1/templates/${name}/invoke`, {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(templatePath(factorySlug, name, "invoke"), {
       method: "POST",
       body: {
         input,
         ...opts?.snapshot !== undefined ? { snapshot: opts.snapshot } : {},
+        ...opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {},
         ...parentRunId ? { parentRunId } : {}
       }
     });
@@ -405,7 +464,9 @@ class AgentComposeClient {
     const pollMs = opts?.pollIntervalMs ?? 1000;
     const { id: runId } = await this.invoke(name, input, {
       ...opts?.snapshot !== undefined ? { snapshot: opts.snapshot } : {},
-      ...opts?.parentRunId !== undefined ? { parentRunId: opts.parentRunId } : {}
+      ...opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {},
+      ...opts?.parentRunId !== undefined ? { parentRunId: opts.parentRunId } : {},
+      ...opts?.factorySlug !== undefined ? { factorySlug: opts.factorySlug } : {}
     });
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
@@ -432,19 +493,78 @@ class AgentComposeClient {
   getStatus(runId) {
     return this.fetch(`/api/v1/workflows/${runId}/status`);
   }
-  async listTemplates() {
-    const body = await this.fetch("/api/v1/templates");
+  async listTemplates(opts) {
+    const path = opts?.factorySlug ? templatePath(opts.factorySlug) : "/api/v1/templates";
+    const body = await this.fetch(path);
     return body.templates;
   }
-  setSecret(workflowName, key, value) {
-    return this.fetch(`/api/v1/templates/${workflowName}/secrets`, { method: "POST", body: { key, value } });
+  async listFactories() {
+    const body = await this.fetch("/api/v1/factories");
+    return body.factories;
+  }
+  createFactory(payload) {
+    return this.fetch("/api/v1/factories", { method: "POST", body: payload });
   }
-  async listSecrets(workflowName) {
-    const body = await this.fetch(`/api/v1/templates/${workflowName}/secrets`);
+  getFactory(slug) {
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(slug)}`);
+  }
+  updateFactory(slug, updates) {
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(slug)}`, { method: "PATCH", body: updates });
+  }
+  deleteFactory(slug) {
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(slug)}`, { method: "DELETE" });
+  }
+  setSecret(workflowName, key, value, opts) {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(templatePath(factorySlug, workflowName, "secrets"), {
+      method: "POST",
+      body: { key, value }
+    });
+  }
+  async listSecrets(workflowName, opts) {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const body = await this.fetch(templatePath(factorySlug, workflowName, "secrets"));
     return body.secrets.map((s) => ({ key: s.secretKey, createdAt: s.createdAt, updatedAt: s.updatedAt }));
   }
-  deleteSecret(workflowName, key) {
-    return this.fetch(`/api/v1/templates/${workflowName}/secrets/${key}`, { method: "DELETE" });
+  deleteSecret(workflowName, key, opts) {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(templatePath(factorySlug, workflowName, "secrets", key), { method: "DELETE" });
+  }
+  createApiKey(input) {
+    return this.fetch("/api-keys", { method: "POST", body: input });
+  }
+  async listApiKeys() {
+    const body = await this.fetch("/api-keys");
+    return body.data;
+  }
+  getUsage(from, to) {
+    const qs = `?from=${encodeURIComponent(from.toISOString())}&to=${encodeURIComponent(to.toISOString())}`;
+    return this.fetch(`/api/v1/usage${qs}`);
+  }
+  cancelRun(runId) {
+    return this.fetch(`/api/v1/workflows/${encodeURIComponent(runId)}/cancel`, { method: "POST" });
+  }
+  async* streamRunLogs(runId, opts) {
+    const headers = { Authorization: `Bearer ${this.apiKey}` };
+    if (opts?.lastEventId && opts.lastEventId > 0) {
+      headers["Last-Event-ID"] = String(opts.lastEventId);
+    }
+    const res = await fetch(`${this.baseUrl}/api/v1/workflows/${encodeURIComponent(runId)}/stream`, {
+      headers,
+      ...opts?.signal ? { signal: opts.signal } : {}
+    });
+    if (!res.ok || !res.body) {
+      let message = res.statusText;
+      try {
+        const body = await res.json();
+        if (body.error)
+          message = body.error;
+      } catch {}
+      throw new AgentComposeError(res.status, message);
+    }
+    for await (const ev of parseSseStream(res.body)) {
+      yield ev.data;
+    }
   }
 }
 // src/utils/errors.ts
@@ -499,16 +619,16 @@ async function bundleWorkflow(workflowPath, overrides) {
   const wfBits = await extractFromBundle(source, "workflow", (wf) => wf ? {
     networkPolicy: wf.networkPolicy,
     placeholders: wf.placeholders,
-    sandboxEnvironment: wf.sandboxEnvironment,
-    snapshot: wf.snapshot
+    snapshot: wf.snapshot,
+    saveSnapshot: wf.saveSnapshot
   } : undefined);
-  const { networkPolicy, placeholders, sandboxEnvironment, snapshot } = wfBits ?? {};
+  const { networkPolicy, placeholders, snapshot, saveSnapshot } = wfBits ?? {};
   return {
     source,
     networkPolicy: overrides?.networkPolicy ?? networkPolicy,
     placeholders: overrides?.placeholders ?? placeholders,
-    ...sandboxEnvironment ? { sandboxEnvironment } : {},
-    ...snapshot !== undefined ? { snapshot } : {}
+    ...snapshot !== undefined ? { snapshot } : {},
+    ...saveSnapshot !== undefined ? { saveSnapshot } : {}
   };
 }
 // src/utils/schemas.ts
@@ -1077,6 +1197,7 @@ export {
   runWorkflow,
   runAgent,
   reconnectSandbox,
+  parseSseStream,
   parseSseExecStream,
   parseNameVersion,
   parseAgentStatus,