@jitsusama/agentic-harness.core 0.1.0

package/dist/internal/refs/builtins.js

@@ -0,0 +1,179 @@
+/**
+ * Built-in ref types: GitHub issues, GitHub PRs, GitHub
+ * repos, Slack messages and Slack threads.
+ *
+ * Each type recognises its own surface forms in text and
+ * builds a canonical URL from a stored value. The canonical
+ * value is the smallest unambiguous string that lets us
+ * rebuild a URL without losing information.
+ *
+ *     type             canonical value           url shape
+ *     -------------    -----------------------   ----------------------------------
+ *     github-issue     owner/repo#NNN            github.com/owner/repo/issues/NNN
+ *     github-pr        owner/repo#NNN            github.com/owner/repo/pull/NNN
+ *     github-repo      owner/repo                github.com/owner/repo
+ *     slack-message    workspace/CHANNEL/pTS     <workspace>.slack.com/archives/CHANNEL/pTS
+ *     slack-thread     workspace/CHANNEL/pTS     <workspace>.slack.com/archives/CHANNEL/pTS
+ *
+ * GitHub's numbering shares one namespace between issues
+ * and PRs within a repo, so the bare `owner/repo#NNN`
+ * notation cannot distinguish them. We match the bare form
+ * as `github-issue` only; PRs require a `/pull/` URL form
+ * to disambiguate. The quest tool resolves the actual kind
+ * via GitHub API when it matters.
+ *
+ * Slack threads and messages share their URL surface; we
+ * discriminate by the `thread_ts` query parameter. A URL
+ * with `thread_ts=` is a `slack-thread` pointing at the
+ * thread parent; a URL without is a `slack-message`.
+ */
+const GITHUB_URL_BASE = "https://github.com";
+const githubIssue = {
+    type: "github-issue",
+    matchAll(text) {
+        const results = [];
+        const seen = new Set();
+        const push = (value) => {
+            if (seen.has(value))
+                return;
+            seen.add(value);
+            results.push(value);
+        };
+        // URLs: https://github.com/owner/repo/issues/NNN
+        const urlRegex = /https?:\/\/(?:www\.)?github\.com\/([\w.-]+)\/([\w.-]+)\/issues\/(\d+)/g;
+        for (const m of text.matchAll(urlRegex)) {
+            push(`${m[1]}/${m[2]}#${m[3]}`);
+        }
+        // Bare form: owner/repo#NNN. Constrain owner and repo
+        // to look like GitHub identifiers and require word
+        // boundaries so we don't match inside URLs we just
+        // captured above.
+        const bareRegex = /(?<![\w/])([\w.-]+)\/([\w.-]+)#(\d+)\b/g;
+        for (const m of text.matchAll(bareRegex)) {
+            push(`${m[1]}/${m[2]}#${m[3]}`);
+        }
+        return results;
+    },
+    url(value) {
+        const m = /^([\w.-]+)\/([\w.-]+)#(\d+)$/.exec(value);
+        if (!m)
+            return undefined;
+        return `${GITHUB_URL_BASE}/${m[1]}/${m[2]}/issues/${m[3]}`;
+    },
+};
+const githubPr = {
+    type: "github-pr",
+    matchAll(text) {
+        const results = [];
+        const urlRegex = /https?:\/\/(?:www\.)?github\.com\/([\w.-]+)\/([\w.-]+)\/pull\/(\d+)/g;
+        for (const m of text.matchAll(urlRegex)) {
+            results.push(`${m[1]}/${m[2]}#${m[3]}`);
+        }
+        return results;
+    },
+    url(value) {
+        const m = /^([\w.-]+)\/([\w.-]+)#(\d+)$/.exec(value);
+        if (!m)
+            return undefined;
+        return `${GITHUB_URL_BASE}/${m[1]}/${m[2]}/pull/${m[3]}`;
+    },
+};
+const githubRepo = {
+    type: "github-repo",
+    matchAll(text) {
+        // Match https://github.com/owner/repo with no further
+        // path component. The lookahead allows whitespace,
+        // end-of-input, markdown link-closing characters or a
+        // trailing slash with the same suffix.
+        const regex = /https?:\/\/(?:www\.)?github\.com\/([\w.-]+)\/([\w.-]+)\/?(?=$|\s|[)\].,;])/g;
+        const results = [];
+        for (const m of text.matchAll(regex)) {
+            results.push(`${m[1]}/${m[2]}`);
+        }
+        return results;
+    },
+    url(value) {
+        const m = /^([\w.-]+)\/([\w.-]+)$/.exec(value);
+        if (!m)
+            return undefined;
+        return `${GITHUB_URL_BASE}/${m[1]}/${m[2]}`;
+    },
+};
+const SLACK_URL_REGEX = /https:\/\/([\w-]+)\.slack\.com\/archives\/([A-Z0-9]+)\/(p\d+)(\?[^\s"')\]]*)?/g;
+/**
+ * Why a Slack ref will not become a URL, or nothing when it will.
+ *
+ * Shared by both Slack types, which store and encode identically.
+ *
+ * The two-part case is called out by name because it is not a typo,
+ * it is the overwhelming majority: a value written from Slack API
+ * data has the channel and the timestamp and no workspace, since the
+ * API never says which workspace you are talking to. Only a value
+ * parsed out of a URL carries all three. Naming the missing part and
+ * where it comes from is the difference between a fixable record and
+ * a link that is simply absent.
+ */
+function whyNoSlackUrl(value) {
+    if (SLACK_VALUE_REGEX.test(value))
+        return undefined;
+    if (/^[A-Z0-9]+\/p?\d+(\.\d+)?$/.test(value)) {
+        return (`"${value}" names a channel and a timestamp but no workspace, ` +
+            "which is what a ref written from Slack API data looks like: the " +
+            "API never says which workspace you are talking to. A link needs " +
+            "workspace/CHANNEL/pTIMESTAMP, so add the workspace this came from.");
+    }
+    return (`"${value}" is not workspace/CHANNEL/pTIMESTAMP, so there is ` +
+        "nothing to build an archive link out of.");
+}
+const SLACK_VALUE_REGEX = /^([\w-]+)\/([A-Z0-9]+)\/(p\d+)$/;
+function slackUrl(value) {
+    const m = SLACK_VALUE_REGEX.exec(value);
+    if (!m)
+        return undefined;
+    return `https://${m[1]}.slack.com/archives/${m[2]}/${m[3]}`;
+}
+const slackMessage = {
+    type: "slack-message",
+    matchAll(text) {
+        const results = [];
+        for (const m of text.matchAll(SLACK_URL_REGEX)) {
+            const query = m[4] ?? "";
+            if (query.includes("thread_ts="))
+                continue;
+            results.push(`${m[1]}/${m[2]}/${m[3]}`);
+        }
+        return results;
+    },
+    url: slackUrl,
+    whyNoUrl: whyNoSlackUrl,
+};
+const slackThread = {
+    type: "slack-thread",
+    matchAll(text) {
+        const results = [];
+        for (const m of text.matchAll(SLACK_URL_REGEX)) {
+            const query = m[4] ?? "";
+            const threadTsMatch = /thread_ts=([\d.]+)/.exec(query);
+            if (!threadTsMatch)
+                continue;
+            // Canonical value points at the THREAD PARENT
+            // (whose ts is `thread_ts`), not the reply we
+            // matched. Convert "1778683833.000200" to
+            // "p1778683833000200" to match Slack's URL form
+            // for the parent message.
+            const parentTs = `p${threadTsMatch[1].replace(".", "")}`;
+            results.push(`${m[1]}/${m[2]}/${parentTs}`);
+        }
+        return results;
+    },
+    url: slackUrl,
+    whyNoUrl: whyNoSlackUrl,
+};
+/** All built-in ref types in stable iteration order. */
+export const BUILTIN_REF_TYPES = [
+    githubIssue,
+    githubPr,
+    githubRepo,
+    slackMessage,
+    slackThread,
+];

package/dist/internal/refs/registry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Refs registry: a process-global map from ref type
+ * identifier to `RefType` definition.
+ *
+ * Implementation note: backed by the shared
+ * `createGlobalSymbolRegistry` helper so every package
+ * registry follows the same shape. The slot persists
+ * across module reimport but NOT across pi's `/reload`,
+ * which spawns a fresh process. Tests call `clear()` to
+ * isolate registrations between cases.
+ */
+import type { Ref, RefType } from "../../refs/types.js";
+export declare const register: (refType: RefType) => void;
+export declare const unregister: (type: string) => void;
+export declare const clear: () => void;
+export declare const get: (type: string) => RefType | undefined;
+export declare const list: () => RefType[];
+/**
+ * Run every registered type's `matchAll` against the given
+ * text and return the union of matches. Order: ref types
+ * are visited in registration order; matches within a type
+ * follow that type's own order. Duplicate `{type, value}`
+ * pairs are dropped.
+ */
+export declare function parseAll(text: string): Ref[];

package/dist/internal/refs/registry.js

@@ -0,0 +1,42 @@
+/**
+ * Refs registry: a process-global map from ref type
+ * identifier to `RefType` definition.
+ *
+ * Implementation note: backed by the shared
+ * `createGlobalSymbolRegistry` helper so every package
+ * registry follows the same shape. The slot persists
+ * across module reimport but NOT across pi's `/reload`,
+ * which spawns a fresh process. Tests call `clear()` to
+ * isolate registrations between cases.
+ */
+import { createGlobalSymbolRegistry } from "../registry/global-symbol-registry.js";
+const registry = createGlobalSymbolRegistry({
+    slot: "pi:agentic-harness:refs-registry",
+    getId: (rt) => rt.type,
+});
+export const register = (refType) => registry.register(refType);
+export const unregister = (type) => registry.unregister(type);
+export const clear = () => registry.clear();
+export const get = (type) => registry.get(type);
+export const list = () => registry.list();
+/**
+ * Run every registered type's `matchAll` against the given
+ * text and return the union of matches. Order: ref types
+ * are visited in registration order; matches within a type
+ * follow that type's own order. Duplicate `{type, value}`
+ * pairs are dropped.
+ */
+export function parseAll(text) {
+    const refs = [];
+    const seen = new Set();
+    for (const rt of list()) {
+        for (const value of rt.matchAll(text)) {
+            const key = `${rt.type}|${value}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            refs.push({ type: rt.type, value });
+        }
+    }
+    return refs;
+}

package/dist/internal/registry/global-symbol-registry.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared helper for pluggable registries stashed on
+ * `globalThis` under a `Symbol.for` key.
+ *
+ * Several library modules (refs, people handle types,
+ * terminal drivers, tree providers, URL fetchers) ship the
+ * same shape: a Map keyed by a stable id, behind a
+ * symbol-keyed slot on globalThis so HMR-style reloads
+ * don't lose registrations. Each used to inline the same
+ * five-function quintet. This helper deduplicates the
+ * mechanism so a new registry is a three-line wrapper.
+ *
+ * The slot persists across module reimport, NOT across pi's
+ * own `/reload` (which spawns a new process and a fresh
+ * globalThis). Callers that need to reseed built-ins on
+ * activate should idempotently call their `registerBuiltin*`
+ * helper.
+ */
+export interface RegistryHandle<T> {
+    register(value: T): void;
+    unregister(id: string): void;
+    clear(): void;
+    get(id: string): T | undefined;
+    list(): T[];
+}
+/**
+ * Create a registry backed by a globalThis slot keyed by
+ * `Symbol.for(slot)`. The slot key should be unique across
+ * the package (use a `pi:<package>:<kind>` shape so
+ * registrations don't alias across libraries).
+ *
+ * `getId` extracts the stable id from a registered value.
+ */
+export declare function createGlobalSymbolRegistry<T>(options: {
+    slot: string;
+    getId: (value: T) => string;
+}): RegistryHandle<T>;

package/dist/internal/registry/global-symbol-registry.js

@@ -0,0 +1,55 @@
+/**
+ * Shared helper for pluggable registries stashed on
+ * `globalThis` under a `Symbol.for` key.
+ *
+ * Several library modules (refs, people handle types,
+ * terminal drivers, tree providers, URL fetchers) ship the
+ * same shape: a Map keyed by a stable id, behind a
+ * symbol-keyed slot on globalThis so HMR-style reloads
+ * don't lose registrations. Each used to inline the same
+ * five-function quintet. This helper deduplicates the
+ * mechanism so a new registry is a three-line wrapper.
+ *
+ * The slot persists across module reimport, NOT across pi's
+ * own `/reload` (which spawns a new process and a fresh
+ * globalThis). Callers that need to reseed built-ins on
+ * activate should idempotently call their `registerBuiltin*`
+ * helper.
+ */
+/**
+ * Create a registry backed by a globalThis slot keyed by
+ * `Symbol.for(slot)`. The slot key should be unique across
+ * the package (use a `pi:<package>:<kind>` shape so
+ * registrations don't alias across libraries).
+ *
+ * `getId` extracts the stable id from a registered value.
+ */
+export function createGlobalSymbolRegistry(options) {
+    const key = Symbol.for(options.slot);
+    function entries() {
+        const host = globalThis;
+        const existing = host[key];
+        if (existing)
+            return existing;
+        const fresh = new Map();
+        host[key] = fresh;
+        return fresh;
+    }
+    return {
+        register(value) {
+            entries().set(options.getId(value), value);
+        },
+        unregister(id) {
+            entries().delete(id);
+        },
+        clear() {
+            entries().clear();
+        },
+        get(id) {
+            return entries().get(id);
+        },
+        list() {
+            return [...entries().values()];
+        },
+    };
+}

package/dist/internal/review/registry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Review provider registry: process-global map from provider
+ * id to `ReviewProvider`. Mirrors the tree, refs, people and
+ * terminal registries and uses the same shared
+ * `createGlobalSymbolRegistry` helper.
+ */
+import type { ReviewProvider } from "../../review/provider.js";
+export declare const register: (provider: ReviewProvider) => void;
+export declare const unregister: (id: string) => void;
+export declare const clear: () => void;
+export declare const get: (id: string) => ReviewProvider | undefined;
+export declare const list: () => ReviewProvider[];

package/dist/internal/review/registry.js

@@ -0,0 +1,16 @@
+/**
+ * Review provider registry: process-global map from provider
+ * id to `ReviewProvider`. Mirrors the tree, refs, people and
+ * terminal registries and uses the same shared
+ * `createGlobalSymbolRegistry` helper.
+ */
+import { createGlobalSymbolRegistry } from "../registry/global-symbol-registry.js";
+const registry = createGlobalSymbolRegistry({
+    slot: "pi:agentic-harness:review-providers",
+    getId: (provider) => provider.id,
+});
+export const register = (provider) => registry.register(provider);
+export const unregister = (id) => registry.unregister(id);
+export const clear = () => registry.clear();
+export const get = (id) => registry.get(id);
+export const list = () => registry.list();

package/dist/internal/sqlite/db.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Thin promise wrapper over the callback-based sqlite3
+ * driver, shared by the local structured stores (memory,
+ * observability). sqlite3 is a native module, so it is
+ * lazy-imported on first open; callers speak promises and
+ * never touch the driver directly.
+ */
+/** A promise-speaking handle to a SQLite database. */
+export interface Db {
+    run(sql: string, params?: readonly unknown[]): Promise<void>;
+    all<T>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+    exec(sql: string): Promise<void>;
+    close(): Promise<void>;
+}
+/** Open a SQLite database at the given path (`:memory:` for tests). */
+export declare function openDb(dbPath: string): Promise<Db>;

package/dist/internal/sqlite/db.js

@@ -0,0 +1,26 @@
+/**
+ * Thin promise wrapper over the callback-based sqlite3
+ * driver, shared by the local structured stores (memory,
+ * observability). sqlite3 is a native module, so it is
+ * lazy-imported on first open; callers speak promises and
+ * never touch the driver directly.
+ */
+/** Open a SQLite database at the given path (`:memory:` for tests). */
+export async function openDb(dbPath) {
+    const sqlite3 = await import("sqlite3");
+    const database = new sqlite3.default.Database(dbPath);
+    return {
+        run: (sql, params = []) => new Promise((resolve, reject) => {
+            database.run(sql, params, (err) => (err ? reject(err) : resolve()));
+        }),
+        all: (sql, params = []) => new Promise((resolve, reject) => {
+            database.all(sql, params, (err, rows) => err ? reject(err) : resolve(rows));
+        }),
+        exec: (sql) => new Promise((resolve, reject) => {
+            database.exec(sql, (err) => (err ? reject(err) : resolve()));
+        }),
+        close: () => new Promise((resolve, reject) => {
+            database.close((err) => (err ? reject(err) : resolve()));
+        }),
+    };
+}

package/dist/internal/terminal/builtins.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Built-in terminal drivers, in the order
+ * `resolveDriver` tries them when no preferred driver is
+ * set. The fallback driver lands last so a real driver
+ * wins when one is present.
+ */
+import type { TerminalDriver } from "../../terminal/types.js";
+export declare const BUILTIN_TERMINAL_DRIVERS: readonly TerminalDriver[];

package/dist/internal/terminal/builtins.js

@@ -0,0 +1,14 @@
+/**
+ * Built-in terminal drivers, in the order
+ * `resolveDriver` tries them when no preferred driver is
+ * set. The fallback driver lands last so a real driver
+ * wins when one is present.
+ */
+import { fallback } from "./drivers/fallback.js";
+import { tmux } from "./drivers/tmux.js";
+import { wezterm } from "./drivers/wezterm.js";
+export const BUILTIN_TERMINAL_DRIVERS = [
+    wezterm,
+    tmux,
+    fallback,
+];

package/dist/internal/terminal/drivers/fallback.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Fallback driver. Available everywhere; "spawns" by
+ * printing the request to stderr so the user can dispatch
+ * it themselves. Used when no real driver is available
+ * (headless CI, unknown terminal, etc.).
+ */
+import type { TerminalDriver } from "../../../terminal/types.js";
+export declare const fallback: TerminalDriver;

package/dist/internal/terminal/drivers/fallback.js

@@ -0,0 +1,31 @@
+/**
+ * Fallback driver. Available everywhere; "spawns" by
+ * printing the request to stderr so the user can dispatch
+ * it themselves. Used when no real driver is available
+ * (headless CI, unknown terminal, etc.).
+ */
+function formatRequest(request) {
+    const parts = [];
+    parts.push(`# terminal-fallback: would have opened ${request.layout}`);
+    if (request.cwd)
+        parts.push(`# cwd: ${request.cwd}`);
+    if (request.title)
+        parts.push(`# title: ${request.title}`);
+    if (request.env) {
+        for (const [k, v] of Object.entries(request.env))
+            parts.push(`${k}=${v}`);
+    }
+    // No command means the caller wanted a bare login shell. Say so,
+    // rather than printing an empty line where a command would be.
+    parts.push(request.command ?? "# (a login shell, no command)");
+    return parts.join("\n");
+}
+export const fallback = {
+    id: "fallback",
+    available() {
+        return true;
+    },
+    async spawn(request) {
+        process.stderr.write(`${formatRequest(request)}\n`);
+    },
+};

package/dist/internal/terminal/drivers/shared.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared helpers for terminal drivers.
+ *
+ * Drivers that hand the command to a multiplexer daemon
+ * (wezterm cli, tmux) cannot pass environment variables
+ * through Node's child_process env: the daemon runs the
+ * pane in its own environment. Wrapping the command in a
+ * shell that sets the env vars and execs the original
+ * command is the portable way to ship per-spawn env.
+ *
+ * Drivers that spawn the process directly (the fallback's
+ * future direct-shell mode, for example) can use Node's
+ * env passthrough and skip the wrap.
+ */
+/**
+ * POSIX-shell-quote a single string. Wraps in single
+ * quotes and escapes any embedded single quotes.
+ */
+export declare function shellQuote(value: string): string;
+/**
+ * Wrap a command so the given env vars are visible to it.
+ * Returns the original command unchanged when no env vars
+ * are supplied.
+ *
+ * The wrap is `KEY=value... exec sh -c '<command>'` rather
+ * than `KEY=value... exec <command>`: the assignment
+ * prefix and `exec` only consume the next single token, so
+ * a compound `<command>` like `echo hi; sleep 30` would
+ * lose everything after the first token. Wrapping in
+ * `sh -c` makes the whole thing a single token from the
+ * outer shell's point of view and lets shell metacharacters
+ * inside `<command>` keep their normal meaning.
+ *
+ * `exec` keeps the process tree shallow: the outer shell
+ * is replaced by the inner sh, which then runs the user's
+ * command, so signals and pid resolution behave as if the
+ * command ran one level deeper than a plain `sh -c`.
+ */
+export declare function wrapCommandWithEnv(command: string, env: Readonly<Record<string, string>> | undefined): string;

package/dist/internal/terminal/drivers/shared.js

@@ -0,0 +1,51 @@
+/**
+ * Shared helpers for terminal drivers.
+ *
+ * Drivers that hand the command to a multiplexer daemon
+ * (wezterm cli, tmux) cannot pass environment variables
+ * through Node's child_process env: the daemon runs the
+ * pane in its own environment. Wrapping the command in a
+ * shell that sets the env vars and execs the original
+ * command is the portable way to ship per-spawn env.
+ *
+ * Drivers that spawn the process directly (the fallback's
+ * future direct-shell mode, for example) can use Node's
+ * env passthrough and skip the wrap.
+ */
+/**
+ * POSIX-shell-quote a single string. Wraps in single
+ * quotes and escapes any embedded single quotes.
+ */
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Wrap a command so the given env vars are visible to it.
+ * Returns the original command unchanged when no env vars
+ * are supplied.
+ *
+ * The wrap is `KEY=value... exec sh -c '<command>'` rather
+ * than `KEY=value... exec <command>`: the assignment
+ * prefix and `exec` only consume the next single token, so
+ * a compound `<command>` like `echo hi; sleep 30` would
+ * lose everything after the first token. Wrapping in
+ * `sh -c` makes the whole thing a single token from the
+ * outer shell's point of view and lets shell metacharacters
+ * inside `<command>` keep their normal meaning.
+ *
+ * `exec` keeps the process tree shallow: the outer shell
+ * is replaced by the inner sh, which then runs the user's
+ * command, so signals and pid resolution behave as if the
+ * command ran one level deeper than a plain `sh -c`.
+ */
+export function wrapCommandWithEnv(command, env) {
+    if (!env)
+        return command;
+    const entries = Object.entries(env);
+    if (entries.length === 0)
+        return command;
+    const assignments = entries
+        .map(([k, v]) => `${k}=${shellQuote(v)}`)
+        .join(" ");
+    return `${assignments} exec sh -c ${shellQuote(command)}`;
+}

package/dist/internal/terminal/drivers/tmux.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Tmux driver. Uses `tmux new-window` for tabs and windows
+ * (tmux has no separate window concept; a new tmux "window"
+ * is what we call a tab), and `tmux split-window` for panes.
+ *
+ * Available when both:
+ *
+ * - The `tmux` binary is on PATH.
+ * - The current process is inside a tmux session (`TMUX`
+ *   env var is set). Otherwise the new tab has nowhere to
+ *   attach.
+ */
+import type { TerminalDriver } from "../../../terminal/types.js";
+export declare const tmux: TerminalDriver;