@jitsusama/agentic-harness.core 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# agentic-harness.core
+
+Pi-agnostic business logic for [agentic-harness](https://github.com/Jitsusama/agentic-harness.pi):
+state machines, guardian decisions, quest/TDD domain model. Each domain is a
+pure, host-agnostic TypeScript module plus a stateless-per-invocation CLI;
+adapters (pi, Claude Code, ...) own persistence, presentation and how their
+host surfaces things like confirmation.
+
+## Domains
+
+### `tdd`
+
+Drives one discrete red-green-refactor loop by attesting each transition.
+
+```ts
+import { attest, idleLoop } from "@jitsusama/agentic-harness.core/tdd";
+
+const result = attest(idleLoop(), {
+	action: "plan",
+	behaviour: "rejects an empty cart",
+});
+// { outcome: "advanced", loop: {...}, discipline: "..." }
+```
+
+`./tdd/presentation` exports the optional glyph/colour vocabulary for hosts
+with a scoreboard; nothing else needs it.
+
+## CLI
+
+Each invocation reads/writes its own small JSON state file — no daemon, no
+long-lived process. This is the shape a Bash-invoked skill or a hook
+dispatcher needs.
+
+```sh
+echo '{"action":"plan","behaviour":"rejects an empty cart"}' \
+  | agentic-harness-core tdd attest --state-file .agentic-harness/tdd-loop.json
+
+agentic-harness-core tdd status --state-file .agentic-harness/tdd-loop.json
+```
+
+Omit `--state-file` to use the default, `.agentic-harness/tdd-loop.json`
+relative to the current directory.
+
+## Development
+
+```sh
+npm install
+npm run build      # compiles src/ + bin/ to dist/
+npm test           # builds, then runs the vitest suite (unit + CLI)
+npm run typecheck
+npm run lint
+```

package/dist/advisor/charter.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The advisor's charter and per-turn prompts.
+ *
+ * The charter is the advisor's standing system prompt: its role,
+ * its evidence discipline, its output contract and the framing
+ * that its findings are advice to weigh, not commands to obey.
+ * The review prompt is what it sees each turn: the watch-list of
+ * captured rules and the new transcript delta.
+ */
+import type { GovernanceRule } from "../governance/index.js";
+/** The advisor's standing system prompt. */
+export declare function advisorCharter(): string;
+/** Build the per-turn review prompt from rules and the delta. */
+export declare function reviewPrompt(rules: GovernanceRule[], delta: string): string;

package/dist/advisor/charter.js

@@ -0,0 +1,48 @@
+/**
+ * The advisor's charter and per-turn prompts.
+ *
+ * The charter is the advisor's standing system prompt: its role,
+ * its evidence discipline, its output contract and the framing
+ * that its findings are advice to weigh, not commands to obey.
+ * The review prompt is what it sees each turn: the watch-list of
+ * captured rules and the new transcript delta.
+ */
+/** The advisor's standing system prompt. */
+export function advisorCharter() {
+    return [
+        "You are an advisor watching a coding agent at work. You are not",
+        "the doer; you never write code or take actions. Your job is to",
+        "catch what the doer rushed past: scope drift, a claim made without",
+        "grounding, a violation of a standing rule, a correctness risk.",
+        "",
+        "Investigate before you speak. You have read-only tools (read,",
+        "grep, glob). Use them to check a suspicion against the workspace",
+        "before you raise it. Every finding must carry the evidence you",
+        "found: a file and line, the text you read, the rule it breaks. A",
+        "finding you cannot ground, you drop.",
+        "",
+        "Stay quiet unless a turn earns a note. Most turns need none. Never",
+        "invent concerns to seem useful, and never repeat advice already",
+        "given.",
+        "",
+        "When you have investigated, answer with only a JSON array of",
+        "findings, each an object with:",
+        '  - "severity": "aside" (a quiet note), "concern" (worth stopping',
+        '    to weigh) or "blocker" (a likely mistake to fix now)',
+        '  - "claim": one sentence, what you observed',
+        '  - "evidence": the file:line or text that grounds the claim',
+        "Return an empty array when there is nothing worth raising. Your",
+        "findings are advice for the doer to weigh, not commands to obey.",
+    ].join("\n");
+}
+/** Build the per-turn review prompt from rules and the delta. */
+export function reviewPrompt(rules, delta) {
+    const watch = rules.length
+        ? [
+            "Standing rules to watch for violations of:",
+            ...rules.map((r) => `- ${r.text}`),
+            "",
+        ].join("\n")
+        : "";
+    return `${watch}New activity since your last review:\n\n${delta}`;
+}

package/dist/advisor/findings.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The advisor's findings: their shape, how they parse out of a
+ * model reply, and how severity plus a back-off counter decide
+ * the delivery channel.
+ *
+ * An aside is a quiet tail note. A concern or blocker interrupts
+ * through the steer channel so it can stop a wrong direction
+ * rather than only annotate it. A back-off window keeps the
+ * advisor from nagging: for a few turns after one interrupt, its
+ * later concerns route to asides instead.
+ */
+/** How loudly a finding should be delivered. */
+export type Severity = "aside" | "concern" | "blocker";
+/** Where a finding is delivered. */
+export type Channel = "aside" | "steer";
+/** One evidence-backed observation from the advisor. */
+export interface Finding {
+    readonly severity: Severity;
+    readonly claim: string;
+    readonly evidence?: string;
+}
+/** Turns to route interrupts to asides after one fires. */
+export declare const IMMUNE_WINDOW = 2;
+/**
+ * Parse a model reply into findings. Accepts a JSON array of
+ * objects anywhere in the reply; anything without a known
+ * severity and a non-empty claim is dropped. A reply with no
+ * parseable array yields no findings.
+ */
+export declare function parseFindings(reply: string): Finding[];
+/**
+ * Decide the channel for a finding given the current back-off
+ * counter. Asides always stay asides; concerns and blockers
+ * interrupt through steer unless the advisor is still inside its
+ * immune window, where they soften to asides.
+ */
+export declare function channelFor(severity: Severity, immuneTurns: number): Channel;
+/**
+ * The back-off counter for the next turn: reset to the immune
+ * window when an interrupt fired this turn, otherwise decay by
+ * one toward zero.
+ */
+export declare function nextImmuneTurns(current: number, firedInterrupt: boolean): number;

package/dist/advisor/findings.js

@@ -0,0 +1,82 @@
+/**
+ * The advisor's findings: their shape, how they parse out of a
+ * model reply, and how severity plus a back-off counter decide
+ * the delivery channel.
+ *
+ * An aside is a quiet tail note. A concern or blocker interrupts
+ * through the steer channel so it can stop a wrong direction
+ * rather than only annotate it. A back-off window keeps the
+ * advisor from nagging: for a few turns after one interrupt, its
+ * later concerns route to asides instead.
+ */
+import { firstJsonArray } from "../internal/json-array.js";
+/** Turns to route interrupts to asides after one fires. */
+export const IMMUNE_WINDOW = 2;
+const SEVERITIES = ["aside", "concern", "blocker"];
+function isSeverity(value) {
+    return typeof value === "string" && SEVERITIES.includes(value);
+}
+/**
+ * Parse a model reply into findings. Accepts a JSON array of
+ * objects anywhere in the reply; anything without a known
+ * severity and a non-empty claim is dropped. A reply with no
+ * parseable array yields no findings.
+ */
+export function parseFindings(reply) {
+    const array = firstJsonArray(reply);
+    if (!array)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(array);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const findings = [];
+    for (const item of parsed) {
+        if (typeof item !== "object" || item === null)
+            continue;
+        const record = item;
+        const claim = typeof record.claim === "string" ? record.claim.trim() : "";
+        if (claim.length === 0 || !isSeverity(record.severity))
+            continue;
+        const evidence = typeof record.evidence === "string" && record.evidence.trim().length > 0
+            ? record.evidence.trim()
+            : undefined;
+        findings.push({
+            severity: record.severity,
+            claim,
+            ...(evidence ? { evidence } : {}),
+        });
+    }
+    return findings;
+}
+/**
+ * Decide the channel for a finding given the current back-off
+ * counter. Asides always stay asides; concerns and blockers
+ * interrupt through steer unless the advisor is still inside its
+ * immune window, where they soften to asides.
+ */
+export function channelFor(severity, immuneTurns) {
+    // A blocker is a likely mistake to fix now, so it always
+    // interrupts; the back-off window must not mute it just because
+    // an earlier concern fired.
+    if (severity === "blocker")
+        return "steer";
+    if (severity === "aside")
+        return "aside";
+    return immuneTurns > 0 ? "aside" : "steer";
+}
+/**
+ * The back-off counter for the next turn: reset to the immune
+ * window when an interrupt fired this turn, otherwise decay by
+ * one toward zero.
+ */
+export function nextImmuneTurns(current, firedInterrupt) {
+    if (firedInterrupt)
+        return IMMUNE_WINDOW;
+    return Math.max(0, current - 1);
+}

package/dist/advisor/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The advisor's decision core: everything about watching turns,
+ * investigating suspicions and raising findings that does not
+ * need a host's UI or extension runtime.
+ *
+ * The orchestration that ties this to a live session (subscribing
+ * to turn events, running the review loop, delivering a finding as
+ * a steer or a quiet note) is adapter-local: it needs a host's
+ * event model and message-delivery primitives, which is exactly
+ * the kind of thing this package's own design principles say stays
+ * out. `advisorCharter`/`reviewPrompt` describe the review the
+ * adapter runs through `completion`'s `runInvestigation`;
+ * `investigationTools` is the read-only palette that investigation
+ * calls; `parseFindings`/`channelFor` turn its reply into
+ * deliverable notes; `isSubstantiveTurn` and the
+ * enabled/disabled settings file round out what a host needs to
+ * decide whether to run a review at all.
+ */
+export { advisorCharter, reviewPrompt } from "./charter.js";
+export type { Channel, Finding, Severity } from "./findings.js";
+export { channelFor, IMMUNE_WINDOW, nextImmuneTurns, parseFindings, } from "./findings.js";
+export { loadAdvisorEnabled, saveAdvisorEnabled } from "./settings.js";
+export { isSubstantiveTurn } from "./substantive.js";
+export { globArgs, grepArgs, investigationTools, resolveWithinRoot, } from "./tools.js";

package/dist/advisor/index.js

@@ -0,0 +1,23 @@
+/**
+ * The advisor's decision core: everything about watching turns,
+ * investigating suspicions and raising findings that does not
+ * need a host's UI or extension runtime.
+ *
+ * The orchestration that ties this to a live session (subscribing
+ * to turn events, running the review loop, delivering a finding as
+ * a steer or a quiet note) is adapter-local: it needs a host's
+ * event model and message-delivery primitives, which is exactly
+ * the kind of thing this package's own design principles say stays
+ * out. `advisorCharter`/`reviewPrompt` describe the review the
+ * adapter runs through `completion`'s `runInvestigation`;
+ * `investigationTools` is the read-only palette that investigation
+ * calls; `parseFindings`/`channelFor` turn its reply into
+ * deliverable notes; `isSubstantiveTurn` and the
+ * enabled/disabled settings file round out what a host needs to
+ * decide whether to run a review at all.
+ */
+export { advisorCharter, reviewPrompt } from "./charter.js";
+export { channelFor, IMMUNE_WINDOW, nextImmuneTurns, parseFindings, } from "./findings.js";
+export { loadAdvisorEnabled, saveAdvisorEnabled } from "./settings.js";
+export { isSubstantiveTurn } from "./substantive.js";
+export { globArgs, grepArgs, investigationTools, resolveWithinRoot, } from "./tools.js";

package/dist/advisor/settings.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The advisor's persisted on/off state.
+ *
+ * The advisor is off by default and turned on by asking for it in
+ * conversation, not by an environment variable. The choice
+ * persists to a small JSON file so it carries across sessions
+ * until turned off again.
+ */
+/**
+ * Read the advisor's enabled flag from `path`. Defaults to false
+ * (off) when the file is missing or unreadable, so the advisor
+ * never runs unless it was explicitly turned on.
+ */
+export declare function loadAdvisorEnabled(path: string): boolean;
+/** Persist the advisor's enabled flag to `path`. */
+export declare function saveAdvisorEnabled(path: string, enabled: boolean): void;

package/dist/advisor/settings.js

@@ -0,0 +1,30 @@
+/**
+ * The advisor's persisted on/off state.
+ *
+ * The advisor is off by default and turned on by asking for it in
+ * conversation, not by an environment variable. The choice
+ * persists to a small JSON file so it carries across sessions
+ * until turned off again.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * Read the advisor's enabled flag from `path`. Defaults to false
+ * (off) when the file is missing or unreadable, so the advisor
+ * never runs unless it was explicitly turned on.
+ */
+export function loadAdvisorEnabled(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return parsed?.enabled === true;
+    }
+    catch {
+        // No settings file yet, or a corrupt one: stay off.
+        return false;
+    }
+}
+/** Persist the advisor's enabled flag to `path`. */
+export function saveAdvisorEnabled(path, enabled) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify({ enabled }, null, 2)}\n`, "utf8");
+}

package/dist/advisor/substantive.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Whether a turn is worth reviewing.
+ *
+ * The advisor is bounded to substantive turns: ones that changed
+ * something or took a consequential action. A turn that only read
+ * or answered a question is not worth a paid review pass. The
+ * signal is the set of tool names the turn invoked.
+ */
+/**
+ * True when any tool name used in the turn signals a change or a
+ * consequential action. Read-only tools (read, grep, glob, ls,
+ * search) do not, so a purely investigative turn is skipped.
+ */
+export declare function isSubstantiveTurn(toolNames: string[]): boolean;

package/dist/advisor/substantive.js

@@ -0,0 +1,33 @@
+/**
+ * Whether a turn is worth reviewing.
+ *
+ * The advisor is bounded to substantive turns: ones that changed
+ * something or took a consequential action. A turn that only read
+ * or answered a question is not worth a paid review pass. The
+ * signal is the set of tool names the turn invoked.
+ */
+/** Tool-name fragments that mark a turn as substantive. */
+const SUBSTANTIVE_MARKERS = [
+    "edit",
+    "write",
+    "apply_patch",
+    "commit",
+    "pr_",
+    "post",
+    "reply",
+    "resolve",
+    "merge",
+    "rename",
+    "delete",
+];
+/**
+ * True when any tool name used in the turn signals a change or a
+ * consequential action. Read-only tools (read, grep, glob, ls,
+ * search) do not, so a purely investigative turn is skipped.
+ */
+export function isSubstantiveTurn(toolNames) {
+    return toolNames.some((name) => {
+        const lower = name.toLowerCase();
+        return SUBSTANTIVE_MARKERS.some((marker) => lower.includes(marker));
+    });
+}

package/dist/advisor/tools.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The advisor's read-only investigation tools.
+ *
+ * Three tools let the advisor check a suspicion against the
+ * workspace without ever changing it: read a file slice, grep for
+ * a pattern and glob for paths. They run under the session's cwd
+ * and cap their output so a single call cannot flood the
+ * advisor's context. Nothing here writes, moves or deletes.
+ *
+ * The advisor's tool-call arguments are steered by transcript
+ * content, which is untrusted (web fetches, file and issue text),
+ * so these tools are hardened against that: paths are contained
+ * to the root, the search pattern is bound as a flag value behind
+ * a `--` terminator so it cannot smuggle in ripgrep flags such as
+ * `--pre` (which would run an arbitrary command), reads are size
+ * capped, and every subprocess is time and output bounded.
+ */
+import type { LoopTool } from "../completion/index.js";
+/**
+ * Resolve a caller path against the investigation root and refuse
+ * anything that escapes it. An absolute path or a `..` climb that
+ * lands outside the root throws rather than reading the host.
+ */
+export declare function resolveWithinRoot(root: string, path: string): string;
+/**
+ * Build ripgrep args that search for `pattern` under `target`
+ * safely: the pattern rides `--regexp` as a bound value and a
+ * `--` terminator precedes the path, so neither can be parsed as
+ * a ripgrep flag (closing the `--pre` command-execution hole).
+ */
+export declare function grepArgs(pattern: string, target: string): string[];
+/** Build ripgrep args that list files matching `pattern` safely. */
+export declare function globArgs(pattern: string): string[];
+/**
+ * Build the read-only tool set rooted at `root`. The optional
+ * signal aborts a long-running grep or glob with the turn.
+ */
+export declare function investigationTools(root: string, signal?: AbortSignal): LoopTool[];

package/dist/advisor/tools.js

@@ -0,0 +1,202 @@
+/**
+ * The advisor's read-only investigation tools.
+ *
+ * Three tools let the advisor check a suspicion against the
+ * workspace without ever changing it: read a file slice, grep for
+ * a pattern and glob for paths. They run under the session's cwd
+ * and cap their output so a single call cannot flood the
+ * advisor's context. Nothing here writes, moves or deletes.
+ *
+ * The advisor's tool-call arguments are steered by transcript
+ * content, which is untrusted (web fetches, file and issue text),
+ * so these tools are hardened against that: paths are contained
+ * to the root, the search pattern is bound as a flag value behind
+ * a `--` terminator so it cannot smuggle in ripgrep flags such as
+ * `--pre` (which would run an arbitrary command), reads are size
+ * capped, and every subprocess is time and output bounded.
+ */
+import { spawn } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { resolve, sep } from "node:path";
+/** Cap on characters returned by any one tool call. */
+const MAX_OUTPUT = 4000;
+/** Cap on lines a read returns when no limit is given. */
+const DEFAULT_READ_LIMIT = 200;
+/** Refuse to read a file larger than this. */
+const MAX_READ_BYTES = 1_000_000;
+/** Wall-clock cap on any one subprocess. */
+const RUN_TIMEOUT_MS = 10_000;
+/** Clamp text to the output cap with a truncation marker. */
+function clamp(text) {
+    if (text.length <= MAX_OUTPUT)
+        return text;
+    return `${text.slice(0, MAX_OUTPUT)}\n... (truncated)`;
+}
+/**
+ * Resolve a caller path against the investigation root and refuse
+ * anything that escapes it. An absolute path or a `..` climb that
+ * lands outside the root throws rather than reading the host.
+ */
+export function resolveWithinRoot(root, path) {
+    const base = resolve(root);
+    const abs = resolve(base, path);
+    if (abs !== base && !abs.startsWith(base + sep)) {
+        throw new Error(`path escapes the investigation root: ${path}`);
+    }
+    return abs;
+}
+/**
+ * Build ripgrep args that search for `pattern` under `target`
+ * safely: the pattern rides `--regexp` as a bound value and a
+ * `--` terminator precedes the path, so neither can be parsed as
+ * a ripgrep flag (closing the `--pre` command-execution hole).
+ */
+export function grepArgs(pattern, target) {
+    return [
+        "--line-number",
+        "--no-heading",
+        "--max-count",
+        "50",
+        "--regexp",
+        pattern,
+        "--",
+        target,
+    ];
+}
+/** Build ripgrep args that list files matching `pattern` safely. */
+export function globArgs(pattern) {
+    // --glob binds the pattern as its value, so it cannot be parsed
+    // as a flag; there is no positional to smuggle a path into.
+    return ["--files", "--glob", pattern];
+}
+/**
+ * Run a command under the root, bounded by a wall-clock timeout
+ * and an output cap. The child is killed when either trips or the
+ * turn's signal aborts, so a wedged or gushing search cannot hang
+ * the advisor or exhaust memory.
+ */
+function run(root, command, args, signal) {
+    return new Promise((resolveOut) => {
+        const child = spawn(command, args, { cwd: root, signal });
+        let out = "";
+        let done = false;
+        const finish = (text) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                // Already exited; nothing to kill.
+            }
+            resolveOut(text);
+        };
+        const timer = setTimeout(() => finish(out.trim() || "(timed out)"), RUN_TIMEOUT_MS);
+        child.stdout?.on("data", (chunk) => {
+            out += chunk.toString();
+            // Stop accumulating well past the clamp so a huge result
+            // cannot balloon memory before it is truncated.
+            if (out.length > MAX_OUTPUT * 2)
+                finish(out);
+        });
+        child.on("error", (err) => finish(`Command failed: ${err.message}`));
+        child.on("close", () => finish(out.trim() || "(no matches)"));
+    });
+}
+/**
+ * Build the read-only tool set rooted at `root`. The optional
+ * signal aborts a long-running grep or glob with the turn.
+ */
+export function investigationTools(root, signal) {
+    return [
+        {
+            name: "read_file",
+            description: "Read a slice of a file. Args: path (string), offset (1-indexed " +
+                "start line, optional), limit (max lines, optional).",
+            parameters: {
+                type: "object",
+                properties: {
+                    path: { type: "string" },
+                    offset: { type: "number" },
+                    limit: { type: "number" },
+                },
+                required: ["path"],
+            },
+            async execute(args) {
+                const path = String(args.path ?? "");
+                if (!path)
+                    return "read_file needs a path.";
+                let resolved;
+                try {
+                    resolved = resolveWithinRoot(root, path);
+                }
+                catch (err) {
+                    return err instanceof Error ? err.message : String(err);
+                }
+                let stats;
+                try {
+                    stats = statSync(resolved);
+                }
+                catch (err) {
+                    return `Cannot read ${path}: ${err instanceof Error ? err.message : String(err)}`;
+                }
+                if (!stats.isFile())
+                    return `Refused: ${path} is not a regular file.`;
+                if (stats.size > MAX_READ_BYTES) {
+                    return `Refused: ${path} is too large (${stats.size} bytes).`;
+                }
+                const content = readFileSync(resolved, "utf8");
+                const lines = content.split("\n");
+                const offset = typeof args.offset === "number" ? Math.max(1, args.offset) : 1;
+                const limit = typeof args.limit === "number" ? args.limit : DEFAULT_READ_LIMIT;
+                const slice = lines.slice(offset - 1, offset - 1 + limit);
+                return clamp(slice.map((line, i) => `${offset + i}: ${line}`).join("\n"));
+            },
+        },
+        {
+            name: "grep",
+            description: "Search for a regex across files. Args: pattern (string), path " +
+                "(directory or file to search, optional).",
+            parameters: {
+                type: "object",
+                properties: {
+                    pattern: { type: "string" },
+                    path: { type: "string" },
+                },
+                required: ["pattern"],
+            },
+            async execute(args) {
+                const pattern = String(args.pattern ?? "");
+                if (!pattern)
+                    return "grep needs a pattern.";
+                let target = ".";
+                if (args.path) {
+                    try {
+                        target = resolveWithinRoot(root, String(args.path));
+                    }
+                    catch (err) {
+                        return err instanceof Error ? err.message : String(err);
+                    }
+                }
+                return clamp(await run(root, "rg", grepArgs(pattern, target), signal));
+            },
+        },
+        {
+            name: "glob",
+            description: "List paths matching a glob. Args: pattern (string).",
+            parameters: {
+                type: "object",
+                properties: { pattern: { type: "string" } },
+                required: ["pattern"],
+            },
+            async execute(args) {
+                const pattern = String(args.pattern ?? "");
+                if (!pattern)
+                    return "glob needs a pattern.";
+                return clamp(await run(root, "rg", globArgs(pattern), signal));
+            },
+        },
+    ];
+}