@caupulican/pi-adaptative 0.81.39 → 0.81.41

package/dist/core/background-lane-controller.d.ts

@@ -1,10 +1,9 @@
 /**
- * Background-lane controller: goal auto-continue, the research lane, scout-worker delegation, and
- * the model-fitness probe.
+ * Execution-plane coordinator for goal continuation, research, managed lanes, worker delegation,
+ * and model fitness.
  *
- * Extracted verbatim from agent-session.ts (god-file decomposition). Owns the lane timers, the
- * single-flight guards, the last research-lane skip reason, the live {@link LaneTracker}, and the
- * session-lifetime abort controllers for in-flight research/worker passes. Everything else it needs
+ * Coordination state is owned by focused controllers. This coordinator retains one AgentSession
+ * composition seam and a shared lane read model. Everything it needs
  * — the session manager, settings, model registry, live model, capability envelope, the goal
  * continuation LOOP, the isolated-completion primitive, spawned-usage accounting, and the telemetry
  * sink — is reached through narrow deps accessors rather than the whole AgentSession.
@@ -14,216 +13,85 @@
  * delegations; goal auto-continue itself only ever asks the session to `continueGoalLoop`, so this
  * controller never touches `prompt()`, the last-assistant-message, retry, or streaming state.
  */
-import type { SessionManager } from "@caupulican/pi-agent-core/node";
-import type { Api, Model, Usage } from "@caupulican/pi-ai";
-import type { AgentSessionEvent, GoalContinuationLoopOptions, GoalContinuationLoopResult, IsolatedCompletionOptions, IsolatedCompletionResult, PromptOptions, ResearchLaneRunOutcome, WorkerDelegationRunOutcome } from "./agent-session.ts";
-import type { CapabilityEnvelope, EvidenceBundle, WorkerRequest, WorkerResult, WorkerResultStatus } from "./autonomy/contracts.ts";
-import { type LaneRecord, type LaneTerminalStatus } from "./autonomy/lane-tracker.ts";
-import { type AutonomyTelemetryEvent } from "./autonomy/telemetry-events.ts";
+import type { Api, Model } from "@caupulican/pi-ai";
+import type { GoalContinuationLoopOptions, GoalContinuationLoopResult, PromptOptions, ResearchLaneRunOutcome, WorkerDelegationRunOutcome } from "./agent-session-contracts.ts";
+import { type LaneRecord } from "./autonomy/lane-tracker.ts";
+import { type WorkerDelegationControllerDeps } from "./delegation/worker-delegation-controller.ts";
+import type { WorkerDelegationRequest } from "./delegation/worker-delegation-request.ts";
 import type { ManagedLaneEvent } from "./extensions/types.ts";
 import type { GoalRuntimeSnapshot, GoalRuntimeSnapshotSettings } from "./goals/goal-runtime-snapshot.ts";
 import type { GoalState } from "./goals/goal-state.ts";
