@jitsusama/agentic-harness.core 0.1.0

package/dist/bin/cli.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/**
+ * A thin, stateless-per-invocation CLI over the domain modules in
+ * `src/`. Each call reads whatever loop state it needs from a
+ * small JSON file it owns, applies one command, and writes the
+ * result back out — no daemon, no port, no long-lived process.
+ * This is the shape both a Bash-invoked Claude Code skill and a
+ * future hook dispatcher need: one process, one JSON in, one JSON
+ * out.
+ *
+ * This file is the CLI adapter, not domain logic — argument
+ * parsing and state-file I/O live here so `src/tdd` stays pure.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { effectiveCwd, tokenize } from "../command/index.js";
+import { checkGitCli } from "../git-cli/index.js";
+import { checkGithubCli } from "../github-cli/index.js";
+import { detectDestructiveCommand, } from "../internal/guardian/history-gate.js";
+import { attest, idleLoop, standingReminder, } from "../tdd/index.js";
+import { runVerify } from "../verify/index.js";
+import { checkAttribution, ensureAttributionHook } from "./attribution.js";
+import { fileGateDeps } from "./gate-deps.js";
+import { checkCommitGuardian, checkIssueGuardian, checkPrGuardian, } from "./guardians.js";
+import { runMemoryEdit, runMemoryRecall, runMemoryReflect, runMemoryRetain, } from "./memory.js";
+import { runNotesAction } from "./notes.js";
+import { processExec } from "./process-exec.js";
+import { runQuestAction } from "./quest.js";
+import { runSlackAuthLogin, runSlackAuthStatus } from "./slack-auth.js";
+/** Where a loop's state lives when the caller doesn't override it. */
+const DEFAULT_STATE_FILE = ".agentic-harness/tdd-loop.json";
+/** Where quest state lives when the caller doesn't override it. */
+const DEFAULT_QUEST_STATE_FILE = ".agentic-harness/quest-state.json";
+function parseArgs(argv) {
+    const [domain, command, ...rest] = argv;
+    if (!domain || !command) {
+        throw new Error("Usage: agentic-harness-core <domain> <command> [--state-file <path>] [--quests-root <path>] [--notes-root <path>]");
+    }
+    let stateFile = domain === "quest" ? DEFAULT_QUEST_STATE_FILE : DEFAULT_STATE_FILE;
+    let questsRoot;
+    let notesRoot;
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === "--state-file") {
+            const value = rest[i + 1];
+            if (!value) {
+                throw new Error("--state-file requires a path");
+            }
+            stateFile = value;
+            i++;
+        }
+        else if (rest[i] === "--quests-root") {
+            const value = rest[i + 1];
+            if (!value) {
+                throw new Error("--quests-root requires a path");
+            }
+            questsRoot = value;
+            i++;
+        }
+        else if (rest[i] === "--notes-root") {
+            const value = rest[i + 1];
+            if (!value) {
+                throw new Error("--notes-root requires a path");
+            }
+            notesRoot = value;
+            i++;
+        }
+    }
+    return { domain, command, stateFile, questsRoot, notesRoot };
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function loadLoop(stateFile) {
+    try {
+        const raw = await readFile(stateFile, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return idleLoop();
+        }
+        throw error;
+    }
+}
+async function saveLoop(stateFile, loop) {
+    await mkdir(dirname(stateFile), { recursive: true });
+    await writeFile(stateFile, `${JSON.stringify(loop, null, 2)}\n`);
+}
+async function runTddAttest(stateFile) {
+    const input = await readStdin();
+    const attestation = JSON.parse(input);
+    const loop = await loadLoop(stateFile);
+    const result = attest(loop, attestation);
+    await saveLoop(stateFile, result.loop);
+    return result;
+}
+async function runTddStatus(stateFile) {
+    const loop = await loadLoop(stateFile);
+    return { loop, reminder: standingReminder(loop) };
+}
+/** A plain-text explanation of why a destructive command was flagged. */
+function historyReason(match) {
+    const label = match.severity === "irrecoverable" ? "Destructive" : "Risky";
+    return `${label} command: ${match.description}`;
+}
+/** Build the hook's JSON stdout for a deny or ask decision. */
+function decisionOutput(permissionDecision, permissionDecisionReason) {
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision,
+            permissionDecisionReason,
+        },
+    });
+}
+/**
+ * Claude Code's PreToolUse hook contract for a Bash call: deny with a
+ * reason, ask with a reason, or say nothing so the normal permission
+ * flow decides. Never emit an explicit "allow" here — that would
+ * bypass whatever else (other hooks, the user's permission mode)
+ * would otherwise decide, for every bash command this hook doesn't
+ * flag.
+ *
+ * Deny takes precedence over ask throughout: a hard-rule violation
+ * (an amend, an unattributed PR, a content-gate violation) is not a
+ * judgment call the way a destructive command or an otherwise-clean
+ * commit/PR/issue is, so it is refused outright rather than softened
+ * into a question. Every guardian wired in here (history, commit, PR,
+ * issue) never rewrites in its own pi-side review either, so "ask" is
+ * a complete adapter for all of them — unlike a guardian that does
+ * rewrite, which a hook can only approximate as deny-and-retry, these
+ * map onto Claude Code's native permission prompt exactly as pi's own
+ * allow/block confirmation does.
+ */
+async function runHookPreBash() {
+    const input = await readStdin();
+    const payload = JSON.parse(input);
+    const command = payload.tool_input?.command;
+    if (payload.tool_name !== "Bash" || !command)
+        return "";
+    const cwd = effectiveCwd(tokenize(command), process.cwd());
+    const resolvedCwd = "dir" in cwd ? cwd.dir : process.cwd();
+    ensureAttributionHook(resolvedCwd);
+    const denyReason = checkGitCli(command) ??
+        checkGithubCli(command) ??
+        checkAttribution(command);
+    if (denyReason)
+        return decisionOutput("deny", denyReason);
+    const destructive = detectDestructiveCommand(command);
+    if (destructive)
+        return decisionOutput("ask", historyReason(destructive));
+    const deps = fileGateDeps(resolvedCwd);
+    const guardianResult = checkCommitGuardian(command, deps) ??
+        (await checkPrGuardian(command, resolvedCwd, deps, processExec)) ??
+        checkIssueGuardian(command, deps);
+    if (guardianResult) {
+        return decisionOutput(guardianResult.decision, guardianResult.reason);
+    }
+    return "";
+}
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.domain === "tdd" && options.command === "attest") {
+        process.stdout.write(`${JSON.stringify(await runTddAttest(options.stateFile))}\n`);
+        return;
+    }
+    if (options.domain === "tdd" && options.command === "status") {
+        process.stdout.write(`${JSON.stringify(await runTddStatus(options.stateFile))}\n`);
+        return;
+    }
+    if (options.domain === "hook" && options.command === "pre-bash") {
+        const output = await runHookPreBash();
+        if (output)
+            process.stdout.write(`${output}\n`);
+        return;
+    }
+    if (options.domain === "verify" && options.command === "run") {
+        const result = await runVerify({ cwd: process.cwd() });
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+        process.exitCode = result.ok ? 0 : 1;
+        return;
+    }
+    if (options.domain === "quest") {
+        const input = await readStdin();
+        const params = input.trim().length > 0 ? JSON.parse(input) : {};
+        const result = await runQuestAction({
+            action: options.command,
+            stateFile: options.stateFile,
+            questsRoot: options.questsRoot,
+        }, params);
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+        process.exitCode = result.ok ? 0 : 1;
+        return;
+    }
+    if (options.domain === "notes") {
+        const input = await readStdin();
+        const params = input.trim().length > 0 ? JSON.parse(input) : {};
+        const result = await runNotesAction({ action: options.command, notesRoot: options.notesRoot }, params);
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+        process.exitCode = result.ok ? 0 : 1;
+        return;
+    }
+    if (options.domain === "memory") {
+        const handlers = {
+            retain: runMemoryRetain,
+            recall: runMemoryRecall,
+            reflect: runMemoryReflect,
+            edit: runMemoryEdit,
+        };
+        const handler = handlers[options.command];
+        if (handler) {
+            const input = await readStdin();
+            process.stdout.write(`${JSON.stringify(await handler(input))}\n`);
+            return;
+        }
+    }
+    if (options.domain === "slack-auth") {
+        if (options.command === "status") {
+            process.stdout.write(`${JSON.stringify(await runSlackAuthStatus())}\n`);
+            return;
+        }
+        if (options.command === "login") {
+            process.stdout.write(`${JSON.stringify(await runSlackAuthLogin())}\n`);
+            return;
+        }
+    }
+    throw new Error(`Unknown command: ${options.domain} ${options.command}`);
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/bin/gate-deps.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Claude Code's file-backed content-gate signature store.
+ *
+ * The prose, section and title gates need to remember which
+ * violation signatures they have already blocked, so a repeat of
+ * the same violation relents instead of looping forever - see
+ * gate/deps.ts for why. pi backs this with its session log; a
+ * PreToolUse hook is a stateless-per-invocation process with no
+ * session object to read one back from, so this backs it with a
+ * small JSON file instead, the same shape tdd's and quest's own
+ * state files already use.
+ *
+ * Scoped to the command's effective cwd rather than to a Claude
+ * Code conversation: a hook invocation carries no session id in
+ * its stdin payload, so there is nothing session-shaped to key on.
+ * The signature persists for the project instead, which changes
+ * "relent on a repeat within this session" to "relent on a repeat
+ * within this project, ever" - a reasonable reading given the
+ * alternative is no relent mechanism at all in this adapter.
+ */
+import type { GateDeps } from "../gate/index.js";
+/** Build a GateDeps backed by a JSON file under `cwd`. */
+export declare function fileGateDeps(cwd: string): GateDeps;

