opencode-matrixx-v2 0.0.0-stage → 1.1.0

package/dist/config/schema.d.ts

@@ -0,0 +1,39 @@
+export { type AnyMcpName, AnyMcpNameSchema, type McpName, McpNameSchema } from "../mcps/types";
+export * from "./schema/agent-definitions";
+export * from "./schema/agent-names";
+export * from "./schema/agent-overrides";
+export * from "./schema/assembly";
+export * from "./schema/babysitting";
+export * from "./schema/background-task";
+export * from "./schema/browser-automation";
+export * from "./schema/categories";
+export * from "./schema/commands";
+export * from "./schema/comment-checker";
+export * from "./schema/context-mode";
+export * from "./schema/dcp";
+export * from "./schema/evolution";
+export * from "./schema/experimental";
+export * from "./schema/headroom";
+export * from "./schema/hooks";
+export * from "./schema/knowledge";
+export * from "./schema/matrix-loop";
+export * from "./schema/matrixx-config";
+export * from "./schema/matrixx-self-config";
+export * from "./schema/memory";
+export * from "./schema/model-config";
+export * from "./schema/model-presets";
+export * from "./schema/morpheus";
+export * from "./schema/morpheus-agent";
+export * from "./schema/notification";
+export * from "./schema/plans";
+export * from "./schema/rtk";
+export * from "./schema/runtime-fallback";
+export * from "./schema/security";
+export * from "./schema/skills";
+export * from "./schema/software-dev-enforcement";
+export * from "./schema/subagent-block";
+export * from "./schema/task";
+export * from "./schema/tasks";
+export * from "./schema/tdd-enforcer";
+export * from "./schema/tmux";
+export * from "./schema/tool-policy";

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

@@ -0,0 +1 @@
+export { _resetAssemblyStateForTesting, clearAssemblyState, disableAssembly, enableAssembly, isAssemblyDisabled, } from "./manager";

package/dist/features/assembly-state/manager.d.ts

@@ -0,0 +1,6 @@
+export declare function isAssemblyDisabled(sessionID: string): boolean;
+export declare function disableAssembly(sessionID: string): void;
+export declare function enableAssembly(sessionID: string): void;
+export declare function clearAssemblyState(sessionID: string): void;
+/** @internal */
+export declare function _resetAssemblyStateForTesting(): void;

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

@@ -0,0 +1,51 @@
+import type { BackgroundTask, LaunchInput } from "./types";
+export declare const TASK_TTL_MS: number;
+export declare const MIN_STABILITY_TIME_MS: number;
+export declare const DEFAULT_STALE_TIMEOUT_MS = 180000;
+export declare const DEFAULT_MESSAGE_STALENESS_TIMEOUT_MS = 600000;
+export declare const DEFAULT_MAX_TOOL_CALLS = 4000;
+export declare const DEFAULT_CIRCUIT_BREAKER_CONSECUTIVE_THRESHOLD = 20;
+export declare const DEFAULT_CIRCUIT_BREAKER_ENABLED = true;
+export declare const MIN_RUNTIME_BEFORE_STALE_MS = 30000;
+export declare const MIN_IDLE_TIME_MS = 5000;
+export declare const POLLING_INTERVAL_MS = 3000;
+export declare const PRUNE_THROTTLE_MS = 30000;
+export declare const TASK_CLEANUP_DELAY_MS: number;
+export declare const DEFAULT_WALL_CLOCK_TIMEOUT_MS = 0;
+export declare const DEFAULT_WALL_CLOCK_ABORT_GRACE_MS = 5000;
+export declare const DEFAULT_WAKE_SCHEDULER_ENABLED = false;
+export declare const DEFAULT_WAKE_INTERVAL_MS = 300000;
+export declare const MIN_WAKE_INTERVAL_MS = 60000;
+export declare const DEFAULT_JOB_BOARD_ENABLED = true;
+export declare const DEFAULT_JOB_BOARD_STRATEGY: "latest";
+export declare const DEFAULT_MAX_RETAINED_SNAPSHOTS = 10;
+export declare const RECONCILE_CONFIRMATION_GRACE_MS = 5000;
+export type ProcessCleanupEvent = NodeJS.Signals | "beforeExit" | "exit";
+export interface MessagePartInfo {
+    sessionID?: string;
+    type?: string;
+    tool?: string;
+}
+export interface EventProperties {
+    sessionID?: string;
+    info?: {
+        id?: string;
+    };
+    [key: string]: unknown;
+}
+export interface Todo {
+    content: string;
+    status: string;
+    priority: string;
+    id?: string;
+}
+export interface QueueItem {
+    task: BackgroundTask;
+    input: LaunchInput;
+}
+export interface SubagentSessionCreatedEvent {
+    sessionID: string;
+    parentID: string;
+    title: string;
+}
+export type OnSubagentSessionCreated = (event: SubagentSessionCreatedEvent) => Promise<void>;

