@atrib/recall 0.14.7 → 1.0.0

package/dist/recall-verb.js

@@ -0,0 +1,299 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+import { logReadPrimitiveCall } from '@atrib/mcp';
+import { EventTypeFilterSchema } from './event-type-filter.js';
+import { recall, runRecallAnnotations, runRecallByContent, runRecallBySigner, runRecallOrphans, runRecallRevisions, runRecallSessionChain, runRecallWalk, } from './index.js';
+import { extractRecordHashFieldsFromMcpResult, runTraceWalk, } from './trace-tools.js';
+import { tryHandleAtribVerify, VerifyInput } from './verification.js';
+const SHA256_REF_PATTERN = /^sha256:[0-9a-f]{64}$/;
+export const RECALL_SHAPES = [
+    'history',
+    'walk',
+    'content',
+    'chain',
+    'annotations',
+    'revisions',
+    'orphans',
+    'by_signer',
+];
+const RecallFilters = z.object({
+    context_id: z
+        .string()
+        .optional()
+        .describe('32-hex context_id filter (history, chain, orphans; walk trace scoping).'),
+    context_scope: z
+        .enum(['all', 'env'])
+        .optional()
+        .describe("History only. How to treat an omitted context_id: 'all' (default) searches cross-context; " +
+        "'env' applies the D078/D083 env-derived current context."),
+    creator_key: z
+        .string()
+        .optional()
+        .describe('Exact creator_key match (history, orphans).'),
+    event_type: EventTypeFilterSchema.optional().describe('Event-kind filter: shorthand alias or full URI (history, orphans).'),
+    content_id: z.string().optional().describe('Exact content_id match (history).'),
+    tool_name: z.string().optional().describe('Exact §8.2 disclosed tool_name match (history).'),
+    args_hash: z.string().optional().describe('Exact §8.3 args_hash match (history).'),
+    min_importance: z
+        .enum(['critical', 'high', 'medium', 'low', 'noise'])
+        .optional()
+        .describe('History only. Minimum annotation-derived importance.'),
+    topic_tags: z
+        .array(z.string())
+        .optional()
+        .describe('History only. OR-match against annotation topic tags.'),
+    include_revised: z
+        .boolean()
+        .optional()
+        .describe('History only. Hide records superseded by a revision when true.'),
+    min_signers: z
+        .number()
+        .optional()
+        .describe('History only. Minimum count of distinct signers.'),
+});
+export const RecallVerbInput = z.object({
+    shape: z
+        .enum(RECALL_SHAPES)
+        .optional()
+        .describe('Which read shape to run. Required unless `verification` is supplied (verification-only ' +
+        'call). history = filter-and-page over the local mirror; walk = graph/causal walk from ' +
+        '`start`; content = BM25 free-form retrieval over `query`; chain = chronological ' +
+        'session chain; annotations / revisions = per-record aggregations from `start`; ' +
+        'orphans = loose-end discovery; by_signer = per-creator aggregation.'),
+    direction: z
+        .enum(['backward', 'forward'])
+        .optional()
+        .describe("Walk only. Omit for the local derived-graph walk (legacy recall_walk). 'backward' walks " +
+        "the informed_by chain that led to `start` (legacy trace); 'forward' walks the records " +
+        'that cited `start` (legacy trace_forward).'),
+    start: z
+        .string()
+        .regex(SHA256_REF_PATTERN)
+        .optional()
+        .describe("'sha256:<64-hex>' starting record_hash. REQUIRED for walk, annotations, and revisions."),
+    query: z
+        .string()
+        .optional()
+        .describe('Free-form BM25 content query per D086. REQUIRED for shape=content.'),
+    filters: RecallFilters.optional().describe('AND-combined filters. Which fields apply depends on the shape; see each field.'),
+    rank_by: z
+        .enum(['timestamp', 'relevance', 'causal_distance'])
+        .optional()
+        .describe('History only. Result ordering; same semantics as the legacy tool.'),
+    rank_anchor: z
+        .string()
+        .optional()
+        .describe('History only. Anchor for non-timestamp rank_by modes.'),
+    limit: z
+        .number()
+        .optional()
+        .describe('Page size / top-k. history: default 10, max 200. content: top-k, default 10, max 50. ' +
+        'chain and orphans: default 50, max 500.'),
+    offset: z
+        .number()
+        .optional()
+        .describe('History only. Pagination offset (explicit handle; never protocol-session state).'),
+    compact: z
+        .boolean()
+        .optional()
+        .describe('history and walk-with-direction: omit heavy record fields (default true).'),
+    include_unverified: z
+        .boolean()
+        .optional()
+        .describe('History only. Include records that failed local signature verification.'),
+    toc: z
+        .boolean()
+        .optional()
+        .describe('History only. Table-of-contents entry shape per record.'),
+    edge_types: z
+        .array(z.enum(['CHAIN_PRECEDES', 'INFORMED_BY', 'ANNOTATES', 'REVISES']))
+        .optional()
+        .describe('Walk (no direction) only. Layer 1 edge types to follow; default all four.'),
+    depth: z
+        .number()
+        .optional()
+        .describe('Walk only. Maximum hop count. Graph walk default 3; directional walks default 3, max 10.'),
+    max_nodes: z
+        .number()
+        .optional()
+        .describe('Walk with direction only. Hard cap on visited records (default 200, max 500).'),
+    include_content: z
+        .boolean()
+        .optional()
+        .describe('chain and walk-with-direction: include the D062 local mirror body per record.'),
+    max_records: z
+        .number()
+        .optional()
+        .describe('Content only. Maximum newest-first records to search before candidate scoring.'),
+    evidence_mode: z
+        .enum(['bounded', 'require_complete'])
+        .optional()
+        .describe('Content only. Coverage posture; same semantics as the legacy tool (D123/D125).'),
+    include_tool_call_args: z
+        .boolean()
+        .optional()
+        .describe('Content only. Lift the operational tool_call score suppression (D156).'),
+    min_records: z
+        .number()
+        .optional()
+        .describe('by_signer only. Minimum record count to include a creator.'),
+    verification: VerifyInput.extend({
+        mode: z
+            .literal('handoff')
+            .optional()
+            .describe("Verification mode. Only 'handoff' (Pattern 3 claim acceptance) exists today."),
+    })
+        .optional()
+        .describe('Run handoff-evidence verification (legacy atrib-verify) and attach the tiered result ' +
+        'as a `verification` block on the response. When the optional @atrib/verify peer is ' +
+        'not installed, the block is { status: "verifier_unavailable" } and the read result ' +
+        'is unaffected (§5.8). Supply without `shape` for a verification-only call.'),
+});
+function refusal(message) {
+    return { isError: true, content: [{ type: 'text', text: message }] };
+}
+/** Dispatch one recall-verb call to the shape runners. Exported for tests. */
+export async function runRecallVerb(input) {
+    if (!input.shape && !input.verification) {
+        return { error: 'recall requires `shape`, `verification`, or both' };
+    }
+    let payload = {};
+    if (input.shape) {
+        const f = input.filters ?? {};
+        switch (input.shape) {
+            case 'history': {
+                payload = (await recall({
+                    ...(f.context_id !== undefined ? { context_id: f.context_id } : {}),
+                    ...(f.context_scope !== undefined ? { context_scope: f.context_scope } : {}),
+                    ...(f.creator_key !== undefined ? { creator_key: f.creator_key } : {}),
+                    ...(f.event_type !== undefined ? { event_type: f.event_type } : {}),
+                    ...(f.content_id !== undefined ? { content_id: f.content_id } : {}),
+                    ...(f.tool_name !== undefined ? { tool_name: f.tool_name } : {}),
+                    ...(f.args_hash !== undefined ? { args_hash: f.args_hash } : {}),
+                    ...(f.min_importance !== undefined ? { min_importance: f.min_importance } : {}),
+                    ...(f.topic_tags !== undefined ? { topic_tags: f.topic_tags } : {}),
+                    ...(f.include_revised !== undefined ? { include_revised: f.include_revised } : {}),
+                    ...(f.min_signers !== undefined ? { min_signers: f.min_signers } : {}),
+                    ...(input.limit !== undefined ? { limit: input.limit } : {}),
+                    ...(input.offset !== undefined ? { offset: input.offset } : {}),
+                    ...(input.compact !== undefined ? { compact: input.compact } : {}),
+                    ...(input.include_unverified !== undefined
+                        ? { include_unverified: input.include_unverified }
+                        : {}),
+                    ...(input.rank_by !== undefined ? { rank_by: input.rank_by } : {}),
+                    ...(input.rank_anchor !== undefined ? { rank_anchor: input.rank_anchor } : {}),
+                    ...(input.toc !== undefined ? { toc: input.toc } : {}),
+                }));
+                break;
+            }
+            case 'walk': {
+                if (!input.start)
+                    return { error: "shape='walk' requires `start`" };
+                if (input.direction) {
+                    const traceArgs = {
+                        record_hash: input.start,
+                        ...(f.context_id !== undefined ? { context_id: f.context_id } : {}),
+                        ...(input.depth !== undefined ? { depth: input.depth } : {}),
+                        ...(input.max_nodes !== undefined ? { max_nodes: input.max_nodes } : {}),
+                        ...(input.compact !== undefined ? { compact: input.compact } : {}),
+                        ...(input.include_content !== undefined
+                            ? { include_content: input.include_content }
+                            : {}),
+                    };
+                    payload = runTraceWalk(input.direction, traceArgs);
+                }
+                else {
+                    payload = await runRecallWalk({
+                        from_record_hash: input.start,
+                        ...(input.edge_types !== undefined
+                            ? { edge_types: input.edge_types }
+                            : {}),
+                        ...(input.depth !== undefined ? { depth: input.depth } : {}),
+                    });
+                }
+                break;
+            }
+            case 'content': {
+                if (input.query === undefined)
+                    return { error: "shape='content' requires `query`" };
+                payload = await runRecallByContent({
+                    query: input.query,
+                    ...(input.limit !== undefined ? { k: input.limit } : {}),
+                    ...(input.max_records !== undefined ? { max_records: input.max_records } : {}),
+                    ...(input.evidence_mode !== undefined ? { evidence_mode: input.evidence_mode } : {}),
+                    ...(input.include_tool_call_args !== undefined
+                        ? { include_tool_call_args: input.include_tool_call_args }
+                        : {}),
+                });
+                break;
+            }
+            case 'chain': {
+                payload = await runRecallSessionChain({
+                    ...(f.context_id !== undefined ? { context_id: f.context_id } : {}),
+                    ...(input.limit !== undefined ? { limit: input.limit } : {}),
+                    ...(input.include_content !== undefined
+                        ? { include_content: input.include_content }
+                        : {}),
+                });
+                break;
+            }
+            case 'annotations': {
+                if (!input.start)
+                    return { error: "shape='annotations' requires `start`" };
+                payload = await runRecallAnnotations({ record_hash: input.start });
+                break;
+            }
+            case 'revisions': {
+                if (!input.start)
+                    return { error: "shape='revisions' requires `start`" };
+                payload = await runRecallRevisions({ record_hash: input.start });
+                break;
+            }
+            case 'orphans': {
+                payload = await runRecallOrphans({
+                    ...(f.context_id !== undefined ? { context_id: f.context_id } : {}),
+                    ...(f.event_type !== undefined ? { event_type: f.event_type } : {}),
+                    ...(f.creator_key !== undefined ? { creator_key: f.creator_key } : {}),
+                    ...(input.limit !== undefined ? { limit: input.limit } : {}),
+                });
+                break;
+            }
+            case 'by_signer': {
+                payload = await runRecallBySigner({
+                    ...(input.min_records !== undefined ? { min_records: input.min_records } : {}),
+                });
+                break;
+            }
+        }
+    }
+    if (input.verification) {
+        const { mode: _mode, ...verifyArgs } = input.verification;
+        payload = { ...payload, verification: await tryHandleAtribVerify(verifyArgs) };
+    }
+    return { payload };
+}
+/** Register the `recall` verb tool on a server. */
+export function registerRecallVerbTool(mcp) {
+    mcp.registerTool('recall', {
+        description: "Look up the agent's signed past: atrib's read verb. One read-only tool absorbs the " +
+            'legacy recall_* tools (shape argument), trace / trace_forward (shape=walk with a ' +
+            'direction), and atrib-verify (the verification parameter). Results are JSON-identical ' +
+            'to the legacy tool they map onto; every compact result keeps record_hash so calls can ' +
+            'be chained. Signs nothing.',
+        inputSchema: RecallVerbInput.shape,
+    }, async (rawInput) => {
+        const input = RecallVerbInput.parse(rawInput);
+        const primitive = `recall:${input.shape ?? 'verification'}`;
+        return logReadPrimitiveCall(primitive, rawInput, async () => {
+            const outcome = await runRecallVerb(input);
+            if ('error' in outcome)
+                return refusal(outcome.error);
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify(outcome.payload, null, 2) },
+                ],
+            };
+        }, extractRecordHashFieldsFromMcpResult);
+    });
+}
+//# sourceMappingURL=recall-verb.js.map

