useathena 0.1.0

package/dist/eval/run-eval.js

@@ -0,0 +1,46 @@
+import { LlmHypothesisEngine } from "../engine/engine.js";
+import { modelClientFromSpec, resolveModelSpec } from "../model/registry.js";
+import { loadConfig } from "../config.js";
+import { LlmJudge, RubricJudge } from "./judge.js";
+import { formatReport, runEval } from "./harness.js";
+import { GOLDEN_SCENARIOS } from "./scenarios.js";
+/**
+ * Run the real engine against the golden scenarios.
+ *
+ *   npm run eval                          # rubric judge (free, keyword floor)
+ *   npm run eval -- --judge llm           # LLM judge (the real measure)
+ *   ATHENA_MODEL=cli:claude:haiku npm run eval
+ */
+const config = loadConfig();
+const spec = resolveModelSpec(config);
+const useLlmJudge = process.argv.includes("--judge") && process.argv[process.argv.indexOf("--judge") + 1] === "llm";
+const model = modelClientFromSpec(spec, config);
+const inner = new LlmHypothesisEngine(model);
+const judge = useLlmJudge ? new LlmJudge(model) : new RubricJudge();
+// Capture what the engine inferred so the report is inspectable, not just scoreable.
+const inferred = new Map();
+const engine = {
+    infer: async (instances) => {
+        const hypotheses = await inner.infer(instances);
+        inferred.set(instances[0]?.situation.domain ?? "unknown", hypotheses);
+        return hypotheses;
+    },
+};
+console.log(`engine model: ${model.id}   judge: ${useLlmJudge ? `llm (${model.id})` : "rubric"}`);
+console.log(`scenarios: ${GOLDEN_SCENARIOS.map((s) => s.id).join(", ")}\n`);
+const startedAt = Date.now();
+const report = await runEval(engine, GOLDEN_SCENARIOS, judge);
+console.log(formatReport(report));
+console.log(`\ndone in ${Math.round((Date.now() - startedAt) / 1000)}s`);
+for (const scenario of report.scenarios) {
+    const golden = GOLDEN_SCENARIOS.find((s) => s.id === scenario.scenarioId);
+    const domain = golden?.train[0]?.situation.domain ?? "unknown";
+    console.log(`\n=== ${scenario.scenarioId} — inferred rules ===`);
+    for (const hypothesis of inferred.get(domain) ?? []) {
+        const flag = scenario.falseHypothesisIds.includes(hypothesis.id) ? "  [UNMATCHED BY RUBRIC]" : "";
+        console.log(`- (${hypothesis.status}, conf ${hypothesis.confidence}, replay ${hypothesis.replay.reproduced}/${hypothesis.replay.tested})${flag}\n` +
+            `  ${hypothesis.rule}\n` +
+            (hypothesis.appliesWhen.length ? `  applies: ${hypothesis.appliesWhen.join("; ")}\n` : "") +
+            (hypothesis.doesNotApplyWhen.length ? `  except:  ${hypothesis.doesNotApplyWhen.join("; ")}` : ""));
+    }
+}

package/dist/eval/scenarios.js

