@ryanfw/prompt-orchestration-pipeline 1.3.4 → 1.3.5

package/docs/http-api.md

@@ -81,7 +81,10 @@ or on error:
 | `forbidden_origin` | 403 | Cross-origin mutation rejected |
 | `status_unavailable` | 500 | Job status file unreadable |
 | `no_pending_gate` | 409 | Job has no pending gate decision |
+| `INVALID_JSON` | 409 | Job status JSON is invalid |
+| `STATUS_CORRUPT` | 409 | Job status file is corrupt |
 | `FS_ERROR` | 500 | Filesystem operation failed |
+| `BAD_PATH` | 400 | Task analysis path is invalid |
 | `BAD_REQUEST` | 400 | Malformed request body |
 | `NOT_FOUND` | 404 | Route or resource not found |
 

package/docs/pop-task-guide.md

@@ -209,6 +209,7 @@ export const inference = async ({ runAgent, io, data, flags }) => {
     // timeoutMs?: number     // optional wall-clock cap
     // idleTimeoutMs?: number // optional no-output cap
     // captureDiff?: boolean  // capture a git diff as 'agent.patch'
+    // onEvent?: (event) => {} // observe adapter harness events during the run
   });
 
   if (!result.ok) {
@@ -226,6 +227,13 @@ By default (`io` is `true`) the agent shares the task's file I/O: it can call th
 task sees, and its `agent-result.md` is written automatically. Token usage and
 cost flow into the job status like any other LLM call.
 
+Use `onEvent` when a task needs to observe live harness activity, such as
+assistant messages, tool calls, usage events, or run completion. POP invokes the
+callback after it has buffered the event and appended the redacted debug log, so
+omitting the callback leaves behavior unchanged. The `event.raw` payload comes
+directly from the underlying CLI adapter; treat it as unstable and avoid
+persisting it unless you have considered sensitive values in the raw stream.
+
 **`runAgent` vs `llm`**: use `llm.<provider>.chat()` for a single request/response
 LLM call; use `runAgent()` when you need a tool-using CLI agent that reads and
 writes files over multiple turns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryanfw/prompt-orchestration-pipeline",
-  "version": "1.3.4",
+  "version": "1.3.5",
   "description": "A Prompt-orchestration pipeline (POP) is a framework for building, running, and experimenting with complex chains of LLM tasks.",
   "type": "module",
   "main": "src/ui/server/index.ts",
@@ -32,7 +32,10 @@
     "ui": "NODE_ENV=development bun --watch src/ui/server/index.ts",
     "ui:dev": "vite",
     "ui:build": "vite build && bun run generate:embedded-assets",
-    "prepack": "bun run ui:build",
+    "verify:package": "bun scripts/verify-package-assets.js",
+    "smoke:packed-consumer": "bun scripts/smoke-packed-consumer.js",
+    "release:check": "bun run ui:build && bun run verify:package && bun run smoke:packed-consumer",
+    "prepack": "bun run ui:build && bun run verify:package",
     "ui:prod": "bun src/ui/server/index.ts",
     "demo:ui": "NODE_ENV=production PO_ROOT=demo bun src/ui/server/index.ts",
     "demo:orchestrator": "PO_ROOT=demo NODE_ENV=production bun -e \"import('./src/core/orchestrator.ts').then(m => m.startOrchestrator({ dataDir: process.env.PO_ROOT || 'demo' })).catch(err => { console.error(err); process.exit(1) })\"",

package/src/cli/__tests__/analyze-task.test.ts

@@ -12,11 +12,10 @@ const availability: ProviderAvailability = {
   anthropic: false,
   gemini: false,
   zai: false,
-  zhipu: false,
-  claudecode: false,
   moonshot: false,
   alibaba: false,
   opencode: false,
+  "claude-code": false,
   mock: false,
 };
 

package/src/config/__tests__/config-schema.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import Ajv from "ajv";
+
+const schemaPath = join(process.cwd(), "config.schema.json");
+const schema = JSON.parse(readFileSync(schemaPath, "utf-8")) as {
+  properties: { llm: { properties: { defaultProvider: { enum: string[] } } } };
+};
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+const validate = ajv.compile(schema);
+
+function llmConfig(defaultProvider: string): unknown {
+  return { llm: { defaultProvider } };
+}
+
+describe("config.schema.json defaultProvider enum", () => {
+  it("accepts canonical provider ids", () => {
+    expect(validate(llmConfig("openai"))).toBe(true);
+    expect(validate(llmConfig("zai"))).toBe(true);
+    expect(validate(llmConfig("claude-code"))).toBe(true);
+    expect(validate(llmConfig("moonshot"))).toBe(true);
+  });
+
+  it("rejects legacy provider ids", () => {
+    expect(validate(llmConfig("zhipu"))).toBe(false);
+    expect(validate(llmConfig("claudecode"))).toBe(false);
+  });
+
+  it("rejects unknown provider ids", () => {
+    expect(validate(llmConfig("neverheard"))).toBe(false);
+  });
+
+  it("enum matches the canonical ProviderName set (no legacy spellings)", () => {
+    const enumValues = schema.properties.llm.properties.defaultProvider.enum;
+    expect(enumValues).not.toContain("zhipu");
+    expect(enumValues).not.toContain("claudecode");
+    expect(enumValues).toContain("zai");
+    expect(enumValues).toContain("claude-code");
+  });
+});

package/src/config/__tests__/legacy-literal-guard.test.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect } from "bun:test";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+
+const FORBIDDEN_LITERALS: ReadonlySet<string> = new Set([
+  "zhipu",
+  "claudecode",
+]);
+
+const STRING_LITERAL_RE = /"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g;
+
+const ALLOWED_FILES: ReadonlySet<string> = new Set([
+  "src/config/models.ts",
+  "src/config/__tests__/models.test.ts",
+  "src/config/__tests__/config-schema.test.ts",
+  "src/config/__tests__/legacy-literal-guard.test.ts",
+  "src/llm/__tests__/legacy-normalization.test.ts",
+  "src/llm/__tests__/index.test.ts",
+  "src/providers/__tests__/types.test.ts",
+  "src/task-analysis/__tests__/analyzer.test.ts",
+  "src/task-analysis/__tests__/enrichers-schema-deducer.test.ts",
+]);
+
+export interface LegacyLiteralViolation {
+  path: string;
+  literal: string;
+}
+
+export interface SourceFile {
+  path: string;
+  content: string;
+}
+
+export function extractStringLiterals(source: string): string[] {
+  const out: string[] = [];
+  for (const match of source.matchAll(STRING_LITERAL_RE)) {
+    const raw = match[0] as string;
+    out.push(raw.slice(1, -1));
+  }
+  return out;
+}
+
+export function scanFiles(
+  files: SourceFile[],
+  allowlist: ReadonlySet<string>,
+): LegacyLiteralViolation[] {
+  const violations: LegacyLiteralViolation[] = [];
+  for (const file of files) {
+    if (allowlist.has(file.path)) continue;
+    for (const literal of extractStringLiterals(file.content)) {
+      if (FORBIDDEN_LITERALS.has(literal)) {
+        violations.push({ path: file.path, literal });
+      }
+    }
+  }
+  return violations;
+}
+
+export function listSourceTsFiles(scanRoot: string, base: string): SourceFile[] {
+  const rootAbs = resolve(scanRoot);
+  const baseAbs = resolve(base);
+  const out: SourceFile[] = [];
+
+  function walk(dir: string): void {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      const st = statSync(full);
+      if (st.isDirectory()) {
+        walk(full);
+      } else if (st.isFile() && /\.(ts|tsx)$/.test(entry)) {
+        const rel = relative(baseAbs, full).split(sep).join("/");
+        out.push({ path: rel, content: readFileSync(full, "utf-8") });
+      }
+    }
+  }
+
+  walk(rootAbs);
+  return out;
+}
+
+describe("extractStringLiterals", () => {
+  it("captures a double-quoted forbidden literal", () => {
+    expect(extractStringLiterals('const p = "zhipu";')).toContain("zhipu");
+  });
+
+  it("ignores the bare legacy word in a comment", () => {
+    expect(extractStringLiterals("// legacy zhipu id\nconst x = 1;")).toEqual([]);
+  });
+});
+
+describe("scanFiles — forbidden literal detection", () => {
+  it('flags "zhipu" outside the allowlist', () => {
+    const violations = scanFiles(
+      [{ path: "src/x.ts", content: 'const p = "zhipu";' }],
+      new Set(),
+    );
+    expect(violations).toEqual([{ path: "src/x.ts", literal: "zhipu" }]);
+  });
+
+  it('flags "claudecode" outside the allowlist', () => {
+    const violations = scanFiles(
+      [{ path: "src/y.ts", content: "const q = \"claudecode\";" }],
+      new Set(),
+    );
+    expect(violations).toEqual([{ path: "src/y.ts", literal: "claudecode" }]);
+  });
+
+  it("skips files listed in the allowlist", () => {
+    const violations = scanFiles(
+      [{ path: "src/config/models.ts", content: 'legacyAliases: ["zhipu"]' }],
+      new Set(["src/config/models.ts"]),
+    );
+    expect(violations).toEqual([]);
+  });
+});
+
+describe("scanFiles — legitimate substrings are not flagged", () => {
+  it("ignores the ZHIPU_API_KEY env-var name", () => {
+    const violations = scanFiles(
+      [{ path: "src/env.ts", content: 'const k = "ZHIPU_API_KEY";' }],
+      new Set(),
+    );
+    expect(violations).toEqual([]);
+  });
+
+  it("ignores an import path that ends in zhipu.ts", () => {
+    const violations = scanFiles(
+      [
+        {
+          path: "src/llm/index.ts",
+          content: 'import { zaiChat } from "../providers/zhipu.ts";',
+        },
+      ],
+      new Set(),
+    );
+    expect(violations).toEqual([]);
+  });
+
+  it("ignores the legacy word inside a comment", () => {
+    const violations = scanFiles(
+      [{ path: "src/cmt.ts", content: "// legacy zhipu id\nconst x = 1;" }],
+      new Set(),
+    );
+    expect(violations).toEqual([]);
+  });
+});
+
+describe("legacy-literal source guard (AC-3)", () => {
+  it("src/ has no forbidden legacy literals outside the allowlist", () => {
+    const cwd = process.cwd();
+    const files = listSourceTsFiles(join(cwd, "src"), cwd);
+    const violations = scanFiles(files, ALLOWED_FILES);
+
+    expect(violations).toEqual([]);
+  });
+});

