@pleri/olam-cli 0.1.201 → 0.1.205

package/dist/agent-stream/question-broker-bridge.js

@@ -0,0 +1,335 @@
+/**
+ * question-broker-bridge.ts — the CLIENT-side `canUseTool` seam for the
+ * mobile-question-inbox (Phase B). The load-bearing universal interceptor:
+ * it sits at the Agent SDK permission boundary, so it covers EVERY runtime
+ * tier (stdio/IPC default, CF Sandbox, in-DO HTTPS) transport-agnostically.
+ *
+ * Flow for an `AskUserQuestion` tool call:
+ *   1. POST {tool_use_id, world/session, payload, nonce} to the broker
+ *      (`POST /v1/questions`, operator bearer). Registration is best-effort
+ *      (Decision #4: only the ANSWER path fails closed) — a broker error here
+ *      simply means we fall through to the local picker.
+ *   2. AWAIT the operator's answer by polling `GET /v1/questions/:id/answer`
+ *      until status flips to 'answered', bounded by an AbortSignal timeout
+ *      (default ~120s, configurable). The SDK already passes an
+ *      `options.signal` that aborts when the whole query() is cancelled; we
+ *      compose BOTH signals so a query abort OR our own timeout ends the wait.
+ *   3. On a matching answer, return `{ behavior: 'allow', updatedInput:<answer>,
+ *      toolUseID }` so the SDK applies the operator's chosen answer as the tool
+ *      input.
+ *   4. On timeout / network-fail / broker-down / **toolUseId mismatch**, return
+ *      a fall-through result that lets the SDK's own AskUserQuestion local
+ *      picker run. A down broker MUST NEVER hang the session (T3 / Decision #6).
+ *
+ * SECURITY GATES implemented here:
+ *
+ *   F2 (T8, client half) — the answer is bound end-to-end to the EXACT
+ *     toolUseId. The await registers under `options.toolUseID`; the broker only
+ *     ever returns the answer for that exact id (`GET /v1/questions/:id/answer`,
+ *     broker half). Before resolving the callback we ADDITIONALLY verify the
+ *     returned `tool_use_id === options.toolUseID` — a defence-in-depth assert
+ *     that rejects ANY cross-question/cross-session answer delivery. A
+ *     mismatched id is treated as a non-answer → local-picker fallback (never
+ *     a silent mis-steer where "delete database" inherits "choose theme").
+ *
+ *   T3 / Decision #6 — a down/slow broker never hangs the session. Every await
+ *     is AbortSignal-bounded; on ANY failure mode the decision is 'ask'
+ *     (fall through to the local picker), so the session is never worse off
+ *     than today.
+ *
+ * Pure-core / impure-shell split (so F2 + the fallback logic are unit-tested
+ * without HTTP or the real SDK):
+ *   - `decideFromBrokerAnswer()` — pure: maps a broker poll result to a typed
+ *     `BridgeDecision`. This is where the F2 toolUseId verification lives.
+ *   - `awaitBrokerAnswer()` — impure: register + poll loop, fetch injected.
+ *   - `makeAskUserQuestionCanUseTool()` — the SDK-shaped factory that maps a
+ *     `BridgeDecision` to a real `PermissionResult`.
+ */
+/**
+ * Pure: map a broker poll response to a `BridgeDecision`, enforcing F2.
+ *
+ * The answer is accepted ONLY when:
+ *   - status === 'answered', AND
+ *   - the returned tool_use_id === the toolUseId WE submitted (F2 client half),
+ *     AND
+ *   - the answer payload is a plain object (usable as `updatedInput`).
+ *
+ * Any other shape → 'ask' with a precise reason (the caller logs it loud so
+ * the inbox can show "fell back to terminal" — never a silent downgrade).
+ *
+ * A `tool_use_id` that does not match is the cross-question race the gate F2
+ * exists to stop: we refuse it and fall through to the local picker rather
+ * than apply an answer meant for a different tool call.
+ */
+export function decideFromBrokerAnswer(submittedToolUseId, poll) {
+    if (poll.status !== 'answered') {
+        return { kind: 'ask', reason: 'not_answered' };
+    }
+    // F2 — the answer MUST be for the exact tool call we registered. A broker
+    // (or a bug, or an attacker who somehow forced a different row) returning a
+    // mismatched id is rejected here: never resolve an await for X with an
+    // answer minted for Y.
+    if (typeof poll.tool_use_id !== 'string' ||
+        poll.tool_use_id !== submittedToolUseId) {
+        return { kind: 'ask', reason: 'tool_use_id_mismatch' };
+    }
+    const answer = poll.answer;
+    if (answer === null || typeof answer !== 'object' || Array.isArray(answer)) {
+        return { kind: 'ask', reason: 'malformed_answer' };
+    }
+    return { kind: 'allow', answer: answer };
+}
+export const DEFAULT_TIMEOUT_MS = 120_000;
+export const DEFAULT_POLL_INTERVAL_MS = 1_000;
+function defaultSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const t = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(t);
+            resolve();
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function defaultNonce() {
+    // crypto.randomUUID is available in Workers, Node ≥16, and modern browsers.
+    // Fall back to a time+random token where it is somehow absent.
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+function defaultOnFallback(info) {
+    // LOUD: every local-picker fallback is surfaced (downgrade-oracle defence /
+    // T11 spirit). The inbox/observability can key on `question.broker_timeout`.
+    // eslint-disable-next-line no-console
+    console.error(JSON.stringify({
+        event: info.reason === 'timeout'
+            ? 'question.broker_timeout'
+            : 'question.broker_fallback',
+        tool_use_id: info.toolUseId,
+        reason: info.reason,
+    }));
+}
+/**
+ * Register the question, then await the operator's answer (bounded by the
+ * AbortSignal/timeout). Returns a `BridgeDecision`.
+ *
+ * Registration is best-effort: a non-2xx register response does NOT abort the
+ * await — we still poll, because another seam (e.g. the cloud observe-tee) may
+ * have registered the same toolUseId. But a hard network failure on register
+ * with no chance of a row existing short-circuits to 'ask' immediately so we
+ * don't burn the full timeout on a guaranteed-empty poll.
+ *
+ * `signal` (from the SDK's `options.signal`) composes with the internal
+ * timeout: whichever fires first ends the await. The session is NEVER hung —
+ * the worst case is `timeoutMs` then a local-picker fallback.
+ */
+export async function awaitBrokerAnswer(input, config) {
+    const fetchImpl = config.fetchImpl ?? globalThis.fetch;
+    const sleep = config.sleepImpl ?? defaultSleep;
+    const nonce = (config.nonceImpl ?? defaultNonce)();
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const pollIntervalMs = config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const onFallback = config.onFallback ?? defaultOnFallback;
+    const base = config.brokerBaseUrl.replace(/\/+$/, '');
+    // Compose the SDK abort signal with our own timeout into one controller.
+    const timeoutController = new AbortController();
+    const composite = timeoutController.signal;
+    const timer = setTimeout(() => timeoutController.abort(), timeoutMs);
+    const forwardAbort = () => timeoutController.abort();
+    if (input.signal) {
+        if (input.signal.aborted)
+            timeoutController.abort();
+        else
+            input.signal.addEventListener('abort', forwardAbort, { once: true });
+    }
+    const finish = (decision) => {
+        clearTimeout(timer);
+        input.signal?.removeEventListener('abort', forwardAbort);
+        if (decision.kind === 'ask') {
+            onFallback({ toolUseId: input.toolUseId, reason: decision.reason });
+        }
+        return decision;
+    };
+    // ── Step 1: register (best-effort). ──────────────────────────────────────
+    try {
+        await fetchImpl(`${base}/v1/questions`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: config.bearer,
+            },
+            body: JSON.stringify({
+                tool_use_id: input.toolUseId,
+                world_id: config.worldId,
+                session_id: config.sessionId,
+                payload: input.payload ?? null,
+                nonce,
+            }),
+            signal: composite,
+        });
+        // We intentionally do NOT branch on the register status: a 429 (flood) or
+        // 403 (not-owned) still leaves us to poll (another seam may own the row),
+        // and the poll's own not_found handling drives the eventual fallback.
+    }
+    catch {
+        // Hard network failure on register: the broker is unreachable. Don't burn
+        // the timeout — fall through to the local picker now.
+        return finish({ kind: 'ask', reason: 'broker_error' });
+    }
+    // ── Step 2: poll for the answer until answered / aborted / timed-out. ─────
+    // world_id scopes the read to the owning world (intra-tenant isolation, F1
+    // read half): the broker rejects a poll whose world_id != the one the
+    // question was registered under. We registered under config.worldId above.
+    const answerUrl = `${base}/v1/questions/${encodeURIComponent(input.toolUseId)}/answer?world_id=${encodeURIComponent(config.worldId)}`;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        if (composite.aborted) {
+            // Distinguish our timeout from an external (query) abort for the reason
+            // string, but both fall through to the local picker.
+            const reason = input.signal?.aborted
+                ? 'broker_error'
+                : 'timeout';
+            return finish({ kind: 'ask', reason });
+        }
+        let poll = null;
+        try {
+            const res = await fetchImpl(answerUrl, {
+                method: 'GET',
+                headers: { Authorization: config.bearer },
+                signal: composite,
+            });
+            if (res.ok) {
+                poll = (await res.json());
+            }
+            // Non-2xx (e.g. 404 not-found before another seam registered, or a
+            // transient 5xx) → keep polling until the deadline; do NOT give up early.
+        }
+        catch {
+            // Transient fetch error mid-poll → keep trying until the deadline.
+            poll = null;
+        }
+        if (poll !== null) {
+            const decision = decideFromBrokerAnswer(input.toolUseId, poll);
+            if (decision.kind === 'allow') {
+                return finish(decision);
+            }
+            // A 'tool_use_id_mismatch' is a hard stop — never apply, fall back now.
+            if (decision.reason === 'tool_use_id_mismatch') {
+                return finish(decision);
+            }
+            // 'not_answered' / 'malformed_answer' → keep polling (still pending).
+        }
+        await sleep(pollIntervalMs, composite);
+    }
+}
+/**
+ * Build the SDK-shaped `canUseTool` callback. It intercepts ONLY
+ * `AskUserQuestion`; every other tool falls through unchanged (allow with the
+ * original input — the bridge is not a general permission gate, it is the
+ * question-answer seam).
+ *
+ * The returned callback matches the SDK `CanUseTool` shape:
+ *   (toolName, input, { signal, toolUseID, … }) => Promise<PermissionResult>
+ *
+ * F2 wiring: the await registers under `options.toolUseID`, and the resolved
+ * `PermissionResult.toolUseID` is set to that same id. The SDK matches the
+ * result back to the originating tool call by id — so a result built for one
+ * toolUseID can never satisfy another.
+ */
+/**
+ * Map a stored broker answer onto the Agent SDK's AskUserQuestion result shape.
+ *
+ * The SDK expects `updatedInput = { questions: <original questions>, answers:
+ * { "<question text>": "<selected label or labels>" } }` (clarifying-questions
+ * contract). The broker stores the operator's selections as the batch
+ * `{ answers: [{ questionId: "q<i>", value: "<label>", index }], toolUseId }`
+ * (or a legacy single value). This pure mapper reconciles the two using the
+ * original tool `input` (which carries the question text + options).
+ *
+ * Pure + exported for unit testing.
+ */
+export function buildAskUserQuestionResult(input, brokerAnswer) {
+    const questions = Array.isArray(input.questions)
+        ? (input.questions)
+        : [];
+    // Normalise the broker answer to a list of { questionId, value, index? } items.
+    let items = [];
+    if (Array.isArray(brokerAnswer)) {
+        items = brokerAnswer;
+    }
+    else if (brokerAnswer != null &&
+        typeof brokerAnswer === 'object' &&
+        Array.isArray(brokerAnswer.answers)) {
+        items = brokerAnswer.answers;
+    }
+    const answers = {};
+    questions.forEach((q, i) => {
+        const qObj = (q ?? {});
+        const text = qObj.question != null ? String(qObj.question) : `q${i}`;
+        const item = items.find((a) => a && a.questionId === `q${i}`);
+        let label;
+        if (item && item.value != null) {
+            label = String(item.value);
+        }
+        else if (i === 0 &&
+            items.length === 0 &&
+            (typeof brokerAnswer === 'string' || typeof brokerAnswer === 'number')) {
+            // Legacy single-value answer applies to the first question.
+            label = String(brokerAnswer);
+        }
+        else {
+            const opts = Array.isArray(qObj.options) ? qObj.options : [];
+            const first = opts[0];
+            label =
+                typeof first === 'string'
+                    ? first
+                    : first && first.label != null
+                        ? String(first.label)
+                        : '';
+        }
+        answers[text] = label;
+    });
+    return { questions, answers };
+}
+export function makeAskUserQuestionCanUseTool(config, deps = {}) {
+    const awaitImpl = deps.awaitImpl ?? awaitBrokerAnswer;
+    return async (toolName, input, options) => {
+        // Only intercept AskUserQuestion; let everything else proceed untouched.
+        if (toolName !== 'AskUserQuestion') {
+            return { behavior: 'allow', toolUseID: options.toolUseID };
+        }
+        const decision = await awaitImpl({
+            toolUseId: options.toolUseID,
+            payload: input,
+            signal: options.signal,
+        }, config);
+        if (decision.kind === 'allow') {
+            // Build the EXACT shape the Agent SDK applies for AskUserQuestion:
+            //   { questions: <original questions>, answers: { "<question text>": "<label>" } }
+            // (per the SDK clarifying-questions contract). The broker stores the
+            // operator's selections as a batch ({answers:[{questionId,value,index}]});
+            // map each back onto its question text using the original `input`. Without
+            // this transform the model can't apply the answer and the session stalls.
+            // toolUseID is echoed so the SDK binds the result to the originating call.
+            return {
+                behavior: 'allow',
+                updatedInput: buildAskUserQuestionResult(input, decision.answer),
+                toolUseID: options.toolUseID,
+            };
+        }
+        // Fall through to the local picker: allow WITHOUT updatedInput ⇒ the SDK
+        // runs AskUserQuestion's own interactive prompt. A down broker never hangs
+        // the session (T3 / Decision #6).
+        return { behavior: 'allow', toolUseID: options.toolUseID };
+    };
+}
+//# sourceMappingURL=question-broker-bridge.js.map

