opencode-matrixx 0.0.1

package/dist/features/background-agent/notify-parent-session.d.ts

@@ -0,0 +1,10 @@
+import type { BackgroundTask } from "./types";
+import type { OpencodeClient } from "./opencode-client";
+export declare function notifyParentSession(args: {
+    task: BackgroundTask;
+    tasks: Map<string, BackgroundTask>;
+    pendingByParent: Map<string, Set<string>>;
+    completionTimers: Map<string, ReturnType<typeof setTimeout>>;
+    clearNotificationsForTask: (taskId: string) => void;
+    client: OpencodeClient;
+}): Promise<void>;

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/parent-session-context-resolver.d.ts

@@ -0,0 +1,14 @@
+import type { OpencodeClient } from "./constants";
+import type { BackgroundTask } from "./types";
+type AgentModel = {
+    providerID: string;
+    modelID: string;
+};
+export declare function resolveParentSessionAgentAndModel(input: {
+    client: OpencodeClient;
+    task: BackgroundTask;
+}): Promise<{
+    agent?: string;
+    model?: AgentModel;
+}>;
+export {};

package/dist/features/background-agent/parent-session-notifier.d.ts

@@ -0,0 +1,3 @@
+import type { BackgroundTask } from "./types";
+import type { ResultHandlerContext } from "./result-handler-context";
+export declare function notifyParentSession(task: BackgroundTask, ctx: ResultHandlerContext): Promise<void>;

package/dist/features/background-agent/poll-running-tasks.d.ts

@@ -0,0 +1,15 @@
+import type { BackgroundTask } from "./types";
+import type { OpencodeClient } from "./opencode-client";
+export declare function pollRunningTasks(args: {
+    tasks: Iterable<BackgroundTask>;
+    client: OpencodeClient;
+    pruneStaleTasksAndNotifications: () => void;
+    checkAndInterruptStaleTasks: (statuses: Record<string, {
+        type: string;
+    }>) => Promise<void>;
+    validateSessionHasOutput: (sessionID: string) => Promise<boolean>;
+    checkSessionTodos: (sessionID: string) => Promise<boolean>;
+    tryCompleteTask: (task: BackgroundTask, source: string) => Promise<boolean>;
+    hasRunningTasks: () => boolean;
+    stopPolling: () => void;
+}): Promise<void>;

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

@@ -0,0 +1,2 @@
+export type ProcessCleanupEvent = NodeJS.Signals | "beforeExit" | "exit";
+export declare function registerProcessSignal(signal: ProcessCleanupEvent, handler: () => void, exitAfter: boolean): () => void;

package/dist/features/background-agent/result-handler-context.d.ts

@@ -0,0 +1,8 @@
+import type { OpencodeClient } from "./constants";
+import type { ConcurrencyManager } from "./concurrency";
+import type { TaskStateManager } from "./state";
+export interface ResultHandlerContext {
+    client: OpencodeClient;
+    concurrencyManager: ConcurrencyManager;
+    state: TaskStateManager;
+}

package/dist/features/background-agent/result-handler.d.ts

@@ -0,0 +1,7 @@
+export type { ResultHandlerContext } from "./result-handler-context";
+export { formatDuration } from "./duration-formatter";
+export { getMessageDir } from "../../shared";
+export { checkSessionTodos } from "./session-todo-checker";
+export { validateSessionHasOutput } from "./session-output-validator";
+export { tryCompleteTask } from "./background-task-completer";
+export { notifyParentSession } from "./parent-session-notifier";

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-output-validator.d.ts

@@ -0,0 +1,2 @@
+import type { OpencodeClient } from "./constants";
+export declare function validateSessionHasOutput(client: OpencodeClient, sessionID: string): Promise<boolean>;

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

@@ -0,0 +1,10 @@
+import type { BackgroundTask } from "./types";
+export declare function cleanupTaskAfterSessionEnds(args: {
+    task: BackgroundTask;
+    tasks: Map<string, BackgroundTask>;
+    idleDeferralTimers: Map<string, ReturnType<typeof setTimeout>>;
+    completionTimers: Map<string, ReturnType<typeof setTimeout>>;
+    cleanupPendingByParent: (task: BackgroundTask) => void;
+    clearNotificationsForTask: (taskId: string) => void;
+    releaseConcurrencyKey?: (key: string) => void;
+}): void;

