@agent-compose/sdk 0.2.0 → 0.2.2

package/README.md

@@ -1,13 +1,10 @@
 # @agent-compose/sdk
 
-TypeScript SDK for [agent-compose](https://github.com/Layr-Labs/agent-compose). Use it to:
+TypeScript SDK for agent-compose. Use it to:
 
 - **Author workflows** that run agentic LLM loops inside isolated sandboxes
 - **Define runtimes** that wrap a coding-CLI tool (Claude Code, OpenAI Desktop, …) into a sandbox-portable agent loop
-- **Register, invoke, observe, and cancel** workflows via the HTTP API (`AgentComposeClient`)
-- **Manage factories, secrets, API keys, and snapshots** programmatically
-
-The hierarchy: a **team** owns one or more **factories** (project containers); each factory owns workflow templates, secrets, and runs. Workflows are versioned per `(factory, name, version)`. New code that doesn't care about factories transparently lands in `default` — every team has one.
+- **Register, invoke, and observe** workflows via the HTTP API (`AgentComposeClient`)
 
 ---
 
@@ -165,10 +162,9 @@ agentc register my-workflow.ts -n my-workflow
 ```
 
 Under the hood that calls `bundleWorkflow(workflowPath)` (resolves imports,
-inlines runtime sources via dynamic-require traversal) and `POST
-/api/v1/factories/<slug>/templates` with the bundled source. If you need
-to drive registration from your own build pipeline, you can do the same
-thing via the SDK directly:
+inlines runtime sources via dynamic-require traversal) and `POST /api/v1/templates`
+with the bundled source. If you need to drive registration from your own
+build pipeline, you can do the same thing via the SDK directly:
 
 ```ts
 import { AgentComposeClient, bundleWorkflow } from "@agent-compose/sdk";
@@ -180,11 +176,10 @@ const client = new AgentComposeClient(
 
 const bundled = await bundleWorkflow("./my-workflow.ts");
 await client.register({
-  name:        "my-workflow",
-  source:      bundled.source,
-  runtimes:    bundled.runtimes,        // [{ name, source }] — embedded so the runner has them locally
-  schedule:    "*/30 * * * *",          // optional cron
-  factorySlug: "default",                // optional — defaults to "default"
+  name:    "my-workflow",
+  source:  bundled.source,
+  runtimes: bundled.runtimes,         // [{ name, source }] — embedded so the runner has them locally
+  schedule: "*/30 * * * *",            // optional cron
   // snapshot, saveSnapshot, networkPolicy, placeholders — all optional
 });
 ```
@@ -209,7 +204,7 @@ const status = await client.invokeAndWait("my-workflow", { repo: "owner/repo" },
   timeoutMs:      5 * 60_000,
   pollIntervalMs: 2000,
 });
-console.log(status.status);   // "success" | "failed" | "abandoned" | "canceled"
+console.log(status.status);   // "success" | "failed" | "abandoned"
 console.log(status.output);   // workflow's return value
 ```
 
@@ -218,10 +213,6 @@ async run() { return … } })` resolves to). `setMetadata()` writes to a
 separate `metadata` field — useful for "side-channel" facts (PR url, plan
 url) without polluting the structured return.
 
-`invoke` and `invokeAndWait` both accept `{ factorySlug, snapshot,
-saveSnapshot, parentRunId }` as the third argument. `factorySlug` defaults
-to `"default"`.
-
 ### Auto parent/child tracing
 
 The SDK detects `process.env.RUN_ID` (set by the runner sandbox on every
@@ -230,123 +221,25 @@ dispatch) and automatically threads it as `parentRunId` on subsequent
 parent/child tree in the dashboard for free. Pass `parentRunId: null`
 to opt out.
 
-### Cancelling a run
-
-```ts
-await client.cancelRun(runId);
-```
-
-Idempotent — cancelling an already-terminal run returns the current state
-without throwing. The server stamps the run as `canceled`, kills any live
-sandboxes, and emits a `run_canceled` event on the stream.
-
-### Streaming live logs
-
-`streamRunLogs` returns an async generator of `RunEvent`s in real time,
-re-attaching via SSE under the hood. Pass `lastEventId` (the highest
-`seq` you've already processed) to resume after a reconnect.
-
-```ts
-for await (const ev of client.streamRunLogs(runId, { lastEventId: 0 })) {
-  console.log(ev.event, ev.seq, ev.data);
-  if (ev.event === "run_complete" || ev.event === "run_failed" || ev.event === "run_canceled") {
-    break;
-  }
-}
-```
-
-`AbortSignal` works too — pass `{ signal }` and call `controller.abort()`
-to tear the stream down from the caller side.
-
----
-
-## Factories
-
-Factories are project containers within a team. Each factory has its own
-workflow templates, secrets, runs, and (optionally) scoped API keys. New
-projects don't need to think about them — `default` is auto-created per
-team and is what the SDK falls back to when `factorySlug` is omitted.
-
-```ts
-// CRUD on factories
-await client.createFactory({ slug: "ci-bots", name: "CI Bots", description: "…" });
-const factories = await client.listFactories();
-const f         = await client.getFactory("ci-bots");
-await client.updateFactory("ci-bots", { name: "Continuous-Integration Bots" });
-await client.deleteFactory("ci-bots");
-
-// Templates list — flat across factories, or scoped to one
-const all   = await client.listTemplates();
-const scoped = await client.listTemplates({ factorySlug: "ci-bots" });
-
-// Register / invoke / secret operations all accept factorySlug
-await client.register({ name: "scrape", source, factorySlug: "ci-bots", … });
-await client.invoke("scrape", { url: "…" }, { factorySlug: "ci-bots" });
-await client.setSecret("scrape", "GH_TOKEN", "ghp_…", { factorySlug: "ci-bots" });
-```
-
-CLI equivalents: `agentc factory list | create | get | update | delete`,
-plus `--factory <slug>` on every other command.
-
 ---
 
 ## Per-workflow secrets
 
-Secrets live in GCP Secret Manager, one row per `(factory, workflow, key)`.
-They're injected as env vars into the runner sandbox at dispatch time,
-never persisted in the VM. Values are write-only — the API only returns
-metadata (key, timestamps).
+Secrets are stored in GCP Secret Manager, one row per `(team, workflow,
+key)`. They're injected as env vars into the runner sandbox at dispatch
+time, never persisted in the VM. Values are write-only — the API only
+returns metadata (key, timestamps).
 
 ```ts
 await client.setSecret("my-workflow", "ANTHROPIC_API_KEY", process.env.ANTHROPIC_API_KEY!);
 const list = await client.listSecrets("my-workflow"); // [{ key, createdAt, updatedAt }]
 await client.deleteSecret("my-workflow", "STALE_KEY");
