opencode-matrixx-v2 0.0.0-stage → 1.0.0

package/dist/tools/delegate-task/sync-session-poller.d.ts

@@ -0,0 +1,18 @@
+import type { SessionMessage } from "../../shared/session-message";
+import type { NativeClient, ToolContextWithMetadata } from "./types";
+export declare function isSessionComplete(messages: SessionMessage[]): boolean;
+export declare function hasToolResultAfterAssistant(messages: SessionMessage[]): boolean;
+export declare function hasAssistantContent(messages: SessionMessage[]): boolean;
+export declare function pollSyncSession(ctx: ToolContextWithMetadata, client: NativeClient, input: {
+    sessionID: string;
+    agentToUse: string;
+    toastManager: {
+        removeTask: (id: string) => void;
+    } | null | undefined;
+    taskId: string | undefined;
+    anchorMessageCount?: number;
+    /** Callback: does the parent session still have running background children? */
+    hasActiveChildBackgroundTasks?: () => boolean;
+    /** Callback: is there a pending parent-wake notification in flight? */
+    hasPendingParentWake?: () => boolean;
+}): Promise<string | null>;

package/dist/tools/delegate-task/sync-task-deps.d.ts

@@ -0,0 +1,11 @@
+import { sendSyncPrompt } from "./sync-prompt-sender";
+import { fetchSyncResult } from "./sync-result-fetcher";
+import { createSyncSession } from "./sync-session-creator";
+import { pollSyncSession } from "./sync-session-poller";
+export declare const syncTaskDeps: {
+    createSyncSession: typeof createSyncSession;
+    sendSyncPrompt: typeof sendSyncPrompt;
+    pollSyncSession: typeof pollSyncSession;
+    fetchSyncResult: typeof fetchSyncResult;
+};
+export type SyncTaskDeps = typeof syncTaskDeps;

package/dist/tools/delegate-task/sync-task.d.ts

@@ -0,0 +1,10 @@
+import type { ModelFallbackInfo } from "../../features/task-toast-manager/types";
+import type { ExecutorContext, ParentContext } from "./executor-types";
+import { type SyncTaskDeps } from "./sync-task-deps";
+import type { DelegateTaskArgs, ToolContextWithMetadata } from "./types";
+export declare function executeSyncTask(args: DelegateTaskArgs, ctx: ToolContextWithMetadata, executorCtx: ExecutorContext, parentContext: ParentContext, agentToUse: string, categoryModel: {
+    providerID: string;
+    modelID: string;
+    variant?: string;
+    temperature?: number;
+} | undefined, systemContent: string | undefined, modelInfo?: ModelFallbackInfo, deps?: SyncTaskDeps): Promise<string>;

package/dist/tools/delegate-task/task-title.d.ts

@@ -0,0 +1,11 @@
+export declare const FALLBACK_TASK_DESCRIPTION = "Background task";
+export declare function resolveTaskDescription(input: {
+    description?: unknown;
+    prompt?: unknown;
+    category?: unknown;
+    subagent_type?: unknown;
+    agent?: unknown;
+}): string;
+export declare function buildTaskTitle(description: unknown, agent: unknown, category?: unknown): string;
+export declare function buildBackgroundTitle(description: unknown, agent: unknown, category?: unknown): string;
+export declare function buildContinuationTitle(description: unknown): string;

package/dist/tools/delegate-task/timing.d.ts

@@ -0,0 +1,16 @@
+export declare function getTimingConfig(): {
+    POLL_INTERVAL_MS: number;
+    MIN_STABILITY_TIME_MS: number;
+    STABILITY_POLLS_REQUIRED: number;
+    WAIT_FOR_SESSION_INTERVAL_MS: number;
+    WAIT_FOR_SESSION_TIMEOUT_MS: number;
+    MAX_POLL_TIME_MS: number;
+    SESSION_CONTINUATION_STABILITY_MS: number;
+};
+export declare function __resetTimingConfig(): void;
+/**
+ * Set poll timeout from plugin config. Called during plugin initialization.
+ * Accepts a value in milliseconds; falls back to 10 min default.
+ */
+export declare function setPollTimeoutMs(ms: number): void;
+export declare function __setTimingConfig(overrides: Partial<ReturnType<typeof getTimingConfig>>): void;

