@martinloop/mcp 0.2.0 → 0.2.7

package/dist/tools/run-store.d.ts

@@ -1,12 +1,44 @@
-import { type LoopRunRecord } from "../vendor/core/index.js";
+import { type LedgerEvent } from "../vendor/core/index.js";
+import type { InspectableLoopRecord } from "./tool-support.js";
 export interface InspectLoopSource {
     source: string;
-    loops: LoopRunRecord[];
+    loops: InspectableLoopRecord[];
+    warnings: string[];
 }
 export interface StatusLoopSource {
     source: string;
-    loop: LoopRunRecord;
+    loop: InspectableLoopRecord;
 }
+export interface DetailedLoopSource {
+    source: string;
+    sourceKind: "file" | "loop_id" | "latest" | "runs_root";
+    runsRoot: string;
+    loop: InspectableLoopRecord;
+    warnings: string[];
+    canonicalRunDirectory?: string;
+    canonicalLoopRecordPath?: string;
+    ledgerPath?: string;
+}
+export interface LoopListInput {
+    runsDir?: string;
+    limit?: number;
+    status?: string;
+    lifecycleState?: string;
+    adapterId?: string;
+    model?: string;
+    updatedAfter?: string;
+}
+export interface LoopListResult {
+    source: string;
+    runsRoot: string;
+    loops: InspectableLoopRecord[];
+    warnings: string[];
+}
+export type LedgerEventsWithDiagnostics = LedgerEvent[] & {
+    warnings?: string[];
+    unreadable?: boolean;
+    ledgerPath?: string;
+};
 export declare function loadLoopRecordsForInspect(input: {
     file?: string;
     runsDir?: string;
@@ -18,3 +50,25 @@ export declare function loadLoopRecordForStatus(input: {
     runsDir?: string;
     latest?: boolean;
 }): Promise<StatusLoopSource>;
+export declare function listLoopRecords(input: LoopListInput): Promise<LoopListResult>;
+export declare function loadDetailedLoopRecord(input: {
+    file?: string;
+    loopId?: string;
+    runsDir?: string;
+    latest?: boolean;
+}): Promise<DetailedLoopSource>;
+export declare function loadAttemptFromLoop(input: {
+    file?: string;
+    loopId?: string;
+    runsDir?: string;
+    attemptIndex?: number;
+}): Promise<{
+    detail: DetailedLoopSource;
+    attempt: InspectableLoopRecord["attempts"][number];
+}>;
+export declare function readLedgerEvents(detail: DetailedLoopSource): Promise<LedgerEventsWithDiagnostics>;
+export declare function readAttemptArtifactFiles(detail: DetailedLoopSource, attemptIndex: number): Promise<string[]>;
+export declare function readAllLoopRecordsSafely(runsRoot: string): Promise<{
+    loops: InspectableLoopRecord[];
+    warnings: string[];
+}>;

package/dist/tools/run-store.js

@@ -1,39 +1,43 @@
-import { stat } from "node:fs/promises";
+import { readFile, readdir, stat } from "node:fs/promises";
 import path from "node:path";
-import { readAllLoopRecords, readLatestLoopRecord, readLatestLoopRecordFromFile, readLoopRecordsFromFile, resolveRunsRoot } from "../vendor/core/index.js";
-import { resolveSafeLoopRecordPath, resolveSafeRunsPath, resolveSafeRunsRootPath } from "../server-validation.js";
+import { readLatestLoopRecordFromFile, readLoopRecordsFromFile, resolveRunsRoot } from "../vendor/core/index.js";
+import { resolveSafeLoopRecordPath, resolveSafeRunsJsonPath, resolveSafeRunsPath, resolveSafeRunsRootPath } from "../server-validation.js";
+import { attemptNotFoundError, invalidSelectorError, noLoopRecordsError, storeUnreadableError } from "./tool-errors.js";
 export async function loadLoopRecordsForInspect(input) {
     const runsRoot = resolveSafeRunsRootPath(input.runsDir, resolveRunsRoot(process.env));
     if (!input.file) {
+        const inspected = await readAllLoopRecordsSafely(runsRoot);
         return {
             source: runsRoot,
-            loops: await readAllLoopRecords(runsRoot)
+            loops: inspected.loops,
+            warnings: inspected.warnings
         };
     }
     const targetPath = resolveSafeRunsPath(input.file, runsRoot);
-    const targetStats = await stat(targetPath);
-    if (targetStats.isDirectory()) {
-        const canonicalLoopRecordPath = path.join(targetPath, "loop-record.json");
-        try {
-            const canonicalLoopRecordStats = await stat(canonicalLoopRecordPath);
-            if (canonicalLoopRecordStats.isFile()) {
+    const targetStats = await safeStat(targetPath);
+    if (targetStats?.isDirectory()) {
+        const canonicalLoopRecordPath = resolveInspectableLoopRecordPath(targetPath, runsRoot);
+        if (canonicalLoopRecordPath) {
+            const canonicalLoopRecordStats = await safeStat(canonicalLoopRecordPath);
+            if (canonicalLoopRecordStats?.isFile()) {
                 return {
                     source: canonicalLoopRecordPath,
-                    loops: await readLoopRecordsFromFile(canonicalLoopRecordPath)
+                    loops: await readRecordsFromFile(canonicalLoopRecordPath),
+                    warnings: []
                 };
             }
         }
-        catch {
-            // fall through to treating the directory as a full runs root
-        }
+        const inspected = await readAllLoopRecordsSafely(targetPath);
         return {
             source: targetPath,
-            loops: await readAllLoopRecords(targetPath)
+            loops: inspected.loops,
+            warnings: inspected.warnings
         };
     }
     return {
         source: targetPath,
-        loops: await readLoopRecordsFromFile(targetPath)
+        loops: await readRecordsFromFile(targetPath),
+        warnings: []
     };
 }
 export async function loadLoopRecordForStatus(input) {
@@ -43,67 +47,414 @@ export async function loadLoopRecordForStatus(input) {
             loop: JSON.parse(input.loopJson)
         };
     }
+    const detail = await loadDetailedLoopRecord(input);
+    return {
+        source: detail.source,
+        loop: detail.loop
+    };
+}
+export async function listLoopRecords(input) {
+    const runsRoot = resolveSafeRunsRootPath(input.runsDir, resolveRunsRoot(process.env));
+    const inspected = await readAllLoopRecordsSafely(runsRoot);
+    const warnings = [...inspected.warnings];
+    const updatedAfterTimestamp = input.updatedAfter !== undefined ? new Date(input.updatedAfter).getTime() : undefined;
+    if (input.updatedAfter !== undefined &&
+        (!Number.isFinite(updatedAfterTimestamp) || Number.isNaN(updatedAfterTimestamp))) {
+        throw invalidSelectorError("Invalid updatedAfter.", "Provide updatedAfter as an ISO-8601 timestamp.");
+    }
+    const loops = inspected.loops
+        .filter((loop) => {
+        if (input.status && loop.status !== input.status) {
+            return false;
+        }
+        if (input.lifecycleState && loop.lifecycleState !== input.lifecycleState) {
+            return false;
+        }
+        if (input.adapterId && !loop.attempts.some((attempt) => attempt.adapterId === input.adapterId)) {
+            return false;
+        }
+        if (input.model && !loop.attempts.some((attempt) => attempt.model === input.model)) {
+            return false;
+        }
+        if (updatedAfterTimestamp !== undefined) {
+            const loopTimestamp = new Date(loop.updatedAt ?? loop.createdAt ?? 0).getTime();
+            if (!Number.isFinite(loopTimestamp) || loopTimestamp <= updatedAfterTimestamp) {
+                return false;
+            }
+        }
+        return true;
+    })
+        .sort((left, right) => timestampForLoop(right) - timestampForLoop(left))
+        .slice(0, input.limit ?? 20);
+    if (loops.length === 0) {
+        warnings.push("No loop records matched the current filters.");
+    }
+    return {
+        source: runsRoot,
+        runsRoot,
+        loops,
+        warnings
+    };
+}
+export async function loadDetailedLoopRecord(input) {
     const runsRoot = resolveSafeRunsRootPath(input.runsDir, resolveRunsRoot(process.env));
+    const selectors = [
+        input.file !== undefined ? "file" : null,
+        input.loopId !== undefined ? "loopId" : null,
+        input.latest ? "latest" : null
+    ].filter((value) => value !== null);
+    if (selectors.length !== 1) {
+        throw invalidSelectorError("Provide exactly one of file, loopId, or latest.", "Choose exactly one run selector per call.");
+    }
     if (input.file) {
         const targetPath = resolveSafeRunsPath(input.file, runsRoot);
-        const targetStats = await stat(targetPath);
+        const targetStats = await safeStat(targetPath);
+        if (!targetStats) {
+            throw noLoopRecordsError();
+        }
         if (targetStats.isDirectory()) {
-            const canonicalLoopRecordPath = path.join(targetPath, "loop-record.json");
-            try {
-                const canonicalLoopRecordStats = await stat(canonicalLoopRecordPath);
-                if (canonicalLoopRecordStats.isFile()) {
-                    const loop = await readLatestLoopRecordFromFile(canonicalLoopRecordPath);
-                    if (!loop) {
-                        throw new Error("No loop records found.");
-                    }
-                    return {
+            const canonicalLoopRecordPath = resolveInspectableLoopRecordPath(targetPath, runsRoot);
+            if (canonicalLoopRecordPath) {
+                const canonicalStats = await safeStat(canonicalLoopRecordPath);
+                if (canonicalStats?.isFile()) {
+                    const loop = await readCanonicalLoopRecord(canonicalLoopRecordPath);
+                    return buildDetailedLoopSource({
                         source: canonicalLoopRecordPath,
-                        loop
-                    };
+                        sourceKind: "file",
+                        runsRoot,
+                        loop,
+                        canonicalLoopRecordPath,
+                        canonicalRunDirectory: path.dirname(canonicalLoopRecordPath)
+                    });
                 }
             }
-            catch {
-                // fall through to treating the directory as a full runs root
-            }
-            const loop = await readLatestLoopRecord(targetPath);
+            const inspected = await readAllLoopRecordsSafely(targetPath);
+            const loop = inspected.loops[0];
             if (!loop) {
-                throw new Error("No loop records found.");
+                throw noLoopRecordsError();
             }
-            return {
+            const detail = await buildDetailedLoopSourceFromDiscoveredLoop({
                 source: targetPath,
+                sourceKind: "runs_root",
+                runsRoot,
                 loop
+            });
+            return {
+                ...detail,
+                warnings: [...detail.warnings, ...inspected.warnings]
             };
         }
-        const loop = await readLatestLoopRecordFromFile(targetPath);
-        if (!loop) {
-            throw new Error("No loop records found.");
+        const latest = await readLatestLoopRecordFromFile(targetPath);
+        if (!latest) {
+            throw noLoopRecordsError();
         }
-        return {
+        if (path.basename(targetPath) === "loop-record.json") {
+            const loop = await readCanonicalLoopRecord(targetPath);
+            return buildDetailedLoopSource({
+                source: targetPath,
+                sourceKind: "file",
+                runsRoot,
+                loop,
+                canonicalLoopRecordPath: targetPath,
+                canonicalRunDirectory: path.dirname(targetPath)
+            });
+        }
+        return await buildDetailedLoopSourceFromDiscoveredLoop({
             source: targetPath,
-            loop
-        };
+            sourceKind: "file",
+            runsRoot,
+            loop: latest
+        });
     }
     if (input.loopId) {
-        const targetPath = resolveSafeLoopRecordPath(input.loopId, runsRoot);
-        const loop = await readLatestLoopRecordFromFile(targetPath);
+        const canonicalLoopRecordPath = resolvePotentialLoopRecordPath(input.loopId, runsRoot);
+        const canonicalStats = await safeStat(canonicalLoopRecordPath);
+        if (canonicalStats?.isFile()) {
+            const loop = await readCanonicalLoopRecord(canonicalLoopRecordPath);
+            return buildDetailedLoopSource({
+                source: canonicalLoopRecordPath,
+                sourceKind: "loop_id",
+                runsRoot,
+                loop,
+                canonicalLoopRecordPath,
+                canonicalRunDirectory: path.dirname(canonicalLoopRecordPath)
+            });
+        }
+        const inspected = await readAllLoopRecordsSafely(runsRoot);
+        const loop = inspected.loops.find((candidate) => candidate.loopId === input.loopId);
         if (!loop) {
-            throw new Error("No loop records found.");
+            throw noLoopRecordsError();
         }
-        return {
-            source: targetPath,
+        const detail = await buildDetailedLoopSourceFromDiscoveredLoop({
+            source: runsRoot,
+            sourceKind: "loop_id",
+            runsRoot,
             loop
+        });
+        return {
+            ...detail,
+            warnings: [...detail.warnings, ...inspected.warnings]
         };
     }
-    if (input.latest) {
-        const loop = await readLatestLoopRecord(runsRoot);
-        if (!loop) {
-            throw new Error("No loop records found.");
+    const inspected = await readAllLoopRecordsSafely(runsRoot);
+    const loop = inspected.loops[0];
+    if (!loop) {
+        throw noLoopRecordsError();
+    }
+    const detail = await buildDetailedLoopSourceFromDiscoveredLoop({
+        source: runsRoot,
+        sourceKind: "latest",
+        runsRoot,
+        loop
+    });
+    return {
+        ...detail,
+        warnings: [...detail.warnings, ...inspected.warnings]
+    };
+}
+export async function loadAttemptFromLoop(input) {
+    const detail = await loadDetailedLoopRecord(input);
+    const attempt = input.attemptIndex !== undefined
+        ? detail.loop.attempts.find((candidate) => candidate.index === input.attemptIndex)
+        : detail.loop.attempts.at(-1);
+    if (!attempt) {
+        throw attemptNotFoundError(input.attemptIndex ?? detail.loop.attempts.length);
+    }
+    return {
+        detail,
+        attempt
+    };
+}
+export async function readLedgerEvents(detail) {
+    const requestedLedgerPath = detail.ledgerPath ??
+        (detail.canonicalRunDirectory ? path.join(detail.canonicalRunDirectory, "ledger.jsonl") : undefined);
+    if (!requestedLedgerPath) {
+        return withLedgerDiagnostics([]);
+    }
+    try {
+        const ledgerPath = resolveInspectableLedgerPath(requestedLedgerPath, detail.runsRoot);
+        const ledgerStats = await safeStat(ledgerPath);
+        if (!ledgerStats?.isFile()) {
+            return withLedgerDiagnostics([], { ledgerPath });
         }
+        const text = await readFile(ledgerPath, "utf8");
+        const events = text
+            .split(/\r?\n/u)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+        return withLedgerDiagnostics(events, { ledgerPath });
+    }
+    catch {
+        return withLedgerDiagnostics([], {
+            unreadable: true,
+            warnings: [
+                `Verification ledger for '${detail.loop.loopId}' is unreadable; ledger verification evidence is unavailable.`
+            ]
+        });
+    }
+}
+export async function readAttemptArtifactFiles(detail, attemptIndex) {
+    if (!detail.canonicalRunDirectory) {
+        return [];
+    }
+    const directory = path.join(detail.canonicalRunDirectory, "artifacts", `attempt-${String(attemptIndex).padStart(3, "0")}`);
+    try {
+        const entries = await readdir(directory, { withFileTypes: true });
+        return entries.filter((entry) => entry.isFile()).map((entry) => entry.name).sort();
+    }
+    catch {
+        return [];
+    }
+}
+export async function readAllLoopRecordsSafely(runsRoot) {
+    let entries;
+    try {
+        entries = await readdir(runsRoot, { withFileTypes: true });
+    }
+    catch {
         return {
-            source: runsRoot,
-            loop
+            loops: [],
+            warnings: [
+                "Configured Martin runs root is missing or unreadable; no loop records could be inspected."
+            ]
         };
     }
-    throw new Error("Provide exactly one of loopJson, file, loopId, or latest.");
+    const loops = [];
+    const warnings = [];
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            const canonicalLoopRecordPath = resolveInspectableLoopRecordPath(path.join(runsRoot, entry.name), runsRoot);
+            if (!canonicalLoopRecordPath) {
+                continue;
+            }
+            const canonicalStats = await safeStat(canonicalLoopRecordPath);
+            if (!canonicalStats?.isFile()) {
+                continue;
+            }
+            try {
+                loops.push(await readCanonicalLoopRecord(canonicalLoopRecordPath));
+            }
+            catch {
+                warnings.push(`Skipped unreadable loop record for '${entry.name}'.`);
+            }
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        const extension = path.extname(entry.name).toLowerCase();
+        if (extension !== ".json" && extension !== ".jsonl") {
+            continue;
+        }
+        const filePath = path.join(runsRoot, entry.name);
+        try {
+            loops.push(...(await readRecordsFromFile(resolveSafeRunsJsonPath(entry.name, runsRoot))));
+        }
+        catch {
+            warnings.push(`Skipped unreadable run file '${entry.name}'.`);
+        }
+    }
+    loops.sort((left, right) => timestampForLoop(right) - timestampForLoop(left));
+    return {
+        loops,
+        warnings
+    };
+}
+async function buildDetailedLoopSourceFromDiscoveredLoop(input) {
+    let canonicalLoopRecordPath;
+    try {
+        canonicalLoopRecordPath = resolveSafeLoopRecordPath(input.loop.loopId, input.runsRoot);
+    }
+    catch {
+        canonicalLoopRecordPath = undefined;
+    }
+    const canonicalStats = canonicalLoopRecordPath ? await safeStat(canonicalLoopRecordPath) : undefined;
+    if (canonicalLoopRecordPath && canonicalStats?.isFile()) {
+        const canonicalLoop = await readCanonicalLoopRecord(canonicalLoopRecordPath);
+        return buildDetailedLoopSource({
+            source: input.source,
+            sourceKind: input.sourceKind,
+            runsRoot: input.runsRoot,
+            loop: canonicalLoop,
+            canonicalLoopRecordPath,
+            canonicalRunDirectory: path.dirname(canonicalLoopRecordPath)
+        });
+    }
+    return buildDetailedLoopSource({
+        source: input.source,
+        sourceKind: input.sourceKind,
+        runsRoot: input.runsRoot,
+        loop: input.loop,
+        warnings: [
+            `Canonical run directory for ${input.loop.loopId} is not available; dossier data may be partial.`
+        ]
+    });
+}
+function buildDetailedLoopSource(input) {
+    return {
+        source: input.source,
+        sourceKind: input.sourceKind,
+        runsRoot: input.runsRoot,
+        loop: input.loop,
+        warnings: input.warnings ?? [],
+        ...(input.canonicalRunDirectory ? { canonicalRunDirectory: input.canonicalRunDirectory } : {}),
+        ...(input.canonicalLoopRecordPath ? { canonicalLoopRecordPath: input.canonicalLoopRecordPath } : {}),
+        ...(input.canonicalRunDirectory
+            ? { ledgerPath: path.join(input.canonicalRunDirectory, "ledger.jsonl") }
+            : {})
+    };
+}
+async function readCanonicalLoopRecord(file) {
+    try {
+        const text = await readFile(file, "utf8");
+        return validateInspectableLoopRecord(JSON.parse(text));
+    }
+    catch {
+        throw storeUnreadableError();
+    }
+}
+async function readRecordsFromFile(file) {
+    try {
+        return (await readLoopRecordsFromFile(file)).map((loop) => validateInspectableLoopRecord(loop));
+    }
+    catch {
+        throw storeUnreadableError();
+    }
+}
+async function safeStat(targetPath) {
+    try {
+        return await stat(targetPath);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveInspectableLoopRecordPath(runDirectory, runsRoot) {
+    try {
+        const relativeLoopRecordPath = path.relative(runsRoot, path.join(runDirectory, "loop-record.json"));
+        return resolveSafeRunsJsonPath(relativeLoopRecordPath, runsRoot);
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolvePotentialLoopRecordPath(loopId, runsRoot) {
+    try {
+        return resolveSafeLoopRecordPath(loopId, runsRoot);
+    }
+    catch (error) {
+        if (!/^[A-Za-z0-9._-]+$/u.test(loopId)) {
+            throw error;
+        }
+        return path.join(runsRoot, loopId, "loop-record.json");
+    }
+}
+function resolveInspectableLedgerPath(ledgerPath, runsRoot) {
+    const relativeLedgerPath = path.relative(runsRoot, ledgerPath);
+    return resolveSafeRunsJsonPath(relativeLedgerPath, runsRoot);
+}
+function timestampForLoop(loop) {
+    const timestamp = new Date(loop.updatedAt ?? loop.createdAt ?? 0).getTime();
+    return Number.isFinite(timestamp) ? timestamp : 0;
+}
+function withLedgerDiagnostics(events, diagnostics = {}) {
+    return Object.assign(events, diagnostics);
+}
+function validateInspectableLoopRecord(value) {
+    if (!isRecord(value)) {
+        throw storeUnreadableError();
+    }
+    const budget = value["budget"];
+    const cost = value["cost"];
+    const attempts = value["attempts"];
+    if (typeof value["loopId"] !== "string" ||
+        !/^[A-Za-z0-9._-]+$/u.test(value["loopId"]) ||
+        typeof value["status"] !== "string" ||
+        typeof value["lifecycleState"] !== "string" ||
+        !isRecord(budget) ||
+        !isFiniteNumber(budget["maxUsd"]) ||
+        !isFiniteNumber(budget["softLimitUsd"]) ||
+        !Number.isInteger(budget["maxIterations"]) ||
+        !Number.isInteger(budget["maxTokens"]) ||
+        !isRecord(cost) ||
+        !isFiniteNumber(cost["actualUsd"]) ||
+        !isFiniteNumber(cost["tokensIn"]) ||
+        !isFiniteNumber(cost["tokensOut"]) ||
+        (cost["avoidedUsd"] !== undefined && !isFiniteNumber(cost["avoidedUsd"])) ||
+        !Array.isArray(attempts) ||
+        !attempts.every(isRecord) ||
+        (value["events"] !== undefined &&
+            (!Array.isArray(value["events"]) || !value["events"].every(isRecord))) ||
+        (value["artifacts"] !== undefined &&
+            (!Array.isArray(value["artifacts"]) || !value["artifacts"].every(isRecord)))) {
+        throw storeUnreadableError();
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
 }
-//# sourceMappingURL=run-store.js.map

package/dist/tools/tool-errors.d.ts

@@ -0,0 +1,37 @@
+import type { MartinErrorCategory } from "../vendor/contracts/index.js";
+export type ToolFailureCode = "attempt_not_found" | "engine_unavailable" | "invalid_arguments" | "invalid_json" | "invalid_path" | "invalid_selector" | "no_loop_records" | "policy_blocked" | "store_unreadable" | "tool_execution_failed" | "unknown_tool" | "unsupported_operation";
+export type ToolFailureCategory = MartinErrorCategory;
+export interface ToolFailure {
+    code: ToolFailureCode;
+    category: ToolFailureCategory;
+    message: string;
+    suggestion?: string;
+    retryable: boolean;
+    details?: Record<string, unknown>;
+}
+export interface MartinToolErrorOptions {
+    category?: ToolFailureCategory;
+    suggestion?: string;
+    retryable?: boolean;
+    exposeMessage?: boolean;
+    details?: Record<string, unknown>;
+}
+export declare class MartinToolError extends Error {
+    readonly code: ToolFailureCode;
+    readonly category: ToolFailureCategory;
+    readonly suggestion?: string;
+    readonly retryable: boolean;
+    readonly exposeMessage: boolean;
+    readonly details?: Record<string, unknown>;
+    constructor(code: ToolFailureCode, message: string, options?: MartinToolErrorOptions);
+}
+export declare function sanitizePotentiallySensitiveMessage(message: string): string;
+export declare function sanitizeToolErrorMessage(error: unknown): string;
+export declare function toToolFailure(error: unknown): ToolFailure;
+export declare function invalidArgumentsError(message: string, suggestion?: string): MartinToolError;
+export declare function invalidPathError(message: string, suggestion?: string): MartinToolError;
+export declare function invalidSelectorError(message: string, suggestion?: string): MartinToolError;
+export declare function noLoopRecordsError(message?: string): MartinToolError;
+export declare function attemptNotFoundError(attemptIndex: number): MartinToolError;
+export declare function storeUnreadableError(message?: string): MartinToolError;
+export declare function unsupportedOperationError(message: string, suggestion?: string): MartinToolError;