-
-// Scope to a non-default factory:
-await client.setSecret("scrape", "GH_TOKEN", "ghp_…", { factorySlug: "ci-bots" });
 ```
 
 Mutations require `admin` scope.
 
 ---
 
-## API keys
-
-Mint and list scoped keys programmatically (requires an `admin`-scoped
-caller key). New keys are returned **once**, in the same response as the
-metadata — copy the `ac_…` value immediately.
-
-```ts
-const created = await client.createApiKey({
-  name:      "ci-dispatcher",
-  scopes:    ["read", "invoke"],
-  expiresAt: new Date(Date.now() + 30 * 86_400_000).toISOString(),  // 30 days
-  // factorySlug: "ci-bots"  // optional — scopes the key to a single factory
-});
-console.log(created.key);   // "ac_…" — the only time you'll see this
-
-const all = await client.listApiKeys();
-```
-
-CLI equivalent: `agentc keys create <name> --scopes read,invoke
---expires-in 30d`.
-
----
-
-## Usage
-
-```ts
-const usage = await client.getUsage(
-  new Date(Date.now() - 30 * 86_400_000),
-  new Date(),
-);
-// usage.rows: [{ day, runs, sandbox_seconds, … }]
-```
-
-CLI equivalent: `agentc usage`.
-
----
-
 ## Snapshots (replay-friendly sandboxes)
 
 Long-running workflows can capture the runner sandbox as a Vercel snapshot
@@ -402,24 +295,17 @@ programmatic / server-to-server callers.
 | `defineRuntime` | Wrap an agent execution provider as an `AgentRuntime` |
 | `defineSandboxEnvironment` | Sugar for declaring a workflow whose primary purpose is to build a snapshot for others to boot from |
 | `runAgent` / `agentLoop` | Embed an LLM loop inside a workflow |
+| `claudeRuntime` / `createClaudeRuntime` / `ClaudeRunner` | Built-in Claude Code runtime + factory |
+| `AgentComposeClient` | HTTP client (register, invoke, status, snapshots, secrets) |
 | `runWorkflow` | Local engine for running a workflow in-process (test harness) |
 | `bundleWorkflow` | Resolve + inline a workflow's runtime sources for registration |
-| `claudeRuntime` / `createClaudeRuntime` / `ClaudeRunner` | Built-in Claude Code runtime + factory |
-| `AgentComposeClient` | HTTP client — register, invoke, cancel, stream logs, factories, snapshots, secrets, API keys, usage |
-| `AgentComposeError` | Thrown by every non-2xx HTTP response |
 | `parseAgentStatus` / `parseAgentResponse` / `AgentStatusSchema` / `AgentMessageSchema` | Protocol parsers |
-| `parseSseStream` | Generic SSE chunk decoder (used by `streamRunLogs`) |
-| `createSandbox` / `reconnectSandbox` / `killAllSandboxes` / `killSandboxById` / `getSandboxQuotas` / `listOwnedSandboxes` / `deleteSandboxSnapshot` | Sandbox-provider helpers (Vercel + E2B) |
-
-Type exports: `WorkflowFn`, `WorkflowCtx`, `WorkflowDefinition`,
-`WorkflowHooks`, `AgentBudget`, `AgentRuntime`, `RuntimeOptions`,
-`ModelExecutionContract`, `McpServerConfig`, `AgentMessage` (and its
-variants), `AgentStatus`, `RunStatus`, `RegisterResult`, `RunEvent`,
-`FactoryRow`, `SnapshotListEntry`, `ApiKey`, `ApiKeyCreated`,
-`UsageRollupRow`, `UsageResponse`, `CancelRunResponse`, `AgentLoopResult`,
-`RunAgentOpts`, `SandboxProvider`, `DesktopSandboxProvider`,
-`SandboxNetworkPolicy`, `SandboxCreateOpts`, `OwnedSandbox`,
-`BundledWorkflow`.
+
+Type exports: `WorkflowFn`, `WorkflowCtx`, `WorkflowDefinition`, `AgentBudget`,
+`AgentRuntime`, `RuntimeOptions`, `ModelExecutionContract`,
+`AgentMessage` (and its variants), `AgentStatus`, `RunStatus`,
+`RegisterResult`, `RunEvent`, `AgentLoopResult`, `RunAgentOpts`,
+`SandboxProvider`, `SandboxNetworkPolicy`, `BundledWorkflow`.
 
 For the canonical signatures, follow your IDE's go-to-definition into
 `@agent-compose/sdk` — `sdk/src/index.ts` is the public surface and the

package/dist/client.d.ts

@@ -11,6 +11,7 @@
  * register`) or build sources yourself and pass them directly.
  */
 import type { RunEvent } from "./types/events.js";