package/dist/tools/delegate-task/tool-options.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Registration options for the delegate-task tool.
+ *
+ * `task` spawns a nested agent, so the host cannot run it from inside a
+ * code-mode `execute` block: the nested spawn has no top-level tool session
+ * context and the call returns an empty string. Marking the tool as
+ * direct-only keeps it out of the code-mode catalog and exposes it as a
+ * direct tool, which is the only context where the spawn works.
+ */
+export declare const TASK_TOOL_OPTIONS: {
+    readonly codemode: false;
+};

package/dist/tools/delegate-task/tools.d.ts

@@ -0,0 +1,16 @@
+import { type SoftwareDevEnforcementConfigInput } from "../../config/schema";
+import { type MatrixxToolDefinition } from "../shared/define-tool";
+import type { DelegateTaskToolOptions } from "./types";
+export { resolveCategoryConfig } from "./categories";
+export { buildSystemContent } from "./prompt-builder";
+export type { BuildSystemContentInput, DelegateTaskToolOptions, SyncSessionCreatedEvent } from "./types";
+/**
+ * Fail-closed TDD enforcement for code-writing delegations (issue #127).
+ * Returns a hard error string when the delegation must be rejected, else null.
+ * Complexity: 1 — single exception path (source without the skill).
+ */
+export declare function requireTddEnforcerForCodeWriting(category: string | undefined, loadSkills: string[], options?: {
+    enforcement?: SoftwareDevEnforcementConfigInput | null;
+    disabledSkills?: Set<string> | string[];
+}): string | null;
+export declare function createDelegateTask(options: DelegateTaskToolOptions): MatrixxToolDefinition;

package/dist/tools/delegate-task/types.d.ts

@@ -0,0 +1,90 @@
+import type { AvailableCategory, AvailableSkill } from "../../agents/dynamic-agent-prompt-builder";
+import type { AgentOverrides, BrowserAutomationProvider, CategoriesConfig, ComplexityDowngrades, ModelPresets, ModelRequirements, SoftwareDevEnforcementConfigInput } from "../../config/schema";
+import type { BackgroundManager } from "../../features/background-agent";
+import type { NativeDomains } from "../../shared/session-context-source";
+export type NativeClient = NativeDomains;
+export interface DelegateTaskArgs {
+    description: string;
+    prompt: string;
+    category?: string;
+    subagent_type?: string;
+    run_in_background: boolean;
+    session_id?: string;
+    command?: string;
+    load_skills: string[];
+    execute?: {
+        task_id: string;
+        task_dir?: string;
+    };
+    /**
+     * Task complexity level (1-5) or "auto" for automatic scoring.
+     * When < 3, model may be downgraded to a cheaper tier.
+     * Default: "auto" (scored from prompt/description heuristics)
+     */
+    complexity?: import("./complexity-types").ComplexityLevel | "auto";
+}
+export interface ToolContextWithMetadata {
+    sessionID: string;
+    messageID: string;
+    agent: string;
+    abort: AbortSignal;
+    metadata?: (input: {
+        title?: string;
+        metadata?: Record<string, unknown>;
+    }) => void | Promise<void>;
+    /**
+     * Tool call ID injected by OpenCode's internal context (not in plugin MatrixxToolContext type,
+     * but present at runtime via spread in fromPlugin()). Used for metadata store keying.
+     */
+    callID?: string;
+    /** @deprecated OpenCode internal naming may vary across versions */
+    callId?: string;
+    /** @deprecated OpenCode internal naming may vary across versions */
+    call_id?: string;
+}
+export interface SyncSessionCreatedEvent {
+    sessionID: string;
+    parentID: string;
+    title: string;
+}
+export interface DelegateTaskToolOptions {
+    manager: BackgroundManager;
+    client: NativeClient;
+    directory: string;
+    /**
+     * Test hook: bypass global cache reads (Bun runs tests in parallel).
+     * If provided, resolveCategoryExecution/resolveSubagentExecution uses this instead of reading from disk cache.
+     */
+    connectedProvidersOverride?: string[] | null;
+    /**
+     * Test hook: bypass fetchAvailableModels() by providing an explicit available model set.
+     */
+    availableModelsOverride?: Set<string>;
+    userCategories?: CategoriesConfig;
+    /** Global provider/model override for ALL tasks (overrides all category models) */
+    globalModel?: string;
+    mouseModel?: string;
+    browserProvider?: BrowserAutomationProvider;
+    disabledSkills?: Set<string>;
+    softwareDevEnforcement?: SoftwareDevEnforcementConfigInput;
+    availableCategories?: AvailableCategory[];
+    availableSkills?: AvailableSkill[];
+    agentOverrides?: AgentOverrides;
+    modelRequirements?: ModelRequirements;
+    complexityDowngrades?: ComplexityDowngrades;
+    /** Named model presets from plugin config (`model_presets`). */
+    modelPresets?: ModelPresets;
+    /** Active preset name from plugin config (`active_preset`). */
+    activePreset?: string;
+    onSyncSessionCreated?: (event: SyncSessionCreatedEvent) => Promise<void>;
+    /** Resolves the live system default model (provider/model); absence falls back to category resolution. */
+    systemDefaultModel?: () => Promise<string | undefined>;
+}
+export interface BuildSystemContentInput {
+    skillContent?: string;
+    categoryPromptAppend?: string;
+    agentName?: string;
+    category?: string;
+    availableCategories?: AvailableCategory[];
+    availableSkills?: AvailableSkill[];
+}