package/dist/bin/gate-deps.js

@@ -0,0 +1,61 @@
+/**
+ * Claude Code's file-backed content-gate signature store.
+ *
+ * The prose, section and title gates need to remember which
+ * violation signatures they have already blocked, so a repeat of
+ * the same violation relents instead of looping forever - see
+ * gate/deps.ts for why. pi backs this with its session log; a
+ * PreToolUse hook is a stateless-per-invocation process with no
+ * session object to read one back from, so this backs it with a
+ * small JSON file instead, the same shape tdd's and quest's own
+ * state files already use.
+ *
+ * Scoped to the command's effective cwd rather than to a Claude
+ * Code conversation: a hook invocation carries no session id in
+ * its stdin payload, so there is nothing session-shaped to key on.
+ * The signature persists for the project instead, which changes
+ * "relent on a repeat within this session" to "relent on a repeat
+ * within this project, ever" - a reasonable reading given the
+ * alternative is no relent mechanism at all in this adapter.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Where signatures persist, relative to the resolved cwd. */
+const SIGNATURES_FILE = ".agentic-harness/gate-signatures.json";
+/** Read the persisted signature list, or an empty one if absent or unreadable. */
+function readSignatureFile(path) {
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed)
+            ? parsed.filter((s) => typeof s === "string")
+            : [];
+    }
+    catch {
+        // Missing or corrupt: no signatures recorded yet, not a failure
+        // worth surfacing to the caller.
+        return [];
+    }
+}
+/** Build a GateDeps backed by a JSON file under `cwd`. */
+export function fileGateDeps(cwd) {
+    const path = join(cwd, SIGNATURES_FILE);
+    return {
+        readSignatures: () => readSignatureFile(path),
+        persistSignature: (signature) => {
+            const signatures = readSignatureFile(path);
+            if (signatures.includes(signature))
+                return;
+            signatures.push(signature);
+            try {
+                mkdirSync(dirname(path), { recursive: true });
+                writeFileSync(path, JSON.stringify(signatures));
+            }
+            catch {
+                // Best-effort: a lost signature only means the loop
+                // breaker forgets a block it already made, not that the
+                // gate itself fails to run.
+            }
+        },
+    };
+}

