mrmainspring 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mr Mainspring contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# Mr Mainspring
+
+Installable MCP backend for local agent demos. It exposes memory, Grimoire
+policy/secret storage, payment intent tools, audit trail tools, Casper anchoring
+boundaries, and x402 settlement-provider wiring.
+
+## Install
+
+```bash
+npm install -g mrmainspring
+```
+
+Run the stdio MCP server:
+
+```bash
+mainspring
+```
+
+For local development from this repository:
+
+```bash
+npm run build
+npm run mcp:stdio
+```
+
+## Environment
+
+The server loads `.env` from the current directory, backend directory, or repo
+root. Use `SIGIL_ENV_FILE` to point at a specific env file.
+
+Important package boundaries:
+
+- Keep `.env`, `.sigil/`, local keys, and generated demo data outside the npm
+  package.
+- Real Casper submission remains gated by `CASPER_ENABLE_REAL_SUBMISSION=true`.
+- Real x402 settlement remains gated by `X402_ENABLE_REAL_SETTLEMENT=true` and
+  a configured `X402_SIGNER_URL`.
+- The signer private key must live outside the repository workspace.
+
+## Library Entry
+
+```ts
+import { createSigilServer } from "mrmainspring";
+```
+
+The CLI entry is also exported as `mrmainspring/mcp`, but importing it starts
+the stdio server; use the package bin for normal MCP client configuration.

package/dist/audit/service.d.ts

@@ -0,0 +1,7 @@
+import type { AuditEvent, AuditEventInput, AuditStore, AuditTailInput, AuditTailResult } from "./types.js";
+export declare class AuditService {
+    private readonly store;
+    constructor(store: AuditStore);
+    record(input: AuditEventInput): Promise<AuditEvent>;
+    tail(input?: AuditTailInput): Promise<AuditTailResult>;
+}

package/dist/audit/service.js

@@ -0,0 +1,98 @@
+import { randomUUID } from "node:crypto";
+import { toJsonObject } from "../memory/canonical.js";
+const DEFAULT_TAIL_LIMIT = 50;
+const MAX_TAIL_LIMIT = 200;
+const MAX_METADATA_BYTES = 16 * 1024;
+const MAX_METADATA_DEPTH = 6;
+const MAX_METADATA_KEYS = 50;
+const MAX_METADATA_ARRAY_ITEMS = 50;
+const MAX_METADATA_STRING_LENGTH = 2048;
+const TRUNCATED = "[truncated]";
+const REDACTED = "[redacted]";
+export class AuditService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async record(input) {
+        const event = {
+            id: createAuditId(),
+            agent_id: input.agent_id ?? null,
+            event_type: input.event_type,
+            subject_type: input.subject_type,
+            subject_id: input.subject_id ?? null,
+            severity: input.severity ?? "info",
+            metadata: sanitizeMetadata(input.metadata ?? {}),
+            created_at: new Date().toISOString()
+        };
+        await this.store.append(event);
+        return event;
+    }
+    async tail(input = {}) {
+        const limit = Math.max(1, Math.min(input.limit ?? DEFAULT_TAIL_LIMIT, MAX_TAIL_LIMIT));
+        const events = (await this.store.list())
+            .filter((event) => !input.agent_id || event.agent_id === input.agent_id)
+            .filter((event) => !input.event_type || event.event_type === input.event_type)
+            .sort((left, right) => right.created_at.localeCompare(left.created_at))
+            .slice(0, limit);
+        return {
+            count: events.length,
+            events
+        };
+    }
+}
+function sanitizeMetadata(metadata) {
+    const object = toJsonObject(metadata, "metadata");
+    const bounded = redactAndBound(object, 0);
+    const size = Buffer.byteLength(JSON.stringify(bounded), "utf8");
+    if (size > MAX_METADATA_BYTES) {
+        return {
+            truncated: true,
+            original_size_bytes: size
+        };
+    }
+    return bounded;
+}
+function redactAndBound(value, depth) {
+    if (depth >= MAX_METADATA_DEPTH) {
+        return TRUNCATED;
+    }
+    if (Array.isArray(value)) {
+        const boundedItems = value
+            .slice(0, MAX_METADATA_ARRAY_ITEMS)
+            .map((item) => redactAndBound(item, depth + 1));
+        if (value.length > MAX_METADATA_ARRAY_ITEMS) {
+            boundedItems.push(TRUNCATED);
+        }
+        return boundedItems;
+    }
+    if (value && typeof value === "object") {
+        const redacted = {};
+        const entries = Object.entries(value).slice(0, MAX_METADATA_KEYS);
+        for (const [key, nestedValue] of entries) {
+            if (isSensitiveKey(key)) {
+                redacted[key] = REDACTED;
+            }
+            else {
+                redacted[key] = redactAndBound(nestedValue, depth + 1);
+            }
+        }
+        if (Object.keys(value).length > MAX_METADATA_KEYS) {
+            redacted.truncated_keys = true;
+        }
+        return redacted;
+    }
+    if (typeof value === "string" && value.length > MAX_METADATA_STRING_LENGTH) {
+        return `${value.slice(0, MAX_METADATA_STRING_LENGTH)}${TRUNCATED}`;
+    }
+    return value;
+}
+function isSensitiveKey(key) {
+    if (/(_hash|Hash|hash)$/.test(key)) {
+        return false;
+    }
+    return /secret|token|key|password|private|payload|credential|authorization|signature|value/i.test(key);
+}
+function createAuditId() {
+    return `aud_${randomUUID().replaceAll("-", "")}`;
+}