package/dist/tools/delegate-task/unstable-agent-task.d.ts

@@ -0,0 +1,8 @@
+import type { ExecutorContext, ParentContext } from "./executor-types";
+import type { DelegateTaskArgs, ToolContextWithMetadata } from "./types";
+export declare function executeUnstableAgentTask(args: DelegateTaskArgs, ctx: ToolContextWithMetadata, executorCtx: ExecutorContext, parentContext: ParentContext, agentToUse: string, categoryModel: {
+    providerID: string;
+    modelID: string;
+    variant?: string;
+    temperature?: number;
+} | undefined, systemContent: string | undefined, actualModel: string | undefined): Promise<string>;

package/dist/tools/evolution/constants.d.ts

@@ -0,0 +1,24 @@
+/**
+ * evolution tool — description string and shared constants.
+ *
+ * The tool description is referenced by the tool factory and included in the
+ * LLM-facing tool schema, so keep it factual, concise, and triggerable.
+ */
+/** Tool description — governance plus read-only retrieval actions. */
+export declare const EVOLUTION_DESCRIPTION = "Govern self-evolution proposals staged in .matrixx/evolution/pending, and retrieve approved knowledge. Actions: 'list' (show pending proposals with version and confidence), 'get' (show a staged proposal), 'approve' (promote a pending skill and record the audit entry), 'reject' (discard a pending proposal), 'status' (state totals, pending count, and audit tail), 'search' (read-only scoped search over approved knowledge), 'get_context' (read-only scoped context, truncated at a char cap). Use this tool instead of shell commands for all evolution state.";
+/** Allowlisted actions: Wave1 governance plus read-only retrieval queries. */
+export declare const EVOLUTION_TOOL_ACTIONS: readonly ["list", "get", "approve", "reject", "status", "search", "get_context"];
+/** The read-only retrieval surface — no action here may mutate evolution state. */
+export declare const EVOLUTION_QUERY_ACTIONS: readonly ["search", "get_context"];
+/** How many audit lines `status` reports. */
+export declare const AUDIT_TAIL_LIMIT = 20;
+/** Hard char cap for `get_context` output; cut text gets a truncation marker. */
+export declare const GET_CONTEXT_CHAR_CAP = 4000;
+/** Max records `search` reports. */
+export declare const SEARCH_RESULT_LIMIT = 20;
+/** Message when the scoped query finds nothing. */
+export declare const NO_RETRIEVABLE_MESSAGE = "No retrievable knowledge for this scope.";
+/** Slugs must stay inside the pending dir — no separators, no traversal. */
+export declare const SLUG_PATTERN: RegExp;
+/** Message when nothing is staged. */
+export declare const NO_PENDING_MESSAGE = "No pending evolution proposals.";

