@intentface/latch-core 0.11.0 → 0.13.0

package/dist/runtime.js

@@ -504,6 +504,23 @@ function fireAndForget(fn) {
  */
 /** Keys whose values are masked when a non-`Error` throw is serialized. */
 const SECRETISH_KEY = /token|secret|password|authorization|cookie|api[-_]?key|credential/i;
+/** The last `error` chunk's text in a UI message stream body (SSE `data:` lines), if any. */
+function lastStreamError(body) {
+    let error;
+    for (const line of body.split("\n")) {
+        if (!line.startsWith("data: "))
+            continue;
+        try {
+            const chunk = JSON.parse(line.slice(6));
+            if (chunk.type === "error" && chunk.errorText)
+                error = chunk.errorText;
+        }
+        catch {
+            // "[DONE]" and other non-JSON lines
+        }
+    }
+    return error;
+}
 export function clientErrorMessage(error) {
     const message = error instanceof Error ? error.message.trim() : "";
     if (message)
@@ -554,13 +571,15 @@ export function createRuntime(config) {
             "Implement openTurn — see the StorageAdapter contract.");
     }
     /** Resolve an agent's per-request config + a display model id. */
-    async function resolveAgentConfig(agentName, principal, request, turnContext) {
+    async function resolveAgentConfig(agentName, principal, request, turnContext, 
+    /** Passed through to `dynamicAgents.resolve` (see DynamicAgentResolveContext). */
+    resolveCtx) {
         const runtimeCtx = await config.context.build({ principal, request, turnContext });
         // Code-declared agents first; otherwise a dynamic (e.g. DB-stored) agent.
         const factory = config.agents[agentName];
         const cfg = factory
             ? await factory({ context: runtimeCtx, principal, turnContext })
-            : await config.dynamicAgents?.resolve(agentName, principal);
+            : await config.dynamicAgents?.resolve(agentName, principal, resolveCtx);
         if (!cfg)
             throw new Error(`Unknown agent: ${agentName}`);
         const modelId = typeof cfg.model === "string"
@@ -576,7 +595,16 @@ export function createRuntime(config) {
      * server-side (resume).
      */
     async function buildTurn(args) {
-        const { resolvedChatId, principal, modelId, cfg, run, lease, runtimeCtx } = args;
+        const { resolvedChatId, principal, run, lease, runtimeCtx } = args;
+        // A per-turn model override replaces the agent's own, and the telemetry id
+        // with it — a run row that says the agent's model while a different one
+        // answered makes every later comparison a lie.
+        const cfg = args.model ? { ...args.cfg, model: args.model } : args.cfg;
+        const modelId = args.model
+            ? typeof args.model === "string"
+                ? args.model
+                : (args.model.modelId ?? "unknown")
+            : args.modelId;
         // Mutable: the start moments below may inject, replace or rewrite history
         // before the model runs. From here on this is the turn's transcript.
         let uiMessages = args.uiMessages;
@@ -777,7 +805,8 @@ export function createRuntime(config) {
         // append the provider's compiled-index block to the instructions. A
         // provider failure degrades to a turn without memory, never a dead turn.
         let instructions = cfg.instructions;
-        if (cfg.memory && config.memory) {
+        const memoryOn = args.memory ?? true;
+        if (memoryOn && cfg.memory && config.memory) {
             const memArgs = { principal, agent: run.agent, memory: cfg.memory };
             try {
                 // Resolve both hooks BEFORE mutating the toolset, so a failure in
@@ -890,7 +919,13 @@ export function createRuntime(config) {
                         depth: depth + 1,
                         autoApprove,
                         blockGated,
+                        // Memory off stays off down the tree: an eval turn's delegate must
+                        // not recall earlier inputs or save new memory either.
+                        ...(memoryOn ? {} : { memory: false }),
                         onProgress,
+                        // Who is delegating — persisted on the sub-thread so every later
+                        // resolve of it can be shaped per parent (DynamicAgentResolveContext).
+                        parentAgent: run.agent,
                         // Telemetry linkage: this turn is the parent; carry the root chat
                         // down so the subagent's trace nests under this conversation.
                         parentRunId: run.id,
@@ -963,18 +998,36 @@ export function createRuntime(config) {
             // Test runs: stub the approval-gated (mutating) tools so a trial has no
             // real side effects. Gated set = connection defaults + the agent's policy.
             if (blockGated) {
+                /**
+                 * Does this approval value actually gate the tool?
+                 *
+                 * NOT a truthiness check. The SDK spells a waiver as the STRING
+                 * `"not-applicable"` — which is truthy — so `if (v)` treated every
+                 * tool an agent had explicitly waived as gated and stubbed it. On an
+                 * agent whose reads are waived to override a connection default, that
+                 * is every read tool: the agent could not retrieve anything, and an
+                 * eval run measured a model with no access to its own corpus.
+                 *
+                 * Gated: `true`, `"user-approval"`, an object (approval with a
+                 * reason), a function. Waived: `false`, `undefined`,
+                 * `"not-applicable"`.
+                 */
+                const gatedBy = (v) => v === true ||
+                    v === "user-approval" ||
+                    typeof v === "function" ||
+                    (typeof v === "object" && v !== null);
                 const gated = new Set();
                 for (const [k, v] of Object.entries(harnessApproval))
-                    if (v)
+                    if (gatedBy(v))
                         gated.add(k);
                 for (const o of opened) {
                     for (const [k, v] of Object.entries(o.toolApproval ?? {}))
-                        if (v)
+                        if (gatedBy(v))
                             gated.add(k);
                 }
                 if (cfg.toolApproval && typeof cfg.toolApproval !== "function") {
                     for (const [k, v] of Object.entries(cfg.toolApproval)) {
-                        if (v)
+                        if (gatedBy(v))
                             gated.add(k);
                         else
                             gated.delete(k);
@@ -992,12 +1045,19 @@ export function createRuntime(config) {
                     if (t && typeof t.execute === "function") {
                         tools[name] = {
                             ...t,
-                            execute: async (input) => ({
-                                __blocked: true,
-                                tool: name,
-                                input,
-                                reason: "approval-gated tool blocked during test run (no real side effects)",
-                            }),
+                            execute: async (input) => blockGated === "simulate-success"
+                                ? {
+                                    ok: true,
+                                    __stubbed: true,
+                                    tool: name,
+                                    input,
+                                }
+                                : {
+                                    __blocked: true,
+                                    tool: name,
+                                    input,
+                                    reason: "approval-gated tool blocked during test run (no real side effects)",
+                                },
                         };
                     }
                 }
@@ -1130,7 +1190,7 @@ export function createRuntime(config) {
             : config.resolvePromptCaching
                 ? config.resolvePromptCaching(modelId, {
                     agent: run.agent,
-                    memoryScoped: !!(cfg.memory && config.memory),
+                    memoryScoped: !!(memoryOn && cfg.memory && config.memory),
                     principal,
                 })
                 : // No hook → caching is ON by default for first-party Anthropic /
@@ -1860,7 +1920,10 @@ export function createRuntime(config) {
             });
         }
         const resolvedChatId = chat.id;
-        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(agentName, principal, request, turnContext);
+        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(agentName, principal, request, turnContext, 
+        // A host may continue a subagent thread through the chat surface; keep
+        // resolving it the way its spawner would.
+        { parentAgent: chat.parentAgent });
         const prior = await storage.loadMessages(principal, resolvedChatId);
         // A new message while the last turn is parked on an approval is itself the
         // decision: the user declined to answer and wants to steer elsewhere. Close
@@ -1902,11 +1965,38 @@ export function createRuntime(config) {
             return null;
         // System op (no request): rebuild the principal from the run's identity blob.
         const principal = await reconstructPrincipal(run.identity);
-        const uiMessages = await storage.loadMessages(principal, run.chatId);
         const lease = {
             owner: dur.instanceId,
             fencingToken: run.fencingToken ?? 1,
         };
+        if (principal === null) {
+            // Refused (see `ReconstructPrincipal`): the identity may no longer act, so
+            // nothing below — not even reading its history — runs as it. End the run
+            // instead of returning early with the lease held: an `active` row would be
+            // reaped and re-refused every tick until `maxAttempts`, and a throw here
+            // would abort the rest of `sweep`'s loop. No `onRunFinished`: its meta
+            // carries the principal, and there is none to report.
+            const error = "principal rejected: reconstructPrincipal refused the run's identity";
+            await storage.updateRun(run.id, {
+                status: "errored",
+                error,
+                endedAt: Date.now(),
+                // Terminal, so give up the reclaim just taken. `reclaimRun` matches
+                // any non-completed row whose lease has lapsed, so a lease left to
+                // expire would let a direct `resume()` re-claim and re-refuse it,
+                // spending an attempt each time.
+                leaseOwner: null,
+                leaseExpiresAt: null,
+            }, lease);
+            console.warn(`[resume] run ${run.id} (${run.agent}): ${error}`);
+            const settled = await storage.getRun(runId);
+            return {
+                runId,
+                status: settled?.status ?? "errored",
+                attempt: settled?.attempt ?? run.attempt ?? null,
+            };
+        }
+        const uiMessages = await storage.loadMessages(principal, run.chatId);
         // What does this run actually need? A crash between the last step's
         // checkpoint and `onFinish`'s `updateRun` leaves a FINISHED turn on an
         // `active` row, and re-running the model there would pay twice for an answer
@@ -2001,7 +2091,12 @@ export function createRuntime(config) {
         // reconcilable even if its (dynamic, DB-stored) agent was since deleted.
         // Before this ordering that throw also aborted `sweep`'s loop, so one such
         // run held up recovery for every other run until its attempts ran out.
-        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(run.agent, principal);
+        // A recovered subagent run must resolve exactly as its spawner shaped it —
+        // crash recovery and `sweep` both land here.
+        const chat = await storage.getChat(principal, run.chatId);
+        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(run.agent, principal, undefined, undefined, {
+            parentAgent: chat?.parentAgent,
+        });
         // A resume was admitted when the turn first ran — never refuse it (the
         // half-done work would strand), but its tokens still settle against the
         // same counters, and the mid-turn stop still applies.
@@ -2046,16 +2141,31 @@ export function createRuntime(config) {
             // Give up on poison runs that keep dying — don't loop forever.
             if ((run.attempt ?? 1) >= maxAttempts)
                 continue;
-            const outcome = await resumeRun(run.id);
-            if (outcome)
-                resumed.push(outcome);
+            // One run's failure must not strand the rest of the batch. The reaper
+            // flipped EVERY run here to `errored` in one write, and no later reap
+            // selects an `errored` row — so an escaping throw (a transient
+            // `reconstructPrincipal` failure, a storage blip) would leave each run
+            // after it unrecovered for good. A throw AFTER the reclaim (the hook,
+            // history, the turn) leaves that run `active` under a lease, so it is
+            // reaped and retried once the lease lapses, spending an attempt like any
+            // other failed resume. A throw FROM the reclaim itself leaves the run as
+            // the reaper left it — `errored`, not auto-retried — which is today's
+            // outcome for that run too; only its neighbours are new to recovery.
+            try {
+                const outcome = await resumeRun(run.id);
+                if (outcome)
+                    resumed.push(outcome);
+            }
+            catch (e) {
+                console.error(`[resume] run ${run.id} (${run.agent}) failed; continuing the sweep:`, e);
+            }
         }
         return { reaped, resumed };
     }
     async function cron(opts) {
         const errors = [];
         const describe = (e) => (e instanceof Error ? e.message : String(e));
-        let due = { fired: 0, errors: 0, skipped: 0, parked: 0 };
+        let due = { fired: 0, errors: 0, skipped: 0, parked: 0, rejected: 0 };
         try {
             due = await runDue({ now: opts?.now });
         }
@@ -2150,7 +2260,7 @@ export function createRuntime(config) {
         if (hasPendingApproval(messages)) {
             return new Response(null, { status: 200 });
         }
-        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(chat.agent, principal, request, turnContext);
+        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(chat.agent, principal, request, turnContext, { parentAgent: chat.parentAgent });
         const admitted = await admitContinuation(principal, chat.agent, "decision");
         const { run, lease } = await openRun(principal, chatId, chat.agent, cfg.configVersion);
         return buildTurn({
@@ -2198,7 +2308,7 @@ export function createRuntime(config) {
             await storage.appendMessages(chatId, changed);
             return new Response(null, { status: 200 });
         }
-        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(chat.agent, principal, request, turnContext);
+        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(chat.agent, principal, request, turnContext, { parentAgent: chat.parentAgent });
         const admitted = await admitContinuation(principal, chat.agent, "decision");
         // The result is persisted WITH the run (atomically where the adapter can):
         // a busy chat refuses before anything is recorded, so the retry finds the
@@ -2244,7 +2354,7 @@ export function createRuntime(config) {
         if (hasPendingApproval(live) || hasPendingToolResult([live[live.length - 1]])) {
             throw new PendingApprovalError("This chat is awaiting a decision — resolve the pending request before compacting.");
         }
-        const { cfg, modelId } = await resolveAgentConfig(chat.agent, principal, request, turnContext);
+        const { cfg, modelId } = await resolveAgentConfig(chat.agent, principal, request, turnContext, { parentAgent: chat.parentAgent });
         // Tool definitions only affect how a recorded tool RESULT is rendered for the
         // model (`toModelOutput`); an unknown tool falls back to its raw JSON rather
         // than failing. So take every definition available without I/O — the agent's
@@ -2377,11 +2487,14 @@ export function createRuntime(config) {
         return chat ? run : null;
     }
     /** A fresh user message from plain text (for cron-fired turns). */
-    function userMessageOf(text) {
+    function userMessageOf(text, files) {
         return {
             id: generateMessageId(),
             role: "user",
-            parts: [{ type: "text", text }],
+            parts: [
+                ...(files ?? []).map((f) => ({ type: "file", url: f.url, mediaType: f.mediaType, ...(f.filename ? { filename: f.filename } : {}) })),
+                { type: "text", text },
+            ],
             metadata: { visibility: "user", createdAt: Date.now() },
         };
     }
@@ -2443,8 +2556,15 @@ export function createRuntime(config) {
                 // Runtime-created thread: stamp it internal so a host filtering its
                 // chat list on kind never shows it (see ChatRecord.kind).
                 kind: "internal",
+                ...(o.parentAgent ? { parentAgent: o.parentAgent } : {}),
             });
         }
+        // A spawn may only continue a thread its own agent delegated. Otherwise
+        // agent B could pass agent A's sub-thread id and have the child resolved
+        // under A — borrowing whatever a host grants A's subagents.
+        if (o.parentAgent && chat.parentAgent && chat.parentAgent !== o.parentAgent) {
+            throw new Error(`Thread ${chatId} was delegated by another agent; omit threadId to start a new one.`);
+        }
         const prior = await storage.loadMessages(o.principal, chatId);
         // Same rule as handleChat: a new message while the thread is parked on an
         // approval IS the decision — close the stale gate as declined (persisted)
@@ -2461,7 +2581,14 @@ export function createRuntime(config) {
         // the run first, persist the message only once it is ours to run.
         const admitted = await admitTurn(o.principal, o.agent, o.trigger);
         const { cfg, modelId, runtimeCtx, run, lease } = await withReservation(admitted, async () => {
-            const resolved = await resolveAgentConfig(o.agent, o.principal, undefined, o.turnContext);
+            const resolved = await resolveAgentConfig(o.agent, o.principal, undefined, o.turnContext, {
+                // A continued thread keeps the parent it was created under (a mismatch
+                // was refused above). Without a stored one — an adapter that doesn't
+                // persist the column — the spawner of THIS turn is the parent: a host
+                // that restricts a subagent by its parent must never see none.
+                parentAgent: chat.parentAgent ?? o.parentAgent,
+                autoApprove: o.autoApprove,
+            });
             const opened = await openTurn(o.principal, chatId, o.agent, [o.message], resolved.cfg.configVersion);
             return { ...resolved, ...opened };
         });
@@ -2478,6 +2605,8 @@ export function createRuntime(config) {
             admitted,
             autoApprove: o.autoApprove,
             blockGated: o.blockGated,
+            memory: o.memory,
+            model: o.model,
             promptCaching: o.promptCaching,
             depth: o.depth ?? 0,
             parentRunId: o.parentRunId,
@@ -2506,7 +2635,9 @@ export function createRuntime(config) {
                 }
                 : undefined,
         });
-        await res.text();
+        // The turn's own failure travels as an `error` chunk — the stream, not a
+        // throw. Keep its text: without it a failed turn reads as a silent one.
+        const error = lastStreamError(await res.text());
         const after = await storage.loadMessages(o.principal, chatId);
         // The verdict is about THIS turn, so read the FINAL message only (the same
         // rule hasPendingApproval applies): an undecided gate in an older message
@@ -2521,6 +2652,7 @@ export function createRuntime(config) {
             answer: pending.length > 0 ? "" : lastAssistantText(after),
             parked,
             ...(pending.length > 0 ? { pending } : {}),
+            ...(error ? { error } : {}),
         };
     }
     /**
@@ -2546,7 +2678,10 @@ export function createRuntime(config) {
         // Another gated call in the same sub step still undecided → can't finish.
         if (hasPendingApproval(subMessages))
             return { answer: "" };
-        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(subChat.agent, principal);
+        const { cfg, modelId, runtimeCtx } = await resolveAgentConfig(subChat.agent, principal, undefined, undefined, 
+        // Same shaping as the first sub-turn: the parent is read off the persisted
+        // sub-thread, and this path is only ever reached by a human decision.
+        { parentAgent: subChat.parentAgent, autoApprove: false });
         const admitted = await admitContinuation(principal, subChat.agent, "decision");
         const { run, lease } = await openRun(principal, subChatId, subChat.agent, cfg.configVersion);
         const res = await buildTurn({
@@ -2609,8 +2744,28 @@ export function createRuntime(config) {
         let errors = 0;
         let skipped = 0;
         let parked = 0;
+        let rejected = 0;
         for (const s of claimed) {
             const next = s.cron ? (config.cron?.(s.cron, now, s.timezone) ?? null) : null;
+            // Rebuild the principal FIRST, because a refusal has to reach the one
+            // write below: `completeSchedule` is fenced by the claim lease and clears
+            // it, so there is no second write in which to disable the schedule. A
+            // refused identity (`null`) is permanent — the owner was removed, the
+            // account is gone — so the schedule is disabled rather than left to refuse
+            // on every tick, which is how a revoked user's schedule stays invisible
+            // forever. A THROW is transient and keeps today's contract: the occurrence
+            // is still consumed, the fire is counted in `errors`, the schedule stays
+            // live. Hosts keep the hook fast (see `reconstructPrincipal`); it now runs
+            // inside the claim window.
+            let principal = null;
+            let principalError;
+            try {
+                principal = await reconstructPrincipal(s.identity);
+            }
+            catch (error) {
+                principalError = { error };
+            }
+            const refused = !principalError && principal === null;
             // Consume the occurrence BEFORE firing, not after. The claim lease is
             // stamped once (never heartbeated), so while a fire is in flight the row
             // still reads `enabled AND nextRunAt <= now` — and once the lease TTL
@@ -2625,7 +2780,20 @@ export function createRuntime(config) {
             // survives and `sweep()` resumes it. For work that is billed per
             // attempt, "ran twice" is strictly worse than "ran once, resumed".
             try {
-                await storage.completeSchedule(s.id, { nextRunAt: next ?? now, lastRunAt: now, enabled: next != null }, dur.instanceId);
+                const applied = await storage.completeSchedule(s.id, { nextRunAt: next ?? now, lastRunAt: now, enabled: next != null && !refused }, dur.instanceId, 
+                // Which claim this is: a later pass on this same instance may have
+                // re-claimed the row under the same owner id since.
+                s.leaseExpiresAt != null ? { leaseExpiresAt: s.leaseExpiresAt } : undefined);
+                if (applied === false) {
+                    // The fence rejected us: our claim lapsed (the lease is never
+                    // renewed, and the hook above runs inside it) and a newer claim —
+                    // another node's, or a later pass on this one — holds this
+                    // occurrence. It fires it and accounts for it; firing here too would
+                    // be the duplicate paid turn consuming-first exists to prevent.
+                    console.warn(`[schedule] ${s.id} (${s.agent}): claim lost before the occurrence was consumed; ` +
+                        `the newer claim owns this fire`);
+                    continue;
+                }
             }
             catch (e) {
                 // Cannot consume the occurrence → do NOT fire. Firing anyway would
@@ -2635,8 +2803,18 @@ export function createRuntime(config) {
                 errors++;
                 continue;
             }
+            if (principalError) {
+                console.error(`[schedule] fire failed for ${s.id} (${s.agent}): reconstructPrincipal threw:`, principalError.error);
+                errors++;
+                continue;
+            }
+            if (principal === null) {
+                console.warn(`[schedule] ${s.id} (${s.agent}): reconstructPrincipal refused the schedule's ` +
+                    `identity — not fired, schedule disabled`);
+                rejected++;
+                continue;
+            }
             try {
-                const principal = await reconstructPrincipal(s.identity);
                 // Parked-predecessor guard: when the LAST fire's chat is still waiting
                 // on a human (an undecided approval or tool result), firing again just
                 // mints another parked chat and pays for the tokens up to the gate —
@@ -2735,29 +2913,31 @@ export function createRuntime(config) {
                 errors++;
             }
         }
-        return { fired, errors, skipped, parked };
+        return { fired, errors, skipped, parked, rejected };
     }
     const self = {
         listAgents: agentInfos,
         handleChat,
-        runAgent: async ({ principal, agent, prompt, threadId, blockGated = true, turnContext, promptCaching, 
+        runAgent: async ({ principal, agent, prompt, files, threadId, blockGated = true, memory, model, turnContext, promptCaching, 
         // No client stream: assume unattended unless the host says otherwise, so
         // a park here can't be silently filtered out as "someone's watching".
         trigger = "programmatic", }) => {
             const r = await runToCompletion({
                 principal,
                 agent,
-                message: userMessageOf(prompt),
+                message: userMessageOf(prompt, files),
                 chatId: threadId,
                 depth: 1,
                 // Autonomous: no human to authorize (blockGated stubs the gated tools).
                 autoApprove: true,
                 blockGated,
+                memory,
+                model,
                 turnContext,
                 promptCaching,
                 trigger,
             });
-            return { threadId: r.chatId, answer: r.answer };
+            return { threadId: r.chatId, answer: r.answer, ...(r.error ? { error: r.error } : {}) };
         },
         compactChat,
         loadHistory,