agent-threader 2.0.5

package/dist/lib/contracts/types.d.ts

@@ -0,0 +1,91 @@
+export interface ManifestV2 {
+    manifest_version: "2.0";
+    run_id: string;
+    tasks: ManifestTaskV2[];
+}
+export interface ManifestTaskV2 {
+    id: string;
+    prompt_ref: string;
+    depends_on: string[];
+    timeout_sec: number;
+    verify_profile: string;
+    context_refs?: string[];
+    priority?: number;
+    retry_policy?: RetryPolicy;
+    metadata?: Record<string, unknown>;
+}
+export interface RetryPolicy {
+    max_attempts?: number;
+    retry_on?: string[];
+}
+export interface VerifyProfileRegistry {
+    profiles: Record<string, VerifyProfile>;
+}
+export interface VerifyProfile {
+    steps: VerifyStep[];
+    rollback_on_failure: boolean;
+}
+export interface VerifyStep {
+    name: string;
+    cmd: string;
+    cwd: string;
+    timeout_sec: number;
+}
+export interface TaskResultV2 {
+    contract_version: "2.0";
+    task_id: string;
+    status: "DONE" | "BLOCKED" | "FAILED" | "CONTRACT_ERROR";
+    summary: string;
+    changed_files?: string[];
+    writes?: WriteEntry[];
+    evidence?: Evidence;
+    failure_class?: string;
+}
+export interface WriteEntry {
+    path: string;
+    op: "create" | "replace" | "append";
+    encoding: "utf8";
+    content?: string;
+    content_ref?: string;
+    sha256_before?: string;
+}
+export interface Evidence {
+    commands?: string[];
+    log_refs?: string[];
+    notes?: string[];
+}
+export interface HealDecisionV2 {
+    contract_version: "2.0";
+    scope: "task" | "batch" | "epoch";
+    decision: "RETRY" | "ESCALATE" | "NOT_FIXABLE";
+    failure_class: string;
+    root_cause: string;
+    patches: HealPatch[];
+    learned_rule?: string;
+    escalations?: Array<{
+        task_id: string;
+        reason: string;
+    }>;
+    retry_policy?: HealRetryPolicy;
+}
+export interface HealPatch {
+    target: "shared_context" | "task_prompt" | "runtime_patch" | "contract_hint";
+    operation: "replace" | "append" | "merge";
+    path?: string;
+    task_id?: string;
+    content?: string | Record<string, unknown>;
+}
+export interface HealRetryPolicy {
+    reset_tasks?: string[];
+    retry_window?: "same_window" | "shrink_window" | "next_epoch";
+}
+export type ParserErrorCode = "NO_SENTINEL" | "INVALID_JSON" | "SCHEMA_VIOLATION" | "MISSING_REQUIRED_FIELD" | "UNSUPPORTED_VERSION";
+export interface ParserFailure {
+    ok: false;
+    code: ParserErrorCode;
+    message: string;
+}
+export type FailureClass = "prompt_gap" | "missing_paths" | "weak_contract" | "contract_error" | "output_format" | "build_error" | "test_error" | "smoke_error" | "timeout" | "transient_infra" | "blocked_external" | "real_bug" | "unknown";
+export declare const HEALABLE_FAILURE_CLASSES: ReadonlySet<string>;
+export declare const NON_HEALABLE_FAILURE_CLASSES: ReadonlySet<string>;
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/contracts/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/contracts/types.ts"],"names":[],"mappings":"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"}

package/dist/lib/contracts/types.js

@@ -0,0 +1,15 @@
+// ─── Manifest ────────────────────────────────────────────────────────────────
+export const HEALABLE_FAILURE_CLASSES = new Set([
+    "prompt_gap",
+    "missing_paths",
+    "weak_contract",
+    "contract_error",
+    "output_format",
+    "timeout",
+    "transient_infra",
+]);
+export const NON_HEALABLE_FAILURE_CLASSES = new Set([
+    "blocked_external",
+    "real_bug",
+]);
+//# sourceMappingURL=types.js.map

