@jitsusama/agentic-harness.core 0.1.0

package/dist/command/cwd.js

@@ -0,0 +1,60 @@
+/**
+ * Effective working directory of a command line: the base cwd
+ * composed with the leading `cd` segments. Consumers that resolve a
+ * relative path (the `git commit -F <file>` reader, say) ask here
+ * instead of scraping the first `cd` with a regex.
+ */
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+/**
+ * Compose the base cwd with the cd segments of the command line. A
+ * `before` source position bounds it to the cd segments that begin
+ * before that position, so a cd after the consuming command does
+ * not move the directory it runs in.
+ */
+export function effectiveCwd(line, baseCwd, before) {
+    let dir = baseCwd;
+    for (const command of line.commands) {
+        if (before !== undefined && command.span.start >= before)
+            break;
+        if (command.argv[0]?.text !== "cd")
+            continue;
+        const targetWord = command.argv[1];
+        if (!targetWord)
+            continue;
+        const target = literalTarget(targetWord);
+        if (target === undefined) {
+            return {
+                unresolvable: true,
+                reason: `cd target ${targetWord.text} is not statically resolvable`,
+            };
+        }
+        dir = applyCd(dir, target);
+    }
+    return { dir };
+}
+/**
+ * The literal directory a cd target names, or undefined when it
+ * depends on a variable, command substitution or glob we cannot
+ * resolve statically.
+ */
+function literalTarget(word) {
+    if (word.quoting === "single")
+        return word.text.slice(1, -1);
+    if (word.quoting === "double") {
+        const inner = word.text.slice(1, -1);
+        return /[$`]/.test(inner) ? undefined : inner;
+    }
+    if (word.quoting === "none") {
+        return /[$`*?[\]{}]/.test(word.text) ? undefined : word.text;
+    }
+    return undefined;
+}
+/** Apply one resolved cd target to the running directory. */
+function applyCd(dir, target) {
+    if (target === "~")
+        return homedir();
+    if (target.startsWith("~/"))
+        return join(homedir(), target.slice(2));
+    return isAbsolute(target) ? target : resolve(dir, target);
+}

package/dist/command/edit.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Splice-by-range editing for the command model. Edits replace only
+ * the byte ranges they target, so every untouched byte of the
+ * source survives identically. This is the safety guarantee: the
+ * model never reconstructs a command from parsed pieces.
+ */
+import type { Span } from "./types.js";
+/** A replacement of one source range with new text. */
+export interface Edit {
+    readonly span: Span;
+    readonly text: string;
+}
+/** Apply edits to the source, splicing only the targeted ranges. */
+export declare function applyEdits(source: string, edits: Edit[]): string;

package/dist/command/edit.js

@@ -0,0 +1,22 @@
+/**
+ * Splice-by-range editing for the command model. Edits replace only
+ * the byte ranges they target, so every untouched byte of the
+ * source survives identically. This is the safety guarantee: the
+ * model never reconstructs a command from parsed pieces.
+ */
+/** Apply edits to the source, splicing only the targeted ranges. */
+export function applyEdits(source, edits) {
+    if (edits.length === 0)
+        return source;
+    const ordered = [...edits].sort((a, b) => a.span.start - b.span.start);
+    let result = "";
+    let cursor = 0;
+    for (const edit of ordered) {
+        if (edit.span.start < cursor) {
+            throw new Error(`overlapping edits: span ${edit.span.start}-${edit.span.end} overlaps a prior edit ending at ${cursor}`);
+        }
+        result += source.slice(cursor, edit.span.start) + edit.text;
+        cursor = edit.span.end;
+    }
+    return result + source.slice(cursor);
+}