package/dist/tools/evolution/index.d.ts

@@ -0,0 +1,3 @@
+export { AUDIT_TAIL_LIMIT, EVOLUTION_DESCRIPTION, EVOLUTION_QUERY_ACTIONS, EVOLUTION_TOOL_ACTIONS, GET_CONTEXT_CHAR_CAP, NO_PENDING_MESSAGE, NO_RETRIEVABLE_MESSAGE, SEARCH_RESULT_LIMIT, SLUG_PATTERN, } from "./constants";
+export { createEvolutionTool, type EvolutionToolOptions } from "./tools";
+export type { EvolutionToolAction, EvolutionToolArgs, PendingProposalSummary } from "./types";

package/dist/tools/evolution/query-actions.d.ts

@@ -0,0 +1,3 @@
+import type { EvolutionToolArgs } from "./types";
+export declare function handleSearch(projectRoot: string, args: EvolutionToolArgs): string;
+export declare function handleGetContext(projectRoot: string, args: EvolutionToolArgs): string;

package/dist/tools/evolution/tools.d.ts

@@ -0,0 +1,16 @@
+import { type EvolutionWriterConfig } from "../../config/schema/evolution";
+import type { MatrixxContext } from "../../plugin/context";
+import { type MatrixxToolDefinition } from "../shared/define-tool";
+export type EvolutionToolOptions = {
+    writerConfig?: EvolutionWriterConfig;
+};
+/**
+ * `evolution` tool factory — governance + query host for self-evolution.
+ *
+ * Wave1 exposes the governance actions `list/get/approve/reject/status`,
+ * all delegated to the evolution store APIs (`EvolutionWriter`, `TraceStore`)
+ * so no shell command ever touches evolution state. T9 adds the read-only
+ * retrieval actions `search` and `get_context`, filtered through the T4a
+ * retrieval contract and scoped to the current project.
+ */
+export declare function createEvolutionTool(ctx: MatrixxContext, options?: EvolutionToolOptions): Record<string, MatrixxToolDefinition>;

package/dist/tools/evolution/types.d.ts

@@ -0,0 +1,20 @@
+import type { KnowledgeKind } from "../../features/evolution/types";
+import type { EVOLUTION_TOOL_ACTIONS } from "./constants";
+/** Allowlisted actions for the `evolution` tool. */
+export type EvolutionToolAction = (typeof EVOLUTION_TOOL_ACTIONS)[number];
+/** Flat args shape for the multi-action `evolution` tool. */
+export type EvolutionToolArgs = {
+    action: EvolutionToolAction;
+    slug?: string;
+    global?: boolean;
+    /** (action=search/get_context) Case-insensitive text match; absent returns all in scope. */
+    query?: string;
+    /** (action=search/get_context) Restrict results to one knowledge kind. */
+    kind?: KnowledgeKind;
+};
+/** Pending proposal summary shown by the `list` action. */
+export type PendingProposalSummary = {
+    slug: string;
+    version: string | null;
+    confidence: number | null;
+};

package/dist/tools/github-search/cli.d.ts

@@ -0,0 +1,7 @@
+import type { GithubSearchResult } from "./types";
+export declare function githubSearch(opts: {
+    query: string;
+    repo?: string;
+    language?: string;
+    limit?: number;
+}): Promise<GithubSearchResult>;