-import { type ModelCapabilityProfile } from "./model-capability.ts";
-import type { ModelRegistry } from "./model-registry.ts";
-import { type StoredFitnessReport } from "./models/fitness-store.ts";
-import { type ModelFitnessReport } from "./research/model-fitness.ts";
-import type { collectWorkspaceSources } from "./research/workspace-collector.ts";
-import type { SettingsManager } from "./settings-manager.ts";
-export declare function clampLaneMaxUsd(settingsMaxUsd: number, foregroundMaxEstimatedUsd?: number): number;
-export declare function getPrivateLaneDeniedPaths(cwd: string, agentDir: string): string[];
-/**
- * Resolves a managed lane's caller-reported terminal `status` (a free-form CLAIM — e.g. a tmux job's
- * own "done"/"blocked" completion marker, a lifecycle tag like "dismissed", or a raw
- * {@link WorkerResultStatus} spelling) onto the LaneTracker's {@link LaneTerminalStatus} vocabulary.
- * Mirrors the same success/blocked mapping direction `worker-runner.ts` already uses for in-process
- * workers ("completed"/"done" -> succeeded, "blocked" -> failed). An unrecognized or missing status is
- * conservatively reported as `"failed"` rather than silently assumed successful (claims-to-review).
- */
-export declare function resolveManagedLaneTerminalStatus(status: string | undefined): LaneTerminalStatus;
-/** Maps a LaneTracker terminal status onto the WorkerResult status vocabulary a managed-lane claim
- * snapshot is persisted under — the two enums use different spellings/values, never interchangeable
- * (e.g. `"canceled"` vs `"cancelled"`); `timeout`/`budget_exhausted` have no dedicated WorkerResult
- * counterpart and are conservatively reported as `"failed"`. */
-export declare function mapManagedLaneTerminalStatus(status: LaneTerminalStatus): WorkerResultStatus;
-export declare function isLocalExecutionModel(model: Pick<Model<Api>, "provider" | "baseUrl">): boolean;
-export interface BackgroundLaneControllerDeps {
-    /** A disposed session must never schedule/persist a lane or continuation. */
-    isDisposed(): boolean;
-    /** Child sessions never run the idle research lane (only the top-level session drives autonomy). */
-    isChildSession(): boolean;
-    /** This session's id, for lane envelope ids and spawned-usage report ids. */
-    getSessionId(): string;
-    /** The workspace root a lane runs relative to (worker path scope + research source collection). */
-    getCwd(): string;
-    /** Root dir the host-keyed {@link FitnessStore} persists under. */
-    getAgentDir(): string;
-    /** Session log: lane records read/append here and feed lane-history dedupe. */
-    getSessionManager(): SessionManager;
-    /** Autonomy / research-lane / worker-delegation / model-capability settings + the profile registry. */
-    getSettingsManager(): SettingsManager;
-    /** Resolves a configured lane model pattern against configured auth. */
-    getModelRegistry(): ModelRegistry;
-    /** Session-scoped provider/model quota exhaustion guard. */
-    isModelExhausted(model: Model<Api>): boolean;
-    /** The session's current model — lanes inherit it unless a lane model is explicitly configured. */
-    getModel(): Model<Api> | undefined;
-    /** Tool/profile gate: delegation is unavailable when the active surface removes `delegate`. */
-    isDelegateToolActive(): boolean;
+import type { ModelCapabilityProfile } from "./model-capability.ts";
+import type { StoredFitnessReport } from "./models/fitness-store.ts";
+import type { TaskRuntimeProjection } from "./orchestration/task-runtime.ts";
+import { type LaneModelResolverDeps } from "./research/lane-model-resolver.ts";
+import type { ModelFitnessReport } from "./research/model-fitness.ts";
+import { type ModelFitnessControllerDeps } from "./research/model-fitness-controller.ts";
+import { type ResearchLaneControllerDeps } from "./research/research-lane-controller.ts";
+export { isLocalExecutionModel } from "./delegation/worker-delegation-controller.ts";
+export { clampLaneMaxUsd } from "./research/lane-model-resolver.ts";
+export interface BackgroundLaneControllerDeps extends WorkerDelegationControllerDeps, ResearchLaneControllerDeps, ModelFitnessControllerDeps, LaneModelResolverDeps {
     /** True iff the `goal` tool is in the session's ACTIVE surface -- the capability-adaptive gate
      * for every goal-continuation loop (see `continueGoalLoopExclusive`): a surface without the
      * goal tool (lean capability blocklist, worker role ceiling, --tools/profile exclusion) must
      * never be driven with continuation prompts it cannot execute. */
     isGoalToolActive(): boolean;
-    /** Foreground cost ceiling — a lane budget is clamped to it, never exceeds it. */
-    getCapabilityEnvelope(): CapabilityEnvelope | undefined;
     /** Capability profile of the SESSION model (gates background lanes, scales continuation budgets). */
     getModelCapabilityProfile(): ModelCapabilityProfile;
-    /** Emits session events for diagnostics and UI state. */
-    emit(event: AgentSessionEvent): void;
-    /** Queue one bounded terminal handoff that wakes the parent without injecting worker product text. */
-    notifyWorkerTerminalHandoff(records: readonly {
-        laneId: string;
-        status: LaneTerminalStatus;
-        reasonCode?: string;
-    }[]): Promise<void>;
-    /** Telemetry sink (codes/ids only — never lane product text). */
-    emitAutonomyTelemetry(event: AutonomyTelemetryEvent): void;
-    /** Durable goal state, if a goal is active (the research lane's demand source). */
-    getGoalStateSnapshot(): GoalState | undefined;
     /** Continuation gate + goal state for the idle autosteer scheduler. */
     getGoalRuntimeSnapshot(settings: GoalRuntimeSnapshotSettings): GoalRuntimeSnapshot;
-    /** Latest persisted evidence bundle, for research-lane dedupe. */
-    getEvidenceBundleSnapshot(): EvidenceBundle | undefined;
-    /** Persist a research lane's evidence bundle to the session log. */
-    saveEvidenceBundleSnapshot(bundle: EvidenceBundle): string;
-    /** Persist a worker delegation's result snapshot to the session log. */
-    saveWorkerResultSnapshot(result: WorkerResult, request?: WorkerRequest): string;
-    /** Bounded, source-labeled memory retrieval for an orchestrator-authorized worker. */
-    readMemoryForLane(query: string): Promise<string>;
-    /** Roll a lane's spawned usage into session accounting (idempotent per reportId). `reportId` is
-     * REQUIRED: every caller derives a stable id from the work unit's identity so a retry
-     * cannot double-count. */
-    addSpawnedUsage(usage: Usage, opts: {
-        label?: string;
-        sourceSessionId?: string;
-        reportId: string;
-    }): string | undefined;
-    /** Bounded LLM call fully isolated from the main session; lanes may supply a child tool loop. */
-    runIsolatedCompletion(opts: IsolatedCompletionOptions): Promise<IsolatedCompletionResult>;
     /** Drive-loop boundary: the session's bounded goal-continuation loop (owns `prompt()`, not us). */
     continueGoalLoop(options: GoalContinuationLoopOptions): Promise<GoalContinuationLoopResult>;
-    /** Best-effort workspace evidence collection (silent-on-failure; [] preserves prior behavior). */
-    collectWorkspaceSources: typeof collectWorkspaceSources;
+    /** Persist an explicit stopped state when the selected surface cannot drive the active goal. */
+    markGoalToolUnavailable(): void;
 }
 export declare class BackgroundLaneController {
-    /** Pending idle timer that starts bounded goal continuation after the session becomes idle. */
-    private _goalAutoContinueTimer;
-    /** Guards bounded idle autosteer so continuation prompts do not recursively trigger themselves. */
-    private _isGoalAutoContinuing;
-    /** Pending idle timer that starts an autonomous research pass after the session becomes idle. */
-    private _researchLaneTimer;
-    /** Single-flight guard: at most one research pass runs at a time per session. */
-    private _isResearchLaneRunning;
-    /** Why the last idle research-lane evaluation skipped, for /autonomy diagnostics. */
-    private _lastResearchLaneSkipReason;
     /** Live lane registry — the real source for AutonomyStatusSnapshot.activeLaneCount. */
     private readonly _laneTracker;
-    private _laneHistorySeeded;
-    private _persistedResearchRunCount;
-    /** Session-lifetime abort for in-flight research passes (same pattern as _reflectionAbort). */
-    private readonly _researchLaneAbort;
-    /** Session-lifetime abort for in-flight delegated workers. */
-    private readonly _workerDelegationAbort;
-    /** Session-local de-duplication for fail-closed profile grants that cannot bind to lane tools. */
-    private readonly _warnedUnboundLaneToolGrants;
-    /** Every background execution is retained until its terminal result is observed. */
-    private readonly _workerPromises;
-    private readonly _queuedWorkers;
-    private _workerNotificationScheduled;
-    private _workerNotificationTail;
-    private _disposed;
-    private _workersCompletedSinceFlush;
-    private _workersFailedSinceFlush;
-    private readonly _workerTerminalSinceFlush;
-    /** Live per-lane mutation ledger for a RUNNING worker — the SAME `toolChangedFiles` Set its
-     * `afterToolCall` hook mutates, plus a spend getter and the originating request. Read
-     * synchronously by `abortInFlightLanes()`'s disposal cutoff, the only provably-safe write window
-     * for a mid-flight cancellation (see that method); deleted there (consumed-ledger guard against
-     * the post-await disposed branch re-persisting) or in the lane's own `finally` on a normal exit. */
-    private readonly _inFlightWorkerLedgers;
-    /** Reload-gate deregister function for a worker queued (not yet running) behind a
-     * contending local-execution foreground model. Registered at enqueue so `/reload` waits for
-     * queued work too, not just running work; deregistered exactly once, either on disposal
-     * (`abortInFlightLanes`) or at the running handoff (`drainQueuedWorkerDelegations`). A laneId with
-     * no entry here (e.g. seeded directly into `_queuedWorkers` by a test) is simply untracked —
-     * deregistration is best-effort by design, never required. */
-    private readonly _queuedWorkerDeregisters;
-    /** Dispatch -> terminal correlation for out-of-process managed lanes (`pi.reportManagedLane`
-     * host bridge), keyed by the CALLER's own `laneId` (e.g. a tmux job id) — distinct from the
-     * internal `LaneTracker` id it maps to. Removed on the matching terminal report so a duplicate or
-     * unmatched terminal call is a safe no-op instead of a double-deregister or an orphaned entry. */
-    private readonly _managedLaneDispatches;
+    private readonly _laneModels;
+    private readonly _goalAutoContinue;
+    private readonly _research;
+    private readonly _fitness;
+    /** Lazily materialized only when managed-lane state is queried or reported. */
+    private _managedLanes;
+    /** Lazily materialized so a UAC surface without `delegate` allocates no worker runtime state. */
+    private _workers;
+    /** One durable lifecycle shared by every worker execution adapter. */
+    private _workerLifecycle;
+    /** Shared terminal outbox for managed and in-process workers; lazy under UAC omission. */
+    private _workerNotifications;
     private readonly deps;
     /** Emit a warning without ever throwing — used from disposal-adjacent persistence where a
      * listener failure (or a bare test double missing `emit`) must never block or crash cleanup. */
     private _safeWarn;
-    private _scheduleWorkerNotification;
-    private _flushWorkerNotification;
     private _recordWorkerTerminal;
     constructor(deps: BackgroundLaneControllerDeps);
-    private _seedLaneHistory;
+    private _getWorkerController;
+    private _getWorkerLifecycle;
+    private _getWorkerNotificationCoordinator;
+    private _getManagedLaneController;
+    private _hydrateManagedLanes;
     /** Live lane records tracked by this process (running and terminal). */
     getLaneRecords(): LaneRecord[];
+    /** Does not materialize the worker controller when UAC omitted delegation. */
+    getTaskRuntimeSnapshot(): TaskRuntimeProjection | undefined;
+    /** Reconcile only when delegation has already been materialized; UAC omission stays zero-load. */
+    synchronizeGoalState(goal: GoalState): void;
     /**
-     * Resolve a tracked managed-lane dispatch's internal `LaneTracker` id from the CALLER's own
-     * `laneId` (the id passed to `recordManagedLane`'s `phase: "dispatch"`, e.g. a reconstructed
-     * `tmux:jobId:agentId`). A deterministic, non-racy keyed lookup against `_managedLaneDispatches` —
-     * NOT a `getLaneRecords()` diff — for a caller (e.g. the goal-to-tmux dispatch adapter) that just
-     * minted the dispatch and needs the internal id `Requirement.boundLaneId`/`inFlightGoalLaneIds`
-     * actually match. `undefined` once the dispatch has gone terminal (removed from the map) or was
-     * never tracked.
+     * Resolve a tracked managed-lane dispatch. The caller's stable id is also the canonical durable
+     * lane id, so this is an existence check rather than an id translation.
      */
     resolveManagedLaneId(callerLaneId: string): string | undefined;
     /** Live count of active lanes — the real source for AutonomyStatusSnapshot.activeLaneCount. */
     getActiveLaneCount(): number;
     /** Belt-and-braces guard: whether ANY queued/running lane is tagged with this goalId. */
     private _hasInFlightLaneForGoal;
-    /**
-     * Host-side bridge for `pi.reportManagedLane`: makes an out-of-process managed lane (e.g. a tmux
-     * worker) a first-class lane in THIS process's LaneTracker. HONEST cross-process seam — the
-     * extension only ever REPORTS a claim; this controller stays the lane-tracking SSOT (no in-process
-     * sandboxing is implied by accepting the report).
-     *
-     * `phase: "dispatch"` mints a `tmux-worker` lane record (goalId-tagged) and registers exactly one
-     * reload-quiesce unit for it. `phase: "terminal"` resolves the caller's free-form `status` claim
-     * onto {@link LaneTerminalStatus} (see {@link resolveManagedLaneTerminalStatus}), completes that
-     * same record, deregisters the quiesce unit (inside a `finally` — never left stuck regardless of
-     * what persistence below does), and persists a bounded worker-result CLAIM snapshot from the
-     * reported `changedFiles`. Host re-review: the reported `changedFiles` are re-checked against
-     * the session's active capability envelope ({@link reviewManagedLaneChangedFiles}, reusing
-     * `validateWorkerResult`'s symlink-safe scope check verbatim) and `parentReviewRequired` is
-     * stamped on the persisted claim whenever that check does not cleanly "allow" -- an out-of-scope
-     * (or no-scope-configured) path is flagged exactly like an in-scope one, since a tmux worker's
-     * write never passed through this process's enforcement in the first place. This is the SESSION
-     * envelope, not a per-launch tmux standing grant (that is a narrower, launch-specific scope;
-     * documented follow-up, not yet implemented). `event.request` stays an unvalidated
-     * caller-supplied bag (per its own doc comment) and is deliberately never read for scoping. A
-     * terminal report for an unknown `laneId` (no matching dispatch tracked) and a duplicate dispatch
-     * for an already-tracked `laneId` are both safe no-ops — never a double registration, a double
-     * persisted claim, or a crash.
-     *
-     * Returns the minted (`phase: "dispatch"`) or completed (`phase: "terminal"`) LaneRecord for an
-     * in-process caller that wants the record without a second `getLaneRecords()` read (e.g. a
-     * faux-bridge test, or the goal-to-tmux dispatch adapter via `resolveManagedLaneId`); `undefined`
-     * on every no-op path (disposed controller, duplicate dispatch, unknown-laneId terminal). The
-     * extension-facing `ExtensionActions.reportManagedLane` TYPE stays `=> void` -- that call site is a
-     * fire-and-forget statement and is unaffected by this return.
-     */
+    /** Delegate the out-of-process dispatch/terminal claim to its single lifecycle owner. */
     recordManagedLane(event: ManagedLaneEvent): LaneRecord | undefined;
     /** Why the last idle research-lane evaluation skipped, for /autonomy diagnostics. */
     getLastResearchLaneSkipReason(): string | undefined;
     /**
-     * Abort any in-flight research pass or delegated worker (called on session dispose).
+     * Abort in-flight research and delegate worker disposal to its single owning controller.
      *
      * This synchronous body is the LAST provably-safe write window for canceled/in-flight work.
      * `dispose()` (agent-session.ts) has already set the session's own disposed flag but has not yet
@@ -236,7 +104,6 @@ export declare class BackgroundLaneController {
     abortInFlightLanes(): void;
     clearGoalAutoContinueTimer(): void;
     scheduleGoalAutoContinueFromIdle(options?: PromptOptions): void;
-    private _runScheduledGoalAutoContinue;
     /**
      * Single-flight entry point for EVERY goal-continuation loop invocation — idle autosteer
      * ({@link _runScheduledGoalAutoContinue}) AND the manual `/goal start` / `/goal-continue`
@@ -247,45 +114,14 @@ export declare class BackgroundLaneController {
      * must never be called directly outside this method, or the guard is bypassed.
      */
     continueGoalLoopExclusive(options: GoalContinuationLoopOptions): Promise<GoalContinuationLoopResult>;
-    /**
-     * A full {@link GoalContinuationLoopResult} for a continuation request that never ran a pass
-     * (another loop already owns the mutex, or the session is disposed). Keeps the skip path
-     * type-identical to a real pass — no separate skip union — so every caller keeps reading
-     * `result.stopReason`/`result.finalSnapshot` unchanged.
-     */
-    private _skippedGoalResult;
     clearResearchLaneTimer(): void;
-    /**
-     * Derive the research demand from durable goal state: an active goal with open requirements,
-     * deduplicated against the latest persisted bundle so the same requirement set is never
-     * researched twice (the query is deterministic, so dedupe survives session reload).
-     */
-    private _buildResearchLaneDemand;
-    /**
-     * Idle trigger for the autonomous research lane (mirrors {@link scheduleGoalAutoContinueFromIdle}).
-     * All skips are recorded in `_lastResearchLaneSkipReason` and surfaced via diagnostics — the lane
-     * informs, it never prompts or blocks the foreground.
-     */
     scheduleResearchLaneFromIdle(): void;
-    private _runScheduledResearchLane;
-    /** Capability profile for a specific lane model (lane budgets scale to the lane model's window). */
-    private _laneCapabilityProfile;
-    /**
-     * Resolve the model for a background lane. Lanes are shipped BY this session, so they inherit
-     * the session's own model unless a lane-specific model is explicitly configured — a single-model
-     * setup (e.g. one local open model) runs its lanes on that same model. An explicitly configured
-     * pattern that cannot resolve/authenticate is a visible skip, not a silent fallback.
-     */
     resolveLaneModel(configuredPattern: string | undefined): Model<Api> | undefined;
-    /**
-     * Resolve what a lane ships with. Precedence: explicit lane model setting, then the lane
-     * profile's model (a shipped profile with a model MUST be obeyed — unresolvable is a visible
-     * skip, never a fallback), then generic inheritance of the session model.
-     */
-    private _resolveLaneShipment;
-    private _warnUnboundLaneToolGrants;
-    /** Stripped research envelope — never the foreground/architect envelope. */
-    private _buildResearchLaneEnvelope;
+    getOrchestrationProfileCatalog(): Array<{
+        profileId: string;
+        role: string;
+        description: string;
+    }>;
     /**
      * Run one bounded, read-only research pass and persist its results: evidence bundle snapshot,
      * terminal lane record, and spawned-usage cost report (single-hop invariant, idempotent on the
@@ -297,32 +133,16 @@ export declare class BackgroundLaneController {
         context?: string;
         goalId?: string;
     }): Promise<ResearchLaneRunOutcome>;
-    /**
-     * Run one bounded scout-worker delegation: build a WorkerRequest with a stripped read-only
-     * envelope, execute it as an isolated completion on a cheap lane, validate the result via
-     * {@link validateWorkerResult} before acceptance, and persist result + lane record + spawned
-     * usage (idempotent per-lane reportId). Consumed by the `delegate` tool.
-     */
-    startWorkerDelegation(request: {
-        instructions: string;
-        /** Model-provided replacement for the worker role prompt (the level-0 core always remains). */
-        systemPrompt?: string;
-        /** Orchestrator-requested read-only memory access; the lane profile may still deny it. */
-        memoryRead?: boolean;
-    }): {
+    /** Start a durable, profile-bound worker delegation. */
+    startWorkerDelegation(request: WorkerDelegationRequest): {
         started: false;
         skipReason: string;
     } | {
         started: true;
         record: LaneRecord;
     };
-    runWorkerDelegationOnce(request: {
-        instructions: string;
-        /** Model-provided replacement for the worker role prompt (the level-0 core always remains). */
-        systemPrompt?: string;
-        /** Orchestrator-requested read-only memory access; the lane profile may still deny it. */
-        memoryRead?: boolean;
-    }, onStarted?: (record: LaneRecord) => void, existingRecord?: LaneRecord): Promise<WorkerDelegationRunOutcome>;
+    /** Run one worker immediately; used by focused integrations and tests. */
+    runWorkerDelegationOnce(request: WorkerDelegationRequest, onStarted?: (record: LaneRecord) => void, existingRecord?: LaneRecord): Promise<WorkerDelegationRunOutcome>;
     /**
      * Probe a candidate model against the subagent contracts (research/worker/judge/search/
      * tool-call surfaces) via {@link runModelFitnessProbe}. The model must resolve and
@@ -342,7 +162,7 @@ export declare class BackgroundLaneController {
         started: false;
         skipReason: string;
     }>;
-    /** Start queued local workers at the owner session's foreground-idle boundary. */
+    /** Start every capacity-eligible queued worker at the owner session's foreground-idle boundary. */
     drainQueuedWorkerDelegations(): void;
     /** Fitness reports persisted for THIS host (measured evidence for architect/profile decisions). */
     getStoredFitnessReports(): StoredFitnessReport[];