opencode-matrixx-v2 0.0.0-stage → 1.1.0

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

@@ -0,0 +1,124 @@
+export interface LSPServerConfig {
+    id: string;
+    command: string[];
+    extensions: string[];
+    disabled?: boolean;
+    env?: Record<string, string>;
+    initialization?: Record<string, unknown>;
+}
+export interface Position {
+    line: number;
+    character: number;
+}
+export interface Range {
+    start: Position;
+    end: Position;
+}
+export interface Location {
+    uri: string;
+    range: Range;
+}
+export interface LocationLink {
+    targetUri: string;
+    targetRange: Range;
+    targetSelectionRange: Range;
+    originSelectionRange?: Range;
+}
+export interface SymbolInfo {
+    name: string;
+    kind: number;
+    location: Location;
+    containerName?: string;
+}
+export interface DocumentSymbol {
+    name: string;
+    kind: number;
+    range: Range;
+    selectionRange: Range;
+    children?: DocumentSymbol[];
+}
+export interface Diagnostic {
+    range: Range;
+    severity?: number;
+    code?: string | number;
+    source?: string;
+    message: string;
+}
+interface TextDocumentIdentifier {
+    uri: string;
+}
+interface VersionedTextDocumentIdentifier extends TextDocumentIdentifier {
+    version: number | null;
+}
+export interface TextEdit {
+    range: Range;
+    newText: string;
+}
+interface TextDocumentEdit {
+    textDocument: VersionedTextDocumentIdentifier;
+    edits: TextEdit[];
+}
+interface CreateFile {
+    kind: "create";
+    uri: string;
+    options?: {
+        overwrite?: boolean;
+        ignoreIfExists?: boolean;
+    };
+}
+interface RenameFile {
+    kind: "rename";
+    oldUri: string;
+    newUri: string;
+    options?: {
+        overwrite?: boolean;
+        ignoreIfExists?: boolean;
+    };
+}
+interface DeleteFile {
+    kind: "delete";
+    uri: string;
+    options?: {
+        recursive?: boolean;
+        ignoreIfNotExists?: boolean;
+    };
+}
+export interface WorkspaceEdit {
+    changes?: {
+        [uri: string]: TextEdit[];
+    };
+    documentChanges?: (TextDocumentEdit | CreateFile | RenameFile | DeleteFile)[];
+}
+export interface PrepareRenameResult {
+    range: Range;
+    placeholder?: string;
+}
+export interface PrepareRenameDefaultBehavior {
+    defaultBehavior: boolean;
+}
+interface ServerLookupInfo {
+    id: string;
+    command: string[];
+    extensions: string[];
+}
+export type ServerLookupResult = {
+    status: "found";
+    server: ResolvedServer;
+} | {
+    status: "not_configured";
+    extension: string;
+    availableServers: string[];
+} | {
+    status: "not_installed";
+    server: ServerLookupInfo;
+    installHint: string;
+};
+export interface ResolvedServer {
+    id: string;
+    command: string[];
+    extensions: string[];
+    priority: number;
+    env?: Record<string, string>;
+    initialization?: Record<string, unknown>;
+}
+export {};

package/dist/tools/lsp/workspace-edit.d.ts

@@ -0,0 +1,8 @@
+import type { WorkspaceEdit } from "./types";
+export interface ApplyResult {
+    success: boolean;
+    filesModified: string[];
+    totalEdits: number;
+    errors: string[];
+}
+export declare function applyWorkspaceEdit(edit: WorkspaceEdit | null): ApplyResult;

package/dist/tools/market-symbol-validator/constants.d.ts