package/dist/audit/store.d.ts

@@ -0,0 +1,7 @@
+import type { AuditEvent, AuditStore } from "./types.js";
+export declare class FileAuditStore implements AuditStore {
+    private readonly store;
+    constructor(dataDir: string);
+    append(event: AuditEvent): Promise<void>;
+    list(): Promise<AuditEvent[]>;
+}

package/dist/audit/store.js

@@ -0,0 +1,37 @@
+import { join } from "node:path";
+import { JsonFileStore } from "../storage/json-file-store.js";
+export class FileAuditStore {
+    store;
+    constructor(dataDir) {
+        this.store = new JsonFileStore({
+            filePath: join(dataDir, "audit.json"),
+            empty: emptyStore,
+            normalize: normalizeStore
+        });
+    }
+    async append(event) {
+        await this.store.update((data) => {
+            data.events.push(event);
+        });
+    }
+    async list() {
+        const data = await this.store.read();
+        return [...data.events];
+    }
+}
+function emptyStore() {
+    return {
+        schema_version: "sigil.audit-store.v1",
+        events: []
+    };
+}
+function normalizeStore(parsed) {
+    const data = asStoreObject(parsed);
+    return {
+        schema_version: "sigil.audit-store.v1",
+        events: Array.isArray(data.events) ? data.events : []
+    };
+}
+function asStoreObject(parsed) {
+    return parsed && typeof parsed === "object" ? parsed : {};
+}

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

@@ -0,0 +1,9 @@
+import { SupabaseRestClient } from "../storage/supabase-rest.js";
+import type { AuditEvent, AuditStore } from "./types.js";
+export declare class SupabaseAuditStore implements AuditStore {
+    private readonly client;
+    private readonly table;
+    constructor(client: SupabaseRestClient);
+    append(event: AuditEvent): Promise<void>;
+    list(): Promise<AuditEvent[]>;
+}

package/dist/audit/supabase-store.js

@@ -0,0 +1,22 @@
+export class SupabaseAuditStore {
+    client;
+    table;
+    constructor(client) {
+        this.client = client;
+        this.table = client.table("audit_events");
+    }
+    async append(event) {
+        await this.client.insert(this.table, {
+            id: event.id,
+            agent_id: event.agent_id,
+            event_type: event.event_type,
+            created_at: event.created_at,
+            record: event
+        });
+    }
+    async list() {
+        return this.client.selectRecords(this.table, {
+            order: { column: "created_at", ascending: true }
+        });
+    }
+}

package/dist/audit/types.d.ts

@@ -0,0 +1,31 @@
+import type { JsonObject } from "../memory/types.js";
+export type AuditSeverity = "debug" | "info" | "warn" | "error";
+export type AuditEventInput = {
+    agent_id?: string | null;
+    event_type: string;
+    subject_type: string;
+    subject_id?: string | null;
+    severity?: AuditSeverity;
+    metadata?: JsonObject;
+};
+export type AuditEvent = Required<Omit<AuditEventInput, "severity" | "metadata" | "agent_id" | "subject_id">> & {
+    id: string;
+    agent_id: string | null;
+    subject_id: string | null;
+    severity: AuditSeverity;
+    metadata: JsonObject;
+    created_at: string;
+};
+export type AuditTailInput = {
+    agent_id?: string;
+    event_type?: string;
+    limit?: number;
+};
+export type AuditTailResult = {
+    count: number;
+    events: AuditEvent[];
+};
+export type AuditStore = {
+    append(event: AuditEvent): Promise<void>;
+    list(): Promise<AuditEvent[]>;
+};

package/dist/audit/types.js

@@ -0,0 +1 @@
+export {};

package/dist/casper/anchorClient.d.ts