package/dist/features/background-agent/session-todo-checker.d.ts

@@ -0,0 +1,2 @@
+import type { OpencodeClient } from "./constants";
+export declare function checkSessionTodos(client: OpencodeClient, sessionID: string): Promise<boolean>;

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

@@ -0,0 +1,7 @@
+import type { OpencodeClient } from "./opencode-client";
+/**
+ * Validates that a session has actual assistant/tool output before marking complete.
+ * Prevents premature completion when session.idle fires before agent responds.
+ */
+export declare function validateSessionHasOutput(client: OpencodeClient, sessionID: string): Promise<boolean>;
+export declare function checkSessionTodos(client: OpencodeClient, sessionID: string): Promise<boolean>;

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

@@ -0,0 +1,10 @@
+import type { OpencodeClient } from "../constants";
+import type { ConcurrencyManager } from "../concurrency";
+import type { LaunchInput } from "../types";
+export declare function createBackgroundSession(options: {
+    client: OpencodeClient;
+    input: LaunchInput;
+    parentDirectory: string;
+    concurrencyManager: ConcurrencyManager;
+    concurrencyKey: string;
+}): Promise<string>;

package/dist/features/background-agent/spawner/concurrency-key-from-launch-input.d.ts

@@ -0,0 +1,2 @@
+import type { LaunchInput } from "../types";
+export declare function getConcurrencyKeyFromLaunchInput(input: LaunchInput): string;

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/spawner-context.d.ts

@@ -0,0 +1,11 @@
+import type { BackgroundTask } from "../types";
+import type { ConcurrencyManager } from "../concurrency";
+import type { OpencodeClient, OnSubagentSessionCreated } from "../constants";
+export interface SpawnerContext {
+    client: OpencodeClient;
+    directory: string;
+    concurrencyManager: ConcurrencyManager;
+    tmuxEnabled: boolean;
+    onSubagentSessionCreated?: OnSubagentSessionCreated;
+    onTaskError: (task: BackgroundTask, error: Error) => void;
+}

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

@@ -0,0 +1,2 @@
+import type { BackgroundTask, LaunchInput } from "../types";
+export declare function createTask(input: LaunchInput): BackgroundTask;

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

@@ -0,0 +1,3 @@
+import type { BackgroundTask, ResumeInput } from "../types";
+import type { SpawnerContext } from "./spawner-context";
+export declare function resumeTask(task: BackgroundTask, input: ResumeInput, ctx: Pick<SpawnerContext, "client" | "concurrencyManager" | "onTaskError">): Promise<void>;

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

@@ -0,0 +1,3 @@
+import type { QueueItem } from "../constants";
+import type { SpawnerContext } from "./spawner-context";
+export declare function startTask(item: QueueItem, ctx: SpawnerContext): Promise<void>;

package/dist/features/background-agent/spawner/tmux-callback-invoker.d.ts

@@ -0,0 +1,8 @@
+import type { OnSubagentSessionCreated } from "../constants";
+export declare function maybeInvokeTmuxCallback(options: {
+    onSubagentSessionCreated?: OnSubagentSessionCreated;
+    tmuxEnabled: boolean;
+    sessionID: string;
+    parentID: string;
+    title: string;
+}): Promise<void>;

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

@@ -0,0 +1,14 @@
+import type { BackgroundTask, LaunchInput, ResumeInput } from "./types";
+import type { OpencodeClient, OnSubagentSessionCreated, QueueItem } from "./constants";
+import type { ConcurrencyManager } from "./concurrency";
+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/stale-task-pruner.d.ts

@@ -0,0 +1,15 @@
+import type { BackgroundTask, LaunchInput } from "./types";
+import type { ConcurrencyManager } from "./concurrency";
+type QueueItem = {
+    task: BackgroundTask;
+    input: LaunchInput;
+};
+export declare function pruneStaleState(args: {
+    tasks: Map<string, BackgroundTask>;
+    notifications: Map<string, BackgroundTask[]>;
+    queuesByKey: Map<string, QueueItem[]>;
+    concurrencyManager: ConcurrencyManager;
+    cleanupPendingByParent: (task: BackgroundTask) => void;
+    clearNotificationsForTask: (taskId: string) => void;
+}): void;
+export {};

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/task-canceller.d.ts