package/dist/recall-verb.js.map

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

package/dist/trace-storage.d.ts

@@ -0,0 +1,36 @@
+import { type AtribRecord, type OnRecordSidecar } from '@atrib/mcp';
+export interface IndexedRecord {
+    record: AtribRecord;
+    /** sha256:<64-hex> form, matching informed_by entries. */
+    record_hash: string;
+    /** Source file the record was read from (for debugging). */
+    source: string;
+    /**
+     * Pre-sign payload context, when the producer wrote it to the local
+     * mirror as a `_local` sidecar on the envelope. Carries semantic content
+     * (toolName, args, result, content) the signed AtribRecord COMMITS TO
+     * via content_id / args_hash / result_hash but does not itself contain.
+     * Absent on legacy bare-record entries from older mirror writes.
+     */
+    local?: SidecarPayload;
+}
+/**
+ * Combined sidecar shape, superset of every producer's local payload
+ * (mcp-wrap writes toolName/args/result; atrib-emit writes content).
+ */
+export interface SidecarPayload extends OnRecordSidecar {
+    content?: unknown;
+    producer?: string;
+}
+/**
+ * Read every *.jsonl mirror in ATRIB_RECORDS_DIR and return an index keyed
+ * by sha256:<64-hex> record_hash. Both shapes (bare AtribRecord and emit's
+ * { record, proof, written_at } envelope) are supported.
+ *
+ * Returns the indexed map AND a flat list (newest-first by timestamp) for
+ * callers that want recall-style enumeration without by-hash lookup.
+ */
+export declare function loadAllRecords(dir?: string): {
+    byHash: Map<string, IndexedRecord>;
+    newestFirst: IndexedRecord[];
+};

