apex-code 0.5.0 → 0.5.1

package/dist/core/extensions/runner.js

@@ -1,7 +1,9 @@
 /**
  * Extension runner - executes extensions and manages their lifecycle.
  */
+import { getCurrentSystemMessage, } from "@earendil-works/pi-ai";
 import { theme } from "../../modes/interactive/theme/theme.js";
+import { buildSystemPrompt, normalizeBuildSystemPromptOptions, } from "../system-prompt.js";
 // Extension shortcuts compete with canonical keybinding ids from keybindings.json.
 // Only editor-global shortcuts are reserved here. Picker-specific bindings are not.
 const RESERVED_KEYBINDINGS_FOR_EXTENSION_CONFLICTS = [
@@ -46,6 +48,31 @@ const buildBuiltinKeybindings = (resolvedKeybindings) => {
     }
     return builtinKeybindings;
 };
+function isUserBashEventResult(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    const hasOperations = candidate.operations !== undefined;
+    const hasResult = candidate.result !== undefined;
+    if (hasOperations === hasResult)
+        return false;
+    if (hasOperations) {
+        const operations = candidate.operations;
+        if (typeof operations !== "object" || operations === null)
+            return false;
+        return typeof operations.exec === "function";
+    }
+    const result = candidate.result;
+    if (typeof result !== "object" || result === null)
+        return false;
+    const resultRecord = result;
+    return (typeof resultRecord.output === "string" &&
+        "exitCode" in resultRecord &&
+        (resultRecord.exitCode === undefined || typeof resultRecord.exitCode === "number") &&
+        typeof resultRecord.cancelled === "boolean" &&
+        typeof resultRecord.truncated === "boolean" &&
+        (resultRecord.fullOutputPath === undefined || typeof resultRecord.fullOutputPath === "string"));
+}
 /**
  * Helper function to emit session_shutdown event to extensions.
  * Returns true if the event was emitted, false if there were no handlers.
@@ -57,14 +84,31 @@ export async function emitSessionShutdownEvent(extensionRunner, event) {
     }
     return false;
 }
+function snapshotEventHandlers(extensions, event) {
+    return extensions.map((ext) => ({ ext, handlers: ext.handlers.get(event)?.slice() ?? [] }));
+}
+function sameMessages(left, right) {
+    return left.length === right.length && left.every((message, index) => message === right[index]);
+}
+/**
+ * Re-attach the prompt and tool state after a `context` handler. Handlers only see the
+ * conversation; the system messages belong to Pi. An unchanged conversation keeps every
+ * system message in place, so models with mid-conversation support keep their cached
+ * prefix. A changed one gets the replayed prompt sections and tool declarations as one
+ * leading system message, so pruning, windowing, or slicing from a compaction summary
+ * cannot drop them.
+ */
+function restoreSystemMessages(current, visible, returned) {
+    if (sameMessages(returned, visible))
+        return current;
+    const head = getCurrentSystemMessage(current);
+    return head ? [head, ...returned] : returned;
+}
 export async function emitProjectTrustEvent(extensionsResult, event, ctx) {
     const errors = [];
-    for (const ext of extensionsResult.extensions) {
+    for (const { ext, handlers } of snapshotEventHandlers(extensionsResult.extensions, "project_trust")) {
         // A single extension may register multiple handlers for the same event.
         // The first project_trust handler that returns yes/no wins; undecided falls through.
-        const handlers = ext.handlers.get("project_trust");
-        if (!handlers || handlers.length === 0)
-            continue;
         for (const handler of handlers) {
             try {
                 const handlerResult = (await handler(event, ctx));
@@ -137,7 +181,7 @@ export class ExtensionRunner {
     getContextUsageFn = () => undefined;
     compactFn = () => { };
     getSystemPromptFn = () => "";
-    getSystemPromptOptionsFn = () => ({ cwd: this.cwd });
+    getSystemPromptOptionsFn = () => normalizeBuildSystemPromptOptions({ cwd: this.cwd });
     newSessionHandler = async () => ({ cancelled: false });
     forkHandler = async () => ({ cancelled: false });
     navigateTreeHandler = async () => ({ cancelled: false });
@@ -185,7 +229,8 @@ export class ExtensionRunner {
         this.getContextUsageFn = contextActions.getContextUsage;
         this.compactFn = contextActions.compact;
         this.getSystemPromptFn = contextActions.getSystemPrompt;
-        this.getSystemPromptOptionsFn = contextActions.getSystemPromptOptions ?? (() => ({ cwd: this.cwd }));
+        this.getSystemPromptOptionsFn =
+            contextActions.getSystemPromptOptions ?? (() => normalizeBuildSystemPromptOptions({ cwd: this.cwd }));
         // Flush provider registrations queued during extension loading
         for (const { name, config, extensionPath } of this.runtime.pendingProviderRegistrations) {
             try {
@@ -614,6 +659,54 @@ export class ExtensionRunner {
         };
         return context;
     }
+    async emitBoundary(baseEvent, buildContext) {
+        const ctx = this.createContext();
+        let entries = [];
+        let shouldContinue = false;
+        let context = await buildContext(entries);
+        let valid = true;
+        for (const { ext, handlers } of snapshotEventHandlers(this.extensions, baseEvent.type)) {
+            for (const handler of handlers) {
+                const event = {
+                    ...baseEvent,
+                    entries,
+                    continue: shouldContinue,
+                    context,
+                };
+                try {
+                    const handlerResult = (await handler(event, ctx));
+                    if (handlerResult?.entries !== undefined)
+                        entries = handlerResult.entries;
+                    if (handlerResult?.continue !== undefined)
+                        shouldContinue = handlerResult.continue;
+                }
+                catch (err) {
+                    this.emitError({
+                        extensionPath: ext.path,
+                        event: baseEvent.type,
+                        error: err instanceof Error ? err.message : String(err),
+                        stack: err instanceof Error ? err.stack : undefined,
+                    });
+                }
+                try {
+                    context = await buildContext(entries);
+                    valid = true;
+                }
+                catch (err) {
+                    valid = false;
+                    this.emitError({
+                        extensionPath: ext.path,
+                        event: baseEvent.type,
+                        error: `Invalid boundary entries: ${err instanceof Error ? err.message : String(err)}`,
+                        stack: err instanceof Error ? err.stack : undefined,
+                    });
+                }
+            }
+        }
+        return valid
+            ? { entries, continue: shouldContinue, context, valid: true }
+            : { entries: [], continue: false, context, valid: false };
+    }
     isSessionBeforeEvent(event) {
         return (event.type === "session_before_switch" ||
             event.type === "session_before_fork" ||
@@ -623,10 +716,7 @@ export class ExtensionRunner {
     async emit(event) {
         const ctx = this.createContext();
         let result;
-        for (const ext of this.extensions) {
-            const handlers = ext.handlers.get(event.type);
-            if (!handlers || handlers.length === 0)
-                continue;
+        for (const { ext, handlers } of snapshotEventHandlers(this.extensions, event.type)) {
             for (const handler of handlers) {
                 try {
                     const handlerResult = await handler(event, ctx);
@@ -651,14 +741,34 @@ export class ExtensionRunner {
         }
         return result;
     }
+    /** Returns the event's own action unless a handler overrides it; the last override wins. */
+    async emitCacheWarmingDecision(event) {
+        const ctx = this.createContext();
+        let action = event.action;
+        for (const { ext, handlers } of snapshotEventHandlers(this.extensions, event.type)) {
+            for (const handler of handlers) {
+                try {
+                    const result = (await handler(event, ctx));
+                    if (result?.action !== undefined)
+                        action = result.action;
+                }
+                catch (err) {
+                    this.emitError({
+                        extensionPath: ext.path,
+                        event: event.type,
+                        error: err instanceof Error ? err.message : String(err),
+                        stack: err instanceof Error ? err.stack : undefined,
+                    });
+                }
+            }
+        }
+        return action;
+    }
     async emitMessageEnd(event) {
         const ctx = this.createContext();
         let currentMessage = event.message;
         let modified = false;
-        for (const ext of this.extensions) {
-            const handlers = ext.handlers.get("message_end");
-            if (!handlers || handlers.length === 0)
-                continue;
+        for (const { ext, handlers } of snapshotEventHandlers(this.extensions, "message_end")) {
             for (const handler of handlers) {
                 try {
                     const currentEvent = { ...event, message: currentMessage };
@@ -694,10 +804,7 @@ export class ExtensionRunner {
         const ctx = this.createContext();
         const currentEvent = { ...event };
         let modified = false;
-        for (const ext of this.extensions) {
-            const handlers = ext.handlers.get("tool_result");
-            if (!handlers || handlers.length === 0)
-                continue;
+        for (const { ext, handlers } of snapshotEventHandlers(this.extensions, "tool_result")) {
             for (const handler of handlers) {
                 try {
                     const handlerResult = (await handler(currentEvent, ctx));
@@ -745,10 +852,7 @@ export class ExtensionRunner {
     async emitToolCall(event) {
         const ctx = this.createContext();
         let result;
-        for (const ext of this.extensions) {
-            const handlers = ext.handlers.get("tool_call");
-            if (!handlers || handlers.length === 0)
-                continue;
+        for (const { handlers } of snapshotEventHandlers(this.extensions, "tool_call")) {
             for (const handler of handlers) {
                 const handlerResult = await handler(event, ctx);
                 if (handlerResult) {
@@ -763,16 +867,16 @@ export class ExtensionRunner {
     }
     async emitUserBash(event) {
         const ctx = this.createContext();
-        for (const ext of this.extensions) {
-            const handlers = ext.handlers.get("user_bash");
-            if (!handlers || handlers.length === 0)
-                continue;
+        for (const { ext, handlers } of snapshotEventHandlers(this.extensions, "user_bash")) {
             for (const handler of handlers) {
                 try {
                     const handlerResult = await handler(event, ctx);
-                    if (handlerResult) {
-                        return handlerResult;
+                    if (handlerResult === undefined)
+                        continue;
+                    if (!isUserBashEventResult(handlerResult)) {
+                        throw new Error("Invalid user_bash handler result: return undefined for local execution or exactly one valid { operations } or { result } object");
                     }
+                    return handlerResult;
                 }
                 catch (err) {
                     const message = err instanceof Error ? err.message : String(err);
@@ -783,25 +887,33 @@ export class ExtensionRunner {
                         error: message,
                         stack,
                     });
+                    throw err;
                 }
             }
         }
         return undefined;
     }
+    /**
+     * Run the request-time transforms in two phases. `context` handlers see the conversation
+     * only and Pi restores the prompt and tool state after each; `context_with_system`
+     * handlers then see the full transcript and their output is used as returned.
+     */
     async emitContext(messages) {
         const ctx = this.createContext();
         let currentMessages = structuredClone(messages);
-        for (const ext of this.extensions) {
-            const handlers = ext.handlers.get("context");
-            if (!handlers || handlers.length === 0)
-                continue;
+        for (const { ext, handlers } of snapshotEventHandlers(this.extensions, "context")) {
             for (const handler of handlers) {
                 try {
-                    const event = { type: "context", messages: currentMessages };
-                    const handlerResult = await handler(event, ctx);
-                    if (handlerResult && handlerResult.messages) {
-                        currentMessages = handlerResult.messages;
-                    }
+                    const visibleMessages = currentMessages.filter((message) => message.role !== "system");
+                    const visibleSnapshot = visibleMessages.slice();
+                    const event = { type: "context", messages: visibleMessages };
+                    const handlerResult = (await handler(event, ctx));
+                    // Handlers may return a new list or edit event.messages in place.
+                    const returned = handlerResult?.messages ??
+                        (sameMessages(visibleMessages, visibleSnapshot) ? undefined : visibleMessages);
+                    if (!returned)
+                        continue;
+                    currentMessages = restoreSystemMessages(currentMessages, visibleSnapshot, returned);
                 }
                 catch (err) {
                     const message = err instanceof Error ? err.message : String(err);
@@ -815,15 +927,41 @@ export class ExtensionRunner {
                 }
             }
         }
+        for (const { ext, handlers } of snapshotEventHandlers(this.extensions, "context_with_system")) {
+            for (const handler of handlers) {
+                try {
+                    const hadLeadingSystemMessage = currentMessages[0]?.role === "system";
+                    const event = { type: "context_with_system", messages: currentMessages };
+                    const handlerResult = (await handler(event, ctx));
+                    currentMessages = handlerResult?.messages ?? currentMessages;
+                    // Providers read the prompt and initial tools from the leading system message.
+                    // Losing it is never intended; report it but honor the handler's output.
+                    if (hadLeadingSystemMessage && currentMessages[0]?.role !== "system") {
+                        this.emitError({
+                            extensionPath: ext.path,
+                            event: "context_with_system",
+                            error: "Handler removed the leading system message; the request has no prompt or initial tool declarations. Keep it at index 0 or replace a dropped prefix with getCurrentSystemMessage().",
+                        });
+                    }
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    const stack = err instanceof Error ? err.stack : undefined;
+                    this.emitError({
+                        extensionPath: ext.path,
+                        event: "context_with_system",
+                        error: message,
+                        stack,
+                    });
+                }
+            }
+        }
         return currentMessages;
     }
     async emitBeforeProviderRequest(payload) {
         const ctx = this.createContext();
         let currentPayload = payload;
-        for (const ext of this.extensions) {
-            const handlers = ext.handlers.get("before_provider_request");
-            if (!handlers || handlers.length === 0)
-                continue;
+        for (const { ext, handlers } of snapshotEventHandlers(this.extensions, "before_provider_request")) {
             for (const handler of handlers) {
                 try {
                     const event = {
@@ -851,10 +989,7 @@ export class ExtensionRunner {
     }
     async emitBeforeProviderHeaders(headers) {
         const ctx = this.createContext();
-        for (const ext of this.extensions) {
-            const handlers = ext.handlers.get("before_provider_headers");
-            if (!handlers || handlers.length === 0)
-                continue;
+        for (const { ext, handlers } of snapshotEventHandlers(this.extensions, "before_provider_headers")) {
             for (const handler of handlers) {
                 try {
                     // Handlers mutate `headers` in place; the return value is ignored.
@@ -878,37 +1013,34 @@ export class ExtensionRunner {
         }
         return headers;
     }
-    async emitBeforeAgentStart(prompt, images, systemPrompt, systemPromptOptions) {
-        let currentSystemPrompt = systemPrompt;
+    async emitBeforeAgentStart(prompt, images, systemPromptOptions) {
+        const currentOptions = normalizeBuildSystemPromptOptions(systemPromptOptions);
+        const renderCurrentSystemPrompt = () => buildSystemPrompt(currentOptions);
         const ctx = Object.defineProperties({}, Object.getOwnPropertyDescriptors(this.createContext()));
         ctx.getSystemPrompt = () => {
             this.assertActive();
-            return currentSystemPrompt;
+            return renderCurrentSystemPrompt();
         };
         const messages = [];
-        let systemPromptModified = false;
-        for (const ext of this.extensions) {
-            const handlers = ext.handlers.get("before_agent_start");
-            if (!handlers || handlers.length === 0)
-                continue;
+        for (const { ext, handlers } of snapshotEventHandlers(this.extensions, "before_agent_start")) {
             for (const handler of handlers) {
                 try {
                     const event = {
                         type: "before_agent_start",
                         prompt,
                         images,
-                        systemPrompt: currentSystemPrompt,
-                        systemPromptOptions,
+                        get systemPrompt() {
+                            return renderCurrentSystemPrompt();
+                        },
+                        systemPromptOptions: currentOptions,
                     };
                     const handlerResult = await handler(event, ctx);
                     if (handlerResult) {
                         const result = handlerResult;
-                        if (result.message) {
+                        if (result.message)
                             messages.push(result.message);
-                        }
                         if (result.systemPrompt !== undefined) {
-                            currentSystemPrompt = result.systemPrompt;
-                            systemPromptModified = true;
+                            currentOptions.forceSystemPrompt = result.systemPrompt;
                         }
                     }
                 }
@@ -924,23 +1056,14 @@ export class ExtensionRunner {
                 }
             }
         }
-        if (messages.length > 0 || systemPromptModified) {
-            return {
-                messages: messages.length > 0 ? messages : undefined,
-                systemPrompt: systemPromptModified ? currentSystemPrompt : undefined,
-            };
-        }
-        return undefined;
+        return { messages, systemPromptOptions: currentOptions };
     }
     async emitResourcesDiscover(cwd, reason) {
         const ctx = this.createContext();
         const skillPaths = [];
         const promptPaths = [];
         const themePaths = [];
-        for (const ext of this.extensions) {
-            const handlers = ext.handlers.get("resources_discover");
-            if (!handlers || handlers.length === 0)
-                continue;
+        for (const { ext, handlers } of snapshotEventHandlers(this.extensions, "resources_discover")) {
             for (const handler of handlers) {
                 try {
                     const event = { type: "resources_discover", cwd, reason };
@@ -975,8 +1098,8 @@ export class ExtensionRunner {
         const ctx = this.createContext();
         let currentText = text;
         let currentImages = images;
-        for (const ext of this.extensions) {
-            for (const handler of ext.handlers.get("input") ?? []) {
+        for (const { ext, handlers } of snapshotEventHandlers(this.extensions, "input")) {
+            for (const handler of handlers) {
                 try {
                     const event = {
                         type: "input",