@jitsusama/agentic-harness.core 0.1.0

package/dist/governance/render.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Render captured rules as a resident prompt block.
+ *
+ * The block rides the prompt coordinator every turn, so it is
+ * kept compact: a short heading, a one-line framing and the rule
+ * texts as a list. An empty store contributes nothing.
+ */
+import type { GovernanceRule } from "./types.js";
+/**
+ * Build the captured-lessons prompt block, or undefined when
+ * there are no rules to contribute.
+ */
+export declare function renderRulesBlock(rules: GovernanceRule[]): string | undefined;

package/dist/governance/render.js

@@ -0,0 +1,23 @@
+/**
+ * Render captured rules as a resident prompt block.
+ *
+ * The block rides the prompt coordinator every turn, so it is
+ * kept compact: a short heading, a one-line framing and the rule
+ * texts as a list. An empty store contributes nothing.
+ */
+/**
+ * Build the captured-lessons prompt block, or undefined when
+ * there are no rules to contribute.
+ */
+export function renderRulesBlock(rules) {
+    if (rules.length === 0)
+        return undefined;
+    return [
+        "## Learned Conventions (Captured From Past Corrections)",
+        "",
+        "These rules were distilled from corrections in earlier sessions.",
+        "Follow them as standing guidance:",
+        "",
+        ...rules.map((r) => `- ${r.text}`),
+    ].join("\n");
+}

package/dist/governance/store.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The governance rule store: a durable, human-editable list of
+ * captured behavioural rules.
+ *
+ * Rules persist as a JSON array in a single file so a person can
+ * open it and edit or remove a rule directly, which the design
+ * requires: a bad captured rule must be easy to fix or delete.
+ * Writes go through a temp file and a rename so a crash mid-write
+ * never leaves a half-written store.
+ */
+import type { GovernanceRule } from "./types.js";
+/** A rule to add, without the fields the store assigns. */
+export type NewRule = Pick<GovernanceRule, "text"> & Partial<Pick<GovernanceRule, "source">>;
+/** A durable store of captured behavioural rules. */
+export interface RuleStore {
+    /** Every rule, in insertion order. */
+    list(): GovernanceRule[];
+    /** File a new rule and return it with its assigned fields. */
+    add(rule: NewRule): GovernanceRule;
+    /** Remove a rule by id; returns true when one was removed. */
+    remove(id: string): boolean;
+    /** Replace the entire rule set (used after a bulk edit). */
+    replaceAll(rules: GovernanceRule[]): void;
+}
+/**
+ * Open the rule store backed by the file at `path`. Every
+ * operation reads through to the file, so two extensions holding
+ * their own store over the same path (correction capture and the
+ * advisor) always see each other's writes, and a hand-edit is
+ * picked up without a restart. Writes are atomic.
+ */
+export declare function openRuleStore(path: string): RuleStore;

package/dist/governance/store.js