package/dist/tools/github-search/constants.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULT_TIMEOUT_MS = 60000;
+export declare const DEFAULT_MAX_OUTPUT_CHARS = 20000;
+export declare const DEFAULT_LIMIT = 10;
+export declare const MAX_LIMIT = 30;
+export declare const CLONE_DEPTH = 1;
+export declare const TMP_PREFIX = "matrixx-gh-";

package/dist/tools/github-search/result-formatter.d.ts

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

package/dist/tools/github-search/tools.d.ts

@@ -0,0 +1,3 @@
+import type { MatrixxContext } from "../../plugin/context";
+import { type MatrixxToolDefinition } from "../shared/define-tool";
+export declare function createGithubSearchTools(_ctx: MatrixxContext): Record<string, MatrixxToolDefinition>;

package/dist/tools/github-search/types.d.ts

@@ -0,0 +1,20 @@
+export interface GithubSearchHit {
+    repo: string;
+    path: string;
+    sha?: string;
+    line?: number;
+    text?: string;
+    url?: string;
+}
+export interface GithubSearchResult {
+    hits: GithubSearchHit[];
+    truncated: boolean;
+    mode: "code-search" | "clone-search";
+    error?: string;
+}
+export interface GithubSearchOptions {
+    query: string;
+    repo?: string;
+    language?: string;
+    limit?: number;
+}

package/dist/tools/glob/cli.d.ts

@@ -0,0 +1,11 @@
+import { type GrepBackend } from "./constants";
+import type { GlobOptions, GlobResult } from "./types";
+export interface ResolvedCli {
+    path: string;
+    backend: GrepBackend;
+}
+declare function buildRgArgs(options: GlobOptions): string[];
+declare function buildFindArgs(options: GlobOptions): string[];
+declare function buildPowerShellCommand(options: GlobOptions): string[];
+export { buildFindArgs, buildPowerShellCommand, buildRgArgs };
+export declare function runRgFiles(options: GlobOptions, resolvedCli?: ResolvedCli): Promise<GlobResult>;

package/dist/tools/glob/constants.d.ts

@@ -0,0 +1,6 @@
+export { type GrepBackend, resolveGrepCli, resolveGrepCliWithAutoInstall } from "../grep/constants";
+export declare const DEFAULT_TIMEOUT_MS = 60000;
+export declare const DEFAULT_LIMIT = 100;
+export declare const DEFAULT_MAX_DEPTH = 20;
+export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
+export declare const RG_FILES_FLAGS: readonly ["--files", "--color=never", "--glob=!.git/*"];

package/dist/tools/glob/result-formatter.d.ts

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

package/dist/tools/glob/tools.d.ts

@@ -0,0 +1,3 @@
+import type { MatrixxContext } from "../../plugin/context";
+import { type MatrixxToolDefinition } from "../shared/define-tool";
+export declare function createGlobTools(ctx: MatrixxContext): Record<string, MatrixxToolDefinition>;

package/dist/tools/glob/types.d.ts

@@ -0,0 +1,20 @@
+export interface FileMatch {
+    path: string;
+    mtime: number;
+}
+export interface GlobResult {
+    files: FileMatch[];
+    totalFiles: number;
+    truncated: boolean;
+    error?: string;
+}
+export interface GlobOptions {
+    pattern: string;
+    paths?: string[];
+    hidden?: boolean;
+    follow?: boolean;
+    noIgnore?: boolean;
+    maxDepth?: number;
+    timeout?: number;
+    limit?: number;
+}

package/dist/tools/grep/cli.d.ts

@@ -0,0 +1,2 @@
+import type { GrepOptions, GrepResult } from "./types";
+export declare function runRg(options: GrepOptions): Promise<GrepResult>;

package/dist/tools/grep/constants.d.ts

