@polpo-ai/node 0.18.6 → 0.18.8

package/dist/adapters/loop-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop-engine.d.ts","sourceRoot":"","sources":["../../src/adapters/loop-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,IAAI,EAAc,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAGL,KAAK,YAAY,EAGlB,MAAM,IAAI,CAAC;AAuCZ,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,yBAAyB,CAAC;AAkDjC;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,eAAe,GAAG,YAAY,CAwB7E;AA8CD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,QAAkB,CAAC;AAiCpD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,YAAY,GAAG,WAAW,CAunClH"}
+{"version":3,"file":"loop-engine.d.ts","sourceRoot":"","sources":["../../src/adapters/loop-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,IAAI,EAAc,MAAM,sBAAsB,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAGL,KAAK,YAAY,EAGlB,MAAM,IAAI,CAAC;AA8CZ,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,yBAAyB,CAAC;AAkDjC;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,eAAe,GAAG,YAAY,CAwB7E;AA8CD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,QAAkB,CAAC;AAiCpD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,YAAY,GAAG,WAAW,CAy5ClH"}

package/dist/adapters/loop-engine.js

@@ -29,6 +29,7 @@ import { generateText, tool as aiTool, } from "ai";
 import { normalizeResponseMessagesForHistory, prepareModelMessagesForTransport, runModelPolicyTurn, isStructuredModelOutputError, modelOutputForJsonSchema, classifyRuntimeError, markToolStrictness, toValidatedToolInputSchema, validateToolInput, } from "@polpo-ai/llm";
 import { cleanupAgentBrowserSession } from "@polpo-ai/tools";
 import { LoopRunner, LoopToolInputValidationError, PipelineExecutor, buildLoopStepAgent, loopContextPrompt, loopAgentInputPrompt, maybeParseJson, LoopAgentOutputError, prepareLoopAgentOutput, normalizeProjectLoop, normalizeToolInput, protectRuntimeToolResultMessages, renderRuntimeToolResult, resolveLoopSelection, compactIfNeeded, extractToolUsageRecord, } from "@polpo-ai/core";
+import { runtimeHookFileChangeForTool } from "@polpo-ai/core/runtime-hooks";
 import { InMemorySteeringController, } from "@polpo-ai/core/steering";
 import { projectLoopConfigSchema } from "@polpo-ai/core/schemas";
 import { NodeFileSystem } from "./node-filesystem.js";
@@ -220,6 +221,72 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
         const sink = handle.onTranscript ?? ctx?.onTranscript;
         sink?.(entry);
     };
