@stigmer/runner 3.12.2 → 3.12.4

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: [] });

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

@@ -162,26 +162,87 @@ export class CallFunctionTaskBuilder implements TaskBuilder {
       const executionId =
         (state.env.__stigmer_execution_id as string | undefined) || undefined;
 
-      const result = await ctx.callFunction(
-        callType,
-        resolved,
-        state.env,
-        {
-          workflowExecutionId: executionId,
-        },
-      );
+      const fnMeta = { workflowExecutionId: executionId };
 
       if (callType === "llm") {
-        return normalizeLlmOutput(
-          result as LlmActivityResult,
-          !!resolved.response_schema,
-        );
+        return this.executeLlmCall(resolved, state.env, fnMeta, ctx);
       }
 
-      return result;
+      return ctx.callFunction(callType, resolved, state.env, fnMeta);
     };
   }
 
+  /**
+   * Executes a `call: llm` with schema-validation policy orchestration —
+   * the llm twin of call-agent's output-contract loop (#686).
+   *
+   * With ON_INVALID_RETRY / ON_INVALID_FALLBACK the activity reports a
+   * validation miss as a `parse_error` result instead of throwing; each
+   * retry is its own activity invocation (visible in Temporal history)
+   * re-prompting with the validation errors so the model can self-correct.
+   * Exhausted retries (or immediate FALLBACK) branch to `fallback_task`
+   * via the engine's flow directive; without one, the task fails — the
+   * proto contract. ON_INVALID_FAIL (default) keeps the activity's
+   * throwing path: one attempt, LLM_SCHEMA_VALIDATION on miss.
+   */
+  private async executeLlmCall(
+    resolved: Record<string, unknown>,
+    env: Record<string, unknown>,
+    fnMeta: { workflowExecutionId?: string },
+    ctx: Parameters<TaskExecutorFn>[2],
+  ): Promise<unknown> {
+    const hasSchema = !!resolved.response_schema;
+    const onInvalid = (resolved.on_invalid as string | undefined) ?? "ON_INVALID_FAIL";
+    const softHandling =
+      hasSchema && (onInvalid === "ON_INVALID_RETRY" || onInvalid === "ON_INVALID_FALLBACK");
+
+    // Proto: max_retries "Default: 1", meaningful only for ON_INVALID_RETRY.
+    const maxRetries =
+      onInvalid === "ON_INVALID_RETRY" ? (resolved.max_retries as number | undefined) ?? 1 : 0;
+
+    let attempts = 0;
+    let lastParseError = "";
+
+    do {
+      const attemptConfig =
+        attempts === 0
+          ? resolved
+          : {
+              ...resolved,
+              prompt:
+                `${resolved.prompt}\n\n[RETRY — Your previous response did not match ` +
+                `the required output schema. Validation errors: ${lastParseError}. ` +
+                `Please ensure your response strictly matches the JSON schema provided.]`,
+            };
+
+      const result = (await ctx.callFunction(
+        "llm",
+        attemptConfig,
+        env,
+        fnMeta,
+      )) as LlmActivityResult;
+
+      if (!softHandling || !result.parse_error) {
+        return normalizeLlmOutput(result, hasSchema);
+      }
+
+      lastParseError = result.parse_error;
+      attempts++;
+    } while (onInvalid === "ON_INVALID_RETRY" && attempts <= maxRetries);
+
+    if (typeof resolved.fallback_task === "string" && resolved.fallback_task !== "") {
+      return {
+        __flow_directive__: resolved.fallback_task,
+        validation_errors: [lastParseError],
+      };
+    }
+
+    throw new Error(
+      `LLM output validation failed after ${attempts} attempt(s) ` +
+      `for task '${this.taskName}': ${lastParseError}`,
+    );
+  }
+
   async shouldRun(): Promise<boolean> {
     return true;
   }

package/src/workflow-engine/types.ts