@@ -0,0 +1,16 @@
+export type GrepBackend = "rg" | "grep";
+interface ResolvedCli {
+    path: string;
+    backend: GrepBackend;
+}
+export declare function resolveGrepCli(): ResolvedCli;
+export declare function resolveGrepCliWithAutoInstall(): Promise<ResolvedCli>;
+export declare const DEFAULT_MAX_DEPTH = 20;
+export declare const DEFAULT_MAX_FILESIZE = "10M";
+export declare const DEFAULT_MAX_COUNT = 500;
+export declare const DEFAULT_MAX_COLUMNS = 1000;
+export declare const DEFAULT_TIMEOUT_MS = 300000;
+export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
+export declare const RG_SAFETY_FLAGS: readonly ["--no-follow", "--color=never", "--no-heading", "--line-number", "--with-filename"];
+export declare const GREP_SAFETY_FLAGS: readonly ["-n", "-H", "--color=never"];
+export {};

package/dist/tools/grep/downloader.d.ts

@@ -0,0 +1,3 @@
+export declare function findFileRecursive(dir: string, filename: string): string | null;
+export declare function downloadAndInstallRipgrep(): Promise<string>;
+export declare function getInstalledRipgrepPath(): string | null;

package/dist/tools/grep/result-formatter.d.ts

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

package/dist/tools/grep/tools.d.ts

@@ -0,0 +1,3 @@
+import type { MatrixxContext } from "../../plugin/context";
+import { type MatrixxToolDefinition } from "../shared/define-tool";
+export declare function createGrepTools(ctx: MatrixxContext): Record<string, MatrixxToolDefinition>;

package/dist/tools/grep/types.d.ts

@@ -0,0 +1,32 @@
+export interface GrepMatch {
+    file: string;
+    line: number;
+    column?: number;
+    text: string;
+}
+export interface GrepResult {
+    matches: GrepMatch[];
+    totalMatches: number;
+    filesSearched: number;
+    truncated: boolean;
+    error?: string;
+}
+export interface GrepOptions {
+    pattern: string;
+    paths?: string[];
+    globs?: string[];
+    excludeGlobs?: string[];
+    context?: number;
+    maxDepth?: number;
+    maxFilesize?: string;
+    maxCount?: number;
+    maxColumns?: number;
+    caseSensitive?: boolean;
+    wholeWord?: boolean;
+    fixedStrings?: boolean;
+    multiline?: boolean;
+    hidden?: boolean;
+    noIgnore?: boolean;
+    fileType?: string[];
+    timeout?: number;
+}

package/dist/tools/handoff/archive-handler.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `handoff` tool — `action: "archive"` handler.
+ *
+ * Renames the active `.matrixx/handoff.md` to `.matrixx/handoff.consumed.md`.
+ * Returns a clear `Error:` string if there is no active handoff to archive
+ * (idempotent semantics: archiving nothing is an error so the caller knows
+ * nothing happened, not a silent no-op).
+ */
+export declare function handleArchive(directory: string): string;

package/dist/tools/handoff/body-formatter.d.ts

@@ -0,0 +1,9 @@
+import type { HandoffSection } from "../../features/handoff";
+/**
+ * Build the human-readable markdown body that follows the YAML frontmatter.
+ *
+ * Mirrors the format from `src/features/builtin-commands/templates/handoff.ts`
+ * (the canonical /handoff command template). Sections are emitted only when
+ * they have content, so a minimal handoff stays minimal.
+ */
+export declare function buildHandoffBody(sections: HandoffSection): string;

package/dist/tools/handoff/constants.d.ts