+    const runtimeHooks = ctx?.inject?.runtimeHooks ?? ctx?.runtimeHooks;
+    const dispatchRuntimeHook = async (event, data = {}, identity = {}) => {
+        if (!runtimeHooks)
+            return { action: "allow" };
+        const result = await runtimeHooks.dispatch({
+            event,
+            surface: ctx?.inject?.runtimeHookSurface
+                ?? ctx?.runtimeHookSurface
+                ?? (ctx?.inject ? "chat" : "task"),
+            identity: {
+                runId: ctx?.runId ?? task.id,
+                sessionId: ctx?.inject?.sessionId,
+                agent: agentConfig.name,
+                ...identity,
+            },
+            data,
+        });
+        return result.decision;
+    };
+    const decisionError = (decision) => {
+        if (decision.action === "allow" || decision.action === "modify")
+            return undefined;
+        const reason = "reason" in decision ? decision.reason : "Runtime hook stopped execution";
+        return new Error(`Runtime hook ${decision.action}: ${reason ?? "stopped"}`);
+    };
+    const runHookedModel = async (data, operation, resultData = () => ({})) => {
+        const before = await dispatchRuntimeHook("model:before", data);
+        const beforeError = decisionError(before);
+        if (beforeError)
+            throw beforeError;
+        try {
+            const result = await operation();
+            const after = await dispatchRuntimeHook("model:after", { ...data, ...resultData(result) });
+            const afterError = decisionError(after);
+            if (afterError)
+                throw afterError;
+            return result;
+        }
+        catch (error) {
+            await dispatchRuntimeHook("model:error", {
+                ...data,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    };
+    const dispatchModelPolicyHook = async (event, identity) => {
+        if (event.type !== "model-fallback-selected")
+            return;
+        const { raw: _raw, ...reason } = event.reason;
+        const data = {
+            from: event.from.model,
+            to: event.to.model,
+            fromIndex: event.from.index,
+            toIndex: event.to.index,
+            reason,
+        };
+        const before = await dispatchRuntimeHook("model:switch:before", data, identity);
+        const beforeError = decisionError(before);
+        if (beforeError)
+            throw beforeError;
+        const after = await dispatchRuntimeHook("model:switch:after", data, identity);
+        const afterError = decisionError(after);
+        if (afterError)
+            throw afterError;
+    };
     /**
      * Execute one tool call: dispatch, activity tracking, outcome collection,
      * toolUsage harvesting, transcript. Shared by LLM-session tool execution
@@ -232,6 +299,23 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
         };
         let isError = false;
         let executionError;
+        const before = await dispatchRuntimeHook("tool:before", {
+            tool: toolCall.name,
+            input: toolCall.args,
+        }, { toolCallId: toolCall.id });
+        const beforeError = decisionError(before);
+        if (beforeError) {
+            isError = true;
+            executionError = beforeError;
+            result = { content: [{ type: "text", text: beforeError.message }], details: {} };
+            return { llmText: beforeError.message, isError, error: executionError };
+        }
+        const effectiveArgs = before.action === "modify"
+            && before.data.input
+            && typeof before.data.input === "object"
+            && !Array.isArray(before.data.input)
+            ? before.data.input
+            : toolCall.args;
         const dispatch = async (args) => {
             if (!pt) {
                 isError = true;
@@ -257,15 +341,38 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
                     };
                 }
             }
-            return result.content
+            let rendered = result.content
                 .map((content) => content.type === "text" ? content.text : `[image: ${content.mimeType}]`)
                 .join("\n");
+            const after = await dispatchRuntimeHook(isError ? "tool:error" : "tool:after", {
+                tool: toolCall.name,
+                input: args,
+                result: rendered,
+            }, { toolCallId: toolCall.id });
+            const afterError = decisionError(after);
+            if (afterError) {
+                isError = true;
+                executionError = afterError;
+                rendered = afterError.message;
+                result = { content: [{ type: "text", text: rendered }], details: {} };
+            }
+            else if (after.action === "modify" && typeof after.data.result === "string") {
+                rendered = after.data.result;
+                result = { ...result, content: [{ type: "text", text: rendered }] };
+            }
+            if (!isError) {
+                const fileChange = runtimeHookFileChangeForTool(toolCall.name, args, rendered);
+                if (fileChange) {
+                    await dispatchRuntimeHook("sandbox:file_changed", fileChange, { toolCallId: toolCall.id });
+                }
+            }
+            return rendered;
         };
         const llmText = ctx?.runToolMiddleware
             ? (await ctx.runToolMiddleware.execute({
                 callId: toolCall.id,
                 name: toolCall.name,
-                args: toolCall.args,
+                args: effectiveArgs,
                 schema: pt?.parameters,
                 context: {
                     agent: agentConfig.name,
@@ -276,7 +383,7 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
                 },
                 signal: abortController.signal,
             }, (request) => dispatch(request.args))).output
-            : await dispatch(toolCall.args);
+            : await dispatch(effectiveArgs);
         activity.lastUpdate = new Date().toISOString();
         // Track file operations from tool details
         const details = result.details;
@@ -327,9 +434,42 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
     async function runLoopSession(options) {
         const { sessionAgent, loopName, loop, contextPrompt } = options;
         let sessionCleanup;
+        let agentHookStarted = false;
+        let sandboxHookStarted = false;
         try {
             const resume = usableResumeState(options.resume, loopName);
             const inject = ctx?.inject;
+            await dispatchRuntimeHook("run:start", { loop: loopName, resumed: Boolean(resume) }, { agent: sessionAgent.name, loop: loopName });
+            await dispatchRuntimeHook(resume ? "session:resume" : "session:start", {
+                loop: loopName,
+                resumed: Boolean(resume),
+            }, { agent: sessionAgent.name, loop: loopName });
+            const spawnDecision = await dispatchRuntimeHook("agent:spawn", {
+                loop: loopName,
+                source: inject ? "chat-run" : "task-run",
+            }, { agent: sessionAgent.name, loop: loopName });
+            const spawnError = decisionError(spawnDecision);
+            if (spawnError)
+                throw spawnError;
+            agentHookStarted = true;
+            if (ctx?.fs || ctx?.shell) {
+                const sandboxDecision = await dispatchRuntimeHook("sandbox:start", {
+                    cwd,
+                    filesystem: Boolean(ctx.fs),
+                    shell: Boolean(ctx.shell),
+                }, { agent: sessionAgent.name, loop: loopName });
+                const sandboxError = decisionError(sandboxDecision);
+                if (sandboxError)
+                    throw sandboxError;
+                sandboxHookStarted = true;
+            }
+            const inputDecision = await dispatchRuntimeHook("input:before", {
+                loop: loopName,
+                hasProjectedInput: Boolean(options.initialUserMessage),
+            }, { agent: sessionAgent.name, loop: loopName });
+            const inputError = decisionError(inputDecision);
+            if (inputError)
+                throw inputError;
             // Inject path (chat-via-executeRun, F1c): use the completions route's
             // already-resolved model/prompt/tools/messages instead of re-resolving from
             // the AgentConfig — parity by construction. Every branch below is
@@ -371,6 +511,9 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
                 toolSet = toToolDeclarations(allPolpoTools);
                 compactionTools = allPolpoTools.map((t) => ({ description: t.description ?? "" }));
             }
+            if (inputDecision.action === "modify" && typeof inputDecision.data.context === "string" && inputDecision.data.context.trim()) {
+                systemPrompt += `\n\n## Runtime hook context\n\n${inputDecision.data.context.trim()}`;
+            }
             const primaryResolved = { model, providerOptions };
             const modelSelection = inject?.modelSelection ??
                 resolvedModelSelection ??
@@ -441,7 +584,7 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
                     const isRecovery = attemptIndex === 1;
                     const resolvedAttempts = new Map();
                     try {
-                        const terminal = await runModelPolicyTurn({
+                        const terminal = await runHookedModel({ phase: "terminal", recovery: isRecovery, model: model.id ?? model.provider }, () => runModelPolicyTurn({
                             selection: modelSelection,
                             resolveAttempt: async (attempt) => {
                                 const resolvedAttempt = attempt.index === 0
@@ -461,13 +604,17 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
                                 };
                             },
                             preserveSingleAttemptError: true,
+                            onPolicyEvent: (event) => dispatchModelPolicyHook(event, {
+                                agent: sessionAgent.name,
+                                loop: loopName,
+                            }),
                             allowCommittedFallback: true,
                             maxRecoverableStreamRetries: 0,
                             system: systemPrompt,
                             messages: terminalMessages(isRecovery),
                             output: modelOutput,
                             abortSignal: abortController.signal,
-                        });
+                        }), (result) => ({ finishReason: result.finishReason, toolCallCount: result.toolCalls?.length ?? 0 }));
                         if (terminal.toolCalls.length > 0 || terminal.output === undefined) {
                             throw new Error(terminal.toolCalls.length > 0
                                 ? "Terminal structured-output phase returned a tool call"
@@ -551,6 +698,10 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
                 }
                 // Context compaction — same call, same config, same quirks as the
                 // legacy engine (see engine-behavior characterization tests).
+                await dispatchRuntimeHook("context:compact:before", {
+                    messageCount: messages.length,
+                    model: model.id ?? model.provider,
+                });
                 const compactionResult = await compactIfNeeded({
                     systemPrompt,
                     messages,
@@ -577,6 +728,10 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
                 });
                 if (compactionResult.compacted) {
                     messages = normalizeResponseMessagesForHistory(compactionResult.messages);
+                    await dispatchRuntimeHook("context:compact:after", {
+                        messageCount: messages.length,
+                        compacted: true,
+                    });
                 }
                 messages = normalizeResponseMessagesForHistory(messages);
                 if (contextTrust === "enforce") {
@@ -588,7 +743,7 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
                 const resolvedAttempts = new Map();
                 let turn;
                 try {
-                    turn = await runModelPolicyTurn({
+                    turn = await runHookedModel({ phase: "operational", model: model.id ?? model.provider }, () => runModelPolicyTurn({
                         selection: modelSelection,
                         resolveAttempt: async (attempt) => {
                             const resolvedAttempt = attempt.index === 0
@@ -608,6 +763,10 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
                             };
                         },
                         preserveSingleAttemptError: true,
+                        onPolicyEvent: (event) => dispatchModelPolicyHook(event, {
+                            agent: sessionAgent.name,
+                            loop: loopName,
+                        }),
                         system: systemPrompt,
                         messages,
                         tools: toolSet,
@@ -768,7 +927,7 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
                                 break;
                             }
                         }
-                    });
+                    }), (result) => ({ finishReason: result.finishReason, toolCallCount: result.toolCalls?.length ?? 0 }));
                 }
                 catch (error) {
                     if (outputSchema !== undefined && isStructuredModelOutputError(error)) {
@@ -919,7 +1078,7 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
                     model: modelStep,
                     executeTool,
                     parallelToolCalls: inject?.parallelToolCalls,
-                    onToolResults: (toolResults) => {
+                    onToolResults: async (toolResults) => {
                         for (const { toolCall, result, isError } of toolResults) {
                             // AI SDK already persisted provider-executed results and invalid
                             // argument errors in responseMessages. Only local results belong
@@ -942,6 +1101,18 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
                                     }],
                             });
                         }
+                        if (toolResults.length > 0) {
+                            await dispatchRuntimeHook("tool:batch:after", {
+                                count: toolResults.length,
+                                failed: toolResults.filter((result) => result.isError).length,
+                                tools: toolResults.map(({ toolCall, isError, skipped }) => ({
+                                    id: toolCall.id,
+                                    name: toolCall.name,
+                                    isError,
+                                    skipped,
+                                })),
+                            }, { agent: sessionAgent.name, loop: loopName });
+                        }
                     },
                     steering,
                     onSteering: async (steeringMessages) => {
@@ -972,9 +1143,118 @@ export function spawnLoopEngine(agentConfig, task, cwd, ctx) {
             if (outputSchema !== undefined && !completedStructuredOutput && !interruptedForClientTool) {
                 throw new LoopAgentOutputError("loop_agent_output_invalid", loopName, `Agent step ${JSON.stringify(loopName)} exhausted maxTurns before producing structured output`, { phase: "max_turns" });
             }
+            const stopDecision = await dispatchRuntimeHook("turn:stop", {
+                loop: loopName,
+                textLength: lastStepText.length,
+            }, { agent: sessionAgent.name, loop: loopName });
+            const stopError = decisionError(stopDecision);
+            if (stopError && stopDecision.action !== "stop")
+                throw stopError;
+            const stopFeedback = stopDecision.action === "stop" ? stopDecision.feedback?.trim() : undefined;
+            if (stopFeedback && !hasStructuredOutput && !abortController.signal.aborted) {
+                const resolvedAttempts = new Map();
+                const retry = await runHookedModel({ phase: "stop-feedback", retry: 1, model: model.id ?? model.provider }, () => runModelPolicyTurn({
+                    selection: modelSelection,
+                    resolveAttempt: async (attempt) => {
+                        const resolvedAttempt = attempt.index === 0
+                            ? primaryResolved
+                            : inject
+                                ? await inject.resolveModelAttempt?.(attempt.model)
+                                : resolveSpawnModelAttempt(sessionAgent, attempt.model, ctx);
+                        if (!resolvedAttempt)
+                            throw new Error(`No model resolver is available for fallback "${attempt.model}"`);
+                        resolvedAttempts.set(attempt.index, resolvedAttempt);
+                        return {
+                            model: resolvedAttempt.model.aiModel,
+                            maxOutputTokens: resolvedAttempt.model.maxTokens,
+                            providerOptions: resolvedAttempt.providerOptions,
+                            capabilities: resolvedAttempt.model.capabilities,
+                        };
+                    },
+                    preserveSingleAttemptError: true,
+                    onPolicyEvent: (event) => dispatchModelPolicyHook(event, {
+                        agent: sessionAgent.name,
+                        loop: loopName,
+                    }),
+                    system: systemPrompt,
+                    messages: [
+                        ...messages,
+                        {
+                            role: "user",
+                            content: `A trusted runtime hook rejected ending the turn and returned this feedback:\n\n${stopFeedback}\n\nContinue once and return the corrected final response. Do not repeat completed side effects.`,
+                        },
+                    ],
+                    tools: {},
+                    toolChoice: "none",
+                    abortSignal: abortController.signal,
+                }), (result) => ({ finishReason: result.finishReason, toolCallCount: result.toolCalls?.length ?? 0 }));
+                if (retry.toolCalls.length > 0)
+                    throw new Error("Stop-feedback recovery returned a tool call");
+                const selectedResolved = resolvedAttempts.get(retry.selectedAttempt.index);
+                if (selectedResolved) {
+                    model = selectedResolved.model;
+                    providerOptions = selectedResolved.providerOptions;
+                }
+                let retryText = retry.text;
+                if (retryText && ctx?.runOutputPolicy) {
+                    retryText = (await ctx.runOutputPolicy.evaluate({
+                        output: retryText,
+                        mode: ctx.runOutputPolicyMode ?? "enforce",
+                        context: { agent: sessionAgent.name, runId: ctx.runId, source: "task", surface: "task" },
+                        signal: abortController.signal,
+                    })).output;
+                }
+                if (retryText) {
+                    try {
+                        ctx?.onDelta?.({ text: `${lastStepText ? "\n\n" : ""}${retryText}` });
+                    }
+                    catch { /* subscriber cannot sink the run */ }
+                    emitTranscript({ type: "assistant", text: retryText });
+                    accumText += retryText;
+                    lastStepText = `${lastStepText ? `${lastStepText}\n\n` : ""}${retryText}`;
+                }
+                if (inject)
+                    emitTranscript({ type: "usage", usage: retry.usage, providerMetadata: retry.providerMetadata });
+                const retryStop = await dispatchRuntimeHook("turn:stop", {
+                    loop: loopName,
+                    textLength: lastStepText.length,
+                    stopFeedbackRetry: 1,
+                }, { agent: sessionAgent.name, loop: loopName });
+                const retryStopError = decisionError(retryStop);
+                if (retryStopError && retryStop.action !== "stop")
+                    throw retryStopError;
+            }
             return { lastText: lastStepText, accumText };
         }