package/dist/lib/contracts/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/contracts/types.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAkIhF,MAAM,CAAC,MAAM,wBAAwB,GAAwB,IAAI,GAAG,CAAC;IACnE,YAAY;IACZ,eAAe;IACf,eAAe;IACf,gBAAgB;IAChB,eAAe;IACf,SAAS;IACT,iBAAiB;CAClB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,4BAA4B,GAAwB,IAAI,GAAG,CAAC;IACvE,kBAAkB;IAClB,UAAU;CACX,CAAC,CAAC"}

package/dist/lib/contracts/validate-manifest.d.ts

@@ -0,0 +1,16 @@
+export interface ValidateManifestOptions {
+    manifestPath: string;
+}
+export interface Issue {
+    severity: "error" | "warning";
+    message: string;
+}
+export interface ValidateManifestResult {
+    valid: boolean;
+    taskCount: number;
+    issues: Issue[];
+    dependencyOrder: string[];
+    warnings: string[];
+}
+export declare function validateManifest(options: ValidateManifestOptions): ValidateManifestResult;
+//# sourceMappingURL=validate-manifest.d.ts.map

package/dist/lib/contracts/validate-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-manifest.d.ts","sourceRoot":"","sources":["../../../src/lib/contracts/validate-manifest.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,KAAK;IACpB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,sBAAsB,CAkFzF"}

package/dist/lib/contracts/validate-manifest.js

