@agent-compose/sdk 0.1.0 → 0.2.1

package/dist/runtimes/openai-desktop.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,16 +443,21 @@ 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 } : {},
-        ...parentRunId ? { parentRunId } : {}
+        ...opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {},
+        ...parentRunId ? { parentRunId } : {},
+        ...opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {},
+        ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {}
       }
     });
   }
@@ -405,7 +466,11 @@ 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 } : {},
+      ...opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {},
+      ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {}
     });
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
@@ -432,19 +497,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;
   }
-  async listSecrets(workflowName) {
-    const body = await this.fetch(`/api/v1/templates/${workflowName}/secrets`);
+  createFactory(payload) {
+    return this.fetch("/api/v1/factories", { method: "POST", body: payload });
+  }
+  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 +623,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

package/dist/sse.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Generic Server-Sent Events (SSE) parser.
+ *
+ * Consumes a `ReadableStream<Uint8Array>` and yields parsed events one at a
+ * time. Each event carries:
+ *   - `id`:    numeric (from `id:` line; `0` if absent)
+ *   - `event`: event name (from `event:` line; `""` if absent)
+ *   - `data`:  parsed JSON payload (the SDK's stream events are always JSON)
+ *
+ * Malformed payloads are silently skipped — same behaviour as the previous
+ * CLI-side parser. Caller drives the loop via `for await (...)` and is
+ * responsible for breaking on terminal events.
+ *
+ * Output type stays loose (`Record<string, unknown>`) on purpose: typed
+ * unions like `RunEvent` aren't structurally narrowable from
+ * `Record<string, unknown>`, so callers that want a discriminated union
+ * cast at the consumption site (see `streamRunLogs`). Keeping the parser
+ * payload-agnostic also means it's reusable for future SSE endpoints with
+ * different shapes.
+ */
+export declare function parseSseStream(body: ReadableStream<Uint8Array>): AsyncGenerator<{
+    id: number;
+    event: string;
+    data: Record<string, unknown>;
+}>;

package/dist/types/events.d.ts

@@ -70,6 +70,11 @@ export type RunEvent = {
     at: number;
     seq?: number;
     reason: string;
+} | {
+    event: "run_canceled";
+    runId: string;
+    at: number;
+    seq?: number;
 } | {
     event: "workflow_log";
     runId: string;

package/dist/types/sandbox-environment.d.ts

@@ -1,15 +1,16 @@
 /**
  * A sandbox environment is a workflow whose job is to leave its VM in a
  * configured state, then snapshot it so other workflows can boot from that
- * state. Snapshots are **opt-in**: the wrapper below sets `snapshot: true`
- * by default (opt out with `snapshot: false` if you only want side effects).
+ * state. Capture is **opt-in**: the wrapper below sets `saveSnapshot: true`
+ * by default (opt out with `saveSnapshot: false` if you only want side
+ * effects).
  *
- * Once captured, reference the snapshot from another workflow's
- * `sandboxEnvironment` field by run UUID, workflow name, or `name@version`:
+ * Once captured, reference the snapshot from another workflow's `snapshot`
+ * field by run UUID, workflow name, or `name@version`:
  *
- *     sandboxEnvironment: "my-setup"          // most recent successful snapshot
- *     sandboxEnvironment: "my-setup@v1"       // version-scoped recency
- *     sandboxEnvironment: "<run-uuid>"        // pinned to an exact run
+ *     snapshot: "my-setup"          // most recent successful snapshot
+ *     snapshot: "my-setup@v1"       // version-scoped recency
+ *     snapshot: "<run-uuid>"        // pinned to an exact run
  *
  * `defineSandboxEnvironment` is sugar over `defineWorkflow` — it makes the
  * setup recipe read like an imperative script by supplying the local
@@ -19,7 +20,7 @@
  *   1. Author a setup file with `defineSandboxEnvironment`.
  *   2. `agentc register setup.ts --build` — registers and invokes once to
  *      capture the snapshot.
- *   3. Other workflows declare `sandboxEnvironment: "name"` and boot from it.
+ *   3. Other workflows declare `snapshot: "name"` and boot from it.
  *   4. `agentc snapshot list` / `delete` to manage the Vercel storage bill.
  *
  * @example
@@ -40,9 +41,9 @@ export interface SandboxEnvironmentDefinition {
     name: string;
     description?: string;
     setup: (sb: SandboxProvider) => Promise<void>;
-    /** Override the sugar's `snapshot: true` default. Set `false` to opt out
-     *  of snapshot capture (rarely useful — an env with no snapshot can't be
-     *  referenced as `sandboxEnvironment`). */
-    snapshot?: boolean;
+    /** Override the sugar's `saveSnapshot: true` default. Set `false` to opt
+     *  out of snapshot capture (rarely useful — an env with no snapshot can't
+     *  be referenced as the `snapshot` field on another workflow). */
+    saveSnapshot?: boolean;
 }
 export declare function defineSandboxEnvironment(env: SandboxEnvironmentDefinition): WorkflowFn<void>;

package/dist/types/workflow.d.ts

@@ -52,19 +52,21 @@ export type WorkflowFn<T = unknown> = (ctx: WorkflowCtx, sandbox: SandboxProvide
 export interface WorkflowDefinition<T = unknown> {
     run: WorkflowFn<T>;
     /**
-     * Name (or `name@version`) of another workflow whose built snapshot this
-     * workflow's runner boots into. Any workflow registered with `--build`
-     * can be used as a sandbox environment.
+     * Reference to a snapshot the runner should boot from at run start.
+     * Accepts a run UUID, a workflow name, or `name@version` — any workflow
+     * registered with `--build` produces a snapshot you can name here. The
+     * runner VM starts in that pre-configured state. Per-invocation
+     * `invoke({ snapshot })` overrides this default.
      */
-    sandboxEnvironment?: string;
+    snapshot?: string;
     /**
-     * Capture a snapshot of the sandbox on successful /complete. Snapshots are
-     * long-lived (never auto-expire) — customers list + delete them explicitly
-     * via `agentc snapshot list/delete`. Per-invocation `invoke({ snapshot })`
-     * overrides this default. `defineSandboxEnvironment` sugar sets this to
-     * true by default.
+     * Capture a snapshot of the sandbox on successful /complete. Snapshots
+     * are long-lived (never auto-expire) — customers list + delete them
+     * explicitly via `agentc snapshot list/delete`. Per-invocation
+     * `invoke({ saveSnapshot })` overrides this default.
+     * `defineSandboxEnvironment` sugar sets this to true by default.
      */
-    snapshot?: boolean;
+    saveSnapshot?: boolean;
     /**
      * Outbound network policy for the runner sandbox.
      * Use "*": [] to allow all traffic while still injecting headers for specific domains.
@@ -100,7 +102,7 @@ export interface WorkflowDefinition<T = unknown> {
  * The returned function is a valid WorkflowFn with metadata fields attached
  * for the bundler / registration layer to read.
  */
-export declare function defineWorkflow<T = unknown>(def: WorkflowDefinition<T>): WorkflowFn<T> & Pick<WorkflowDefinition, "networkPolicy" | "placeholders" | "sandboxEnvironment" | "snapshot">;
+export declare function defineWorkflow<T = unknown>(def: WorkflowDefinition<T>): WorkflowFn<T> & Pick<WorkflowDefinition, "networkPolicy" | "placeholders" | "snapshot" | "saveSnapshot">;
 /** Observability-only lifecycle hooks — passed to the workflow engine, not workflow authors. */
 export interface WorkflowHooks {
     onStepStart?: (step: string) => void;

package/dist/utils/bundler.d.ts

@@ -13,11 +13,12 @@ export interface BundledWorkflow {
     source: string;
     networkPolicy?: SandboxNetworkPolicy;
     placeholders?: Record<string, string>;
-    /** Name (or `name@version`) of another workflow whose built snapshot this
-     *  workflow boots from, if declared via `sandboxEnvironment`. */
-    sandboxEnvironment?: string;
-    /** Default snapshot-on-success flag from the workflow definition, if any. */
-    snapshot?: boolean;
+    /** Run UUID, workflow name, or `name@version` referencing the snapshot
+     *  this workflow's runner boots from, if declared via the `snapshot`
+     *  field on `defineWorkflow`. */
+    snapshot?: string;
+    /** Default capture-on-success flag from the workflow definition. */
+    saveSnapshot?: boolean;
 }
 /** Bundle a workflow from source. */
 export declare function bundleWorkflow(workflowPath: string, overrides?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {