@jitsusama/agentic-harness.core 0.1.0

package/dist/attribution/commit-hook.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The prepare-commit-msg hook that attributes every commit made
+ * under an adapter, not just a typed `git commit`. Command-level
+ * injection only sees a literal git commit; cherry-pick, revert,
+ * rebase, merge and editor commits reach attribution only through
+ * this hook.
+ *
+ * The trigger condition (an env var pi can set before its own tool
+ * call, a marker file a Claude Code hook can only write to disk,
+ * ...) is the one thing that genuinely differs per adapter, so it's
+ * the one thing this module takes as a parameter rather than
+ * assuming. Everything else — idempotent install, chaining any
+ * hook the repo already had, never adding a second AI co-author —
+ * is host-agnostic and shared.
+ */
+/**
+ * How an adapter's hook decides whether to attribute a commit, and
+ * how it identifies its own installed hook.
+ */
+export interface CommitHookOptions {
+    /** Comment marker identifying this as this adapter's hook, for idempotent (re)installs. */
+    readonly marker: string;
+    /** Filename suffix for a pre-existing hook this displaces (e.g. "pi-chained"). */
+    readonly chainedSuffix: string;
+    /** Shell test that must succeed for this commit to be attributed, e.g. `[ -n "$PI_CO_AUTHOR" ]`. */
+    readonly gateTest: string;
+    /** Shell expression yielding the trailer line text, e.g. `"$PI_CO_AUTHOR"`. */
+    readonly trailerExpr: string;
+}
+/** Build the prepare-commit-msg script for the given adapter options. */
+export declare function buildPrepareCommitMsgHook(options: CommitHookOptions): string;
+/** The outcome of trying to install the hook. */
+export interface HookInstall {
+    readonly installed: boolean;
+    readonly reason?: string;
+}
+/**
+ * Install the prepare-commit-msg hook into a repo's hooks
+ * directory, honouring core.hooksPath and chaining any existing
+ * hook. A no-op when this adapter's hook is already installed.
+ */
+export declare function installCommitHook(repoRoot: string, options: CommitHookOptions): HookInstall;
+/**
+ * Ensure the hook is installed in the repo containing dir, at most
+ * once per repo root. Resolves the repo, records it in `installed`
+ * so later commands in the same repo are skipped, and installs
+ * best-effort. A directory outside any git repo is a no-op. This is
+ * how hook coverage follows the session into repos it later cds
+ * into, rather than only the repo the session started in.
+ */
+export declare function ensureCommitHook(dir: string, installed: Set<string>, options: CommitHookOptions): void;
+/** The git repository root containing dir, or null when there is none. */
+export declare function repoRootOf(dir: string): string | null;

package/dist/attribution/commit-hook.js

@@ -0,0 +1,133 @@
+/**
+ * The prepare-commit-msg hook that attributes every commit made
+ * under an adapter, not just a typed `git commit`. Command-level
+ * injection only sees a literal git commit; cherry-pick, revert,
+ * rebase, merge and editor commits reach attribution only through
+ * this hook.
+ *
+ * The trigger condition (an env var pi can set before its own tool
+ * call, a marker file a Claude Code hook can only write to disk,
+ * ...) is the one thing that genuinely differs per adapter, so it's
+ * the one thing this module takes as a parameter rather than
+ * assuming. Everything else — idempotent install, chaining any
+ * hook the repo already had, never adding a second AI co-author —
+ * is host-agnostic and shared.
+ */
+import { execFileSync } from "node:child_process";
+import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { isAbsolute, join } from "node:path";
+/** Build the prepare-commit-msg script for the given adapter options. */
+export function buildPrepareCommitMsgHook(options) {
+    return `#!/bin/sh
+# ${options.marker}
+# Appends the AI co-author trailer to commits made under this adapter.
+# Idempotent and chains to any displaced hook.
+
+msg_file="$1"
+
+chained="$(CDPATH= cd "$(dirname "$0")" && pwd)/prepare-commit-msg.${options.chainedSuffix}"
+if [ -x "$chained" ]; then
+	"$chained" "$@" || exit $?
+fi
+
+${options.gateTest} || exit 0
+[ -f "$msg_file" ] || exit 0
+
+if grep -qi 'co-authored-by[: ]*ai' "$msg_file"; then
+	exit 0
+fi
+
+git interpret-trailers --in-place --trailer ${options.trailerExpr} "$msg_file"
+`;
+}
+/**
+ * Install the prepare-commit-msg hook into a repo's hooks
+ * directory, honouring core.hooksPath and chaining any existing
+ * hook. A no-op when this adapter's hook is already installed.
+ */
+export function installCommitHook(repoRoot, options) {
+    // A custom core.hooksPath means a hook manager (husky and the
+    // like) or a shared, possibly version-controlled hooks directory
+    // owns the hooks. Leave it alone rather than write this adapter's
+    // hook into a directory it does not own.
+    if (hasCustomHooksPath(repoRoot)) {
+        return { installed: false, reason: "custom core.hooksPath configured" };
+    }
+    let hooksDir;
+    try {
+        hooksDir = resolveHooksDir(repoRoot);
+    }
+    catch (error) {
+        return { installed: false, reason: `not a git repo: ${String(error)}` };
+    }
+    const target = join(hooksDir, "prepare-commit-msg");
+    if (existsSync(target) &&
+        readFileSync(target, "utf8").includes(options.marker)) {
+        return { installed: false, reason: "already installed" };
+    }
+    if (existsSync(target)) {
+        const chained = join(hooksDir, `prepare-commit-msg.${options.chainedSuffix}`);
+        // A backup already here means a non-adapter hook was chained
+        // before; renaming over it would lose the original, so refuse
+        // instead.
+        if (existsSync(chained)) {
+            return {
+                installed: false,
+                reason: `a prepare-commit-msg.${options.chainedSuffix} backup already exists`,
+            };
+        }
+        renameSync(target, chained);
+    }
+    writeFileSync(target, buildPrepareCommitMsgHook(options), { mode: 0o755 });
+    chmodSync(target, 0o755);
+    return { installed: true };
+}
+/** Whether the repo configures a custom core.hooksPath. */
+function hasCustomHooksPath(repoRoot) {
+    try {
+        const value = execFileSync("git", ["-C", repoRoot, "config", "--get", "core.hooksPath"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        return value.length > 0;
+    }
+    catch {
+        // git config exits non-zero when the key is unset: no custom path.
+        return false;
+    }
+}
+/**
+ * Ensure the hook is installed in the repo containing dir, at most
+ * once per repo root. Resolves the repo, records it in `installed`
+ * so later commands in the same repo are skipped, and installs
+ * best-effort. A directory outside any git repo is a no-op. This is
+ * how hook coverage follows the session into repos it later cds
+ * into, rather than only the repo the session started in.
+ */
+export function ensureCommitHook(dir, installed, options) {
+    const root = repoRootOf(dir);
+    if (!root || installed.has(root))
+        return;
+    installed.add(root);
+    try {
+        installCommitHook(root, options);
+    }
+    catch {
+        // Best-effort: never let hook installation break a command.
+    }
+}
+/** Resolve the active hooks directory, honouring core.hooksPath. */
+function resolveHooksDir(repoRoot) {
+    const path = execFileSync("git", ["-C", repoRoot, "rev-parse", "--git-path", "hooks"], { encoding: "utf8" }).trim();
+    return isAbsolute(path) ? path : join(repoRoot, path);
+}
+/** The git repository root containing dir, or null when there is none. */
+export function repoRootOf(dir) {
+    try {
+        return execFileSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        // Not a git repository (or git unavailable): no hook to install.
+        return null;
+    }
+}

package/dist/attribution/gh-footer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Splice-based attribution for gh pr/issue commands. Locates the
+ * body of a gh create/edit command and inserts a footer in place,
+ * editing only the body span so the working directory, environment
+ * assignments and every other flag survive byte-identically.
+ *
+ * A parse-and-rebuild path was tried before this and dropped the
+ * leading cd, GH_HOST and -R when it reconstructed the command;
+ * this module never reconstructs one.
+ */
+/** The outcome of attempting to attribute a gh command. */
+export type GhFooterInsertion = {
+    kind: "rewritten";
+    command: string;
+} | {
+    kind: "blocked";
+    reason: string;
+} | {
+    kind: "skip";
+};
+/**
+ * Insert a footer into the body of a gh pr or gh issue create/edit
+ * command. Skips when the command is not a gh entity command, has
+ * no body, or is already attributed; blocks when the command is a
+ * gh entity command in a shape outside the supported grammar.
+ */
+export declare function insertGhBodyFooter(command: string, entity: "pr" | "issue", footer: string, alreadyAttributed: (bodyText: string) => boolean): GhFooterInsertion;

package/dist/attribution/gh-footer.js

@@ -0,0 +1,80 @@
+/**
+ * Splice-based attribution for gh pr/issue commands. Locates the
+ * body of a gh create/edit command and inserts a footer in place,
+ * editing only the body span so the working directory, environment
+ * assignments and every other flag survive byte-identically.
+ *
+ * A parse-and-rebuild path was tried before this and dropped the
+ * leading cd, GH_HOST and -R when it reconstructed the command;
+ * this module never reconstructs one.
+ */
+import { applyEdits, findFlag, tokenize, } from "../command/index.js";
+import { GH_BODY_SPEC, isGhCommand } from "../github-cli/index.js";
+import { stripHeredocBodies, stripShellData } from "../shell/index.js";
+/**
+ * Insert a footer into the body of a gh pr or gh issue create/edit
+ * command. Skips when the command is not a gh entity command, has
+ * no body, or is already attributed; blocks when the command is a
+ * gh entity command in a shape outside the supported grammar.
+ */
+export function insertGhBodyFooter(command, entity, footer, alreadyAttributed) {
+    const stripped = stripShellData(stripHeredocBodies(command));
+    if (!isGhCommand(stripped, entity))
+        return { kind: "skip" };
+    const line = tokenize(command);
+    if (!line.supported) {
+        return {
+            kind: "blocked",
+            reason: line.unsupportedReason ?? "unsupported command shape",
+        };
+    }
+    const ghCommand = findGhCommand(line.commands, entity);
+    if (!ghCommand)
+        return { kind: "skip" };
+    const insertion = locateBodyInsertion(command, ghCommand);
+    if (insertion === "unsafe") {
+        return {
+            kind: "blocked",
+            reason: "inline --body is unquoted, so a multi-line footer cannot be spliced safely; use --body-file - with a quoted heredoc",
+        };
+    }
+    if (!insertion)
+        return { kind: "skip" };
+    if (alreadyAttributed(insertion.bodyText))
+        return { kind: "skip" };
+    const edit = {
+        span: { start: insertion.at, end: insertion.at },
+        text: footer,
+    };
+    return { kind: "rewritten", command: applyEdits(command, [edit]) };
+}
+/** Find a gh create/edit command for the entity among the commands. */
+function findGhCommand(commands, entity) {
+    return commands.find((command) => command.argv[0]?.text === "gh" &&
+        command.argv[1]?.text === entity &&
+        (command.argv[2]?.text === "create" || command.argv[2]?.text === "edit"));
+}
+/**
+ * Locate where a footer joins the body: the end of a heredoc body,
+ * or just inside the closing quote of an inline --body value.
+ */
+function locateBodyInsertion(source, command) {
+    if (command.heredoc) {
+        const { bodySpan } = command.heredoc;
+        return {
+            at: bodySpan.end,
+            bodyText: source.slice(bodySpan.start, bodySpan.end),
+        };
+    }
+    const body = findFlag(command, GH_BODY_SPEC, "body");
+    if (!body?.valueSpan)
+        return undefined;
+    const { start, end } = body.valueSpan;
+    const quoted = source[end - 1] === '"' || source[end - 1] === "'";
+    // An unquoted inline body cannot hold the footer's newlines
+    // without breaking the command into separate statements, so it
+    // is unsafe to splice; the caller fails closed on it.
+    if (!quoted)
+        return "unsafe";
+    return { at: end - 1, bodyText: source.slice(start + 1, end - 1) };
+}

package/dist/attribution/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public API for the `attribution` domain: making AI involvement
+ * in commits, PRs and issues transparent, however a host chooses
+ * to realize it. Two genuinely different mechanisms live here
+ * because the one thing that differs per adapter — how a commit
+ * gets marked as AI-driven, given each host's own capabilities —
+ * is a real port (`CommitHookOptions`), not a reflexive one.
+ */
+export { buildPrepareCommitMsgHook, type CommitHookOptions, ensureCommitHook, type HookInstall, installCommitHook, repoRootOf, } from "./commit-hook.js";
+export { type GhFooterInsertion, insertGhBodyFooter } from "./gh-footer.js";
+export { formatModelName } from "./model-name.js";

package/dist/attribution/index.js

@@ -0,0 +1,11 @@
+/**
+ * Public API for the `attribution` domain: making AI involvement
+ * in commits, PRs and issues transparent, however a host chooses
+ * to realize it. Two genuinely different mechanisms live here
+ * because the one thing that differs per adapter — how a commit
+ * gets marked as AI-driven, given each host's own capabilities —
+ * is a real port (`CommitHookOptions`), not a reflexive one.
+ */
+export { buildPrepareCommitMsgHook, ensureCommitHook, installCommitHook, repoRootOf, } from "./commit-hook.js";
+export { insertGhBodyFooter } from "./gh-footer.js";
+export { formatModelName } from "./model-name.js";

package/dist/attribution/model-name.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Model identifier formatting for display in a co-authorship
+ * trailer. Each adapter builds its own branded trailer text; this
+ * is the one piece of that formatting worth sharing verbatim.
+ */
+/**
+ * Format the model identifier for display. Strips a trailing date
+ * suffix, title-cases hyphen segments and joins consecutive digit
+ * segments into a version number (claude-opus-4-6 -> Claude Opus 4.6).
+ */
+export declare function formatModelName(modelId: string): string;

package/dist/attribution/model-name.js

@@ -0,0 +1,26 @@
+/**
+ * Model identifier formatting for display in a co-authorship
+ * trailer. Each adapter builds its own branded trailer text; this
+ * is the one piece of that formatting worth sharing verbatim.
+ */
+/**
+ * Format the model identifier for display. Strips a trailing date
+ * suffix, title-cases hyphen segments and joins consecutive digit
+ * segments into a version number (claude-opus-4-6 -> Claude Opus 4.6).
+ */
+export function formatModelName(modelId) {
+    const stripped = modelId.replace(/-?\d{8,}$/, "");
+    const parts = stripped.split("-");
+    const result = [];
+    for (const part of parts) {
+        const isDigit = /^\d+$/.test(part);
+        const prevIsDigit = result.length > 0 && /^\d/.test(result[result.length - 1]);
+        if (isDigit && prevIsDigit) {
+            result[result.length - 1] += `.${part}`;
+        }
+        else {
+            result.push(part.charAt(0).toUpperCase() + part.slice(1));
+        }
+    }
+    return result.join(" ");
+}

package/dist/bin/attribution.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Claude Code's attribution wiring: the CLI-adapter half of the
+ * attribution domain's commit-hook port (see attribution/commit-hook.ts
+ * for why the trigger condition is a parameter at all).
+ *
+ * Pi can set an env var in its own process right before the bash
+ * tool call it precedes. A PreToolUse hook is a separate process
+ * that exits before that tool call runs, with no way to inject an
+ * env var forward into it. The signal this adapter uses instead is
+ * a marker file written next to the installed hook script itself:
+ * idempotent to refresh, trivial for the hook to read, and it
+ * needs no cooperation from the tool call that follows.
+ *
+ * The real behavioural difference this trades away: pi's env var
+ * is scoped to one tool call, so a human typing `git commit`
+ * themselves in the same repo is never attributed. This marker
+ * file persists for the repo once written, so it cannot tell an
+ * agent-driven commit from a human one made in the same repo while
+ * the plugin is active. Given the domain's own stated ethos (over-
+ * attributing in an unwatched, headless run is a smaller sin than
+ * under-attributing), that's an accepted trade, not an oversight.
+ */
+/**
+ * Ensure the commit-attribution hook and its marker file exist for
+ * dir's repo. Best-effort and silent: this runs on every bash call,
+ * not just git ones, so coverage follows the agent as it cds
+ * between repos, matching pi's own ensureCommitHook usage.
+ */
+export declare function ensureAttributionHook(dir: string): void;
+/**
+ * Check a gh pr/issue command for missing attribution. A hook can't
+ * rewrite the call the way pi's guardian can, so this hands back a
+ * reason naming the corrected command for the agent to retry with,
+ * rather than splicing it in place.
+ */
+export declare function checkAttribution(command: string): string | null;