@@ -0,0 +1,14 @@
+/**
+ * handoff tool — description string and shared constants.
+ *
+ * The tool description is referenced by the tool factory and included in the
+ * LLM-facing tool schema, so keep it factual, concise, and triggerable.
+ */
+/** Tool description — covers all four supported actions. */
+export declare const HANDOFF_DESCRIPTION = "Multi-action handoff tool backed by .matrixx/handoff.md. Actions: 'create' (write a structured handoff with YAML frontmatter and a markdown body), 'read' (load the current handoff content for context pickup), 'archive' (rename the active handoff to handoff.consumed.md to mark it as consumed), 'list' (show all handoff files in .matrixx/). Use this tool when the current session needs to preserve state for a future session, or when a fresh session is resuming work from a prior handoff.";
+/** Maximum bytes tolerated from a single git stdout read before we abort. */
+export declare const MAX_GIT_OUTPUT_BYTES = 4096;
+/** Hard timeout for any single `git` invocation, in milliseconds. */
+export declare const GIT_COMMAND_TIMEOUT_MS = 5000;
+/** Sentinel used when we cannot resolve git metadata for the working dir. */
+export declare const UNKNOWN_GIT_SHA = "unknown";

package/dist/tools/handoff/create-handler.d.ts

@@ -0,0 +1,35 @@
+import type { MatrixxToolContext } from "../shared/define-tool";
+/**
+ * Args expected for the `create` action. Mirrors the documented handoff
+ * sections. All `optional()` fields are passed through to the schema as-is.
+ */
+export type HandoffCreateArgs = {
+    topics: string[];
+    user_requests: string;
+    goal: string;
+    work_completed: string[];
+    current_state: string;
+    pending_tasks?: string[];
+    key_files?: {
+        path: string;
+        purpose: string;
+    }[];
+    important_decisions?: {
+        decision: string;
+        rationale: string;
+    }[];
+    explicit_constraints?: string[];
+    context_for_continuation?: string;
+};
+/**
+ * `handoff` tool — `action: "create"` handler.
+ *
+ * Builds a structured handoff document (validated YAML frontmatter +
+ * human-readable markdown body) and writes it to `.matrixx/handoff.md`.
+ * Returns a `Error:` string if the inputs fail schema validation OR if the
+ * underlying I/O write fails.
+ */
+export declare function handleCreate(args: HandoffCreateArgs, ctx: {
+    directory: string;
+    stateDirectory?: string;
+}, context: MatrixxToolContext): Promise<string>;

package/dist/tools/handoff/git.d.ts

@@ -0,0 +1,12 @@
+import type { GitHead } from "../../features/handoff";
+/**
+ * Resolve the current git HEAD for `directory`.
+ *
+ * Returns a `GitHead` (`{ sha, branch?, detached? }`) when `directory` is
+ * inside a working git repo, or `null` otherwise. Never throws.
+ *
+ * - `sha` always populated (HEAD's commit sha)
+ * - `branch` populated when HEAD points at a local branch
+ * - `detached: true` when HEAD points directly at a commit
+ */
+export declare function getGitHead(directory: string): Promise<GitHead | null>;

package/dist/tools/handoff/list-handler.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `handoff` tool — `action: "list"` handler.
+ *
+ * Returns a human-readable summary of every handoff-shaped file inside
+ * `.matrixx/`. If the directory or any matching files are missing, returns
+ * the documented empty-state string.
+ */
+export declare function handleList(directory: string): string;

package/dist/tools/handoff/read-handler.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `handoff` tool — `action: "read"` handler.
+ *
+ * Loads `.matrixx/handoff.md` and returns its full content (YAML frontmatter
+ * + markdown body) so the LLM can apply it as context for the new session.
+ * Returns a clear `Error:` string if no active handoff exists.
+ */
+export declare function handleRead(directory: string): string;

package/dist/tools/handoff/tools.d.ts

@@ -0,0 +1,11 @@
+import type { MatrixxContext } from "../../plugin/context";
+import { type MatrixxToolDefinition } from "../shared/define-tool";
+/**
+ * `handoff` tool factory.
+ *
+ * Exposes a single `handoff` tool that the LLM dispatches via its `action`
+ * argument. Action handlers are split out into sibling files
+ * (`create-handler`, `read-handler`, `archive-handler`, `list-handler`) so
+ * this dispatcher stays small and each handler can evolve independently.
+ */
+export declare function createHandoffTools(ctx: MatrixxContext): Record<string, MatrixxToolDefinition>;

package/dist/tools/hashline-edit/autocorrect-replacement-lines.d.ts