@@ -0,0 +1,14 @@
+import type { SymbolSeverity } from "./types";
+export declare const MARKET_SYMBOL_VALIDATE_DESCRIPTION = "Deterministic, read-only validator for market symbols used in code or config. Enforces the CCXT unified convention. Returns a JSON report with a status exit code (0=clean, 1=warnings, 2=errors).\n\nRules:\n- MS001 perpetual symbol missing the `:settle` suffix (use `BTC/USDT:USDT`).\n- MS002 hardcoded exchange id or exchange-native symbol (e.g. `binance`, `BTCUSDT`) instead of a unified symbol.\n- MS003 symbol not present in the provided `exchangeMarkets` allowlist.\n- MS004 a capability method (fetchOHLCV, createOrder, ...) called without an `exchange.has[...]` guard.\n\nProvide `source` (inline text), `path` (file or directory), and/or `symbols` (a list to validate directly). Providing none fails closed with status 2.";
+export declare const EXCHANGE_IDS: Set<string>;
+export interface Capability {
+    call: string;
+    key: string;
+}
+export declare const CAPABILITIES: Capability[];
+export declare const SYMBOL_EXTENSIONS: string[];
+export declare const RULE_CATALOG: Record<string, {
+    severity: SymbolSeverity;
+    issue: string;
+    fix: string;
+}>;

package/dist/tools/market-symbol-validator/tools.d.ts

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

package/dist/tools/market-symbol-validator/types.d.ts

@@ -0,0 +1,21 @@
+export type SymbolSeverity = "warn" | "error";
+export interface SymbolFinding {
+    rule: string;
+    severity: SymbolSeverity;
+    file: string;
+    line: number;
+    symbol: string;
+    issue: string;
+    fix: string;
+}
+export interface SymbolSummary {
+    filesScanned: number;
+    total: number;
+    byRule: Record<string, number>;
+    note?: string;
+}
+export interface SymbolValidationResult {
+    status: 0 | 1 | 2;
+    findings: SymbolFinding[];
+    summary: SymbolSummary;
+}

package/dist/tools/market-symbol-validator/validator.d.ts

@@ -0,0 +1,9 @@
+import type { SymbolFinding, SymbolValidationResult } from "./types";
+export declare function validateText(text: string, file: string, marketSet: Set<string> | null): SymbolFinding[];
+export declare function validateSymbols(symbols: string[], marketSet: Set<string> | null): SymbolFinding[];
+export declare function validatePath(opts: {
+    base: string;
+    target: string;
+    marketSet: Set<string> | null;
+}): SymbolValidationResult;
+export declare function buildResult(findings: SymbolFinding[], filesScanned: number): SymbolValidationResult;

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

@@ -0,0 +1,24 @@
+/**
+ * Notepad Tool Constants
+ *
+ * Barrel only. The `task-notepad-writer` hook owns every notepad-storage
+ * constant: `MATRIXX_DIR_NAME`, `NOTEPADS_SUBDIR`, `NOTEPAD_EXTENSION`,
+ * `ADHOC_BUCKET`, `PLAN_NAME_METADATA_KEY`, `SLUG_MAX_LENGTH`, plus the
+ * template helpers (`renderNotepad`, `renderCompletionStamp`,
+ * `taskIdMarkerLine`/`taskIdMarkerPresent`).
+ * This file MUST NEVER re-declare them — import the owner instead, so a
+ * duplicated bucket/template definition cannot come back.
+ * Only notepad-tool-only constants live here.
+ */
+export { ADHOC_BUCKET, COMPLETED_STATUS, COMPLETION_SECTION_TITLE, MATRIXX_DIR_NAME, NOTEPAD_EXTENSION, NOTEPADS_SUBDIR, PLAN_EXTENSION, PLAN_NAME_METADATA_KEY, PLANS_SUBDIR, SLUG_MAX_LENGTH, } from "../../hooks/task-notepad-writer/constants";
+/** Bucket/planName vocabulary: kebab-case `[a-z0-9-]+` (mirrors `PLAN_BASENAME_KEBAB_REGEX`). */
+export declare const NOTEPAD_BUCKET_KEBAB_REGEX: RegExp;
+/** File vocabulary: kebab-case basename ending in `.md` (mirrors `PLAN_FILENAME_KEBAB_REGEX`). */
+export declare const NOTEPAD_FILENAME_KEBAB_REGEX: RegExp;
+/** Error vocabulary shared by the notepad tool family (Tasks 2-3). */
+export declare const NOTEPAD_ERROR_CODES: {
+    readonly invalidPlanName: "invalid_plan_name";
+    readonly invalidFilePath: "invalid_file_path";
+    readonly notFound: "not_found";
+};
+export type NotepadErrorCode = (typeof NOTEPAD_ERROR_CODES)[keyof typeof NOTEPAD_ERROR_CODES];

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