@@ -0,0 +1,123 @@
+import { readFileSync } from "node:fs";
+import { ConfigError } from "../errors/types.js";
+import { validateManifestSchema } from "./schema-validator.js";
+export function validateManifest(options) {
+    const issues = [];
+    const warnings = [];
+    let raw;
+    try {
+        raw = readFileSync(options.manifestPath, "utf8");
+    }
+    catch (e) {
+        throw new ConfigError(options.manifestPath, `Cannot read manifest: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new ConfigError(options.manifestPath, `Invalid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const schemaResult = validateManifestSchema(data);
+    if (!schemaResult.valid) {
+        for (const err of schemaResult.errors) {
+            issues.push({ severity: "error", message: `${err.path}: ${err.message}` });
+        }
+        return { valid: false, taskCount: 0, issues, dependencyOrder: [], warnings };
+    }
+    const manifest = data;
+    const taskIds = new Set();
+    const duplicates = new Set();
+    for (const task of manifest.tasks) {
+        if (!task.id || typeof task.id !== "string") {
+            issues.push({ severity: "error", message: "Task missing id" });
+            continue;
+        }
+        if (taskIds.has(task.id)) {
+            duplicates.add(task.id);
+        }
+        taskIds.add(task.id);
+        if (!task.prompt_ref) {
+            issues.push({ severity: "error", message: `Task ${task.id}: missing prompt_ref` });
+        }
+        if (!Array.isArray(task.depends_on)) {
+            issues.push({ severity: "error", message: `Task ${task.id}: missing depends_on array` });
+        }
+        if (typeof task.timeout_sec !== "number" || task.timeout_sec <= 0) {
+            issues.push({ severity: "error", message: `Task ${task.id}: timeout_sec must be > 0` });
+        }
+        if (!task.verify_profile) {
+            issues.push({ severity: "error", message: `Task ${task.id}: missing verify_profile` });
+        }
+    }
+    for (const dup of duplicates) {
+        issues.push({ severity: "error", message: `Duplicate task id: ${dup}` });
+    }
+    for (const task of manifest.tasks) {
+        if (!Array.isArray(task.depends_on))
+            continue;
+        for (const dep of task.depends_on) {
+            if (!taskIds.has(dep)) {
+                issues.push({ severity: "error", message: `Task ${task.id}: depends_on references unknown task "${dep}"` });
+            }
+        }
+    }
+    const depOrder = topologicalSort(manifest.tasks, issues);
+    const valid = issues.every(i => i.severity !== "error");
+    return {
+        valid,
+        taskCount: manifest.tasks.length,
+        issues,
+        dependencyOrder: depOrder,
+        warnings,
+    };
+}
+function topologicalSort(tasks, issues) {
+    const graph = new Map();
+    const inDegree = new Map();
+    for (const task of tasks) {
+        graph.set(task.id, []);
+        inDegree.set(task.id, 0);
+    }
+    for (const task of tasks) {
+        if (!Array.isArray(task.depends_on))
+            continue;
+        for (const dep of task.depends_on) {
+            if (!graph.has(dep))
+                continue;
+            graph.get(dep).push(task.id);
+            inDegree.set(task.id, (inDegree.get(task.id) ?? 0) + 1);
+        }
+    }
+    // Priority-aware: lower priority value = earlier in queue
+    const priorityMap = new Map();
+    for (const task of tasks) {
+        priorityMap.set(task.id, task.priority ?? Infinity);
+    }
+    const queue = [];
+    for (const [id, deg] of inDegree) {
+        if (deg === 0)
+            queue.push(id);
+    }
+    queue.sort((a, b) => (priorityMap.get(a) ?? Infinity) - (priorityMap.get(b) ?? Infinity));
+    const order = [];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        order.push(current);
+        const ready = [];
+        for (const neighbor of graph.get(current) ?? []) {
+            const newDeg = (inDegree.get(neighbor) ?? 1) - 1;
+            inDegree.set(neighbor, newDeg);
+            if (newDeg === 0)
+                ready.push(neighbor);
+        }
+        ready.sort((a, b) => (priorityMap.get(a) ?? Infinity) - (priorityMap.get(b) ?? Infinity));
+        queue.push(...ready);
+    }
+    if (order.length < tasks.length) {
+        const inCycle = tasks.filter(t => !order.includes(t.id)).map(t => t.id);
+        issues.push({ severity: "error", message: `Circular dependency detected involving: ${inCycle.join(", ")}` });
+    }
+    return order;
+}
+//# sourceMappingURL=validate-manifest.js.map

package/dist/lib/contracts/validate-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-manifest.js","sourceRoot":"","sources":["../../../src/lib/contracts/validate-manifest.ts"],"names":[],"mappings":"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"}

package/dist/lib/diagnostics/doctor.d.ts

@@ -0,0 +1,17 @@
+export type DoctorStatus = 'pass' | 'warn' | 'fail';
+export interface DoctorCheck {
+    id: string;
+    title: string;
+    status: DoctorStatus;
+    detail: string;
+    recommendation?: string;
+}
+export interface DoctorResult {
+    ok: boolean;
+    checks: DoctorCheck[];
+}
+export interface DoctorOptions {
+    cwd?: string;
+}
+export declare function runDoctor(options?: DoctorOptions): DoctorResult;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/lib/diagnostics/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/lib/diagnostics/doctor.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AA4HD,wBAAgB,SAAS,CAAC,OAAO,GAAE,aAAkB,GAAG,YAAY,CAcnE"}

package/dist/lib/diagnostics/doctor.js

@@ -0,0 +1,131 @@
+import { accessSync, constants, existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+function parseMajor(version) {
+    const clean = version.startsWith('v') ? version.slice(1) : version;
+    const [majorRaw] = clean.split('.');
+    const major = Number.parseInt(majorRaw, 10);
+    return Number.isNaN(major) ? 0 : major;
+}
+function checkNodeVersion() {
+    const major = parseMajor(process.version);
+    if (major >= 18) {
+        return {
+            id: 'node_version',
+            title: 'Node.js version',
+            status: 'pass',
+            detail: `Detected ${process.version} (supported: >=18)`,
+        };
+    }
+    return {
+        id: 'node_version',
+        title: 'Node.js version',
+        status: 'fail',
+        detail: `Detected ${process.version} (supported: >=18)`,
+        recommendation: 'Upgrade Node.js to 18 or newer.',
+    };
+}
+function checkNpm() {
+    const result = spawnSync('npm', ['--version'], { encoding: 'utf8' });
+    if (result.status === 0) {
+        const version = (result.stdout ?? '').trim();
+        return {
+            id: 'npm_available',
+            title: 'npm availability',
+            status: 'pass',
+            detail: `npm ${version || 'available'}`,
+        };
+    }
+    return {
+        id: 'npm_available',
+        title: 'npm availability',
+        status: 'fail',
+        detail: 'npm was not found in PATH or failed to run.',
+        recommendation: 'Install npm and ensure it is available in your shell PATH.',
+    };
+}
+function checkHomeWritable() {
+    const home = os.homedir();
+    try {
+        accessSync(home, constants.W_OK);
+        return {
+            id: 'home_writable',
+            title: 'Home directory write access',
+            status: 'pass',
+            detail: `Writable: ${home}`,
+        };
+    }
+    catch {
+        return {
+            id: 'home_writable',
+            title: 'Home directory write access',
+            status: 'fail',
+            detail: `Not writable: ${home}`,
+            recommendation: 'Ensure your user can write to the home directory for skill installation.',
+        };
+    }
+}
+function checkInstallScriptParity(cwd) {
+    const rootInstall = path.join(cwd, 'install.sh');
+    const siteInstall = path.join(cwd, 'site', 'install.sh');
+    if (!existsSync(rootInstall) || !existsSync(siteInstall)) {
+        return {
+            id: 'install_script_sync',
+            title: 'Installer parity (repo clone)',
+            status: 'warn',
+            detail: 'install.sh and site/install.sh were not both found in current directory.',
+            recommendation: 'Run doctor from the AgentThreader repository to verify script parity.',
+        };
+    }
+    const rootContent = readFileSync(rootInstall, 'utf8');
+    const siteContent = readFileSync(siteInstall, 'utf8');
+    if (rootContent === siteContent) {
+        return {
+            id: 'install_script_sync',
+            title: 'Installer parity (repo clone)',
+            status: 'pass',
+            detail: 'install.sh and site/install.sh are in sync.',
+        };
+    }
+    return {
+        id: 'install_script_sync',
+        title: 'Installer parity (repo clone)',
+        status: 'warn',
+        detail: 'install.sh and site/install.sh differ.',
+        recommendation: 'Copy root install.sh to site/install.sh after installer changes.',
+    };
+}
+function checkCompiledArtifacts(cwd) {
+    const expected = path.join(cwd, 'compiled', 'cursor', 'skills', 'agent-threader', 'SKILL.md');
+    if (existsSync(expected)) {
+        return {
+            id: 'compiled_artifacts',
+            title: 'Compiled skill artifacts',
+            status: 'pass',
+            detail: 'Compiled skill artifacts are present.',
+        };
+    }
+    return {
+        id: 'compiled_artifacts',
+        title: 'Compiled skill artifacts',
+        status: 'warn',
+        detail: 'Compiled artifacts were not found in this working directory.',
+        recommendation: 'From a repo clone, run: npm run compile',
+    };
+}
+export function runDoctor(options = {}) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const checks = [
+        checkNodeVersion(),
+        checkNpm(),
+        checkHomeWritable(),
+        checkInstallScriptParity(cwd),
+        checkCompiledArtifacts(cwd),
+    ];
+    return {
+        ok: checks.every((check) => check.status !== 'fail'),
+        checks,
+    };
+}
+//# sourceMappingURL=doctor.js.map

package/dist/lib/diagnostics/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../../src/lib/diagnostics/doctor.ts"],"names":[],"mappings":"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"}

package/dist/lib/errors/explain-error.d.ts

@@ -0,0 +1,10 @@
+export interface ErrorExplanation {
+    code: string;
+    category: 'app' | 'parser';
+    meaning: string;
+    likelyCauses: string[];
+    suggestedFixes: string[];
+}
+export declare function explainErrorCode(code: string): ErrorExplanation | undefined;
+export declare function listKnownErrorCodes(): string[];
+//# sourceMappingURL=explain-error.d.ts.map

package/dist/lib/errors/explain-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-error.d.ts","sourceRoot":"","sources":["../../../src/lib/errors/explain-error.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,GAAG,QAAQ,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAoED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAG3E;AAED,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C"}

package/dist/lib/errors/explain-error.js

@@ -0,0 +1,73 @@
+const EXPLANATIONS = {
+    APP_ERROR: {
+        code: 'APP_ERROR',
+        category: 'app',
+        meaning: 'A generic application error was thrown.',
+        likelyCauses: ['Unexpected runtime condition', 'Unhandled edge case in command flow'],
+        suggestedFixes: ['Rerun with a narrower input and inspect command output', 'Use `agent-threader explain <code>` on a more specific code when available'],
+    },
+    NOT_FOUND_ERROR: {
+        code: 'NOT_FOUND_ERROR',
+        category: 'app',
+        meaning: 'A required file or entity could not be found.',
+        likelyCauses: ['Incorrect file path', 'Missing state or manifest file'],
+        suggestedFixes: ['Verify the path exists', 'Run from the expected working directory'],
+    },
+    COMMAND_ERROR: {
+        code: 'COMMAND_ERROR',
+        category: 'app',
+        meaning: 'A subprocess command failed.',
+        likelyCauses: ['Build/test command exited non-zero', 'Missing tool in PATH'],
+        suggestedFixes: ['Run the failing command directly to inspect full output', 'Install the required tool and retry'],
+    },
+    CONFIG_ERROR: {
+        code: 'CONFIG_ERROR',
+        category: 'app',
+        meaning: 'A configuration or contract file could not be read or validated.',
+        likelyCauses: ['Invalid JSON syntax', 'Schema mismatch', 'Unreadable file permissions'],
+        suggestedFixes: ['Validate JSON formatting', 'Run `agent-threader validate-manifest <path>`', 'Check file permissions'],
+    },
+    NO_SENTINEL: {
+        code: 'NO_SENTINEL',
+        category: 'parser',
+        meaning: 'Expected contract sentinel block was not found in log output.',
+        likelyCauses: ['Worker/healer did not emit fenced contract', 'Wrong log file was parsed'],
+        suggestedFixes: ['Ensure prompts require the correct sentinel marker', 'Confirm you passed the correct log path'],
+    },
+    INVALID_JSON: {
+        code: 'INVALID_JSON',
+        category: 'parser',
+        meaning: 'Contract sentinel was found, but JSON could not be parsed.',
+        likelyCauses: ['Malformed JSON emitted by model', 'Truncated contract output'],
+        suggestedFixes: ['Tighten prompt instructions for strict JSON', 'Retry task and verify full contract block is present'],
+    },
+    SCHEMA_VIOLATION: {
+        code: 'SCHEMA_VIOLATION',
+        category: 'parser',
+        meaning: 'JSON parsed successfully, but contract schema validation failed.',
+        likelyCauses: ['Unexpected field names/types', 'Missing required contract fields'],
+        suggestedFixes: ['Compare output against schema in `skill/schemas`', 'Update prompt to enforce exact field names and enums'],
+    },
+    MISSING_REQUIRED_FIELD: {
+        code: 'MISSING_REQUIRED_FIELD',
+        category: 'parser',
+        meaning: 'Required contract fields are missing from output.',
+        likelyCauses: ['Model omitted fields', 'Prompt did not include complete contract requirements'],
+        suggestedFixes: ['Include required fields explicitly in prompt template', 'Use examples that include full contract shape'],
+    },
+    UNSUPPORTED_VERSION: {
+        code: 'UNSUPPORTED_VERSION',
+        category: 'parser',
+        meaning: 'Contract version in output is not supported by this runtime.',
+        likelyCauses: ['Outdated prompts', 'Mixed version artifacts in workflow'],
+        suggestedFixes: ['Emit contract_version 2.0 for v2 contracts', 'Align prompt/system instructions with current schema version'],
+    },
+};
+export function explainErrorCode(code) {
+    const key = code.trim().toUpperCase();
+    return EXPLANATIONS[key];
+}
+export function listKnownErrorCodes() {
+    return Object.keys(EXPLANATIONS).sort();
+}
+//# sourceMappingURL=explain-error.js.map

package/dist/lib/errors/explain-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-error.js","sourceRoot":"","sources":["../../../src/lib/errors/explain-error.ts"],"names":[],"mappings":"AAUA,MAAM,YAAY,GAAqC;IACrD,SAAS,EAAE;QACT,IAAI,EAAE,WAAW;QACjB,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,yCAAyC;QAClD,YAAY,EAAE,CAAC,8BAA8B,EAAE,qCAAqC,CAAC;QACrF,cAAc,EAAE,CAAC,wDAAwD,EAAE,4EAA4E,CAAC;KACzJ;IACD,eAAe,EAAE;QACf,IAAI,EAAE,iBAAiB;QACvB,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,+CAA+C;QACxD,YAAY,EAAE,CAAC,qBAAqB,EAAE,gCAAgC,CAAC;QACvE,cAAc,EAAE,CAAC,wBAAwB,EAAE,yCAAyC,CAAC;KACtF;IACD,aAAa,EAAE;QACb,IAAI,EAAE,eAAe;QACrB,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,8BAA8B;QACvC,YAAY,EAAE,CAAC,oCAAoC,EAAE,sBAAsB,CAAC;QAC5E,cAAc,EAAE,CAAC,yDAAyD,EAAE,qCAAqC,CAAC;KACnH;IACD,YAAY,EAAE;QACZ,IAAI,EAAE,cAAc;QACpB,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,kEAAkE;QAC3E,YAAY,EAAE,CAAC,qBAAqB,EAAE,iBAAiB,EAAE,6BAA6B,CAAC;QACvF,cAAc,EAAE,CAAC,0BAA0B,EAAE,+CAA+C,EAAE,wBAAwB,CAAC;KACxH;IACD,WAAW,EAAE;QACX,IAAI,EAAE,aAAa;QACnB,QAAQ,EAAE,QAAQ;QAClB,OAAO,EAAE,+DAA+D;QACxE,YAAY,EAAE,CAAC,4CAA4C,EAAE,2BAA2B,CAAC;QACzF,cAAc,EAAE,CAAC,oDAAoD,EAAE,yCAAyC,CAAC;KAClH;IACD,YAAY,EAAE;QACZ,IAAI,EAAE,cAAc;QACpB,QAAQ,EAAE,QAAQ;QAClB,OAAO,EAAE,4DAA4D;QACrE,YAAY,EAAE,CAAC,iCAAiC,EAAE,2BAA2B,CAAC;QAC9E,cAAc,EAAE,CAAC,6CAA6C,EAAE,sDAAsD,CAAC;KACxH;IACD,gBAAgB,EAAE;QAChB,IAAI,EAAE,kBAAkB;QACxB,QAAQ,EAAE,QAAQ;QAClB,OAAO,EAAE,kEAAkE;QAC3E,YAAY,EAAE,CAAC,8BAA8B,EAAE,kCAAkC,CAAC;QAClF,cAAc,EAAE,CAAC,kDAAkD,EAAE,sDAAsD,CAAC;KAC7H;IACD,sBAAsB,EAAE;QACtB,IAAI,EAAE,wBAAwB;QAC9B,QAAQ,EAAE,QAAQ;QAClB,OAAO,EAAE,mDAAmD;QAC5D,YAAY,EAAE,CAAC,sBAAsB,EAAE,uDAAuD,CAAC;QAC/F,cAAc,EAAE,CAAC,uDAAuD,EAAE,+CAA+C,CAAC;KAC3H;IACD,mBAAmB,EAAE;QACnB,IAAI,EAAE,qBAAqB;QAC3B,QAAQ,EAAE,QAAQ;QAClB,OAAO,EAAE,8DAA8D;QACvE,YAAY,EAAE,CAAC,kBAAkB,EAAE,qCAAqC,CAAC;QACzE,cAAc,EAAE,CAAC,4CAA4C,EAAE,8DAA8D,CAAC;KAC/H;CACF,CAAC;AAEF,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAA8B,CAAC;IAClE,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1C,CAAC"}

package/dist/lib/errors/types.d.ts

@@ -0,0 +1,16 @@
+export declare class AppError extends Error {
+    readonly code: string;
+    readonly context: Record<string, unknown>;
+    constructor(message: string, code?: string, context?: Record<string, unknown>);
+    toJSON(): Record<string, unknown>;
+}
+export declare class NotFoundError extends AppError {
+    constructor(entity: string, identifier: string, context?: Record<string, unknown>);
+}
+export declare class CommandError extends AppError {
+    constructor(command: string, exitCode: number | null, stderr: string, context?: Record<string, unknown>);
+}
+export declare class ConfigError extends AppError {
+    constructor(filePath: string, cause: string, context?: Record<string, unknown>);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/errors/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/errors/types.ts"],"names":[],"mappings":"AAAA,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGxC,OAAO,EAAE,MAAM,EACf,IAAI,SAAc,EAClB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAQvC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQlC;AAED,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAQtF;AAED,qBAAa,YAAa,SAAQ,QAAQ;gBAC5B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAS5G;AAED,qBAAa,WAAY,SAAQ,QAAQ;gBAC3B,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAQnF"}

package/dist/lib/errors/types.js

@@ -0,0 +1,50 @@
+export class AppError extends Error {
+    code;
+    context;
+    constructor(message, code = 'APP_ERROR', context = {}) {
+        super(message);
+        this.name = 'AppError';
+        this.code = code;
+        this.context = context;
+    }
+    toJSON() {
+        return {
+            error: this.name,
+            code: this.code,
+            message: this.message,
+            context: this.context,
+        };
+    }
+}
+export class NotFoundError extends AppError {
+    constructor(entity, identifier, context = {}) {
+        super(`${entity} not found: ${identifier}`, 'NOT_FOUND_ERROR', {
+            entity,
+            identifier,
+            ...context,
+        });
+        this.name = 'NotFoundError';
+    }
+}
+export class CommandError extends AppError {
+    constructor(command, exitCode, stderr, context = {}) {
+        super(`Command failed: ${command}`, 'COMMAND_ERROR', {
+            command,
+            exitCode,
+            stderr,
+            ...context,
+        });
+        this.name = 'CommandError';
+    }
+}
+export class ConfigError extends AppError {
+    constructor(filePath, cause, context = {}) {
+        super(`Configuration error in ${filePath}: ${cause}`, 'CONFIG_ERROR', {
+            filePath,
+            cause,
+            ...context,
+        });
+        this.name = 'ConfigError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/lib/errors/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/errors/types.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAS;IACb,OAAO,CAA0B;IAE1C,YACE,OAAe,EACf,IAAI,GAAG,WAAW,EAClB,UAAmC,EAAE;QAErC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,MAAM;QACJ,OAAO;YACL,KAAK,EAAE,IAAI,CAAC,IAAI;YAChB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,aAAc,SAAQ,QAAQ;IACzC,YAAY,MAAc,EAAE,UAAkB,EAAE,UAAmC,EAAE;QACnF,KAAK,CAAC,GAAG,MAAM,eAAe,UAAU,EAAE,EAAE,iBAAiB,EAAE;YAC7D,MAAM;YACN,UAAU;YACV,GAAG,OAAO;SACX,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACxC,YAAY,OAAe,EAAE,QAAuB,EAAE,MAAc,EAAE,UAAmC,EAAE;QACzG,KAAK,CAAC,mBAAmB,OAAO,EAAE,EAAE,eAAe,EAAE;YACnD,OAAO;YACP,QAAQ;YACR,MAAM;YACN,GAAG,OAAO;SACX,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,QAAQ;IACvC,YAAY,QAAgB,EAAE,KAAa,EAAE,UAAmC,EAAE;QAChF,KAAK,CAAC,0BAA0B,QAAQ,KAAK,KAAK,EAAE,EAAE,cAAc,EAAE;YACpE,QAAQ;YACR,KAAK;YACL,GAAG,OAAO;SACX,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/dist/lib/index.d.ts

@@ -0,0 +1,29 @@
+export { AppError, NotFoundError, CommandError, ConfigError } from './errors/types.js';
+export { explainErrorCode, listKnownErrorCodes } from './errors/explain-error.js';
+export type { ErrorExplanation } from './errors/explain-error.js';
+export type { ManifestV2, ManifestTaskV2, RetryPolicy, VerifyProfileRegistry, VerifyProfile, VerifyStep, TaskResultV2, WriteEntry, Evidence, HealDecisionV2, HealPatch, HealRetryPolicy, ParserErrorCode, ParserFailure, FailureClass, } from './contracts/types.js';
+export { HEALABLE_FAILURE_CLASSES, NON_HEALABLE_FAILURE_CLASSES } from './contracts/types.js';
+export type { StateV2, RunPolicy, TaskStatus, TaskState, HistoryEntry, HealingRound, } from './state/types.js';
+export { DEFAULT_POLICY, FIBONACCI_BATCH_SEQUENCE } from './state/types.js';
+export type { PreparedInvocation, ExecutionArtifact, AdapterHealth, RunContext, CliAdapter, } from './adapters/types.js';
+export { parseTaskResult, parseHealDecision, parseTaskResultFromString, parseHealDecisionFromString, generateFailureSignature, isParserFailure, } from './parser/parser.js';
+export { loadState, writeState, initializeState, computeManifestDigest } from './state/state.js';
+export { validateManifestSchema, validateTaskResultSchema, validateHealDecisionSchema, validateStateSchema, validateVerifyProfileSchema, } from './contracts/schema-validator.js';
+export type { SchemaValidationResult, SchemaError } from './contracts/schema-validator.js';
+export { validateManifest } from './contracts/validate-manifest.js';
+export type { ValidateManifestOptions, ValidateManifestResult, Issue } from './contracts/validate-manifest.js';
+export { initState } from './state/init-state.js';
+export type { InitStateOptions, InitStateResult } from './state/init-state.js';
+export { getStatus } from './state/status.js';
+export type { StatusOptions, StatusResult, FailedTaskInfo } from './state/status.js';
+export { getLogs } from './state/logs.js';
+export type { LogsOptions, LogsResult, LogEntry } from './state/logs.js';
+export { parseResult } from './parser/parse-result.js';
+export type { ParseResultOptions, ParseResultResult } from './parser/parse-result.js';
+export { parseHeal } from './parser/parse-heal.js';
+export type { ParseHealOptions, ParseHealResult } from './parser/parse-heal.js';
+export { runDoctor } from './diagnostics/doctor.js';
+export type { DoctorOptions, DoctorResult, DoctorCheck, DoctorStatus } from './diagnostics/doctor.js';
+export { buildDependencyOrder, getReadyTasks, isTerminalStatus, isRunComplete, growBatchSize, shrinkBatchSize, computeEffectiveWindowSize, isHealableFailure, computeFailureRate, shouldHeal, checkConvergence, shouldEscalateTask, shouldAbortRun, validatePatch, validatePatchSet, validateWrites, } from './orchestrator/index.js';
+export type { SchedulingResult, BatchDecision, WindowOutcome, FailureRateResult, HealDecisionInput, ShouldHealResult, ConvergenceResult, EscalationResult, RunAbortResult, PatchValidationResult, WriteSafetyOptions, WriteSafetyResult, } from './orchestrator/index.js';
+//# sourceMappingURL=index.d.ts.map