@@ -0,0 +1,470 @@
+import { makeInstance } from "../core/fixtures.js";
+let sequence = 0;
+function correction(input) {
+    sequence += 1;
+    return makeInstance({
+        kind: input.kind ?? "correction",
+        observedAt: new Date(Date.UTC(2026, 4, 1) + sequence * 3_600_000).toISOString(),
+        situation: { summary: input.summary, domain: input.domain, cues: [], objectIds: [] },
+        before: { mediaType: "text/plain", content: input.before, contentHash: `fix-${sequence}-a` },
+        after: { mediaType: "text/plain", content: input.after, contentHash: `fix-${sequence}-b` },
+        diff: {
+            summary: input.diffSummary,
+            hunks: [{ before: input.before, after: input.after }],
+            magnitude: input.magnitude ?? "minor",
+        },
+    });
+}
+// --- 1. Em-dash removal (crisp lexical rule, cross-channel) ---
+const emdash = {
+    id: "emdash",
+    title: "Removes em-dashes from drafted text",
+    planted: [
+        {
+            key: "emdash.remove",
+            statement: "Remove em-dashes from drafts; use commas, periods, or parentheses instead.",
+            domain: "writing.style",
+            mustMention: [
+                ["em-dash", "em dash", "—", "dash"],
+                ["remove", "avoid", "replace", "without", "no ", "never"],
+            ],
+        },
+    ],
+    train: [
+        correction({
+            domain: "writing.style",
+            summary: "editing agent-drafted follow-up email to a prospect",
+            before: "We're aligned on pricing — let's move to the legal review.",
+            after: "We're aligned on pricing. Let's move to the legal review.",
+            diffSummary: "replaced em-dash with a period",
+        }),
+        correction({
+            domain: "writing.style",
+            summary: "editing agent-drafted LinkedIn post",
+            before: "Great conversation today — lots to unpack — more on this soon.",
+            after: "Great conversation today, lots to unpack. More on this soon.",
+            diffSummary: "replaced two em-dashes with comma and period",
+        }),
+        correction({
+            domain: "writing.style",
+            summary: "editing agent-drafted Slack summary",
+            before: "Checked the Q2 numbers — they match the board deck.",
+            after: "Checked the Q2 numbers, they match the board deck.",
+            diffSummary: "replaced em-dash with a comma",
+        }),
+        correction({
+            domain: "writing.style",
+            summary: "editing agent-drafted product one-pager",
+            before: "Our wedge — tacit knowledge capture — is hard to copy.",
+            after: "Our wedge (tacit knowledge capture) is hard to copy.",
+            diffSummary: "replaced em-dash pair with parentheses",
+        }),
+    ],
+    heldOut: [
+        {
+            instance: correction({
+                domain: "writing.style",
+                summary: "editing agent-drafted intro email",
+                before: "Happy to intro you to Lena — she runs RevOps at Klar.",
+                after: "Happy to intro you to Lena. She runs RevOps at Klar.",
+                diffSummary: "replaced em-dash with a period",
+            }),
+            kind: "apply",
+            ruleKey: "emdash.remove",
+            expectMention: [["em-dash", "em dash", "—", "dash"]],
+        },
+    ],
+};
+// --- 2. LinkedIn connection-note tone (calibration band: not salesy, not dry) ---
+const linkedinTone = {
+    id: "linkedin-tone",
+    title: "Connection notes: personal and specific, neither pitch nor boilerplate",
+    planted: [
+        {
+            key: "linkedin.note_band",
+            statement: "LinkedIn connection notes should be brief and personal: reference something specific about the recipient; no product pitch or meeting ask, but no empty boilerplate either.",
+            domain: "linkedin.connection_note",
+            mustMention: [
+                ["personal", "specific", "reference"],
+                ["pitch", "salesy", "sell", "demo", "promotional"],
+                ["boilerplate", "generic", "dry", "empty"],
+            ],
+        },
+    ],
+    alsoAcceptable: [
+        {
+            key: "linkedin.soft_close",
+            statement: "Close connection notes with a soft ask-free line like 'Would be glad to connect.'",
+            domain: "linkedin.connection_note",
+            mustMention: [["glad to connect", "soft", "close", "closing"]],
+        },
+    ],
+    train: [
+        correction({
+            domain: "linkedin.connection_note",
+            summary: "connection note to a RevOps lead, draft was a pitch",
+            before: "Hi Maria, athena cuts agent errors by 40%. Want to book a quick demo this week? Here's my calendar link.",
+            after: "Hi Maria, your post on why agent pilots stall in RevOps matched what we keep hearing. Would be glad to connect.",
+            diffSummary: "removed product pitch, demo ask, and calendar link; added reference to her post",
+            magnitude: "rewrite",
+        }),
+        correction({
+            domain: "linkedin.connection_note",
+            summary: "connection note to a conference speaker, draft was promotional",
+            before: "Hi Jonas, we're building the future of agent reliability. Check out athena and let's set up a call.",
+            after: "Hi Jonas, your SaaStr talk on tacit knowledge in sales teams stuck with me. Would be glad to connect.",
+            diffSummary: "removed promotion and call ask; referenced his talk",
+            magnitude: "rewrite",
+        }),
+        correction({
+            domain: "linkedin.connection_note",
+            summary: "connection note to a CTO, draft was empty boilerplate",
+            before: "Hi Tom, I'd like to add you to my professional network.",
+            after: "Hi Tom, your point about CRM data rot was spot on. We hear the same from every RevOps team. Would be glad to connect.",
+            diffSummary: "replaced generic boilerplate with a specific reference to his content",
+            magnitude: "rewrite",
+        }),
+        correction({
+            domain: "linkedin.connection_note",
+            summary: "connection note to a founder, draft was generic",
+            before: "Hello Anna, expanding my network in the GTM space. Let's connect.",
+            after: "Hello Anna, loved how you framed design partners as co-builders in your newsletter. Would be glad to connect.",
+            diffSummary: "replaced generic networking line with a specific reference to her newsletter",
+            magnitude: "rewrite",
+        }),
+        correction({
+            domain: "linkedin.connection_note",
+            summary: "connection note to a VP Sales, draft pitched in the second sentence",
+            before: "Hi Priya, great panel yesterday. By the way, athena could fix your team's follow-up problem, want a demo?",
+            after: "Hi Priya, great panel yesterday. Your line about reps drowning in tools was the highlight. Would be glad to connect.",
+            diffSummary: "kept the personal opener, removed the pitch and demo ask",
+        }),
+    ],
+    heldOut: [
+        {
+            instance: correction({
+                domain: "linkedin.connection_note",
+                summary: "connection note to a sales engineer, draft was salesy",
+                before: "Hi Omar, athena makes agents reliable. Free trial this week only, interested?",
+                after: "Hi Omar, your teardown of agent demos that fall apart in week two was brutal and accurate. Would be glad to connect.",
+                diffSummary: "removed pitch and urgency, added specific reference",
+                magnitude: "rewrite",
+            }),
+            kind: "apply",
+            ruleKey: "linkedin.note_band",
+            expectMention: [["pitch", "salesy", "sell", "demo", "promotional"]],
+        },
+        {
+            instance: correction({
+                domain: "linkedin.connection_note",
+                summary: "connection note to an analyst, draft was bare",
+                before: "Hi Dana, let's connect.",
+                after: "Hi Dana, your market map of agent memory vendors is the best one out there. Would be glad to connect.",
+                diffSummary: "replaced bare ask with specific reference to her work",
+                magnitude: "rewrite",
+            }),
+            kind: "apply",
+            ruleKey: "linkedin.note_band",
+            expectMention: [["specific", "personal", "reference"]],
+        },
+    ],
+};
+// --- 3. Slack brevity (context-conditional with a legitimate exception) ---
+const slackBrevity = {
+    id: "slack-brevity",
+    title: "Slack replies stay short unless detail is asked for",
+    planted: [
+        {
+            key: "slack.brevity",
+            statement: "Slack replies should be at most a few sentences unless the thread explicitly asks for a detailed write-up.",
+            domain: "slack.reply",
+            mustMention: [
+                ["short", "brief", "concise", "few sentences", "long"],
+            ],
+            boundaries: [
+                {
+                    statement: "Long-form is fine when someone explicitly asks for a detailed write-up or analysis.",
+                    mustMention: [["unless", "except", "asked", "asks", "request", "detail"]],
+                },
+            ],
+        },
+    ],
+    train: [
+        correction({
+            domain: "slack.reply",
+            summary: "reply to a status question in #gtm",
+            before: "Good question! So there are several aspects to consider here. First, the pipeline review showed that we have 14 open opportunities, of which 6 are in stage 3 or later. Second, the two enterprise deals are waiting on security review, which historically takes 2-3 weeks. Third, regarding the renewal cohort, I think we should also discuss the expansion potential, because if we look at usage data there are at least 4 accounts that crossed the seat threshold. Happy to go deeper on any of these!",
+            after: "6 of 14 opps are stage 3+. Both enterprise deals are in security review (2-3 weeks). Renewals look fine.",
+            diffSummary: "cut a seven-sentence reply to three short sentences with the key numbers",
+            magnitude: "rewrite",
+        }),
+        correction({
+            domain: "slack.reply",
+            summary: "reply to 'did the import finish?' in #eng",
+            before: "Yes! The import finished successfully. For context, we processed all the records from the staging environment and the deduplication step worked as expected. There were a few warnings about malformed rows but nothing blocking. Let me know if you want me to walk through the logs together sometime.",
+            after: "Yes, finished clean. A few malformed-row warnings, nothing blocking.",
+            diffSummary: "cut five sentences to two",
+            magnitude: "substantive",
+        }),
+        correction({
+            domain: "slack.reply",
+            summary: "reply to a quick scheduling check in DM",
+            before: "Thanks for asking! I checked my calendar and I have a few options. Tuesday is quite packed with the board prep, but Wednesday morning could work, and Thursday afternoon is also relatively free. I would say Wednesday is probably best but I'm flexible. What works best for you?",
+            after: "Wednesday morning or Thursday afternoon. Slight preference for Wednesday.",
+            diffSummary: "cut the reply to the two viable options",
+            magnitude: "substantive",
+        }),
+        correction({
+            domain: "slack.reply",
+            summary: "reply to 'any blockers?' in standup thread",
+            before: "Not really blockers per se, but there are a few things worth mentioning for visibility. The OAuth review is still pending on Google's side, which is expected at this stage. I'm also waiting for feedback on the pricing doc, though that's not urgent yet. Otherwise everything is moving along nicely and I'm optimistic about the timeline.",
+            after: "No blockers. OAuth review pending on Google's side (expected).",
+            diffSummary: "cut to the one fact that matters",
+            magnitude: "substantive",
+        }),
+    ],
+    heldOut: [
+        {
+            instance: correction({
+                domain: "slack.reply",
+                summary: "reply to 'can you write up the full analysis of the churned accounts?'",
+                before: "We lost 3 accounts this quarter. Acme churned over a missing integration: they asked for the HubSpot sync in January, we shipped half of it. Beta Corp's champion left in March and we never rebuilt the relationship with the new VP. Gamma's usage dropped 60% after their reorg and nobody flagged it. Common thread: all three had warning signs in usage data at least six weeks out. Proposal: weekly usage-drop alert plus a champion-change playbook.",
+                after: "We lost 3 accounts this quarter. Acme churned over a missing integration: they asked for the HubSpot sync in January, we shipped half of it. Beta Corp's champion left in March and we never rebuilt the relationship with the new VP. Gamma's usage dropped 60% after their reorg and nobody flagged it. Common thread: all three had warning signs in usage data at least six weeks out. Proposal: weekly usage-drop alert plus a champion-change playbook.",
+                diffSummary: "kept long-form as-is: a detailed write-up was explicitly requested",
+                kind: "approval",
+                magnitude: "trivial",
+            }),
+            kind: "boundary",
+            ruleKey: "slack.brevity",
+            expectMention: [["unless", "except", "asked", "asks", "request", "detail"]],
+        },
+        {
+            instance: correction({
+                domain: "slack.reply",
+                summary: "reply to 'how did the demo go?' in #gtm",
+                before: "The demo went really well overall! We started with the usual deck intro, then moved into the live product part. They especially liked the review queue, and the CTO asked several questions about the MCP integration, which I took as a strong buying signal. There were some concerns about pricing at the end but I think we handled them well. Next step is a technical deep-dive with their platform team, probably next week.",
+                after: "Went well. CTO dug into the MCP integration (good sign). Next: technical deep-dive with their platform team next week.",
+                diffSummary: "cut six sentences to three",
+                magnitude: "substantive",
+            }),
+            kind: "apply",
+            ruleKey: "slack.brevity",
+            expectMention: [["short", "brief", "concise", "few sentences", "long"]],
+        },
+    ],
+};
+// --- 4. External formality (boundary discrimination: ongoing vs first contact) ---
+const externalFormality = {
+    id: "external-formality",
+    title: "Warm and direct with known externals; stiff formality only for first contact",
+    planted: [
+        {
+            key: "external.warmth",
+            statement: "With external partners we already work with, drop stiff formality: warm, direct, professional tone. Keep formal register only for first contact with senior executives.",
+            domain: "email.external",
+            mustMention: [
+                ["formal", "formality", "stiff"],
+                ["warm", "direct", "relaxed", "casual"],
+            ],
+            boundaries: [
+                {
+                    statement: "First contact with senior executives stays formal.",
+                    mustMention: [
+                        [
+                            "first contact",
+                            "first-contact",
+                            "first outreach",
+                            "first email",
+                            "cold outreach",
+                            "new contact",
+                            "no existing relationship",
+                            "no established relationship",
+                            "senior",
+                            "executive",
+                        ],
+                    ],
+                },
+            ],
+        },
+    ],
+    alsoAcceptable: [
+        {
+            key: "external.concrete_commitments",
+            statement: "Replace vague hedged commitments ('in due course', 'whether you might be available') with concrete specifics: a day, a duration.",
+            domain: "email.external",
+            mustMention: [
+                ["concrete", "specific", "bounded"],
+                ["vague", "hedge", "in due course", "open-ended"],
+            ],
+        },
+    ],
+    train: [
+        correction({
+            domain: "email.external",
+            summary: "recap email to a partner we've worked with for months",
+            before: "Dear Mr. Petersen, I hope this message finds you well. Pursuant to our discussion on Tuesday, please find below a summary of the agreed action items for your kind consideration.",
+            after: "Hi Lars, great talking Tuesday. Quick recap of what we agreed:",
+            diffSummary: "dropped formal salutation and stiff phrasing for warm direct tone with a known partner",
+            magnitude: "rewrite",
+        }),
+        correction({
+            domain: "email.external",
+            summary: "reply to a design partner's feedback email",
+            before: "Dear Ms. Okafor, thank you very much for your valuable feedback. We are most grateful for the time you have invested and shall revert with a detailed response in due course.",
+            after: "Hi Amara, this is exactly the feedback we needed, thank you. I'll get back to you with details by Thursday.",
+            diffSummary: "replaced stiff gratitude formula with warm direct reply and a concrete commitment",
+            magnitude: "rewrite",
+        }),
+        correction({
+            domain: "email.external",
+            summary: "scheduling email to an agency contact we talk to weekly",
+            before: "Dear Mr. Brandt, I would like to kindly inquire whether you might be available for a call next week.",
+            after: "Hi Felix, do you have 30 minutes next week?",
+            diffSummary: "cut formal inquiry to a direct question for a weekly contact",
+            magnitude: "substantive",
+        }),
+        correction({
+            domain: "email.external",
+            summary: "follow-up to a customer champion after the QBR",
+            before: "Dear Mrs. Lindqvist, it was a pleasure to meet with you and your esteemed colleagues. We remain at your disposal should any questions arise.",
+            after: "Hi Sara, really enjoyed the session with your team. Ping me anytime if questions come up.",
+            diffSummary: "dropped ceremonial closing for warm direct tone with an established champion",
+            magnitude: "rewrite",
+        }),
+    ],
+    heldOut: [
+        {
+            instance: correction({
+                domain: "email.external",
+                summary: "first cold email to the CFO of an enterprise prospect",
+                before: "Dear Mr. Tanaka, I hope this message finds you well. I am writing to introduce athena and to ask whether a brief conversation might be of interest.",
+                after: "Dear Mr. Tanaka, I hope this message finds you well. I am writing to introduce athena and to ask whether a brief conversation might be of interest.",
+                diffSummary: "kept formal register: first contact with a senior executive",
+                kind: "approval",
+                magnitude: "trivial",
+            }),
+            kind: "boundary",
+            ruleKey: "external.warmth",
+            expectMention: [
+                [
+                    "first contact",
+                    "first-contact",
+                    "first outreach",
+                    "first email",
+                    "cold outreach",
+                    "new contact",
+                    "no existing relationship",
+                    "no established relationship",
+                    "senior",
+                    "executive",
+                ],
+            ],
+        },
+        {
+            instance: correction({
+                domain: "email.external",
+                summary: "status email to an implementation partner we work with daily",
+                before: "Dear Mr. Novak, please be advised that the integration milestone has been reached as per the agreed schedule.",
+                after: "Hi Petr, milestone done, right on schedule.",
+                diffSummary: "dropped stiff formal notice for direct update to a daily collaborator",
+                magnitude: "rewrite",
+            }),
+            kind: "apply",
+            ruleKey: "external.warmth",
+            expectMention: [["warm", "direct", "relaxed", "casual"]],
+        },
+    ],
+};
+// --- 5. Meeting scheduling push (calibration band: concrete CTA, no pressure) ---
+const meetingPush = {
+    id: "meeting-push",
+    title: "Always propose a concrete next step, never with pressure",
+    planted: [
+        {
+            key: "scheduling.band",
+            statement: "When closing a message, always propose a concrete next meeting (one or two specific options), but without pressure tactics or assumed commitment.",
+            domain: "email.scheduling",
+            mustMention: [
+                ["concrete", "specific", "propose", "options", "next step"],
+                ["pressure", "pushy", "assume", "force"],
+            ],
+        },
+    ],
+    train: [
+        correction({
+            domain: "email.scheduling",
+            summary: "closing of a follow-up email, draft was pushy",
+            before: "I'll send a calendar invite for tomorrow 9am. Looking forward to closing this!",
+            after: "Would Tuesday or Thursday afternoon work for a 30-minute follow-up? Happy to adjust.",
+            diffSummary: "replaced assumed commitment and urgency with two concrete options",
+            magnitude: "rewrite",
+        }),
+        correction({
+            domain: "email.scheduling",
+            summary: "closing of a demo recap, draft had no next step",
+            before: "Thanks again for your time. Let me know if you ever want to chat further.",
+            after: "Thanks again for your time. Would early next week work for a technical deep-dive? Tuesday or Wednesday morning are both open.",
+            diffSummary: "replaced vague open-ended closing with a concrete proposal and two options",
+            magnitude: "substantive",
+        }),
+        correction({
+            domain: "email.scheduling",
+            summary: "closing of a pricing discussion email, draft was pushy",
+            before: "This offer expires Friday, so we should get a contract call on the books today. When can you sign?",
+            after: "Happy to walk through the proposal together. Would Thursday or Friday work for a short call?",
+            diffSummary: "removed deadline pressure and signing push; proposed two call options",
+            magnitude: "rewrite",
+        }),
+        correction({
+            domain: "email.scheduling",
+            summary: "closing of a re-engagement email, draft had no ask",
+            before: "Hope things are going well on your side. Don't hesitate to reach out anytime.",
+            after: "Hope things are going well on your side. Worth a 20-minute catch-up? Next Wednesday or Friday morning would work here.",
+            diffSummary: "added a concrete low-pressure meeting proposal with two options",
+            magnitude: "substantive",
+        }),
+        correction({
+            domain: "email.scheduling",
+            summary: "closing of an intro email, draft assumed the meeting",
+            before: "I've gone ahead and booked us 45 minutes on Monday. See you then!",
+            after: "Would a 30-minute intro call help? Monday or Tuesday afternoon both work on my side.",
+            diffSummary: "replaced pre-booked meeting with a proposal and options",
+            magnitude: "rewrite",
+        }),
+    ],
+    heldOut: [
+        {
+            instance: correction({
+                domain: "email.scheduling",
+                summary: "closing of a check-in email, draft trailed off without an ask",
+                before: "Anyway, lots happening on our side too. Talk soon!",
+                after: "Anyway, lots happening on our side too. Want to swap notes for 20 minutes? Thursday or Friday would work here.",
+                diffSummary: "added a concrete two-option proposal to a closing that had none",
+                magnitude: "substantive",
+            }),
+            kind: "apply",
+            ruleKey: "scheduling.band",
+            expectMention: [["concrete", "specific", "propose", "options", "next step"]],
+        },
+        {
+            instance: correction({
+                domain: "email.scheduling",
+                summary: "closing of a negotiation email, draft pressured for commitment",
+                before: "We need your decision by end of week. Can you confirm a signing call for Thursday?",
+                after: "Take the time you need with the proposal. If a call would help, Thursday or early next week both work here.",
+                diffSummary: "removed deadline pressure, kept a concrete but optional call offer",
+                magnitude: "rewrite",
+            }),
+            kind: "apply",
+            ruleKey: "scheduling.band",
+            expectMention: [["pressure", "pushy", "assume", "force"]],
+        },
+    ],
+};
+export const GOLDEN_SCENARIOS = [
+    emdash,
+    linkedinTone,
+    slackBrevity,
+    externalFormality,
+    meetingPush,
+];