@@ -0,0 +1,20 @@
+/**
+ * Notepad tools barrel (Task 1).
+ *
+ * Path/template LOGIC is owned by `src/hooks/task-notepad-writer/` — this
+ * barrel only re-exports it (thin wrappers allowed, no copies), so `grep
+ * resolveNotepadPath src/` keeps a single definition. Tasks 2-3 build the
+ * `notepad_create` / `notepad_read` / `notepad_append` / `notepad_list`
+ * factories on top of these imports.
+ */
+export { renderCompletionStamp, renderNotepad, taskIdMarkerLine, taskIdMarkerPresent, } from "../../hooks/task-notepad-writer/constants";
+export type { BucketReason, NotepadResolution, NotepadTask, TaskNotepadWriterContext, } from "../../hooks/task-notepad-writer/notepad-path";
+export { countNotepadFiles, extractPlanName, findExistingNotepadForTask, findNotepadForTask, notepadsRootFor, resolveNotepadPath, slugifySubject, } from "../../hooks/task-notepad-writer/notepad-path";
+export type { NotepadErrorCode } from "./constants";
+export { ADHOC_BUCKET, COMPLETED_STATUS, COMPLETION_SECTION_TITLE, MATRIXX_DIR_NAME, NOTEPAD_BUCKET_KEBAB_REGEX, NOTEPAD_ERROR_CODES, NOTEPAD_EXTENSION, NOTEPAD_FILENAME_KEBAB_REGEX, NOTEPADS_SUBDIR, PLAN_NAME_METADATA_KEY, SLUG_MAX_LENGTH, } from "./constants";
+export { createNotepadAppendTool, MAX_NOTEPAD_APPEND_BYTES } from "./notepad-append";
+export { createNotepadCreateTool } from "./notepad-create";
+export { createNotepadListTool } from "./notepad-list";
+export { createNotepadReadTool } from "./notepad-read";
+export type { NotepadBucketReason, NotepadBucketResolution, NotepadPathResolution, NotepadValidationError, } from "./validation";
+export { validateBucketName, validateNotepadFilePath } from "./validation";

package/dist/tools/notepad/notepad-append.d.ts

@@ -0,0 +1,4 @@
+import type { MatrixxContext } from "../../plugin/context";
+import { type MatrixxToolDefinition } from "../shared/define-tool";
+export declare const MAX_NOTEPAD_APPEND_BYTES = 40000;
+export declare function createNotepadAppendTool(ctx?: MatrixxContext): MatrixxToolDefinition;

package/dist/tools/notepad/notepad-create.d.ts

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

package/dist/tools/notepad/notepad-list.d.ts

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

package/dist/tools/notepad/notepad-read.d.ts

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

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

@@ -0,0 +1,14 @@
+import { resolveDirectory } from "../plan/types";
+export { resolveDirectory };
+export interface NotepadCreateArgs {
+    planName?: string | undefined;
+    fileName?: string | undefined;
+    subject?: string | undefined;
+    taskId?: string | undefined;
+}
+export interface NotepadReadArgs {
+    planName?: string | undefined;
+    fileName: string;
+    offset?: number | undefined;
+    limit?: number | undefined;
+}

package/dist/tools/notepad/validation.d.ts