+import type { SandboxNetworkPolicy } from "./sandbox.js";
 export interface RegisterResult {
     id: string;
     name: string;
@@ -136,6 +137,8 @@ export declare class AgentComposeClient {
         saveSnapshot?: boolean;
         parentRunId?: string | null;
         factorySlug?: string;
+        networkPolicy?: SandboxNetworkPolicy;
+        placeholders?: Record<string, string>;
     }): Promise<{
         id: string;
     }>;
@@ -151,6 +154,8 @@ export declare class AgentComposeClient {
         saveSnapshot?: boolean;
         parentRunId?: string | null;
         factorySlug?: string;
+        networkPolicy?: SandboxNetworkPolicy;
+        placeholders?: Record<string, string>;
         timeoutMs?: number;
         pollIntervalMs?: number;
     }): Promise<RunStatus>;

package/dist/index.js

@@ -455,7 +455,9 @@ class AgentComposeClient {
         input,
         ...opts?.snapshot !== undefined ? { snapshot: opts.snapshot } : {},
         ...opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {},
-        ...parentRunId ? { parentRunId } : {}
+        ...parentRunId ? { parentRunId } : {},
+        ...opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {},
+        ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {}
       }
     });
   }
@@ -466,7 +468,9 @@ class AgentComposeClient {
       ...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?.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) {

package/dist/runtimes/openai-desktop.js

@@ -455,7 +455,9 @@ class AgentComposeClient {
         input,
         ...opts?.snapshot !== undefined ? { snapshot: opts.snapshot } : {},
         ...opts?.saveSnapshot !== undefined ? { saveSnapshot: opts.saveSnapshot } : {},
-        ...parentRunId ? { parentRunId } : {}
+        ...parentRunId ? { parentRunId } : {},
+        ...opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {},
+        ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {}
       }
     });
   }