package/dist/command/flags.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Flag layer: understand a command's flags against a caller-supplied
+ * spec. The core ships no flag tables; each domain passes the spec
+ * for the command it owns, so knowledge of a command lives in one
+ * place and is imported where needed.
+ */
+import type { SimpleCommand, Span } from "./types.js";
+/** One known flag: its canonical name, long and short forms. */
+export interface FlagDef {
+    readonly name: string;
+    readonly long?: string;
+    readonly short?: string;
+    readonly takesValue: boolean;
+}
+/** The set of flags a caller knows about for a command. */
+export interface FlagSpec {
+    readonly flags: FlagDef[];
+}
+/** A located flag occurrence and, when it takes one, its value. */
+export interface FlagMatch {
+    readonly name: string;
+    readonly flagSpan: Span;
+    readonly value?: string;
+    readonly valueSpan?: Span;
+}
+/** Find the first occurrence of a named flag in a command. */
+export declare function findFlag(command: SimpleCommand, spec: FlagSpec, name: string): FlagMatch | undefined;
+/** Find every occurrence of a named flag in a command, in order. */
+export declare function findFlags(command: SimpleCommand, spec: FlagSpec, name: string): FlagMatch[];

package/dist/command/flags.js

@@ -0,0 +1,111 @@
+/**
+ * Flag layer: understand a command's flags against a caller-supplied
+ * spec. The core ships no flag tables; each domain passes the spec
+ * for the command it owns, so knowledge of a command lives in one
+ * place and is imported where needed.
+ */
+/** Find the first occurrence of a named flag in a command. */
+export function findFlag(command, spec, name) {
+    return findFlags(command, spec, name)[0];
+}
+/** Find every occurrence of a named flag in a command, in order. */
+export function findFlags(command, spec, name) {
+    const def = spec.flags.find((flag) => flag.name === name);
+    if (!def)
+        return [];
+    const { argv } = command;
+    const matches = [];
+    for (let i = 0; i < argv.length; i++) {
+        const direct = matchAt(def, argv[i], argv[i + 1]);
+        if (direct) {
+            matches.push(direct);
+            continue;
+        }
+        const clustered = matchInCluster(spec, def, argv[i], argv[i + 1]);
+        if (clustered)
+            matches.push(clustered);
+    }
+    return matches;
+}
+/**
+ * Match one flag definition against a word and the word that
+ * follows it, covering the long, long=value, short and attached
+ * short forms. Returns a match, or undefined when the word is not
+ * this flag.
+ */
+function matchAt(def, word, next) {
+    const separateValue = () => def.takesValue && next ? { value: next.text, valueSpan: next.span } : {};
+    const attachedValue = (prefixLength) => ({
+        name: def.name,
+        flagSpan: word.span,
+        value: word.text.slice(prefixLength),
+        valueSpan: { start: word.span.start + prefixLength, end: word.span.end },
+    });
+    const long = def.long ? `--${def.long}` : undefined;
+    if (long && word.text === long) {
+        return { name: def.name, flagSpan: word.span, ...separateValue() };
+    }
+    if (long && word.text.startsWith(`${long}=`)) {
+        return attachedValue(long.length + 1);
+    }
+    const short = def.short ? `-${def.short}` : undefined;
+    if (short && word.text === short) {
+        return { name: def.name, flagSpan: word.span, ...separateValue() };
+    }
+    if (short &&
+        def.takesValue &&
+        word.text.length > short.length &&
+        word.text.startsWith(short)) {
+        return attachedValue(short.length);
+    }
+    return undefined;
+}
+/**
+ * Match a flag inside a clustered short word like `-am`, where
+ * leading characters are boolean short flags and a later character
+ * is the one being looked for. Walks the cluster left to right
+ * against the full spec; bails to undefined the moment it meets a
+ * character the spec does not know or an earlier short flag that
+ * would itself consume a value, since then the cluster cannot be
+ * read safely.
+ */
+function matchInCluster(spec, def, word, next) {
+    const { text } = word;
+    if (!text.startsWith("-") || text.startsWith("--") || text.length < 2) {
+        return undefined;
+    }
+    const chars = text.slice(1);
+    for (let j = 0; j < chars.length; j++) {
+        const member = spec.flags.find((flag) => flag.short === chars[j]);
+        if (!member)
+            return undefined;
+        if (member.name === def.name) {
+            if (!def.takesValue)
+                return { name: def.name, flagSpan: word.span };
+            const rest = chars.slice(j + 1);
+            if (rest.length > 0) {
+                const prefixLength = 1 + j + 1;
+                return {
+                    name: def.name,
+                    flagSpan: word.span,
+                    value: rest,
+                    valueSpan: {
+                        start: word.span.start + prefixLength,
+                        end: word.span.end,
+                    },
+                };
+            }
+            return next
+                ? {
+                    name: def.name,
+                    flagSpan: word.span,
+                    value: next.text,
+                    valueSpan: next.span,
+                }
+                : { name: def.name, flagSpan: word.span };
+        }
+        if (member.takesValue)
+            return undefined;
+    }
+    return undefined;
+}