package/dist/agent-stream/sdk-env-merge.demo.js

@@ -0,0 +1,35 @@
+/**
+ * sdk-env-merge.demo.ts — value-signal demo for the 0.3.149 env foot-gun.
+ *
+ * Run: npx tsx packages/intelligence/src/agent-stream/sdk-env-merge.demo.ts
+ * (or `node --import tsx ...`). Prints a before/after showing how many
+ * load-bearing keys a naive bare-literal `Options.env` would strip vs. the
+ * safe merge helper.
+ */
+import { mergeSubprocessEnv, findStrippedEnvKeys, OLAM_LOAD_BEARING_SUBPROCESS_ENV, } from './sdk-env-merge';
+// A realistic supervisor env an olam Claude Code subprocess inherits.
+const inherited = {
+    PATH: '/usr/local/bin:/usr/bin',
+    HOME: '/root',
+    ANTHROPIC_BASE_URL: 'http://127.0.0.1:8787',
+    HOST_CP_URL: 'http://host.docker.internal:3112',
+    HOST_CP_BEARER: 'redacted',
+    AGENT_DRIVER_TOOLS_ENABLED: '1',
+};
+// The mistake: inject ONE var as a bare Options.env literal.
+const naive = { OLAM_QUESTION_BROKER_URL: 'https://broker' };
+const naiveStripped = findStrippedEnvKeys(naive, OLAM_LOAD_BEARING_SUBPROCESS_ENV, inherited);
+// The fix: merge on top of the inherited env.
+const safe = mergeSubprocessEnv(naive, inherited);
+const safeStripped = findStrippedEnvKeys(safe, OLAM_LOAD_BEARING_SUBPROCESS_ENV, inherited);
+/* eslint-disable no-console */
+console.log('SDK 0.3.149 Options.env = REPLACE (not merge). Value signal:');
+console.log(`  inherited load-bearing keys present: ${OLAM_LOAD_BEARING_SUBPROCESS_ENV.filter((k) => typeof inherited[k] === 'string').length}`);
+console.log(`  bare-literal env keys: ${Object.keys(naive).length}`);
+console.log(`  -> bare literal STRIPS ${naiveStripped.length} load-bearing keys: ${naiveStripped.join(', ')}`);
+console.log(`  -> mergeSubprocessEnv STRIPS ${safeStripped.length} keys (env size ${Object.keys(safe).length})`);
+console.log(naiveStripped.length > 0 && safeStripped.length === 0
+    ? 'PASS: helper prevents the silent env-wipe.'
+    : 'FAIL: unexpected result.');
+/* eslint-enable no-console */
+//# sourceMappingURL=sdk-env-merge.demo.js.map

