apex-code 0.0.1-alpha.1 → 0.0.1-alpha.3

package/dist/core/agent-session.js

@@ -15,7 +15,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname } from "node:path";
 import { contentText } from "@earendil-works/pi-ai";
-import { clampThinkingLevel, cleanupSessionResources, getSupportedThinkingLevels, isContextOverflow, isRecoverableLength, isRetryableAssistantError, modelsAreEqual, resetApiProviders, streamSimple, } from "@earendil-works/pi-ai/compat";
+import { clampThinkingLevel, cleanupSessionResources, getSupportedThinkingLevels, isContextOverflow, isRecoverableLength, isRetryableAssistantError, modelsAreEqual, resetApiProviders, } from "@earendil-works/pi-ai/compat";
 import { getThemeByName, theme } from "../modes/interactive/theme/theme.js";
 import { stripFrontmatter } from "../utils/frontmatter.js";
 import { resolvePath } from "../utils/paths.js";
@@ -24,19 +24,25 @@ import { normalizeToolResultImages } from "../utils/tool-result-images.js";
 import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
 import { executeBashWithOperations } from "./bash-executor.js";
 import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateTokens, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
+import { evictionBudget, installContextPipeline, isDefaultStreamFunction } from "./context/pipeline.js";
 import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
+import { SessionEvidenceSink } from "./evidence.js";
 import { exportSessionToHtml } from "./export-html/index.js";
 import { createToolHtmlRenderer } from "./export-html/tool-renderer.js";
 import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
 import { ModelRegistry } from "./model-registry.js";
+import { evaluateToolCall } from "./permissions/gate.js";
+import { createInteractiveResponder } from "./permissions/responder.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
-import { CURRENT_SESSION_VERSION, getLatestCompactionEntry } from "./session-manager.js";
+import { CURRENT_SESSION_VERSION, getLatestCompactionEntry, TODO_CUSTOM_ENTRY_TYPE, } from "./session-manager.js";
 import { createSyntheticSourceInfo } from "./source-info.js";
 import { buildSystemPrompt } from "./system-prompt.js";
 import { createLocalBashOperations } from "./tools/bash.js";
 import { createAllToolDefinitions } from "./tools/index.js";