package/dist/command/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Command model: a lossless, range-indexed view of a bash command
+ * line, plus a flag-spec layer for understanding and a splice
+ * primitive for editing.
+ *
+ * Public entry point. Guardians and interceptors pull from here to
+ * detect, enforce and rewrite commands without reconstructing them.
+ */
+export type { EffectiveCwd } from "./cwd.js";
+export { effectiveCwd } from "./cwd.js";
+export type { Edit } from "./edit.js";
+export { applyEdits } from "./edit.js";
+export type { FlagDef, FlagMatch, FlagSpec } from "./flags.js";
+export { findFlag, findFlags } from "./flags.js";
+export { tokenize } from "./tokenize.js";
+export type { CommandLine, Connector, Heredoc, Quoting, Redirect, SimpleCommand, Span, Word, } from "./types.js";

package/dist/command/index.js

@@ -0,0 +1,12 @@
+/**
+ * Command model: a lossless, range-indexed view of a bash command
+ * line, plus a flag-spec layer for understanding and a splice
+ * primitive for editing.
+ *
+ * Public entry point. Guardians and interceptors pull from here to
+ * detect, enforce and rewrite commands without reconstructing them.
+ */
+export { effectiveCwd } from "./cwd.js";
+export { applyEdits } from "./edit.js";
+export { findFlag, findFlags } from "./flags.js";
+export { tokenize } from "./tokenize.js";

package/dist/command/tokenize.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tokenizer for the command model. Turns a bash command string
+ * into a lossless, range-indexed CommandLine.
+ */
+import type { CommandLine } from "./types.js";
+/** Tokenize a bash command line into a CommandLine. */
+export declare function tokenize(source: string): CommandLine;

package/dist/command/tokenize.js