@@ -0,0 +1,102 @@
+/**
+ * The governance rule store: a durable, human-editable list of
+ * captured behavioural rules.
+ *
+ * Rules persist as a JSON array in a single file so a person can
+ * open it and edit or remove a rule directly, which the design
+ * requires: a bad captured rule must be easy to fix or delete.
+ * Writes go through a temp file and a rename so a crash mid-write
+ * never leaves a half-written store.
+ */
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/** Mint a short, collision-resistant rule id. */
+function mintId() {
+    return randomBytes(4).toString("hex");
+}
+/** True for a record with the string fields a rule requires. */
+function isValidRule(value) {
+    const r = value;
+    return (typeof r?.id === "string" &&
+        typeof r?.text === "string" &&
+        typeof r?.createdAt === "string");
+}
+/**
+ * Read and parse the store file, tolerating a missing file. A
+ * file that will not parse is moved aside (never overwritten in
+ * place) so a hand-edit typo cannot silently erase every rule on
+ * the next write; the caller then starts from empty. Malformed
+ * individual entries are dropped rather than rendered as blanks.
+ */
+function readRules(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        // No file yet: an empty store is the correct starting point.
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // Preserve the unparseable file under a new name and remove it
+        // from the path so the next read starts clean and the next
+        // write does not clobber the user's (recoverable) content.
+        try {
+            renameSync(path, `${path}.corrupt-${Date.now()}`);
+        }
+        catch {
+            // Could not move it aside; leave it and start empty anyway.
+        }
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    return parsed.filter(isValidRule);
+}
+/** Write the rule set atomically. */
+function writeRules(path, rules) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = join(dirname(path), `.rules.${mintId()}.tmp`);
+    writeFileSync(tmp, `${JSON.stringify(rules, null, 2)}\n`, "utf8");
+    renameSync(tmp, path);
+}
+/**
+ * Open the rule store backed by the file at `path`. Every
+ * operation reads through to the file, so two extensions holding
+ * their own store over the same path (correction capture and the
+ * advisor) always see each other's writes, and a hand-edit is
+ * picked up without a restart. Writes are atomic.
+ */
+export function openRuleStore(path) {
+    return {
+        list() {
+            return readRules(path);
+        },
+        add(rule) {
+            const filed = {
+                id: mintId(),
+                text: rule.text.trim(),
+                createdAt: new Date().toISOString(),
+                ...(rule.source ? { source: rule.source } : {}),
+            };
+            writeRules(path, [...readRules(path), filed]);
+            return filed;
+        },
+        remove(id) {
+            const current = readRules(path);
+            const next = current.filter((r) => r.id !== id);
+            const removed = next.length !== current.length;
+            if (removed)
+                writeRules(path, next);
+            return removed;
+        },
+        replaceAll(next) {
+            writeRules(path, [...next]);
+        },
+    };
+}

package/dist/governance/types.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Types for the governance rule store.
+ *
+ * A governance rule is a behavioural lesson captured from a past
+ * correction: a short imperative the agent should follow going
+ * forward. Rules are the durable output of correction capture and
+ * the watch-list the advisor reviews turns against.
+ */
+/** A single captured behavioural rule. */
+export interface GovernanceRule {
+    /** Stable short identifier, unique within the store. */
+    readonly id: string;
+    /** The rule itself, phrased as an imperative. */
+    readonly text: string;
+    /** ISO timestamp of when the rule was filed. */
+    readonly createdAt: string;
+    /** Where the rule came from, e.g. a capturing session id. */
+    readonly source?: string;
+}

package/dist/governance/types.js

@@ -0,0 +1,9 @@
+/**
+ * Types for the governance rule store.
+ *
+ * A governance rule is a behavioural lesson captured from a past
+ * correction: a short imperative the agent should follow going
+ * forward. Rules are the durable output of correction capture and
+ * the watch-list the advisor reviews turns against.
+ */
+export {};

package/dist/guardian/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The portable half of the guardian contract: the result shape a
+ * content gate hands back. Registration and redirect formatting
+ * stay adapter-local -- they wire into a host's own tool-call
+ * interception, which every adapter does differently.
+ */
+export { ALLOW, type GuardianBlock, type GuardianResult } from "./types.js";

package/dist/guardian/index.js

@@ -0,0 +1,7 @@
+/**
+ * The portable half of the guardian contract: the result shape a
+ * content gate hands back. Registration and redirect formatting
+ * stay adapter-local -- they wire into a host's own tool-call
+ * interception, which every adapter does differently.
+ */
+export { ALLOW } from "./types.js";

package/dist/guardian/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The shared shape a guardian's content gates hand back to their
+ * adapter: allow, block, or (reserved, unused today) rewrite.
+ *
+ * The full `CommandGuardian<T>` contract -- detect/parse/review
+ * over a live host context -- stays adapter-local, since `review`
+ * needs a host's own confirmation UI. This is only the result
+ * shape the pure gates (prose, section, title) return, shared so
+ * every adapter's glue speaks the same result.
+ */
+/**
+ * Result of a guardian review:
+ * - ALLOW (undefined): allow the command as-is
+ * - { block, reason }: block execution with a reason
+ * - { rewrite }: allow execution with a rewritten command
+ *
+ * No guardian emits a rewrite today: the content gates block or
+ * allow, while a sanctioned rewrite (an attribution splice, an
+ * interceptor's corrected command) is each adapter's own doing.
+ * The rewrite variant is retained as intentional contract surface
+ * for a future gate that wants it.
+ */
+export type GuardianResult = undefined | GuardianBlock | {
+    rewrite: string;
+};
+/**
+ * A refusal, named so a function that can only refuse can say so.
+ *
+ * Returning the whole union from something that never rewrites lets
+ * the rewrite variant leak into a caller that only accepts a block.
+ */
+export type GuardianBlock = {
+    block: true;
+    reason: string;
+};
+/** Allow the command as-is. Named constant for self-documenting returns. */
+export declare const ALLOW: GuardianResult;

package/dist/guardian/types.js

@@ -0,0 +1,12 @@
+/**
+ * The shared shape a guardian's content gates hand back to their
+ * adapter: allow, block, or (reserved, unused today) rewrite.
+ *
+ * The full `CommandGuardian<T>` contract -- detect/parse/review
+ * over a live host context -- stays adapter-local, since `review`
+ * needs a host's own confirmation UI. This is only the result
+ * shape the pure gates (prose, section, title) return, shared so
+ * every adapter's glue speaks the same result.
+ */
+/** Allow the command as-is. Named constant for self-documenting returns. */
+export const ALLOW = undefined;

package/dist/internal/github/cli.d.ts

@@ -0,0 +1,40 @@
+/**
+ * GitHub CLI command parsing for gh pr/issue create/edit: detection
+ * and field extraction (action, title, body, entity number).
+ *
+ * Parsing runs on the command model (lib/command): the command is
+ * tokenized, the gh pr/issue command is located in the token stream,
+ * and its title and body are read through caller-supplied flag specs.
+ * This scopes extraction to the gh command itself, so a flag in a
+ * chained command is never mistaken for the gh command's, and it
+ * reads the short forms (-t, -b) as well as the long ones. Editing a
+ * body for attribution is a splice (attribution-edit), not a rebuild,
+ * so this module no longer reconstructs commands.
+ */
+export { isGhCommand } from "../../github-cli/index.js";
+/** Parsed gh pr create/edit command with extracted fields. */
+export interface PrCommand {
+    /** "create" or "edit" */
+    readonly action: "create" | "edit";
+    readonly title: string | null;
+    readonly body: string | null;
+    /** PR number for edit commands */
+    readonly prNumber: string | null;
+}
+/** Detect whether a bash command contains a gh pr create or edit. */
+export declare function isPrCommand(command: string): boolean;
+/** Extract PR details from a bash command. Returns null if nothing to gate. */
+export declare function parsePrCommand(command: string): PrCommand | null;
+/** Parsed gh issue create/edit command with extracted fields. */
+export interface IssueCommand {
+    /** "create" or "edit" */
+    readonly action: "create" | "edit";
+    readonly title: string | null;
+    readonly body: string | null;
+    /** Issue number for edit commands */
+    readonly issueNumber: string | null;
+}
+/** Detect whether a bash command contains a gh issue create or edit. */
+export declare function isIssueCommand(command: string): boolean;
+/** Extract issue details from a bash command. Returns null if nothing to gate. */
+export declare function parseIssueCommand(command: string): IssueCommand | null;

package/dist/internal/github/cli.js

@@ -0,0 +1,102 @@
+/**
+ * GitHub CLI command parsing for gh pr/issue create/edit: detection
+ * and field extraction (action, title, body, entity number).
+ *
+ * Parsing runs on the command model (lib/command): the command is
+ * tokenized, the gh pr/issue command is located in the token stream,
+ * and its title and body are read through caller-supplied flag specs.
+ * This scopes extraction to the gh command itself, so a flag in a
+ * chained command is never mistaken for the gh command's, and it
+ * reads the short forms (-t, -b) as well as the long ones. Editing a
+ * body for attribution is a splice (attribution-edit), not a rebuild,
+ * so this module no longer reconstructs commands.
+ */
+import { findFlag, tokenize, } from "../../command/index.js";
+import { GH_BODY_SPEC, isGhCommand } from "../../github-cli/index.js";
+import { unquote } from "../../shell/index.js";
+export { isGhCommand } from "../../github-cli/index.js";
+/** The title flag of gh pr/issue, in its long and short forms. */
+const GH_TITLE_SPEC = {
+    flags: [{ name: "title", long: "title", short: "t", takesValue: true }],
+};
+/** Locate a gh pr/issue create or edit command in the token stream. */
+function findGhEntity(command, kind) {
+    return tokenize(command).commands.find((c) => c.argv[0]?.text === "gh" &&
+        c.argv[1]?.text === kind &&
+        (c.argv[2]?.text === "create" || c.argv[2]?.text === "edit"));
+}
+/** Read a flag's value, unquoted, or null when it is absent. */
+function readFlagValue(command, spec, name) {
+    const match = findFlag(command, spec, name);
+    if (!match || match.value === undefined)
+        return null;
+    return unquote(match.value);
+}
+/**
+ * Read the body: the heredoc body verbatim when the command has
+ * one, otherwise the inline --body (or -b) value, unquoted.
+ */
+function readBody(command, gh) {
+    if (gh.heredoc)
+        return command.slice(gh.heredoc.bodySpan.start, gh.heredoc.bodySpan.end);
+    return readFlagValue(gh, GH_BODY_SPEC, "body");
+}
+/** The entity number that follows `gh <kind> edit`, when present. */
+function readNumber(gh) {
+    const arg = gh.argv[3]?.text;
+    return arg && /^\d+$/.test(arg) ? arg : null;
+}
+/**
+ * Parse a gh pr/issue command into its reviewable fields, or null
+ * when there is nothing to gate.
+ *
+ * A command with a body parses. A title-only edit also parses, with
+ * a null body, so the title gate runs on the one path whose sole
+ * purpose is changing the title. Everything else, a bodyless create
+ * or a metadata-only edit, carries no reviewable content here, so
+ * leave it ungated.
+ */
+function parseGhEntity(command, kind) {
+    const gh = findGhEntity(command, kind);
+    if (!gh)
+        return null;
+    const action = gh.argv[2]?.text === "create" ? "create" : "edit";
+    const title = readFlagValue(gh, GH_TITLE_SPEC, "title");
+    const body = readBody(command, gh);
+    const number = action === "edit" ? readNumber(gh) : null;
+    if (!body && !(action === "edit" && title))
+        return null;
+    return { action, title, body, number };
+}
+/** Detect whether a bash command contains a gh pr create or edit. */
+export function isPrCommand(command) {
+    return isGhCommand(command, "pr");
+}
+/** Extract PR details from a bash command. Returns null if nothing to gate. */
+export function parsePrCommand(command) {
+    const entity = parseGhEntity(command, "pr");
+    if (!entity)
+        return null;
+    return {
+        action: entity.action,
+        title: entity.title,
+        body: entity.body,
+        prNumber: entity.number,
+    };
+}
+/** Detect whether a bash command contains a gh issue create or edit. */
+export function isIssueCommand(command) {
+    return isGhCommand(command, "issue");
+}
+/** Extract issue details from a bash command. Returns null if nothing to gate. */
+export function parseIssueCommand(command) {
+    const entity = parseGhEntity(command, "issue");
+    if (!entity)
+        return null;
+    return {
+        action: entity.action,
+        title: entity.title,
+        body: entity.body,
+        issueNumber: entity.number,
+    };
+}

