@wolfx/oh-my-openagent 3.17.4-beta.1

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

@@ -0,0 +1,167 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+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 declare class BackgroundManager {
+    private tasks;
+    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;
+    readonly taskHistory: TaskHistory;
+    private cachedCircuitBreakerSettings?;
+    constructor(ctx: PluginInput, config?: BackgroundTaskConfig, options?: {
+        tmuxConfig?: TmuxConfig;
+        onSubagentSessionCreated?: OnSubagentSessionCreated;
+        onShutdown?: () => void | Promise<void>;
+        enableParentSessionNotifications?: boolean;
+    });
+    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;
+    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 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/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,23 @@
+import type { BackgroundTaskConfig } from "../../config/schema";
+import type { OpencodeClient } from "./constants";
+export declare const DEFAULT_MAX_SUBAGENT_DEPTH = 3;
+export declare const DEFAULT_MAX_ROOT_SESSION_SPAWN_BUDGET = 50;
+export interface SubagentSpawnContext {
+    rootSessionID: string;
+    parentDepth: number;
+    childDepth: number;
+}
+export declare function getMaxSubagentDepth(config?: BackgroundTaskConfig): number;
+export declare function getMaxRootSessionSpawnBudget(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;
+export declare function createSubagentDescendantLimitError(input: {
+    rootSessionID: string;
+    descendantCount: number;
+    maxDescendants: number;
+}): 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,96 @@
+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 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;
+    /** 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";

package/dist/features/builtin-commands/templates/init-deep.d.ts

@@ -0,0 +1 @@
+export declare const INIT_DEEP_TEMPLATE = "# /init-deep\n\nGenerate hierarchical AGENTS.md files. Root + complexity-scored subdirectories.\n\n## Usage\n\n```\n/init-deep                      # Update mode: modify existing + create new where warranted\n/init-deep --create-new         # Read existing \u2192 remove all \u2192 regenerate from scratch\n/init-deep --max-depth=2        # Limit directory depth (default: 3)\n```\n\n---\n\n## Workflow (High-Level)\n\n1. **Discovery + Analysis** (concurrent)\n   - Fire background explore agents immediately\n   - Main session: bash structure + LSP codemap + read existing AGENTS.md\n2. **Score & Decide** - Determine AGENTS.md locations from merged findings\n3. **Generate** - Root first, then subdirs in parallel\n4. **Review** - Deduplicate, trim, validate\n\n<critical>\n**TodoWrite ALL phases. Mark in_progress \u2192 completed in real-time.**\n```\nTodoWrite([\n  { id: \"discovery\", content: \"Fire explore agents + LSP codemap + read existing\", status: \"pending\", priority: \"high\" },\n  { id: \"scoring\", content: \"Score directories, determine locations\", status: \"pending\", priority: \"high\" },\n  { id: \"generate\", content: \"Generate AGENTS.md files (root + subdirs)\", status: \"pending\", priority: \"high\" },\n  { id: \"review\", content: \"Deduplicate, validate, trim\", status: \"pending\", priority: \"medium\" }\n])\n```\n</critical>\n\n---\n\n## Phase 1: Discovery + Analysis (Concurrent)\n\n**Mark \"discovery\" as in_progress.**\n\n### Fire Background Explore Agents IMMEDIATELY\n\nDon't wait-these run async while main session works.\n\n```\n// Fire all at once, collect results later\ntask(subagent_type=\"explore\", load_skills=[], description=\"Explore project structure\", run_in_background=true, prompt=\"Project structure: PREDICT standard patterns for detected language \u2192 REPORT deviations only\")\ntask(subagent_type=\"explore\", load_skills=[], description=\"Find entry points\", run_in_background=true, prompt=\"Entry points: FIND main files \u2192 REPORT non-standard organization\")\ntask(subagent_type=\"explore\", load_skills=[], description=\"Find conventions\", run_in_background=true, prompt=\"Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig) \u2192 REPORT project-specific rules\")\ntask(subagent_type=\"explore\", load_skills=[], description=\"Find anti-patterns\", run_in_background=true, prompt=\"Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments \u2192 LIST forbidden patterns\")\ntask(subagent_type=\"explore\", load_skills=[], description=\"Explore build/CI\", run_in_background=true, prompt=\"Build/CI: FIND .github/workflows, Makefile \u2192 REPORT non-standard patterns\")\ntask(subagent_type=\"explore\", load_skills=[], description=\"Find test patterns\", run_in_background=true, prompt=\"Test patterns: FIND test configs, test structure \u2192 REPORT unique conventions\")\n```\n\n<dynamic-agents>\n**DYNAMIC AGENT SPAWNING**: After bash analysis, spawn ADDITIONAL explore agents based on project scale:\n\n| Factor | Threshold | Additional Agents |\n|--------|-----------|-------------------|\n| **Total files** | >100 | +1 per 100 files |\n| **Total lines** | >10k | +1 per 10k lines |\n| **Directory depth** | \u22654 | +2 for deep exploration |\n| **Large files (>500 lines)** | >10 files | +1 for complexity hotspots |\n| **Monorepo** | detected | +1 per package/workspace |\n| **Multiple languages** | >1 | +1 per language |\n\n```bash\n# Measure project scale first\ntotal_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)\ntotal_lines=$(find . -type f \\( -name \"*.ts\" -o -name \"*.py\" -o -name \"*.go\" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')\nlarge_files=$(find . -type f \\( -name \"*.ts\" -o -name \"*.py\" \\) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {count++} END {print count+0}')\nmax_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1)\n```\n\nExample spawning:\n```\n// 500 files, 50k lines, depth 6, 15 large files \u2192 spawn 5+5+2+1 = 13 additional agents\ntask(subagent_type=\"explore\", load_skills=[], description=\"Analyze large files\", run_in_background=true, prompt=\"Large file analysis: FIND files >500 lines, REPORT complexity hotspots\")\ntask(subagent_type=\"explore\", load_skills=[], description=\"Explore deep modules\", run_in_background=true, prompt=\"Deep modules at depth 4+: FIND hidden patterns, internal conventions\")\ntask(subagent_type=\"explore\", load_skills=[], description=\"Find shared utilities\", run_in_background=true, prompt=\"Cross-cutting concerns: FIND shared utilities across directories\")\n// ... more based on calculation\n```\n</dynamic-agents>\n\n### Main Session: Concurrent Analysis\n\n**While background agents run**, main session does:\n\n#### 1. Bash Structural Analysis\n```bash\n# Directory depth + file counts\nfind . -type d -not -path '*/\\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c\n\n# Files per directory (top 30)\nfind . -type f -not -path '*/\\.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30\n\n# Code concentration by extension\nfind . -type f \\( -name \"*.py\" -o -name \"*.ts\" -o -name \"*.tsx\" -o -name \"*.js\" -o -name \"*.go\" -o -name \"*.rs\" \\) -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20\n\n# Existing AGENTS.md / CLAUDE.md\nfind . -type f \\( -name \"AGENTS.md\" -o -name \"CLAUDE.md\" \\) -not -path '*/node_modules/*' 2>/dev/null\n```\n\n#### 2. Read Existing AGENTS.md\n```\nFor each existing file found:\n  Read(filePath=file)\n  Extract: key insights, conventions, anti-patterns\n  Store in EXISTING_AGENTS map\n```\n\nIf `--create-new`: Read all existing first (preserve context) \u2192 then delete all \u2192 regenerate.\n\n#### 3. LSP Codemap (if available)\n```\nLspServers()  # Check availability\n\n# Entry points (parallel)\nLspDocumentSymbols(filePath=\"src/index.ts\")\nLspDocumentSymbols(filePath=\"main.py\")\n\n# Key symbols (parallel)\nLspWorkspaceSymbols(filePath=\".\", query=\"class\")\nLspWorkspaceSymbols(filePath=\".\", query=\"interface\")\nLspWorkspaceSymbols(filePath=\".\", query=\"function\")\n\n# Centrality for top exports\nLspFindReferences(filePath=\"...\", line=X, character=Y)\n```\n\n**LSP Fallback**: If unavailable, rely on explore agents + AST-grep.\n\n### Collect Background Results\n\n```\n// After main session analysis done, collect all task results\nfor each task_id: background_output(task_id=\"...\")\n```\n\n**Merge: bash + LSP + existing + explore findings. Mark \"discovery\" as completed.**\n\n---\n\n## Phase 2: Scoring & Location Decision\n\n**Mark \"scoring\" as in_progress.**\n\n### Scoring Matrix\n\n| Factor | Weight | High Threshold | Source |\n|--------|--------|----------------|--------|\n| File count | 3x | >20 | bash |\n| Subdir count | 2x | >5 | bash |\n| Code ratio | 2x | >70% | bash |\n| Unique patterns | 1x | Has own config | explore |\n| Module boundary | 2x | Has index.ts/__init__.py | bash |\n| Symbol density | 2x | >30 symbols | LSP |\n| Export count | 2x | >10 exports | LSP |\n| Reference centrality | 3x | >20 refs | LSP |\n\n### Decision Rules\n\n| Score | Action |\n|-------|--------|\n| **Root (.)** | ALWAYS create |\n| **>15** | Create AGENTS.md |\n| **8-15** | Create if distinct domain |\n| **<8** | Skip (parent covers) |\n\n### Output\n```\nAGENTS_LOCATIONS = [\n  { path: \".\", type: \"root\" },\n  { path: \"src/hooks\", score: 18, reason: \"high complexity\" },\n  { path: \"src/api\", score: 12, reason: \"distinct domain\" }\n]\n```\n\n**Mark \"scoring\" as completed.**\n\n---\n\n## Phase 3: Generate AGENTS.md\n\n**Mark \"generate\" as in_progress.**\n\n<critical>\n**File Writing Rule**: If AGENTS.md already exists at the target path \u2192 use `Edit` tool. If it does NOT exist \u2192 use `Write` tool.\nNEVER use Write to overwrite an existing file. ALWAYS check existence first via `Read` or discovery results.\n</critical>\n\n### Root AGENTS.md (Full Treatment)\n\n```markdown\n# PROJECT KNOWLEDGE BASE\n\n**Generated:** {TIMESTAMP}\n**Commit:** {SHORT_SHA}\n**Branch:** {BRANCH}\n\n## OVERVIEW\n{1-2 sentences: what + core stack}\n\n## STRUCTURE\n\\`\\`\\`\n{root}/\n\u251C\u2500\u2500 {dir}/    # {non-obvious purpose only}\n\u2514\u2500\u2500 {entry}\n\\`\\`\\`\n\n## WHERE TO LOOK\n| Task | Location | Notes |\n|------|----------|-------|\n\n## CODE MAP\n{From LSP - skip if unavailable or project <10 files}\n\n| Symbol | Type | Location | Refs | Role |\n|--------|------|----------|------|------|\n\n## CONVENTIONS\n{ONLY deviations from standard}\n\n## ANTI-PATTERNS (THIS PROJECT)\n{Explicitly forbidden here}\n\n## UNIQUE STYLES\n{Project-specific}\n\n## COMMANDS\n\\`\\`\\`bash\n{dev/test/build}\n\\`\\`\\`\n\n## NOTES\n{Gotchas}\n```\n\n**Quality gates**: 50-150 lines, no generic advice, no obvious info.\n\n### Subdirectory AGENTS.md (Parallel)\n\nLaunch writing tasks for each location:\n\n```\nfor loc in AGENTS_LOCATIONS (except root):\n  task(category=\"writing\", load_skills=[], run_in_background=false, description=\"Generate AGENTS.md\", prompt=\\`\n    Generate AGENTS.md for: ${loc.path}\n    - Reason: ${loc.reason}\n    - 30-80 lines max\n    - NEVER repeat parent content\n    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS\n  \\`)\n```\n\n**Wait for all. Mark \"generate\" as completed.**\n\n---\n\n## Phase 4: Review & Deduplicate\n\n**Mark \"review\" as in_progress.**\n\nFor each generated file:\n- Remove generic advice\n- Remove parent duplicates\n- Trim to size limits\n- Verify telegraphic style\n\n**Mark \"review\" as completed.**\n\n---\n\n## Final Report\n\n```\n=== init-deep Complete ===\n\nMode: {update | create-new}\n\nFiles:\n  [OK] ./AGENTS.md (root, {N} lines)\n  [OK] ./src/hooks/AGENTS.md ({N} lines)\n\nDirs Analyzed: {N}\nAGENTS.md Created: {N}\nAGENTS.md Updated: {N}\n\nHierarchy:\n  ./AGENTS.md\n  \u2514\u2500\u2500 src/hooks/AGENTS.md\n```\n\n---\n\n## Anti-Patterns\n\n- **Static agent count**: MUST vary agents based on project size/depth\n- **Sequential execution**: MUST parallel (explore + LSP concurrent)\n- **Ignoring existing**: ALWAYS read existing first, even with --create-new\n- **Over-documenting**: Not every dir needs AGENTS.md\n- **Redundancy**: Child never repeats parent\n- **Generic content**: Remove anything that applies to ALL projects\n- **Verbose style**: Telegraphic or die";

package/dist/features/builtin-commands/templates/ralph-loop.d.ts

@@ -0,0 +1,3 @@
+export declare const RALPH_LOOP_TEMPLATE = "You are starting a Ralph Loop - a self-referential development loop that runs until task completion.\n\n## How Ralph Loop Works\n\n1. You will work on the task continuously\n2. When you believe the task is FULLY complete, output: `<promise>{{COMPLETION_PROMISE}}</promise>`\n3. If you don't output the promise, the loop will automatically inject another prompt to continue\n4. Maximum iterations: Configurable (default 100)\n\n## Rules\n\n- Focus on completing the task fully, not partially\n- Don't output the completion promise until the task is truly done\n- Each iteration should make meaningful progress toward the goal\n- If stuck, try different approaches\n- Use todos to track your progress\n\n## Exit Conditions\n\n1. **Completion**: Output your completion promise tag when fully complete\n2. **Max Iterations**: Loop stops automatically at limit\n3. **Cancel**: User runs `/cancel-ralph` command\n\n## Your Task\n\nParse the arguments below and begin working on the task. The format is:\n`\"task description\" [--completion-promise=TEXT] [--max-iterations=N] [--strategy=reset|continue]`\n\nDefault completion promise is \"DONE\" and default max iterations is 100.";
+export declare const ULW_LOOP_TEMPLATE = "You are starting an ULTRAWORK Loop - a self-referential development loop that runs until verified completion.\n\n## How ULTRAWORK Loop Works\n\n1. You will work on the task continuously\n2. When you believe the work is complete, output: `<promise>{{COMPLETION_PROMISE}}</promise>`\n3. That does NOT finish the loop yet. The system will require Oracle verification\n4. The loop only ends after the system confirms Oracle verified the result\n5. The iteration limit is 500 for ultrawork mode, 100 for normal mode\n\n## Rules\n\n- Focus on finishing the task completely\n- After you emit the completion promise, run Oracle verification when instructed\n- Do not treat DONE as final completion until Oracle verifies it\n\n## Exit Conditions\n\n1. **Verified Completion**: Oracle verifies the result and the system confirms it\n2. **Cancel**: User runs `/cancel-ralph`\n\n## Your Task\n\nParse the arguments below and begin working on the task. The format is:\n`\"task description\" [--completion-promise=TEXT] [--strategy=reset|continue]`\n\nDefault completion promise is \"DONE\".";
+export declare const CANCEL_RALPH_TEMPLATE = "Cancel the currently active Ralph Loop.\n\nThis will:\n1. Stop the loop from continuing\n2. Clear the loop state file\n3. Allow the session to end normally\n\nCheck if a loop is active and cancel it. Inform the user of the result.";