@@ -0,0 +1,33 @@
+import { NOTEPAD_ERROR_CODES } from "./constants";
+export type NotepadBucketReason = "plan-name" | "no-plan-name";
+export interface NotepadBucketResolution {
+    bucket: string;
+    reason: NotepadBucketReason;
+}
+export interface NotepadPathResolution {
+    resolved: string;
+    bucketDir: string;
+    bucket: string;
+}
+export type NotepadValidationError = {
+    error: typeof NOTEPAD_ERROR_CODES.invalidPlanName | typeof NOTEPAD_ERROR_CODES.invalidFilePath;
+    message: string;
+};
+/**
+ * Validate a planName/bucket argument.
+ *
+ * Empty (undefined/null/"") falls back to the adhoc bucket with reason
+ * `no-plan-name` (mirrors the hook `resolveNotepadPath` no-plan-name arm).
+ * Anything outside kebab `[a-z0-9-]+` — including `..`, `/`, `\\`, and
+ * absolute paths — is rejected as `invalid_plan_name`.
+ */
+export declare function validateBucketName(planName: unknown): NotepadBucketResolution | NotepadValidationError;
+/**
+ * Validate a notepad fileName inside a planName bucket.
+ *
+ * Mirrors `validatePlanFilePath`: basename must end `.md`, match kebab-case,
+ * resolve inside the bucket dir (no `..` escape, no subdirectories), and pass
+ * `isAllowedFile`. A bad bucket surfaces `invalid_plan_name`; every file
+ * problem surfaces `invalid_file_path`.
+ */
+export declare function validateNotepadFilePath(fileName: string, planName: string | null | undefined, directory: string): NotepadPathResolution | NotepadValidationError;

package/dist/tools/pdf-extract-figures/tools.d.ts

@@ -0,0 +1,11 @@
+import { type MatrixxToolDefinition } from "../shared/define-tool";
+export interface PdfExtractFiguresArgs {
+    file_path: string;
+    output_dir?: string;
+    page?: number;
+    min_width?: number;
+    min_height?: number;
+    min_area?: number;
+    json_only?: boolean;
+}
+export declare function createPdfExtractFiguresTool(): Record<string, MatrixxToolDefinition>;

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

@@ -0,0 +1,13 @@
+/**
+ * Plan Tool Constants
+ *
+ * Barrel only. mission-state owns every plan-storage constant:
+ * `PLANS_DIR`, `MAX_PLAN_FILE_BYTES`, `META_TAG_PREFIX`, `META_TAG_SUFFIX`.
+ * This file MUST NEVER re-declare them — import the owner instead, so the
+ * duplicated cap definition cannot come back.
+ * Only the plan-tool-only constants live here.
+ */
+export { MAX_PLAN_FILE_BYTES, META_TAG_PREFIX, META_TAG_SUFFIX, PLANS_DIR, } from "../../features/mission-state/constants";
+export declare const MAX_PLAN_READ_RENDERED_BYTES = 40000;
+export declare const PLAN_FILENAME_KEBAB_REGEX: RegExp;
+export declare const PLAN_BASENAME_KEBAB_REGEX: RegExp;

