opencode-matrixx 2.6.5 → 2.6.7

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,40 @@
+export interface SessionOutputClient {
+    session: {
+        messages: (args: {
+            path: {
+                id: string;
+            };
+        }) => Promise<unknown>;
+    };
+}
+interface SessionMessagePart {
+    type?: string;
+    text?: string;
+    content?: string | unknown[];
+}
+export interface SessionMessage {
+    info?: {
+        role?: string;
+        error?: unknown;
+    };
+    parts?: SessionMessagePart[];
+}
+/**
+ * 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`.
+ */
+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>;
+export {};

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

@@ -1,4 +1,22 @@
 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;
@@ -15,4 +33,6 @@ export declare class TaskHistory {
     getByParentSession(parentSessionID: string): TaskHistoryEntry[];
     clearSession(parentSessionID: string): void;
     formatForCompaction(parentSessionID: string): string | null;
+    getJobBoardEntries(parentSessionID: string): JobBoardRow[];
+    buildJobBoardSnapshot(parentSessionID: string, opts?: BuildJobBoardSnapshotOpts): JobBoardSnapshot | null;
 }

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

@@ -1,4 +1,6 @@
-export type BackgroundTaskStatus = "pending" | "running" | "completed" | "error" | "cancelled" | "interrupt";
+export type BackgroundTaskStatus = "pending" | "running" | "completed" | "error" | "cancelled" | "interrupt" | "stopped" | "statusUncertain";
+/** Why a background task reached a terminal state (persisted on the handle). */
+export type BackgroundTerminalReason = "queue-saturated" | "no-output" | "uncertain" | "aborted" | "stale" | "nested-depth-exceeded" | "wall-clock-timeout";
 export interface ToolCallWindow {
     lastSignature: string;
     consecutiveCount: number;
@@ -54,6 +56,10 @@ export interface BackgroundTask {
     lastMsgCount?: number;
     /** Number of consecutive polls with stable message count */
     stablePolls?: number;
+    /** Why the task reached a terminal state (e.g. stopped/statusUncertain) */
+    terminalReason?: BackgroundTerminalReason;
+    /** Compressed result payload for handoff to parent session (set by tryCompleteTask) */
+    compactedResult?: string;
 }
 export interface LaunchInput {
     description: string;
@@ -90,4 +96,18 @@ export interface ResumeInput {
     parentAgent?: string;
     parentTools?: Record<string, boolean>;
 }
+export interface ReviveInput {
+    taskId?: string;
+    sessionId?: string;
+    prompt: string;
+    parentSessionID: string;
+    parentMessageID: string;
+    parentModel?: {
+        providerID: string;
+        modelID: string;
+    };
+    parentAgent?: string;
+    parentTools?: Record<string, boolean>;
+    force?: boolean;
+}
 export {};

package/dist/features/background-agent/wake-scheduler.d.ts

@@ -0,0 +1,47 @@
+export interface WakeSchedulerConfig {
+    enabled?: boolean;
+    intervalMs?: number;
+}
+export interface WakeParentState {
+    hasPendingChildren: boolean;
+    hasUndeliveredNotifications: boolean;
+    hasUnfinishedTodos?: boolean;
+}
+export declare const WAKE_REMINDER_TEXT = "<system-reminder>\n[BACKGROUND WAKE]\n\nOne or more background tasks for this session are still running or have undelivered results.\nUse background_output with the task ID to retrieve results when ready.\nDo NOT poll - continue productive work.\n</system-reminder>";
+export declare function isWakeSchedulerEnabled(cfg?: WakeSchedulerConfig): boolean;
+export declare function resolveWakeIntervalMs(cfg?: WakeSchedulerConfig): number;
+export declare function shouldWakeForParent(state: WakeParentState): boolean;
+export declare function nextWakeDelay(lastWakeAtMs: number, intervalMs: number, nowMs?: number): number;
+export declare class WakeTracker {
+    private stagnantByParent;
+    recordWake(parentSessionID: string, progressed: boolean): boolean;
+    resetOnActivity(parentSessionID: string): void;
+    stagnantCount(parentSessionID: string): number;
+}
+export type WakeTimerHandle = ReturnType<typeof setTimeout>;
+export type WakeScheduleTimer = (callback: () => void, delayMs: number) => WakeTimerHandle;
+export type WakeClearTimer = (handle: WakeTimerHandle) => void;
+export interface WakeRegistration {
+    intervalMs: number;
+    readState: () => WakeParentState;
+    deliverWake: () => void | Promise<void>;
+}
+export declare class WakeScheduler {
+    private timers;
+    private registrations;
+    private snapshots;
+    private readonly tracker;
+    private readonly scheduleTimer;
+    private readonly clearTimer;
+    constructor(deps?: {
+        scheduleTimer?: WakeScheduleTimer;
+        clearTimer?: WakeClearTimer;
+    });
+    private armTimer;
+    schedule(parentSessionID: string, registration: WakeRegistration): void;
+    clear(parentSessionID: string): void;
+    dispose(): void;
+    hasScheduledWake(parentSessionID: string): boolean;
+    private clearTimerFor;
+    private tick;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Wall-clock supervisor: fire-once elapsed-time bound for running background tasks.
+ *
+ * Staleness is activity-based; this module is elapsed-time-based. Each armed entry
+ * fires its callback exactly once when `startedAtMs + timeoutMs` passes, no matter
+ * how busy or productive the task looks. A timeout of `0` or `undefined` means OFF
+ * and arms nothing.
+ *
+ * Grace contract (manager-owned, pinned here): on fire the manager aborts the
+ * session once, waits `wallClockAbortGraceMs`, then marks the task terminal —
+ * unless the task completed naturally during grace, in which case the natural
+ * outcome wins and the pending mark is cancelled.
+ *
+ * This module must not import from manager/client/fs — pure timers only. It mirrors
+ * the settled-flag lifecycle of `acquireWithDeadline` in `concurrency.ts`.
+ */
+/** Maximum delay accepted by `setTimeout` (2^31-1 ms); enforced by schema max too. */
+export declare const MAX_WALLCLOCK_TIMEOUT_MS = 2147483647;
+/** Context delivered to the fire callback exactly once per armed deadline. */
+export interface WallclockFireContext {
+    taskId: string;
+    elapsedMs: number;
+    limitMs: number;
+}
+export type WallclockFireCallback = (ctx: WallclockFireContext) => void;
+/** Pure remaining-time math: deadline minus now (negative when already expired). */
+export declare function remainingMs(startedAtMs: number, timeoutMs: number, nowMs?: number): number;
+/** OFF (`0`/`undefined`) never arms; any other value is an active elapsed-time bound. */
+export declare function isWallclockEnabled(timeoutMs: number | undefined): timeoutMs is number;
+export declare class WallclockSupervisor {
+    private entries;
+    arm(taskId: string, startedAtMs: number, timeoutMs: number | undefined, onFire: WallclockFireCallback): void;
+    disarm(taskId: string): boolean;
+    disarmAll(): void;
+    size(): number;
+    getDeadlineAt(taskId: string): number | undefined;
+}

package/dist/features/bdd/schema.d.ts

@@ -86,8 +86,8 @@ export declare const HttpMethodSchema: z.ZodEnum<{
 }>;
 export declare const ResponseFormatSchema: z.ZodEnum<{
     binary: "binary";
-    json: "json";
     text: "text";
+    json: "json";
     html: "html";
     xml: "xml";
 }>;
@@ -118,8 +118,8 @@ export declare const ApiResponseSchema: z.ZodObject<{
     status: z.ZodNumber;
     format: z.ZodEnum<{
         binary: "binary";
-        json: "json";
         text: "text";
+        json: "json";
         html: "html";
         xml: "xml";
     }>;
@@ -174,8 +174,8 @@ export declare const ApiAnnotationsSchema: z.ZodObject<{
         status: z.ZodNumber;
         format: z.ZodEnum<{
             binary: "binary";
-            json: "json";
             text: "text";
+            json: "json";
             html: "html";
             xml: "xml";
         }>;
@@ -236,8 +236,8 @@ export declare const ContractAnnotationsSchema: z.ZodObject<{
             status: z.ZodNumber;
             format: z.ZodEnum<{
                 binary: "binary";
-                json: "json";
                 text: "text";
+                json: "json";
                 html: "html";
                 xml: "xml";
             }>;
@@ -366,8 +366,8 @@ export declare const ContractSchema: z.ZodObject<{
                 status: z.ZodNumber;
                 format: z.ZodEnum<{
                     binary: "binary";
-                    json: "json";
                     text: "text";
+                    json: "json";
                     html: "html";
                     xml: "xml";
                 }>;

package/dist/hooks/background-task-blocker/hook.d.ts

@@ -0,0 +1,10 @@
+export declare function createBackgroundTaskBlockerHook(): {
+    "tool.execute.before": (input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }, _output: {
+        args: Record<string, unknown>;
+        message?: string;
+    }) => Promise<void>;
+};

package/dist/hooks/background-task-blocker/index.d.ts

@@ -0,0 +1 @@
+export { createBackgroundTaskBlockerHook } from "./hook";

package/dist/hooks/context-mode-enforcer/constants.d.ts

@@ -1,6 +1,6 @@
 export declare const HOOK_NAME = "context-mode-enforcer";
 export declare const WARN_MESSAGE_READ = "Use ctx_search / ctx_batch_execute / ctx_execute for analysis \u2014 raw read/grep/glob bypasses FTS5 sandbox and pollutes context. Use Read only with hashline IDs for Edit (non-plan paths; .matrixx/plans/*.md must use plan_read/plan_update).";
-export declare const BLOCK_MESSAGE_GREP_GLOB = "Blocked: raw grep/glob is forbidden when context-mode is enforced. Use ctx_search (indexed) \u2192 grep/glob fallback only when ctx_* unavailable, or ctx_batch_execute / ctx_execute for multi-file analysis.";
+export declare const BLOCK_MESSAGE_GREP_GLOB: string;
 export declare const WARN_MESSAGE_BASH_READ = "Use ctx_* / Read tool instead of `cat`/`head`/`tail`/`grep` via bash for analysis. Raw bash file reads bypass sandbox.";
 export declare const DEFAULT_BLOCKED_TOOLS: readonly ["grep", "glob"];
 export declare const WARN_ONLY_TOOLS: readonly ["read"];

package/dist/hooks/index.d.ts

@@ -3,6 +3,7 @@ export { createArchitectHook } from "./architect";
 export { createAutoSlashCommandHook } from "./auto-slash-command";
 export { createAutoUpdateCheckerHook } from "./auto-update-checker";
 export { createBackgroundNotificationHook } from "./background-notification";
+export { createBackgroundTaskBlockerHook } from "./background-task-blocker";
 export { createBashFileReadGuardHook } from "./bash-file-read-guard";
 export { createCategorySkillReminderHook } from "./category-skill-reminder";
 export { createCommentCheckerHooks } from "./comment-checker";