mrmainspring 0.1.0

package/dist/mcp/memoryTools.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { jsonResult } from "./jsonResult.js";
+import { memoryTypes } from "../memory/types.js";
+const memoryTypeSchema = z.enum(memoryTypes);
+const jsonBodySchema = z.record(z.string(), z.unknown());
+export function registerMemoryTools(server, memoryService) {
+    server.registerTool("memory.write", {
+        title: "Write Memory",
+        description: "Store a Mr Mainspring agent memory and compute its deterministic content hash.",
+        inputSchema: {
+            agent_id: z.string().min(1),
+            type: memoryTypeSchema,
+            body: jsonBodySchema,
+            source: jsonBodySchema.optional(),
+            anchor: z.boolean().optional(),
+            memory_id: z.string().min(1).optional(),
+            prev_anchor_hash: z.string().min(1).nullable().optional()
+        }
+    }, async (input) => {
+        const memory = await memoryService.write(input);
+        return jsonResult({
+            memory_id: memory.memory_id,
+            content_hash: memory.content_hash,
+            metadata_hash: memory.metadata_hash,
+            anchor_status: memory.anchor_status,
+            created_at: memory.created_at
+        });
+    });
+    server.registerTool("memory.read", {
+        title: "Read Memory",
+        description: "Read one stored Mr Mainspring memory by agent and memory id.",
+        inputSchema: {
+            agent_id: z.string().min(1),
+            memory_id: z.string().min(1)
+        }
+    }, async ({ agent_id, memory_id }) => {
+        const memory = await memoryService.read(agent_id, memory_id);
+        if (!memory) {
+            return jsonResult({
+                found: false,
+                agent_id,
+                memory_id
+            });
+        }
+        return jsonResult({
+            found: true,
+            memory
+        });
+    });
+    server.registerTool("memory.search", {
+        title: "Search Memory",
+        description: "Search stored Mr Mainspring memories for an agent.",
+        inputSchema: {
+            agent_id: z.string().min(1),
+            query: z.string().default(""),
+            limit: z.number().int().min(1).max(50).optional()
+        }
+    }, async ({ agent_id, query, limit }) => {
+        const result = await memoryService.search(agent_id, query, limit);
+        return jsonResult(result);
+    });
+    server.registerTool("memory.verify", {
+        title: "Verify Memory",
+        description: "Recompute a local memory hash and report whether it still matches the stored hash.",
+        inputSchema: {
+            agent_id: z.string().min(1),
+            memory_id: z.string().min(1)
+        }
+    }, async ({ agent_id, memory_id }) => {
+        const verification = await memoryService.verify(agent_id, memory_id);
+        return jsonResult(verification);
+    });
+}

package/dist/mcp/paymentTools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { PaymentService } from "../payments/service.js";
+export declare function registerPaymentTools(server: McpServer, paymentService: PaymentService): void;

package/dist/mcp/paymentTools.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { jsonResult } from "./jsonResult.js";
+const nonEmptyStringSchema = z.string().trim().min(1);
+const urlSchema = z.string().trim().url();
+const decimalAmountSchema = z
+    .string()
+    .trim()
+    .regex(/^\d+(\.\d+)?$/, "Expected a non-negative decimal amount");
+export function registerPaymentTools(server, paymentService) {
+    server.registerTool("payment.fetch", {
+        title: "x402 Payment Fetch",
+        description: "Create a durable x402 payment record after checking a Grimoire policy. With request_challenge=true, make the first x402 HTTP request, persist and approve 402 requirements, then either persist a disabled/failed receipt or, when real settlement is configured, retry the paid resource with PAYMENT-SIGNATURE and return verified settlement without exposing signed payloads.",
+        inputSchema: {
+            agent_id: nonEmptyStringSchema,
+            policy_id: nonEmptyStringSchema,
+            method: nonEmptyStringSchema.default("GET"),
+            url: urlSchema,
+            expected_amount: decimalAmountSchema.optional(),
+            idempotency_key: nonEmptyStringSchema.optional(),
+            request_challenge: z.boolean().optional().default(false)
+        }
+    }, async (input) => {
+        const result = await paymentService.fetch(input);
+        return jsonResult(result);
+    });
+    server.registerTool("payment.receipt", {
+        title: "Read Payment Receipt",
+        description: "Return the persisted Mr Mainspring payment intent and receipt metadata. Signed payloads and secrets are never returned.",
+        inputSchema: {
+            payment_id: nonEmptyStringSchema
+        }
+    }, async ({ payment_id }) => jsonResult(await paymentService.receipt(payment_id)));
+}

