@agent-native/core 0.51.15 → 0.53.0

package/dist/agent/production-agent.js

@@ -19,7 +19,8 @@ import { createToolSearchEntry, TOOL_SEARCH_ACTION_NAME, } from "./tool-search.j
 import { getDefaultMaxIterations, normalizeMaxIterations, readAgentLoopSettings, } from "./loop-settings.js";
 import { isReasoningEffort, normalizeReasoningEffortForModel, } from "../shared/reasoning-effort.js";
 import { isAgentActionStopError } from "../action.js";
-import { writeLedgerEntry, readLedgerEntry, clearLedgerForThread, } from "./run-store.js";
+import { writeLedgerEntry, readLedgerEntry, clearLedgerForThread, getCurrentTurnEventsForThread, } from "./run-store.js";
+import { classifyToolCallJournal, findCompletedJournalEntry, } from "./tool-call-journal.js";
 import { preUploadAttachments } from "../file-upload/pre-upload-attachments.js";
 import { extensionIdFromPathname } from "../extensions/path.js";
 import { applyContextDirectives } from "./context-xray/apply-directives.js";
@@ -27,6 +28,7 @@ import { completeRun as completeProgressRun, startRun as startProgressRun, updat
 import { loadContextDirectives } from "./context-xray/directives-store.js";
 import { buildManifest, writeContextManifest, } from "./context-xray/manifest.js";
 import { computeProtectedSegmentIds } from "./context-xray/segments.js";
+import { maybeCompactThread, buildObservationalContext, hasObservationalMemory, serializeObservationalMemoryBlock, } from "./observational-memory/index.js";
 // Register built-in engines on first import
 registerBuiltinEngines();
 export { PROVIDER_TO_ENV };
@@ -1065,6 +1067,84 @@ function findCurrentTurnStartForContinuation(messages) {
     }
     return 0;
 }