@@ -0,0 +1,99 @@
+export declare const REAL_CASPER_ANCHOR_ENV_VARS: readonly ["CASPER_RPC_URL", "CASPER_NETWORK_NAME", "MEMORY_ANCHOR_CONTRACT_HASH", "MEMORY_ANCHOR_PACKAGE_HASH", "CASPER_ACCOUNT_KEY_PATH", "CASPER_ENABLE_REAL_SUBMISSION"];
+export type AnchorMemoryRequest = {
+    agent_id: string;
+    memory_id: string;
+    content_hash: string;
+    metadata_hash: string;
+    prev_anchor_hash: string | null;
+};
+export type AnchorSubmission = {
+    anchor_id: string;
+    agent_id_hash: string;
+    memory_id_hash: string;
+    content_hash: string;
+    metadata_hash: string;
+    prev_anchor_hash: string | null;
+};
+export type AnchorSubmissionReason = "casper_contract_not_configured" | "casper_client_not_configured" | "casper_transaction_submission_disabled" | "casper_transaction_submission_failed" | "casper_transaction_hash_missing";
+export type AnchorSubmissionResult = {
+    status: "pending" | "anchored" | "failed";
+    anchor_id: string;
+    casper_transaction_hash: string | null;
+    onchain_content_hash: string | null;
+    reason?: AnchorSubmissionReason;
+};
+export type CasperAnchorClient = {
+    readonly mode: "unconfigured" | "configured";
+    anchorMemory(submission: AnchorSubmission): Promise<AnchorSubmissionResult>;
+};
+export type CasperAnchorClientConfig = {
+    networkName: string;
+    caip2ChainId: string;
+    rpcUrl: string | null;
+    accountKeyPath: string | null;
+    memoryAnchorContractHash: string | null;
+    memoryAnchorPackageHash: string | null;
+    submissionEnabled?: boolean;
+    clientBin?: string;
+    clientWslDistro?: string | null;
+    anchorSubmissionMode?: "transaction-package" | "deploy-contract-hash";
+    gasPriceTolerance?: string;
+    pricingMode?: string;
+    anchorPaymentAmountMotes?: string;
+};
+export type ValidatedCasperAnchorConfig = {
+    networkName: string;
+    caip2ChainId: string;
+    rpcUrl: string;
+    accountKeyPath: string;
+    memoryAnchorContractHash: string;
+    memoryAnchorPackageHash: string;
+    submissionEnabled: boolean;
+    clientBin: string;
+    clientWslDistro: string | null;
+    anchorSubmissionMode: "transaction-package" | "deploy-contract-hash";
+    gasPriceTolerance: string;
+    pricingMode: string;
+    anchorPaymentAmountMotes: string;
+};
+export type CasperCommandResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+export type CasperCommandRunner = (command: string, args: readonly string[]) => Promise<CasperCommandResult>;
+export type CasperAnchorClientOptions = {
+    commandRunner?: CasperCommandRunner;
+};
+export type CasperCommandInvocation = {
+    command: string;
+    args: string[];
+};
+export declare class UnconfiguredCasperAnchorClient implements CasperAnchorClient {
+    private readonly reason;
+    readonly mode: "unconfigured";
+    readonly submissions: AnchorSubmission[];
+    constructor(reason?: AnchorSubmissionReason);
+    anchorMemory(submission: AnchorSubmission): Promise<AnchorSubmissionResult>;
+}
+export declare class ConfiguredCasperAnchorClient implements CasperAnchorClient {
+    readonly config: ValidatedCasperAnchorConfig;
+    private readonly commandRunner;
+    readonly mode: "configured";
+    readonly submissions: AnchorSubmission[];
+    constructor(config: ValidatedCasperAnchorConfig, commandRunner?: CasperCommandRunner);
+    anchorMemory(submission: AnchorSubmission): Promise<AnchorSubmissionResult>;
+}
+export declare class MockCasperAnchorClient extends UnconfiguredCasperAnchorClient {
+    constructor();
+}
+export declare function createCasperAnchorClient(config: CasperAnchorClientConfig, options?: CasperAnchorClientOptions): CasperAnchorClient;
+export declare function validateCasperAnchorConfig(config: CasperAnchorClientConfig): ValidatedCasperAnchorConfig | null;
+export declare function createAnchorSubmission(input: AnchorMemoryRequest): AnchorSubmission;
+export declare function createPendingAnchorResult(submission: AnchorSubmission, reason: AnchorSubmissionReason): AnchorSubmissionResult;
+export declare function createFailedAnchorResult(submission: AnchorSubmission, reason: AnchorSubmissionReason): AnchorSubmissionResult;
+export declare function createAnchoredAnchorResult(submission: AnchorSubmission, casperTransactionHash: string): AnchorSubmissionResult;
+export declare function createSubmittedAnchorResult(submission: AnchorSubmission, casperTransactionHash: string): AnchorSubmissionResult;
+export declare function computeAnchorId(input: AnchorMemoryRequest): string;
+export declare function buildCasperAnchorCommand(config: ValidatedCasperAnchorConfig, submission: AnchorSubmission): CasperCommandInvocation;
+export declare function extractCasperTransactionHash(result: CasperCommandResult): string | null;