audrey 0.17.0 → 0.20.0

package/dist/src/rules-compiler.js

@@ -0,0 +1,143 @@
+/**
+ * Rules compiler — turn PromotionCandidates into reviewable Markdown files.
+ *
+ * Each rule gets its own file under `.claude/rules/<slug>.md` with YAML
+ * front matter that records the source memory ids, confidence, evidence
+ * count, and promotion timestamp. That front matter is what makes the rule
+ * traceable: a later audit or revert can map the file back to the exact
+ * memories that produced it.
+ */
+const STOP_WORDS = new Set(['the', 'a', 'an', 'is', 'of', 'and', 'or', 'to', 'for', 'with', 'on', 'at', 'by', 'in', 'as']);
+function titleFor(candidate) {
+    const words = candidate.content.replace(/\s+/g, ' ').trim().split(' ');
+    const leading = words.slice(0, 12).join(' ');
+    const trimmed = leading.replace(/[.!?,;:]+$/, '');
+    return trimmed.length > 0 ? trimmed : `Rule ${candidate.candidate_id}`;
+}
+function slugifyTitle(title) {
+    const lowered = title.toLowerCase();
+    const words = lowered.split(/[^a-z0-9]+/).filter(w => w && !STOP_WORDS.has(w));
+    const slug = words.slice(0, 6).join('-');
+    return slug.length > 0 ? slug : 'rule';
+}
+function renderFrontmatter(meta) {
+    const lines = ['---'];
+    for (const [key, value] of Object.entries(meta)) {
+        lines.push(renderFrontmatterLine(key, value, 0));
+    }
+    lines.push('---');
+    return lines.join('\n');
+}
+function renderFrontmatterLine(key, value, indent) {
+    const pad = '  '.repeat(indent);
+    if (value == null) {
+        return `${pad}${key}: null`;
+    }
+    if (typeof value === 'string') {
+        return `${pad}${key}: ${quoteString(value)}`;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return `${pad}${key}: ${value}`;
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return `${pad}${key}: []`;
+        const items = value.map(v => `${pad}  - ${quoteString(String(v))}`).join('\n');
+        return `${pad}${key}:\n${items}`;
+    }
+    if (typeof value === 'object') {
+        const nested = Object.entries(value)
+            .map(([k, v]) => renderFrontmatterLine(k, v, indent + 1))
+            .join('\n');
+        return `${pad}${key}:\n${nested}`;
+    }
+    return `${pad}${key}: ${String(value)}`;
+}
+function quoteString(value) {
+    const needsQuoting = /[:#\n"'`\\]/.test(value) || value.startsWith(' ') || value.endsWith(' ');
+    if (!needsQuoting)
+        return value;
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+export function renderClaudeRule(candidate, promotedAt) {
+    const title = titleFor(candidate);
+    const slug = slugifyTitle(title);
+    const relativePath = `.claude/rules/${slug}.md`;
+    const frontmatter = {
+        title,
+        audrey: {
+            memory_ids: [candidate.memory_id],
+            memory_type: candidate.memory_type,
+            candidate_id: candidate.candidate_id,
+            confidence: Number(candidate.confidence.toFixed(3)),
+            evidence_count: candidate.evidence_count,
+            usage_count: candidate.usage_count,
+            failure_prevented: candidate.failure_prevented,
+            score: Number(candidate.score.toFixed(2)),
+            promoted_at: promotedAt,
+        },
+    };
+    if (candidate.scope) {
+        frontmatter.audrey.scope = candidate.scope;
+    }
+    if (candidate.tags.length > 0) {
+        frontmatter.audrey.tags = candidate.tags;
+    }
+    const evidenceLine = candidate.failure_prevented > 0
+        ? `This rule would have prevented ${candidate.failure_prevented} recent tool failure${candidate.failure_prevented === 1 ? '' : 's'}.`
+        : `Supported by ${candidate.evidence_count} observation${candidate.evidence_count === 1 ? '' : 's'}.`;
+    const bodyLines = [
+        renderFrontmatter(frontmatter),
+        '',
+        `# ${title}`,
+        '',
+        candidate.content,
+        '',
+        '## Why this rule',
+        '',
+        `- ${candidate.reason}`,
+        `- ${evidenceLine}`,
+        `- Confidence: ${(candidate.confidence * 100).toFixed(1)}%`,
+        '',
+        '## Provenance',
+        '',
+        `- Source memory: \`${candidate.memory_type}:${candidate.memory_id}\``,
+        `- Promoted at: ${promotedAt}`,
+        `- Revocation: delete this file, or run \`audrey forget ${candidate.memory_id}\` to retract the underlying memory.`,
+        '',
+    ];
+    return {
+        title,
+        slug,
+        relativePath,
+        body: bodyLines.join('\n'),
+        frontmatter,
+    };
+}
+export function renderAllRules(candidates, promotedAt) {
+    const seen = new Set();
+    const docs = [];
+    for (const candidate of candidates) {
+        const doc = renderClaudeRule(candidate, promotedAt);
+        // Ensure slug uniqueness — if two candidates produce the same slug,
+        // disambiguate with a short suffix of the candidate id.
+        let finalSlug = doc.slug;
+        let n = 1;
+        while (seen.has(finalSlug)) {
+            finalSlug = `${doc.slug}-${n++}`;
+        }
+        seen.add(finalSlug);
+        if (finalSlug !== doc.slug) {
+            docs.push({
+                ...doc,
+                slug: finalSlug,
+                relativePath: `.claude/rules/${finalSlug}.md`,
+            });
+        }
+        else {
+            docs.push(doc);
+        }
+    }
+    return docs;
+}
+//# sourceMappingURL=rules-compiler.js.map

package/dist/src/rules-compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules-compiler.js","sourceRoot":"","sources":["../../src/rules-compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;AAE3H,SAAS,QAAQ,CAAC,SAA6B;IAC7C,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACvE,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IAClD,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,SAAS,CAAC,YAAY,EAAE,CAAC;AACzE,CAAC;AAED,SAAS,YAAY,CAAC,KAAa;IACjC,MAAM,OAAO,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/E,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzC,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;AACzC,CAAC;AAED,SAAS,iBAAiB,CAAC,IAA6B;IACtD,MAAM,KAAK,GAAa,CAAC,KAAK,CAAC,CAAC;IAChC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,qBAAqB,CAAC,GAAW,EAAE,KAAc,EAAE,MAAc;IACxE,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;QAClB,OAAO,GAAG,GAAG,GAAG,GAAG,QAAQ,CAAC;IAC9B,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,GAAG,GAAG,GAAG,GAAG,KAAK,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;IAC/C,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QAC5D,OAAO,GAAG,GAAG,GAAG,GAAG,KAAK,KAAK,EAAE,CAAC;IAClC,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,GAAG,GAAG,GAAG,GAAG,MAAM,CAAC;QAClD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,GAAG,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/E,OAAO,GAAG,GAAG,GAAG,GAAG,MAAM,KAAK,EAAE,CAAC;IACnC,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;aAC5D,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,qBAAqB,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,CAAC;aACxD,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,OAAO,GAAG,GAAG,GAAG,GAAG,MAAM,MAAM,EAAE,CAAC;IACpC,CAAC;IACD,OAAO,GAAG,GAAG,GAAG,GAAG,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAC1C,CAAC;AAED,SAAS,WAAW,CAAC,KAAa;IAChC,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC/F,IAAI,CAAC,YAAY;QAAE,OAAO,KAAK,CAAC;IAChC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,SAA6B,EAAE,UAAkB;IAChF,MAAM,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,YAAY,GAAG,iBAAiB,IAAI,KAAK,CAAC;IAEhD,MAAM,WAAW,GAA4B;QAC3C,KAAK;QACL,MAAM,EAAE;YACN,UAAU,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC;YACjC,WAAW,EAAE,SAAS,CAAC,WAAW;YAClC,YAAY,EAAE,SAAS,CAAC,YAAY;YACpC,UAAU,EAAE,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YACnD,cAAc,EAAE,SAAS,CAAC,cAAc;YACxC,WAAW,EAAE,SAAS,CAAC,WAAW;YAClC,iBAAiB,EAAE,SAAS,CAAC,iBAAiB;YAC9C,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YACzC,WAAW,EAAE,UAAU;SACxB;KACF,CAAC;IACF,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC;QACnB,WAAW,CAAC,MAAkC,CAAC,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC;IAC1E,CAAC;IACD,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,WAAW,CAAC,MAAkC,CAAC,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;IACxE,CAAC;IAED,MAAM,YAAY,GAAG,SAAS,CAAC,iBAAiB,GAAG,CAAC;QAClD,CAAC,CAAC,kCAAkC,SAAS,CAAC,iBAAiB,uBAAuB,SAAS,CAAC,iBAAiB,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG;QACrI,CAAC,CAAC,gBAAgB,SAAS,CAAC,cAAc,eAAe,SAAS,CAAC,cAAc,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;IAExG,MAAM,SAAS,GAAG;QAChB,iBAAiB,CAAC,WAAW,CAAC;QAC9B,EAAE;QACF,KAAK,KAAK,EAAE;QACZ,EAAE;QACF,SAAS,CAAC,OAAO;QACjB,EAAE;QACF,kBAAkB;QAClB,EAAE;QACF,KAAK,SAAS,CAAC,MAAM,EAAE;QACvB,KAAK,YAAY,EAAE;QACnB,iBAAiB,CAAC,SAAS,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;QAC3D,EAAE;QACF,eAAe;QACf,EAAE;QACF,sBAAsB,SAAS,CAAC,WAAW,IAAI,SAAS,CAAC,SAAS,IAAI;QACtE,kBAAkB,UAAU,EAAE;QAC9B,0DAA0D,SAAS,CAAC,SAAS,sCAAsC;QACnH,EAAE;KACH,CAAC;IAEF,OAAO;QACL,KAAK;QACL,IAAI;QACJ,YAAY;QACZ,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;QAC1B,WAAW;KACZ,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,UAAgC,EAAE,UAAkB;IACjF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,IAAI,GAAc,EAAE,CAAC;IAC3B,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,gBAAgB,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;QACpD,oEAAoE;QACpE,wDAAwD;QACxD,IAAI,SAAS,GAAG,GAAG,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3B,SAAS,GAAG,GAAG,GAAG,CAAC,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;QACnC,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACpB,IAAI,SAAS,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC;YAC3B,IAAI,CAAC,IAAI,CAAC;gBACR,GAAG,GAAG;gBACN,IAAI,EAAE,SAAS;gBACf,YAAY,EAAE,iBAAiB,SAAS,KAAK;aAC9C,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/src/server.d.ts

@@ -0,0 +1,12 @@
+import type { AudreyConfig } from './types.js';
+export interface ServerOptions {
+    port?: number;
+    hostname?: string;
+    config: AudreyConfig;
+    apiKey?: string;
+}
+export declare function startServer(options: ServerOptions): Promise<{
+    port: number;
+    close: () => void;
+}>;
+//# sourceMappingURL=server.d.ts.map

package/dist/src/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,aAAa;;;GAqBvD"}

package/dist/src/server.js

@@ -0,0 +1,22 @@
+import { serve } from '@hono/node-server';
+import { createApp } from './routes.js';
+import { Audrey } from './audrey.js';
+export async function startServer(options) {
+    const { port = 7437, hostname = '0.0.0.0', config, apiKey } = options;
+    const audrey = new Audrey(config);
+    if (audrey.embeddingProvider && typeof audrey.embeddingProvider.ready === 'function') {
+        await audrey.embeddingProvider.ready();
+    }
+    const app = createApp(audrey, { apiKey });
+    const server = serve({ fetch: app.fetch, port, hostname }, (info) => {
+        console.error(`[audrey-http] listening on ${hostname}:${info.port}`);
+    });
+    return {
+        port,
+        close: () => {
+            server.close();
+            audrey.close();
+        },
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/src/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAUrC,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAsB;IACtD,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,QAAQ,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IACtE,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;IAElC,IAAI,MAAM,CAAC,iBAAiB,IAAI,OAAO,MAAM,CAAC,iBAAiB,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QACrF,MAAM,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,CAAC;IACzC,CAAC;IAED,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAE1C,MAAM,MAAM,GAAG,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE;QAClE,OAAO,CAAC,KAAK,CAAC,8BAA8B,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,IAAI;QACJ,KAAK,EAAE,GAAG,EAAE;YACV,MAAM,CAAC,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/tool-trace.d.ts

@@ -0,0 +1,37 @@
+/**
+ * High-level API for capturing agent tool traces.
+ *
+ * Contract: raw tool input / output / error text NEVER leaves this module
+ * without going through redact(). The default behavior is to keep only
+ * metadata (content hash, redacted error summary, file fingerprints) —
+ * opting into retainDetails pulls in the actual payload, still redacted.
+ */
+import Database from 'better-sqlite3';
+import { type EventOutcome, type EventType, type MemoryEvent } from './events.js';
+import { type RedactionHit } from './redact.js';
+export interface ObserveToolInput {
+    event: EventType | string;
+    tool: string;
+    source?: string;
+    sessionId?: string;
+    actorAgent?: string;
+    input?: unknown;
+    output?: unknown;
+    outcome?: EventOutcome;
+    errorSummary?: string;
+    cwd?: string;
+    files?: string[];
+    metadata?: Record<string, unknown>;
+    retainDetails?: boolean;
+}
+export interface ObserveToolResult {
+    event: MemoryEvent;
+    redactions: RedactionHit[];
+}
+/**
+ * Extract a one-line text summary from a tool result. Used when caller
+ * provides raw output text; we never store the raw content, only the summary.
+ */
+export declare function summarizeOutput(output: unknown, maxChars?: number): string | null;
+export declare function observeTool(db: Database.Database, input: ObserveToolInput): ObserveToolResult;
+//# sourceMappingURL=tool-trace.d.ts.map

package/dist/src/tool-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-trace.d.ts","sourceRoot":"","sources":["../../src/tool-trace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAEtC,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,WAAW,EAEjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAA2C,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAIzF,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,WAAW,CAAC;IACnB,UAAU,EAAE,YAAY,EAAE,CAAC;CAC5B;AAwCD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAE,MAAY,GAAG,MAAM,GAAG,IAAI,CAQtF;AAoBD,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,CAqD7F"}

package/dist/src/tool-trace.js

@@ -0,0 +1,142 @@
+/**
+ * High-level API for capturing agent tool traces.
+ *
+ * Contract: raw tool input / output / error text NEVER leaves this module
+ * without going through redact(). The default behavior is to keep only
+ * metadata (content hash, redacted error summary, file fingerprints) —
+ * opting into retainDetails pulls in the actual payload, still redacted.
+ */
+import { createHash } from 'node:crypto';
+import { statSync, readFileSync, existsSync } from 'node:fs';
+import { insertEvent, } from './events.js';
+import { redact, redactJson, summarizeRedactions } from './redact.js';
+const MAX_ERROR_SUMMARY_CHARS = 2000;
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function hashOf(value) {
+    if (value == null)
+        return null;
+    const text = typeof value === 'string' ? value : JSON.stringify(value);
+    if (!text)
+        return null;
+    return sha256(text);
+}
+function fingerprintFile(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const stat = statSync(path);
+        if (!stat.isFile())
+            return null;
+        if (stat.size === 0)
+            return `${path}|0|${stat.mtimeMs.toFixed(0)}|empty`;
+        if (stat.size > 16 * 1024 * 1024) {
+            // Files over 16 MB get a size/mtime-only fingerprint. Avoids blowing
+            // out memory on huge binaries while still giving us a change signal.
+            return `${path}|${stat.size}|${stat.mtimeMs.toFixed(0)}|skip`;
+        }
+        const contentHash = sha256(readFileSync(path).toString('hex'));
+        return `${path}|${stat.size}|${stat.mtimeMs.toFixed(0)}|${contentHash.slice(0, 16)}`;
+    }
+    catch {
+        return null;
+    }
+}
+function safeErrorSummary(input) {
+    if (!input)
+        return { text: null, hits: [] };
+    const trimmed = input.length > MAX_ERROR_SUMMARY_CHARS
+        ? input.slice(0, MAX_ERROR_SUMMARY_CHARS) + '…[truncated]'
+        : input;
+    const result = redact(trimmed);
+    return { text: result.text, hits: result.redactions };
+}
+/**
+ * Extract a one-line text summary from a tool result. Used when caller
+ * provides raw output text; we never store the raw content, only the summary.
+ */
+export function summarizeOutput(output, maxChars = 240) {
+    if (output == null)
+        return null;
+    const text = typeof output === 'string' ? output : safeStringify(output);
+    if (!text)
+        return null;
+    const firstLine = text.split(/\r?\n/).find(line => line.trim().length > 0) ?? text;
+    const trimmed = firstLine.trim();
+    if (trimmed.length <= maxChars)
+        return trimmed;
+    return trimmed.slice(0, maxChars - 1) + '…';
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function mergeHits(...sets) {
+    const counts = new Map();
+    for (const set of sets) {
+        for (const hit of set) {
+            counts.set(hit.class, (counts.get(hit.class) ?? 0) + hit.count);
+        }
+    }
+    return [...counts.entries()].map(([cls, count]) => ({ class: cls, count }));
+}
+export function observeTool(db, input) {
+    const errorSummary = safeErrorSummary(input.errorSummary);
+    const metadataRaw = {
+        ...(input.metadata ?? {}),
+    };
+    if (input.retainDetails) {
+        if (input.input !== undefined)
+            metadataRaw.redacted_input = input.input;
+        if (input.output !== undefined)
+            metadataRaw.redacted_output = input.output;
+    }
+    else {
+        const summary = summarizeOutput(input.output);
+        if (summary)
+            metadataRaw.output_summary = summary;
+    }
+    const { value: redactedMetadata, redactions: metadataHits } = redactJson(metadataRaw);
+    const fileFingerprints = (input.files ?? [])
+        .map(fingerprintFile)
+        .filter((fp) => fp != null);
+    const allHits = mergeHits(errorSummary.hits, metadataHits);
+    let redactionState;
+    if (allHits.length > 0) {
+        redactionState = 'redacted';
+    }
+    else if (input.retainDetails) {
+        redactionState = 'clean';
+    }
+    else {
+        redactionState = 'unreviewed';
+    }
+    const finalMetadata = redactedMetadata && Object.keys(redactedMetadata).length > 0
+        ? {
+            ...redactedMetadata,
+            ...(allHits.length > 0 ? { redactions: summarizeRedactions(allHits) } : {}),
+        }
+        : (allHits.length > 0 ? { redactions: summarizeRedactions(allHits) } : null);
+    const event = insertEvent(db, {
+        sessionId: input.sessionId ?? null,
+        eventType: input.event,
+        source: input.source ?? 'tool-trace',
+        actorAgent: input.actorAgent ?? null,
+        toolName: input.tool,
+        inputHash: hashOf(input.input),
+        outputHash: hashOf(input.output),
+        outcome: input.outcome ?? (input.event === 'PostToolUseFailure' ? 'failed' : null),
+        errorSummary: errorSummary.text,
+        cwd: input.cwd ?? null,
+        fileFingerprints,
+        redactionState,
+        metadata: finalMetadata,
+    });
+    return { event, redactions: allHits };
+}
+//# sourceMappingURL=tool-trace.js.map

package/dist/src/tool-trace.js.map

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