@@ -0,0 +1,315 @@
+/**
+ * Tokenizer for the command model. Turns a bash command string
+ * into a lossless, range-indexed CommandLine.
+ */
+import { matchHeredocs } from "../shell/parse.js";
+/** Tokenize a bash command line into a CommandLine. */
+export function tokenize(source) {
+    const heredocs = collectHeredocs(source);
+    const { segments, connectors } = splitTopLevel(source, heredocs);
+    const commands = [];
+    for (const segment of segments) {
+        const command = buildCommand(source, segment.start, segment.end, heredocs);
+        if (command)
+            commands.push(command);
+    }
+    const unsupportedReason = detectUnsupported(source, heredocs) ?? detectControlFlow(commands);
+    return {
+        source,
+        commands,
+        connectors,
+        supported: unsupportedReason === undefined,
+        ...(unsupportedReason ? { unsupportedReason } : {}),
+    };
+}
+/**
+ * Scan for constructs outside the supported grammar, ignoring
+ * quoted text and heredoc bodies (where the bytes are literal or
+ * user content, not command structure). Returns a reason when one
+ * is found, so a consumer can fail closed on it.
+ */
+function detectUnsupported(source, heredocs) {
+    let i = 0;
+    const n = source.length;
+    while (i < n) {
+        const body = heredocs.find((h) => i >= h.bodyStart && i < h.bodyEnd);
+        if (body) {
+            i = body.bodyEnd;
+            continue;
+        }
+        const ch = source[i];
+        if (ch === "'" || ch === '"') {
+            i = skipQuoted(source, i);
+            continue;
+        }
+        if (ch === "\\") {
+            i += 2;
+            continue;
+        }
+        if (ch === "$" && source[i + 1] === "(") {
+            return "command substitution $(...) is not supported";
+        }
+        if (ch === "`") {
+            return "backtick command substitution is not supported";
+        }
+        if (ch === "(") {
+            return "a subshell (...) is not supported";
+        }
+        if (ch === "{" && isWhitespace(source[i + 1])) {
+            return "a brace group { ...; } is not supported";
+        }
+        i++;
+    }
+    return undefined;
+}
+const CONTROL_FLOW_KEYWORDS = new Set([
+    "if",
+    "then",
+    "else",
+    "elif",
+    "fi",
+    "for",
+    "while",
+    "until",
+    "do",
+    "done",
+    "case",
+    "esac",
+    "select",
+    "function",
+]);
+/** Flag a command whose name is a shell control-flow keyword. */
+function detectControlFlow(commands) {
+    for (const command of commands) {
+        const name = command.argv[0]?.text;
+        if (name && CONTROL_FLOW_KEYWORDS.has(name)) {
+            return `shell control flow (${name}) is not supported`;
+        }
+    }
+    return undefined;
+}
+/** Locate every heredoc in the source, with body and whole spans. */
+function collectHeredocs(source) {
+    return matchHeredocs(source).map((match) => {
+        const bodyStart = source.indexOf("\n", match.index) + 1;
+        return {
+            index: match.index,
+            end: match.index + match.length,
+            bodyStart,
+            bodyEnd: bodyStart + match.body.length,
+            delimiter: match.delim,
+            quoted: match.quoted,
+        };
+    });
+}
+/**
+ * Walk the source at the top level, respecting quoting, and split
+ * it at connector operators (&&, ||, ;, |, newline). Returns the
+ * segment spans between operators and the connectors themselves.
+ */
+function splitTopLevel(source, heredocs) {
+    const segments = [];
+    const connectors = [];
+    let i = 0;
+    let segmentStart = 0;
+    const n = source.length;
+    while (i < n) {
+        const heredoc = heredocs.find((h) => h.index === i);
+        if (heredoc) {
+            i = heredoc.end;
+            continue;
+        }
+        if (isContinuation(source, i)) {
+            i += 2;
+            continue;
+        }
+        const ch = source[i];
+        if (ch === "'" || ch === '"') {
+            i = skipQuoted(source, i);
+            continue;
+        }
+        const op = connectorAt(source, i);
+        if (op) {
+            segments.push({ start: segmentStart, end: i });
+            connectors.push({ op, span: { start: i, end: i + op.length } });
+            i += op.length;
+            segmentStart = i;
+            continue;
+        }
+        i++;
+    }
+    segments.push({ start: segmentStart, end: n });
+    return { segments, connectors };
+}
+/** The connector operator beginning at index i, or undefined. */
+function connectorAt(source, i) {
+    const ch = source[i];
+    const next = source[i + 1];
+    if (ch === "&" && next === "&")
+        return "&&";
+    // A lone & backgrounds the preceding command. Exclude the
+    // redirect forms: &>/&>> (next is >) and >& duplication (the
+    // previous char is >), so only a true background & splits.
+    if (ch === "&" && next !== ">" && source[i - 1] !== ">")
+        return "&";
+    if (ch === "|" && next === "|")
+        return "||";
+    if (ch === "|" && next === "&")
+        return "|&";
+    if (ch === "|")
+        return "|";
+    if (ch === ";")
+        return ";";
+    if (ch === "\n")
+        return "\n";
+    return undefined;
+}
+/** Build a simple command from the words in source[start, end). */
+function buildCommand(source, start, end, heredocs) {
+    const heredoc = heredocs.find((h) => h.index >= start && h.index < end);
+    const scanEnd = heredoc ? source.indexOf("\n", heredoc.index) : end;
+    const openerWords = scanWords(source, start, scanEnd).filter((word) => !heredoc || word.span.start < heredoc.index);
+    if (openerWords.length === 0)
+        return undefined;
+    let firstArgv = 0;
+    while (firstArgv < openerWords.length &&
+        isAssignment(openerWords[firstArgv].text)) {
+        firstArgv++;
+    }
+    const assignments = openerWords.slice(0, firstArgv);
+    const { argv, redirects } = extractRedirects(openerWords.slice(firstArgv));
+    const spanEnd = heredoc
+        ? heredoc.end
+        : openerWords[openerWords.length - 1].span.end;
+    return {
+        span: { start: openerWords[0].span.start, end: spanEnd },
+        assignments,
+        argv,
+        redirects,
+        ...(heredoc ? { heredoc: toHeredoc(heredoc) } : {}),
+    };
+}
+/** Project a HeredocInfo onto the public Heredoc shape. */
+function toHeredoc(info) {
+    return {
+        delimiter: info.delimiter,
+        quoted: info.quoted,
+        bodySpan: { start: info.bodyStart, end: info.bodyEnd },
+        span: { start: info.index, end: info.end },
+    };
+}
+const REDIRECT = /^(\d*)(>>|>|<)(&\d+)?$/;
+/**
+ * Pull redirects out of a word list. A redirect operator that names
+ * a file descriptor duplication (2>&1) stands alone; any other
+ * operator consumes the following word as its target.
+ */
+function extractRedirects(words) {
+    const argv = [];
+    const redirects = [];
+    for (let j = 0; j < words.length; j++) {
+        const word = words[j];
+        const match = REDIRECT.exec(word.text);
+        if (!match) {
+            argv.push(word);
+            continue;
+        }
+        const hasDuplication = Boolean(match[3]);
+        const target = !hasDuplication ? words[j + 1] : undefined;
+        if (target) {
+            redirects.push({
+                span: { start: word.span.start, end: target.span.end },
+                operator: word.text,
+                target,
+            });
+            j++;
+        }
+        else {
+            redirects.push({
+                span: { start: word.span.start, end: word.span.end },
+                operator: word.text,
+            });
+        }
+    }
+    return { argv, redirects };
+}
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+/** Whether a word is a leading NAME=value env assignment. */
+function isAssignment(text) {
+    return ASSIGNMENT.test(text);
+}
+const isWhitespace = (ch) => ch === " " || ch === "\t" || ch === "\n";
+/** Whether a backslash-newline line continuation begins at i. */
+function isContinuation(source, i) {
+    return source[i] === "\\" && source[i + 1] === "\n";
+}
+/**
+ * Index just past a quoted span beginning at the quote at i. Inside
+ * double quotes a backslash escapes the next character, so an
+ * escaped quote does not end the span; single quotes take no
+ * escapes, so a backslash there is literal.
+ */
+function skipQuoted(source, i) {
+    const quote = source[i];
+    i++;
+    while (i < source.length && source[i] !== quote) {
+        if (quote === '"' && source[i] === "\\" && i + 1 < source.length) {
+            i += 2;
+            continue;
+        }
+        i++;
+    }
+    if (i < source.length)
+        i++;
+    return i;
+}
+/**
+ * Split source[start, end) into words, treating single- and
+ * double-quoted spans as part of the surrounding word so a quoted
+ * space does not break the word. Each word's text is the raw source
+ * slice, so the span maps back to the source exactly.
+ */
+function scanWords(source, start, end) {
+    const words = [];
+    let i = start;
+    while (i < end) {
+        while (i < end && (isWhitespace(source[i]) || isContinuation(source, i))) {
+            i += isContinuation(source, i) ? 2 : 1;
+        }
+        if (i >= end)
+            break;
+        const wordStart = i;
+        let sawSingle = false;
+        let sawDouble = false;
+        while (i < end && !isWhitespace(source[i]) && !isContinuation(source, i)) {
+            const ch = source[i];
+            if (ch === "'") {
+                sawSingle = true;
+                i = skipQuoted(source, i);
+                continue;
+            }
+            if (ch === '"') {
+                sawDouble = true;
+                i = skipQuoted(source, i);
+                continue;
+            }
+            i++;
+        }
+        words.push({
+            span: { start: wordStart, end: i },
+            text: source.slice(wordStart, i),
+            quoting: classifyQuoting(sawSingle, sawDouble),
+        });
+    }
+    return words;
+}
+/** Classify a word's quote style from which quote kinds it used. */
+function classifyQuoting(sawSingle, sawDouble) {
+    if (sawSingle && sawDouble)
+        return "mixed";
+    if (sawSingle)
+        return "single";
+    if (sawDouble)
+        return "double";
+    return "none";
+}