package/dist/tools/plan/error-codes.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Plan Tool Error-Code Taxonomy (Task 14)
+ *
+ * Every plan tool failure is reported as `{ error: <code>, message, ... }` where
+ * `code` is one of `PLAN_ERROR_CODES`. Codes are DISTINCT conditions — a size
+ * refusal never shares a code with a permissions or I/O refusal — so a caller can
+ * decide whether to retry, paginate, shrink, or fix its arguments.
+ *
+ * | code | meaning | retryable |
+ * |------|---------|-----------|
+ * | `file_not_found` | path does not exist | no |
+ * | `invalid_file_path` | failed `validatePlanFilePath` (not `.md`, not kebab, subdirectory, outside `PLANS_DIR`) | no |
+ * | `file_too_large` | over `MAX_PLAN_FILE_BYTES` and the requested mode cannot bypass | yes — via pagination/section |
+ * | `read_failed` | genuinely unreadable (permissions, I/O, encoding) | maybe |
+ * | `validation_error` | a supplied argument is present and invalid | no |
+ * | `section_stale` | supplied `contentHash` ≠ recomputed | yes — re-read |
+ * | `section_not_found` | selector resolves to nothing | no |
+ * | `section_ambiguous` | selector matches >1 candidate | no — disambiguate |
+ * | `size_exceeded` | a write would exceed the cap | no — shrink |
+ * | `trim_required` | consecutive growing writes refused; same content will keep failing | no same-content — retry only with trimmed/deferred content |
+ * | `status_transition_rejected` | backward status jump without `forceCompletion` | no — retry forward or with force |
+ *
+ * RESERVED — declared here, produced by a later task:
+ * - `section_stale`, `section_not_found`, `section_ambiguous` — Task 10/15
+ *   (section selector + contentHash verification). No producer exists yet; do
+ *   not invent one before that task lands.
+ *
+ * `file_too_large` is also populated by Tasks 15/16 (cap-as-ceiling bypass and
+ * the `plan_tasks` degrade path). The codes below are the shared contract.
+ */
+/**
+ * The cap rendered with thousands separators for human-facing prose.
+ * Always derived from the single constant — never a hand-written literal — so the
+ * message and the hint cannot drift from the value the guard actually enforces.
+ */
+export declare function formatPlanCap(cap?: number): string;
+/**
+ * Shared `message` + `hint` for `size_exceeded`. `plan_create` and `plan_update`
+ * reject on mirrored conditions, so both build this from the same function.
+ */
+export declare function planSizeExceededFields(actual: number, cap?: number): {
+    message: string;
+    hint: string;
+};
+/**
+ * Recovery hint for `trim_required`: names concrete trim/defer actions, never
+ * a bare byte total. Same-content retry is NOT retryable; a retry with smaller
+ * (trimmed or deferred) content IS.
+ */
+export declare const TRIM_REQUIRED_HINT = "Trim required: remove completed phases into the plan's out-of-scope table as deferrals, delete verbose evidence blocks, or move a phase range to a cutover companion; then retry with smaller content. Shrinking writes are still accepted.";
+/**
+ * Shared `message` + `hint` + diagnostics for `trim_required`: `actual` is the
+ * refused byte size, `cap` is the enforced cap, `overBy` is how far over the
+ * write landed, and `headroom` is the remaining room measured from the
+ * pre-write content (negative when the file is already over the cap).
+ */
+export declare function planTrimRequiredFields(actual: number, originalBytes: number, cap?: number): {
+    message: string;
+    hint: string;
+    actual: number;
+    cap: number;
+    overBy: number;
+    headroom: number;
+};
+export declare const PLAN_ERROR_CODES: {
+    readonly fileNotFound: "file_not_found";
+    readonly invalidFilePath: "invalid_file_path";
+    readonly fileTooLarge: "file_too_large";
+    readonly readFailed: "read_failed";
+    readonly validationError: "validation_error";
+    readonly sectionStale: "section_stale";
+    readonly sectionNotFound: "section_not_found";
+    readonly sectionAmbiguous: "section_ambiguous";
+    readonly sizeExceeded: "size_exceeded";
+    readonly trimRequired: "trim_required";
+    readonly statusTransitionRejected: "status_transition_rejected";
+};
+export type PlanErrorCode = (typeof PLAN_ERROR_CODES)[keyof typeof PLAN_ERROR_CODES];
+export declare const PLAN_ERROR_MEANINGS: Record<PlanErrorCode, string>;
+export declare const PLAN_ERROR_RETRYABLE: Record<PlanErrorCode, boolean>;
+/** Recovery hint for `file_too_large`: name a concrete next call, not "split the file". */
+export declare const FILE_TOO_LARGE_HINT = "Retry plan_read with offset/limit to page into the file, or with a section selector to read one region; plan_tasks returns the manifest without the body.";
+/** `{ error, message, hint, filePath, size }` — retryable size refusal. */
+export declare function fileTooLargePayload(filePath: string, size: number, cap: number): string;
+/** `{ error, message, filePath }` — genuinely unreadable. Never claims "too large". */
+export declare function readFailedPayload(filePath: string, reason?: string): string;
+/**
+ * Which code a failed plan read should carry.
+ * A permissions/IO errno wins over a size reading — an unreadable file is not
+ * retryable via pagination, so it must not masquerade as `file_too_large`.
+ */
+export declare function classifyReadRefusal(input: {
+    sizeOverCap: number | null;
+    errno: string | null;
+}): "read_failed" | "file_too_large";
+/** Recovery hint for `status_transition_rejected`: forward-only order plus the explicit override. */
+export declare const STATUS_TRANSITION_REJECTED_HINT = "Plan status moves forward only (pending -> in_progress -> completed). Retry with a forward status, or pass forceCompletion: true for an explicit human-approved backward jump.";
+/** `{ error, message, hint, from, to }` — rejected backward status jump. */
+export declare function statusTransitionRejectedPayload(from: string, to: string): string;

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