package/dist/bin/guardians.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Claude Code's write-confirmation guardians: commit, PR and
+ * issue review.
+ *
+ * All three share the same shape pi's own guardians already have:
+ * deterministic content gates (prose, section, title, redirect) run
+ * first and block outright on a violation, exactly as pi's own
+ * `review()` does before it ever shows a human anything. Only once
+ * a command clears every gate does a human get asked - and unlike
+ * pi's own `!ctx.hasUI -> ALLOW` fallback for a context with no
+ * panel to show, an ordinary Claude Code chat is not headless: a
+ * human is there, so this asks rather than silently allowing,
+ * which is genuinely more protection than pi itself offers a
+ * subagent or a headless run.
+ *
+ * The section and title gates cite pi's own skill names
+ * (`github-pr-format`, `github-issue-format`) in their block
+ * messages ("see the X skill for what belongs in each section").
+ * agentic-harness.claude has no equivalent skill yet, so that
+ * pointer is presently dead for a Claude Code user; the concrete
+ * violation detail alongside it (which headings are invented,
+ * missing or misordered) still is not, and stays actionable on its
+ * own. Revisit once those guide skills port here.
+ */
+import type { Exec } from "../exec/index.js";
+import type { GateDeps } from "../gate/index.js";
+/** What a guardian check hands back to the hook dispatcher. */
+export interface GuardianHookResult {
+    decision: "deny" | "ask";
+    reason: string;
+}
+/**
+ * Check a `git commit` command: the prose gate first (blocks
+ * outright on a violation, same as pi), then an ask showing the
+ * message and its format notes. Returns null for anything else, or
+ * a message-less commit (nothing here to gate).
+ */
+export declare function checkCommitGuardian(command: string, deps: GateDeps): GuardianHookResult | null;
+/**
+ * Check a `gh pr create`/`edit` command: the redirect gate (does
+ * this checkout even belong to GitHub), then section, title and
+ * prose - each blocking outright on a violation - then an ask
+ * showing the title and body. Returns null for anything else.
+ */
+export declare function checkPrGuardian(command: string, cwd: string, deps: GateDeps, exec: Exec): Promise<GuardianHookResult | null>;
+/**
+ * Check a `gh issue create`/`edit` command: section, title and
+ * prose gates, then an ask showing the title and body. Returns
+ * null for anything else.
+ */
+export declare function checkIssueGuardian(command: string, deps: GateDeps): GuardianHookResult | null;