@@ -0,0 +1 @@
+export declare function autocorrectReplacementLines(originalLines: string[], replacementLines: string[]): string[];

package/dist/tools/hashline-edit/constants.d.ts

@@ -0,0 +1,34 @@
+export declare const NIBBLE_STR = "ZPMQVRWSNKTXJBYH";
+/**
+ * Anchor id width in characters. Each char is one NIBBLE_STR symbol, so 4
+ * chars give a 16-symbol (2^16 = 65,536 entry) index space — a 32-bit id.
+ *
+ * The width used to be 2 (8 bits). At 8 bits a 1200-line file has
+ * N(N-1)/512 = 2,810 expected colliding pairs, so a stale anchor matched an
+ * unrelated line most of the time. At 4 chars that drops to N(N-1)/131,072.
+ */
+export declare const HASHLINE_ID_LENGTH = 4;
+/** @deprecated pre-widening anchor width; still parsed, validated more weakly. */
+export declare const LEGACY_HASHLINE_ID_LENGTH = 2;
+/** Number of dictionary entries — the full 16-bit index space. */
+export declare const HASHLINE_DICT_SIZE = 65536;
+/**
+ * Escaped NIBBLE_STR for use inside a character class. Derived from the single
+ * definition of the alphabet so the patterns below can never drift from the
+ * dictionary that produces the ids they match.
+ */
+export declare const NIBBLE_CHARSET: string;
+/** Generated, not hand-written — 65,536 ids would be an unusable literal. */
+export declare const HASHLINE_DICT: string[];
+/** @deprecated pre-widening 8-bit dictionary, kept only to validate old anchors. */
+export declare const LEGACY_HASHLINE_DICT: string[];
+/** Canonical ref: `12#ABCD`. */
+export declare const HASHLINE_REF_PATTERN: RegExp;
+/** Read output line: `12#ABCD|content`. */
+export declare const HASHLINE_OUTPUT_PATTERN: RegExp;
+/** Pre-widening ref: `12#AB`. Deprecated width, still accepted on parse. */
+export declare const LEGACY_HASHLINE_REF_PATTERN: RegExp;
+/** A bare hash id, canonical or legacy. */
+export declare const HASHLINE_HASH_PATTERN: RegExp;
+/** Trailing hash id of a ref, canonical or legacy. */
+export declare const HASHLINE_TRAILING_HASH_PATTERN: RegExp;

package/dist/tools/hashline-edit/diff-utils.d.ts

@@ -0,0 +1,6 @@
+export declare function toHashlineContent(content: string): string;
+export declare function generateUnifiedDiff(oldContent: string, newContent: string, filePath: string): string;
+export declare function countLineDiffs(oldContent: string, newContent: string): {
+    additions: number;
+    deletions: number;
+};

package/dist/tools/hashline-edit/edit-deduplication.d.ts

@@ -0,0 +1,5 @@
+import type { HashlineEdit } from "./types";
+export declare function dedupeEdits(edits: HashlineEdit[]): {
+    edits: HashlineEdit[];
+    deduplicatedEdits: number;
+};

package/dist/tools/hashline-edit/edit-operation-primitives.d.ts

@@ -0,0 +1,10 @@
+interface EditApplyOptions {
+    skipValidation?: boolean;
+}
+export declare function applySetLine(lines: string[], anchor: string, newText: string | string[], options?: EditApplyOptions): string[];
+export declare function applyReplaceLines(lines: string[], startAnchor: string, endAnchor: string, newText: string | string[], options?: EditApplyOptions): string[];
+export declare function applyInsertAfter(lines: string[], anchor: string, text: string | string[], options?: EditApplyOptions): string[];
+export declare function applyInsertBefore(lines: string[], anchor: string, text: string | string[], options?: EditApplyOptions): string[];
+export declare function applyAppend(lines: string[], text: string | string[]): string[];
+export declare function applyPrepend(lines: string[], text: string | string[]): string[];
+export {};