@@ -0,0 +1,7 @@
+export { MAX_PLAN_FILE_BYTES, PLAN_FILENAME_KEBAB_REGEX, PLANS_DIR } from "./constants";
+export { createPlanCreateTool } from "./plan-create";
+export { createPlanDeleteTool } from "./plan-delete";
+export { createPlanListTool } from "./plan-list";
+export { createPlanReadTool } from "./plan-read";
+export { createPlanTasksTool } from "./plan-tasks";
+export { createPlanUpdateTool } from "./plan-update";

package/dist/tools/plan/plan-create.d.ts

@@ -0,0 +1,3 @@
+import type { MatrixxContext } from "../../plugin/context";
+import { type MatrixxToolDefinition } from "../shared/define-tool";
+export declare function createPlanCreateTool(ctx?: MatrixxContext, cap?: number): MatrixxToolDefinition;

package/dist/tools/plan/plan-delete.d.ts

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

package/dist/tools/plan/plan-list.d.ts

@@ -0,0 +1,3 @@
+import type { MatrixxContext } from "../../plugin/context";
+import { type MatrixxToolDefinition } from "../shared/define-tool";
+export declare function createPlanListTool(ctx?: MatrixxContext, cap?: number): MatrixxToolDefinition;

package/dist/tools/plan/plan-read-pagination.d.ts