package/dist/internal/guardian/commit-file.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Reads a commit message file for the `git commit -F <file>`
+ * path, resolving the path the way the shell would before the
+ * command runs.
+ */
+/** Read a commit message file, or null when it cannot be read. */
+export declare function readCommitFile(rawPath: string, baseDir: string | null): string | null;

package/dist/internal/guardian/commit-file.js

@@ -0,0 +1,36 @@
+/**
+ * Reads a commit message file for the `git commit -F <file>`
+ * path, resolving the path the way the shell would before the
+ * command runs.
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+/**
+ * Resolve a raw `-F` path against the home directory (for `~`),
+ * an absolute path directly, or the command's `cd` base
+ * directory (falling back to the process cwd) for a relative
+ * path.
+ */
+function resolvePath(rawPath, baseDir) {
+    if (rawPath === "~")
+        return homedir();
+    if (rawPath.startsWith("~/"))
+        return join(homedir(), rawPath.slice(2));
+    if (isAbsolute(rawPath))
+        return rawPath;
+    return resolve(baseDir ?? process.cwd(), rawPath);
+}
+/** Read a commit message file, or null when it cannot be read. */
+export function readCommitFile(rawPath, baseDir) {
+    try {
+        return readFileSync(resolvePath(rawPath, baseDir), "utf8");
+    }
+    catch {
+        // Fail open: an unreadable file (missing, permissions, a path
+        // with unexpanded shell variables) means no attribution and no
+        // gate for this commit, never a wrong rewrite. The caller
+        // treats null as "no message found".
+        return null;
+    }
+}

package/dist/internal/guardian/commit-format.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Validates commit messages against conventional commit format,
+ * subject length limits and body line wrap rules.
+ *
+ * Shared rather than owned by the guardian, because there are two
+ * roads into the same repository and a rule enforced on one of them
+ * is not enforced. The guardian meets a commit typed into a shell by
+ * intercepting the command; `work record` never runs a command at
+ * all, committing through the exec seam, so it arrived behind the
+ * guardian rather than in front of it and was held only to the prose
+ * rules. This module is what both roads now ask.
+ */
+export interface CommitValidation {
+    subjectLength: number;
+    subjectOk: boolean;
+    bodyWrapOk: boolean;
+    bodyLongestLine: number;
+    bodyLongestLineNum: number;
+    conventionalOk: boolean;
+}
+/** Validate a commit message against conventional commit rules. */
+export declare function validate(message: string): CommitValidation;
+/**
+ * What is wrong with a commit message, said so a caller can fix it.
+ *
+ * For the road with nobody watching. The guardian renders the same
+ * facts as ticks and warnings next to a panel, which informs a person
+ * who is already deciding; a caller that gets a list of sentences can
+ * act on it without one. Empty means the message is fine.
+ *
+ * Each complaint names the measurement rather than the rule, because
+ * "subject is 63 characters, and the limit is 50" can be acted on and
+ * "subject too long" sends the reader to go and count.
+ */
+export declare function complaintsAbout(message: string): string[];

package/dist/internal/guardian/commit-format.js

