@caupulican/pi-adaptative 0.81.40 → 0.81.42

package/dist/core/agent-session.js

@@ -1,4 +1,4 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { basename, dirname } from "node:path";
 import { compactToolResultDetailsForRetention, createCustomMessage, DEFAULT_STREAM_IDLE, withStreamIdleWatchdog, } from "@caupulican/pi-agent-core";
@@ -21,12 +21,11 @@ import { appendWorkerClaimSnapshot, getWorkerClaimSnapshots } from "./delegation
 import { FailureCorpusRecorder } from "./failure-corpus.js";
 import { ForegroundRecoveryController } from "./foreground-recovery-controller.js";
 import { GatewayRegistry } from "./gateways/channel-provider.js";
-import { GoalLoopController } from "./goal-loop-controller.js";
-import { buildGoalRuntimeSnapshot, } from "./goals/goal-runtime-snapshot.js";
-import { applyGoalEvent } from "./goals/goal-state.js";
-import { appendGoalStateSnapshot, getLatestGoalStateSnapshot } from "./goals/session-goal-state.js";
+import { injectCompactGoalContext } from "./goals/compact-goal-context.js";
+import { GoalSessionController } from "./goals/goal-session-controller.js";
 import { constrainStreamIdleToHttpTimeout } from "./http-dispatcher.js";
-import { beginHumanInputRequest, createHumanInputRequest, formatHumanInputAnswerText, getLatestHumanInputSnapshots, getResumableHumanInputSnapshot, getWorkerHumanInputsRequiringDelivery, HUMAN_INPUT_WORKER_RESPONSE_CUSTOM_TYPE, resolveHumanInput, } from "./human-input.js";
+import { getWorkerHumanInputsRequiringDelivery } from "./human-input.js";
+import { HumanInputController } from "./human-input-controller.js";
 import { appendLearningDecisionSnapshot, getLearningDecisionSnapshots } from "./learning/session-learning-decision.js";
 import { isPromotedFrontmatter, SkillCurator } from "./learning/skill-curator.js";
 import { LocalRuntimeController } from "./local-runtime-controller.js";
@@ -37,6 +36,7 @@ import { formatModelRouterModel, ModelRouterController } from "./model-router-co
 import { ModelSelectionController } from "./model-selection-controller.js";
 import { ModelAdaptationStore } from "./models/adaptation-store.js";
 import { HF_TRANSFORMERS_PROVIDER, OLLAMA_PROVIDER } from "./models/local-registration.js";
+import { isLoopbackModelEndpoint } from "./models/model-endpoint.js";
 import { DEFAULT_ADAPTIVE_STREAM_IDLE_CEILING_MS, estimateContextPromptTokens, resolveAdaptiveStreamIdleOptions, withModelPerfProfile, } from "./models/perf-profile.js";
 import { resolveConfiguredOrchestrationModel } from "./orchestration/model-binding.js";
 import { validateOrchestrationProfile } from "./orchestration/profile-registry.js";
@@ -93,63 +93,8 @@ function tagRawness(wrapped, innerIsRawStreamSimple) {
     Object.defineProperty(wrapped, RAW_STREAM_MARKER, { value: innerIsRawStreamSimple });
     return wrapped;
 }
