useathena 0.1.0

package/dist/model/api-model-client.js

@@ -0,0 +1,99 @@
+import { extractJson } from "./cli-model-client.js";
+/**
+ * API providers over plain fetch — no provider SDKs (design rule: dependencies
+ * are a product decision; the surface we need is one POST per inference).
+ *
+ * Two wire formats cover the landscape:
+ * - Anthropic Messages API (api.anthropic.com)
+ * - OpenAI-compatible chat completions (OpenAI itself, Ollama, LM Studio,
+ *   vLLM, llama.cpp — anything exposing /chat/completions)
+ */
+const DEFAULT_TIMEOUT_MS = 240_000;
+const DEFAULT_MAX_TOKENS = 16_000;
+export class AnthropicApiModelClient {
+    options;
+    id;
+    baseUrl;
+    constructor(options) {
+        this.options = options;
+        this.id = `anthropic:${options.model}`;
+        this.baseUrl = (options.baseUrl ?? "https://api.anthropic.com").replace(/\/$/, "");
+    }
+    async generateJson(request) {
+        if (!this.options.apiKey) {
+            throw new Error("anthropic provider needs an API key — set ANTHROPIC_API_KEY or run: athena setup");
+        }
+        const body = await postJson(`${this.baseUrl}/v1/messages`, {
+            "x-api-key": this.options.apiKey,
+            "anthropic-version": "2023-06-01",
+        }, {
+            model: this.options.model,
+            max_tokens: DEFAULT_MAX_TOKENS,
+            system: request.system,
+            messages: [{ role: "user", content: request.prompt }],
+        }, this.options.timeoutMs);
+        const message = body;
+        if (message.stop_reason === "refusal") {
+            throw new Error("anthropic API declined the request (stop_reason: refusal)");
+        }
+        const text = message.content?.find((block) => block.type === "text")?.text;
+        if (typeof text !== "string") {
+            throw new Error(`anthropic API returned no text content: ${JSON.stringify(body).slice(0, 300)}`);
+        }
+        return extractJson(text);
+    }
+}
+export class OpenAiCompatibleModelClient {
+    options;
+    id;
+    baseUrl;
+    constructor(options, providerLabel = "openai") {
+        this.options = options;
+        this.id = `${providerLabel}:${options.model}`;
+        this.baseUrl = (options.baseUrl ?? "https://api.openai.com/v1").replace(/\/$/, "");
+    }
+    async generateJson(request) {
+        const headers = {};
+        if (this.options.apiKey)
+            headers.authorization = `Bearer ${this.options.apiKey}`;
+        const body = await postJson(`${this.baseUrl}/chat/completions`, headers, {
+            model: this.options.model,
+            messages: [
+                { role: "system", content: request.system },
+                { role: "user", content: request.prompt },
+            ],
+        }, this.options.timeoutMs);
+        const completion = body;
+        const text = completion.choices?.[0]?.message?.content;
+        if (typeof text !== "string") {
+            throw new Error(`${this.id} returned no message content: ${JSON.stringify(body).slice(0, 300)}`);
+        }
+        return extractJson(text);
+    }
+}
+async function postJson(url, headers, body, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...headers },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            throw new Error(`${url} returned ${response.status}: ${text.slice(0, 300)}`);
+        }
+        return JSON.parse(text);
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new Error(`${url} timed out after ${timeoutMs}ms`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/model/cli-model-client.js

@@ -0,0 +1,111 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * CLI-runner providers: inference through a locally authenticated agent CLI,
+ * so a Claude or ChatGPT subscription powers the engine with no API key.
+ *
+ * Verified against real installs: `claude -p --output-format json` and
+ * `codex exec` (prompt on stdin, final message via --output-last-message).
+ */
+const DEFAULT_TIMEOUT_MS = 240_000;
+export class ClaudeCliModelClient {
+    options;
+    id;
+    constructor(options = {}) {
+        this.options = options;
+        this.id = `cli:claude${options.model ? `:${options.model}` : ""}`;
+    }
+    async generateJson(request) {
+        const args = ["-p", "--output-format", "json", "--max-turns", "1"];
+        if (this.options.model)
+            args.push("--model", this.options.model);
+        const stdout = await run("claude", args, `${request.system}\n\n${request.prompt}`, this.options.timeoutMs);
+        const envelope = JSON.parse(stdout);
+        if (envelope.is_error || typeof envelope.result !== "string") {
+            throw new Error(`claude CLI returned an error envelope: ${stdout.slice(0, 300)}`);
+        }
+        return extractJson(envelope.result);
+    }
+}
+export class CodexCliModelClient {
+    options;
+    id;
+    constructor(options = {}) {
+        this.options = options;
+        this.id = `cli:codex${options.model ? `:${options.model}` : ""}`;
+    }
+    async generateJson(request) {
+        // codex exec has no single-shot JSON mode; the final agent message lands
+        // in --output-last-message. Ephemeral + read-only keeps an inference call
+        // from touching the workspace or leaving session files behind.
+        const outFile = join(tmpdir(), `athena-codex-${randomUUID()}.txt`);
+        const args = [
+            "exec",
+            "--ephemeral",
+            "--skip-git-repo-check",
+            "--sandbox", "read-only",
+            "--color", "never",
+            "--output-last-message", outFile,
+        ];
+        if (this.options.model)
+            args.push("--model", this.options.model);
+        args.push("-");
+        try {
+            await run("codex", args, `${request.system}\n\n${request.prompt}`, this.options.timeoutMs);
+            const text = readFileSync(outFile, "utf8");
+            return extractJson(text);
+        }
+        finally {
+            rmSync(outFile, { force: true });
+        }
+    }
+}
+function run(command, args, stdin, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            reject(new Error(`${command} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => (stdout += chunk.toString()));
+        child.stderr.on("data", (chunk) => (stderr += chunk.toString()));
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve(stdout);
+            else
+                reject(new Error(`${command} exited ${code}: ${stderr.slice(0, 300)}`));
+        });
+        child.stdin.write(stdin);
+        child.stdin.end();
+    });
+}
+/** Models wrap JSON in prose or fences more often than they should. Extract the first JSON value. */
+export function extractJson(text) {
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
+    const body = fenced?.[1] ?? text;
+    const start = body.search(/[{[]/);
+    if (start === -1)
+        throw new Error(`no JSON found in model output: ${text.slice(0, 200)}`);
+    for (let end = body.length; end > start; end--) {
+        const slice = body.slice(start, end).trim();
+        if (!slice.endsWith("}") && !slice.endsWith("]"))
+            continue;
+        try {
+            return JSON.parse(slice);
+        }
+        catch {
+            // keep shrinking — trailing prose after the JSON value
+        }
+    }
+    throw new Error(`unparseable JSON in model output: ${text.slice(0, 200)}`);
+}

package/dist/model/model-client.js

@@ -0,0 +1,28 @@
+/**
+ * Model-agnostic LLM access. The core never assumes a provider.
+ *
+ * Planned providers (MVP requirement — subscriptions must work, no API key needed):
+ * - API: Anthropic, OpenAI-compatible endpoints (incl. local: Ollama, LM Studio)
+ * - CLI runners: `claude -p --output-format json`, `codex exec --json` — uses the
+ *   user's existing Claude/ChatGPT subscription via the locally authenticated tool.
+ *
+ * The interface is deliberately the lowest common denominator of all of those:
+ * one-shot, non-streaming, JSON out. CLI runners can't stream; nothing here may
+ * ever require streaming, token counts, or provider-specific tool calling.
+ */
+/** Scripted client for tests: returns queued responses in order. */
+export class MockModelClient {
+    id = "mock:scripted";
+    requests = [];
+    responses;
+    constructor(responses) {
+        this.responses = [...responses];
+    }
+    generateJson(request) {
+        this.requests.push(request);
+        if (this.responses.length === 0) {
+            return Promise.reject(new Error("MockModelClient: no scripted responses left"));
+        }
+        return Promise.resolve(this.responses.shift());
+    }
+}

package/dist/model/registry.js

@@ -0,0 +1,67 @@
+import { ClaudeCliModelClient, CodexCliModelClient } from "./cli-model-client.js";
+import { AnthropicApiModelClient, OpenAiCompatibleModelClient } from "./api-model-client.js";
+/**
+ * Model specs are provider:model strings, with an optional @baseUrl suffix for
+ * self-hosted OpenAI-compatible servers:
+ *
+ *   cli:claude[:model]                 claude CLI — Claude subscription, no key
+ *   cli:codex[:model]                  codex CLI — ChatGPT subscription, no key
+ *   anthropic[:model]                  Anthropic API (ANTHROPIC_API_KEY)
+ *   openai:<model>                     OpenAI API (OPENAI_API_KEY)
+ *   openai:<model>@<baseUrl>           any OpenAI-compatible server (LM Studio, vLLM, …)
+ *   ollama:<model>                     local Ollama (http://127.0.0.1:11434/v1)
+ *
+ * Resolution order for the active spec: ATHENA_MODEL env, then config.json
+ * (written by `athena setup`), then the cli:claude default.
+ */
+export const DEFAULT_MODEL_SPEC = "cli:claude";
+export const DEFAULT_ANTHROPIC_MODEL = "claude-opus-4-8";
+export const OLLAMA_BASE_URL = "http://127.0.0.1:11434/v1";
+export const SUPPORTED_SPECS = "cli:claude[:model], cli:codex[:model], anthropic[:model], openai:<model>[@baseUrl], ollama:<model>";
+export function resolveModelSpec(config = {}) {
+    return process.env.ATHENA_MODEL ?? config.model ?? DEFAULT_MODEL_SPEC;
+}
+export function modelClientFromSpec(spec, config = {}) {
+    const at = spec.indexOf("@");
+    const head = at === -1 ? spec : spec.slice(0, at);
+    const baseUrl = at === -1 ? undefined : spec.slice(at + 1);
+    const [provider, ...rest] = head.split(":");
+    const model = rest.join(":") || undefined;
+    switch (provider) {
+        case "cli": {
+            const [runner, cliModel] = [rest[0], rest.slice(1).join(":") || undefined];
+            if (runner === "claude")
+                return new ClaudeCliModelClient(cliModel !== undefined ? { model: cliModel } : {});
+            if (runner === "codex")
+                return new CodexCliModelClient(cliModel !== undefined ? { model: cliModel } : {});
+            throw new Error(`unknown CLI runner "${runner}" — supported: ${SUPPORTED_SPECS}`);
+        }
+        case "anthropic": {
+            const apiKey = process.env.ANTHROPIC_API_KEY ?? config.keys?.anthropic;
+            return new AnthropicApiModelClient({
+                model: model ?? DEFAULT_ANTHROPIC_MODEL,
+                ...(apiKey !== undefined ? { apiKey } : {}),
+                ...(baseUrl !== undefined ? { baseUrl } : {}),
+            });
+        }
+        case "openai": {
+            if (!model) {
+                throw new Error(`openai spec needs a model, e.g. "openai:gpt-5.2" or "openai:<model>@http://localhost:1234/v1"`);
+            }
+            const apiKey = process.env.OPENAI_API_KEY ?? config.keys?.openai;
+            return new OpenAiCompatibleModelClient({
+                model,
+                ...(apiKey !== undefined ? { apiKey } : {}),
+                ...(baseUrl !== undefined ? { baseUrl } : {}),
+            });
+        }
+        case "ollama": {
+            if (!model) {
+                throw new Error(`ollama spec needs a model, e.g. "ollama:llama3.3" (see: ollama list)`);
+            }
+            return new OpenAiCompatibleModelClient({ model, baseUrl: baseUrl ?? OLLAMA_BASE_URL }, "ollama");
+        }
+        default:
+            throw new Error(`unknown model spec "${spec}" — supported: ${SUPPORTED_SPECS}`);
+    }
+}

package/dist/sensors/claude-code-hook.js

@@ -0,0 +1,131 @@
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { basename } from "node:path";
+import { ingestSensorEvent } from "../capture/ingest.js";
+const EXPLICIT_MARKER = /^(remember|athena)\s*[:,]\s*(.+)$/is;
+/** Redirects at the start of a prompt: the user is stopping or reversing the agent. */
+const REDIRECT_START = /^(no|nope|wrong|wait|stop|hold on|don't|do not|undo|revert|not like that)\b/i;
+/** Soft openers that look like redirects but aren't. */
+const REDIRECT_START_EXCEPTIONS = /^no (worries|problem|rush|need)\b/i;
+/** Correction phrases anywhere in the prompt. */
+const REDIRECT_INLINE = /\b(that's (wrong|not right|not what)|not what i (asked|meant|wanted)|why did you|you should(n't| not) have|i didn't ask (for|you)|never do that|don't do that again|you keep|again with)\b/i;
+export function detectSignal(prompt) {
+    const trimmed = prompt.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    const explicit = EXPLICIT_MARKER.exec(trimmed);
+    if (explicit) {
+        return { kind: "manual_note", note: explicit[2].trim(), reason: "explicit_marker" };
+    }
+    if (REDIRECT_START.test(trimmed) && !REDIRECT_START_EXCEPTIONS.test(trimmed)) {
+        return { kind: "override", reason: "redirect_opener" };
+    }
+    if (REDIRECT_INLINE.test(trimmed)) {
+        return { kind: "override", reason: "correction_phrase" };
+    }
+    return undefined;
+}
+export function handleUserPrompt(store, input) {
+    const signal = detectSignal(input.prompt);
+    if (!signal)
+        return { captured: null, reason: "no signal" };
+    const project = input.cwd ? basename(input.cwd) : "general";
+    const domain = `code.${project}`;
+    const emittedAt = new Date().toISOString();
+    let event;
+    if (signal.kind === "manual_note") {
+        event = {
+            sensorId: "sen_claude_code",
+            emittedAt,
+            kind: "manual_note",
+            situation: {
+                summary: `explicit remember: ${truncate(signal.note, 100)}`,
+                domain,
+                app: "claude-code",
+            },
+            after: { mediaType: "text/plain", content: signal.note },
+        };
+    }
+    else {
+        const lastTurn = input.transcript_path ? lastAssistantTurn(input.transcript_path) : undefined;
+        event = {
+            sensorId: "sen_claude_code",
+            emittedAt,
+            kind: "override",
+            situation: {
+                summary: `user redirected the agent: ${truncate(input.prompt, 100)}`,
+                domain,
+                app: "claude-code",
+            },
+            ...(lastTurn !== undefined ? { before: { mediaType: "text/markdown", content: lastTurn } } : {}),
+            after: { mediaType: "text/plain", content: input.prompt },
+            raw: { reason: signal.reason, sessionId: input.session_id },
+        };
+    }
+    const instance = ingestSensorEvent(store, event);
+    return { captured: instance.id, kind: instance.kind };
+}
+const TAIL_BYTES = 64_000;
+const TURN_CAP = 2_000;
+/** Read the last assistant message (text + tool summary) from a Claude Code transcript. */
+export function lastAssistantTurn(transcriptPath) {
+    let raw;
+    try {
+        raw = readTail(transcriptPath, TAIL_BYTES);
+    }
+    catch {
+        return undefined;
+    }
+    const lines = raw.split("\n").slice(1); // drop the first, possibly partial, line
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (line.trim().length === 0)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const rendered = renderAssistantEntry(entry);
+        if (rendered !== undefined)
+            return rendered;
+    }
+    return undefined;
+}
+function renderAssistantEntry(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return undefined;
+    const record = entry;
+    if (record.type !== "assistant" || !Array.isArray(record.message?.content))
+        return undefined;
+    const parts = [];
+    for (const block of record.message.content) {
+        if (block.type === "text" && typeof block.text === "string" && block.text.trim().length > 0) {
+            parts.push(block.text.trim());
+        }
+        else if (block.type === "tool_use" && typeof block.name === "string") {
+            parts.push(`[tool: ${block.name}]`);
+        }
+    }
+    if (parts.length === 0)
+        return undefined;
+    return truncate(parts.join("\n"), TURN_CAP);
+}
+function readTail(path, bytes) {
+    const size = statSync(path).size;
+    const start = Math.max(0, size - bytes);
+    const length = size - start;
+    const buffer = Buffer.alloc(length);
+    const fd = openSync(path, "r");
+    try {
+        readSync(fd, buffer, 0, length, start);
+    }
+    finally {
+        closeSync(fd);
+    }
+    return buffer.toString("utf8");
+}
+function truncate(text, max) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}

package/dist/serve/brief.js

@@ -0,0 +1,95 @@
+import { newId } from "../core/ids.js";
+import { parseRef, refTo } from "../core/refs.js";
+/**
+ * Brief compilation: deterministic select-and-assemble over the store.
+ * No LLM call — the intelligence already happened (engine) or will happen
+ * (the agent reading the brief). Compilation must be fast, cheap, auditable.
+ *
+ * v1 readiness policy (documented heuristic, revisit with outcome data):
+ *   act               servable rule at high confidence, nothing contradicted
+ *   act_with_caveats  servable rules, but caveats or modest confidence
+ *   inspect_first     no rules, but facts/unvalidated patterns worth opening
+ *   ask_human         athena knows nothing useful for this task
+ */
+const MAX_RULES = 5;
+const MAX_FACTS = 3;
+const MAX_OPEN_QUESTIONS = 3;
+const HIGH_CONFIDENCE = 0.7;
+export function compileBrief(store, request, now = () => new Date()) {
+    const inScope = collectHypotheses(store, request);
+    const servable = inScope
+        .filter((h) => h.status === "validated" || h.status === "active")
+        .sort((a, b) => b.confidence - a.confidence);
+    const stale = inScope.filter((h) => h.status === "stale");
+    const unvalidated = inScope.filter((h) => h.status === "candidate");
+    const rules = servable.slice(0, MAX_RULES).map((h) => ({
+        hypothesisId: h.id,
+        rule: h.rule,
+        confidence: h.confidence,
+        appliesBecause: request.domain && h.domain === request.domain
+            ? `domain ${h.domain} matches the task`
+            : `matched task terms in ${h.domain}`,
+        boundaries: h.doesNotApplyWhen,
+        ref: refTo(h.id),
+    }));
+    const facts = store
+        .search(request.task, "source", MAX_FACTS)
+        .flatMap((hit) => {
+        const source = store.getSource(parseRef(hit.ref).id);
+        return source ? [source] : [];
+    })
+        .map((source) => ({
+        statement: `${source.title}: ${source.content.slice(0, 160)}`,
+        ref: refTo(source.id),
+    }));
+    const doNotAssume = stale.map((h) => `A previously learned rule is stale — do not assume it still holds: "${h.rule}"`);
+    const openQuestions = unvalidated
+        .slice(0, MAX_OPEN_QUESTIONS)
+        .map((h) => `Unvalidated pattern (needs more evidence before acting on it): "${h.rule}"`);
+    const brief = {
+        id: newId("brf", now().getTime()),
+        task: request.task,
+        compiledAt: now().toISOString(),
+        rules,
+        facts,
+        doNotAssume,
+        openQuestions,
+        readiness: readinessFor(rules, facts, doNotAssume, openQuestions),
+        refs: [...rules.map((r) => r.ref), ...facts.map((f) => f.ref), ...unvalidated.slice(0, MAX_OPEN_QUESTIONS).map((h) => refTo(h.id))],
+    };
+    // Serving is an event: fires feed the outcome loop.
+    for (const rule of rules) {
+        const hypothesis = store.getHypothesis(rule.hypothesisId);
+        if (!hypothesis)
+            continue;
+        hypothesis.validity.fires += 1;
+        hypothesis.validity.lastFiredAt = brief.compiledAt;
+        store.saveHypothesis(hypothesis);
+    }
+    store.saveBrief(brief);
+    return brief;
+}
+function collectHypotheses(store, request) {
+    const byId = new Map();
+    if (request.domain) {
+        for (const hypothesis of store.listHypotheses({ domain: request.domain })) {
+            byId.set(hypothesis.id, hypothesis);
+        }
+    }
+    for (const hit of store.search(request.task, "hypothesis")) {
+        const id = parseRef(hit.ref).id;
+        const hypothesis = store.getHypothesis(id);
+        if (hypothesis)
+            byId.set(hypothesis.id, hypothesis);
+    }
+    return [...byId.values()].filter((h) => h.status !== "retired");
+}
+function readinessFor(rules, facts, doNotAssume, openQuestions) {
+    if (rules.length > 0 && doNotAssume.length === 0 && (rules[0]?.confidence ?? 0) >= HIGH_CONFIDENCE)
+        return "act";
+    if (rules.length > 0)
+        return "act_with_caveats";
+    if (facts.length > 0 || openQuestions.length > 0)
+        return "inspect_first";
+    return "ask_human";
+}

package/dist/serve/outcome.js

@@ -0,0 +1,56 @@
+import { newId } from "../core/ids.js";
+/**
+ * Closes the loop: an outcome judges every rule that was served in the brief.
+ * Uncorrected output upholds them; a correction overrides them and links the
+ * new instance as a counterexample. Repeatedly overridden rules go stale —
+ * they leave the servable pool until revalidation.
+ *
+ * Promotion is autonomous: a validated rule that keeps being upheld with no
+ * overrides graduates to active on its own (schema: "review approve | N upheld
+ * outcomes --> active"). Review approval is the fast path, not a gate.
+ */
+const STALE_OVERRIDE_THRESHOLD = 2;
+const ACTIVE_UPHELD_THRESHOLD = 3;
+export function recordOutcome(store, input, now = () => new Date()) {
+    const brief = store.getBrief(input.briefId);
+    if (!brief)
+        throw new Error(`outcome references unknown brief ${input.briefId}`);
+    if (input.result === "uncorrected" || input.result === "corrected") {
+        for (const rule of brief.rules) {
+            const hypothesis = store.getHypothesis(rule.hypothesisId);
+            if (!hypothesis)
+                continue;
+            if (input.result === "uncorrected") {
+                hypothesis.validity.upheld += 1;
+                hypothesis.lastConfirmedAt = now().toISOString();
+                if (hypothesis.status === "validated" &&
+                    hypothesis.validity.upheld >= ACTIVE_UPHELD_THRESHOLD &&
+                    hypothesis.validity.overridden === 0) {
+                    hypothesis.status = "active";
+                }
+            }
+            else {
+                hypothesis.validity.overridden += 1;
+                if (input.correctionInstanceId &&
+                    !hypothesis.counterexampleInstanceIds.includes(input.correctionInstanceId)) {
+                    hypothesis.counterexampleInstanceIds.push(input.correctionInstanceId);
+                }
+                if (hypothesis.validity.overridden >= STALE_OVERRIDE_THRESHOLD &&
+                    hypothesis.validity.overridden > hypothesis.validity.upheld &&
+                    (hypothesis.status === "validated" || hypothesis.status === "active")) {
+                    hypothesis.status = "stale";
+                }
+            }
+            store.saveHypothesis(hypothesis);
+        }
+    }
+    const outcome = {
+        id: newId("out", now().getTime()),
+        briefId: input.briefId,
+        result: input.result,
+        ...(input.correctionInstanceId ? { correctionInstanceId: input.correctionInstanceId } : {}),
+        recordedAt: now().toISOString(),
+    };
+    store.saveOutcome(outcome);
+    return outcome;
+}

package/dist/store/open.js

@@ -0,0 +1,19 @@
+import { parseRef } from "../core/refs.js";
+/** Dereference an athena:// ref to its entity. Shared by MCP and CLI. */
+export function openRef(store, ref) {
+    const parsed = parseRef(ref);
+    switch (parsed.kind) {
+        case "instance":
+            return store.getInstance(parsed.id);
+        case "hypothesis":
+            return store.getHypothesis(parsed.id);
+        case "source":
+            return store.getSource(parsed.id);
+        case "object":
+            return store.getObject(parsed.id);
+        case "brief":
+            return store.getBrief(parsed.id);
+        case "outcome":
+            return store.getOutcome(parsed.id);
+    }
+}