+import { createTodoWriteToolDefinition } from "./tools/todo-write.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
+import { createToolSchemaToolDefinition } from "./tools/tool-schema.js";
 import { addUsageToTotals, createUsageTotals } from "./usage-totals.js";
 /**
  * Parse a skill block from message text.
@@ -118,6 +124,8 @@ export class AgentSession {
     _excludedToolNames;
     _baseToolsOverride;
     _sessionStartEvent;
+    _permissionGate;
+    _evidenceSink;
     _extensionUIContext;
     _extensionMode = "print";
     _extensionCommandContextActions;
@@ -131,6 +139,7 @@ export class AgentSession {
     _toolDefinitions = new Map();
     _toolPromptSnippets = new Map();
     _toolPromptGuidelines = new Map();
+    _loadedDeferredSchemas = new Set();
     // Base system prompt (without extension appends) - used to apply fresh appends each turn
     _baseSystemPrompt = "";
     _baseSystemPromptOptions;
@@ -150,11 +159,14 @@ export class AgentSession {
         this._excludedToolNames = config.excludedToolNames ? new Set(config.excludedToolNames) : undefined;
         this._baseToolsOverride = config.baseToolsOverride;
         this._sessionStartEvent = config.sessionStartEvent ?? { type: "session_start", reason: "startup" };
+        this._permissionGate = config.permissionGate;
+        this._evidenceSink = config.evidenceSink ?? new SessionEvidenceSink(this.sessionManager);
         // Always subscribe to agent events for internal handling
         // (session persistence, extensions, auto-compaction, retry logic)
         this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
         this._installAgentToolHooks();
         this._installAgentNextTurnRefresh();
+        this._installContextPipeline();
         this._buildRuntime({
             activeToolNames: this._initialActiveToolNames,
             includeAllExtensionTools: true,
@@ -193,7 +205,7 @@ export class AgentSession {
         throw new Error(formatNoApiKeyFoundMessage(model.provider));
     }
     async _getSummarizationRequestAuth(model) {
-        if (this.agent.streamFunction === streamSimple) {
+        if (isDefaultStreamFunction(this.agent.streamFunction)) {
             return this._getRequiredRequestAuth(model);
         }
         try {
@@ -223,25 +235,63 @@ export class AgentSession {
     _installAgentToolHooks() {
         this.agent.beforeToolCall = async ({ toolCall, args }) => {
             const runner = this._extensionRunner;
-            if (!runner.hasHandlers("tool_call")) {
-                return undefined;
-            }
-            try {
-                return await runner.emitToolCall({
-                    type: "tool_call",
-                    toolName: toolCall.name,
-                    toolCallId: toolCall.id,
-                    input: args,
-                });
-            }
-            catch (err) {
-                if (err instanceof Error) {
-                    throw err;
+            if (runner.hasHandlers("tool_call")) {
+                let extensionResult;
+                try {
+                    extensionResult = await runner.emitToolCall({
+                        type: "tool_call",
+                        toolName: toolCall.name,
+                        toolCallId: toolCall.id,
+                        input: args,
+                    });
                 }
-                throw new Error(`Extension failed, blocking execution: ${String(err)}`);
+                catch (err) {
+                    if (err instanceof Error) {
+                        throw err;
+                    }
+                    throw new Error(`Extension failed, blocking execution: ${String(err)}`);
+                }
+                // A blocking extension remains authoritative. A non-blocking result
+                // (including a mutation-only `{}`) must still pass the permission gate,
+                // which evaluates the extension's final input below.
+                if (extensionResult?.block === true)
+                    return extensionResult;
+            }
+            // Permission gate (roadmap Phase 2a, ADR 0004). Off by default — see
+            // AgentSessionConfig.permissionGate. When present, every registered tool
+            // call passes through it (contracts.md invariant 2): this is the seam,
+            // not a per-tool opt-in.
+            if (this._permissionGate) {
+                const decision = await evaluateToolCall(toolCall.name, args, {
+                    ...this._permissionGate,
+                    getContract: (name) => this.getToolDefinition(name)?.contract,
+                    getResponder: () => this._extensionMode === "tui" && this._extensionUIContext
+                        ? createInteractiveResponder(this._extensionUIContext)
+                        : undefined,
+                });
+                if (decision.block)
+                    return { block: true, reason: decision.reason };
             }
+            return undefined;
         };
         this.agent.afterToolCall = async ({ toolCall, args, result, isError }) => {
+            const definition = this.getToolDefinition(toolCall.name);
+            if (this._evidenceSink && definition?.contract) {
+                try {
+                    const records = definition.contract.evidence.capture(args, result);
+                    if (!records.every((record) => definition.contract?.evidence.emits.has(record.kind))) {
+                        throw new Error("Evidence capture emitted a kind not declared by its tool contract");
+                    }
+                    if (records.length > 0)
+                        this._evidenceSink.record({ toolName: toolCall.name, records });
+                }
+                catch (error) {
+                    this._evidenceSink.recordDiagnostic?.({
+                        toolName: toolCall.name,
+                        reason: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
             const runner = this._extensionRunner;
             const hookResult = runner.hasHandlers("tool_result")
                 ? await runner.emitToolResult({
@@ -291,6 +341,46 @@ export class AgentSession {
             };
         };
     }
+    /**
+     * Installs the context pipeline settled in `docs/architecture/contracts.md` § 2:
+     * deferred-schema resolution → tool-result eviction → compaction. Compaction
+     * already runs reactively from `_checkCompaction`, after a response comes back
+     * over-threshold or overflowed; this method only adds the two stages that run
+     * *ahead of* every LLM request, so that reactive check is reached less often
+     * because the request it is reacting to is smaller. It does not call into
+     * compaction and does not need to.
+     *
+     * The wiring itself — where each stage attaches, and why they land in different
+     * seams (`transformContext` for eviction, `streamFunction` for schema
+     * projection) — lives in `./context/pipeline.ts`'s `installContextPipeline`,
+     * shared with the offline replay harness so there is one implementation, not
+     * two. This method only supplies this session's two dependencies: a contract
+     * lookup backed by `getToolDefinition`, and a budget thunk (never cached — see
+     * `_evictionBudget`, which reads live `this.model` / `this.settingsManager` on
+     * every call, so a model switch or settings edit mid-session takes effect on
+     * the very next request).
+     */
+    _installContextPipeline() {
+        installContextPipeline(this.agent, {
+            contractLookup: (name) => this.getToolDefinition(name)?.contract,
+            loadedSchemaNames: this._loadedDeferredSchemas,
+            evictionBudget: () => this._evictionBudget(),
+        });
+    }
+    /**
+     * Token budget for `evictToolResults`'s outbound pass, derived from the same
+     * quantities compaction already uses for its own threshold
+     * (`getCompactionSettings()`; see `shouldCompact` in
+     * `core/compaction/compaction.ts`). The formula itself is `./context/
+     * pipeline.ts`'s `evictionBudget` — see that function's comment for the "why
+     * half of headroom" reasoning; this method only supplies production's real
+     * `contextWindow` / `reserveTokens` inputs.
+     */
+    _evictionBudget() {
+        const contextWindow = this.model?.contextWindow ?? 0;
+        const { reserveTokens } = this.settingsManager.getCompactionSettings();
+        return evictionBudget(contextWindow, reserveTokens);
+    }
     // =========================================================================
     // Event Subscription
     // =========================================================================