package/dist/agent-stream/sdk-env-merge.js

@@ -0,0 +1,98 @@
+/**
+ * sdk-env-merge.ts — SDK 0.3.149 `Options.env` replace-not-merge guard.
+ *
+ * Finding (claude-agent-sdk-typescript CHANGELOG 0.3.149, late May 2026):
+ *
+ *   "Clarified that `Options.env` REPLACES the subprocess environment rather
+ *    than merging with `process.env`."
+ *
+ * This is a silent foot-gun. Olam's SDK launch options (`buildSdkOptions` in
+ * driver-runner.ts, `buildAskQueryOptions` in cli/src/ask/sdk-client.ts)
+ * deliberately set NO `env` field — they rely on the spawned Claude Code
+ * subprocess inheriting the supervisor's `process.env` (PATH, HOME,
+ * ANTHROPIC_BASE_URL, HOST_CP_URL/BEARER, AGENT_DRIVER_TOOLS_ENABLED, the
+ * vault-routing vars, etc.). See the comment at driver-runner.ts:159-161.
+ *
+ * If a future change ever sets `options.env = { ONE_VAR: 'x' }` to inject a
+ * single variable, the SDK would WIPE the entire inherited environment —
+ * breaking `withCredential` routing, the chunk-poster URL, the bearer auth,
+ * and the tools escape-hatch all at once, with no error (the subprocess just
+ * boots with an empty env and fails downstream in confusing ways).
+ *
+ * This module provides the SAFE way to inject env into SDK Options: always
+ * MERGE on top of `process.env`. Pair it with the audit guard in
+ * `sdk-env-merge.audit.test.ts`, which fails red if any olam Options builder
+ * sets `env` to a non-merged literal.
+ */
+/**
+ * Build a subprocess environment for `Options.env` that MERGES the given
+ * overrides on top of the inherited base env (default `process.env`).
+ *
+ * Because SDK 0.3.149+ treats `Options.env` as a full REPLACEMENT, you must
+ * never pass a bare `{ MY_VAR: 'x' }` literal — that strips PATH/HOME/auth.
+ * This helper guarantees the inherited env survives.
+ *
+ * `undefined` values in `base` (the natural shape of `process.env`) are
+ * dropped, so the result is a clean `Record<string, string>` the SDK accepts.
+ * Overrides win over base on key collision (immutable — a fresh object is
+ * returned; neither input is mutated).
+ *
+ * @param overrides Variables to set/replace on top of the inherited env.
+ * @param base      Inherited env to merge onto. Defaults to `process.env`.
+ */
+export function mergeSubprocessEnv(overrides, base = process.env) {
+    const merged = {};
+    for (const [k, v] of Object.entries(base)) {
+        if (typeof v === 'string')
+            merged[k] = v;
+    }
+    for (const [k, v] of Object.entries(overrides)) {
+        merged[k] = v;
+    }
+    return merged;
+}
+/**
+ * Assert that an SDK Options object's `env` field (if present) is a SAFE
+ * merge — i.e. it preserves the load-bearing inherited keys rather than being
+ * a bare replacement literal. Returns the list of MISSING load-bearing keys
+ * (empty = safe). Use in tests/guards; do not throw from hot paths.
+ *
+ * "Safe" here is intentionally conservative: if `env` is absent, the
+ * subprocess inherits everything → always safe (returns `[]`). If `env` is
+ * present, every key in `requiredKeys` that exists in the inherited base env
+ * MUST also appear in `env`, or it is flagged.
+ *
+ * @param env          The `Options.env` value (or undefined if unset).
+ * @param requiredKeys Inherited keys that MUST survive into the subprocess.
+ * @param base         Inherited env to check against. Defaults to `process.env`.
+ */
+export function findStrippedEnvKeys(env, requiredKeys, base = process.env) {
+    if (env === undefined)
+        return []; // inherit-all → safe
+    const missing = [];
+    for (const key of requiredKeys) {
+        const inheritedHasIt = typeof base[key] === 'string';
+        if (inheritedHasIt && !(key in env))
+            missing.push(key);
+    }
+    return missing;
+}
+/**
+ * The load-bearing env keys an olam Claude Code subprocess depends on. If any
+ * of these is silently stripped by a bare `Options.env` replacement, the
+ * subprocess breaks in a confusing, non-erroring way. Used by the audit guard.
+ */
+export const OLAM_LOAD_BEARING_SUBPROCESS_ENV = [
+    'PATH',
+    'HOME',
+    // Auth / vault routing (see root CLAUDE.md "Outbound Claude API calls").
+    'ANTHROPIC_BASE_URL',
+    'ANTHROPIC_API_KEY',
+    'OLAM_ANTHROPIC_BASE_URL',
+    // Host control-plane wiring read by driver-runner.ts main().
+    'HOST_CP_URL',
+    'HOST_CP_BEARER',
+    // Tools escape-hatch read from the child process (driver-runner.ts:173).
+    'AGENT_DRIVER_TOOLS_ENABLED',
+];
+//# sourceMappingURL=sdk-env-merge.js.map