package/dist/bin/guardians.js

@@ -0,0 +1,174 @@
+/**
+ * Claude Code's write-confirmation guardians: commit, PR and
+ * issue review.
+ *
+ * All three share the same shape pi's own guardians already have:
+ * deterministic content gates (prose, section, title, redirect) run
+ * first and block outright on a violation, exactly as pi's own
+ * `review()` does before it ever shows a human anything. Only once
+ * a command clears every gate does a human get asked - and unlike
+ * pi's own `!ctx.hasUI -> ALLOW` fallback for a context with no
+ * panel to show, an ordinary Claude Code chat is not headless: a
+ * human is there, so this asks rather than silently allowing,
+ * which is genuinely more protection than pi itself offers a
+ * subagent or a headless run.
+ *
+ * The section and title gates cite pi's own skill names
+ * (`github-pr-format`, `github-issue-format`) in their block
+ * messages ("see the X skill for what belongs in each section").
+ * agentic-harness.claude has no equivalent skill yet, so that
+ * pointer is presently dead for a Claude Code user; the concrete
+ * violation detail alongside it (which headings are invented,
+ * missing or misordered) still is not, and stays actionable on its
+ * own. Revisit once those guide skills port here.
+ */
+import { isIssueCommand, isPrCommand, parseIssueCommand, parsePrCommand, } from "../internal/github/cli.js";
+import { readCommitFile } from "../internal/guardian/commit-file.js";
+import { complaintsAbout } from "../internal/guardian/commit-format.js";
+import { extractMessage, isGitCommitCommand, } from "../internal/guardian/commit-shell.js";
+import { proseGateNote, runProseGate, } from "../internal/guardian/prose-gate.js";
+import { runRedirectGate } from "../internal/guardian/redirect-gate.js";
+import { runSectionGate, sectionGateNote, } from "../internal/guardian/section-gate.js";
+import { runTitleGate, titleGateNote, } from "../internal/guardian/title-gate.js";
+import { ISSUE_SECTIONS, PR_SECTIONS } from "../sections/index.js";
+/** Turn a GuardianResult into a deny reason, or null when it doesn't block. */
+function denyFrom(result) {
+    if (!result)
+        return null;
+    if ("block" in result)
+        return result.reason;
+    // No content gate ported so far emits rewrite, but the type allows
+    // it: approximate as deny, naming the corrected form for the agent
+    // to retry with, since a hook cannot splice a rewrite into the
+    // call the way pi's guardian can.
+    return `This command needs a change before it can run:\n\n${result.rewrite}`;
+}
+const MAX_PREVIEW = 4000;
+/** Cap a body preview so the reason stays a reasonable size. */
+function truncate(text) {
+    if (text.length <= MAX_PREVIEW)
+        return text;
+    return `${text.slice(0, MAX_PREVIEW)}\n... (truncated)`;
+}
+const PR_SECTION_CONFIG = {
+    sanctioned: PR_SECTIONS,
+    entityLabel: "PR",
+    skill: "github-pr-format",
+};
+const PR_TITLE_CONFIG = { entityLabel: "PR", skill: "github-pr-format" };
+const ISSUE_SECTION_CONFIG = {
+    sanctioned: ISSUE_SECTIONS,
+    entityLabel: "issue",
+    skill: "github-issue-format",
+};
+const ISSUE_TITLE_CONFIG = {
+    entityLabel: "issue",
+    skill: "github-issue-format",
+};
+/** Plain-text review prompt for a commit message. */
+function commitAskReason(message, isAmend, relentNote) {
+    const complaints = complaintsAbout(message);
+    const notes = complaints.length > 0
+        ? `Format notes: ${complaints.join("; ")}.`
+        : "Format looks clean (conventional, within the length limits).";
+    const amendNote = isAmend ? " This amends the previous commit." : "";
+    const relentSuffix = relentNote ? `\n\n${relentNote}` : "";
+    return `Review this commit before it runs.${amendNote}\n\n${truncate(message)}\n\n${notes}${relentSuffix}`;
+}
+/**
+ * Check a `git commit` command: the prose gate first (blocks
+ * outright on a violation, same as pi), then an ask showing the
+ * message and its format notes. Returns null for anything else, or
+ * a message-less commit (nothing here to gate).
+ */
+export function checkCommitGuardian(command, deps) {
+    if (!isGitCommitCommand(command))
+        return null;
+    const message = extractMessage(command, readCommitFile);
+    if (!message)
+        return null;
+    const proseDeny = denyFrom(runProseGate(deps, message));
+    if (proseDeny)
+        return { decision: "deny", reason: proseDeny };
+    const isAmend = /--amend\b/.test(command);
+    const relentNote = proseGateNote(deps, message);
+    return {
+        decision: "ask",
+        reason: commitAskReason(message, isAmend, relentNote),
+    };
+}
+/** Plain-text review prompt for a PR or issue body. */
+function entityAskReason(label, action, title, body, relentNotes) {
+    const parts = [`Review this ${label} ${action} before it runs.`];
+    if (title)
+        parts.push("", `Title: ${title}`);
+    if (body)
+        parts.push("", truncate(body));
+    for (const note of relentNotes) {
+        if (note)
+            parts.push("", note);
+    }
+    return parts.join("\n");
+}
+/**
+ * Check a `gh pr create`/`edit` command: the redirect gate (does
+ * this checkout even belong to GitHub), then section, title and
+ * prose - each blocking outright on a violation - then an ask
+ * showing the title and body. Returns null for anything else.
+ */
+export async function checkPrGuardian(command, cwd, deps, exec) {
+    if (!isPrCommand(command))
+        return null;
+    const parsed = parsePrCommand(command);
+    if (!parsed)
+        return null;
+    const redirectDeny = denyFrom(await runRedirectGate(deps, { action: parsed.action, cwd, exec }));
+    if (redirectDeny)
+        return { decision: "deny", reason: redirectDeny };
+    const sectionDeny = denyFrom(runSectionGate(deps, parsed.body, PR_SECTION_CONFIG));
+    if (sectionDeny)
+        return { decision: "deny", reason: sectionDeny };
+    const titleDeny = denyFrom(runTitleGate(deps, parsed.title, PR_TITLE_CONFIG));
+    if (titleDeny)
+        return { decision: "deny", reason: titleDeny };
+    const proseDeny = denyFrom(runProseGate(deps, parsed.body));
+    if (proseDeny)
+        return { decision: "deny", reason: proseDeny };
+    return {
+        decision: "ask",
+        reason: entityAskReason("PR", parsed.action, parsed.title, parsed.body, [
+            sectionGateNote(deps, parsed.body, PR_SECTION_CONFIG),
+            titleGateNote(deps, parsed.title, PR_TITLE_CONFIG),
+            proseGateNote(deps, parsed.body),
+        ]),
+    };
+}
+/**
+ * Check a `gh issue create`/`edit` command: section, title and
+ * prose gates, then an ask showing the title and body. Returns
+ * null for anything else.
+ */
+export function checkIssueGuardian(command, deps) {
+    if (!isIssueCommand(command))
+        return null;
+    const parsed = parseIssueCommand(command);
+    if (!parsed)
+        return null;
+    const sectionDeny = denyFrom(runSectionGate(deps, parsed.body, ISSUE_SECTION_CONFIG));
+    if (sectionDeny)
+        return { decision: "deny", reason: sectionDeny };
+    const titleDeny = denyFrom(runTitleGate(deps, parsed.title, ISSUE_TITLE_CONFIG));
+    if (titleDeny)
+        return { decision: "deny", reason: titleDeny };
+    const proseDeny = denyFrom(runProseGate(deps, parsed.body));
+    if (proseDeny)
+        return { decision: "deny", reason: proseDeny };
+    return {
+        decision: "ask",
+        reason: entityAskReason("issue", parsed.action, parsed.title, parsed.body, [
+            sectionGateNote(deps, parsed.body, ISSUE_SECTION_CONFIG),
+            titleGateNote(deps, parsed.title, ISSUE_TITLE_CONFIG),
+            proseGateNote(deps, parsed.body),
+        ]),
+    };
+}

