@coool/opencode-adaptive 0.0.0-stage → 1.0.1

package/dist/supervisor/supervisor.d.ts

@@ -0,0 +1,86 @@
+import type { TierName } from "../core/tier-policy/types.js";
+import type { OperatingMode } from "../core/scheduler/types.js";
+import type { SettingsV1 } from "../state/settings/index.js";
+import type { PatchResult, SettingsPatch } from "../state/settings/types.js";
+import type { Receipt } from "../state/receipts/types.js";
+import type { StatusSnapshot } from "../rpc/status.js";
+import type { EventReport } from "../adapters/opencode/index.js";
+import type { RetryHookInput, SupervisorOptions } from "./types.js";
+/**
+ * The recovery's post-settle guard aborted it (the session went OFF or the
+ * user interrupted while the host settle was in flight). Callers use it to
+ * skip the ordinary ops-failure degradation (parking) — an aborted recovery
+ * is a steering change, not an infrastructure failure.
+ */
+export declare class RecoveryAbortedError extends Error {
+    constructor(sessionID: string);
+}
+export declare class Supervisor {
+    #private;
+    /** Last agent observed per session (role-hint routing evidence, ADP-002). */
+    static readonly MAX_AGENT_HINTS = 1024;
+    /**
+     * Sessions whose last model change was the user's own pick
+     * (`selected-external`): prompt admission does not re-route them —
+     * switching would undo the user's `/model` choice (ADP-028). Cleared by an
+     * adaptive switch, a tier request, or a mode change; a standing settings
+     * pin overrides the suppression (the pin is manual intent too).
+     */
+    static readonly MAX_MANUAL_SELECTIONS = 1024;
+    constructor(options: SupervisorOptions);
+    /** Handle one host report (event pump or session hook). */
+    handleReport(report: EventReport): Promise<void>;
+    /**
+     * Handle one `retry` hook invocation. On a veto this mutates
+     * `input.decision` to `{ retry: false }`; otherwise the decision is left
+     * untouched and OpenCode's native retry policy stands.
+     */
+    handleRetry(input: RetryHookInput): Promise<void>;
+    /**
+     * Record an escalation-tool request (ADP-015 agent self-report) against the
+     * session's current work unit. Returns false when no unit is active — the
+     * request is then discarded (escalation is a per-unit signal).
+     */
+    noteEscalationRequest(sessionID: string, reason: string, evidence: string): boolean;
+    /**
+     * Record an agent-declared tier request for the session (the adaptive_tier
+     * tool). STICKY: it steers the session's next and following admissions
+     * until cleared — an agent works across many units in one task. Returns
+     * false on an unknown tier (the tool re-validates before calling).
+     *
+     * Fire-and-forget persistence: the recorder signature is sync on both the
+     * tool and the RPC source interfaces, so the write is enqueued without
+     * awaiting it. Readers (routing, getTierRequest, the idle sweep) flush the
+     * store's queue before reading, which makes the record visible
+     * deterministically; a write failure drops the record fail-open (the tool
+     * told the agent "recorded", the persisted mirror simply never sees it —
+     * the same degradation the in-memory map had on restart).
+     */
+    noteTierRequest(sessionID: string, tier: string): boolean;
+    /** The session's tier request, or `null` when it follows the routing ladder. */
+    getTierRequest(sessionID: string): Promise<TierName | null>;
+    /** Clear one session's tier request (`null` is the only valid input). */
+    setTierRequest(sessionID: string, tier: TierName | null): Promise<void>;
+    /** Current settings (awaits the constructor load). */
+    settings(): Promise<SettingsV1>;
+    /** Validate and persist a settings patch; returns per-field errors. */
+    updateSettings(patch: SettingsPatch): Promise<PatchResult>;
+    /** The session's mode override, or `null` when it follows the global mode. */
+    getSessionMode(sessionID: string): Promise<OperatingMode | null>;
+    /**
+     * Persist one session's mode override (`null` clears it). Throws on write
+     * failure — the RPC handler degrades that to an error patch result
+     * (fail-open, ADP-031), while the routing path never calls this.
+     */
+    setSessionMode(sessionID: string, mode: OperatingMode | null): Promise<void>;
+    /**
+     * Bounded status snapshot for the status view (ADP-033). Health is read
+     * from the persisted record set (not the in-memory registry): the serving
+     * instance's registry can be empty when the host's plugin reconciliation
+     * placed the event-pump hooks on another instance, while the persisted
+     * mirror is shared by every instance.
+     */
+    status(): Promise<StatusSnapshot>;
+    /** Newest-first bounded receipt view (ADP-030). */
+    receipts(): Promise<Receipt[]>;
+}