@@ -0,0 +1,42 @@
+export type SelectLinesResult = {
+    selected: string[];
+    startIndex: number;
+} | {
+    argument: "offset" | "limit";
+    message: string;
+};
+/**
+ * Strict: an OMITTED offset/limit means "use the default", but a PRESENT-BUT-INVALID
+ * value is an argument error. Silently falling back made `offset: 0` (a common
+ * off-by-one) return the ENTIRE file instead of erroring — on a near-cap file that
+ * is exactly the "100% more damaged" outcome the cap work exists to prevent, and it
+ * masks typos in a machine-facing tool.
+ */
+export declare function resolvePositive(value: unknown, argument: "offset" | "limit"): {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function selectLines(lines: string[], offset?: number, limit?: number): SelectLinesResult;
+/**
+ * Shrink a requested window until its RENDERED payload fits `budget` bytes.
+ *
+ * SAME RULER AS THE CHECK IT CLAMPS AGAINST — `measurePlanBytes` (UTF-8), not
+ * `JSON.stringify(...).length` (UTF-16 code units, which under-count a CJK render
+ * by up to 3x and would let a clamped payload exceed the budget it was clamped to).
+ * Both live in the same module on purpose so they cannot drift apart.
+ *
+ * `build(count, selected)` renders the COMPLETE response — envelope included — for a
+ * window of that many lines, and the returned payload is that same `build` result.
+ * Measuring a bare slice and then wrapping it in metadata would under-count by
+ * exactly the envelope size, which is how a "clamped" payload came out 88 bytes
+ * over the very budget it was clamped to. It must be pure and cheap: the binary
+ * search calls it O(log n) times.
+ */
+export declare function clampWindowToRenderedBudget(lines: string[], startIndex: number, requestedCount: number, budget: number, build: (count: number, selected: string[]) => unknown): {
+    count: number;
+    clamped: boolean;
+    payload: unknown;
+};

package/dist/tools/plan/plan-read.d.ts

@@ -0,0 +1,3 @@
+import type { MatrixxContext } from "../../plugin/context";
+import { type MatrixxToolDefinition } from "../shared/define-tool";
+export declare function createPlanReadTool(ctx?: MatrixxContext, cap?: number): MatrixxToolDefinition;

package/dist/tools/plan/plan-tasks-clamp.d.ts

@@ -0,0 +1,32 @@
+/** How many entries of `total` the payload actually shows. */
+export interface TruncationMarker {
+    shown: number;
+    total: number;
+}
+export interface ManifestView<TItem> {
+    tasks: TItem[];
+    dod: string[];
+    /** Non-null whenever `tasks` was dropped from the tail. */
+    tasksTruncated: TruncationMarker | null;
+    /** Non-null only when `tasks` alone could not fit the budget. */
+    dodTruncated: TruncationMarker | null;
+}
+export interface ClampResult<TItem> {
+    payload: unknown;
+    view: ManifestView<TItem>;
+    /** True when either list was shortened. */
+    clamped: boolean;
+}
+/**
+ * Clamp a two-list manifest to the rendered budget: `tasks` first (dropped from
+ * the TAIL), then `dod` only if `tasks` alone still cannot fit.
+ *
+ * `tasks` is the unbounded axis — a pathological plan can carry thousands of
+ * numbered entries — so it absorbs the cut. `dod` is small and bounded in
+ * practice, making it a last resort rather than routine behaviour.
+ *
+ * `build` composes the whole response from the view, so truncation markers and
+ * hints ride along only when real. When the full manifest already fits, the
+ * returned view carries null markers and the payload is the untruncated one.
+ */
+export declare function clampManifestToRenderedBudget<TItem>(tasks: readonly TItem[], dod: readonly string[], budget: number, build: (view: ManifestView<TItem>) => unknown): ClampResult<TItem>;

package/dist/tools/plan/plan-tasks.d.ts

@@ -0,0 +1,3 @@
+import type { MatrixxContext } from "../../plugin/context";
+import { type MatrixxToolDefinition } from "../shared/define-tool";
+export declare function createPlanTasksTool(ctx?: MatrixxContext, cap?: number): MatrixxToolDefinition;

package/dist/tools/plan/plan-update.d.ts

@@ -0,0 +1,4 @@
+import type { MatrixxContext } from "../../plugin/context";
+import { type MatrixxToolDefinition } from "../shared/define-tool";
+import { type PostApplyHook } from "./plan-write-guard";
+export declare function createPlanUpdateTool(ctx?: MatrixxContext, postApply?: PostApplyHook, cap?: number): MatrixxToolDefinition;

package/dist/tools/plan/plan-write-guard.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The plan write path's cap guard — the ONLY place a write is measured against
+ * the cap and the ONLY place a write is rolled back.
+ *
+ * `grep -rn "MAX_PLAN_FILE_BYTES" src/tools/plan/plan-update.ts` shows the hashline
+ * path and the section-scoped path both arrive here as the same `appliedContent`:
+ * a section-scoped edit is resolved to anchors and then written by the same
+ * executor. One guard, one rollback, no second copy to drift.
+ */
+/** `keep` — the applied content is under the cap and must be persisted. */
+export interface PlanCapKept {
+    kind: "keep";
+    bytes: number;
+}
+/** `rolled-back` — over the cap: the original bytes are restored and this is the payload. */
+export interface PlanCapExceeded {
+    kind: "rolled-back";
+    bytes: number;
+    payload: string;
+}
+export type PlanCapVerdict = PlanCapKept | PlanCapExceeded;
+export declare const TRIM_REQUIRED_AFTER_CONSECUTIVE_REFUSALS = 2;
+export declare function resetPlanWriteGuardForTesting(): void;
+/**
+ * Runs between "the edit is on disk" and "the cap is enforced" so a fault in
+ * that window can be injected. Production passes nothing; the parameter exists
+ * so the window is reachable from a test rather than only from a real crash.
+ */
+export type PostApplyHook = () => void;
+/**
+ * Measure `appliedContent` with the single byte ruler, and roll back to
+ * `originalContent` when it is over the cap.
+ *
+ * The rollback goes through the same tmp+rename `atomicWrite` as the apply, so a
+ * crash mid-restore cannot truncate the plan: the target is never written in
+ * place, only ever replaced by rename.
+ */
+export declare function enforcePlanCap(resolved: string, originalContent: string, appliedContent: string, cap?: number): PlanCapVerdict;

package/dist/tools/plan/section-edit.d.ts

@@ -0,0 +1,24 @@
+import type { RawHashlineEdit } from "../hashline-edit/normalize-edits";
+/** A section-scoped edit, as it arrives on the wire. */
+export interface RawSectionEdit extends RawHashlineEdit {
+    section?: string;
+    sectionIndex?: number;
+    contentHash?: string;
+}
+type Outcome = {
+    kind: "error";
+    body: Record<string, unknown>;
+} | {
+    kind: "ok";
+    edits: RawHashlineEdit[];
+    sectionIds: string[];
+};
+/**
+ * Resolve every section-scoped edit against ONE fresh parse of `content`, and
+ * return the equivalent absolute hashline edits. Edits with no `section` pass
+ * through untouched, so a single call may mix both forms.
+ */
+export declare function resolveSectionScopedEdits(content: string, rawEdits: RawSectionEdit[]): Outcome;
+/** Post-write section metadata. All hashes are RECOMPUTED from the new text. */
+export declare function sectionWritePayload(content: string, sectionIds: string[]): Record<string, unknown>;
+export {};

package/dist/tools/plan/section-index.d.ts

@@ -0,0 +1,22 @@
+import type { PlanOutlineEntry, PlanSectionIndexEntry } from "./types";
+/** 64-bit position-sensitive hash; lowercase hex, exactly 16 digits. */
+export declare function computeSectionHash(id: string, startLine: number, span: string): string;
+/** The section's exact original text span, trailing newline included when present. */
+export declare function readSectionSpan(lines: string[], entry: PlanSectionIndexEntry): string;
+/**
+ * Build the byte-accounted section index. Anything before the first H2/H3 (the
+ * document title, the preamble) is NOT a section and is excluded — callers
+ * account for it separately as front matter when reconciling bytes.
+ */
+export declare function buildSectionIndex(content: string): PlanSectionIndexEntry[];
+/**
+ * Legacy truncation outline, moved here out of `plan-read.ts`.
+ *
+ * The shape is UNCHANGED (`{ level, text, line, anchor }`) because `plan_read`'s
+ * `{truncated, outline, hint}` payload is a live contract. Numbered tasks are
+ * reported wherever they appear — most of the corpus has no `## TODOs` section
+ * (21/35 plans carry zero numbered tasks), so this must not assume one. Task
+ * progress stays with `countPlanProgressFromContent`; this is a locator, never
+ * a progress authority.
+ */
+export declare function buildOutline(lines: string[]): PlanOutlineEntry[];

package/dist/tools/plan/section-locate.d.ts

@@ -0,0 +1,9 @@
+import type { PlanSectionIndexEntry } from "./types";
+/** Stable, de-duplicated list of the ids THIS file actually has. */
+export declare function availableSectionIds(entries: PlanSectionIndexEntry[]): string[];
+/** Resolve a selector to exactly ONE entry, failing closed on duplicates. */
+export declare function locateSectionEntry(entries: PlanSectionIndexEntry[], selector: string, sectionIndex: number | undefined): {
+    entry: PlanSectionIndexEntry;
+} | {
+    failure: Record<string, unknown>;
+};