omctest 0.0.1

package/dist/features/background-agent/manager.d.ts

@@ -0,0 +1,179 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import type { ModelFallbackControllerAccessor } from "../../hooks/model-fallback";
+import type { BackgroundTask, LaunchInput, ResumeInput } from "./types";
+import { TaskHistory } from "./task-history";
+import type { BackgroundTaskConfig, TmuxConfig } from "../../config/schema";
+import { type SubagentSpawnContext } from "./subagent-spawn-limits";
+interface EventProperties {
+    sessionID?: string;
+    info?: {
+        id?: string;
+    };
+    [key: string]: unknown;
+}
+interface Event {
+    type: string;
+    properties?: EventProperties;
+}
+export interface SubagentSessionCreatedEvent {
+    sessionID: string;
+    parentID: string;
+    title: string;
+}
+export type OnSubagentSessionCreated = (event: SubagentSessionCreatedEvent) => Promise<void>;
+export interface BackgroundManagerConfig {
+    pluginContext: PluginInput;
+    config?: BackgroundTaskConfig;
+    tmuxConfig?: TmuxConfig;
+    onSubagentSessionCreated?: OnSubagentSessionCreated;
+    onShutdown?: () => void | Promise<void>;
+    enableParentSessionNotifications?: boolean;
+    modelFallbackControllerAccessor?: ModelFallbackControllerAccessor;
+}
+export declare class BackgroundManager {
+    private tasks;
+    private tasksByParentSession;
+    private notifications;
+    private pendingNotifications;
+    private pendingByParent;
+    private client;
+    private directory;
+    private pollingInterval?;
+    private pollingInFlight;
+    private concurrencyManager;
+    private shutdownTriggered;
+    private config?;
+    private tmuxEnabled;
+    private onSubagentSessionCreated?;
+    private onShutdown?;
+    private queuesByKey;
+    private processingKeys;
+    private completionTimers;
+    private completedTaskSummaries;
+    private idleDeferralTimers;
+    private notificationQueueByParent;
+    private observedOutputSessions;
+    private observedIncompleteTodosBySession;
+    private rootDescendantCounts;
+    private preStartDescendantReservations;
+    private enableParentSessionNotifications;
+    private modelFallbackControllerAccessor?;
+    readonly taskHistory: TaskHistory;
+    private cachedCircuitBreakerSettings?;
+    constructor(config: BackgroundManagerConfig);
+    private abortSessionWithLogging;
+    assertCanSpawn(parentSessionID: string): Promise<SubagentSpawnContext>;
+    reserveSubagentSpawn(parentSessionID: string): Promise<{
+        spawnContext: SubagentSpawnContext;
+        descendantCount: number;
+        commit: () => number;
+        rollback: () => void;
+    }>;
+    private registerRootDescendant;
+    private unregisterRootDescendant;
+    private markPreStartDescendantReservation;
+    private settlePreStartDescendantReservation;
+    private rollbackPreStartDescendantReservation;
+    private addTask;
+    private removeTask;
+    private updateTaskParent;
+    private removeTaskFromParentIndex;
+    launch(input: LaunchInput): Promise<BackgroundTask>;
+    private processKey;
+    private startTask;
+    getTask(id: string): BackgroundTask | undefined;
+    getTasksByParentSession(sessionID: string): BackgroundTask[];
+    getAllDescendantTasks(sessionID: string): BackgroundTask[];
+    findBySession(sessionID: string): BackgroundTask | undefined;
+    private resolveTaskAttemptBySession;
+    private getConcurrencyKeyFromInput;
+    /**
+     * Track a task created elsewhere (e.g., from task) for notification tracking.
+     * This allows tasks created by other tools to receive the same toast/prompt notifications.
+     */
+    trackTask(input: {
+        taskId: string;
+        sessionId: string;
+        parentSessionId: string;
+        description: string;
+        agent?: string;
+        parentAgent?: string;
+        concurrencyKey?: string;
+    }): Promise<BackgroundTask>;
+    resume(input: ResumeInput): Promise<BackgroundTask>;
+    private checkSessionTodos;
+    private markSessionOutputObserved;
+    private clearSessionOutputObserved;
+    private clearSessionTodoObservation;
+    private hasOutputSignalFromPart;
+    handleEvent(event: Event): void;
+    private handleSessionErrorEvent;
+    private tryFallbackRetry;
+    markForNotification(task: BackgroundTask): void;
+    getPendingNotifications(sessionID: string): BackgroundTask[];
+    clearNotifications(sessionID: string): void;
+    queuePendingNotification(sessionID: string | undefined, notification: string): void;
+    injectPendingNotificationsIntoChatMessage(output: {
+        parts: Array<{
+            type: string;
+            text?: string;
+            [key: string]: unknown;
+        }>;
+    }, sessionID: string): void;
+    /**
+     * Validates that a session has actual assistant/tool output before marking complete.
+     * Prevents premature completion when session.idle fires before agent responds.
+     */
+    private validateSessionHasOutput;
+    private clearNotificationsForTask;
+    /**
+     * Remove task from pending tracking for its parent session.
+     * Cleans up the parent entry if no pending tasks remain.
+     */
+    private cleanupPendingByParent;
+    private clearTaskHistoryWhenParentTasksGone;
+    private scheduleTaskRemoval;
+    cancelTask(taskId: string, options?: {
+        source?: string;
+        reason?: string;
+        abortSession?: boolean;
+        skipNotification?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Cancels a pending task by removing it from queue and marking as cancelled.
+     * Does NOT abort session (no session exists yet) or release concurrency slot (wasn't acquired).
+     */
+    cancelPendingTask(taskId: string): boolean;
+    private startPolling;
+    private stopPolling;
+    private registerProcessCleanup;
+    private unregisterProcessCleanup;
+    /**
+     * Get all running tasks (for compaction hook)
+     */
+    getRunningTasks(): BackgroundTask[];
+    /**
+     * Get all non-running tasks still in memory (for compaction hook)
+     */
+    getNonRunningTasks(): BackgroundTask[];
+    /**
+     * Safely complete a task with race condition protection.
+     * Returns true if task was successfully completed, false if already completed by another path.
+     */
+    private tryCompleteTask;
+    private notifyParentSession;
+    private hasRunningTasks;
+    private pruneStaleTasksAndNotifications;
+    private checkAndInterruptStaleTasks;
+    private verifySessionExists;
+    private failCrashedTask;
+    private pollRunningTasks;
+    /**
+     * Shutdown the manager gracefully.
+     * Cancels all pending concurrency waiters and clears timers.
+     * Should be called when the plugin is unloaded.
+     */
+    shutdown(): Promise<void>;
+    private enqueueNotificationForParent;
+}
+export {};

package/dist/features/background-agent/opencode-client.d.ts

@@ -0,0 +1,2 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+export type OpencodeClient = PluginInput["client"];

package/dist/features/background-agent/process-cleanup.d.ts

@@ -0,0 +1,8 @@
+interface CleanupTarget {
+    shutdown(): void | Promise<void>;
+}
+export declare function registerManagerForCleanup(manager: CleanupTarget): void;
+export declare function unregisterManagerForCleanup(manager: CleanupTarget): void;
+/** @internal - test-only reset for module-level singleton state */
+export declare function _resetForTesting(): void;
+export {};

package/dist/features/background-agent/process-cleanup.test-helpers.d.ts

@@ -0,0 +1,4 @@
+type ProcessCleanupEvent = NodeJS.Signals | "beforeExit" | "exit" | "uncaughtException" | "unhandledRejection";
+export declare function getNewListener(signal: ProcessCleanupEvent, existingListeners: Function[]): () => void;
+export declare function flushMicrotasks(): Promise<void>;
+export {};

package/dist/features/background-agent/remove-task-toast-tracking.d.ts

@@ -0,0 +1 @@
+export declare function removeTaskToastTracking(taskId: string): void;

package/dist/features/background-agent/session-existence.d.ts

@@ -0,0 +1,3 @@
+import type { OpencodeClient } from "./opencode-client";
+export declare const MIN_SESSION_GONE_POLLS = 3;
+export declare function verifySessionExists(client: OpencodeClient, sessionID: string, directory?: string): Promise<boolean>;

package/dist/features/background-agent/session-idle-event-handler.d.ts

@@ -0,0 +1,10 @@
+import type { BackgroundTask } from "./types";
+export declare function handleSessionIdleBackgroundEvent(args: {
+    properties: Record<string, unknown>;
+    findBySession: (sessionID: string) => BackgroundTask | undefined;
+    idleDeferralTimers: Map<string, ReturnType<typeof setTimeout>>;
+    validateSessionHasOutput: (sessionID: string) => Promise<boolean>;
+    checkSessionTodos: (sessionID: string) => Promise<boolean>;
+    tryCompleteTask: (task: BackgroundTask, source: string) => Promise<boolean>;
+    emitIdleEvent: (sessionID: string) => void;
+}): void;

package/dist/features/background-agent/session-status-classifier.d.ts

@@ -0,0 +1,2 @@
+export declare function isActiveSessionStatus(type: string): boolean;
+export declare function isTerminalSessionStatus(type: string): boolean;

package/dist/features/background-agent/spawner/parent-directory-resolver.d.ts

@@ -0,0 +1,6 @@
+import type { OpencodeClient } from "../constants";
+export declare function resolveParentDirectory(options: {
+    client: OpencodeClient;
+    parentSessionID: string;
+    defaultDirectory: string;
+}): Promise<string>;

package/dist/features/background-agent/spawner.d.ts

@@ -0,0 +1,17 @@
+import type { BackgroundTask, LaunchInput, ResumeInput } from "./types";
+import type { OpencodeClient, OnSubagentSessionCreated, QueueItem } from "./constants";
+import type { ConcurrencyManager } from "./concurrency";
+export declare const FALLBACK_AGENT = "general";
+export declare function isAgentNotFoundError(error: unknown): boolean;
+export declare function buildFallbackBody(originalBody: Record<string, unknown>, fallbackAgent: string): Record<string, unknown>;
+export interface SpawnerContext {
+    client: OpencodeClient;
+    directory: string;
+    concurrencyManager: ConcurrencyManager;
+    tmuxEnabled: boolean;
+    onSubagentSessionCreated?: OnSubagentSessionCreated;
+    onTaskError: (task: BackgroundTask, error: Error) => void;
+}
+export declare function createTask(input: LaunchInput): BackgroundTask;
+export declare function startTask(item: QueueItem, ctx: SpawnerContext): Promise<void>;
+export declare function resumeTask(task: BackgroundTask, input: ResumeInput, ctx: Pick<SpawnerContext, "client" | "concurrencyManager" | "onTaskError">): Promise<void>;

package/dist/features/background-agent/state.d.ts

@@ -0,0 +1,35 @@
+import type { BackgroundTask, LaunchInput } from "./types";
+import type { QueueItem } from "./constants";
+export declare class TaskStateManager {
+    readonly tasks: Map<string, BackgroundTask>;
+    readonly notifications: Map<string, BackgroundTask[]>;
+    readonly pendingByParent: Map<string, Set<string>>;
+    readonly queuesByKey: Map<string, QueueItem[]>;
+    readonly processingKeys: Set<string>;
+    readonly completionTimers: Map<string, ReturnType<typeof setTimeout>>;
+    getTask(id: string): BackgroundTask | undefined;
+    findBySession(sessionID: string): BackgroundTask | undefined;
+    getTasksByParentSession(sessionID: string): BackgroundTask[];
+    getAllDescendantTasks(sessionID: string): BackgroundTask[];
+    getRunningTasks(): BackgroundTask[];
+    getNonRunningTasks(): BackgroundTask[];
+    hasRunningTasks(): boolean;
+    getConcurrencyKeyFromInput(input: LaunchInput): string;
+    getConcurrencyKeyFromTask(task: BackgroundTask): string;
+    addTask(task: BackgroundTask): void;
+    removeTask(taskId: string): void;
+    trackPendingTask(parentSessionID: string, taskId: string): void;
+    cleanupPendingByParent(task: BackgroundTask): void;
+    markForNotification(task: BackgroundTask): void;
+    getPendingNotifications(sessionID: string): BackgroundTask[];
+    clearNotifications(sessionID: string): void;
+    clearNotificationsForTask(taskId: string): void;
+    addToQueue(key: string, item: QueueItem): void;
+    getQueue(key: string): QueueItem[] | undefined;
+    removeFromQueue(key: string, taskId: string): boolean;
+    setCompletionTimer(taskId: string, timer: ReturnType<typeof setTimeout>): void;
+    clearCompletionTimer(taskId: string): void;
+    clearAllCompletionTimers(): void;
+    clear(): void;
+    cancelPendingTask(taskId: string): boolean;
+}

package/dist/features/background-agent/subagent-spawn-limits.d.ts

@@ -0,0 +1,16 @@
+import type { BackgroundTaskConfig } from "../../config/schema";
+import type { OpencodeClient } from "./constants";
+export declare const DEFAULT_MAX_SUBAGENT_DEPTH = 3;
+export interface SubagentSpawnContext {
+    rootSessionID: string;
+    parentDepth: number;
+    childDepth: number;
+}
+export declare function getMaxSubagentDepth(config?: BackgroundTaskConfig): number;
+export declare function resolveSubagentSpawnContext(client: OpencodeClient, parentSessionID: string, directory?: string): Promise<SubagentSpawnContext>;
+export declare function createSubagentDepthLimitError(input: {
+    childDepth: number;
+    maxDepth: number;
+    parentSessionID: string;
+    rootSessionID: string;
+}): Error;

package/dist/features/background-agent/task-history.d.ts

@@ -0,0 +1,19 @@
+import type { BackgroundTaskStatus } from "./types";
+export interface TaskHistoryEntry {
+    id: string;
+    sessionID?: string;
+    agent: string;
+    description: string;
+    status: BackgroundTaskStatus;
+    category?: string;
+    startedAt?: Date;
+    completedAt?: Date;
+}
+export declare class TaskHistory {
+    private entries;
+    record(parentSessionID: string | undefined, entry: TaskHistoryEntry): void;
+    getByParentSession(parentSessionID: string): TaskHistoryEntry[];
+    clearSession(parentSessionID: string): void;
+    clearAll(): void;
+    formatForCompaction(parentSessionID: string): string | null;
+}

package/dist/features/background-agent/task-poller.d.ts

@@ -0,0 +1,23 @@
+import type { BackgroundTaskConfig } from "../../config/schema";
+import type { BackgroundTask } from "./types";
+import type { ConcurrencyManager } from "./concurrency";
+import type { OpencodeClient } from "./opencode-client";
+export declare function pruneStaleTasksAndNotifications(args: {
+    tasks: Map<string, BackgroundTask>;
+    notifications: Map<string, BackgroundTask[]>;
+    onTaskPruned: (taskId: string, task: BackgroundTask, errorMessage: string) => void;
+    taskTtlMs?: number;
+}): void;
+export type SessionStatusMap = Record<string, {
+    type: string;
+}>;
+export declare function checkAndInterruptStaleTasks(args: {
+    tasks: Iterable<BackgroundTask>;
+    client: OpencodeClient;
+    directory?: string;
+    config: BackgroundTaskConfig | undefined;
+    concurrencyManager: ConcurrencyManager;
+    notifyParentSession: (task: BackgroundTask) => Promise<void>;
+    sessionStatuses?: SessionStatusMap;
+    onTaskInterrupted?: (task: BackgroundTask) => void;
+}): Promise<void>;

package/dist/features/background-agent/types.d.ts

@@ -0,0 +1,120 @@
+import type { FallbackEntry } from "../../shared/model-requirements";
+import type { DelegatedModelConfig } from "../../shared/model-resolution-types";
+import type { SessionPermissionRule } from "../../shared/question-denied-session-permission";
+export type BackgroundTaskStatus = "pending" | "running" | "completed" | "error" | "cancelled" | "interrupt";
+export interface ToolCallWindow {
+    lastSignature: string;
+    consecutiveCount: number;
+    threshold: number;
+}
+export interface TaskProgress {
+    toolCalls: number;
+    lastTool?: string;
+    toolCallWindow?: ToolCallWindow;
+    countedToolPartIDs?: Set<string>;
+    lastUpdate: Date;
+    lastMessage?: string;
+    lastMessageAt?: Date;
+}
+export type BackgroundTaskAttemptStatus = BackgroundTaskStatus;
+export interface BackgroundTaskAttempt {
+    attemptId: string;
+    attemptNumber: number;
+    sessionId?: string;
+    providerId?: string;
+    modelId?: string;
+    variant?: string;
+    status: BackgroundTaskAttemptStatus;
+    error?: string;
+    startedAt?: Date;
+    completedAt?: Date;
+}
+export interface BackgroundTask {
+    id: string;
+    sessionId?: string;
+    rootSessionId?: string;
+    parentSessionId: string;
+    parentMessageId: string;
+    description: string;
+    prompt: string;
+    agent: string;
+    spawnDepth?: number;
+    status: BackgroundTaskStatus;
+    queuedAt?: Date;
+    startedAt?: Date;
+    completedAt?: Date;
+    result?: string;
+    error?: string;
+    progress?: TaskProgress;
+    parentModel?: {
+        providerID: string;
+        modelID: string;
+    };
+    model?: DelegatedModelConfig;
+    /** Fallback chain for runtime retry on model errors */
+    fallbackChain?: FallbackEntry[];
+    /** Number of fallback retry attempts made */
+    attemptCount?: number;
+    /** Active concurrency slot key */
+    concurrencyKey?: string;
+    /** Persistent key for re-acquiring concurrency on resume */
+    concurrencyGroup?: string;
+    /** Parent session's agent name for notification */
+    parentAgent?: string;
+    /** Parent session's tool restrictions for notification prompts */
+    parentTools?: Record<string, boolean>;
+    /** Marks if the task was launched from an unstable agent/category */
+    isUnstableAgent?: boolean;
+    /** Category used for this task (e.g., 'quick', 'visual-engineering') */
+    category?: string;
+    /** Pending retry notification details for the next spawned retry session */
+    retryNotification?: {
+        previousSessionID?: string;
+        failedModel?: string;
+        failedError?: string;
+        nextModel: string;
+    };
+    /** Structured attempt history for retry observability */
+    attempts?: BackgroundTaskAttempt[];
+    /** ID of the currently active attempt */
+    currentAttemptID?: string;
+    /** Last message count for stability detection */
+    lastMsgCount?: number;
+    /** Number of consecutive polls with stable message count */
+    stablePolls?: number;
+    /** Number of consecutive polls where session was missing from status map */
+    consecutiveMissedPolls?: number;
+}
+export interface LaunchInput {
+    description: string;
+    prompt: string;
+    agent: string;
+    parentSessionId: string;
+    parentMessageId: string;
+    parentModel?: {
+        providerID: string;
+        modelID: string;
+    };
+    parentAgent?: string;
+    parentTools?: Record<string, boolean>;
+    model?: DelegatedModelConfig;
+    /** Fallback chain for runtime retry on model errors */
+    fallbackChain?: FallbackEntry[];
+    isUnstableAgent?: boolean;
+    skills?: string[];
+    skillContent?: string;
+    category?: string;
+    sessionPermission?: SessionPermissionRule[];
+}
+export interface ResumeInput {
+    sessionId: string;
+    prompt: string;
+    parentSessionId: string;
+    parentMessageId: string;
+    parentModel?: {
+        providerID: string;
+        modelID: string;
+    };
+    parentAgent?: string;
+    parentTools?: Record<string, boolean>;
+}

package/dist/features/background-agent/wait-for-task-session.d.ts

@@ -0,0 +1,17 @@
+import type { BackgroundTaskStatus } from "./types";
+type AbortSignalLike = {
+    aborted: boolean;
+};
+interface TaskReader {
+    getTask(taskID: string): {
+        sessionId?: string;
+        status?: BackgroundTaskStatus;
+    } | undefined;
+}
+export interface WaitForTaskSessionIDOptions {
+    timeoutMs?: number;
+    intervalMs?: number;
+    signal?: AbortSignalLike;
+}
+export declare function waitForTaskSessionID(manager: TaskReader, taskID: string, options?: WaitForTaskSessionIDOptions): Promise<string | undefined>;
+export {};

package/dist/features/boulder-state/constants.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Boulder State Constants
+ */
+export declare const BOULDER_DIR = ".sisyphus";
+export declare const BOULDER_FILE = "boulder.json";
+export declare const BOULDER_STATE_PATH = ".sisyphus/boulder.json";
+export declare const NOTEPAD_DIR = "notepads";
+export declare const NOTEPAD_BASE_PATH = ".sisyphus/notepads";
+/** Prometheus plan directory pattern */
+export declare const PROMETHEUS_PLANS_DIR = ".sisyphus/plans";

package/dist/features/boulder-state/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types";
+export * from "./constants";
+export * from "./storage";
+export * from "./top-level-task";

package/dist/features/boulder-state/storage.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Boulder State Storage
+ *
+ * Handles reading/writing boulder.json for active plan tracking.
+ */
+import type { BoulderState, PlanProgress, TaskSessionState } from "./types";
+export declare function getBoulderFilePath(directory: string): string;
+export declare function readBoulderState(directory: string): BoulderState | null;
+export declare function writeBoulderState(directory: string, state: BoulderState): boolean;
+export declare function appendSessionId(directory: string, sessionId: string, origin?: "direct" | "appended"): BoulderState | null;
+export declare function clearBoulderState(directory: string): boolean;
+export declare function getTaskSessionState(directory: string, taskKey: string): TaskSessionState | null;
+export declare function upsertTaskSessionState(directory: string, input: {
+    taskKey: string;
+    taskLabel: string;
+    taskTitle: string;
+    sessionId: string;
+    agent?: string;
+    category?: string;
+}): BoulderState | null;
+/**
+ * Find Prometheus plan files for this project.
+ * Prometheus stores plans at: {project}/.sisyphus/plans/{name}.md
+ */
+export declare function findPrometheusPlans(directory: string): string[];
+/**
+ * Parse a plan file and count checkbox progress.
+ *
+ * Only top-level (zero-indent) checkboxes under `## TODOs` and
+ * `## Final Verification Wave` sections are counted. The checkbox
+ * body must carry a valid task label (`N.` for TODOs, `FN.` for
+ * Final Verification Wave). Nested acceptance-criteria checkboxes
+ * and checkboxes in other sections are intentionally ignored so
+ * that progress tracking stays aligned with `readCurrentTopLevelTask`.
+ */
+export declare function getPlanProgress(planPath: string): PlanProgress;
+/**
+ * Extract plan name from file path.
+ */
+export declare function getPlanName(planPath: string): string;
+/**
+ * Create a new boulder state for a plan.
+ */
+export declare function createBoulderState(planPath: string, sessionId: string, agent?: string, worktreePath?: string): BoulderState;

package/dist/features/boulder-state/top-level-task.d.ts

@@ -0,0 +1,2 @@
+import type { TopLevelTaskRef } from "./types";
+export declare function readCurrentTopLevelTask(planPath: string): TopLevelTaskRef | null;

package/dist/features/boulder-state/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Boulder State Types
+ *
+ * Manages the active work plan state for Sisyphus orchestrator.
+ * Named after Sisyphus's boulder - the eternal task that must be rolled.
+ */
+export interface BoulderState {
+    /** Absolute path to the active plan file */
+    active_plan: string;
+    /** ISO timestamp when work started */
+    started_at: string;
+    /** Session IDs that have worked on this plan */
+    session_ids: string[];
+    session_origins?: Record<string, "direct" | "appended">;
+    /** Plan name derived from filename */
+    plan_name: string;
+    /** Agent type to use when resuming (e.g., 'atlas') */
+    agent?: string;
+    /** Absolute path to the git worktree root where work happens */
+    worktree_path?: string;
+    /** Preferred reusable subagent sessions keyed by current top-level plan task */
+    task_sessions?: Record<string, TaskSessionState>;
+}
+export interface PlanProgress {
+    /** Total number of checkboxes */
+    total: number;
+    /** Number of completed checkboxes */
+    completed: number;
+    /** Whether all tasks are done */
+    isComplete: boolean;
+}
+export interface TaskSessionState {
+    /** Stable identifier for the current top-level plan task (e.g. todo:1 / final-wave:F1) */
+    task_key: string;
+    /** Original task label from the plan file */
+    task_label: string;
+    /** Full task title from the plan file */
+    task_title: string;
+    /** Preferred reusable subagent session */
+    session_id: string;
+    /** Agent associated with the task session, when known */
+    agent?: string;
+    /** Category associated with the task session, when known */
+    category?: string;
+    /** Last update timestamp */
+    updated_at: string;
+}
+export interface TopLevelTaskRef {
+    /** Stable identifier for the current top-level plan task */
+    key: string;
+    /** Task section in the Prometheus plan */
+    section: "todo" | "final-wave";
+    /** Original label token (e.g. 1 / F1) */
+    label: string;
+    /** Full task title extracted from the checkbox line */
+    title: string;
+}

package/dist/features/builtin-commands/commands.d.ts

@@ -0,0 +1,6 @@
+import type { BuiltinCommandName, BuiltinCommands } from "./types";
+interface LoadBuiltinCommandsOptions {
+    useRegisteredAgents?: boolean;
+}
+export declare function loadBuiltinCommands(disabledCommands?: BuiltinCommandName[], options?: LoadBuiltinCommandsOptions): BuiltinCommands;
+export {};

package/dist/features/builtin-commands/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./commands";

package/dist/features/builtin-commands/templates/handoff.d.ts

@@ -0,0 +1 @@
+export declare const HANDOFF_TEMPLATE = "# Handoff Command\n\n## Purpose\n\nUse /handoff when:\n- The current session context is getting too long and quality is degrading\n- You want to start fresh while preserving essential context from this session\n- The context window is approaching capacity\n\nThis creates a detailed context summary that can be used to continue work in a new session.\n\n---\n\n# PHASE 0: VALIDATE REQUEST\n\nBefore proceeding, confirm:\n- [ ] There is meaningful work or context in this session to preserve\n- [ ] The user wants to create a handoff summary (not just asking about it)\n\nIf the session is nearly empty or has no meaningful context, inform the user there is nothing substantial to hand off.\n\n---\n\n# PHASE 1: GATHER PROGRAMMATIC CONTEXT\n\nExecute these tools to gather concrete data:\n\n1. session_read({ session_id: \"$SESSION_ID\" }) - full session history\n2. todoread() - current task progress\n3. Bash({ command: \"git diff --stat HEAD~10..HEAD\" }) - recent file changes\n4. Bash({ command: \"git status --porcelain\" }) - uncommitted changes\n\nSuggested execution order:\n\n```\nsession_read({ session_id: \"$SESSION_ID\" })\ntodoread()\nBash({ command: \"git diff --stat HEAD~10..HEAD\" })\nBash({ command: \"git status --porcelain\" })\n```\n\nAnalyze the gathered outputs to understand:\n- What the user asked for (exact wording)\n- What work was completed\n- What tasks remain incomplete (include todo state)\n- What decisions were made\n- What files were modified or discussed (include git diff/stat + status)\n- What patterns, constraints, or preferences were established\n\n---\n\n# PHASE 2: EXTRACT CONTEXT\n\nWrite the context summary from first person perspective (\"I did...\", \"I told you...\").\n\nFocus on:\n- Capabilities and behavior, not file-by-file implementation details\n- What matters for continuing the work\n- Avoiding excessive implementation details (variable names, storage keys, constants) unless critical\n- USER REQUESTS (AS-IS) must be verbatim (do not paraphrase)\n- EXPLICIT CONSTRAINTS must be verbatim only (do not invent)\n\nQuestions to consider when extracting:\n- What did I just do or implement?\n- What instructions did I already give which are still relevant (e.g. follow patterns in the codebase)?\n- What files did I tell you are important or that I am working on?\n- Did I provide a plan or spec that should be included?\n- What did I already tell you that is important (libraries, patterns, constraints, preferences)?\n- What important technical details did I discover (APIs, methods, patterns)?\n- What caveats, limitations, or open questions did I find?\n\n---\n\n# PHASE 3: FORMAT OUTPUT\n\nGenerate a handoff summary using this exact format:\n\n```\nHANDOFF CONTEXT\n===============\n\nUSER REQUESTS (AS-IS)\n---------------------\n- [Exact verbatim user requests - NOT paraphrased]\n\nGOAL\n----\n[One sentence describing what should be done next]\n\nWORK COMPLETED\n--------------\n- [First person bullet points of what was done]\n- [Include specific file paths when relevant]\n- [Note key implementation decisions]\n\nCURRENT STATE\n-------------\n- [Current state of the codebase or task]\n- [Build/test status if applicable]\n- [Any environment or configuration state]\n\nPENDING TASKS\n-------------\n- [Tasks that were planned but not completed]\n- [Next logical steps to take]\n- [Any blockers or issues encountered]\n- [Include current todo state from todoread()]\n\nKEY FILES\n---------\n- [path/to/file1] - [brief role description]\n- [path/to/file2] - [brief role description]\n(Maximum 10 files, prioritized by importance)\n- (Include files from git diff/stat and git status)\n\nIMPORTANT DECISIONS\n-------------------\n- [Technical decisions that were made and why]\n- [Trade-offs that were considered]\n- [Patterns or conventions established]\n\nEXPLICIT CONSTRAINTS\n--------------------\n- [Verbatim constraints only - from user or existing AGENTS.md]\n- If none, write: None\n\nCONTEXT FOR CONTINUATION\n------------------------\n- [What the next session needs to know to continue]\n- [Warnings or gotchas to be aware of]\n- [References to documentation if relevant]\n```\n\nRules for the summary:\n- Plain text with bullets\n- No markdown headers with # (use the format above with dashes)\n- No bold, italic, or code fences within content\n- Use workspace-relative paths for files\n- Keep it focused - only include what matters for continuation\n- Pick an appropriate length based on complexity\n- USER REQUESTS (AS-IS) and EXPLICIT CONSTRAINTS must be verbatim only\n\n---\n\n# PHASE 4: PROVIDE INSTRUCTIONS\n\nAfter generating the summary, instruct the user:\n\n```\n---\n\nTO CONTINUE IN A NEW SESSION:\n\n1. Press 'n' in OpenCode TUI to open a new session, or run 'opencode' in a new terminal\n2. Paste the HANDOFF CONTEXT above as your first message\n3. Add your request: \"Continue from the handoff context above. [Your next task]\"\n\nThe new session will have all context needed to continue seamlessly.\n```\n\n---\n\n# IMPORTANT CONSTRAINTS\n\n- DO NOT attempt to programmatically create new sessions (no API available to agents)\n- DO provide a self-contained summary that works without access to this session\n- DO include workspace-relative file paths\n- DO NOT include sensitive information (API keys, credentials, secrets)\n- DO NOT exceed 10 files in the KEY FILES section\n- DO keep the GOAL section to a single sentence or short paragraph\n\n---\n\n# EXECUTE NOW\n\nBegin by gathering programmatic context, then synthesize the handoff summary.\n";