package/dist/command/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Core types for the command model: a lossless, range-indexed
+ * description of a bash command line.
+ *
+ * Every structural element carries a byte span into the original
+ * source string, so a consumer can edit by splicing exactly the
+ * range it targets and leave everything else untouched.
+ */
+/** A half-open byte range [start, end) into the source string. */
+export interface Span {
+    readonly start: number;
+    readonly end: number;
+}
+/** How a word was quoted in the source. */
+export type Quoting = "none" | "single" | "double" | "mixed";
+/** A single shell word (a command name, a flag, a value). */
+export interface Word {
+    readonly span: Span;
+    readonly text: string;
+    readonly quoting: Quoting;
+}
+/** A heredoc attached to a simple command. */
+export interface Heredoc {
+    readonly delimiter: string;
+    readonly quoted: boolean;
+    readonly bodySpan: Span;
+    readonly span: Span;
+}
+/**
+ * A redirect, and the word it names when it names one.
+ *
+ * The operator is kept as written, so a consumer can tell a content
+ * target (`>`, `>>`) from a stream being routed (`2>`, `&>`). The target
+ * is absent for a file-descriptor duplication such as `2>&1`, which names
+ * no file at all.
+ */
+export interface Redirect {
+    readonly span: Span;
+    readonly operator: string;
+    readonly target?: Word;
+}
+/** A simple command: optional env assignments, argv and redirects. */
+export interface SimpleCommand {
+    readonly span: Span;
+    readonly assignments: Word[];
+    readonly argv: Word[];
+    readonly redirects: Redirect[];
+    readonly heredoc?: Heredoc;
+}
+/** A top-level operator joining two simple commands. */
+export interface Connector {
+    readonly op: "&&" | "||" | ";" | "|" | "|&" | "&" | "\n";
+    readonly span: Span;
+}
+/**
+ * A tokenized command line. The commands and connectors interleave
+ * in source order; `supported` is false when the line contains a
+ * construct outside the grammar the model understands.
+ */
+export interface CommandLine {
+    readonly source: string;
+    readonly commands: SimpleCommand[];
+    readonly connectors: Connector[];
+    readonly supported: boolean;
+    readonly unsupportedReason?: string;
+}