@@ -0,0 +1,27 @@
+import type { BackgroundTask } from "./types";
+import type { LaunchInput } from "./types";
+import type { ConcurrencyManager } from "./concurrency";
+import type { OpencodeClient } from "./opencode-client";
+type QueueItem = {
+    task: BackgroundTask;
+    input: LaunchInput;
+};
+export declare function cancelBackgroundTask(args: {
+    taskId: string;
+    options?: {
+        source?: string;
+        reason?: string;
+        abortSession?: boolean;
+        skipNotification?: boolean;
+    };
+    tasks: Map<string, BackgroundTask>;
+    queuesByKey: Map<string, QueueItem[]>;
+    completionTimers: Map<string, ReturnType<typeof setTimeout>>;
+    idleDeferralTimers: Map<string, ReturnType<typeof setTimeout>>;
+    concurrencyManager: ConcurrencyManager;
+    client: OpencodeClient;
+    cleanupPendingByParent: (task: BackgroundTask) => void;
+    markForNotification: (task: BackgroundTask) => void;
+    notifyParentSession: (task: BackgroundTask) => Promise<void>;
+}): Promise<boolean>;
+export {};

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

@@ -0,0 +1,13 @@
+import type { BackgroundTask } from "./types";
+import type { ConcurrencyManager } from "./concurrency";
+import type { OpencodeClient } from "./opencode-client";
+export declare function tryCompleteBackgroundTask(args: {
+    task: BackgroundTask;
+    source: string;
+    concurrencyManager: ConcurrencyManager;
+    idleDeferralTimers: Map<string, ReturnType<typeof setTimeout>>;
+    client: OpencodeClient;
+    markForNotification: (task: BackgroundTask) => void;
+    cleanupPendingByParent: (task: BackgroundTask) => void;
+    notifyParentSession: (task: BackgroundTask) => Promise<void>;
+}): Promise<boolean>;

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

@@ -0,0 +1,18 @@
+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;
+    formatForCompaction(parentSessionID: string): string | null;
+}

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

@@ -0,0 +1,15 @@
+import type { BackgroundTask } from "./types";
+import type { LaunchInput } from "./types";
+type QueueItem = {
+    task: BackgroundTask;
+    input: LaunchInput;
+};
+export declare function launchBackgroundTask(args: {
+    input: LaunchInput;
+    tasks: Map<string, BackgroundTask>;
+    pendingByParent: Map<string, Set<string>>;
+    queuesByKey: Map<string, QueueItem[]>;
+    getConcurrencyKeyFromInput: (input: LaunchInput) => string;
+    processKey: (key: string) => void;
+}): BackgroundTask;
+export {};

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

@@ -0,0 +1,20 @@
+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;
+}): void;
+export type SessionStatusMap = Record<string, {
+    type: string;
+}>;
+export declare function checkAndInterruptStaleTasks(args: {
+    tasks: Iterable<BackgroundTask>;
+    client: OpencodeClient;
+    config: BackgroundTaskConfig | undefined;
+    concurrencyManager: ConcurrencyManager;
+    notifyParentSession: (task: BackgroundTask) => Promise<void>;
+    sessionStatuses?: SessionStatusMap;
+}): Promise<void>;

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

@@ -0,0 +1,7 @@
+import type { BackgroundTask } from "./types";
+export declare function getTasksByParentSession(tasks: Iterable<BackgroundTask>, sessionID: string): BackgroundTask[];
+export declare function getAllDescendantTasks(tasksByParent: (sessionID: string) => BackgroundTask[], sessionID: string): BackgroundTask[];
+export declare function findTaskBySession(tasks: Iterable<BackgroundTask>, sessionID: string): BackgroundTask | undefined;
+export declare function getRunningTasks(tasks: Iterable<BackgroundTask>): BackgroundTask[];
+export declare function getNonRunningTasks(tasks: Iterable<BackgroundTask>): BackgroundTask[];
+export declare function hasRunningTasks(tasks: Iterable<BackgroundTask>): boolean;

package/dist/features/background-agent/task-queue-processor.d.ts