package/dist/bin/attribution.js

@@ -0,0 +1,82 @@
+/**
+ * Claude Code's attribution wiring: the CLI-adapter half of the
+ * attribution domain's commit-hook port (see attribution/commit-hook.ts
+ * for why the trigger condition is a parameter at all).
+ *
+ * Pi can set an env var in its own process right before the bash
+ * tool call it precedes. A PreToolUse hook is a separate process
+ * that exits before that tool call runs, with no way to inject an
+ * env var forward into it. The signal this adapter uses instead is
+ * a marker file written next to the installed hook script itself:
+ * idempotent to refresh, trivial for the hook to read, and it
+ * needs no cooperation from the tool call that follows.
+ *
+ * The real behavioural difference this trades away: pi's env var
+ * is scoped to one tool call, so a human typing `git commit`
+ * themselves in the same repo is never attributed. This marker
+ * file persists for the repo once written, so it cannot tell an
+ * agent-driven commit from a human one made in the same repo while
+ * the plugin is active. Given the domain's own stated ethos (over-
+ * attributing in an unwatched, headless run is a smaller sin than
+ * under-attributing), that's an accepted trade, not an oversight.
+ */
+import { execFileSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { ensureCommitHook, insertGhBodyFooter, repoRootOf, } from "../attribution/index.js";
+/** Filename of the marker file, written beside the installed hook. */
+const MARKER_FILENAME = "agentic-harness-claude-co-author";
+/** The trailer line the installed hook appends to a commit message. */
+const COMMIT_TRAILER = "Co-Authored-By: AI via Claude Code <noreply@anthropic.com>";
+/** The footer spliced into an unattributed gh pr/issue body. */
+const GH_FOOTER = "\n\n---\n*Co-Authored-By AI via [Claude Code](https://claude.com/claude-code)*";
+/** Matches existing attribution, so a re-run never double-attributes. */
+const ALREADY_ATTRIBUTED = /co-authored-by[:\s]+ai/i;
+const CLAUDE_OPTIONS = {
+    marker: "agentic-harness-claude-commit-attribution-hook",
+    chainedSuffix: "agentic-harness-claude-chained",
+    gateTest: `[ -f "$(dirname "$0")/${MARKER_FILENAME}" ]`,
+    trailerExpr: `"$(cat "$(dirname "$0")/${MARKER_FILENAME}")"`,
+};
+/** Resolve the active hooks directory, honouring core.hooksPath. */
+function resolveHooksDir(repoRoot) {
+    const path = execFileSync("git", ["-C", repoRoot, "rev-parse", "--git-path", "hooks"], { encoding: "utf8" }).trim();
+    return isAbsolute(path) ? path : join(repoRoot, path);
+}
+/**
+ * Ensure the commit-attribution hook and its marker file exist for
+ * dir's repo. Best-effort and silent: this runs on every bash call,
+ * not just git ones, so coverage follows the agent as it cds
+ * between repos, matching pi's own ensureCommitHook usage.
+ */
+export function ensureAttributionHook(dir) {
+    const root = repoRootOf(dir);
+    if (!root)
+        return;
+    ensureCommitHook(dir, new Set(), CLAUDE_OPTIONS);
+    try {
+        writeFileSync(join(resolveHooksDir(root), MARKER_FILENAME), `${COMMIT_TRAILER}\n`);
+    }
+    catch {
+        // Best-effort: never let marker maintenance break a command.
+    }
+}
+/**
+ * Check a gh pr/issue command for missing attribution. A hook can't
+ * rewrite the call the way pi's guardian can, so this hands back a
+ * reason naming the corrected command for the agent to retry with,
+ * rather than splicing it in place.
+ */
+export function checkAttribution(command) {
+    for (const entity of ["pr", "issue"]) {
+        const result = insertGhBodyFooter(command, entity, GH_FOOTER, (body) => ALREADY_ATTRIBUTED.test(body));
+        if (result.kind === "rewritten") {
+            return ("This command needs AI co-authorship attribution before it can " +
+                `run. Retry with:\n\n${result.command}`);
+        }
+        if (result.kind === "blocked") {
+            return `Attribution cannot be applied to this gh ${entity} command: ${result.reason}.`;
+        }
+    }
+    return null;
+}

package/dist/bin/cli.d.ts

@@ -0,0 +1,14 @@
+#!/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.
+ */
+export {};