package/dist/bin/memory.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The CLI adapter's memory wiring: scope resolution plus the four
+ * request/response shapes the `memory` subcommands speak. Domain
+ * logic (the store itself) lives in `../memory`; this file is
+ * where a CLI-specific "what scope applies right now" answer gets
+ * made, since core deliberately doesn't own that (see
+ * memory/scope.ts).
+ *
+ * Each call opens and closes its own connection: this CLI is
+ * stateless per invocation like every other subcommand here, and
+ * SQLite is built for exactly this access pattern.
+ */
+export declare function runMemoryRetain(input: string): Promise<unknown>;
+export declare function runMemoryRecall(input: string): Promise<unknown>;
+export declare function runMemoryReflect(input: string): Promise<unknown>;
+export declare function runMemoryEdit(input: string): Promise<unknown>;

package/dist/bin/memory.js

@@ -0,0 +1,81 @@
+/**
+ * The CLI adapter's memory wiring: scope resolution plus the four
+ * request/response shapes the `memory` subcommands speak. Domain
+ * logic (the store itself) lives in `../memory`; this file is
+ * where a CLI-specific "what scope applies right now" answer gets
+ * made, since core deliberately doesn't own that (see
+ * memory/scope.ts).
+ *
+ * Each call opens and closes its own connection: this CLI is
+ * stateless per invocation like every other subcommand here, and
+ * SQLite is built for exactly this access pattern.
+ */
+import { memoryDbPath, openMemoryStore } from "../memory/index.js";
+/** The scope a call gets when it doesn't name one: the project at cwd. */
+function defaultScope() {
+    return { kind: "project", path: process.cwd() };
+}
+export async function runMemoryRetain(input) {
+    const req = JSON.parse(input);
+    const store = await openMemoryStore(await memoryDbPath());
+    try {
+        return await store.retain({
+            scope: req.scope ?? defaultScope(),
+            text: req.text,
+            ...(req.tags ? { tags: req.tags } : {}),
+            ...(req.source ? { source: req.source } : {}),
+        });
+    }
+    finally {
+        await store.close();
+    }
+}
+export async function runMemoryRecall(input) {
+    const req = JSON.parse(input || "{}");
+    const store = await openMemoryStore(await memoryDbPath());
+    try {
+        return await store.recall({
+            scope: req.scope ?? defaultScope(),
+            ...(req.query ? { text: req.query } : {}),
+            ...(req.limit ? { limit: req.limit } : {}),
+            ...(req.includeGlobal !== undefined
+                ? { includeGlobal: req.includeGlobal }
+                : {}),
+        });
+    }
+    finally {
+        await store.close();
+    }
+}
+export async function runMemoryReflect(input) {
+    const req = JSON.parse(input);
+    const store = await openMemoryStore(await memoryDbPath());
+    try {
+        const text = await store.reflect({
+            scope: req.scope ?? defaultScope(),
+            question: req.question,
+        });
+        return { text };
+    }
+    finally {
+        await store.close();
+    }
+}
+export async function runMemoryEdit(input) {
+    const req = JSON.parse(input);
+    const store = await openMemoryStore(await memoryDbPath());
+    try {
+        if (req.invalidate) {
+            await store.invalidate(req.id);
+            return { ok: true, invalidated: req.id };
+        }
+        const fact = await store.edit(req.id, {
+            ...(req.text !== undefined ? { text: req.text } : {}),
+            ...(req.tags !== undefined ? { tags: req.tags } : {}),
+        });
+        return { ok: fact !== null, fact };
+    }
+    finally {
+        await store.close();
+    }
+}