@@ -336,6 +336,12 @@ export interface HttpCallConfig {
   readonly query?: Record<string, string>;
   readonly output?: string;
   readonly redirect?: string;
+  /**
+   * Request timeout in seconds (proto: HttpCallTaskConfig.timeout_seconds,
+   * 1-300). Aborts the request and fails the task with HTTP_CALL_TIMEOUT;
+   * the engine also widens the activity's startToClose to fit it (#686).
+   */
+  readonly timeout_seconds?: number;
 }
 
 export type EndpointDef = string | { readonly uri: string; readonly authentication?: Record<string, unknown> };

package/src/workflows/engine-core.ts

@@ -67,17 +67,44 @@ const evalProxy = proxyLocalActivities<EvalActivities>({
   startToCloseTimeout: "10s",
 });
 
+const CALL_PROXY_RETRY = {
+  maximumAttempts: 5,
+  initialInterval: "1s",
+  backoffCoefficient: 2,
+  maximumInterval: "1m",
+} as const;
+
 const callProxy = proxyActivities<HttpActivities & GrpcActivities & FunctionActivities>({
   startToCloseTimeout: "5m",
   heartbeatTimeout: "30s",
-  retry: {
-    maximumAttempts: 5,
-    initialInterval: "1s",
-    backoffCoefficient: 2,
-    maximumInterval: "1m",
-  },
+  retry: CALL_PROXY_RETRY,
 });
 
+/**
+ * Task-config timeouts (llm_call.timeout ≤600s, http_call.timeout_seconds
+ * ≤300s) can exceed or crowd the default 5m startToClose, which would kill
+ * the activity before its own well-typed LLM_TIMEOUT / HTTP_CALL_TIMEOUT
+ * failure fires. When a task declares a budget, proxy its call with
+ * startToClose = budget + 30s so the in-activity bound always wins (#686).
+ *
+ * proxyActivities in workflow code is a deterministic proxy construction
+ * (no Temporal commands); the memo just avoids rebuilding per call.
+ */
+const timeoutAwareProxies = new Map<number, typeof callProxy>();
+function callProxyFor(timeoutSeconds: number | undefined): typeof callProxy {
+  if (!timeoutSeconds || !Number.isFinite(timeoutSeconds)) return callProxy;
+  let proxy = timeoutAwareProxies.get(timeoutSeconds);
+  if (!proxy) {
+    proxy = proxyActivities<HttpActivities & GrpcActivities & FunctionActivities>({
+      startToCloseTimeout: `${timeoutSeconds + 30}s`,
+      heartbeatTimeout: "30s",
+      retry: CALL_PROXY_RETRY,
+    });
+    timeoutAwareProxies.set(timeoutSeconds, proxy);
+  }
+  return proxy;
+}
+
 const runProxy = proxyActivities<RunActivities>({
   startToCloseTimeout: "5m",
   heartbeatTimeout: "30s",
@@ -240,7 +267,7 @@ export async function runWorkflowEngine(
     runWorkflow: (config: RunWorkflowExecutionConfig) => orchestrateRunWorkflow(config),
     awaitHumanInput: (config: HumanInputExecutionConfig) => orchestrateHumanInput(config),
     callHttp: (config: HttpCallConfig, runtimeEnv: Record<string, unknown>) =>
-      callProxy.CallHttp(config, runtimeEnv),
+      callProxyFor(config.timeout_seconds).CallHttp(config, runtimeEnv),
     callGrpc: (config: GrpcCallConfig, runtimeEnv: Record<string, unknown>) =>
       callProxy.CallGrpc(config, runtimeEnv),
     callFunction: (
@@ -249,7 +276,11 @@ export async function runWorkflowEngine(
       runtimeEnv: Record<string, unknown>,
       fnMeta: CallFunctionMetadata,
     ) =>
-      callProxy.CallFunction(
+      callProxyFor(
+        call === "llm" && typeof config.timeout === "number"
+          ? config.timeout
+          : undefined,
+      ).CallFunction(
         call,
         config,
         runtimeEnv,