@@ -0,0 +1,14 @@
+import type { BackgroundTask } from "./types";
+import type { ConcurrencyManager } from "./concurrency";
+type QueueItem = {
+    task: BackgroundTask;
+    input: import("./types").LaunchInput;
+};
+export declare function processConcurrencyKeyQueue(args: {
+    key: string;
+    queuesByKey: Map<string, QueueItem[]>;
+    processingKeys: Set<string>;
+    concurrencyManager: ConcurrencyManager;
+    startTask: (item: QueueItem) => Promise<void>;
+}): Promise<void>;
+export {};

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

@@ -0,0 +1,14 @@
+import type { BackgroundTask, ResumeInput } from "./types";
+import type { ConcurrencyManager } from "./concurrency";
+import type { OpencodeClient } from "./opencode-client";
+export declare function resumeBackgroundTask(args: {
+    input: ResumeInput;
+    findBySession: (sessionID: string) => BackgroundTask | undefined;
+    client: OpencodeClient;
+    concurrencyManager: ConcurrencyManager;
+    pendingByParent: Map<string, Set<string>>;
+    startPolling: () => void;
+    markForNotification: (task: BackgroundTask) => void;
+    cleanupPendingByParent: (task: BackgroundTask) => void;
+    notifyParentSession: (task: BackgroundTask) => Promise<void>;
+}): Promise<BackgroundTask>;

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

@@ -0,0 +1,27 @@
+import type { BackgroundTask } from "./types";
+import type { LaunchInput } from "./types";
+import type { ConcurrencyManager } from "./concurrency";
+import type { OpencodeClient } from "./opencode-client";
+type QueueItem = {
+    task: BackgroundTask;
+    input: LaunchInput;
+};
+export declare function startQueuedTask(args: {
+    item: QueueItem;
+    client: OpencodeClient;
+    defaultDirectory: string;
+    tmuxEnabled: boolean;
+    onSubagentSessionCreated?: (event: {
+        sessionID: string;
+        parentID: string;
+        title: string;
+    }) => Promise<void>;
+    startPolling: () => void;
+    getConcurrencyKeyFromInput: (input: LaunchInput) => string;
+    concurrencyManager: ConcurrencyManager;
+    findBySession: (sessionID: string) => BackgroundTask | undefined;
+    markForNotification: (task: BackgroundTask) => void;
+    cleanupPendingByParent: (task: BackgroundTask) => void;
+    notifyParentSession: (task: BackgroundTask) => Promise<void>;
+}): Promise<void>;
+export {};

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

@@ -0,0 +1,18 @@
+import type { BackgroundTask } from "./types";
+import type { ConcurrencyManager } from "./concurrency";
+export declare function trackExternalTask(args: {
+    input: {
+        taskId: string;
+        sessionID: string;
+        parentSessionID: string;
+        description: string;
+        agent?: string;
+        parentAgent?: string;
+        concurrencyKey?: string;
+    };
+    tasks: Map<string, BackgroundTask>;
+    pendingByParent: Map<string, Set<string>>;
+    concurrencyManager: ConcurrencyManager;
+    startPolling: () => void;
+    cleanupPendingByParent: (task: BackgroundTask) => void;
+}): Promise<BackgroundTask>;

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

