@martinloop/mcp 0.2.0 → 0.2.5

package/dist/tools/tool-errors.js

@@ -0,0 +1,170 @@
+export class MartinToolError extends Error {
+    code;
+    category;
+    suggestion;
+    retryable;
+    exposeMessage;
+    details;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = "MartinToolError";
+        this.code = code;
+        this.category = options.category ?? "transient";
+        this.suggestion = options.suggestion;
+        this.retryable = options.retryable ?? false;
+        this.exposeMessage = options.exposeMessage ?? true;
+        this.details = options.details;
+    }
+}
+const SENSITIVE_MESSAGE_PATTERN = /([A-Za-z]:\\|\/|policy\.rego|policy\.wasm|\.pem|\.env)/u;
+export function sanitizePotentiallySensitiveMessage(message) {
+    return SENSITIVE_MESSAGE_PATTERN.test(message) ? "Tool execution failed." : message;
+}
+export function sanitizeToolErrorMessage(error) {
+    if (error instanceof MartinToolError) {
+        return error.exposeMessage
+            ? sanitizePotentiallySensitiveMessage(error.message)
+            : "Tool execution failed.";
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return sanitizePotentiallySensitiveMessage(message);
+}
+export function toToolFailure(error) {
+    if (error instanceof MartinToolError) {
+        return {
+            code: error.code,
+            category: error.category,
+            message: sanitizeToolErrorMessage(error),
+            ...(error.suggestion ? { suggestion: error.suggestion } : {}),
+            retryable: error.retryable,
+            ...(error.details ? { details: error.details } : {})
+        };
+    }
+    const rawMessage = error instanceof Error ? error.message : String(error);
+    const message = sanitizeToolErrorMessage(error);
+    if (error instanceof SyntaxError || /JSON/u.test(rawMessage)) {
+        return {
+            code: "invalid_json",
+            category: "invalid_input",
+            message,
+            suggestion: "Provide a valid JSON-serialized LoopRecord.",
+            retryable: false
+        };
+    }
+    if (/No loop records found\./u.test(rawMessage)) {
+        return {
+            code: "no_loop_records",
+            category: "not_found",
+            message: "No loop records found.",
+            suggestion: "Run martin_run first or point file, loopId, or runsDir at a populated Martin runs location.",
+            retryable: false
+        };
+    }
+    if (/Attempt .* not found\./u.test(rawMessage)) {
+        return {
+            code: "attempt_not_found",
+            category: "not_found",
+            message,
+            suggestion: "Choose a valid attemptIndex for the selected Martin run.",
+            retryable: false
+        };
+    }
+    if (/Provide exactly one/u.test(rawMessage)) {
+        return {
+            code: "invalid_selector",
+            category: "invalid_input",
+            message,
+            suggestion: "Choose exactly one selector: loopJson, file, loopId, or latest.",
+            retryable: false
+        };
+    }
+    if (/Unknown tool/u.test(rawMessage)) {
+        return {
+            code: "unknown_tool",
+            category: "invalid_input",
+            message,
+            suggestion: "Refresh the tool list and call one of the advertised Martin tools.",
+            retryable: false
+        };
+    }
+    if (/is not available on PATH/u.test(rawMessage)) {
+        return {
+            code: "engine_unavailable",
+            category: "environment",
+            message,
+            suggestion: "Install the requested CLI or set MARTIN_LIVE=false for stub execution.",
+            retryable: false
+        };
+    }
+    if (/Unknown arguments/u.test(rawMessage) ||
+        /Tool arguments must be an object\./u.test(rawMessage) ||
+        /^Invalid /u.test(rawMessage)) {
+        return {
+            code: /Invalid (allowedPaths|deniedPaths|file|loopId|runsDir|workingDirectory)\./u.test(rawMessage)
+                ? "invalid_path"
+                : "invalid_arguments",
+            category: "invalid_input",
+            message,
+            suggestion: "Check the tool schema and resend only supported, in-scope values.",
+            retryable: false
+        };
+    }
+    if (/Unable to read Martin runs store\./u.test(rawMessage)) {
+        return {
+            code: "store_unreadable",
+            category: "store_unreadable",
+            message,
+            suggestion: "Check runsDir permissions and confirm the selected Martin run store is readable.",
+            retryable: false
+        };
+    }
+    return {
+        code: "tool_execution_failed",
+        category: "transient",
+        message,
+        suggestion: "Review the tool inputs and environment, then retry when the underlying issue is fixed.",
+        retryable: true
+    };
+}
+export function invalidArgumentsError(message, suggestion) {
+    return new MartinToolError("invalid_arguments", message, {
+        category: "invalid_input",
+        suggestion
+    });
+}
+export function invalidPathError(message, suggestion) {
+    return new MartinToolError("invalid_path", message, {
+        category: "invalid_input",
+        suggestion
+    });
+}
+export function invalidSelectorError(message, suggestion) {
+    return new MartinToolError("invalid_selector", message, {
+        category: "invalid_input",
+        suggestion
+    });
+}
+export function noLoopRecordsError(message = "No loop records found.") {
+    return new MartinToolError("no_loop_records", message, {
+        category: "not_found",
+        suggestion: "Run martin_run first or point file, loopId, or runsDir at a populated Martin runs location."
+    });
+}
+export function attemptNotFoundError(attemptIndex) {
+    return new MartinToolError("attempt_not_found", `Attempt ${attemptIndex} not found.`, {
+        category: "not_found",
+        suggestion: "Choose an attemptIndex that exists in the selected Martin run."
+    });
+}
+export function storeUnreadableError(message = "Unable to read Martin runs store.") {
+    return new MartinToolError("store_unreadable", message, {
+        category: "store_unreadable",
+        suggestion: "Check runsDir permissions and confirm the selected Martin run store is readable."
+    });
+}
+export function unsupportedOperationError(message, suggestion) {
+    return new MartinToolError("unsupported_operation", message, {
+        category: "invalid_input",
+        suggestion
+    });
+}

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

@@ -0,0 +1,16 @@
+import type { ToolFailure } from "./tool-errors.js";
+interface TextContentBlock {
+    type: "text";
+    text: string;
+}
+export declare function createToolSuccessResult<T extends object>(output: T, summary: string): {
+    content: TextContentBlock[];
+    structuredContent: T;
+    _meta: Record<string, unknown>;
+};
+export declare function createToolErrorResult(failure: ToolFailure): {
+    content: TextContentBlock[];
+    isError: true;
+    _meta: Record<string, unknown>;
+};
+export {};

package/dist/tools/tool-response.js

@@ -0,0 +1,34 @@
+function createJsonBlock(output) {
+    return {
+        type: "text",
+        text: JSON.stringify(output, null, 2)
+    };
+}
+export function createToolSuccessResult(output, summary) {
+    return {
+        content: [createJsonBlock(output), { type: "text", text: summary }],
+        structuredContent: output,
+        _meta: {
+            "martinloop/summary": summary,
+            "martinloop/contentVersion": "2026-05-15"
+        }
+    };
+}
+export function createToolErrorResult(failure) {
+    const content = [
+        { type: "text", text: `Tool error: ${failure.message}` }
+    ];
+    if (failure.suggestion) {
+        content.push({ type: "text", text: `Suggestion: ${failure.suggestion}` });
+    }
+    return {
+        content,
+        isError: true,
+        _meta: {
+            "martinloop/error": failure,
+            "martinloop/errorCode": failure.code,
+            "martinloop/errorCategory": failure.category,
+            "martinloop/retryable": failure.retryable
+        }
+    };
+}

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

@@ -1,4 +1,17 @@
+import type { LoopArtifact, LoopBudget, LoopCost, LoopEvent, LoopTask } from "../vendor/contracts/index.js";
+import { type LedgerEvent, type LoopAttemptRecord, type LoopRunRecord } from "../vendor/core/index.js";
 export type MartinEngine = "claude" | "codex";
+export interface InspectableLoopAttempt extends LoopAttemptRecord {
+    attemptId?: string;
+    summary?: string;
+}
+export interface InspectableLoopRecord extends Omit<LoopRunRecord, "attempts" | "task"> {
+    attempts: InspectableLoopAttempt[];
+    task?: LoopTask;
+    artifacts?: LoopArtifact[];
+    events?: LoopEvent[];
+    metadata?: Record<string, string>;
+}
 export interface LoopPreview {
     loopId: string;
     title: string;
@@ -15,23 +28,100 @@ export interface LoopPreview {
     remainingBudgetUsd: number;
     remainingIterations: number;
     remainingTokens: number;
+    lastAttempt?: AttemptSummary;
+}
+export interface AttemptArtifactFiles {
+    directory: string;
+    available: boolean;
+    files: string[];
+}
+export interface AttemptSummary {
+    index: number;
+    attemptId?: string;
+    adapterId?: string;
+    model?: string;
+    failureClass?: string;
+    intervention?: string;
+    startedAt?: string;
+    completedAt?: string;
+    summary?: string;
+    artifacts?: AttemptArtifactFiles;
+}
+export interface ArtifactSummary {
+    totalCount: number;
+    kinds: Record<string, number>;
+    highlights: Array<{
+        artifactId: string;
+        kind: string;
+        label: string;
+        uri: string;
+    }>;
+}
+export interface VerificationSummary {
+    status: "passed" | "failed" | "unavailable";
+    eventCount: number;
+    ledgerEventCount: number;
+    latestAttemptIndex?: number;
+    completedAt?: string;
+    summary?: string;
+    warnings: string[];
+}
+export interface RunWarningEnvelope {
+    warnings: string[];
+}
+export interface EventSummary {
+    type: string;
+    timestamp?: string;
+    lifecycleState?: string;
+    payload: Record<string, unknown>;
+}
+export interface LoopCollectionSummary {
+    latestRun?: LoopPreview;
+    recentRuns: LoopPreview[];
+    statusBreakdown: Record<string, number>;
+    lifecycleBreakdown: Record<string, number>;
 }
 export interface CliAvailability {
+    command: string;
     available: boolean;
+    locator: string;
     detail: string;
     resolvedPath?: string;
 }
 export interface ExecutionMode {
     liveMode: boolean;
     mode: "live" | "stub";
+    detail: string;
 }
-export interface RunStoreInspection {
+export interface RunStoreInspection extends LoopCollectionSummary {
+    runsRoot: string;
     exists: boolean;
     loopCount: number;
-    latestRun?: LoopPreview;
     warnings: string[];
 }
+export interface CanonicalRunPaths {
+    runsRoot: string;
+    runDirectory: string;
+    loopRecordPath: string;
+    ledgerPath: string;
+}
 export declare function resolveExecutionMode(): ExecutionMode;
+export declare function detectCliAvailability(command: string): CliAvailability;
 export declare function getEngineAvailability(engine: MartinEngine): CliAvailability;
 export declare function formatUsd(value: number): string;
+export declare function buildLoopPreview(loop: InspectableLoopRecord): LoopPreview;
+export declare function buildAttemptSummary(attempt: InspectableLoopAttempt, artifacts?: AttemptArtifactFiles): AttemptSummary;
+export declare function buildArtifactSummary(loop: InspectableLoopRecord): ArtifactSummary;
+export declare function buildVerificationSummary(loop: InspectableLoopRecord, ledgerEvents?: LedgerEvent[]): VerificationSummary;
+export declare function buildEventSummaries(loop: InspectableLoopRecord, limit?: number): EventSummary[];
+export declare function buildLoopCollectionSummary(loops: Array<LoopRunRecord | InspectableLoopRecord>): LoopCollectionSummary;
 export declare function inspectRunsRoot(runsRoot?: string): Promise<RunStoreInspection>;
+export declare function buildRunRecordPaths(runsRoot: string, loopId: string): CanonicalRunPaths;
+export declare function buildAttemptArtifactDirectory(runsRoot: string, loopId: string, attemptIndex: number): string;
+export declare function buildAttemptArtifactsReference(runsRoot: string, loopId: string, attemptIndex: number): Promise<AttemptArtifactFiles>;
+export declare function buildCostSnapshot(cost: Pick<LoopCost, "actualUsd" | "tokensIn" | "tokensOut"> & {
+    avoidedUsd?: number;
+}): LoopCost;
+export declare function buildBudgetSnapshot(budget: LoopBudget): LoopBudget;
+export declare function buildSuggestedResourceUris(loopId: string): string[];
+export declare function buildSuggestedPromptNames(): string[];