package/dist/memory/canonical.d.ts

@@ -0,0 +1,4 @@
+import type { JsonObject, JsonValue } from "./types.js";
+export declare function toJsonValue(value: unknown, path?: string): JsonValue;
+export declare function toJsonObject(value: unknown, path?: string): JsonObject;
+export declare function canonicalizeJson(value: unknown): string;

package/dist/memory/canonical.js

@@ -0,0 +1,49 @@
+export function toJsonValue(value, path = "$") {
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error(`Non-finite number at ${path}`);
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => toJsonValue(item, `${path}[${index}]`));
+    }
+    if (typeof value === "object") {
+        const objectValue = value;
+        const output = {};
+        for (const [key, item] of Object.entries(objectValue)) {
+            if (item === undefined) {
+                continue;
+            }
+            output[key] = toJsonValue(item, `${path}.${key}`);
+        }
+        return output;
+    }
+    throw new Error(`Unsupported JSON value at ${path}`);
+}
+export function toJsonObject(value, path = "$") {
+    const json = toJsonValue(value, path);
+    if (json === null || Array.isArray(json) || typeof json !== "object") {
+        throw new Error(`Expected JSON object at ${path}`);
+    }
+    return json;
+}
+export function canonicalizeJson(value) {
+    return JSON.stringify(sortJsonValue(toJsonValue(value)));
+}
+function sortJsonValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortJsonValue);
+    }
+    if (value !== null && typeof value === "object") {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = sortJsonValue(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}

package/dist/memory/hash.d.ts

@@ -0,0 +1 @@
+export declare function sha256Hex(input: string): string;

package/dist/memory/hash.js

@@ -0,0 +1,4 @@
+import { createHash } from "node:crypto";
+export function sha256Hex(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}

package/dist/memory/service.d.ts

@@ -0,0 +1,37 @@
+import type { AuditService } from "../audit/service.js";
+import { type CasperAnchorClient } from "../casper/anchorClient.js";
+import type { MemorySearchResult, MemoryStore, StoredMemoryEntry, WriteMemoryInput } from "./types.js";
+export declare class MemoryService {
+    private readonly store;
+    private readonly audit?;
+    private readonly anchorClient?;
+    constructor(store: MemoryStore, audit?: AuditService | undefined, anchorClient?: CasperAnchorClient | undefined);
+    write(input: WriteMemoryInput): Promise<StoredMemoryEntry>;
+    read(agentId: string, memoryId: string): Promise<StoredMemoryEntry | null>;
+    search(agentId: string, query: string, limit?: number): Promise<MemorySearchResult>;
+    verify(agentId: string, memoryId: string): Promise<{
+        valid: boolean;
+        reason: string;
+        agent_id: string;
+        memory_id: string;
+        local_valid?: undefined;
+        anchor_status?: undefined;
+        local_content_hash?: undefined;
+        stored_content_hash?: undefined;
+        onchain_content_hash?: undefined;
+        anchor_id?: undefined;
+        casper_transaction_hash?: undefined;
+    } | {
+        valid: boolean;
+        local_valid: boolean;
+        anchor_status: import("./types.js").AnchorStatus;
+        agent_id: string;
+        memory_id: string;
+        local_content_hash: string;
+        stored_content_hash: string;
+        onchain_content_hash: string | null;
+        anchor_id: string | null;
+        casper_transaction_hash: string | null;
+        reason?: undefined;
+    }>;
+}

package/dist/memory/service.js

@@ -0,0 +1,175 @@
+import { randomUUID } from "node:crypto";
+import { createAnchorSubmission, createPendingAnchorResult } from "../casper/anchorClient.js";
+import { canonicalizeJson, toJsonObject } from "./canonical.js";
+import { sha256Hex } from "./hash.js";
+const MEMORY_SCHEMA_VERSION = "sigil.memory.v1";
+export class MemoryService {
+    store;
+    audit;
+    anchorClient;
+    constructor(store, audit, anchorClient) {
+        this.store = store;
+        this.audit = audit;
+        this.anchorClient = anchorClient;
+    }
+    async write(input) {
+        const memoryId = input.memory_id ?? createMemoryId();
+        const createdAt = new Date().toISOString();
+        const source = toJsonObject(input.source ?? {}, "source");
+        const body = toJsonObject(input.body, "body");
+        const envelope = {
+            schema_version: MEMORY_SCHEMA_VERSION,
+            agent_id: input.agent_id,
+            memory_id: memoryId,
+            type: input.type,
+            source,
+            body,
+            created_at: createdAt,
+            prev_anchor_hash: input.prev_anchor_hash ?? null
+        };
+        const canonicalJson = canonicalizeJson(envelope);
+        const contentHash = sha256Hex(canonicalJson);
+        const metadataHash = sha256Hex(canonicalizeJson({
+            agent_id: envelope.agent_id,
+            memory_id: envelope.memory_id,
+            type: envelope.type,
+            source: envelope.source,
+            created_at: envelope.created_at
+        }));
+        let anchorSubmission = null;
+        let anchorResult = null;
+        if (input.anchor) {
+            anchorSubmission = createAnchorSubmission({
+                agent_id: envelope.agent_id,
+                memory_id: envelope.memory_id,
+                content_hash: contentHash,
+                metadata_hash: metadataHash,
+                prev_anchor_hash: envelope.prev_anchor_hash
+            });
+            anchorResult = this.anchorClient
+                ? await this.anchorClient.anchorMemory(anchorSubmission)
+                : createPendingAnchorResult(anchorSubmission, "casper_client_not_configured");
+        }
+        const entry = {
+            ...envelope,
+            canonical_json: canonicalJson,
+            content_hash: contentHash,
+            metadata_hash: metadataHash,
+            anchor_status: anchorResult?.status ?? (input.anchor ? "pending" : "not_requested"),
+            anchor_id: anchorResult?.anchor_id ?? anchorSubmission?.anchor_id ?? null,
+            casper_transaction_hash: anchorResult?.casper_transaction_hash ?? null,
+            onchain_content_hash: anchorResult?.onchain_content_hash ?? null,
+            updated_at: createdAt
+        };
+        await this.store.save(entry);
+        await this.audit?.record({
+            agent_id: entry.agent_id,
+            event_type: "memory.created",
+            subject_type: "memory",
+            subject_id: entry.memory_id,
+            metadata: {
+                type: entry.type,
+                content_hash: entry.content_hash,
+                metadata_hash: entry.metadata_hash,
+                anchor_status: entry.anchor_status
+            }
+        });
+        return entry;
+    }
+    async read(agentId, memoryId) {
+        return this.store.get(agentId, memoryId);
+    }
+    async search(agentId, query, limit = 10) {
+        const normalizedQuery = query.trim().toLowerCase();
+        const entries = await this.store.list(agentId);
+        const results = entries
+            .filter((entry) => {
+            if (normalizedQuery.length === 0) {
+                return true;
+            }
+            return buildSearchText(entry).includes(normalizedQuery);
+        })
+            .slice(0, Math.max(1, Math.min(limit, 50)))
+            .map(toSummary);
+        return {
+            agent_id: agentId,
+            query,
+            count: results.length,
+            results
+        };
+    }
+    async verify(agentId, memoryId) {
+        const entry = await this.store.get(agentId, memoryId);
+        if (!entry) {
+            return {
+                valid: false,
+                reason: "memory_not_found",
+                agent_id: agentId,
+                memory_id: memoryId
+            };
+        }
+        const envelope = toEnvelope(entry);
+        const localContentHash = sha256Hex(canonicalizeJson(envelope));
+        const localValid = localContentHash === entry.content_hash;
+        await this.audit?.record({
+            agent_id: agentId,
+            event_type: localValid ? "memory.verify_succeeded" : "memory.verify_failed",
+            subject_type: "memory",
+            subject_id: memoryId,
+            severity: localValid ? "info" : "warn",
+            metadata: {
+                local_content_hash: localContentHash,
+                stored_content_hash: entry.content_hash,
+                anchor_status: entry.anchor_status
+            }
+        });
+        return {
+            valid: localValid,
+            local_valid: localValid,
+            anchor_status: entry.anchor_status,
+            agent_id: agentId,
+            memory_id: memoryId,
+            local_content_hash: localContentHash,
+            stored_content_hash: entry.content_hash,
+            onchain_content_hash: entry.onchain_content_hash ?? null,
+            anchor_id: entry.anchor_id ?? null,
+            casper_transaction_hash: entry.casper_transaction_hash ?? null
+        };
+    }
+}
+function createMemoryId() {
+    return `mem_${randomUUID().replaceAll("-", "")}`;
+}
+function buildSearchText(entry) {
+    return [
+        entry.memory_id,
+        entry.type,
+        JSON.stringify(entry.source),
+        JSON.stringify(entry.body),
+        entry.content_hash
+    ]
+        .join(" ")
+        .toLowerCase();
+}
+function toSummary(entry) {
+    return {
+        memory_id: entry.memory_id,
+        type: entry.type,
+        content_hash: entry.content_hash,
+        anchor_status: entry.anchor_status,
+        created_at: entry.created_at,
+        source: entry.source
+    };
+}
+function toEnvelope(entry) {
+    return {
+        schema_version: entry.schema_version,
+        agent_id: entry.agent_id,
+        memory_id: entry.memory_id,
+        type: entry.type,
+        source: entry.source,
+        body: entry.body,
+        created_at: entry.created_at,
+        prev_anchor_hash: entry.prev_anchor_hash
+    };
+}

package/dist/memory/store.d.ts

@@ -0,0 +1,8 @@
+import type { MemoryStore, StoredMemoryEntry } from "./types.js";
+export declare class FileMemoryStore implements MemoryStore {
+    private readonly store;
+    constructor(dataDir: string);
+    save(entry: StoredMemoryEntry): Promise<void>;
+    get(agentId: string, memoryId: string): Promise<StoredMemoryEntry | null>;
+    list(agentId: string): Promise<StoredMemoryEntry[]>;
+}

package/dist/memory/store.js

@@ -0,0 +1,49 @@
+import { join } from "node:path";
+import { JsonFileStore } from "../storage/json-file-store.js";
+export class FileMemoryStore {
+    store;
+    constructor(dataDir) {
+        this.store = new JsonFileStore({
+            filePath: join(dataDir, "memory.json"),
+            empty: emptyStore,
+            normalize: normalizeStore
+        });
+    }
+    async save(entry) {
+        await this.store.update((data) => {
+            const existingIndex = data.memories.findIndex((memory) => memory.agent_id === entry.agent_id && memory.memory_id === entry.memory_id);
+            if (existingIndex >= 0) {
+                data.memories[existingIndex] = entry;
+            }
+            else {
+                data.memories.push(entry);
+            }
+        });
+    }
+    async get(agentId, memoryId) {
+        const data = await this.store.read();
+        return (data.memories.find((memory) => memory.agent_id === agentId && memory.memory_id === memoryId) ?? null);
+    }
+    async list(agentId) {
+        const data = await this.store.read();
+        return data.memories
+            .filter((memory) => memory.agent_id === agentId)
+            .sort((left, right) => right.created_at.localeCompare(left.created_at));
+    }
+}
+function emptyStore() {
+    return {
+        schema_version: "sigil.memory-store.v1",
+        memories: []
+    };
+}
+function normalizeStore(parsed) {
+    const data = asStoreObject(parsed);
+    return {
+        schema_version: "sigil.memory-store.v1",
+        memories: Array.isArray(data.memories) ? data.memories : []
+    };
+}
+function asStoreObject(parsed) {
+    return parsed && typeof parsed === "object" ? parsed : {};
+}

package/dist/memory/supabase-store.d.ts

@@ -0,0 +1,10 @@
+import { SupabaseRestClient } from "../storage/supabase-rest.js";
+import type { MemoryStore, StoredMemoryEntry } from "./types.js";
+export declare class SupabaseMemoryStore implements MemoryStore {
+    private readonly client;
+    private readonly table;
+    constructor(client: SupabaseRestClient);
+    save(entry: StoredMemoryEntry): Promise<void>;
+    get(agentId: string, memoryId: string): Promise<StoredMemoryEntry | null>;
+    list(agentId: string): Promise<StoredMemoryEntry[]>;
+}

package/dist/memory/supabase-store.js

@@ -0,0 +1,30 @@
+export class SupabaseMemoryStore {
+    client;
+    table;
+    constructor(client) {
+        this.client = client;
+        this.table = client.table("memories");
+    }
+    async save(entry) {
+        await this.client.upsert(this.table, {
+            agent_id: entry.agent_id,
+            memory_id: entry.memory_id,
+            created_at: entry.created_at,
+            updated_at: entry.updated_at,
+            record: entry
+        }, "agent_id,memory_id");
+    }
+    async get(agentId, memoryId) {
+        const [record] = await this.client.selectRecords(this.table, {
+            filters: { agent_id: agentId, memory_id: memoryId },
+            limit: 1
+        });
+        return record ?? null;
+    }
+    async list(agentId) {
+        return this.client.selectRecords(this.table, {
+            filters: { agent_id: agentId },
+            order: { column: "created_at" }
+        });
+    }
+}

package/dist/memory/types.d.ts

@@ -0,0 +1,56 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export declare const memoryTypes: readonly ["observation", "decision", "payment", "secret_usage", "system_event"];
+export type MemoryType = (typeof memoryTypes)[number];
+export type AnchorStatus = "not_requested" | "pending" | "anchored" | "failed";
+export type MemoryEnvelope = {
+    schema_version: "sigil.memory.v1";
+    agent_id: string;
+    memory_id: string;
+    type: MemoryType;
+    source: JsonObject;
+    body: JsonObject;
+    created_at: string;
+    prev_anchor_hash: string | null;
+};
+export type StoredMemoryEntry = MemoryEnvelope & {
+    canonical_json: string;
+    content_hash: string;
+    metadata_hash: string;
+    anchor_status: AnchorStatus;
+    anchor_id: string | null;
+    casper_transaction_hash: string | null;
+    onchain_content_hash: string | null;
+    updated_at: string;
+};
+export type WriteMemoryInput = {
+    agent_id: string;
+    type: MemoryType;
+    body: unknown;
+    source?: unknown;
+    anchor?: boolean;
+    memory_id?: string;
+    prev_anchor_hash?: string | null;
+};
+export type MemorySummary = {
+    memory_id: string;
+    type: MemoryType;
+    content_hash: string;
+    anchor_status: AnchorStatus;
+    created_at: string;
+    source: JsonObject;
+};
+export type MemorySearchResult = {
+    agent_id: string;
+    query: string;
+    count: number;
+    results: MemorySummary[];
+};
+export type MemoryStore = {
+    save(entry: StoredMemoryEntry): Promise<void>;
+    get(agentId: string, memoryId: string): Promise<StoredMemoryEntry | null>;
+    list(agentId: string): Promise<StoredMemoryEntry[]>;
+};

package/dist/memory/types.js

@@ -0,0 +1,7 @@
+export const memoryTypes = [
+    "observation",
+    "decision",
+    "payment",
+    "secret_usage",
+    "system_event"
+];

package/dist/payments/service.d.ts

@@ -0,0 +1,26 @@
+import type { AuditService } from "../audit/service.js";
+import type { GrimoireService } from "../grimoire/service.js";
+import type { X402ChallengeRequest, X402ChallengeResult } from "../x402/client.js";
+import type { X402SettlementProvider } from "../x402/settlement.js";
+import type { PaymentFetchInput, PaymentFetchResult, PaymentReceiptResult, PaymentStore } from "./types.js";
+type X402ChallengeRequester = {
+    requestChallenge(input: X402ChallengeRequest): Promise<X402ChallengeResult>;
+};
+export declare class PaymentService {
+    private readonly grimoireService;
+    private readonly store;
+    private readonly audit?;
+    private readonly challengeClient?;
+    private readonly settlementProvider?;
+    constructor(grimoireService: GrimoireService, store: PaymentStore, audit?: AuditService | undefined, challengeClient?: X402ChallengeRequester | undefined, settlementProvider?: X402SettlementProvider | undefined);
+    preflightFetch(input: PaymentFetchInput): Promise<PaymentFetchResult>;
+    fetch(input: PaymentFetchInput): Promise<PaymentFetchResult>;
+    receipt(paymentId: string): Promise<PaymentReceiptResult>;
+    private fetchChallenge;
+    private markSettlementUnavailable;
+    private settleApprovedRequirement;
+    private checkCurrentPeriodSpend;
+    private persistSettlementReceipt;
+    private resultFromIntent;
+}
+export {};