+/**
+ * First message index that is safe to start a trimmed window on. A window must
+ * not begin with a tool-result-only user message — that would orphan it from
+ * the assistant tool-call turn it answers and break Anthropic's tool_use /
+ * tool_result pairing. We walk forward from `desiredStart` to the first
+ * non-orphaned boundary; if none exists we refuse to trim (return -1).
+ */
+function findSafeWindowStart(messages, desiredStart) {
+    for (let i = Math.max(0, desiredStart); i < messages.length; i++) {
+        if (!isToolResultOnlyUserMessage(messages[i]))
+            return i;
+    }
+    return -1;
+}
+/**
+ * Observational Memory consumer (threshold-gated, conservative).
+ *
+ * Builds the three-tier OM context for a thread and, ONLY when the thread has
+ * already crossed the compaction threshold (i.e. it has at least one persisted
+ * observation/reflection), returns a rewritten message list that:
+ *   - prepends a single system-role "Observational Memory" block holding the
+ *     reflections + observations, and
+ *   - replaces the raw older history with just the recent-raw-message window,
+ *     keeping the current user turn and any pending tool results intact.
+ *
+ * For threads with NO OM entries (every short thread) it returns the input
+ * array unchanged by reference, so the common path is byte-for-byte identical.
+ *
+ * Best-effort: any failure returns the input unchanged so OM can never break a
+ * normal turn.
+ */
+async function applyObservationalMemoryToContext(messages, opts) {
+    if (!opts.ownerEmail)
+        return messages;
+    try {
+        const context = await buildObservationalContext({
+            threadId: opts.threadId,
+            ownerEmail: opts.ownerEmail,
+            orgId: opts.orgId ?? null,
+            messages,
+        });
+        // No compacted memory yet → short thread, leave context untouched.
+        if (!hasObservationalMemory(context))
+            return messages;
+        const block = serializeObservationalMemoryBlock(context);
+        if (!block.trim())
+            return messages;
+        // EngineMessage has no "system" role; the framework injects auxiliary
+        // context as leading user messages (same convention as the continuation
+        // nudge and the resume journal note), and the serialized block is clearly
+        // self-labeled "[Observational Memory]".
+        const omMessage = {
+            role: "user",
+            content: [{ type: "text", text: block }],
+        };
+        // Trim the raw prefix to only the recent-raw window. The window is the tail
+        // of `messages`, so it always contains the latest user turn and any pending
+        // tool results. Guard the boundary so we never start mid tool_use/result
+        // pair; if a safe boundary can't be found, additively inject the memory
+        // block WITHOUT trimming (the conservative fallback) so we never drop a
+        // pending tool result.
+        const recentCount = context.recentMessages.length;
+        if (recentCount === 0 || recentCount >= messages.length) {
+            return [omMessage, ...messages];
+        }
+        const desiredStart = messages.length - recentCount;
+        const safeStart = findSafeWindowStart(messages, desiredStart);
+        if (safeStart < 0) {
+            // Whole tail is tool-result-only (degenerate) — don't trim.
+            return [omMessage, ...messages];
+        }
+        return [omMessage, ...messages.slice(safeStart)];
+    }
+    catch (err) {
+        console.warn("[observational-memory] context injection skipped:", err instanceof Error ? err.message : String(err));
+        return messages;
+    }
+}
 function seedReadOnlyToolResultsFromHistory(messages, actions) {
     const cache = new Map();
     if (!isInternalContinuationTurn(messages))
@@ -1421,6 +1501,30 @@ export async function runAgentLoop(opts) {
     const readOnlyToolResultCache = seedReadOnlyToolResultsFromHistory(messages, actions);
     const duplicateReadOnlyToolCalls = new Map();
     const writeToolInterruptions = seedWriteToolInterruptionsFromHistory(messages, actions);
+    // Tool-call journal hard-block (resume safety). Snapshot the per-turn journal
+    // ONCE here, before any tool runs in this chunk, so it reflects only PRIOR
+    // run chunks of this logical turn. A write tool whose exact call already
+    // completed in an earlier interrupted chunk must not re-fire its side effect;
+    // when matched, runToolCall returns the journaled result instead of executing.
+    // Loaded eagerly (not lazily mid-loop) so the current chunk's own
+    // asynchronously-persisted tool_done events can never leak in and make a
+    // same-chunk call wrongly short-circuit. Best-effort: any ledger failure
+    // leaves the journal empty and all calls run normally. Fresh first-turn calls
+    // see an empty journal and are unaffected.
+    let toolCallJournal = null;
+    const consumedJournalKeys = new Set();
+    if (opts.threadId) {
+        try {
+            const priorEvents = await getCurrentTurnEventsForThread(opts.threadId);
+            if (priorEvents.length > 0) {
+                toolCallJournal = classifyToolCallJournal(priorEvents);
+            }
+        }
+        catch {
+            // Journal is a hardening layer, never a gate — a failed ledger read just
+            // means no hard-block this turn.
+        }
+    }
     const bufferTextUntilFinalGuard = Boolean(opts.finalResponseGuard);
     let finalGuardRetries = 0;
     let iterations = 0;
@@ -1465,6 +1569,21 @@ export async function runAgentLoop(opts) {
             catch (err) {
                 console.warn("[context-xray] context transform skipped:", err instanceof Error ? err.message : String(err));
             }
+            // Observational Memory (consumer): for long threads that have already been
+            // compacted, fold the reflections+observations in as a leading context
+            // block and prefer the recent-raw-message window over the full raw
+            // history. No-op (returns the same array) for short threads with no OM
+            // entries, so the common path is unchanged. Runs after the context-xray
+            // transform so the two compose; best-effort inside the helper. Gated on an
+            // authenticated owner so anonymous threads never read OM scoped to a
+            // shared default identity.
+            if (opts.ownerEmail) {
+                contextMessages = await applyObservationalMemoryToContext(contextMessages, {
+                    threadId: opts.threadId,
+                    ownerEmail: opts.ownerEmail,
+                    orgId: opts.orgId ?? null,
+                });
+            }
         }
         for (let retry = 0;; retry++) {
             assistantContent = undefined;
@@ -1690,6 +1809,11 @@ export async function runAgentLoop(opts) {
         finalGuardRetries = 0;
         flushBufferedAssistantText();
         let requestedActionStop = null;
+        // Human-in-the-loop approvals granted by the user for this turn (opt-in;
+        // empty for the overwhelming majority of turns). Keyed by the stable
+        // tool-call approval key so a re-issued continuation can let an approved
+        // call run. The model cannot populate this — it comes from the request.
+        const approvedToolCallKeys = new Set(opts.approvedToolCalls ?? []);
         const runToolCall = async (toolCall) => {
             const wireToolInput = JSON.stringify(toolCall.input ?? {});
             const normalizedToolInput = normalizeToolCallInputForHistory(toolCall.input);
@@ -1774,6 +1898,60 @@ export async function runAgentLoop(opts) {
                     isError: true,
                 };
             }
+            // Human-in-the-loop approval gate (opt-in via defineAction
+            // `needsApproval`; default off). When an action requires approval and
+            // this specific call has NOT been approved by a human, pause the turn
+            // instead of executing. The action's side effect never happens until a
+            // human re-issues the turn approving this call's stable key.
+            const approvalKey = toolCallCacheKey(toolCall.name, toolCall.input);
+            if (actionEntry.needsApproval && !approvedToolCallKeys.has(approvalKey)) {
+                let mustApprove = false;
+                try {
+                    mustApprove =
+                        typeof actionEntry.needsApproval === "function"
+                            ? Boolean(await actionEntry.needsApproval(toolCall.input, {
+                                userEmail: getRequestUserEmail(),
+                                orgId: getRequestOrgId() ?? null,
+                                caller: "tool",
+                            }))
+                            : actionEntry.needsApproval === true;
+                }
+                catch {
+                    // Fail closed: a throwing predicate means we require approval rather
+                    // than silently running a high-consequence action.
+                    mustApprove = true;
+                }
+                if (mustApprove) {
+                    send({
+                        type: "tool_start",
+                        tool: toolCall.name,
+                        input: toolCall.input,
+                    });
+                    send({
+                        type: "approval_required",
+                        tool: toolCall.name,
+                        input: toolCall.input,
+                        approvalKey,
+                        ...(toolCall.id ? { toolCallId: toolCall.id } : {}),
+                    });
+                    const result = `Awaiting human approval to run "${toolCall.name}". This action did ` +
+                        `NOT execute — a human must approve this specific call before it ` +
+                        `can run. The turn is paused; do not retry.`;
+                    send({ type: "tool_done", tool: toolCall.name, result });
+                    recordToolResult(result, false);
+                    requestedActionStop ??= {
+                        message: `Waiting for your approval to run ${toolCall.name}.`,
+                        errorCode: "needs-approval",
+                    };
+                    return {
+                        type: "tool-result",
+                        toolCallId: toolCall.id,
+                        toolName: toolCall.name,
+                        toolInput: wireToolInput,
+                        content: result,
+                    };
+                }
+            }
             const cacheKey = actionEntry.readOnly === true
                 ? toolCallCacheKey(toolCall.name, toolCall.input)
                 : null;
@@ -1805,6 +1983,40 @@ export async function runAgentLoop(opts) {
                     content: result,
                 };
             }
+            // TOOL-CALL JOURNAL HARD-BLOCK (resume safety, tool-layer enforcement).
+            // The prompt-level resume journal already TELLS a resuming model not to
+            // re-run completed tool calls; this enforces it at the tool layer so a
+            // re-dispatched write call whose exact (tool name + input) already
+            // completed in an earlier interrupted chunk of this turn does NOT execute
+            // its side effect again — we return the journaled result instead and emit
+            // the normal tool_start/tool_done so the transcript stays coherent.
+            //
+            // Gated on a non-readOnly tool + an existing prior-chunk journal (so fresh
+            // calls with no completed journal entry are completely unaffected). The
+            // snapshot was taken before this chunk's tools ran, so it can only match a
+            // PRIOR completion, never one from the current chunk.
+            if (!actionEntry.readOnly && toolCallJournal) {
+                const journaled = findCompletedJournalEntry(toolCallJournal, toolCall.name, toolCall.input, consumedJournalKeys);
+                if (journaled) {
+                    const recordedResult = journaled.result ?? "";
+                    const result = `(Already completed in an earlier interrupted attempt - not re-run to avoid a duplicate side effect.)\n\n` +
+                        recordedResult;
+                    send({
+                        type: "tool_start",
+                        tool: toolCall.name,
+                        input: toolCall.input,
+                    });
+                    send({ type: "tool_done", tool: toolCall.name, result });
+                    recordToolResult(result, false);
+                    return {
+                        type: "tool-result",
+                        toolCallId: toolCall.id,
+                        toolName: toolCall.name,
+                        toolInput: wireToolInput,
+                        content: result,
+                    };
+                }
+            }
             // Guard against write tools that have been interrupted too many times in
             // this turn (connection drop mid-execution → agent retries → repeat).
             // A write tool that keeps failing likely has a timeout / large-payload
@@ -2124,6 +2336,23 @@ export async function runAgentLoop(opts) {
         // intact so the next continuation chunk can still recover from it.
         if (opts.threadId) {
             void clearLedgerForThread(opts.threadId).catch(() => { });
+            // Observational Memory (producer): after a clean turn, run a best-effort
+            // compaction pass so long threads accrue observations/reflections that the
+            // consumer above will surface on later turns. Both the Observer and the
+            // Reflector no-op below their token thresholds, so this is cheap for short
+            // threads. Fire-and-forget; any failure is swallowed so OM never affects
+            // the user-visible turn.
+            if (opts.ownerEmail) {
+                const compactThreadId = opts.threadId;
+                void maybeCompactThread({
+                    threadId: compactThreadId,
+                    ownerEmail: opts.ownerEmail,
+                    orgId: opts.orgId ?? null,
+                    messages,
+                }).catch((err) => {
+                    console.warn("[observational-memory] post-turn compaction skipped:", err instanceof Error ? err.message : String(err));
+                });
+            }
         }
     }
     return usage;
@@ -2998,6 +3227,16 @@ export function createProductionAgentHandler(options) {
                 ...(threadId
                     ? { threadId: effectiveThreadId, turnId: effectiveTurnId }
                     : {}),
+                // Human-in-the-loop approval grants for this turn (sanitized — the
+                // request is untrusted; accept only a bounded list of string keys).
+                ...(Array.isArray(body.approvedToolCalls) &&
+                    body.approvedToolCalls.length
+                    ? {
+                        approvedToolCalls: body.approvedToolCalls
+                            .filter((k) => typeof k === "string")
+                            .slice(0, 200),
+                    }
+                    : {}),
             };
             send({ type: "activity", label: "Contacting model" });
             // loopUsage is always assigned — either via instrumentAgentLoop or