@@ -466,7 +468,9 @@ class AgentComposeClient {
       ...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?.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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {
@@ -24,7 +24,15 @@
       "default": "./dist/runtimes/openai-desktop.js"
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "src/**/*.md",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
   "engines": {
     "node": ">=20"
   },

package/src/agent/agent-loop.ts

@@ -0,0 +1,131 @@
+/**
+ * Agent loop — runner-agnostic iteration driver operating through ModelExecutionContract.
+ * Each iteration: build prompt → sendMessage() → parse <status> → done / continue / circuit-break.
+ */
+
+import type { RuntimeOptions, ModelExecutionContract } from "../index.js";
+import { z } from "zod";
+import { AgentStatusSchema, parseAgentResponse } from "./protocol.js";
+import type { AgentStatus, AgentMessage } from "./protocol.js";
+
+export const DEFAULT_CLAUDE_MODEL = "claude-opus-4-7";
+
+const SAME_BLOCKER_ITERATIONS = 3;
+const STALL_ITERATIONS        = 3;
+
+export function parseAgentStatus(text: string): AgentStatus | null {
+  const match = text.match(/<status>([\s\S]*?)<\/status>/);
+  if (!match) return null;
+  try {
+    const result = AgentStatusSchema.safeParse(JSON.parse(match[1].trim()));
+    return result.success ? result.data : null;
+  } catch { return null; }
+}
+
+const DEFAULT_ALLOWED_TOOLS = ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "WebFetch"];
+
+export interface AgentLoopResult {
+  sessionId:   string;
+  lastStatus:  AgentStatus | null;
+  iterations:  number;
+  response?:   unknown;
+}
+
+export async function agentLoop(opts: {
+  label?: string;
+  onIteration?: (iteration: number, status: AgentStatus | null) => void;
+  turnsPerIteration?: number;
+  maxIterations?: number;
+  buildPrompt: (lastStatus: AgentStatus | null, iteration: number) => string;
+  onAgentEvent?: (iteration: number, msg: AgentMessage) => void;
+  allowedTools?: string[];
+  responseSchema?: z.ZodType<unknown>;
+  runtime?: (opts: RuntimeOptions) => ModelExecutionContract;
+  cwd?: string;
+}): Promise<AgentLoopResult> {
+  const label              = opts.label ?? "[Agent Loop]";
+  const turnsPerIteration  = opts.turnsPerIteration ?? 40;
+  const maxIterations      = opts.maxIterations ?? 8;
+
+  if (!opts.runtime) throw new Error("agentLoop: opts.runtime is required");
+  const client = opts.runtime({
+    maxTurns:     turnsPerIteration,
+    allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
+    label,
+    cwd:          opts.cwd,
+  });
+
+  let lastSessionId          = "";
+  let lastStatus: AgentStatus | null = null;
+  let iterationsWithoutStatus = 0;
+  let blockerStreak: { key: string; count: number } | null = null;
+
+  for (let iteration = 0; iteration < maxIterations; iteration++) {
+    const prompt = opts.buildPrompt(lastStatus, iteration);
+    process.stderr.write(`${label} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration} turns\n`);
+
+    let responseText = "";
+    for await (const msg of client.sendMessage({ prompt, sessionId: iteration > 0 ? lastSessionId : undefined })) {
+      opts.onAgentEvent?.(iteration, msg);
+      if (msg.type === "init")  lastSessionId = msg.sessionId;
+      if (msg.type === "text")  responseText += msg.text;
+      if (msg.type === "error") throw new Error(`Agent error: ${msg.text}`);
+    }
+    process.stdout.write("\n");
+
+    let status = parseAgentStatus(responseText);
+    process.stderr.write(`\n${label} iteration ${iteration + 1} status: exit_signal=${status?.exit_signal ?? "(no status)"} blockers=${JSON.stringify(status?.blockers ?? [])}\n`);
+    lastStatus = status ?? lastStatus;
+    opts.onIteration?.(iteration + 1, status);
+
+    if (status?.exit_signal && (status.blockers?.length ?? 0) === 0) {
+      let response: unknown = status;
+      if (opts.responseSchema) {
+        const raw = parseAgentResponse(responseText);
+        if (raw === null) {
+          process.stderr.write(`\n${label} NO <response> BLOCK — response tail: ${responseText.slice(-400)}\n`);
+          status = { ...status!, exit_signal: false, blockers: ["No <response> block found — emit a <response> block with the required JSON fields before setting exit_signal: true"] };
+          opts.onIteration?.(iteration + 1, status);
+          continue;
+        }
+        const parsed = opts.responseSchema.safeParse({ ...status, ...(raw as object) });
+        if (!parsed.success) {
+          process.stderr.write(`\n${label} <response> SCHEMA FAILED: ${parsed.error.message}\nraw: ${JSON.stringify(raw).slice(0, 400)}\n`);
+          status = { ...status!, exit_signal: false, blockers: [`<response> schema validation failed: ${parsed.error.message}`] };
+          opts.onIteration?.(iteration + 1, status);
+          continue;
+        }
+        response = parsed.data;
+      }
+      process.stderr.write(`${label} done after ${iteration + 1}/${maxIterations} iterations\n`);
+      return { sessionId: lastSessionId, lastStatus: status, iterations: iteration + 1, response };
+    }
+
+    if (!status) {
+      if (++iterationsWithoutStatus >= STALL_ITERATIONS)
+        throw new Error(`${label} stalled: no <status> block after ${iterationsWithoutStatus} iterations`);
+    } else {
+      iterationsWithoutStatus = 0;
+    }
+
+    if (status?.blockers?.length) {
+      const key = status.blockers.join("|");
+      if (blockerStreak !== null && blockerStreak.key === key) {
+        if (++blockerStreak.count >= SAME_BLOCKER_ITERATIONS)
+          throw new Error(`${label} circuit break: same blocker repeated ${blockerStreak.count}x — "${status.blockers[0]}"`);
+      } else {
+        blockerStreak = { key, count: 1 };
+      }
+    } else {
+      blockerStreak = null;
+    }
+
+    if (iteration + 1 < maxIterations)
+      process.stderr.write(`${label} continuing to iteration ${iteration + 2}/${maxIterations}\n`);
+  }
+
+  if (opts.responseSchema)
+    throw new Error(`${label} did not produce a valid <response> after ${maxIterations} iterations`);
+  process.stderr.write(`${label} exhausted ${maxIterations} iterations, proceeding with available work\n`);
+  return { sessionId: lastSessionId, lastStatus, iterations: maxIterations };
+}

package/src/agent/protocol-suffix.md

@@ -0,0 +1,57 @@
+## Status Signal
+
+When you have finished your work or are blocked, emit a `<status>` block at the end of your response:
+
+```json
+<status>
+{
+  "summary": "one sentence describing what was done or what is blocking",
+  "completed": ["each acceptance criterion that is now fully met"],
+  "blockers": [],
+  "changed_files": ["relative/path/to/file"],
+  "tests_run": true,
+  "exit_signal": true
+}
+</status>
+```
+
+**Field semantics:**
+- `summary`: one sentence — what was accomplished or what is blocking
+- `completed`: acceptance criteria items that are fully done — be specific
+- `blockers`: non-empty when `exit_signal: false` — describe the exact obstacle
+- `changed_files`: relative paths of files you created or modified
+- `tests_run`: `true` if you ran any test suite (pass or fail); `false` if no tests exist or you skipped them
+- `exit_signal: true` — set when ALL acceptance criteria are met and no blockers remain
+- `exit_signal: false` — set when blocked or unfinished; `blockers` must be non-empty
+
+**If you are still actively working** and have not reached a natural stopping point, do NOT emit a `<status>` block — just keep working.
+
+**Example (done):**
+
+```json
+<status>
+{
+  "summary": "Added input validation middleware to /api/tasks with tests",
+  "completed": ["POST /api/tasks validates required fields", "Returns 400 with details on invalid input", "Unit tests passing"],
+  "blockers": [],
+  "changed_files": ["src/middleware/validate.ts", "src/routes/tasks.ts", "tests/validate.test.ts"],
+  "tests_run": true,
+  "exit_signal": true
+}
+</status>
+```
+
+**Example (blocked):**
+
+```json
+<status>
+{
+  "summary": "Implemented middleware but tests are failing due to module resolution",
+  "completed": ["Middleware created and wired into route"],
+  "blockers": ["Tests fail: cannot resolve import './validate' — module resolution config unclear"],
+  "changed_files": ["src/middleware/validate.ts"],
+  "tests_run": true,
+  "exit_signal": false
+}
+</status>
+```

package/src/agent/protocol.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { AgentStatusSchema } from "../utils/schemas.js";
+import type { AgentMessage } from "../types/protocol.js";
+
+export type {
+  AgentMessage, AgentMessageInit, AgentMessageText, AgentMessageThinking,
+  AgentMessageToolUse, AgentMessageToolResult, AgentMessageDone,
+  AgentMessageError, AgentMessageUsage, AgentStatus,
+} from "../types/protocol.js";
+
+export { AgentStatusSchema };
+
+export const AgentMessageSchema = z.object({
+  type: z.enum(["init", "text", "thinking", "tool_use", "tool_result", "done", "error", "usage"]),
+  timestamp: z.string(),
+}).passthrough() as unknown as z.ZodType<AgentMessage>;
+
+export function parseAgentResponse(text: string): unknown {
+  const match = text.match(/<response>([\s\S]*?)<\/response>/);
+  if (!match) return null;
+  try { return JSON.parse(match[1].trim()); } catch { return null; }
+}