open-multi-agent-kit 0.96.1 → 0.96.2

package/dist/core/agent-session.js

@@ -44,6 +44,7 @@ import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
 import { assertTextChatModelForCompletion } from "./grok-harness.js";
 import { grokPlaybookAppendForProvider } from "./grok-playbook.js";
+import { captureHostResourceSnapshot } from "./host-resource-snapshot.js";
 import { decideLoadoutAccess } from "./loadout-access-policy.js";
 import { loadMcpServerConfigs } from "./mcp/config.js";
 import { McpManager } from "./mcp/manager.js";
@@ -53,6 +54,7 @@ import { TurnMetricsSink } from "./turn-metrics.js";
 const DISABLED_ENV_VALUES = new Set(["0", "false", "off", "disable", "disabled"]);
 const MAX_OVERFLOW_RECOVERY_ATTEMPTS = 2;
 const OVERFLOW_RECOVERY_EMERGENCY_TOKENS = 4_096;
+const MAX_RESOURCE_OBSERVATION_JOURNALS = 32;
 function isDisabledEnvValue(value) {
     return value !== undefined && DISABLED_ENV_VALUES.has(value.trim().toLowerCase());
 }
@@ -75,6 +77,7 @@ import { selectContextFilesForModel } from "./model-prompt-policy.js";
 import { findExactModelReferenceMatch } from "./model-resolver.js";
 import { computePromptTokenBudget } from "./prompt-budget.js";
 import { classifyPromptCacheTransition } from "./prompt-cache.js";
+import { createPromptSettlementState, reducePromptSettlement, settlePromptIfReady, } from "./prompt-settlement.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
 import { isQuotaExhaustionMessage, isStickySafetyModel, pickFailoverCandidate, resolveProviderResilience, shouldEjectStickySafetyModel, shouldHonorSafetyFailover, stickySafetyBlockMessage, } from "./provider-resilience.js";
 import { computeRetryDelayMs, failoverModelKey, isFailoverTriggerError, isRetryableAssistantError, nextRetryAttempt, retryBudgetForAssistantError, } from "./provider-retry.js";
@@ -82,8 +85,13 @@ import { getBiasStepsForCell, parseRouterBiasSnapshot } from "./reasoning-router
 import { classifyTaskV4, deriveRouterFeedbackFeaturesV4, resolveThinkingLevelV4WithUncertainty, TASK_CLASS_THINKING_LEVELS_V4, } from "./reasoning-router-v4.js";
 import { redactSensitiveText, redactSensitiveTextForced } from "./redaction.js";
 import { getRepositoryRouterLearningPaths } from "./repository-learning-scope.js";
+import { decideResourceAdmission } from "./resource-admission.js";
+import { resolveResourceGovernorSettings } from "./resource-governor-settings.js";
+import { admissionObservationFacts, classificationObservationFacts, ResourceObservationJournal, settledObservationFacts, snapshotObservationFacts, soundObservationFacts, } from "./resource-observation-journal.js";
+import { decideResourceSafetyGate, RESOURCE_PRESSURE_REQUIRED_ACTION } from "./resource-safety-gate.js";
 import { appendRouterFeedbackRecord, ROUTER_FEEDBACK_LEVELS, } from "./router-feedback-collector.js";
 import { RunJournalStore } from "./run-journal-store.js";
+import { RunResourceLeaseController } from "./run-resource-lease.js";
 import { SessionBashRuntime } from "./session-bash-runtime.js";
 import { SessionBashService } from "./session-bash-service.js";
 import { SessionCompactionService } from "./session-compaction-service.js";
@@ -98,6 +106,8 @@ import { createAllToolDefinitions } from "./tools/index.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
 import { createVerifiedBashOperations } from "./verified-bash-adapter.js";
 import { resolveSessionWorkspaceScope } from "./verified-bash-runtime.js";