package/dist/trace-storage.js

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Local mirror reader for atrib-trace.
+ *
+ * Reads either one ATRIB_RECORD_FILE mirror or every *.jsonl mirror under
+ * ~/.atrib/records/ and normalizes to bare AtribRecord shape regardless of
+ * producer (wrapper-signed or emit envelope).
+ *
+ * Builds an in-memory index by record_hash so trace can walk informed_by
+ * chains in O(1) per hop. The hash key is sha256:<64-hex> (the same form
+ * informed_by entries use), so no transformation needed at lookup time.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { canonicalRecord, hexEncode, sha256, withDerivedLocalContent, } from '@atrib/mcp';
+const RECORDS_FILE = process.env.ATRIB_RECORD_FILE;
+const RECORDS_DIR = process.env.ATRIB_RECORDS_DIR ?? join(homedir(), '.atrib', 'records');
+/**
+ * Read every *.jsonl mirror in ATRIB_RECORDS_DIR and return an index keyed
+ * by sha256:<64-hex> record_hash. Both shapes (bare AtribRecord and emit's
+ * { record, proof, written_at } envelope) are supported.
+ *
+ * Returns the indexed map AND a flat list (newest-first by timestamp) for
+ * callers that want recall-style enumeration without by-hash lookup.
+ */
+export function loadAllRecords(dir = RECORDS_DIR) {
+    const byHash = new Map();
+    const all = [];
+    const paths = [];
+    if (RECORDS_FILE) {
+        paths.push({ path: RECORDS_FILE, source: basename(RECORDS_FILE) });
+    }
+    else {
+        if (!existsSync(dir))
+            return { byHash, newestFirst: [] };
+        try {
+            for (const fname of readdirSync(dir).filter((f) => f.endsWith('.jsonl'))) {
+                paths.push({ path: join(dir, fname), source: fname });
+            }
+        }
+        catch {
+            return { byHash, newestFirst: [] };
+        }
+    }
+    for (const { path, source } of paths) {
+        try {
+            const raw = readFileSync(path, 'utf8');
+            for (const line of raw.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    // Normalize: envelope shape vs legacy bare record shape.
+                    const isEnvelope = 'record' in parsed &&
+                        parsed.record &&
+                        parsed.record.context_id !== undefined;
+                    const rec = isEnvelope
+                        ? parsed.record
+                        : parsed;
+                    if (!rec.context_id || !rec.signature || !rec.timestamp)
+                        continue;
+                    const hashHex = hexEncode(sha256(canonicalRecord(rec)));
+                    const indexed = {
+                        record: rec,
+                        record_hash: `sha256:${hashHex}`,
+                        source,
+                    };
+                    // Lift the `_local` sidecar onto the indexed record when present.
+                    // Legacy bare-record entries have no sidecar; that's OK, consumers
+                    // tolerate its absence.
+                    if (isEnvelope) {
+                        const sidecar = parsed._local;
+                        if (sidecar)
+                            indexed.local = withDerivedLocalContent(rec.event_type, sidecar);
+                    }
+                    byHash.set(indexed.record_hash, indexed);
+                    all.push(indexed);
+                }
+                catch {
+                    // Malformed line; skip.
+                }
+            }
+        }
+        catch {
+            // File read failure; skip this file.
+        }
+    }
+    all.sort((a, b) => b.record.timestamp - a.record.timestamp);
+    return { byHash, newestFirst: all };
+}
+//# sourceMappingURL=trace-storage.js.map