-/**
- * Parse a skill block from message text.
- * Returns null if the text doesn't contain a skill block.
- */
-export function parseSkillBlock(text) {
-    const match = text.match(/^<skill name="([^"]+)" location="([^"]+)">\n([\s\S]*?)\n<\/skill>(?:\n\n([\s\S]+))?$/);
-    if (!match)
-        return null;
-    return {
-        name: match[1],
-        location: match[2],
-        content: match[3],
-        userMessage: match[4]?.trim() || undefined,
-    };
-}
-/** customType for spawned-usage roll-up entries (Cost Aggregation, Model A). */
-export const SPAWNED_USAGE_CUSTOM_TYPE = "spawned_usage";
-/**
- * customType for a persisted runaway-loop-backstop entry: the agent loop stopped a turn stuck
- * repeating one identical tool-call signature. This is the session-log/telemetry sink for
- * {@link Agent.onRunawayStop} — see `_installAgentToolHooks`.
- */
-export const RUNAWAY_STOP_CUSTOM_TYPE = "runaway_stop";
-/**
- * customType for a persisted tool-validation-escalation entry: the agent loop bounced the same
- * tool-call validation failure enough times to escalate. This is the session-log/telemetry sink for
- * {@link Agent.onToolValidationEscalation} — see `_installAgentToolHooks`.
- */
-export const TOOL_VALIDATION_ESCALATION_CUSTOM_TYPE = "tool_validation_escalation";
-/** Fallback {@link IsolatedCompletionOptions.laneKind} for callers that do not tag their lane. */
-export const DEFAULT_ISOLATED_LANE_KIND = "isolated";
-/**
- * Derive a STABLE synthetic cache-affinity key for an isolated completion lane. Isolated calls
- * deliberately never carry the real session id (see reflection-controller.ts's isolation invariants —
- * an isolated call must not entangle with the main session), which today also means every isolated
- * call looks like a brand-new, uncorrelated session to providers with session-affinity headers /
- * `prompt_cache_key` (anthropic.ts's `x-session-affinity`, openai-responses.ts /
- * openai-completions.ts's `prompt_cache_key`), defeating their cache routing.
- *
- * This key is deterministic per `(laneKind, model, systemPrompt)` — the SAME lane calling the SAME
- * model with the SAME (static) system prompt always gets the SAME key, so repeat calls route to the
- * same cache-warm backend — while remaining fully synthetic: it is a salted hash, namespaced with a
- * `lane:` prefix, and never derived from or equal to the real session id.
- */
-export function computeLaneAffinityKey(laneKind, model, systemPrompt) {
-    const modelKey = model ? `${model.provider}/${model.id}` : "unknown-model";
-    // NUL-separated fields: laneKind/modelKey are drawn from small caller-controlled vocabularies
-    // that never contain a raw NUL, so this cannot field-collide the way a plain colon/space join could.
-    const digest = createHash("sha256")
-        .update(["pi-lane-affinity-v1", laneKind, modelKey, systemPrompt].join("\u0000"))
-        .digest("hex")
-        .slice(0, 32);
-    return `lane:${laneKind}:${digest}`;
-}
-// ============================================================================
-// Constants
-// ============================================================================
+export * from "./agent-session-contracts.js";
+import { RUNAWAY_STOP_CUSTOM_TYPE, TOOL_VALIDATION_ESCALATION_CUSTOM_TYPE } from "./agent-session-contracts.js";
 // ============================================================================
 // AgentSession Class
 // ============================================================================