package/dist/image-digests.json

@@ -1,12 +1,12 @@
 {
-  "auth": "sha256:3f46d206ae15e4cdad15adeaf2e0f0da8367a3292f3c9e80f7e1a12b4d73580b",
-  "devbox": "sha256:0f19fd86fe94556939c668ff987f9daf09a1f266c6bfd79bc283dd728da0487a",
-  "devbox-base": "sha256:f6270555a60ae23f9e5cecbd55aac6dc6cfc6554a176ccb165380f39568b9bf5",
-  "host-cp": "sha256:3c601e4ea81d49e0c494c132dbf34aeffffedf37f9f09d4877b0d3139341bc50",
-  "kg-service": "sha256:47f6a594ef402b92032560afd8e6ed4758223d8c8d09f24ede8eff436dc3a31a",
-  "memory-service": "sha256:6bfa2209ff735728457e155031c526008acd53276f2026ffa95905a301e414bb",
-  "mcp-auth": "sha256:a97684d8d69922d4ce35af45700e15973a7463f088516a4383b6b6022bc37a16",
+  "auth": "sha256:06c9cd39405e650141a78927f1701bf7b06a86cd98eeaef9b22eb53d46f6f523",
+  "devbox": "sha256:467e0da5ce48ce281c9799f52b2efabc2eba2228e4ab807412523bdb00a52917",
+  "devbox-base": "sha256:4fd8d2797b6126778c034e442a8429cbbc2e90f772ff11061bcb317d735d9293",
+  "host-cp": "sha256:501037587e33d0a1c13df88d72ad9b855508e4c0163cb65673211cd3ddd9227b",
+  "kg-service": "sha256:a739f0fdf60aef0d26b51314698a07bba423c3d43571616cffd7b1195abb205d",
+  "memory-service": "sha256:b10649ba9b56bb11b99e5142559d4b8a37a2b8ae2ad8ce38fb8b535449d26f85",
+  "mcp-auth": "sha256:cdeb8813619f0198dbbcc80b2c98dbeb3a842e8d1ec38796d459ad254c5e1d98",
   "$schema_version": 1,
-  "$published_version": "0.1.201",
+  "$published_version": "0.1.205",
   "$registry": "ghcr.io/pleri"
 }