@stigmer/runner 3.12.3 → 3.12.4

package/src/shared/model-client.ts

@@ -34,6 +34,12 @@ import {
   toFoundryDeploymentName,
 } from "./llm-backend.js";
 import { resolveToApiModelId } from "./model-registry.js";
+import {
+  toAnthropicServiceTier,
+  toOpenAiServiceTier,
+  type EffectiveServiceTier,
+} from "./service-tier.js";
+import { getRunnerSecret } from "./runner-credential-store.js";
 
 export interface BuildChatModelOptions {
   /** Registry id ("claude-haiku-4.5"), "provider:model", or a provider API id. */
@@ -63,6 +69,20 @@ export interface BuildChatModelOptions {
    */
   readonly timeoutMs?: number;
   readonly maxRetries?: number;
+  /**
+   * The execution's EFFECTIVE service tier (stigmer/stigmer#361) — already
+   * resolved by the caller (resolveEffectiveServiceTier), never
+   * UNSPECIFIED. When set, every provider request pins its tier explicitly
+   * (OpenAI `service_tier`; Anthropic `service_tier` via invocationKwargs)
+   * so the provider ACCOUNT's default can never pick the price — the #357
+   * contract, held on the native harness. Deliberately optional:
+   * platform-internal utility calls (tool-approval classification, session
+   * subjects, structured extraction, workflow llm_call) are not the
+   * execution's own turns and send no tier — the provider treats an absent
+   * parameter as its standard behavior, and those calls' models are
+   * platform-chosen economy models.
+   */
+  readonly serviceTier?: EffectiveServiceTier;
 }
 
 /**
@@ -128,11 +148,11 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
   // tests. Prerequisites are re-checked here (not only in
   // the factories' preflight) so paths that construct models without a
   // runner factory still fail at dispatch with the catalog message instead
-  // of mid-request. Credentials are read natively by each SDK from its
-  // standard conventions (GCP: CLOUD_ML_REGION + ADC; AWS: AWS_REGION +
-  // the credential chain / AWS_BEARER_TOKEN_BEDROCK; Foundry:
-  // ANTHROPIC_FOUNDRY_API_KEY, or the Azure credential chain when no key
-  // is set).
+  // of mid-request. Ambient credentials are read natively by each SDK from
+  // its standard conventions (GCP: CLOUD_ML_REGION + ADC; AWS: AWS_REGION +
+  // the credential chain); runner-held keys (AWS_BEARER_TOKEN_BEDROCK,
+  // ANTHROPIC_FOUNDRY_API_KEY) are passed explicitly from the credential
+  // store because the boot capture empties their env slots (#508).
   let backendCreateClient:
     | ((options: { maxRetries?: number; timeout?: number }) => unknown)
     | undefined;
@@ -149,8 +169,17 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
     const prereq = checkBedrockPrerequisites();
     if (prereq !== null) throw new Error(prereq);
     const { AnthropicBedrock } = await import("@anthropic-ai/bedrock-sdk");
+    // The SDK's own default for `apiKey` is process.env.AWS_BEARER_TOKEN_BEDROCK,
+    // which the boot capture has emptied (#508) — hand it the stored value
+    // explicitly. `undefined` when absent preserves the SDK's fallthrough to
+    // the ambient AWS credential chain (env keys, IRSA, config files).
+    const bedrockBearerToken = getRunnerSecret("AWS_BEARER_TOKEN_BEDROCK");
     backendCreateClient = (options) =>
-      new AnthropicBedrock({ maxRetries: options.maxRetries, timeout: options.timeout });
+      new AnthropicBedrock({
+        apiKey: bedrockBearerToken,
+        maxRetries: options.maxRetries,
+        timeout: options.timeout,
+      });
     wireModelId = toBedrockModelId(apiModelId);
     if (maxTokens === undefined) {
       // LangChain's per-model maxTokens table prefix-matches the model
@@ -179,8 +208,13 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
     // so refreshed tokens flow without reconstruction (pinned by
     // foundry-seam.test.ts). Endpoint (resource or base URL) and the key
     // are read natively by the SDK from its own env vars.
+    // The SDK's own default for `apiKey` is process.env.ANTHROPIC_FOUNDRY_API_KEY,
+    // which the boot capture has emptied (#508) — resolve it from the store
+    // and hand it over explicitly. The either/or stays intact: exactly one of
+    // apiKey / azureADTokenProvider reaches the constructor.
+    const foundryApiKey = getRunnerSecret("ANTHROPIC_FOUNDRY_API_KEY")?.trim() || undefined;
     let azureADTokenProvider: (() => Promise<string>) | undefined;
-    if (!process.env.ANTHROPIC_FOUNDRY_API_KEY?.trim()) {
+    if (!foundryApiKey) {
       const { DefaultAzureCredential, getBearerTokenProvider } = await import("@azure/identity");
       azureADTokenProvider = getBearerTokenProvider(
         new DefaultAzureCredential(),
@@ -191,7 +225,7 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
       new AnthropicFoundry({
         maxRetries: options.maxRetries,
         timeout: options.timeout,
-        ...(azureADTokenProvider ? { azureADTokenProvider } : {}),
+        ...(foundryApiKey ? { apiKey: foundryApiKey } : { azureADTokenProvider }),
       });
     // Unlike the vertex/bedrock ids, the deployment name needs no maxTokens
     // handling: stripping the snapshot date preserves LangChain's per-model
@@ -207,19 +241,27 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
     ? buildProxyHeaders(opts.stigmerToken, opts.headerScope ?? {})
     : undefined;
 
-  // Proxy mode authenticates with the Stigmer token; direct mode falls back to
-  // the provider's own env-var key.
+  // Proxy mode authenticates with the Stigmer token; direct mode falls back
+  // to the provider's own key, resolved from the credential store (the boot
+  // capture moved it out of process.env, #508).
   const apiKey = opts.proxyEndpoint
     ? (opts.stigmerToken ?? "proxy-managed")
     : provider === "openai"
-      ? (process.env.OPENAI_API_KEY ?? "")
-      : (process.env.ANTHROPIC_API_KEY ?? "");
+      ? (getRunnerSecret("OPENAI_API_KEY") ?? "")
+      : (getRunnerSecret("ANTHROPIC_API_KEY") ?? "");
 
+  // maxRetries applies when a timeout is bound (a retry loop under a bound
+  // multiplies the wall-clock budget) or when the caller pinned it
+  // explicitly (call-llm hands retry ownership to Temporal, #686). Callers
+  // that set neither keep LangChain's default retry behavior unchanged.
+  const maxRetries = timeoutMs !== undefined || opts.maxRetries !== undefined
+    ? { maxRetries: opts.maxRetries ?? 0 }
+    : {};
   const common = {
     temperature: opts.temperature ?? 0,
     apiKey,
     ...(maxTokens ? { maxTokens } : {}),
-    ...(timeoutMs ? { maxRetries: opts.maxRetries ?? 0 } : {}),
+    ...maxRetries,
   };
 
   // The request timeout lives in a different slot per wrapper: ChatOpenAI
@@ -242,6 +284,18 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
       ? { clientOptions: anthropicClientOptions }
       : {};
 
+  // The tier rides the request body per provider dialect (#361): OpenAI
+  // takes `service_tier` as a first-class constructor field; ChatAnthropic
+  // has no such field, so it rides `invocationKwargs`, which the wrapper
+  // spreads into every request body. Both spellings resolve through the
+  // shared mapping so no construction site can invent a third one.
+  const openAiServiceTierField = opts.serviceTier !== undefined
+    ? { service_tier: toOpenAiServiceTier(opts.serviceTier) }
+    : {};
+  const anthropicServiceTierField = opts.serviceTier !== undefined
+    ? { invocationKwargs: { service_tier: toAnthropicServiceTier(opts.serviceTier) } }
+    : {};
+
   // The two SDKs name the transport-override block differently (OpenAI:
   // `configuration`, Anthropic: `clientOptions`) — encapsulating that here is
   // the whole point, since the shape mismatch is where bugs used to hide.
@@ -249,6 +303,7 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
     ? new ChatOpenAI({
         model: apiModelId,
         ...common,
+        ...openAiServiceTierField,
         ...(timeoutMs ? { timeout: timeoutMs } : {}),
         ...(baseUrl || headers
           ? {
@@ -266,6 +321,13 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
         // provided) is what lets this construct with no ANTHROPIC_API_KEY.
         // (Backend mode never has a proxy — see the precedence rule above —
         // so the clientOptions here carry at most the timeout.)
+        //
+        // service_tier deliberately does NOT ride backend requests:
+        // standard/priority tiers are an Anthropic-FIRST-PARTY billing
+        // concept, and Vertex/Bedrock/Foundry bill through the cloud
+        // provider with no tier dimension — an unknown body param there is
+        // a request refusal waiting to happen. The account-default price
+        // hole this parameter closes does not exist on those backends.
         new ChatAnthropic({
           model: wireModelId,
           ...common,
@@ -275,6 +337,7 @@ export async function buildChatModel(opts: BuildChatModelOptions): Promise<Built
       : new ChatAnthropic({
           model: apiModelId,
           ...common,
+          ...anthropicServiceTierField,
           ...anthropicClientOptionsField,
         });
 

package/src/shared/registry-endpoint.ts

@@ -21,6 +21,7 @@
 
 import { normalizeEndpoint } from "../config.js";
 import type { FetchRetryPolicy } from "./http-retry.js";
+import { runnerSecretsEnvView } from "./runner-credential-store.js";
 
 /** Default local stigmer-server origin — mirrors config.ts's local-mode default. */
 const DEFAULT_LOCAL_BACKEND = "http://localhost:7234";
@@ -68,8 +69,15 @@ export function resolveRegistryBaseUrl(env: NodeJS.ProcessEnv = process.env): st
 /**
  * Build request headers for registry fetches: bearer auth when a token is
  * present (cloud requires it; the local server ignores it).
+ *
+ * The default env is the credential-store view, not bare `process.env`:
+ * both token names are captured out of the environment at boot (#508), and
+ * the store also carries rotated tokens (manager updateToken / static
+ * renewal) that never touch env at all.
  */
-export function buildRegistryHeaders(env: NodeJS.ProcessEnv = process.env): Record<string, string> {
+export function buildRegistryHeaders(
+  env: NodeJS.ProcessEnv = runnerSecretsEnvView(),
+): Record<string, string> {
   const token = env.STIGMER_TOKEN ?? env.STIGMER_AUTH_TOKEN;
   return token ? { Authorization: `Bearer ${token}` } : {};
 }

package/src/shared/runner-credential-keys.ts

@@ -10,7 +10,13 @@
  * their sanctioned delivery channel, and denying them here would break it.
  *
  * Consumers:
- * - shell-env.ts: SHELL_ENV_DENYLIST for the native harness `execute` tool.
+ * - runner-credential-store.ts: captures every name listed in this module
+ *   out of `process.env` at boot (issue #508 — the Cursor SDK's local agent
+ *   runtime runs in-process and its shell tool spawns from the runner's own
+ *   env, so credentials must not LIVE there; see that module for custody
+ *   rules).
+ * - shell-env.ts: SHELL_ENV_DENYLIST for the native harness `execute` tool
+ *   (defense-in-depth behind the boot scrub).
  * - mcp-manager.test.ts: leak-tripwire canaries for MCP stdio subprocesses
  *   (that path passes NO runner env by construction; the test plants these
  *   names to prove none leak through).
@@ -44,3 +50,32 @@ export const RUNNER_CREDENTIAL_ENV_KEYS: readonly string[] = [
   // (llm-backend.ts documents it as a supported auth path).
   "AWS_BEARER_TOKEN_BEDROCK",
 ];
+
+/**
+ * Env var names of the runner's non-credential secrets — material that is
+ * not an outbound-call credential (so it does not belong in
+ * {@link RUNNER_CREDENTIAL_ENV_KEYS}, whose inclusion rule is pinned above)
+ * but is every bit as sensitive in an agent-readable environment
+ * (owner ruling on #508: same boot scrub, separate constant so the #385
+ * rule keeps its meaning).
+ *
+ * The `*_KEY_ID` companions are deliberately absent: key identifiers are
+ * rotation bookkeeping, not secrets.
+ */
+export const RUNNER_ENCRYPTION_ENV_KEYS: readonly string[] = [
+  // Temporal payload-encryption keys (encryption/config.ts). An agent that
+  // reads these could decrypt the runner's Temporal history payloads.
+  "STIGMER_PAYLOAD_ENCRYPTION_KEY",
+  "STIGMER_PAYLOAD_ENCRYPTION_SECONDARY_KEY",
+];
+
+/**
+ * Every env name whose VALUE the credential store takes custody of at boot:
+ * the #385 credential set plus the #508 encryption-key set. This is the
+ * scrub list — after `captureRunnerSecrets()`, none of these names remain
+ * in `process.env`.
+ */
+export const RUNNER_SECRET_ENV_KEYS: readonly string[] = [
+  ...RUNNER_CREDENTIAL_ENV_KEYS,
+  ...RUNNER_ENCRYPTION_ENV_KEYS,
+];

package/src/shared/runner-credential-store.ts

@@ -0,0 +1,115 @@
+/**
+ * Custody point for the runner's own secrets — the VALUES companion to
+ * runner-credential-keys.ts's names (issue #508).
+ *
+ * Why this exists: the Cursor SDK's local agent runtime ships inside
+ * `@cursor/sdk` and runs IN-PROCESS in the runner. Its shell tool spawns
+ * bash with `{...process.env, ...}` and its git layer does the same, so
+ * anything living in the runner's `process.env` is readable by every shell
+ * command the agent runs — and the SDK exposes no env option for local
+ * agents to scrub at the spawn boundary. Denylists on runner-owned spawn
+ * sites (shell-env.ts) cannot reach those vendor spawns. The only fix that
+ * covers every spawn surface, present and future, is for secrets not to
+ * LIVE in `process.env` at all: this module captures them at boot and is
+ * the sole holder afterwards.
+ *
+ * Custody rules:
+ *
+ *  1. `captureRunnerSecrets()` runs at every boot door (both public runner
+ *     factories, plus main() for symmetry) — it MOVES every
+ *     {@link RUNNER_SECRET_ENV_KEYS} value out of `process.env` into a
+ *     module-private map. Idempotent; first call wins.
+ *  2. Reads go through {@link getRunnerSecret}: captured value first, live
+ *     `process.env` as fallback. The fallback keeps the store honest rather
+ *     than frozen — production sets these vars only at process start (the
+ *     capture window), so the fallback is a dead path there, but tests and
+ *     unusual embedders that plant a value later see it behave exactly like
+ *     the env read it replaced.
+ *  3. Rotation writes go through {@link setRunnerSecret} (the
+ *     runner-manager/static-renewal token channel that previously wrote
+ *     `process.env.STIGMER_TOKEN` in lockstep with its tokenRef).
+ *  4. {@link runnerSecretsEnvView} adapts the store to the codebase's
+ *     `env: NodeJS.ProcessEnv` injection seams (llm-backend,
+ *     registry-endpoint). The view re-merges secrets over `process.env` —
+ *     it exists for in-process CONFIG READS ONLY and must never be handed
+ *     to a child process env or any spawn options.
+ *
+ * Embedder note: `@stigmer/runner` is a public library, and capture runs
+ * inside the factories, so embedding the runner scrubs the HOST process's
+ * env of runner secrets at boot. That is the point — agent shells run in
+ * the embedder's process — and host code that still needs a value reads it
+ * through this module.
+ */
+
+import { RUNNER_SECRET_ENV_KEYS } from "./runner-credential-keys.js";
+
+const captured = new Map<string, string>();
+let captureRan = false;
+
+/**
+ * Move every {@link RUNNER_SECRET_ENV_KEYS} value out of `process.env` into
+ * the store. Idempotent — only the first call captures, so a late caller
+ * cannot re-freeze values that rotation has since replaced.
+ */
+export function captureRunnerSecrets(): void {
+  if (captureRan) return;
+  captureRan = true;
+  for (const name of RUNNER_SECRET_ENV_KEYS) {
+    const value = process.env[name];
+    if (value !== undefined) {
+      captured.set(name, value);
+      delete process.env[name];
+    }
+  }
+}
+
+/**
+ * Read a runner secret: captured value first, live `process.env` fallback
+ * (see custody rule 2). Returns `undefined` when the secret is absent —
+ * callers own their missing-secret reaction, exactly as with the env reads
+ * this replaces.
+ */
+export function getRunnerSecret(name: string): string | undefined {
+  return captured.get(name) ?? process.env[name];
+}
+
+/**
+ * Write (or with `null`, clear) a runner secret — the rotation channel.
+ * Ensures capture has run first so a rotated value can never sit in
+ * `process.env` because a writer beat the boot capture.
+ */
+export function setRunnerSecret(name: string, value: string | null): void {
+  captureRunnerSecrets();
+  if (value === null) {
+    captured.delete(name);
+  } else {
+    captured.set(name, value);
+  }
+}
+
+/**
+ * `process.env` with the captured secrets merged back over it — an adapter
+ * for the `env: NodeJS.ProcessEnv` injection seams so their defaults stay
+ * secret-aware after the boot scrub.
+ *
+ * IN-PROCESS CONFIG READS ONLY: never pass this to a spawn/exec env, a
+ * worker thread, or anything else that leaves the process — doing so would
+ * reopen exactly the leak the store closes.
+ */
+export function runnerSecretsEnvView(): NodeJS.ProcessEnv {
+  const view: NodeJS.ProcessEnv = { ...process.env };
+  for (const [name, value] of captured) {
+    view[name] = value;
+  }
+  return view;
+}
+
+/**
+ * Test-only: forget everything captured and re-arm capture. Unit tests that
+ * plant secret env vars and boot pieces of the runner need each test to see
+ * its own values.
+ */
+export function resetRunnerSecretsForTests(): void {
+  captured.clear();
+  captureRan = false;
+}

package/src/shared/service-tier.ts

@@ -0,0 +1,78 @@
+/**
+ * Harness-neutral service-tier semantics (stigmer/stigmer#357, extended to
+ * the native harness by #361).
+ *
+ * The platform contract: an execution's price-bearing tier is ALWAYS
+ * explicit by the time a provider request leaves the runner. UNSPECIFIED
+ * resolves to STANDARD here and ONLY here — every upstream layer preserves
+ * the caller's raw enum so "user chose standard" stays distinguishable
+ * from "platform default" all the way to the ledger.
+ *
+ * Each harness owns its translation of the EFFECTIVE tier into provider
+ * wire terms:
+ *   - Cursor: explicit `ModelSelection.params` pinning the price-bearing
+ *     variant booleans (`execute-cursor/service-tier.ts`).
+ *   - Native: the provider's own request parameter, mapped in
+ *     `model-client.ts` (`toOpenAiServiceTier` / `toAnthropicServiceTier`
+ *     below) so no construction site can invent a third mapping.
+ */
+
+import { ServiceTier } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+/**
+ * The effective tier after platform-default resolution: never UNSPECIFIED.
+ */
+export type EffectiveServiceTier = ServiceTier.STANDARD | ServiceTier.FAST;
+
+/**
+ * Resolve the configured tier to its effective value. The single place in
+ * the platform where UNSPECIFIED becomes STANDARD.
+ */
+export function resolveEffectiveServiceTier(
+  configured: ServiceTier | undefined,
+): EffectiveServiceTier {
+  return configured === ServiceTier.FAST ? ServiceTier.FAST : ServiceTier.STANDARD;
+}
+
+/** Human-readable tier label for logs and error messages. */
+export function serviceTierLabel(tier: ServiceTier): string {
+  switch (tier) {
+    case ServiceTier.FAST:
+      return "fast";
+    case ServiceTier.STANDARD:
+      return "standard";
+    default:
+      return "unspecified";
+  }
+}
+
+/**
+ * OpenAI's `service_tier` request parameter for the effective tier.
+ *
+ * STANDARD maps to "default", NOT "auto": "auto" lets the ACCOUNT's
+ * project settings pick the processing tier — the exact
+ * account-default-decides-the-price hole #357 closed on the Cursor
+ * harness. FAST maps to "priority" (pay-as-you-go priority processing);
+ * create-time validation makes FAST unreachable until a registry entry
+ * prices it, so today's traffic always sends "default". "flex" (cheaper,
+ * slower) is a possible future tier, deliberately unmapped.
+ */
+export function toOpenAiServiceTier(tier: EffectiveServiceTier): "default" | "priority" {
+  return tier === ServiceTier.FAST ? "priority" : "default";
+}
+
+/**
+ * Anthropic's `service_tier` request parameter for the effective tier.
+ *
+ * STANDARD maps to "standard_only": never consume priority-tier capacity,
+ * so the bill is the public standard rate regardless of what the account
+ * has purchased. FAST maps to "auto" — Anthropic's priority tier is
+ * PURCHASED capacity, and "auto" means "use it when available"; the
+ * response's `usage.service_tier` reports what actually served, which is
+ * what billing reconciles against. FAST is unreachable until a registry
+ * entry prices it (and the platform buys priority capacity — the #361
+ * half-2 hold).
+ */
+export function toAnthropicServiceTier(tier: EffectiveServiceTier): "auto" | "standard_only" {
+  return tier === ServiceTier.FAST ? "auto" : "standard_only";
+}

package/src/shared/skill-writer.ts

@@ -162,7 +162,7 @@ async function extractZipToWorkspace(
 ): Promise<void> {
   const entries = await extractZipFileEntries(zipBytes);
   for (const entry of entries) {
-    await backend.writeFile(`${targetDir}/${entry.path}`, entry.content);
+    await backend.writeFileBuffer(`${targetDir}/${entry.path}`, Buffer.from(entry.content));
   }
 }
 
@@ -174,7 +174,7 @@ async function extractZipToWorkspaceExcluding(
 ): Promise<void> {
   const entries = await extractZipFileEntries(zipBytes, { exclude: [excludeName] });
   for (const entry of entries) {
-    await backend.writeFile(`${targetDir}/${entry.path}`, entry.content);
+    await backend.writeFileBuffer(`${targetDir}/${entry.path}`, Buffer.from(entry.content));
   }
 }
 

package/src/shared/zip-extract.ts

@@ -1,7 +1,14 @@
 /**
- * Skill-artifact ZIP extraction: text-decoded entries with non-fatal
+ * Skill-artifact ZIP extraction: byte-preserving entries with non-fatal
  * structural failure.
  *
+ * Entries are returned as raw bytes, never decoded: skill artifacts carry
+ * binary assets (images, fonts, archives) alongside text, and a UTF-8
+ * decode/encode round-trip silently corrupts anything that isn't valid
+ * UTF-8 (issue #683). No consumer parses entry content as text — SKILL.md
+ * is excluded from extraction on every path and written from the Skill
+ * spec instead — so there is deliberately no text accessor to misuse.
+ *
  * Structural parsing lives in zip-structure.ts (central-directory-based —
  * see that module's doc for why local-header walks are never acceptable,
  * issue #450). This module owns the skill-artifact *policy* on top of it:
@@ -33,8 +40,8 @@ import { EOCD_MIN_SIZE, parseZipStructure, type ZipStructuralEntry } from "./zip
 export interface ZipFileEntry {
   /** Relative path within the archive (forward-slash separated). */
   readonly path: string;
-  /** Decoded text content of the file. */
-  readonly content: string;
+  /** Raw file bytes, exactly as stored in the archive. */
+  readonly content: Uint8Array;
 }
 
 /**
@@ -91,17 +98,17 @@ function isExcluded(name: string, excludeSet: ReadonlySet<string>): boolean {
 
 // ─── Decompression ───────────────────────────────────────────────────────
 
-async function decompressEntry(entry: ZipStructuralEntry): Promise<string> {
+async function decompressEntry(entry: ZipStructuralEntry): Promise<Uint8Array> {
   if (entry.compressionMethod === 0) {
-    return new TextDecoder().decode(entry.compressedData);
+    return entry.compressedData;
   }
 
   if (entry.compressionMethod === 8) {
-    return new Promise<string>((resolve, reject) => {
+    return new Promise<Uint8Array>((resolve, reject) => {
       const inflate = createInflateRaw();
       const chunks: Buffer[] = [];
       inflate.on("data", (chunk: Buffer) => chunks.push(chunk));
-      inflate.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+      inflate.on("end", () => resolve(Buffer.concat(chunks)));
       inflate.on("error", reject);
       inflate.end(Buffer.from(entry.compressedData));
     });

package/src/workflow-engine/__tests__/golden-execution.test.ts

@@ -523,8 +523,27 @@ describe("Golden Execution — Tier 1d: Advanced Tasks", () => {
 
     await executeDoTasks(model.do, null, state, model, evaluateExpressionBatch, ctx);
 
-    expect(mockCallFunction).toHaveBeenCalledTimes(2);
+    expect(mockCallFunction).toHaveBeenCalledTimes(3);
     expect(state.data.events_emitted).toBe(true);
+
+    // Delivery targets authored in the DSL (oss#530) must reach the
+    // function-call boundary verbatim: the runner's emit activity
+    // discriminates each entry structurally on its webhook/signal key.
+    const deliveryConfig = mockCallFunction.mock.calls[2][1] as Record<string, unknown>;
+    expect(deliveryConfig.delivery).toEqual([
+      {
+        webhook: {
+          url: "https://hooks.acme.com/orders",
+          headers: { "X-Source": "stigmer" },
+        },
+      },
+      {
+        signal: {
+          execution_id: "wfx_shipping_001",
+          signal_name: "order-fulfilled",
+        },
+      },
+    ]);
   });
 
   it("#20 human-input — HITL approval gates with timeout policies", async () => {

package/src/workflow-engine/__tests__/tasks/call-function.test.ts

@@ -208,6 +208,111 @@ describe("CallFunctionTaskBuilder", () => {
   // The config resolver must never pre-evaluate them — the pre-fix
   // behavior substituted the evaluated boolean back into the config and
   // crashed the validate activity with `expr.includes is not a function`.
+  describe("llm on_invalid policy orchestration (#686)", () => {
+    const schemaTaskDef = (extra: Record<string, unknown>): CallFunctionTaskDef => ({
+      kind: "call:function",
+      call: "llm",
+      with: {
+        model: "gpt-4o-mini",
+        prompt: "Classify",
+        response_schema: { type: "object", properties: { answer: { type: "number" } } },
+        ...extra,
+      },
+    });
+
+    const invalidResult = {
+      result: undefined, model: "gpt-4o-mini", provider: "openai",
+      input_tokens: 0, output_tokens: 0, parse_error: "answer: Required",
+    };
+    const validResult = {
+      result: { answer: 42 }, model: "gpt-4o-mini", provider: "openai",
+      input_tokens: 10, output_tokens: 5,
+    };
+
+    it("ON_INVALID_RETRY re-prompts with the validation errors and succeeds", async () => {
+      mockCallFunction
+        .mockResolvedValueOnce(invalidResult)
+        .mockResolvedValueOnce(validResult);
+
+      const builder = new CallFunctionTaskBuilder(
+        "classify", schemaTaskDef({ on_invalid: "ON_INVALID_RETRY", max_retries: 2 }),
+      );
+      const result = await builder.build()(null, createState(), makeCtx());
+
+      expect(result).toMatchObject({ structured: { answer: 42 } });
+      expect(mockCallFunction).toHaveBeenCalledTimes(2);
+      const retryConfig = mockCallFunction.mock.calls[1][1] as Record<string, unknown>;
+      expect(retryConfig.prompt).toContain("Classify");
+      expect(retryConfig.prompt).toContain("answer: Required");
+      expect(retryConfig.prompt).toContain("RETRY");
+    });
+
+    it("ON_INVALID_RETRY exhausts max_retries then fails without a fallback_task", async () => {
+      mockCallFunction.mockResolvedValue(invalidResult);
+
+      const builder = new CallFunctionTaskBuilder(
+        "classify", schemaTaskDef({ on_invalid: "ON_INVALID_RETRY", max_retries: 2 }),
+      );
+
+      await expect(builder.build()(null, createState(), makeCtx()))
+        .rejects.toThrow(/validation failed after 3 attempt\(s\).*answer: Required/);
+      // first attempt + max_retries retries
+      expect(mockCallFunction).toHaveBeenCalledTimes(3);
+    });
+
+    it("ON_INVALID_RETRY defaults max_retries to 1 (proto contract)", async () => {
+      mockCallFunction.mockResolvedValue(invalidResult);
+
+      const builder = new CallFunctionTaskBuilder(
+        "classify", schemaTaskDef({ on_invalid: "ON_INVALID_RETRY" }),
+      );
+
+      await expect(builder.build()(null, createState(), makeCtx())).rejects.toThrow();
+      expect(mockCallFunction).toHaveBeenCalledTimes(2);
+    });
+
+    it("exhausted retries branch to fallback_task when set", async () => {
+      mockCallFunction.mockResolvedValue(invalidResult);
+
+      const builder = new CallFunctionTaskBuilder(
+        "classify",
+        schemaTaskDef({ on_invalid: "ON_INVALID_RETRY", max_retries: 1, fallback_task: "human_review" }),
+      );
+      const result = await builder.build()(null, createState(), makeCtx());
+
+      expect(result).toEqual({
+        __flow_directive__: "human_review",
+        validation_errors: ["answer: Required"],
+      });
+      expect(mockCallFunction).toHaveBeenCalledTimes(2);
+    });
+
+    it("ON_INVALID_FALLBACK branches immediately without retrying", async () => {
+      mockCallFunction.mockResolvedValue(invalidResult);
+
+      const builder = new CallFunctionTaskBuilder(
+        "classify",
+        schemaTaskDef({ on_invalid: "ON_INVALID_FALLBACK", fallback_task: "human_review" }),
+      );
+      const result = await builder.build()(null, createState(), makeCtx());
+
+      expect(result).toMatchObject({ __flow_directive__: "human_review" });
+      expect(mockCallFunction).toHaveBeenCalledTimes(1);
+    });
+
+    it("a parse_error without a soft policy passes through as normal output (activity owns the failure)", async () => {
+      // Default policy: the activity throws LLM_SCHEMA_VALIDATION itself and
+      // never returns parse_error — the engine must not add a second layer.
+      mockCallFunction.mockResolvedValue(validResult);
+
+      const builder = new CallFunctionTaskBuilder("classify", schemaTaskDef({}));
+      const result = await builder.build()(null, createState(), makeCtx());
+
+      expect(result).toMatchObject({ structured: { answer: 42 } });
+      expect(mockCallFunction).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe("deferred expression fields", () => {
     it("passes validate rules[].expression through unresolved while input and message interpolate", async () => {
       mockCallFunction.mockResolvedValue({ valid: true, errors: [] });