package/dist/command/types.js

@@ -0,0 +1,9 @@
+/**
+ * Core types for the command model: a lossless, range-indexed
+ * description of a bash command line.
+ *
+ * Every structural element carries a byte span into the original
+ * source string, so a consumer can edit by splicing exactly the
+ * range it targets and leave everything else untouched.
+ */
+export {};

package/dist/completion/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Side completions: run a one-shot completion against a model
+ * from the registry, off the agent's own loop.
+ *
+ * The advisor and correction capture both need a cheap second
+ * model to distill or judge without disturbing the doer. This is
+ * the shared mechanism, proven by the milestone-5 probe.
+ *
+ * Actually running a model is a port (`CompleteSimple`), not
+ * something this package can do on its own: `runSideCompletion` and
+ * `runInvestigation` both take one as a parameter. An adapter
+ * resolves its own host's completion function and passes it in.
+ */
+export { type InvestigationRequest, type InvestigationResult, type LoopTool, runInvestigation, } from "./investigate.js";
+export { looksLikeGlm, type ModelRef, type ModelTarget, pickModel, } from "./resolve.js";
+export { runSideCompletion, type SideCompletionRequest, type SideCompletionResult, } from "./side.js";
+export type { CompatModule, CompleteSimple, CompletionMessage, CompletionRegistry, } from "./types.js";