@stigmer/runner 3.10.0 → 3.11.1-dev.20260812192248

package/dist/encryption/config.js

@@ -0,0 +1,108 @@
+/**
+ * Payload-encryption configuration (stigmer-cloud#227, stigmer#398).
+ *
+ * Two key sources, strict precedence:
+ *
+ *   1. Environment (STIGMER_PAYLOAD_ENCRYPTION_KEY(_ID)) — the operator's
+ *      explicit choice: self-hosted deployments sharing one key with their
+ *      server, and cloud sandboxes injected with the platform key. When the
+ *      env key is set, bootstrap-delivered material is ignored entirely.
+ *   2. Bootstrap-delivered — server-managed per-identity keys handed to
+ *      desktop-class runners by getRunnerBootstrapConfig. Held in memory
+ *      only; persistence lives server-side, which is what makes Temporal
+ *      replay work across runner restarts (every boot re-fetches the SAME
+ *      key).
+ *
+ * Encryption is enabled iff a key is present from either source — the same
+ * enabled-iff-configured pattern as the claim-check codec. A malformed key
+ * fails the boot rather than silently running plaintext: an operator who set
+ * the key (or a server that minted one) intended history to be encrypted.
+ *
+ * Key rotation: payloads carry the id of the key that encrypted them.
+ * During a rotation window the previous key stays readable via the
+ * secondary pair while new payloads are written under the primary key.
+ * Workers capture keys at construction, so a rotated bootstrap key lands
+ * on the next runner boot — there is no live re-key.
+ */
+const KEY_ENV = "STIGMER_PAYLOAD_ENCRYPTION_KEY";
+const KEY_ID_ENV = "STIGMER_PAYLOAD_ENCRYPTION_KEY_ID";
+const SECONDARY_KEY_ENV = "STIGMER_PAYLOAD_ENCRYPTION_SECONDARY_KEY";
+const SECONDARY_KEY_ID_ENV = "STIGMER_PAYLOAD_ENCRYPTION_SECONDARY_KEY_ID";
+const AES_256_KEY_BYTES = 32;
+/**
+ * Returns the encryption config, or undefined when encryption is not
+ * configured (the codec is then simply not installed).
+ *
+ * Source precedence: the env key wins outright; bootstrap-delivered
+ * material applies only when no env key is set (see the module doc).
+ *
+ * @throws when a key is present but malformed, or a key id is missing —
+ *   key misconfiguration must stop the boot, not degrade to plaintext.
+ *   This applies equally to bootstrap material: a server that hands out
+ *   a bad key or omits its id has broken the protocol contract, and
+ *   running plaintext against a server that manages keys would silently
+ *   defeat the feature.
+ */
+export function loadPayloadEncryptionConfig(bootstrap) {
+    const rawKey = process.env[KEY_ENV];
+    if (rawKey) {
+        const primary = {
+            keyId: requireKeyId(KEY_ID_ENV),
+            key: parseKey(rawKey, KEY_ENV),
+        };
+        const rawSecondary = process.env[SECONDARY_KEY_ENV];
+        const secondary = rawSecondary
+            ? {
+                keyId: requireKeyId(SECONDARY_KEY_ID_ENV),
+                key: parseKey(rawSecondary, SECONDARY_KEY_ENV),
+            }
+            : undefined;
+        return { primary, secondary };
+    }
+    if (bootstrap?.key) {
+        const primary = {
+            keyId: requireBootstrapKeyId(bootstrap.keyId, "payload_encryption_key_id"),
+            key: parseKey(bootstrap.key, "bootstrap payload_encryption_key"),
+        };
+        const secondary = bootstrap.secondaryKey
+            ? {
+                keyId: requireBootstrapKeyId(bootstrap.secondaryKeyId, "payload_encryption_secondary_key_id"),
+                key: parseKey(bootstrap.secondaryKey, "bootstrap payload_encryption_secondary_key"),
+            }
+            : undefined;
+        return { primary, secondary };
+    }
+    return undefined;
+}
+function requireKeyId(envName) {
+    const keyId = process.env[envName];
+    // An explicit id is required (no default): during rotation two keys
+    // coexist, and payloads must name which one encrypted them.
+    if (!keyId) {
+        throw new Error(`Payload encryption misconfigured: ${envName} is required when the ` +
+            `corresponding key is set`);
+    }
+    return keyId;
+}
+function requireBootstrapKeyId(keyId, fieldName) {
+    if (!keyId) {
+        throw new Error(`Runner bootstrap returned a payload encryption key without its ${fieldName} — ` +
+            `refusing to encrypt under an unidentified key (server contract violation)`);
+    }
+    return keyId;
+}
+function parseKey(rawBase64, envName) {
+    let key;
+    try {
+        key = Buffer.from(rawBase64, "base64");
+    }
+    catch {
+        throw new Error(`Payload encryption misconfigured: ${envName} is not valid base64`);
+    }
+    if (key.length !== AES_256_KEY_BYTES) {
+        throw new Error(`Payload encryption misconfigured: ${envName} must decode to ` +
+            `${AES_256_KEY_BYTES} bytes (AES-256), got ${key.length}`);
+    }
+    return key;
+}
+//# sourceMappingURL=config.js.map