+import { classifyWorkloadCommand } from "./workload-classifier.js";
+import { WorkloadPermitError, WorkloadPermitPool } from "./workload-permit-pool.js";
 /**
  * Parse a skill block from message text.
  * Returns null if the text doesn't contain a skill block.
@@ -356,6 +366,14 @@ export class AgentSession {
     _runJournalStore;
     _ownedSessionOwnerLease;
     _activeRunId = null;
+    // Resource governor (roadmap M2): lease controller owns the temporary tool
+    // cap for governed runs; the last decision backs the §19.4 read-only API.
+    _resourceLeaseController;
+    _resourceObservations = null;
+    _resourceObservationJournals = new Map();
+    _latestResourcePromptRunId = null;
+    _lastResourceAdmission = null;
+    _workloadPermitPool;
     _pendingRuntimeTerminationCause;
     _activeRunToolTermination;
     _lastTermination;
@@ -436,6 +454,7 @@ export class AgentSession {
             isStreaming: () => this.isStreaming,
             pushMessage: (message) => this.agent.state.messages.push(message),
             appendMessage: (message) => this.sessionManager.appendMessage(message),
+            acquireResourcePermit: (command, signal) => this._acquireBashResourcePermit(command, signal),
         });
         this._compactionService = new SessionCompactionService({
             sessionManager: this.sessionManager,
@@ -1627,7 +1646,15 @@ export class AgentSession {
         this._promptCacheKey = nextKey;
         this._promptCacheStablePrefixCharacters = boundary ?? 0;
     }
+    _getDefaultActiveSkills() {
+        const trustedSkillNames = new Set(this._resourceLoader
+            .getSkills()
+            .skills.filter((skill) => skill.sourceInfo.scope === "user")
+            .map((skill) => skill.name));
+        return this.settingsManager.getDefaultActiveSkills().filter((name) => trustedSkillNames.has(name));
+    }
     _rebuildSystemPrompt(toolNames, model = this.model) {
+        const defaultActiveSkills = this._getDefaultActiveSkills();
         const assembled = assembleSessionSystemPrompt({
             cwd: this._cwd,
             toolNames,
@@ -1638,6 +1665,8 @@ export class AgentSession {
             appendSystemPrompt: this._resourceLoader.getAppendSystemPrompt(),
             providerAppend: grokPlaybookAppendForProvider(model?.provider),
             skills: this._resourceLoader.getSkills().skills,
+            activeSkillNames: defaultActiveSkills,
+            activeSkillSource: defaultActiveSkills.length > 0 ? "settings" : undefined,
             contextFiles: selectContextFilesForModel(this._resourceLoader.getAgentsFiles().agentsFiles, model),
             contextBudget: this._getContextBudgetOptions(undefined, model),
         });
@@ -1649,6 +1678,15 @@ export class AgentSession {
     // Prompting
     // =========================================================================
     async _runAgentPrompt(messages) {
+        // One identity per top-level run (§16.2): internal retries and
+        // continuations inside this call share it, as does the resource lease.
+        const promptRunId = `prompt-run-${randomUUID()}`;
+        const startedAtEpochMs = Date.now();
+        // Roadmap M2: the lease spans the whole run including internal retries
+        // and continuations, so they share one admission decision (§8.3).
+        const resourceLease = await this._beginResourceGovernedRun(promptRunId);
+        const resourceObservations = this._resourceObservationJournals.get(promptRunId) ?? null;
+        let outcome = "completed";
         try {
             await this.agent.prompt(messages);
             while (await this._handlePostAgentRun()) {
@@ -1656,11 +1694,251 @@ export class AgentSession {
             }
         }
         catch (error) {
+            outcome =
+                this._userAbortRequested || (error instanceof Error && /abort/i.test(error.message)) ? "aborted" : "failed";
             this._publishRuntimeFailure(error);
             throw error;
         }
         finally {
+            if (resourceLease !== null) {
+                // Generation-safe: a stale release after another run acquired the
+                // lease is a no-op instead of clobbering the newer cap (§8.1).
+                this._resourceLeaseController?.release(resourceLease);
+                resourceObservations?.record("resource_lease_released_v1", { promptRunId });
+            }
             this._flushPendingBashMessages();
+            // §16.4 (M4): settle only after every in-run continuation drained.
+            this._emitPromptSettledIfReady({ promptRunId, startedAtEpochMs, outcome, resourceObservations });
+        }
+    }
+    /**
+     * Emit `prompt_settled` when the §16.4 conditions hold. Called exactly
+     * once per promptRunId (from `_runAgentPrompt`'s finally), so the same
+     * run can never emit twice; late-queued messages block emission
+     * conservatively — the continuation run settles under its own id.
+     * Settlement is a UX signal only and must never affect the run (§16.1).
+     */
+    _emitPromptSettledIfReady(input) {
+        try {
+            let state = createPromptSettlementState(input.promptRunId, input.startedAtEpochMs);
+            state = reducePromptSettlement(state, { kind: "terminal", outcome: input.outcome });
+            if (this.isStreaming) {
+                state = reducePromptSettlement(state, { kind: "tool", delta: 1 });
+            }
+            if (this.agent.hasQueuedMessages()) {
+                state = reducePromptSettlement(state, { kind: "continuation", delta: 1 });
+            }
+            const settled = settlePromptIfReady(state, Date.now());
+            if (settled.event !== null) {
+                input.resourceObservations?.record("prompt_settled_v1", settledObservationFacts(settled.event));
+                this._emit(settled.event);
+            }
+        }
+        catch {
+            // Never let settlement bookkeeping break a run.
+        }
+    }
+    /**
+     * Resource governor preflight for one top-level run (roadmap §8, §25.3 M2).
+     *
+     * - `off`: nothing; v0.96.1 observable behavior is preserved.
+     * - `observe` (default): fire-and-forget probe records a decision for the
+     *   §19.4 read-only API; the cap never changes and the prompt is never
+     *   delayed. The pending probe is bounded (~cpuSampleMs) and never rejects.
+     * - `adaptive`/`strict`: bounded blocking probe (default 300 ms deadline),
+     *   then a generation-safe lease applies the effective tool cap for this
+     *   run. The caller's `finally` releases it exactly once.
+     *
+     * Never throws: any probe or policy failure leaves this run ungoverned
+     * (§2.1: probe failure must not crash or block the prompt).
+     */
+    async _beginResourceGovernedRun(promptRunId) {
+        try {
+            const resolved = resolveResourceGovernorSettings(this.settingsManager.getResourceGovernorSettings());
+            if (resolved.mode === "off") {
+                return null;
+            }
+            const resourceObservations = this._openResourceObservations(promptRunId);
+            const probeOptions = {
+                cwd: this._cwd,
+                maxProbeMs: resolved.maxProbeMs,
+                cpuSampleMs: resolved.cpuSampleMs,
+            };
+            // §7.3: Agent.maxToolConcurrency uses undefined for "unlimited"; the
+            // admission contract uses 0 for the same meaning.
+            const configuredCaps = { maxToolConcurrency: this.agent.maxToolConcurrency ?? 0 };
+            if (resolved.mode === "observe") {
+                void captureHostResourceSnapshot(probeOptions)
+                    .then((snapshot) => {
+                    const decision = decideResourceAdmission({
+                        snapshot,
+                        config: resolved.admission,
+                        configuredCaps,
+                    });
+                    if (this._latestResourcePromptRunId === promptRunId) {
+                        this._lastResourceAdmission = decision;
+                    }
+                    resourceObservations?.record("resource_snapshot_v1", snapshotObservationFacts(snapshot));
+                    resourceObservations?.record("resource_admission_v1", admissionObservationFacts(decision));
+                })
+                    .catch(() => { });
+                return null;
+            }
+            const snapshot = await captureHostResourceSnapshot(probeOptions);
+            const decision = decideResourceAdmission({ snapshot, config: resolved.admission, configuredCaps });
+            if (this._latestResourcePromptRunId === promptRunId) {
+                this._lastResourceAdmission = decision;
+            }
+            resourceObservations?.record("resource_snapshot_v1", snapshotObservationFacts(snapshot));
+            resourceObservations?.record("resource_admission_v1", admissionObservationFacts(decision));
+            this._resourceLeaseController ??= new RunResourceLeaseController({
+                getCap: () => this.agent.maxToolConcurrency,
+                setCap: (cap) => {
+                    this.agent.maxToolConcurrency = cap;
+                },
+            });
+            const lease = this._resourceLeaseController.acquire({ promptRunId, decision });
+            resourceObservations?.record("resource_lease_acquired_v1", {
+                decisionId: decision.decisionId,
+                appliedToolCap: decision.maxToolConcurrency,
+            });
+            return lease;
+        }
+        catch {
+            return null;
+        }
+    }
+    _openResourceObservations(promptRunId) {
+        this._latestResourcePromptRunId = promptRunId;
+        try {
+            const journal = ResourceObservationJournal.open(this._cwd, promptRunId);
+            this._resourceObservations = journal;
+            this._resourceObservationJournals.set(promptRunId, journal);
+            while (this._resourceObservationJournals.size > MAX_RESOURCE_OBSERVATION_JOURNALS) {
+                const oldestPromptRunId = this._resourceObservationJournals.keys().next().value;
+                if (oldestPromptRunId === undefined)
+                    break;
+                this._resourceObservationJournals.delete(oldestPromptRunId);
+            }
+            return journal;
+        }
+        catch {
+            this._resourceObservations = null;
+            this._resourceObservationJournals.delete(promptRunId);
+            return null;
+        }
+    }
+    /** §20.2: record the TUI-side completion sound result in its originating run journal. */
+    recordCompletionSoundResult(promptRunId, result) {
+        const journal = this._resourceObservationJournals.get(promptRunId);
+        journal?.record("completion_sound_result_v1", soundObservationFacts(result));
+        this._resourceObservationJournals.delete(promptRunId);
+        if (this._latestResourcePromptRunId === promptRunId) {
+            this._latestResourcePromptRunId = null;
+            if (this._resourceObservations === journal)
+                this._resourceObservations = null;
+        }
+    }
+    /** §19.4 read-only SDK surface: the most recent resource admission decision, if any. */
+    getCurrentResourceAdmission() {
+        return this._lastResourceAdmission;
+    }
+    /** §19.4 read-only SDK surface: capture a fresh host resource snapshot. */
+    async getHostResourceSnapshot() {
+        const resolved = resolveResourceGovernorSettings(this.settingsManager.getResourceGovernorSettings());
+        return captureHostResourceSnapshot({
+            cwd: this._cwd,
+            maxProbeMs: resolved.maxProbeMs,
+            cpuSampleMs: resolved.cpuSampleMs,
+        });
+    }
+    /** §19.4 read-only SDK surface: shared workload permit pool state, if any. */
+    getWorkloadPermitSnapshot() {
+        return this._workloadPermitPool?.snapshot() ?? null;
+    }
+    /**
+     * §14.1 shared-budget seam: child subagents must reuse this instance
+     * instead of creating a private pool (host oversubscription). The live
+     * child launcher wiring lands in M6.
+     */
+    get workloadPermitPool() {
+        this._workloadPermitPool ??= new WorkloadPermitPool();
+        return this._workloadPermitPool;
+    }
+    /**
+     * Resource safety gate for the bash boundary (roadmap §9.4/§11, M3).
+     * Runs only in adaptive/strict mode with a recorded admission decision;
+     * observe/off keep v0.96.1 behavior. Never throws: gate machinery
+     * failures leave the command ungated (§2.1), while computed block
+     * verdicts and permit rejections return a bounded §11.3 payload.
+     */
+    async _acquireBashResourcePermit(command, signal) {
+        try {
+            const resolved = resolveResourceGovernorSettings(this.settingsManager.getResourceGovernorSettings());
+            if (resolved.mode !== "adaptive" && resolved.mode !== "strict") {
+                return {};
+            }
+            const decision = this._lastResourceAdmission;
+            if (decision === null) {
+                return {};
+            }
+            const classification = classifyWorkloadCommand(command);
+            this._resourceObservations?.record("workload_classification_v1", classificationObservationFacts(classification));
+            const verdict = decideResourceSafetyGate({ commandSafety: "allowed", classification, decision });
+            if (verdict.kind === "allow") {
+                return {};
+            }
+            if (verdict.kind === "block") {
+                return { blocked: JSON.stringify(verdict.block) };
+            }
+            this._workloadPermitPool ??= new WorkloadPermitPool({ capacity: decision.maxHeavyProcesses });
+            const pool = this._workloadPermitPool;
+            pool.setCapacity(decision.maxHeavyProcesses);
+            const waitStartedMs = Date.now();
+            this._resourceObservations?.record("workload_permit_wait_v1", {
+                workloadClass: classification.workloadClass,
+                weight: verdict.weight,
+            });
+            try {
+                const permit = await pool.acquire({
+                    requestId: `bash-${randomUUID()}`,
+                    promptRunId: this._resourceLeaseController?.activeLease?.promptRunId ?? "unleased",
+                    workloadClass: classification.workloadClass,
+                    weight: verdict.weight,
+                    signal,
+                    // Bounded §10.3 timeout-aware wait; a settings knob can follow later.
+                    timeoutMs: 60_000,
+                });
+                this._resourceObservations?.record("workload_permit_acquired_v1", {
+                    workloadClass: classification.workloadClass,
+                    weight: verdict.weight,
+                    waitMs: Date.now() - waitStartedMs,
+                });
+                return {
+                    release: () => {
+                        permit.release();
+                        this._resourceObservations?.record("workload_permit_released_v1", {
+                            workloadClass: classification.workloadClass,
+                            weight: verdict.weight,
+                        });
+                    },
+                };
+            }
+            catch (error) {
+                const code = error instanceof WorkloadPermitError ? error.code : "queue_overflow";
+                return {
+                    blocked: JSON.stringify({
+                        kind: "resource_pressure",
+                        pressure: decision.pressure,
+                        action: "defer-heavy",
+                        reasonCodes: [...decision.reasons, `resource.permit.${code}`],
+                        requiredAction: RESOURCE_PRESSURE_REQUIRED_ACTION,
+                    }),
+                };
+            }
+        }
+        catch {
+            return {};
         }
     }
     async _handlePostAgentRun() {
@@ -1702,8 +1980,13 @@ export class AgentSession {
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const preflightResult = options?.preflightResult;
         let currentText = redactSensitiveText(text);
-        let promptActiveSkillNames = [...(options?.activeSkillNames ?? [])];
-        let promptActiveSkillSource = options?.activeSkillSource;
+        const defaultActiveSkills = this._getDefaultActiveSkills();
+        let promptActiveSkillNames = mergePromptActiveSkillNames(defaultActiveSkills, options?.activeSkillNames ?? []);
+        let promptActiveSkillSource = defaultActiveSkills.length > 0
+            ? options?.activeSkillSource
+                ? `settings+${options.activeSkillSource}`
+                : "settings"
+            : options?.activeSkillSource;
         let isBangSkillInvocation = false;
         if (expandPromptTemplates) {
             const bangInvocation = parseBangInvocation(text, {
@@ -1715,7 +1998,8 @@ export class AgentSession {
                     ? `/skill:${bangInvocation.skillName} ${bangInvocation.prompt}`
                     : `/skill:${bangInvocation.skillName}`;
                 promptActiveSkillNames = mergePromptActiveSkillNames(promptActiveSkillNames, bangInvocation.activeSkillNames);
-                promptActiveSkillSource = bangInvocation.source;
+                promptActiveSkillSource =
+                    defaultActiveSkills.length > 0 ? `settings+${bangInvocation.source}` : bangInvocation.source;
             }
         }
         let messages;
@@ -1819,8 +2103,8 @@ export class AgentSession {
             const turnSystemPromptOptions = {
                 ...this._baseSystemPromptOptions,
                 contextBudget: this._getContextBudgetOptions(expandedText),
-                ...(promptActiveSkillNames.length > 0 ? { activeSkillNames: promptActiveSkillNames } : {}),
-                ...(promptActiveSkillSource ? { activeSkillSource: promptActiveSkillSource } : {}),
+                activeSkillNames: promptActiveSkillNames,
+                activeSkillSource: promptActiveSkillSource,
             };
             const turnSystemPrompt = buildSystemPromptPlan(turnSystemPromptOptions);
             // Emit before_agent_start extension event