+        catch (error) {
+            await dispatchRuntimeHook("turn:error", {
+                loop: loopName,
+                error: error instanceof Error ? error.message : String(error),
+            }, { agent: sessionAgent.name, loop: loopName }).catch(() => { });
+            throw error;
+        }
         finally {
+            if (sandboxHookStarted) {
+                await dispatchRuntimeHook("sandbox:end", {
+                    cwd,
+                    aborted: abortController.signal.aborted,
+                }, { agent: sessionAgent.name, loop: loopName }).catch(() => { });
+            }
+            if (agentHookStarted) {
+                await dispatchRuntimeHook("agent:end", {
+                    loop: loopName,
+                    source: ctx?.inject ? "chat-run" : "task-run",
+                    aborted: abortController.signal.aborted,
+                }, { agent: sessionAgent.name, loop: loopName }).catch(() => { });
+            }
+            await dispatchRuntimeHook("session:end", {
+                loop: loopName,
+                aborted: abortController.signal.aborted,
+            }, { agent: sessionAgent.name, loop: loopName }).catch(() => { });
+            await dispatchRuntimeHook("run:end", {
+                loop: loopName,
+                aborted: abortController.signal.aborted,
+            }, { agent: sessionAgent.name, loop: loopName }).catch(() => { });
             if (sessionCleanup) {
                 await sessionCleanup().catch(() => undefined);
                 toolCleanups.delete(sessionCleanup);