package/dist/encryption/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/encryption/config.ts"],"names":[],"mappings":"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"}

package/dist/encryption/index.d.ts

@@ -0,0 +1,3 @@
+export { EncryptionPayloadCodec } from "./payload-codec.js";
+export { loadPayloadEncryptionConfig } from "./config.js";
+export type { PayloadEncryptionConfig, EncryptionKey } from "./config.js";

package/dist/encryption/index.js

@@ -0,0 +1,3 @@
+export { EncryptionPayloadCodec } from "./payload-codec.js";
+export { loadPayloadEncryptionConfig } from "./config.js";
+//# sourceMappingURL=index.js.map

package/dist/encryption/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/encryption/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC"}

package/dist/encryption/payload-codec.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Temporal PayloadCodec that encrypts payloads at rest in workflow
+ * history (stigmer-cloud#227).
+ *
+ * Why: the workflow engine runs inside the Temporal deterministic
+ * sandbox, so decrypted execution-context values cross the history
+ * boundary in many places — the hydrate activity result, the runtime
+ * env passed as an input to every per-task activity, and expression
+ * results recorded as local-activity markers. Encrypting at the payload
+ * codec layer closes the entire class with one mechanism instead of
+ * chasing each crossing.
+ *
+ * Envelope (cross-SDK contract — the Java decode-only codec in
+ * stigmer-cloud's temporal-starter must match it byte-for-byte, pinned
+ * by the conformance fixture in __tests__/fixtures/):
+ *
+ *   metadata: encoding            = "binary/encrypted"
+ *             encryption-key-id   = <key id that encrypted this payload>
+ *   data:     iv (12 bytes) ‖ AES-256-GCM(ciphertext ‖ tag (16 bytes))
+ *
+ * The plaintext is the serialized ORIGINAL Payload proto (metadata AND
+ * data), so decode restores the payload exactly — including its
+ * original encoding — with no side channel.
+ *
+ * Decode passes through payloads it did not encode. This is what keeps
+ * plaintext signals from the Java/Go orchestrators and pre-rollout
+ * in-flight histories working with zero migration. Everything else
+ * fails closed: unknown key id, missing key id, and ciphertext tampering
+ * all throw rather than surfacing bogus payloads.
+ */
+import type { Payload, PayloadCodec } from "@temporalio/common";
+import type { PayloadEncryptionConfig } from "./config.js";
+export declare class EncryptionPayloadCodec implements PayloadCodec {
+    private readonly config;
+    private readonly decryptKeysById;
+    constructor(config: PayloadEncryptionConfig);
+    encode(payloads: Payload[]): Promise<Payload[]>;
+    decode(payloads: Payload[]): Promise<Payload[]>;
+    private encodePayload;
+    private decodePayload;
+}

package/dist/encryption/payload-codec.js

@@ -0,0 +1,130 @@
+/**
+ * Temporal PayloadCodec that encrypts payloads at rest in workflow
+ * history (stigmer-cloud#227).
+ *
+ * Why: the workflow engine runs inside the Temporal deterministic
+ * sandbox, so decrypted execution-context values cross the history
+ * boundary in many places — the hydrate activity result, the runtime
+ * env passed as an input to every per-task activity, and expression
+ * results recorded as local-activity markers. Encrypting at the payload
+ * codec layer closes the entire class with one mechanism instead of
+ * chasing each crossing.
+ *
+ * Envelope (cross-SDK contract — the Java decode-only codec in
+ * stigmer-cloud's temporal-starter must match it byte-for-byte, pinned
+ * by the conformance fixture in __tests__/fixtures/):
+ *
+ *   metadata: encoding            = "binary/encrypted"
+ *             encryption-key-id   = <key id that encrypted this payload>
+ *   data:     iv (12 bytes) ‖ AES-256-GCM(ciphertext ‖ tag (16 bytes))
+ *
+ * The plaintext is the serialized ORIGINAL Payload proto (metadata AND
+ * data), so decode restores the payload exactly — including its
+ * original encoding — with no side channel.
+ *
+ * Decode passes through payloads it did not encode. This is what keeps
+ * plaintext signals from the Java/Go orchestrators and pre-rollout
+ * in-flight histories working with zero migration. Everything else
+ * fails closed: unknown key id, missing key id, and ciphertext tampering
+ * all throw rather than surfacing bogus payloads.
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+// Default-import + destructure, NOT `import { temporal } from …`:
+// @temporalio/proto is CommonJS and its `temporal` export defeats Node's
+// cjs-module-lexer named-export detection, so the named form loads under
+// tsx/vitest (their interop is looser) but crashes plain `node dist/main.js`
+// at startup with "Named export 'temporal' not found" (stigmer/stigmer#399
+// boot regression). Pinned by scripts/verify-dist-boot.mjs in CI.
+import proto from "@temporalio/proto";
+const { temporal } = proto;
+const ENCODING_METADATA_KEY = "encoding";
+const ENCRYPTED_ENCODING_VALUE = "binary/encrypted";
+const KEY_ID_METADATA_KEY = "encryption-key-id";
+/** AES-GCM parameters shared with the Java implementation. */
+const IV_BYTES = 12;
+const AUTH_TAG_BYTES = 16;
+export class EncryptionPayloadCodec {
+    config;
+    decryptKeysById;
+    constructor(config) {
+        this.config = config;
+        this.decryptKeysById = new Map([[config.primary.keyId, config.primary.key]]);
+        if (config.secondary) {
+            this.decryptKeysById.set(config.secondary.keyId, config.secondary.key);
+        }
+    }
+    async encode(payloads) {
+        return payloads.map((p) => this.encodePayload(p));
+    }
+    async decode(payloads) {
+        return payloads.map((p) => this.decodePayload(p));
+    }
+    encodePayload(payload) {
+        // Data-less payloads (binary/null from void results) stay as-is:
+        // there is nothing to protect, and the cross-language parents that
+        // await our workflows as void must be able to read them without a key.
+        if (!payload.data || payload.data.length === 0) {
+            return payload;
+        }
+        const plaintext = temporal.api.common.v1.Payload.encode(payload).finish();
+        return {
+            metadata: {
+                [ENCODING_METADATA_KEY]: Buffer.from(ENCRYPTED_ENCODING_VALUE),
+                [KEY_ID_METADATA_KEY]: Buffer.from(this.config.primary.keyId),
+            },
+            data: encrypt(plaintext, this.config.primary),
+        };
+    }
+    decodePayload(payload) {
+        if (!isEncryptedPayload(payload)) {
+            return payload;
+        }
+        const keyIdBytes = payload.metadata?.[KEY_ID_METADATA_KEY];
+        if (!keyIdBytes) {
+            throw new Error("Encrypted payload is missing its encryption-key-id metadata — refusing to decode");
+        }
+        const keyId = Buffer.from(keyIdBytes).toString("utf-8");
+        const key = this.decryptKeysById.get(keyId);
+        if (!key) {
+            throw new Error(`Encrypted payload uses unknown key id '${keyId}' — configure it as the ` +
+                `primary or secondary payload encryption key (rotation window?)`);
+        }
+        const plaintext = decrypt(payload.data, key, keyId);
+        return temporal.api.common.v1.Payload.decode(plaintext);
+    }
+}
+function isEncryptedPayload(payload) {
+    const encoding = payload.metadata?.[ENCODING_METADATA_KEY];
+    if (!encoding)
+        return false;
+    return Buffer.from(encoding).toString("utf-8") === ENCRYPTED_ENCODING_VALUE;
+}
+function encrypt(plaintext, key) {
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", key.key, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    // Layout iv ‖ ciphertext ‖ tag matches Java's AES/GCM/NoPadding, whose
+    // doFinal() output is ciphertext ‖ tag.
+    return Buffer.concat([iv, ciphertext, cipher.getAuthTag()]);
+}
+function decrypt(data, key, keyId) {
+    if (data.length < IV_BYTES + AUTH_TAG_BYTES) {
+        throw new Error(`Encrypted payload under key id '${keyId}' is truncated (${data.length} bytes)`);
+    }
+    const buf = Buffer.from(data);
+    const iv = buf.subarray(0, IV_BYTES);
+    const ciphertext = buf.subarray(IV_BYTES, buf.length - AUTH_TAG_BYTES);
+    const tag = buf.subarray(buf.length - AUTH_TAG_BYTES);
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    try {
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    }
+    catch {
+        // GCM auth failure: tampered ciphertext or a key that does not match
+        // its advertised id. Never surface partially decrypted bytes.
+        throw new Error(`Failed to decrypt payload under key id '${keyId}' — ciphertext is ` +
+            `corrupt or the configured key does not match`);
+    }
+}
+//# sourceMappingURL=payload-codec.js.map

package/dist/encryption/payload-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-codec.js","sourceRoot":"","sources":["../../src/encryption/payload-codec.ts"],"names":[],"mappings":"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"}

package/dist/middleware/index.d.ts

@@ -4,6 +4,9 @@
  * Assembles the ordered middleware array from a MiddlewareStackConfig.
  * The composition order matches the Python create_deep_agent injection:
  *
+ *   0. Path normalization (conditional: only on permission-rule-bearing
+ *      graphs — FIRST, so every downstream middleware observes canonical
+ *      workspace-absolute paths)
  *   1. Loop detection (always)
  *   2. Execution budget (always)
  *   3. Tool truncation (always)

package/dist/middleware/index.js

@@ -4,6 +4,9 @@
  * Assembles the ordered middleware array from a MiddlewareStackConfig.
  * The composition order matches the Python create_deep_agent injection:
  *
+ *   0. Path normalization (conditional: only on permission-rule-bearing
+ *      graphs — FIRST, so every downstream middleware observes canonical
+ *      workspace-absolute paths)
  *   1. Loop detection (always)
  *   2. Execution budget (always)
  *   3. Tool truncation (always)
@@ -12,6 +15,7 @@
  *   6. Error hints (always)
  *   7. OTel spans (always, no-op when OTel not configured)
  */
+import { createPathNormalizationMiddleware } from "./path-normalization.js";
 import { createLoopDetectionMiddleware } from "./loop-detection.js";
 import { createExecutionBudgetMiddleware } from "./execution-budget.js";
 import { createToolTruncationMiddleware } from "./tool-truncation.js";
@@ -22,6 +26,9 @@ import { createErrorHintsMiddleware } from "./error-hints.js";
 import { createOtelSpansMiddleware } from "./otel-spans.js";
 export function buildMiddlewareStack(config = {}) {
     const stack = [];
+    if (config.pathNormalization) {
+        stack.push(createPathNormalizationMiddleware(config.pathNormalization));
+    }
     stack.push(createLoopDetectionMiddleware(config.loopDetection));
     stack.push(createExecutionBudgetMiddleware(config.executionBudget));
     stack.push(createToolTruncationMiddleware(config.toolTruncation));

package/dist/middleware/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,+BAA+B,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAA0B,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAY5D,MAAM,UAAU,oBAAoB,CAClC,SAAgC,EAAE;IAElC,MAAM,KAAK,GAAwB,EAAE,CAAC;IAEtC,KAAK,CAAC,IAAI,CAAC,6BAA6B,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;IAEhE,KAAK,CAAC,IAAI,CAAC,+BAA+B,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC;IAEpE,KAAK,CAAC,IAAI,CAAC,8BAA8B,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC;IAElE,MAAM,YAAY,GAAG,4BAA4B,EAAE,CAAC;IACpD,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAEzB,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,4BAA4B,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,iBAAiB,GAAG,uBAAuB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAClE,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAE9B,KAAK,CAAC,IAAI,CAAC,0BAA0B,EAAE,CAAC,CAAC;QACzC,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;QAExD,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,0BAA0B,EAAE,CAAC,CAAC;IACzC,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IAExD,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC5D,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAE,iCAAiC,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,+BAA+B,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAA0B,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAY5D,MAAM,UAAU,oBAAoB,CAClC,SAAgC,EAAE;IAElC,MAAM,KAAK,GAAwB,EAAE,CAAC;IAEtC,IAAI,MAAM,CAAC,iBAAiB,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,iCAAiC,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,6BAA6B,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;IAEhE,KAAK,CAAC,IAAI,CAAC,+BAA+B,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC;IAEpE,KAAK,CAAC,IAAI,CAAC,8BAA8B,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC;IAElE,MAAM,YAAY,GAAG,4BAA4B,EAAE,CAAC;IACpD,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAEzB,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,4BAA4B,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,iBAAiB,GAAG,uBAAuB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAClE,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAE9B,KAAK,CAAC,IAAI,CAAC,0BAA0B,EAAE,CAAC,CAAC;QACzC,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;QAExD,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,0BAA0B,EAAE,CAAC,CAAC;IACzC,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IAExD,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC5D,CAAC"}

package/dist/middleware/path-normalization.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Workspace-relative path normalization for permission-rule-bearing graphs
+ * (issue #429).
+ *
+ * deepagents' permission enforcement canonicalizes tool-call paths BEFORE any
+ * rule or backend runs, and its validation refuses non-absolute paths — on
+ * EVERY filesystem tool call once a graph carries any permission rules, reads
+ * included. Plan mode is the only rule-bearing production configuration
+ * (shared/plan-mode-permissions.ts), so there a workspace-relative path —
+ * the shape the multi-workspace prompt explicitly mandates, and one models
+ * routinely choose in single-workspace sessions — fails with
+ * `path must be absolute` instead of just working, burning tool rounds until
+ * the model adapts by switching to absolute paths.
+ *
+ * This middleware repairs the contract at our own seam: it rewrites
+ * workspace-relative paths on the deepagents built-in filesystem tools to
+ * workspace-absolute before the tool (and therefore enforcement) runs. The
+ * write-deny rule then fires as designed and reads succeed on the first try.
+ * Rule-less (act-mode) graphs never install it — the legacy backend already
+ * resolves relative paths under the workspace root, so act mode keeps a
+ * byte-zero delta.
+ *
+ * Invariant — nothing becomes newly reachable: only paths whose resolution
+ * stays INSIDE the workspace root are rewritten. Escaping relatives (`../x`)
+ * and `~`-carrying paths are left raw so today's validation refusal keeps
+ * speaking (a naive join would resolve `..` away and smuggle an out-of-root
+ * read past validation), and absolute paths pass through byte-untouched.
+ * The middleware converts false errors into correct behavior — never a
+ * refusal into an allowance the rules didn't decide.
+ *
+ * Tool matching is by bare built-in name, the house doctrine (an MCP server
+ * is not expected to shadow a built-in name — see shared/tool-kind.ts); the
+ * rewrite touches only the tool's path-bearing argument, never glob/grep
+ * patterns. Install FIRST in the stack so every downstream middleware
+ * (approval gate, error hints, otel spans) observes canonical paths.
+ */
+import type { StigmerMiddleware } from "./types.js";
+export interface PathNormalizationConfig {
+    /** The workspace root the graph's filesystem backend resolves against. */
+    readonly rootDir: string;
+}
+/**
+ * Rewrite `raw` to its workspace-absolute form, or return undefined when the
+ * value must be left untouched (absolute already, `~`-carrying, or escaping
+ * the workspace root). Exported for direct unit testing of the mapping table.
+ */
+export declare function normalizeWorkspacePathArg(raw: string, rootDir: string): string | undefined;
+/**
+ * Create middleware that normalizes workspace-relative paths on the built-in
+ * filesystem tools before permission enforcement sees them.
+ *
+ * Installed only on graphs that carry filesystem permission rules — derive
+ * the install condition from the same expression that supplies the rules
+ * (setup.ts / compileSubagents) so the rules and their normalization shim
+ * cannot drift apart.
+ */
+export declare function createPathNormalizationMiddleware(config: PathNormalizationConfig): StigmerMiddleware;

package/dist/middleware/path-normalization.js

@@ -0,0 +1,109 @@
+/**
+ * Workspace-relative path normalization for permission-rule-bearing graphs
+ * (issue #429).
+ *
+ * deepagents' permission enforcement canonicalizes tool-call paths BEFORE any
+ * rule or backend runs, and its validation refuses non-absolute paths — on
+ * EVERY filesystem tool call once a graph carries any permission rules, reads
+ * included. Plan mode is the only rule-bearing production configuration
+ * (shared/plan-mode-permissions.ts), so there a workspace-relative path —
+ * the shape the multi-workspace prompt explicitly mandates, and one models
+ * routinely choose in single-workspace sessions — fails with
+ * `path must be absolute` instead of just working, burning tool rounds until
+ * the model adapts by switching to absolute paths.
+ *
+ * This middleware repairs the contract at our own seam: it rewrites
+ * workspace-relative paths on the deepagents built-in filesystem tools to
+ * workspace-absolute before the tool (and therefore enforcement) runs. The
+ * write-deny rule then fires as designed and reads succeed on the first try.
+ * Rule-less (act-mode) graphs never install it — the legacy backend already
+ * resolves relative paths under the workspace root, so act mode keeps a
+ * byte-zero delta.
+ *
+ * Invariant — nothing becomes newly reachable: only paths whose resolution
+ * stays INSIDE the workspace root are rewritten. Escaping relatives (`../x`)
+ * and `~`-carrying paths are left raw so today's validation refusal keeps
+ * speaking (a naive join would resolve `..` away and smuggle an out-of-root
+ * read past validation), and absolute paths pass through byte-untouched.
+ * The middleware converts false errors into correct behavior — never a
+ * refusal into an allowance the rules didn't decide.
+ *
+ * Tool matching is by bare built-in name, the house doctrine (an MCP server
+ * is not expected to shadow a built-in name — see shared/tool-kind.ts); the
+ * rewrite touches only the tool's path-bearing argument, never glob/grep
+ * patterns. Install FIRST in the stack so every downstream middleware
+ * (approval gate, error hints, otel spans) observes canonical paths.
+ */
+import { isAbsolute, relative } from "node:path";
+import { resolveWorkspacePath } from "../shared/file-change.js";
+/**
+ * The path-bearing argument of each deepagents built-in filesystem tool.
+ * `ls`/`glob`/`grep` take a base directory `path` (defaulting to "/" when
+ * omitted — absolute, so untouched here); the file tools take `file_path`.
+ * Confirmed against the installed deepagents' tool definitions.
+ */
+const PATH_ARG_BY_TOOL = new Map([
+    ["ls", "path"],
+    ["glob", "path"],
+    ["grep", "path"],
+    ["read_file", "file_path"],
+    ["write_file", "file_path"],
+    ["edit_file", "file_path"],
+]);
+/**
+ * Rewrite `raw` to its workspace-absolute form, or return undefined when the
+ * value must be left untouched (absolute already, `~`-carrying, or escaping
+ * the workspace root). Exported for direct unit testing of the mapping table.
+ */
+export function normalizeWorkspacePathArg(raw, rootDir) {
+    if (raw.length === 0 || isAbsolute(raw))
+        return undefined;
+    // Upstream validation refuses `~` segments even in absolute paths, so a
+    // rewrite could not make such a call succeed — leave the raw shape (and
+    // therefore the honest refusal) intact.
+    if (raw.split("/").includes("~"))
+        return undefined;
+    const { absolutePath } = resolveWorkspacePath(raw, rootDir, false);
+    // No-new-reachability guard: `join` inside the resolver normalizes `..`
+    // segments away, so an escaping relative would otherwise pass upstream
+    // validation as a clean out-of-root absolute path. Today that shape is
+    // refused; keep it that way.
+    const rel = relative(rootDir, absolutePath);
+    if (rel.startsWith("..") || isAbsolute(rel))
+        return undefined;
+    return absolutePath;
+}
+/**
+ * Create middleware that normalizes workspace-relative paths on the built-in
+ * filesystem tools before permission enforcement sees them.
+ *
+ * Installed only on graphs that carry filesystem permission rules — derive
+ * the install condition from the same expression that supplies the rules
+ * (setup.ts / compileSubagents) so the rules and their normalization shim
+ * cannot drift apart.
+ */
+export function createPathNormalizationMiddleware(config) {
+    const { rootDir } = config;
+    return {
+        name: "PathNormalizationMiddleware",
+        wrapToolCall(request, handler) {
+            const argKey = PATH_ARG_BY_TOOL.get(request.toolCall.name);
+            if (!argKey)
+                return handler(request);
+            const raw = request.toolCall.args[argKey];
+            if (typeof raw !== "string")
+                return handler(request);
+            const normalized = normalizeWorkspacePathArg(raw, rootDir);
+            if (normalized === undefined)
+                return handler(request);
+            return handler({
+                ...request,
+                toolCall: {
+                    ...request.toolCall,
+                    args: { ...request.toolCall.args, [argKey]: normalized },
+                },
+            });
+        },
+    };
+}
+//# sourceMappingURL=path-normalization.js.map

package/dist/middleware/path-normalization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-normalization.js","sourceRoot":"","sources":["../../src/middleware/path-normalization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAGhE;;;;;GAKG;AACH,MAAM,gBAAgB,GAAgC,IAAI,GAAG,CAAC;IAC5D,CAAC,IAAI,EAAE,MAAM,CAAC;IACd,CAAC,MAAM,EAAE,MAAM,CAAC;IAChB,CAAC,MAAM,EAAE,MAAM,CAAC;IAChB,CAAC,WAAW,EAAE,WAAW,CAAC;IAC1B,CAAC,YAAY,EAAE,WAAW,CAAC;IAC3B,CAAC,WAAW,EAAE,WAAW,CAAC;CAC3B,CAAC,CAAC;AAOH;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACvC,GAAW,EACX,OAAe;IAEf,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1D,wEAAwE;IACxE,wEAAwE;IACxE,wCAAwC;IACxC,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAEnD,MAAM,EAAE,YAAY,EAAE,GAAG,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IAEnE,wEAAwE;IACxE,uEAAuE;IACvE,uEAAuE;IACvE,6BAA6B;IAC7B,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAC5C,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAE9D,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iCAAiC,CAC/C,MAA+B;IAE/B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAE3B,OAAO;QACL,IAAI,EAAE,6BAA6B;QAEnC,YAAY,CAAC,OAAO,EAAE,OAAO;YAC3B,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC3D,IAAI,CAAC,MAAM;gBAAE,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;YAErC,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC1C,IAAI,OAAO,GAAG,KAAK,QAAQ;gBAAE,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;YAErD,MAAM,UAAU,GAAG,yBAAyB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC3D,IAAI,UAAU,KAAK,SAAS;gBAAE,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;YAEtD,OAAO,OAAO,CAAC;gBACb,GAAG,OAAO;gBACV,QAAQ,EAAE;oBACR,GAAG,OAAO,CAAC,QAAQ;oBACnB,IAAI,EAAE,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE;iBACzD;aACF,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/middleware/types.d.ts

@@ -83,6 +83,8 @@ export interface OtelSpansConfig {
 }
 import type { ApprovalGateConfig } from "./approval-gate.js";
 export type { ApprovalGateConfig };
+import type { PathNormalizationConfig } from "./path-normalization.js";
+export type { PathNormalizationConfig };
 /**
  * Top-level configuration for buildMiddlewareStack().
  * All sections are optional — the factory applies sensible defaults.
@@ -94,4 +96,10 @@ export interface MiddlewareStackConfig {
     readonly costCap?: CostCapConfig | null;
     readonly otelSpans?: Partial<OtelSpansConfig>;
     readonly approvalGate?: ApprovalGateConfig | null;
+    /**
+     * Workspace-relative path normalization (issue #429). Set iff the graph
+     * carries filesystem permission rules — derive from the same expression
+     * that supplies the rules so the two cannot drift apart.
+     */
+    readonly pathNormalization?: PathNormalizationConfig | null;
 }

package/dist/payload-codecs.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Single assembly point for the worker's payload codec chain, shared by
+ * the standalone runner (runner.ts) and the runner manager
+ * (runner-manager.ts) so the two entrypoints cannot drift.
+ *
+ * Codec order is a correctness property, not a style choice. Temporal
+ * applies codecs in array order on encode and in reverse on decode, so
+ * with [encryption, claimcheck]:
+ *
+ *   encode: encrypt → claim-check   (payloads the claim-check codec
+ *           relocates to object storage are already ciphertext)
+ *   decode: claim-check → decrypt   (restore the blob, then decrypt)
+ */
+import type { PayloadCodec } from "@temporalio/common";
+import type { Config } from "./config.js";
+import type { BootstrapKeyMaterial } from "./encryption/config.js";
+export declare function createPayloadCodecs(config: Config, bootstrapKeys?: BootstrapKeyMaterial): Promise<PayloadCodec[] | undefined>;

package/dist/payload-codecs.js

@@ -0,0 +1,42 @@
+/**
+ * Single assembly point for the worker's payload codec chain, shared by
+ * the standalone runner (runner.ts) and the runner manager
+ * (runner-manager.ts) so the two entrypoints cannot drift.
+ *
+ * Codec order is a correctness property, not a style choice. Temporal
+ * applies codecs in array order on encode and in reverse on decode, so
+ * with [encryption, claimcheck]:
+ *
+ *   encode: encrypt → claim-check   (payloads the claim-check codec
+ *           relocates to object storage are already ciphertext)
+ *   decode: claim-check → decrypt   (restore the blob, then decrypt)
+ */
+export async function createPayloadCodecs(config, bootstrapKeys) {
+    const codecs = [];
+    const { loadPayloadEncryptionConfig, EncryptionPayloadCodec } = await import("./encryption/index.js");
+    // Env-configured keys win outright; server-managed (bootstrap) keys apply
+    // only when the env is silent — see encryption/config.ts for the rationale.
+    const encryptionConfig = loadPayloadEncryptionConfig(bootstrapKeys);
+    if (encryptionConfig) {
+        codecs.push(new EncryptionPayloadCodec(encryptionConfig));
+        const source = process.env.STIGMER_PAYLOAD_ENCRYPTION_KEY ? "env" : "bootstrap";
+        console.log(`[runner] Payload encryption enabled (source=${source}, ` +
+            `key_id=${encryptionConfig.primary.keyId}` +
+            (encryptionConfig.secondary
+                ? `, secondary_key_id=${encryptionConfig.secondary.keyId})`
+                : ")"));
+    }
+    const { loadClaimcheckConfig, ClaimcheckPayloadCodec } = await import("./claimcheck/index.js");
+    const claimcheckConfig = loadClaimcheckConfig();
+    if (claimcheckConfig.enabled) {
+        const { loadArtifactStorageConfig, createArtifactStorage } = await import("./shared/artifact-storage.js");
+        const storageConfig = loadArtifactStorageConfig(config);
+        const storage = createArtifactStorage(storageConfig);
+        codecs.push(new ClaimcheckPayloadCodec(storage, claimcheckConfig));
+        console.log(`[runner] Claimcheck enabled (threshold=${claimcheckConfig.thresholdBytes}B, ` +
+            `compression=${claimcheckConfig.compressionEnabled}, ` +
+            `storage=${storageConfig.type})`);
+    }
+    return codecs.length > 0 ? codecs : undefined;
+}
+//# sourceMappingURL=payload-codecs.js.map

package/dist/payload-codecs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-codecs.js","sourceRoot":"","sources":["../src/payload-codecs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAc,EACd,aAAoC;IAEpC,MAAM,MAAM,GAAmB,EAAE,CAAC;IAElC,MAAM,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,GAAG,MAAM,MAAM,CAC1E,uBAAuB,CACxB,CAAC;IACF,0EAA0E;IAC1E,4EAA4E;IAC5E,MAAM,gBAAgB,GAAG,2BAA2B,CAAC,aAAa,CAAC,CAAC;IACpE,IAAI,gBAAgB,EAAE,CAAC;QACrB,MAAM,CAAC,IAAI,CAAC,IAAI,sBAAsB,CAAC,gBAAgB,CAAC,CAAC,CAAC;QAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC;QAChF,OAAO,CAAC,GAAG,CACT,+CAA+C,MAAM,IAAI;YACvD,UAAU,gBAAgB,CAAC,OAAO,CAAC,KAAK,EAAE;YAC1C,CAAC,gBAAgB,CAAC,SAAS;gBACzB,CAAC,CAAC,sBAAsB,gBAAgB,CAAC,SAAS,CAAC,KAAK,GAAG;gBAC3D,CAAC,CAAC,GAAG,CAAC,CACX,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,GAAG,MAAM,MAAM,CACnE,uBAAuB,CACxB,CAAC;IACF,MAAM,gBAAgB,GAAG,oBAAoB,EAAE,CAAC;IAChD,IAAI,gBAAgB,CAAC,OAAO,EAAE,CAAC;QAC7B,MAAM,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,GAAG,MAAM,MAAM,CACvE,8BAA8B,CAC/B,CAAC;QACF,MAAM,aAAa,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,qBAAqB,CAAC,aAAa,CAAC,CAAC;QACrD,MAAM,CAAC,IAAI,CAAC,IAAI,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC;QACnE,OAAO,CAAC,GAAG,CACT,0CAA0C,gBAAgB,CAAC,cAAc,KAAK;YAC5E,eAAe,gBAAgB,CAAC,kBAAkB,IAAI;YACtD,WAAW,aAAa,CAAC,IAAI,GAAG,CACnC,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAChD,CAAC"}