package/dist/trace-storage.js.map

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

package/dist/trace-tools.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The legacy `trace` / `trace_forward` tools, kept as permanent aliases over
+ * @atrib/recall's read surface (the walk shapes of the `recall` verb). Walks
+ * a record's informed_by chain backward (the reasoning chain that led to it)
+ * or forward (the records that cited it). Reads only the local mirror
+ * (~/.atrib/records/*.jsonl), same scope as recall.
+ *
+ * Moved here from @atrib/trace per the attest/recall rename; @atrib/trace
+ * re-exports this module so existing imports keep working, and the
+ * `recall` verb reaches the same implementation via shape='walk' with a
+ * direction argument.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { type IndexedRecord, type SidecarPayload } from './trace-storage.js';
+import { type TraceVisited } from './trace-walk.js';
+export declare const TraceInput: z.ZodObject<{
+    record_hash: z.ZodString;
+    context_id: z.ZodOptional<z.ZodString>;
+    depth: z.ZodOptional<z.ZodNumber>;
+    max_nodes: z.ZodOptional<z.ZodNumber>;
+    compact: z.ZodOptional<z.ZodBoolean>;
+    include_content: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type TraceInputT = z.infer<typeof TraceInput>;
+interface CompactVisited {
+    depth: number;
+    record_hash: string;
+    parent_hashes: string[];
+    source: string | null;
+    event_type: string | null;
+    context_id: string | null;
+    creator_key: string | null;
+    timestamp: number | null;
+    /** informed_by entries on this record. Empty if none or dangling. */
+    next_informed_by: string[];
+    /** Sub-set of next_informed_by that were resolved (present in mirror). */
+    next_resolved: string[];
+    /** Sub-set of next_informed_by that were dangling (not in mirror). */
+    next_dangling: string[];
+    /**
+     * Semantic context from the local sidecar when present. Carries
+     * tool name + brief content summary so the agent can reason about
+     * the record's meaning without separately fetching it. Absent on
+     * legacy bare-record entries that pre-date the sidecar.
+     */
+    sidecar_summary?: {
+        tool_name?: string;
+        span_kind?: string;
+        span_name?: string;
+        model_name?: string;
+        prompt_version?: string;
+        topics?: string[];
+        intent?: string;
+        rationale?: string;
+        /**
+         * First 200 chars of the record's human-readable content, derived
+         * per event_type from the @atrib/mcp normative shapes (D086):
+         * observation `what`, annotation `summary`, revision `new_position`.
+         * For legacy records using non-normative names (`summary` on
+         * observation), falls back to `summary`.
+         */
+        what?: string;
+        /** Annotation `importance` field when present. */
+        importance?: string;
+        producer?: string;
+    };
+    /** Signed structural disclosures, surfaced when present on the record. */
+    informed_by?: string[];
+    tool_name?: string;
+    args_hash?: string;
+    result_hash?: string;
+    /** D062 local mirror body, included only when include_content=true. */
+    local_content?: unknown;
+    local_producer?: string;
+}
+/** Pull a compact summary from the sidecar's content payload.
+ * Exported for unit testing of the per-event_type content-shape handling. */
+export declare function summarizeSidecar(loadedRecord: {
+    local?: SidecarPayload;
+} | undefined): CompactVisited['sidecar_summary'];
+export declare function compactVisited(v: TraceVisited, danglingSet: Set<string>, byHash: Map<string, IndexedRecord>, includeContent: boolean): CompactVisited;
+export declare function extractRecordHashFieldsFromMcpResult(result: unknown): string[];
+/**
+ * Run one informed_by walk and return the JSON payload. This is the single
+ * implementation behind the legacy `trace` / `trace_forward` tools AND the
+ * `recall` verb's shape='walk' with a direction, so their results are
+ * JSON-identical by construction (read-equivalence conformance family).
+ */
+export declare function runTraceWalk(direction: 'backward' | 'forward', args: TraceInputT): Record<string, unknown>;
+/** Register the legacy `trace` + `trace_forward` tools on a server. */
+export declare function registerTraceTools(mcp: McpServer): void;
+export interface AtribTraceServer {
+    mcp: McpServer;
+}
+/**
+ * Wire up the legacy atrib-trace MCP server. Mounts `trace` and
+ * `trace_forward` plus the `recall` verb (alias-window rule W1). The
+ * @atrib/trace package re-exports this factory.
+ */
+export declare function createAtribTraceServer(): Promise<AtribTraceServer>;
+export {};