@@ -0,0 +1,63 @@
+/**
+ * Validates commit messages against conventional commit format,
+ * subject length limits and body line wrap rules.
+ *
+ * Shared rather than owned by the guardian, because there are two
+ * roads into the same repository and a rule enforced on one of them
+ * is not enforced. The guardian meets a commit typed into a shell by
+ * intercepting the command; `work record` never runs a command at
+ * all, committing through the exec seam, so it arrived behind the
+ * guardian rather than in front of it and was held only to the prose
+ * rules. This module is what both roads now ask.
+ */
+/** Validate a commit message against conventional commit rules. */
+export function validate(message) {
+    const lines = message.split("\n");
+    const subject = lines[0] || "";
+    const bodyLines = lines.length > 2 ? lines.slice(2) : [];
+    let bodyLongestLine = 0;
+    let bodyLongestLineNum = 0;
+    for (let i = 0; i < bodyLines.length; i++) {
+        const lineLen = bodyLines[i]?.length ?? 0;
+        if (lineLen > bodyLongestLine) {
+            bodyLongestLine = lineLen;
+            bodyLongestLineNum = i + 3; // offset for subject + blank line
+        }
+    }
+    return {
+        subjectLength: subject.length,
+        subjectOk: subject.length <= 50,
+        bodyWrapOk: bodyLongestLine <= 72,
+        bodyLongestLine,
+        bodyLongestLineNum,
+        conventionalOk: /^[a-z]+(\([a-z0-9/_-]+\))?!?:\s/.test(subject),
+    };
+}
+/**
+ * What is wrong with a commit message, said so a caller can fix it.
+ *
+ * For the road with nobody watching. The guardian renders the same
+ * facts as ticks and warnings next to a panel, which informs a person
+ * who is already deciding; a caller that gets a list of sentences can
+ * act on it without one. Empty means the message is fine.
+ *
+ * Each complaint names the measurement rather than the rule, because
+ * "subject is 63 characters, and the limit is 50" can be acted on and
+ * "subject too long" sends the reader to go and count.
+ */
+export function complaintsAbout(message) {
+    const checked = validate(message);
+    const said = [];
+    if (!checked.conventionalOk) {
+        said.push("the subject is not conventional form, which is type(scope): subject, " +
+            "with the scope optional and the type lower case");
+    }
+    if (!checked.subjectOk) {
+        said.push(`the subject is ${checked.subjectLength} characters and the limit is 50`);
+    }
+    if (!checked.bodyWrapOk) {
+        said.push(`body line ${checked.bodyLongestLineNum} is ${checked.bodyLongestLine} ` +
+            "characters and the limit is 72");
+    }
+    return said;
+}

package/dist/internal/guardian/commit-shell.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Git commit command parsing: locating a git commit past its
+ * global options and extracting its message (heredoc, -m/-am, or
+ * -F file) on the command model.
+ *
+ * These are commit-guardian internals. General-purpose shell
+ * parsing lives in lib/shell/.
+ */
+import { type CommandLine, type SimpleCommand } from "../../command/index.js";
+/**
+ * Find the git command in a tokenized line whose subcommand is
+ * `sub`, looking past leading global options so a form like
+ * `git -C dir commit` is still found.
+ */
+export declare function findGitCommand(line: CommandLine, sub: string): SimpleCommand | undefined;
+/** Whether a bash command contains a git commit, global options aside. */
+export declare function isGitCommitCommand(command: string): boolean;
+/**
+ * Extract the commit message from a bash command.
+ *
+ * Supports the heredoc form (git commit -F- <<'EOF'...EOF), one or
+ * more -m/--message flags (including the -am cluster), and a
+ * -F <file> read through the optional reader.
+ *
+ * Parsing runs on the command model, so only the git commit
+ * command's own argv and heredoc are read. A -m written inside a
+ * heredoc body, or a heredoc belonging to a chained command, is
+ * never mistaken for the message, because neither lives in the
+ * commit's argv.
+ *
+ * A `git commit -F <file>` (a real file, not `-F-` stdin) is
+ * resolved through the optional `readFile` reader, which is given
+ * the raw path and the command's effective working directory and
+ * returns the file's contents or null. Without a reader, or when
+ * the read fails, this returns null and the caller no-ops, so an
+ * unreadable file is a missed gate, never a wrong rewrite.
+ */
+export declare function extractMessage(command: string, readFile?: (rawPath: string, baseDir: string | null) => string | null): string | null;