package/dist/bin/notes.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The `notes` domain's CLI handler: one process per call, no
+ * persisted state -- every verb is fully determined by
+ * `notesRoot` plus its own params, so unlike `bin/quest.ts`
+ * there is no `.agentic-harness/notes-state.json` to load or
+ * save.
+ *
+ * notesRoot resolves the same way quest's questsRoot does: a
+ * single default location every tool on the machine sees
+ * unless told otherwise, not something that shifts under you
+ * as cwd changes. There's no sibling pi extension to alias
+ * onto (quest's default points at the exact path
+ * agentic-harness.pi's quest-workflow extension already
+ * writes to), so notes gets its own XDG-rooted default
+ * instead. Override with `--notes-root` or
+ * `AGENTIC_HARNESS_NOTES_ROOT` when the archive lives
+ * somewhere else -- e.g. a specific repo's notes tree.
+ */
+import type { NoteResult, NoteToolParams } from "../notes/verbs/shared.js";
+/**
+ * Default notesRoot: an XDG data-dir location, mirroring how
+ * `bin/quest.ts`'s `defaultQuestsRoot` resolves.
+ */
+export declare function defaultNotesRoot(env?: NodeJS.ProcessEnv, home?: string): string;
+export interface NotesCliOptions {
+    action: string;
+    notesRoot: string | undefined;
+}
+/** Run one notes action against `notesRoot`, resolved from the flag/env/cwd chain. */
+export declare function runNotesAction(options: NotesCliOptions, params: NoteToolParams): Promise<NoteResult>;