@@ -0,0 +1,90 @@
+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;
+    lastUpdate: Date;
+    lastMessage?: string;
+    lastMessageAt?: Date;
+    countedToolPartIDs?: Set<string>;
+}
+export interface BackgroundTask {
+    id: string;
+    sessionID?: string;
+    parentSessionID: string;
+    parentMessageID: string;
+    description: string;
+    prompt: string;
+    agent: string;
+    status: BackgroundTaskStatus;
+    queuedAt?: Date;
+    startedAt?: Date;
+    completedAt?: Date;
+    result?: string;
+    error?: string;
+    progress?: TaskProgress;
+    parentModel?: {
+        providerID: string;
+        modelID: string;
+    };
+    model?: {
+        providerID: string;
+        modelID: string;
+        variant?: string;
+    };
+    /** 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', 'construct') */
+    category?: string;
+    /** Last message count for stability detection */
+    lastMsgCount?: number;
+    /** Number of consecutive polls with stable message count */
+    stablePolls?: 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?: {
+        providerID: string;
+        modelID: string;
+        variant?: string;
+    };
+    isUnstableAgent?: boolean;
+    skills?: string[];
+    skillContent?: string;
+    category?: string;
+}
+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/builtin-commands/commands.d.ts

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

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\" }) \u2014 full session history\n2. todoread() \u2014 current task progress\n3. Bash({ command: \"git diff --stat HEAD~10..HEAD\" }) \u2014 recent file changes\n4. Bash({ command: \"git status --porcelain\" }) \u2014 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. WRITE the summary to .matrix/handoff.md using the Write tool. Use 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\nWrite this content to .matrix/handoff.md using the Write tool. This file will be automatically loaded when a new session starts.\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 writing the file, inform the user:\n\n```\n---\n\nHANDOFF COMPLETE:\n\nContext saved to .matrix/handoff.md\n\nTo continue in a new session:\n1. Press 'n' in OpenCode TUI to open a new session, or run 'opencode' in a new terminal\n2. Your context will be loaded automatically \u2014 no copy-paste needed\n3. Start with your next task: \"Continue from where I left off. [Your next task]\"\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 in the .matrix/handoff.md file\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\u2014these run async while main session works.\n\n```\n// Fire all at once, collect results later\ntask(subagent_type=\"trinity\", 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=\"trinity\", load_skills=[], description=\"Find entry points\", run_in_background=true, prompt=\"Entry points: FIND main files \u2192 REPORT non-standard organization\")\ntask(subagent_type=\"trinity\", 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=\"trinity\", 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=\"trinity\", 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=\"trinity\", 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=\"trinity\", load_skills=[], description=\"Analyze large files\", run_in_background=true, prompt=\"Large file analysis: FIND files >500 lines, REPORT complexity hotspots\")\ntask(subagent_type=\"trinity\", load_skills=[], description=\"Explore deep modules\", run_in_background=true, prompt=\"Deep modules at depth 4+: FIND hidden patterns, internal conventions\")\ntask(subagent_type=\"trinity\", 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=\"broadcast\", 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/matrix-loop.d.ts

@@ -0,0 +1,2 @@
+export declare const MATRIX_LOOP_TEMPLATE = "You are starting a Matrix Loop - a self-referential development loop that runs until task completion.\n\n## How Matrix 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-loop` 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]`\n\nDefault completion promise is \"DONE\" and default max iterations is 100.";
+export declare const CANCEL_LOOP_TEMPLATE = "Cancel the currently active Matrix 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.";

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

@@ -0,0 +1 @@
+export declare const PICKUP_TEMPLATE = "# Pickup Command\n\n## Purpose\n\nUse /pickup to load handoff context from a previous session.\nThis reads the .matrix/handoff.md file created by /handoff and uses it as context for this session.\n\n---\n\n# PHASE 1: LOAD HANDOFF FILE\n\n1. Read the file .matrix/handoff.md using the Read tool\n2. If the file does not exist, inform the user:\n   \"No handoff context found. Run /handoff in a previous session first to create one.\"\n   Then STOP \u2014 do not proceed to Phase 2.\n\n---\n\n# PHASE 2: ARCHIVE THE FILE\n\nAfter successfully reading the handoff content:\n\n1. Rename .matrix/handoff.md to .matrix/handoff.consumed.md using Bash:\n   Bash({ command: \"mv .matrix/handoff.md .matrix/handoff.consumed.md\" })\n\nThis prevents the same handoff from being picked up again.\n\n---\n\n# PHASE 3: APPLY CONTEXT\n\n1. Acknowledge the loaded context to the user with a brief summary:\n   - What the previous session was working on (from GOAL section)\n   - What was completed (from WORK COMPLETED section)\n   - What remains (from PENDING TASKS section)\n\n2. State: \"Handoff context loaded. Ready to continue.\"\n\n3. If the user provided additional instructions with the /pickup command, begin working on those immediately using the handoff context.\n\n---\n\n# IMPORTANT CONSTRAINTS\n\n- DO read the handoff file using the Read tool \u2014 do not guess or fabricate context\n- DO archive the file after reading to prevent duplicate pickups\n- DO NOT modify the handoff content \u2014 use it as-is for context\n- DO NOT attempt to load handoff.consumed.md \u2014 that is a previously consumed handoff\n- DO summarize the context briefly \u2014 the user wants to know what was picked up\n- DO begin working immediately if the user provided a task alongside /pickup\n";