package/src/config/__tests__/models.test.ts

@@ -6,17 +6,20 @@ import {
   DEFAULT_MODEL_BY_PROVIDER,
   FUNCTION_NAME_BY_ALIAS,
   PROVIDER_FUNCTIONS,
+  PROVIDERS,
   aliasToFunctionName,
   getProviderFromAlias,
   getModelFromAlias,
   getModelConfig,
   buildProviderFunctionsIndex,
+  normalizeLegacyProvider,
   validateModelRegistry,
 } from "../models";
-import type { ModelConfigEntry } from "../models";
+import type { ModelConfigEntry, ProviderName, ProviderMeta } from "../models";
 
 const MODEL_COUNT = 51;
 const PROVIDER_COUNT = 9;
+const REGISTRY_PROVIDER_COUNT = 10;
 
 describe("ModelAlias", () => {
   it(`has exactly ${MODEL_COUNT} entries`, () => {
@@ -378,3 +381,138 @@ describe("validateModelRegistry — invariant failures", () => {
     expect(() => validateModelRegistry(config, set)).not.toThrow();
   });
 });
+
+describe("normalizeLegacyProvider", () => {
+  it('maps legacy "zhipu" to canonical "zai"', () => {
+    expect(normalizeLegacyProvider("zhipu")).toBe("zai");
+  });
+
+  it('maps legacy "claudecode" to canonical "claude-code"', () => {
+    expect(normalizeLegacyProvider("claudecode")).toBe("claude-code");
+  });
+
+  it('returns canonical "zai" for itself', () => {
+    expect(normalizeLegacyProvider("zai")).toBe("zai");
+  });
+
+  it('returns canonical "claude-code" for itself', () => {
+    expect(normalizeLegacyProvider("claude-code")).toBe("claude-code");
+  });
+
+  it('returns canonical "openai" for itself', () => {
+    expect(normalizeLegacyProvider("openai")).toBe("openai");
+  });
+
+  it("returns null for an unknown provider string", () => {
+    expect(normalizeLegacyProvider("unknown")).toBeNull();
+  });
+
+  it("returns null for the empty string", () => {
+    expect(normalizeLegacyProvider("")).toBeNull();
+  });
+
+  it("returns null for Object.prototype property names", () => {
+    expect(normalizeLegacyProvider("constructor")).toBeNull();
+    expect(normalizeLegacyProvider("toString")).toBeNull();
+    expect(normalizeLegacyProvider("valueOf")).toBeNull();
+    expect(normalizeLegacyProvider("hasOwnProperty")).toBeNull();
+    expect(normalizeLegacyProvider("__proto__")).toBeNull();
+  });
+});
+
+describe("PROVIDERS registry invariants", () => {
+  const CANONICAL_PROVIDER_IDS: ProviderName[] = [
+    "openai",
+    "anthropic",
+    "deepseek",
+    "gemini",
+    "zai",
+    "claude-code",
+    "moonshot",
+    "alibaba",
+    "opencode",
+    "mock",
+  ];
+
+  it(`has exactly ${REGISTRY_PROVIDER_COUNT} rows, one per canonical ProviderName`, () => {
+    expect(Object.keys(PROVIDERS).length).toBe(REGISTRY_PROVIDER_COUNT);
+    for (const id of CANONICAL_PROVIDER_IDS) {
+      expect(id in PROVIDERS).toBe(true);
+    }
+  });
+
+  it("table is frozen", () => {
+    expect(Object.isFrozen(PROVIDERS)).toBe(true);
+  });
+
+  it("legacyAliases are unique across the registry (no alias maps to two providers)", () => {
+    const seen = new Map<string, ProviderName>();
+    for (const [canonical, meta] of Object.entries(PROVIDERS) as [ProviderName, ProviderMeta][]) {
+      for (const alias of meta.legacyAliases) {
+        const prior = seen.get(alias);
+        if (prior !== undefined) {
+          throw new Error(
+            `legacy alias "${alias}" is claimed by both "${prior}" and "${canonical}"`,
+          );
+        }
+        seen.set(alias, canonical);
+      }
+    }
+  });
+
+  it("no legacy alias collides with a canonical id", () => {
+    const canonicalSet = new Set<string>(CANONICAL_PROVIDER_IDS);
+    for (const meta of Object.values(PROVIDERS)) {
+      for (const alias of meta.legacyAliases) {
+        expect(canonicalSet.has(alias)).toBe(false);
+      }
+    }
+  });
+
+  it("MODEL_CONFIG providers are all registered catalog providers (no orphans, no mock)", () => {
+    for (const entry of Object.values(MODEL_CONFIG)) {
+      expect(entry.provider in PROVIDERS).toBe(true);
+      expect(entry.provider).not.toBe("mock");
+    }
+  });
+
+  it("MODEL_CONFIG / DEFAULT_MODEL_BY_PROVIDER / PROVIDER_FUNCTIONS exclude only mock from the registry", () => {
+    const registryKeys = new Set<string>(Object.keys(PROVIDERS));
+    const catalogKeys = new Set<string>(Object.keys(PROVIDER_FUNCTIONS));
+    const defaultKeys = new Set<string>(
+      Object.keys(DEFAULT_MODEL_BY_PROVIDER) as string[],
+    );
+
+    for (const key of catalogKeys) expect(registryKeys.has(key)).toBe(true);
+    for (const key of defaultKeys) expect(registryKeys.has(key)).toBe(true);
+
+    const missingFromCatalog = [...registryKeys].filter(
+      (k) => !catalogKeys.has(k),
+    );
+    const missingFromDefaults = [...registryKeys].filter(
+      (k) => !defaultKeys.has(k),
+    );
+    expect(missingFromCatalog).toEqual(["mock"]);
+    expect(missingFromDefaults).toEqual(["mock"]);
+  });
+
+  it("canonical<->alias round-trip via normalizeLegacyProvider", () => {
+    for (const [canonical, meta] of Object.entries(PROVIDERS) as [ProviderName, ProviderMeta][]) {
+      expect(normalizeLegacyProvider(canonical)).toBe(canonical);
+      for (const alias of meta.legacyAliases) {
+        expect(normalizeLegacyProvider(alias)).toBe(canonical);
+      }
+    }
+  });
+
+  it("CLI providers declare sampling: []", () => {
+    expect(PROVIDERS["claude-code"]!.sampling).toEqual([]);
+    expect(PROVIDERS.opencode!.sampling).toEqual([]);
+  });
+
+  it("mock is runtime-only: empty envKeys/sampling, isCLI false", () => {
+    expect(PROVIDERS.mock!.envKeys).toEqual([]);
+    expect(PROVIDERS.mock!.sampling).toEqual([]);
+    expect(PROVIDERS.mock!.isCLI).toBe(false);
+  });
+});

package/src/config/models.ts

@@ -1,16 +1,118 @@
-export type ProviderName =
-  | "openai"
-  | "anthropic"
-  | "gemini"
-  | "deepseek"
-  | "moonshot"
-  | "claude-code"
-  | "zai"
-  | "alibaba"
-  | "opencode";
+import type { ProviderName } from "../providers/types.ts";
+
+export type { ProviderName };
+
+// ─── Provider Facts Registry (pure data; behavior wired in llm/index.ts) ─────
+
+export type SamplingParam =
+  | "temperature"
+  | "topP"
+  | "stop"
+  | "frequencyPenalty"
+  | "presencePenalty"
+  | "seed";
+
+export interface ProviderMeta {
+  usageAvailable: boolean;
+  isCLI: boolean;
+  sampling: SamplingParam[];
+  envKeys: string[];
+  legacyAliases: string[];
+}
+
+export type ModelCatalogProviderName = Exclude<ProviderName, "mock">;
+
+export const PROVIDERS: Readonly<Record<ProviderName, ProviderMeta>> = Object.freeze({
+  openai: {
+    usageAvailable: true,
+    isCLI: false,
+    sampling: ["temperature", "topP", "stop", "frequencyPenalty", "presencePenalty", "seed"],
+    envKeys: ["OPENAI_API_KEY"],
+    legacyAliases: [],
+  },
+  anthropic: {
+    usageAvailable: true,
+    isCLI: false,
+    sampling: ["temperature", "topP", "stop"],
+    envKeys: ["ANTHROPIC_API_KEY"],
+    legacyAliases: [],
+  },
+  gemini: {
+    usageAvailable: true,
+    isCLI: false,
+    sampling: ["temperature", "topP", "stop"],
+    envKeys: ["GEMINI_API_KEY"],
+    legacyAliases: [],
+  },
+  deepseek: {
+    usageAvailable: true,
+    isCLI: false,
+    sampling: ["temperature", "topP", "stop", "frequencyPenalty", "presencePenalty"],
+    envKeys: ["DEEPSEEK_API_KEY"],
+    legacyAliases: [],
+  },
+  moonshot: {
+    usageAvailable: true,
+    isCLI: false,
+    sampling: ["temperature", "topP", "stop"],
+    envKeys: ["MOONSHOT_API_KEY"],
+    legacyAliases: [],
+  },
+  zai: {
+    usageAvailable: true,
+    isCLI: false,
+    sampling: ["temperature", "topP", "stop"],
+    envKeys: ["ZAI_API_KEY", "ZHIPU_API_KEY"],
+    legacyAliases: ["zhipu"],
+  },
+  alibaba: {
+    usageAvailable: true,
+    isCLI: false,
+    sampling: ["temperature", "topP", "stop", "frequencyPenalty", "presencePenalty"],
+    envKeys: ["ALIBABA_API_KEY"],
+    legacyAliases: [],
+  },
+  "claude-code": {
+    usageAvailable: false,
+    isCLI: true,
+    sampling: [],
+    envKeys: [],
+    legacyAliases: ["claudecode"],
+  },
+  opencode: {
+    usageAvailable: true,
+    isCLI: true,
+    sampling: [],
+    envKeys: [],
+    legacyAliases: [],
+  },
+  mock: {
+    usageAvailable: true,
+    isCLI: false,
+    sampling: [],
+    envKeys: [],
+    legacyAliases: [],
+  },
+});
+
+/**
+ * Resolves a runtime provider string to its canonical ProviderName. Returns the
+ * canonical id for canonical input and for registered legacy aliases; returns
+ * `null` for unknown strings. Derived from PROVIDERS[*].legacyAliases so the
+ * alias map stays single-source.
+ */
+export function normalizeLegacyProvider(name: string): ProviderName | null {
+  if (Object.hasOwn(PROVIDERS, name)) return name as ProviderName;
+  for (const [canonical, meta] of Object.entries(PROVIDERS) as [ProviderName, ProviderMeta][]) {
+    if (meta.legacyAliases.includes(name)) return canonical;
+  }
+  return null;
+}
+
+// ─── Model Catalog Types ─────────────────────────────────────────────────────
 
 export interface ModelConfigEntry {
-  readonly provider: ProviderName;
+  readonly provider: ModelCatalogProviderName;
   readonly model: string;
   readonly tokenCostInPerMillion: number;
   readonly tokenCostOutPerMillion: number;
@@ -18,7 +120,7 @@ export interface ModelConfigEntry {
 
 export interface ProviderFunctionEntry {
   readonly alias: string;
-  readonly provider: ProviderName;
+  readonly provider: ModelCatalogProviderName;
   readonly model: string;
   readonly functionName: string;
   readonly fullPath: string;
@@ -452,7 +554,7 @@ export function aliasToFunctionName(alias: string): string {
   );
 }
 
-export function getProviderFromAlias(alias: string): ProviderName {
+export function getProviderFromAlias(alias: string): ModelCatalogProviderName {
   if (typeof alias !== "string") {
     throw new Error(
       `Invalid model alias: expected string, got ${typeof alias}`,
@@ -461,7 +563,7 @@ export function getProviderFromAlias(alias: string): ProviderName {
   if (!alias.includes(":")) {
     throw new Error(`Invalid model alias: "${alias}" does not contain a colon`);
   }
-  return alias.split(":")[0] as ProviderName;
+  return alias.split(":")[0] as ModelCatalogProviderName;
 }
 
 export function getModelFromAlias(alias: string): string {
@@ -486,7 +588,7 @@ export function getModelConfig(alias: string): ModelConfigEntry | null {
 // ─── Default Model By Provider ───────────────────────────────────────────────
 
 export const DEFAULT_MODEL_BY_PROVIDER: Readonly<
-  Record<ProviderName, ModelAliasKey>
+  Record<ModelCatalogProviderName, ModelAliasKey>
 > = Object.freeze({
   openai: "openai:gpt-5.4",
   anthropic: "anthropic:sonnet-4-6",
@@ -497,7 +599,7 @@ export const DEFAULT_MODEL_BY_PROVIDER: Readonly<
   zai: "zai:glm-5-1",
   alibaba: "alibaba:qwen3-max",
   opencode: "opencode:default",
-} as const);
+} satisfies Record<ModelCatalogProviderName, ModelAliasKey>);
 
 // ─── Function Name Derived Index ─────────────────────────────────────────────
 
@@ -514,11 +616,11 @@ export const FUNCTION_NAME_BY_ALIAS: Readonly<Record<ModelAliasKey, string>> =
 // ─── Provider Functions Index ────────────────────────────────────────────────
 
 export type ProviderFunctionsIndex = Readonly<
-  Record<ProviderName, readonly ProviderFunctionEntry[]>
+  Record<ModelCatalogProviderName, readonly ProviderFunctionEntry[]>
 >;
 
 export function buildProviderFunctionsIndex(): ProviderFunctionsIndex {
-  const index: Partial<Record<ProviderName, ProviderFunctionEntry[]>> = {};
+  const index: Partial<Record<ModelCatalogProviderName, ProviderFunctionEntry[]>> = {};
 
   for (const alias of Object.keys(MODEL_CONFIG) as ModelAliasKey[]) {
     const entry = (MODEL_CONFIG as Record<string, ModelConfigEntry>)[alias]!;
@@ -542,7 +644,7 @@ export function buildProviderFunctionsIndex(): ProviderFunctionsIndex {
   }
 
   // Freeze each provider array
-  for (const provider of Object.keys(index) as ProviderName[]) {
+  for (const provider of Object.keys(index) as ModelCatalogProviderName[]) {
     Object.freeze(index[provider]);
   }
 

package/src/core/__tests__/agent-step.test.ts

@@ -518,6 +518,58 @@ describe("runAgentStep", () => {
     expect(logCalls[0]).toBe("writeLog:test-agent-agent-debug.log");
   });
 
+  it("passes every observed event to a provided entry.onEvent", async () => {
+    const io = createFakeIO();
+    const events: HarnessEvent[] = [
+      { harness: "claude", seq: 0, at: 1, raw: { text: "hello" }, type: "assistant_message", text: "hello" },
+      { harness: "claude", seq: 1, at: 2, raw: { message: "done" }, type: "run_completed", result: makeSuccessResult() },
+    ];
+    const run = mock((opts: { onEvent?: (event: HarnessEvent) => void }) => {
+      for (const event of events) {
+        opts.onEvent?.(event);
+      }
+      return makeFakeHarnessRun(makeSuccessResult());
+    });
+    const startMcpIoServer = mock(async () => createFakeMcpHandle());
+
+    const relayed: HarnessEvent[] = [];
+    await executeAgent(
+      {
+        io,
+        entry: { name: "a", harness: "claude", prompt: "p", onEvent: (e) => relayed.push(e) },
+      },
+      { run, startMcpIoServer },
+    );
+
+    expect(relayed).toEqual(events);
+    const logCalls = io.calls.filter((c) => c.startsWith("writeLog:"));
+    expect(logCalls).toHaveLength(events.length);
+  });
+
+  it("with no entry.onEvent, buffering and debug-log writes are unchanged", async () => {
+    const io = createFakeIO();
+    const events: HarnessEvent[] = [
+      { harness: "claude", seq: 0, at: 1, raw: { text: "hello" }, type: "assistant_message", text: "hello" },
+      { harness: "claude", seq: 1, at: 2, raw: { message: "done" }, type: "run_completed", result: makeSuccessResult() },
+    ];
+    const run = mock((opts: { onEvent?: (event: HarnessEvent) => void }) => {
+      for (const event of events) {
+        opts.onEvent?.(event);
+      }
+      return makeFakeHarnessRun(makeSuccessResult());
+    });
+    const startMcpIoServer = mock(async () => createFakeMcpHandle());
+
+    const result = await executeAgent(
+      { io, entry: { name: "a", harness: "claude", prompt: "p" } },
+      { run, startMcpIoServer },
+    );
+
+    expect(result.ok).toBe(true);
+    const logCalls = io.calls.filter((c) => c.startsWith("writeLog:"));
+    expect(logCalls).toHaveLength(events.length);
+  });
+
   it("promptFrom reads the named artifact for the prompt", async () => {
     let capturedIO: ReturnType<typeof createFakeIO> | undefined;
     const createTaskFileIO = mock(() => {