package/dist/mcp/server.js

@@ -0,0 +1,107 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ingestSensorEvent } from "../capture/ingest.js";
+import { compileBrief } from "../serve/brief.js";
+import { recordOutcome } from "../serve/outcome.js";
+import { openRef } from "../store/open.js";
+/**
+ * The agent surface: exactly 4 tools (design rule 8). No durable-mutation
+ * tools — athena_record creates evidence and outcomes; rules change only
+ * through the engine and human review.
+ */
+const INSTANCE_KINDS = [
+    "correction",
+    "override",
+    "decision",
+    "escalation",
+    "failed_attempt",
+    "approval",
+    "manual_note",
+];
+const OUTCOME_RESULTS = ["uncorrected", "corrected", "abandoned", "unknown"];
+export function buildMcpServer(store) {
+    const server = new McpServer({ name: "athena", version: "0.1.0" });
+    server.registerTool("athena_brief", {
+        description: "Call this BEFORE acting on a task. Returns the tacit judgment rules that apply (with confidence and boundary conditions), relevant facts with citations, things you must not assume, open questions, and a readiness verdict (act / act_with_caveats / inspect_first / ask_human). Honor the boundaries and do-not-assume list. After finishing the task, report what happened with athena_record type=outcome, citing the briefId.",
+        inputSchema: {
+            task: z.string().describe("The task you are about to perform, in one sentence"),
+            domain: z
+                .string()
+                .optional()
+                .describe('Optional dot-path domain, e.g. "email.outreach", "slack.reply", "code.review"'),
+        },
+    }, ({ task, domain }) => {
+        const brief = compileBrief(store, domain !== undefined ? { task, domain } : { task });
+        return asJson(brief);
+    });
+    server.registerTool("athena_open", {
+        description: "Dereference any athena:// ref from a brief or search result: the full hypothesis with evidence links, the underlying judgment instance (the actual correction), a source, an object, a brief, or an outcome.",
+        inputSchema: { ref: z.string().describe("An athena:// ref, e.g. athena://hypothesis/hyp_...") },
+    }, ({ ref }) => {
+        const entity = openRef(store, ref);
+        if (!entity)
+            throw new Error(`${ref} does not exist`);
+        return asJson(entity);
+    });
+    server.registerTool("athena_record", {
+        description: "Report back to athena. type=outcome: after a task where you used a brief, report whether your output was accepted unchanged (uncorrected) or edited by the human (corrected) — this is how rules earn or lose trust. type=event: capture a judgment moment you observed (a correction of your output, a human decision, a failed approach, an explicit 'remember this'). Events become evidence for new rules after review; nothing you record changes durable rules directly.",
+        inputSchema: {
+            type: z.enum(["outcome", "event"]),
+            briefId: z.string().optional().describe("outcome: the brief this outcome judges"),
+            result: z.enum(OUTCOME_RESULTS).optional().describe("outcome: what happened"),
+            correctionInstanceId: z
+                .string()
+                .optional()
+                .describe("outcome: if corrected, the instance id of the captured correction (record the event first)"),
+            kind: z.enum(INSTANCE_KINDS).optional().describe("event: what kind of judgment moment"),
+            summary: z.string().optional().describe("event: one-line situation summary"),
+            domain: z.string().optional().describe('event: dot-path domain, e.g. "email.outreach"'),
+            task: z.string().optional().describe("event: what was being attempted"),
+            before: z.string().optional().describe("event: the draft/output before the human acted"),
+            after: z.string().optional().describe("event: the human's version (omit for approvals)"),
+            app: z.string().optional().describe("event: where this happened (gmail, slack, claude-code...)"),
+        },
+    }, (args) => {
+        if (args.type === "outcome") {
+            if (!args.briefId || !args.result)
+                throw new Error("outcome requires briefId and result");
+            const outcome = recordOutcome(store, {
+                briefId: args.briefId,
+                result: args.result,
+                ...(args.correctionInstanceId
+                    ? { correctionInstanceId: args.correctionInstanceId }
+                    : {}),
+            });
+            return asJson(outcome);
+        }
+        if (!args.kind || !args.summary)
+            throw new Error("event requires kind and summary");
+        const event = {
+            sensorId: "sen_mcp",
+            emittedAt: new Date().toISOString(),
+            kind: args.kind,
+            situation: {
+                summary: args.summary,
+                ...(args.domain !== undefined ? { domain: args.domain } : {}),
+                ...(args.task !== undefined ? { task: args.task } : {}),
+                ...(args.app !== undefined ? { app: args.app } : {}),
+            },
+            ...(args.before !== undefined ? { before: { mediaType: "text/plain", content: args.before } } : {}),
+            ...(args.after !== undefined ? { after: { mediaType: "text/plain", content: args.after } } : {}),
+        };
+        const instance = ingestSensorEvent(store, event);
+        return asJson({ recorded: instance.id, kind: instance.kind, domain: instance.situation.domain });
+    });
+    server.registerTool("athena_search", {
+        description: "Lexical search across captured judgment instances, learned rules, and sources. Returns athena:// refs ranked by relevance — open them with athena_open.",
+        inputSchema: {
+            query: z.string(),
+            lane: z.enum(["instance", "hypothesis", "source"]).optional().describe("Restrict to one lane"),
+            limit: z.number().int().min(1).max(50).optional(),
+        },
+    }, ({ query, lane, limit }) => asJson(store.search(query, lane, limit ?? 20)));
+    return server;
+}
+function asJson(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}

package/dist/mcp-server.js

@@ -0,0 +1,7 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildMcpServer } from "./mcp/server.js";
+import { AthenaStore } from "./store/store.js";
+import { dbPath } from "./config.js";
+const store = new AthenaStore(dbPath());
+const server = buildMcpServer(store);
+await server.connect(new StdioServerTransport());