package/dist/features/background-agent/error-helpers.d.ts

@@ -0,0 +1,4 @@
+import type { EventProperties } from "./manager";
+export declare function getErrorText(error: unknown): string;
+export declare function isAbortedSessionError(error: unknown): boolean;
+export declare function getSessionErrorMessage(properties: EventProperties): string | undefined;

package/dist/features/background-agent/handle-index.d.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import type { BackgroundTask } from "./types";
+/**
+ * File-backed handle index for background tasks.
+ *
+ * Mirrors the `task-storage` pattern: one file per handle under a
+ * project-scoped `.matrixx/bg-handles/` directory, written atomically via
+ * `tmp + renameSync`. Only a lightweight index is persisted — prompts,
+ * progress, results, errors and tool-call windows stay ephemeral.
+ *
+ * This lets a freshly-created `BackgroundManager` recover previously-created
+ * `bg_*` handles after a plugin/process restart.
+ */
+export declare const BG_HANDLE_DIR_NAME = "bg-handles";
+export declare const BG_HANDLE_FILE_PREFIX = "bg_";
+export declare const BgHandleSchema: z.ZodObject<{
+    taskId: z.ZodString;
+    parentSessionID: z.ZodString;
+    parentMessageID: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    agent: z.ZodString;
+    status: z.ZodEnum<{
+        error: "error";
+        cancelled: "cancelled";
+        interrupt: "interrupt";
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        stopped: "stopped";
+        statusUncertain: "statusUncertain";
+    }>;
+    sessionID: z.ZodOptional<z.ZodString>;
+    terminalReason: z.ZodOptional<z.ZodEnum<{
+        aborted: "aborted";
+        "queue-saturated": "queue-saturated";
+        "no-output": "no-output";
+        uncertain: "uncertain";
+        stale: "stale";
+        "nested-depth-exceeded": "nested-depth-exceeded";
+        "wall-clock-timeout": "wall-clock-timeout";
+        expired: "expired";
+    }>>;
+    model: z.ZodOptional<z.ZodObject<{
+        providerID: z.ZodString;
+        modelID: z.ZodString;
+        variant: z.ZodOptional<z.ZodString>;
+        temperature: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    category: z.ZodOptional<z.ZodString>;
+    concurrencyGroup: z.ZodOptional<z.ZodString>;
+    queuedAt: z.ZodOptional<z.ZodNumber>;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    completedAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type BgHandle = z.infer<typeof BgHandleSchema>;
+/** Project-scoped handle directory: `<project>/.matrixx/bg-handles`. */
+export declare function getBgHandleDir(directory: string): string;
+/** One file per handle id: `<project>/.matrixx/bg-handles/<taskId>.json`. */
+export declare function getHandlePath(directory: string, taskId: string): string;
+/** Single source of truth for the OpenCode subagent session title format. */
+export declare function buildSubagentTitle(description: unknown, agent: unknown, category?: unknown): string;
+/** Project a full task onto the lightweight, persistable handle index. */
+export declare function toHandle(task: BackgroundTask): BgHandle;
+/**
+ * Atomically persist a handle: write to a temp file then rename into place.
+ * Throws on write failure; callers decide how to surface it.
+ */
+export declare function writeHandle(directory: string, task: BackgroundTask): void;
+/** Read and validate every persisted handle. Invalid/corrupt files are skipped. */
+export declare function readHandles(directory: string): BgHandle[];
+/** Remove the handle file for a task id. Returns true when a file was deleted. */
+export declare function deleteHandleFile(directory: string, taskId: string): boolean;
+/**
+ * Bounded TTL sweep: delete handle files whose most recent timestamp is older
+ * than `ttlMs` (default 30 min). Corrupt/unreadable files are swept too so the
+ * directory cannot grow without bound. Returns the number of files removed.
+ */
+export declare function sweepStaleHandles(directory: string, ttlMs?: number, now?: number): number;

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

@@ -0,0 +1,5 @@
+export { BG_HANDLE_FILE_PREFIX, type BgHandle, BgHandleSchema, deleteHandleFile, getBgHandleDir, getHandlePath, readHandles, sweepStaleHandles, toHandle, writeHandle, } from "./handle-index";
+export { BackgroundManager, type OnSubagentSessionCreated, type SubagentSessionCreatedEvent } from "./manager";
+export { TaskStateManager } from "./state";
+export { TaskHistory, type TaskHistoryEntry } from "./task-history";
+export * from "./types";

package/dist/features/background-agent/loop-detector.d.ts

@@ -0,0 +1,16 @@
+import type { BackgroundTaskConfig } from "../../config/schema";
+import type { ToolCallWindow } from "./types";
+export interface CircuitBreakerSettings {
+    enabled: boolean;
+    maxToolCalls: number;
+    consecutiveThreshold: number;
+}
+interface ToolLoopDetectionResult {
+    triggered: boolean;
+    toolName?: string;
+    repeatedCount?: number;
+}
+export declare function resolveCircuitBreakerSettings(config?: BackgroundTaskConfig): CircuitBreakerSettings;
+export declare function recordToolCall(window: ToolCallWindow | undefined, toolName: string, settings: CircuitBreakerSettings, toolInput?: Record<string, unknown> | null): ToolCallWindow;
+export declare function detectRepetitiveToolUse(window: ToolCallWindow | undefined): ToolLoopDetectionResult;
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,199 @@
+/**
+ * Native v2 background-task shim (D5).
+ *
+ * Replaces the custom orchestration that lived here (~2455 LOC: polling
+ * loops, concurrency semaphores, queue admission, restart handling,
+ * wake-scheduler, wall-clock supervisor, tmux pane callbacks, parent
+ * notification pipeline) with a thin wrapper over the native session APIs:
+ *
+ * - native `session.create` + `session.prompt` for launches
+ * - Native `session.idle` / `session.error` events (via `handleEvent`) for
+ *   completion detection — no polling loops, no reconcile probes
+ * - native `session.interrupt` for cancellation
+ * - File-backed handles (`handle-index`) for restart visibility only —
+ *   persisted `running|pending` handles reload as `statusUncertain`,
+ *   revivable with `force: true`
+ *
+ * Deleted (D5): the reconciler, admission classifier, wake-scheduler and every
+ * tmux spawn wired through `setup-domains` `onSubagentSessionCreated`.
+ * Kept intentionally: `handle-index.ts` (restart visibility), `revive.ts`
+ * (pure eligibility logic), `task-history.ts` (compaction context),
+ * `types.ts` / `constants.ts` (shapes). The interactive-bash tool and the
+ * doctor `tmux-integration` check keep their own tmux binary usage.
+ */
+import type { BackgroundTaskConfig, MatrixxConfig } from "../../config/schema";
+import type { V2Event } from "../../plugin/context";
+import type { NativePluginContext } from "../../shared/session-context-source";
+import type { EventProperties, OnSubagentSessionCreated, SubagentSessionCreatedEvent } from "./constants";
+import { TaskHistory } from "./task-history";
+import type { BackgroundTask, LaunchInput, ResumeInput, ReviveInput } from "./types";
+export type { EventProperties, OnSubagentSessionCreated, SubagentSessionCreatedEvent, };
+/**
+ * Ephemeral native session descriptor (T1 unified-bg-native-tracking).
+ *
+ * Read-only view over the session-state registry — NOT a persisted bg_
+ * handle. Uses the lightweight `subagentSessions`/`subagentParentMap`
+ * registry (getSubagentSessionIDs + getParentSessionID) rather than the
+ * heavier storage.ts SDK read path (getMainSessions/getAllSessions),
+ * which requires directory-scoped sqlite/JSON access.
+ */
+export interface NativeDescendant {
+    sessionId: string;
+    parentSessionId: string;
+    isChild: boolean;
+}
+export declare class BackgroundManager {
+    private tasks;
+    private knownSessions;
+    private nativeDescCache;
+    private native;
+    private directory;
+    private config?;
+    readonly taskHistory: TaskHistory;
+    constructor(ctx: NativePluginContext, config?: BackgroundTaskConfig, options?: {
+        /** @deprecated Native session events own display; ignored. */
+        onSubagentSessionCreated?: OnSubagentSessionCreated;
+        onShutdown?: () => void;
+        /** Full plugin config — supplies the `tasks.*` store location. */
+        pluginConfig?: Partial<MatrixxConfig>;
+    });
+    /**
+     * Reload persisted handles for restart visibility. Persisted
+     * `running|pending` handles are NOT probed against the host (no reconcile
+     * loops); they reload as `statusUncertain` and stay revivable with force.
+     */
+    restoreHandles(): Promise<void>;
+    /**
+     * Launch a subagent via the native session APIs: `session.create` with the
+     * parent linkage, then a fire-and-forget `session.prompt`. No queues, no
+     * semaphores, no tmux callbacks — saturation surfaces as a thrown error
+     * from the host instead of a synthetic `queue-saturated` terminal state.
+     */
+    launch(input: LaunchInput & {
+        sessionId?: string;
+        sessionID?: string;
+        messageId?: string;
+        messageID?: string;
+    }): Promise<BackgroundTask>;
+    /**
+     * Track a task created elsewhere (e.g. via the native task tool) for
+     * notification/toast bookkeeping.
+     */
+    trackTask(input: {
+        taskId: string;
+        sessionID: string;
+        parentSessionID: string;
+        description: string;
+        agent?: string;
+        parentAgent?: string;
+        concurrencyKey?: string;
+    }): Promise<BackgroundTask>;
+    resume(input: ResumeInput): Promise<BackgroundTask>;
+    /** Revive a terminal task with a new prompt via native `session.prompt`. */
+    revive(input: ReviveInput): Promise<BackgroundTask>;
+    listRevivable(parentSessionID?: string): Array<{
+        taskId: string;
+        description: string;
+        agent: string;
+        status: string;
+        sessionID: string;
+        terminalReason?: string;
+    }>;
+    /**
+     * Native event routing (wired by the background-notification hook).
+     * Completion is detected from native session lifecycle events only —
+     * no polling, no reconcile probes.
+     */
+    /**
+     * Normalize a raw session ID: trim surrounding whitespace and strip
+     * query/hash suffixes so mismatched shapes still hit the same task.
+     */
+    private static normalizeSessionID;
+    handleEvent(event: V2Event): void;
+    getKnownSessionIds(): Set<string>;
+    getTask(id: string): BackgroundTask | undefined;
+    getTasksByParentSession(sessionID: string): BackgroundTask[];
+    getAllDescendantTasks(sessionID: string): BackgroundTask[];
+    /**
+     * Read-only native descendants of a session (T1).
+     *
+     * Walks the ephemeral session-state registry: a native ses_ session
+     * counts as a descendant when its ancestor chain (via getParentSessionID)
+     * includes `sessionId`. Returns ephemeral descriptors only — no handle
+     * writes, no persistence. Cycle-guarded with a visited set (the older
+     * getAllDescendantTasks lacks one). Returns [] for unknown sessions.
+     */
+    getNativeDescendants(sessionId: string): NativeDescendant[];
+    findBySession(sessionID: string): BackgroundTask | undefined;
+    findDiskTaskBySession(sessionID: string): BackgroundTask | undefined;
+    cancelTask(taskId: string, options?: {
+        source?: string;
+        reason?: string;
+        abortSession?: boolean;
+        skipNotification?: boolean;
+    }): Promise<boolean>;
+    cancelPendingTask(taskId: string): boolean;
+    cancelAllForSession(parentSessionID: string): number;
+    waitForAllDescendants(sessionID: string, timeoutMs?: number, pollIntervalMs?: number): Promise<{
+        completed: Array<{
+            id: string;
+            description: string;
+            agent: string;
+            status: string;
+        }>;
+        timedOut: Array<{
+            id: string;
+            description: string;
+            agent: string;
+            status: string;
+        }>;
+    }>;
+    shutdown(): void;
+    private taskTtlMs;
+    private persistHandle;
+    private abortSessionQuietly;
+    /** Fire-and-forget native prompt with the task's agent/model/tool scope. */
+    private firePrompt;
+}
+/**
+ * Resolve any task/session id to a unified payload (unified output/wait_all).
+ *
+ * - bg_ prefix: registry map lookup (origin bg). Covers bg tasks only.
+ * - ses_ prefix: findBySession first (covering bg task); else read-only live
+ *   lookup via the native client session.messages/session.get (no registry
+ *   write, no handle persist). Origin is ses when the session answers live,
+ *   foreign when only visible via bounded session.list backfill sweep.
+ * - task_id vs session_id ambiguity: a bg_ id that is also a session id is
+ *   treated as a bg_ task first (registry wins); tools surface ambiguity.
+ * - unknown: typed { error: not_found, id }.
+ */
+export type ResolveAnyResult = {
+    origin: "bg";
+    task: import("./types").BackgroundTask;
+} | {
+    origin: "ses" | "foreign";
+    sessionId: string;
+    output: unknown;
+    messages?: unknown;
+} | {
+    error: "not_found";
+    id: string;
+};
+export declare function resolveAny(manager: BackgroundManager, id: string): Promise<ResolveAnyResult>;
+/**
+ * Sessions covered by wait_all: pending/running bg_ tasks plus known live
+ * ses_* ids (knownSessions + bounded list backfill). Wired into
+ * waitForAllDescendants via uncoveredNatives; documented here so the
+ * coverage contract lives next to the query.
+ */
+export declare function listKnownSessions(manager: BackgroundManager): {
+    bgPending: string[];
+    liveSes: string[];
+};
+/**
+ * Test-only reset hook (D5 native migration): the pre-migration in-memory
+ * prune throttle was removed — stale-handle expiry is now the throttle-free TTL sweep in
+ * `handle-index.ts` (`sweepStaleHandles`, invoked per operation). Kept as a
+ * no-op so `tests/test-setup.ts` and older prune-throttle tests keep loading.
+ */
+export declare function _resetPruneThrottleForTesting(): void;

package/dist/features/background-agent/message-dir.d.ts

@@ -0,0 +1,5 @@
+import { type StoredMessage } from "../hook-message-injector";
+export declare function getMessageDir(sessionID: string): string | null;
+export declare function _resetMessageDirCacheForTesting(): void;
+export declare function isCompactionAgent(agent: string | undefined): boolean;
+export declare function findNearestMessageExcludingCompaction(messageDir: string): StoredMessage | null;

package/dist/features/background-agent/notification-builder.d.ts

@@ -0,0 +1,11 @@
+import type { SessionContextCarrier } from "../../shared/session-context-source";
+import type { BackgroundTask } from "./types";
+export declare function buildCompletionNotification(task: Pick<BackgroundTask, "id" | "description" | "error" | "status">, allComplete: boolean, completedTasks: Pick<BackgroundTask, "id" | "description">[], remainingCount: number, duration: string, errorInfo: string): string;
+export declare function resolveAgentAndModel(client: SessionContextCarrier, task: Pick<BackgroundTask, "parentSessionID" | "parentAgent">, enableParentSessionNotifications: boolean): Promise<{
+    agent: string | undefined;
+    model: {
+        providerID: string;
+        modelID: string;
+    } | undefined;
+}>;
+export declare function buildJobBoardNotification(snapshot: import("./task-history").JobBoardSnapshot): string;

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

@@ -0,0 +1,39 @@
+/**
+ * Revive eligibility classification for background tasks.
+ *
+ * Pure logic: decides whether a persisted handle may be revived into a new
+ * session. No I/O, no manager access, no client imports.
+ */
+import type { BgHandle } from "./handle-index";
+import type { BackgroundTask } from "./types";
+export declare const REVIVABLE_STATUSES: readonly ["cancelled", "stopped", "interrupt", "error", "completed"];
+export declare function isRevivableStatus(status: string): boolean;
+export type ReviveBlockReason = "active" | "uncertain" | "no-session" | "unknown-task" | "expired";
+export type ReviveEligibility = {
+    eligible: true;
+} | {
+    eligible: false;
+    reason: ReviveBlockReason;
+};
+export declare function classifyRevivable(handle: {
+    status: string;
+    sessionID?: string;
+    terminalReason?: string;
+}, opts?: {
+    force?: boolean;
+}): ReviveEligibility;
+/**
+ * Locate a revivable handle by task id or session id. `taskId` wins when
+ * both are supplied. Returns `undefined` when neither matches.
+ */
+export declare function findRevivableHandle(handles: BgHandle[], opts: {
+    taskId?: string;
+    sessionId?: string;
+}): BgHandle | undefined;
+/**
+ * Rehydrate a pre-admission `BackgroundTask` from a persisted handle with a
+ * NEW prompt. Mirrors `restoreTaskFromHandle` except `prompt` comes from the
+ * caller and `status` restarts at `"pending"`; `startedAt` is left unset (it
+ * is assigned on admission) and `completedAt`/`error` are cleared.
+ */
+export declare function toReviveTask(handle: BgHandle, prompt: string): BackgroundTask;

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

@@ -0,0 +1,26 @@
+import type { SessionContextCarrier } from "../../shared/session-context-source";
+import type { SessionMessage } from "../../shared/session-message";
+export type SessionOutputClient = SessionContextCarrier;
+export type { SessionMessage };
+/**
+ * Fetch the raw messages for a session. Throws on transport failure so callers
+ * can decide between fail-open (legacy) and fail-safe (reconciliation).
+ */
+export declare function fetchSessionMessages(client: SessionOutputClient, sessionID: string): Promise<SessionMessage[]>;
+/**
+ * True when the session produced real assistant/tool output with content.
+ * Shared by `validateSessionHasOutput` (manager) and `reconcileHandle`.
+ * Analysis-only content (<analysis> blocks) does NOT count as output —
+ * prevents premature completion when a subagent has only emitted its
+ * planning preamble.
+ */
+export declare function stripAnalysisBlocks(text: string): string;
+export declare function messagesHaveAssistantOutput(messages: SessionMessage[], sessionID?: string): boolean;
+/** True when any assistant message carries a recorded provider/abort error. */
+export declare function messagesHaveRecordedError(messages: SessionMessage[]): boolean;
+/**
+ * Validate that a session has actual assistant/tool output before marking
+ * complete. Fail-open: transport errors return true so a flaky lookup cannot
+ * block the existing polling/idle completion path.
+ */
+export declare function validateSessionHasOutput(client: SessionOutputClient, sessionID: string): Promise<boolean>;

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

@@ -0,0 +1,35 @@
+import type { QueueItem } from "./constants";
+import type { BackgroundTask, LaunchInput } from "./types";
+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-history.d.ts

@@ -0,0 +1,38 @@
+import type { BackgroundTaskStatus } from "./types";
+export type JobBoardStrategy = "latest" | "checkpoint-compatible";
+export interface JobBoardRow {
+    agent: string;
+    category?: string;
+    status: BackgroundTaskStatus;
+    description: string;
+    session?: string;
+}
+export interface JobBoardSnapshot {
+    strategy: JobBoardStrategy;
+    block: string;
+    retained?: string[];
+}
+export interface BuildJobBoardSnapshotOpts {
+    strategy?: JobBoardStrategy;
+    maxRetained?: number;
+    previous?: string[];
+}
+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;
+    getJobBoardEntries(parentSessionID: string): JobBoardRow[];
+    buildJobBoardSnapshot(parentSessionID: string, opts?: BuildJobBoardSnapshotOpts): JobBoardSnapshot | null;
+}