@@ -168,9 +113,6 @@ export class AgentSession {
     _queuedExtensionCommands = [];
     _pendingNextTurnMessages = [];
     _streamingPromptSubmissionTail = Promise.resolve();
-    /** Serializes owner-input overlays so concurrent worker terminals cannot replace each other. */
-    _humanInputTail = Promise.resolve();
-    _activeHumanInputRequestIds = new Set();
     /**
      * The last tool set requested via setActiveToolsByName BEFORE model-capability filtering, so
      * switching from a small-window model back to a large one restores the full requested set.
@@ -207,6 +149,7 @@ export class AgentSession {
      * background-lane-controller.ts); owns the lane timers/guards, the last research-lane skip
      * reason, the live LaneTracker, and the in-flight research/worker abort controllers. */
     _backgroundLanes;
+    _humanInput;
     /** Plug-and-play memory subsystem (see memory-controller.ts); owns the OKF retrieval provider, the
      * latest retrieval/prompt-inclusion reports, the reload-safe MemoryManager, the recall
      * effectiveness tracker, and the extension-contributed pending providers. */
@@ -253,9 +196,8 @@ export class AgentSession {
     /** Native reflection engine + learning-apply/rollback path (see reflection-controller.ts); owns no
      * session state, applies durable writes through the bundled memory tool and the session log. */
     _reflection;
-    /** Bounded goal auto-continuation loop (see goal-loop-controller.ts); reads goal state fresh
-     * each pass and re-enters the session's own prompt path. */
-    _goalContinuation;
+    /** Durable goal lifecycle, accounting, and raw continuation loop. */
+    _goals;
     _isChildSession;
     _baseToolsOverride;
     _sessionStartEvent;
@@ -401,6 +343,30 @@ export class AgentSession {
             getLearningAuditRecords: () => this.getLearningAuditRecords(),
         });
         this._modelRegistry = config.modelRegistry;
+        this._humanInput = new HumanInputController({
+            getSessionManager: () => this.sessionManager,
+            getUIContext: () => this._extensionUIContext,
+            getExtensionMode: () => this._extensionMode,
+            waitForIdle: () => this.agent.waitForIdle(),
+            isDisposed: () => this._disposed,
+            isStreaming: () => this.isStreaming,
+            getModel: () => this.model,
+            getArtifactStore: () => this._getToolArtifactStore(),
+            getImageStore: () => this._getSessionImageStore(),
+            runAgentPrompt: (messages) => this._runAgentPrompt(messages),
+            sendCustomMessage: (message, options) => this.sendCustomMessage(message, options),
+            emitWarning: (message) => this._emit({ type: "warning", message }),
+        });
+        this._goals = new GoalSessionController({
+            getSessionManager: () => this.sessionManager,
+            getModelProvider: () => this.model?.provider,
+            getLaneRecords: () => this._backgroundLanes.getLaneRecords(),
+            getTaskRuntimeSnapshot: () => this._backgroundLanes.getTaskRuntimeSnapshot(),
+            synchronizeGoalState: (state) => this._backgroundLanes.synchronizeGoalState(state),
+            scheduleGoalAutoContinueFromIdle: () => this._backgroundLanes.scheduleGoalAutoContinueFromIdle(),
+            prompt: (text, options) => this.prompt(text, options),
+            emitWarning: (message) => this._emit({ type: "warning", message }),
+        });
         this._backgroundLanes = new BackgroundLaneController({
             isDisposed: () => this._disposed,
             isChildSession: () => this._isChildSession,
@@ -409,6 +375,7 @@ export class AgentSession {
             getAgentDir: () => this._agentDir,
             getSessionManager: () => this.sessionManager,
             getSettingsManager: () => this.settingsManager,
+            getResourceLoader: () => this._resourceLoader,
             getActiveOrchestrationProfile: () => config.orchestrationProfile,
             getModelRegistry: () => this._modelRegistry,
             isModelExhausted: (model) => this._foregroundRecovery.isModelExhausted(`${model.provider}/${model.id}`),
@@ -422,17 +389,18 @@ export class AgentSession {
             emitAutonomyTelemetry: (event) => this._emitAutonomyTelemetry(event),
             getGoalStateSnapshot: () => this.getGoalStateSnapshot(),
             getGoalRuntimeSnapshot: (settings) => this.getGoalRuntimeSnapshot(settings),
+            markGoalToolUnavailable: () => this._goals.markToolUnavailable(),
             getEvidenceBundleSnapshot: () => this.getEvidenceBundleSnapshot(),
             saveEvidenceBundleSnapshot: (bundle) => this.saveEvidenceBundleSnapshot(bundle),
             saveWorkerClaimSnapshot: (claim, request) => this.saveWorkerClaimSnapshot(claim, request),
-            queueWorkerHumanInput: (request) => this._queueWorkerHumanInput(request),
+            queueWorkerHumanInput: (request) => this._humanInput.queueWorkerInput(request),
             readMemoryForLane: (query) => this._memory.readMemoryForLane(query),
             addSpawnedUsage: (usage, opts) => this.addSpawnedUsage(usage, opts),
             runIsolatedCompletion: (opts) => this.runIsolatedCompletion(opts),
             // RAW loop, deliberately bypassing the public `continueGoalLoop` — that method now delegates
             // to this controller's own `continueGoalLoopExclusive` guard, so routing through it here would
             // recurse into the guard from inside itself instead of driving the actual continuation pass.
-            continueGoalLoop: (options) => this._goalContinuation.continueGoalLoop(options),
+            continueGoalLoop: (options) => this._goals.continueLoop(options),
             collectWorkspaceSources: (args) => this._collectWorkspaceSources(args),
         });
         this._memory = new MemoryController({
@@ -569,11 +537,6 @@ export class AgentSession {
             addSpawnedUsage: (usage, opts) => this.addSpawnedUsage(usage, opts),
             saveLearningDecisionSnapshot: (decision) => this.saveLearningDecisionSnapshot(decision),
         });
-        this._goalContinuation = new GoalLoopController({
-            getGoalRuntimeSnapshot: (settings) => this.getGoalRuntimeSnapshot(settings),
-            prompt: (text, options) => this.prompt(text, options),
-            recordGoalContinuationPass: (pass) => this.recordGoalContinuationPass(pass),
-        });
         this._extensionRunnerRef = config.extensionRunnerRef;
         this._initialActiveToolNames = config.orchestrationProfile
             ? [...config.orchestrationProfile.toolNames]
@@ -632,7 +595,8 @@ export class AgentSession {
             getExcludedToolNames: () => this._excludedToolNames,
             deriveToolProfileFilter: () => this._profileFilter.deriveToolProfileFilter(),
             isToolOrCommandAllowedByProfile: (name) => this._profileFilter.isToolOrCommandAllowedByProfile(name),
-            filterExtensionsForRuntime: (extensions) => this._profileFilter.filterExtensionsForRuntime(extensions),
+            isExtensionPathAllowed: (path, authority, baseDir) => this._profileFilter.isExtensionPathAllowed(path, authority, baseDir),
+            filterExtensionsForRuntime: (extensions, explicitLiveExtensionPaths) => this._profileFilter.filterExtensionsForRuntime(extensions, explicitLiveExtensionPaths),
             setUnboundToolGrantWarnings: (warnings) => {
                 this._unboundToolGrantWarnings = warnings;
             },
@@ -662,6 +626,7 @@ export class AgentSession {
             saveTaskStepsStateSnapshot: (state) => this.saveTaskStepsStateSnapshot(state),
             getContextGcReport: (messages) => this.getContextGcReport(messages),
             startWorkerDelegation: (request) => this._backgroundLanes.startWorkerDelegation(request),
+            workerAgentControl: this._backgroundLanes,
             getOrchestrationProfileCatalog: () => this._backgroundLanes.getOrchestrationProfileCatalog(),
             getWorkerLaneRecords: () => this._backgroundLanes.getLaneRecords(),
             getWorkerClaimSnapshots: () => this.getWorkerClaimSnapshots(),
@@ -877,15 +842,7 @@ export class AgentSession {
         }
     }
     _isWarmableLocalModel(model) {
-        if (model.api !== "openai-completions")
-            return false;
-        try {
-            const hostname = new URL(model.baseUrl).hostname.toLowerCase();
-            return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]";
-        }
-        catch {
-            return false;
-        }
+        return model.api === "openai-completions" && isLoopbackModelEndpoint(model.baseUrl);
     }
     /**
      * True when the session's stream fn is the raw `streamSimple` provider entry (directly, or as the
@@ -903,7 +860,7 @@ export class AgentSession {
             }
             throw new Error(result.error);
         }
-        if (result.apiKey) {
+        if (this._modelRegistry.canUseResolvedRequestAuth(model, result)) {
             return { apiKey: result.apiKey, headers: result.headers };
         }
         const isOAuth = this._modelRegistry.isUsingOAuth(model);
@@ -983,7 +940,7 @@ export class AgentSession {
             // character caps are the only budget protection for this block -- load-bearing,
             // not merely defensive.
             const gcMessages = this._maybeAppendMemoryEvidenceBlock(enforcementResult.messages, memoryReport);
-            return gcMessages;
+            return injectCompactGoalContext(gcMessages, this.getGoalStateSnapshot());
         };
     }
     /**
@@ -1542,7 +1499,7 @@ export class AgentSession {
             }
         }
         if (event.type === "agent_end" && !this._willRetryAfterAgentEnd(event)) {
-            this._schedulePendingWorkerHumanInputs();
+            this._humanInput.schedulePendingWorkerInputs();
         }
     };
     _willRetryAfterAgentEnd(event) {
@@ -1770,7 +1727,7 @@ export class AgentSession {
             this.agent.afterToolCall = undefined;
             this.agent.transformContext = undefined;
         });
-        safely(() => this._extensionRunner.invalidate("This extension ctx is stale after session replacement or reload. Do not use a captured pi or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For reload, do not use the old ctx after await ctx.reload()."));
+        safely(() => this._extensionRunner.invalidate());
         safely(() => this._disconnectFromAgent());
         this._eventListeners = [];
         // Best-effort memory cleanup (release locks/handles). Write-side onSessionEnd is wired on a
@@ -2001,186 +1958,13 @@ export class AgentSession {
             await this._drainQueuedExtensionCommands();
         }
     }
-    _queueWorkerHumanInput(request) {
-        const existing = getLatestHumanInputSnapshots(this.sessionManager).find((snapshot) => snapshot.request.workerRequestId === request.workerRequestId);
-        if (existing)
-            return;
-        const blockerText = request.blockers
-            .slice(0, 4)
-            .map((blocker) => blocker.slice(0, 500))
-            .join("; ");
-        const question = createHumanInputRequest({
-            source: "worker",
-            workerRequestId: request.workerRequestId,
-            questions: [
-                {
-                    id: "worker_review",
-                    header: "Worker review",
-                    question: `${request.message.slice(0, 1_500)}${blockerText ? ` Blockers: ${blockerText}` : ""}`,
-                    options: [
-                        {
-                            label: "Review now",
-                            description: "Have the parent inspect the worker claim and evidence before reconciling it.",
-                        },
-                        {
-                            label: "Keep blocked",
-                            description: "Leave the worker result blocked and continue without accepting its output.",
-                        },
-                    ],
-                },
-            ],
-            acceptsImages: false,
-        });
-        beginHumanInputRequest(this.sessionManager, question);
-        if (!this.isStreaming)
-            this._scheduleWorkerHumanInput(question);
-    }
-    _schedulePendingWorkerHumanInputs() {
-        for (const snapshot of getWorkerHumanInputsRequiringDelivery(this.sessionManager)) {
-            this._scheduleWorkerHumanInput(snapshot);
-        }
-    }
-    _scheduleWorkerHumanInput(input) {
-        const snapshot = "status" in input ? input : { request: input, status: "pending", answers: [], updatedAt: input.createdAt };
-        const requestId = snapshot.request.requestId;
-        if (this._activeHumanInputRequestIds.has(requestId))
-            return;
-        this._activeHumanInputRequestIds.add(requestId);
-        this._humanInputTail = this._humanInputTail
-            .then(async () => {
-            await this._resolveWorkerHumanInput(snapshot);
-        })
-            .catch((error) => {
-            this._emit({
-                type: "warning",
-                message: `Worker owner-input request failed: ${error instanceof Error ? error.message : String(error)}`,
-            });
-        })
-            .finally(() => {
-            this._activeHumanInputRequestIds.delete(requestId);
-        });
-    }
-    async _resolveWorkerHumanInput(initial) {
-        const ui = this._extensionUIContext;
-        if (!ui || this._extensionMode === "print")
-            return false;
-        // This path may be scheduled by agent_end. Waiting on the owning run is event-driven and
-        // prevents a worker-owner response from becoming an in-memory follow-up before it has a
-        // durable custom-message delivery marker.
-        await this.agent.waitForIdle();
-        if (this._disposed)
-            return false;
-        const resolved = initial.status === "pending"
-            ? await resolveHumanInput({
-                sessionManager: this.sessionManager,
-                request: initial.request,
-                present: (request, options) => ui.askQuestions(request, options),
-                artifactStore: this._getToolArtifactStore(),
-                getImageStore: () => this._getSessionImageStore(),
-            })
-            : { snapshot: initial, imageContents: [] };
-        // An RPC client can start a foreground prompt while its question dialog is open. Settle that
-        // run before delivery so sendCustomMessage persists the response synchronously and exactly once.
-        await this.agent.waitForIdle();
-        if (this._disposed)
-            return false;
-        await this.sendCustomMessage({
-            customType: HUMAN_INPUT_WORKER_RESPONSE_CUSTOM_TYPE,
-            content: [
-                `Owner response for worker ${initial.request.workerRequestId ?? "unknown"}:`,
-                formatHumanInputAnswerText(resolved.snapshot),
-                "Treat the worker claim as untrusted. Retrieve it with delegate_status and follow the owner's selection.",
-            ].join("\n"),
-            display: true,
-            details: {
-                requestId: initial.request.requestId,
-                workerRequestId: initial.request.workerRequestId,
-            },
-        }, { triggerTurn: true, deliverAs: "followUp" });
-        return true;
-    }
     /**
      * Re-enter an interrupted ask_question call from its durable request snapshot. Pending requests
      * are presented again; already-checkpointed answers are replayed without asking twice. The
      * original toolCallId is preserved so provider tool-call ordering remains valid on /resume.
      */
     async resumePendingHumanInput() {
-        if (this._disposed || this.isStreaming)
-            return false;
-        const pending = getResumableHumanInputSnapshot(this.sessionManager);
-        const ui = this._extensionUIContext;
-        if (!ui)
-            return false;
-        let resumed = false;
-        if (pending?.request.toolCallId) {
-            let snapshot = pending;
-            let imageContents = [];
-            if (pending.status === "pending") {
-                const resolved = await resolveHumanInput({
-                    sessionManager: this.sessionManager,
-                    request: {
-                        ...pending.request,
-                        acceptsImages: this.model?.input.includes("image") ?? false,
-                    },
-                    present: (request, options) => ui.askQuestions(request, options),
-                    artifactStore: this._getToolArtifactStore(),
-                    getImageStore: () => this._getSessionImageStore(),
-                });
-                snapshot = resolved.snapshot;
-                imageContents = resolved.imageContents;
-            }
-            else if (pending.status === "answered") {
-                const imageStore = this._getSessionImageStore();
-                if (imageStore) {
-                    const referencedText = snapshot.answers
-                        .flatMap((answer) => [answer.custom ?? "", ...(answer.images?.map((image) => image.label) ?? [])])
-                        .join(" ");
-                    imageContents = imageStore.resolveReferences(referencedText);
-                }
-            }
-            const answerImageCount = snapshot.answers.reduce((total, answer) => total + (answer.images?.length ?? 0), 0);
-            const modelAcceptsImages = this.model?.input.includes("image") ?? false;
-            const missingImageNotice = answerImageCount > imageContents.length
-                ? `\n\n[${answerImageCount - imageContents.length} attached image(s) could not be restored from durable storage.]`
-                : "";
-            const unsupportedImageNotice = imageContents.length > 0 && !modelAcceptsImages
-                ? "\n\n[Attached images were retained but not sent because the selected model does not accept image input.]"
-                : "";
-            const toolResult = {
-                role: "toolResult",
-                toolCallId: pending.request.toolCallId,
-                toolName: pending.request.toolName ?? "ask_question",
-                content: [
-                    {
-                        type: "text",
-                        text: `${formatHumanInputAnswerText(snapshot)}${missingImageNotice}${unsupportedImageNotice}`,
-                    },
-                    ...(modelAcceptsImages ? imageContents : []),
-                ],
-                details: {
-                    questions: snapshot.request.questions,
-                    answers: snapshot.answers,
-                    cancelled: snapshot.status === "cancelled",
-                    ...(snapshot.reason ? { reason: snapshot.reason } : {}),
-                },
-                isError: false,
-                timestamp: Date.now(),
-            };
-            await this._runAgentPrompt(toolResult);
-            resumed = true;
-        }
-        for (const workerInput of getWorkerHumanInputsRequiringDelivery(this.sessionManager)) {
-            if (this._activeHumanInputRequestIds.has(workerInput.request.requestId))
-                continue;
-            this._activeHumanInputRequestIds.add(workerInput.request.requestId);
-            try {
-                resumed = (await this._resolveWorkerHumanInput(workerInput)) || resumed;
-            }
-            finally {
-                this._activeHumanInputRequestIds.delete(workerInput.request.requestId);
-            }
-        }
-        return resumed;
+        return this._humanInput.resumePending();
     }
     /**
      * Shared {@link OllamaRuntime} for a given server, lazily created and cached by baseUrl so every
@@ -2274,6 +2058,7 @@ export class AgentSession {
         // selected/authenticated — can un-register it from _earlyDisplayedUserMessages instead of
         // leaking the reference forever.
         let userMessage;
+        let promptMessage;
         let routingStarted = false;
         let pendingNextTurnCount = 0;
         // Effectiveness feedback: remember the recall page + the query so we can score, after the
@@ -2346,17 +2131,25 @@ export class AgentSession {
             // (seconds), not a regex; awaiting it first made the prompt appear to hang. The
             // authoritative message_start emitted later for this SAME object is suppressed in
             // _handleAgentEvent (see _earlyDisplayedUserMessages) so it is still shown exactly once.
-            const userContent = [{ type: "text", text: expandedText }];
-            if (currentImages) {
-                userContent.push(...currentImages);
+            if (options?.internalContextType) {
+                if (currentImages && currentImages.length > 0) {
+                    throw new Error("Internal context turns do not accept image attachments.");
+                }
+                promptMessage = createCustomMessage(options.internalContextType, expandedText, false, undefined, new Date().toISOString());
+            }
+            else {
+                const userContent = [{ type: "text", text: expandedText }];
+                if (currentImages)
+                    userContent.push(...currentImages);
+                userMessage = {
+                    role: "user",
+                    content: userContent,
+                    timestamp: Date.now(),
+                };
+                promptMessage = userMessage;
+                this._earlyDisplayedUserMessages.add(userMessage);
+                this._emit({ type: "message_start", message: userMessage });
             }
-            userMessage = {
-                role: "user",
-                content: userContent,
-                timestamp: Date.now(),
-            };
-            this._earlyDisplayedUserMessages.add(userMessage);
-            this._emit({ type: "message_start", message: userMessage });
             // Bracket the routing/prep phase (judge, model/auth checks, compaction, ...) so the UI can
             // show general "working" feedback for it — otherwise the user stares at their own echoed
             // prompt with nothing happening for however long the judge takes. routing_end is emitted
@@ -2410,7 +2203,7 @@ export class AgentSession {
             // prefetch a relevant <memory_context> page from past sessions and prepend it as data ahead of
             // the user message. Best-effort and gated: trivial turns are skipped, and providers return ""
             // (no page) when nothing is relevant — so it stays net-negative and the GC packs stale pages.
-            if (this._memory.shouldAttemptRecall(expandedText)) {
+            if (!options?.internalContextType && this._memory.shouldAttemptRecall(expandedText)) {
                 try {
                     const recall = await this._memory.prefetchRecall(expandedText);
                     if (recall) {
@@ -2429,13 +2222,13 @@ export class AgentSession {
             }
             // Add user message (built earlier, before the router judge, so it could be painted
             // immediately — see the early message_start emit above).
-            messages.push(userMessage);
+            messages.push(promptMessage);
             // Inject any pending "nextTurn" messages as context alongside the user message
             pendingNextTurnCount = this._pendingNextTurnMessages.length;
             for (const msg of this._pendingNextTurnMessages.slice(0, pendingNextTurnCount)) {
                 messages.push(msg);
             }
-            const taskStepsState = this.getTaskStepsStateSnapshot();
+            const taskStepsState = options?.internalContextType ? undefined : this.getTaskStepsStateSnapshot();
             const taskStepsContext = taskStepsState ? formatTaskStepsContext(taskStepsState) : undefined;
             if (taskStepsState && taskStepsContext) {
                 messages.push(createCustomMessage("task_steps_context", taskStepsContext, false, { revision: taskStepsState.revision }, new Date().toISOString()));
@@ -3287,49 +3080,35 @@ export class AgentSession {
      *
      * @returns the id of the appended custom entry
      */
-    saveGoalStateSnapshot(state) {
-        const entryId = appendGoalStateSnapshot(this.sessionManager, state);
-        try {
-            this._backgroundLanes.synchronizeGoalState(state);
-        }
-        catch (error) {
-            this._emit({
-                type: "warning",
-                message: `Goal state persisted but durable worker reconciliation failed: ${error instanceof Error ? error.message : String(error)}`,
-            });
-        }
-        return entryId;
+    saveGoalStateSnapshot(state, expected) {
+        return this._goals.saveState(state, expected);
+    }
+    /** Persist a branch-scoped tombstone and stop goal-owned execution without resurrecting old state. */
+    clearGoalStateSnapshot(state, now) {
+        return this._goals.clearState(state, now);
     }
     /**
      * Retrieve the latest valid goal state snapshot from the session log.
      */
     getGoalStateSnapshot() {
-        return getLatestGoalStateSnapshot(this.sessionManager);
+        return this._goals.getState();
     }
     /**
-     * Persist one submitted continuation pass's turn/wall-clock/spend contribution onto the active
-     * goal's durable cumulative budget (see `GoalState.continuationTurnsUsed` et al.). This is the
+     * Persist one submitted continuation pass's exact turn/wall-clock/token/spend contribution onto the active
+     * goal's durable cumulative accounting (see `GoalState.continuationTurnsUsed` et al.). This is the
      * "persistence dep" `GoalLoopController` calls once per pass actually submitted — it, not the
-     * loop controller, is where USD gets attributed: it reads the session's OWN cumulative model
-     * spend (`getCostSummary().ownCost` — deliberately excludes worker/subagent spend, which is
-     * tracked and budgeted separately) and threads that single absolute reading into a
-     * `record_continuation_budget` event; the pure reducer in `goal-state.ts` derives the delta.
+     * loop controller, is where usage gets attributed: it scans only assistant messages appended on
+     * the active branch after the pass's captured cursor. Compaction cannot erase or reattribute that
+     * append-only interval, and unrelated foreground turns outside the interval are excluded.
      * A no-op when no goal state exists (defensive — in practice this is only ever called right
      * after a pass the loop already confirmed was submitted against an active goal).
      */
     recordGoalContinuationPass(pass) {
-        const state = this.getGoalStateSnapshot();
-        if (!state)
-            return;
-        const sessionCostUsd = this.getCostSummary().ownCost;
-        const updated = applyGoalEvent(state, {
-            type: "record_continuation_budget",
-            turns: pass.turns,
-            wallClockMs: pass.wallClockMs,
-            sessionCostUsd,
-            now: new Date().toISOString(),
-        });
-        this.saveGoalStateSnapshot(updated);
+        this._goals.recordContinuationPass(pass);
+    }
+    /** Restore runtime intent without mutating persisted goal lifecycle state. */
+    restoreGoalRuntimeAfterResume() {
+        this._goals.restoreAfterResume();
     }
     /** Save native task-step state to the active session log. */
     saveTaskStepsStateSnapshot(state) {
@@ -3394,12 +3173,7 @@ export class AgentSession {
      * same live lane state, since both reach this same method.
      */
     getGoalRuntimeSnapshot(settings) {
-        return buildGoalRuntimeSnapshot({
-            sessionManager: this.sessionManager,
-            settings,
-            laneRecords: this._backgroundLanes.getLaneRecords(),
-            taskRuntime: this._backgroundLanes.getTaskRuntimeSnapshot(),
-        });
+        return this._goals.getRuntimeSnapshot(settings);
     }
     /**
      * Capability profile derived from the CURRENT session model's own metadata (context window),
@@ -3456,14 +3230,14 @@ export class AgentSession {
         return this._backgroundLanes.getStoredFitnessReports();
     }
     async continueGoalOnce(options) {
-        return this._goalContinuation.continueGoalOnce(options);
+        return this._goals.continueOnce(options);
     }
     /**
      * Public entry point for BOTH idle autosteer and manual (`/goal start`, `/goal-continue`)
      * continuation. Delegates to {@link BackgroundLaneController.continueGoalLoopExclusive}, the
      * single-flight guard that prevents two goal loops from racing to submit prompts through the
      * same session (which throws "Agent is already processing" from the second submission). Do not
-     * call `this._goalContinuation.continueGoalLoop` directly from here — that bypasses the guard.
+     * call `this._goals.continueLoop` directly from here — that bypasses the guard.
      */
     async continueGoalLoop(options) {
         return this._backgroundLanes.continueGoalLoopExclusive(options);