@@ -611,12 +701,16 @@ export class AgentSession {
      * Get all configured tools with name, description, parameter schema, prompt guidelines, and source metadata.
      */
     getAllTools() {
-        return Array.from(this._toolDefinitions.values()).map(({ definition, sourceInfo }) => ({
+        const schemaToolActive = this.getActiveToolNames().includes("tool_schema");
+        return Array.from(this._toolDefinitions.values())
+            .filter(({ definition }) => definition.name !== "tool_schema" || schemaToolActive)
+            .map(({ definition, sourceInfo }) => ({
             name: definition.name,
             description: definition.description,
             parameters: definition.parameters,
             promptGuidelines: definition.promptGuidelines,
             sourceInfo,
+            unclassified: !("contract" in definition),
         }));
     }
     getToolDefinition(name) {
@@ -2012,6 +2106,14 @@ export class AgentSession {
                 }
             }
         }
+        const hasDeferredActiveTool = nextActiveToolNames.some((name) => {
+            const contract = definitionRegistry.get(name)?.definition
+                ?.contract;
+            return contract?.context.deferSchema === true;
+        });
+        if (hasDeferredActiveTool && this._toolRegistry.has("tool_schema")) {
+            nextActiveToolNames.push("tool_schema");
+        }
         this.setActiveToolsByName([...new Set(nextActiveToolNames)]);
     }
     _buildRuntime(options) {
@@ -2027,6 +2129,22 @@ export class AgentSession {
                 read: { autoResizeImages },
                 bash: { commandPrefix: shellCommandPrefix, shellPath },
             });
+        baseToolDefinitions.tool_schema = createToolSchemaToolDefinition({
+            getTool: (name) => {
+                if (!this.getActiveToolNames().includes(name))
+                    return undefined;
+                const definition = this._toolDefinitions.get(name)?.definition;
+                return definition ? { name: definition.name, parameters: definition.parameters } : undefined;
+            },
+            markLoaded: (name) => {
+                this._loadedDeferredSchemas.add(name);
+            },
+        });
+        baseToolDefinitions.todo_write = createTodoWriteToolDefinition({
+            write: (todos) => {
+                this.sessionManager.appendCustomEntry(TODO_CUSTOM_ENTRY_TYPE, todos);
+            },
+        });
         this._baseToolDefinitions = new Map(Object.entries(baseToolDefinitions).map(([name, tool]) => [name, tool]));
         const extensionsResult = this._resourceLoader.getExtensions();
         if (options.flagValues) {