@agent-compose/sdk 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.2.1",
+  "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; }
+}

package/src/agent/run-agent.ts

@@ -0,0 +1,141 @@
+/**
+ * runAgent — canonical entry point for embedding an LLM agent inside a
+ * workflow. The workflow's `run()` body calls it; the loop executes
+ * against the runner's own VM.
+ *
+ * Glue packaged so workflows don't duplicate it:
+ *   - Inject `{{VAR}}` placeholders into the prompt template.
+ *   - Strip the `--- frontmatter ---` header authors use for IDE hints.
+ *   - Append PROTOCOL_SUFFIX (status/response format instructions).
+ *   - Append a response-format appendix when `responseSchema` is set.
+ *   - Delegate to `agentLoop`.
+ */
+
+import { z } from "zod";
+import { agentLoop } from "./agent-loop.js";
+import type { AgentLoopResult } from "./agent-loop.js";
+import type { AgentMessage, AgentStatus } from "../types/protocol.js";
+import type { AgentRuntime, RuntimeOptions } from "../types/runtime.js";
+import type { SandboxProvider } from "../types/sandbox.js";
+import type { AgentBudget } from "../types/workflow.js";
+import PROTOCOL_SUFFIX_RAW from "./protocol-suffix.md" with { type: "text" };
+
+const PROTOCOL_SUFFIX = stripFrontmatter(PROTOCOL_SUFFIX_RAW);
+
+function stripFrontmatter(content: string): string {
+  if (!content.startsWith("---")) return content;
+  const end = content.indexOf("\n---", 3);
+  return end === -1 ? content : content.slice(end + 4).trimStart();
+}
+
+function inject(template: string, vars: Record<string, string>): string {
+  return Object.entries(vars).reduce((t, [k, v]) => t.replaceAll(`{{${k}}}`, v), template);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function zodTypeName(schema: any): string {
+  if (schema instanceof z.ZodString)   return "string";
+  if (schema instanceof z.ZodNumber)   return "number";
+  if (schema instanceof z.ZodBoolean)  return "boolean";
+  if (schema instanceof z.ZodArray)    return `${zodTypeName(schema.element)}[]`;
+  if (schema instanceof z.ZodEnum)     return (schema.options as string[]).map((o: string) => `"${o}"`).join(" | ");
+  if (schema instanceof z.ZodOptional) return `${zodTypeName(schema.unwrap())} (optional)`;
+  if (schema instanceof z.ZodNullable) return `${zodTypeName(schema.unwrap())} | null`;
+  if (schema instanceof z.ZodLiteral)  return `"${String(schema.value)}"`;
+  if (schema instanceof z.ZodObject)   return "object";
+  return "any";
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function buildResponseFormatAppendix(schema: z.ZodType<any>): string {
+  const header = ["## Response Format", "", "When you emit `exit_signal: true` in your `<status>` block, also include a `<response>` block containing JSON immediately after `<status>`:", ""];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const shape: Record<string, any> | null =
+    schema instanceof z.ZodObject ? (schema as z.ZodObject<z.ZodRawShape>).shape : null;
+  const body = shape
+    ? (() => {
+      const entries = Object.entries(shape);
+      const example = Object.fromEntries(entries.map(([k, v]) => [k, `<${zodTypeName(v)}>`]));
+      return [
+        "Fields:",
+        ...entries.map(([k, v]) => `- \`${k}\` (${zodTypeName(v)})`),
+        "", "Example:", "<response>",
+        JSON.stringify(example, null, 2),
+        "</response>",
+      ];
+    })()
+    : [
+      "The response must match this schema:",
+      `Expected type: ${zodTypeName(schema)}`,
+      "", "Example:", "<response>",
+      `<${zodTypeName(schema)}>`,
+      "</response>",
+    ];
+  return [...header, ...body].join("\n");
+}
+
+export interface RunAgentOpts<T = unknown> {
+  /** Sandbox the runtime executes commands against. Inside a workflow,
+   *  always pass `ctx.sandbox` — a pre-constructed local provider for
+   *  the runner's own VM. Exposed as a parameter so tests and non-workflow
+   *  callers can substitute their own. */
+  sandbox: SandboxProvider;
+  /** Runtime definition from `createClaudeRuntime({...})` (or custom). */
+  runtime: AgentRuntime;
+  /** Prompt template. Authors can include YAML-style `--- frontmatter ---`
+   *  at the top for IDE hints; it's stripped before the model sees it. */
+  prompt: string;
+  /** Substitution map for `{{VAR}}` placeholders in the prompt. `WORKING_DIR`
+   *  and `DIFF_BASE` auto-populate from `opts.workingDir` unless overridden. */
+  promptVars?: Record<string, string>;
+  /** `cwd` forwarded to the runtime — every shell command runs here. */
+  workingDir?: string;
+  /** Tools the model may use. Defaults to a safe kitchen-sink set inside
+   *  `agentLoop`. Pass [] to disable tool use entirely. */
+  tools?: string[];
+  /** Turn/iteration caps. Defaults: 40 turns/iteration, 8 iterations. */
+  budget?: AgentBudget;
+  /** If set, the loop demands a `<response>` block when `exit_signal=true`
+   *  and validates it against this schema. The response format appendix is
+   *  appended to the prompt on first iteration. */
+  responseSchema?: z.ZodType<T>;
+  /** Label prefix for runtime stderr ("[sbid][agent]" by default). */
+  label?: string;
+  /** Per-message event callback — wire this to your workflow's event
+   *  telemetry if you want per-tool-call observability. */
+  onAgentEvent?: (iteration: number, msg: AgentMessage) => void;
+  /** Per-iteration status callback — fires after each model turn with the
+   *  parsed `<status>` block (or null if the model didn't emit one). */
+  onIteration?: (iteration: number, status: AgentStatus | null) => void;
+}
+
+/**
+ * Run an agent loop inside a workflow. Returns the loop's final
+ * `AgentLoopResult`, including `response` when a `responseSchema` was
+ * supplied and the model validated against it.
+ */
+export async function runAgent<T = unknown>(opts: RunAgentOpts<T>): Promise<AgentLoopResult> {
+  const workingDir = opts.workingDir ?? "";
+  const promptVars = { WORKING_DIR: workingDir, DIFF_BASE: "HEAD~1", ...opts.promptVars };
+
+  return agentLoop({
+    runtime: (runtimeOpts: RuntimeOptions) => opts.runtime.create(opts.sandbox, runtimeOpts),
+    ...(opts.label !== undefined ? { label: opts.label } : {}),
+    ...(opts.budget?.turnsPerIteration !== undefined ? { turnsPerIteration: opts.budget.turnsPerIteration } : {}),
+    ...(opts.budget?.maxIterations     !== undefined ? { maxIterations:     opts.budget.maxIterations }     : {}),
+    ...(opts.tools                      !== undefined ? { allowedTools:      opts.tools }                    : {}),
+    ...(opts.responseSchema             !== undefined ? { responseSchema:    opts.responseSchema }           : {}),
+    ...(workingDir                                     ? { cwd: workingDir }                                 : {}),
+    buildPrompt: (_lastStatus, iteration) => {
+      // Mid-loop: session resumes via --resume, model has history; only the
+      // protocol suffix is needed so tool-use + status block grammar stays fresh.
+      if (iteration > 0) return PROTOCOL_SUFFIX;
+      const base = inject(stripFrontmatter(opts.prompt), promptVars);
+      return opts.responseSchema
+        ? `${base}\n\n${PROTOCOL_SUFFIX}\n\n${buildResponseFormatAppendix(opts.responseSchema)}`
+        : `${base}\n\n${PROTOCOL_SUFFIX}`;
+    },
+    ...(opts.onAgentEvent ? { onAgentEvent: opts.onAgentEvent } : {}),
+    ...(opts.onIteration  ? { onIteration:  opts.onIteration  } : {}),
+  });
+}