@oharness/engine 0.1.0

package/dist/agent/memory.js

@@ -0,0 +1,147 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { shortId } from "../util/id.js";
+import { splitFrontmatter } from "./skills.js";
+/** How much of the memory index may enter the system prompt. */
+const MAX_PROMPT_CHARS = 4_000;
+export class MemoryStore {
+    dir;
+    cache;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    get location() {
+        return this.dir;
+    }
+    async load() {
+        if (this.cache)
+            return this.cache;
+        let files;
+        try {
+            files = (await readdir(this.dir)).filter((name) => name.endsWith(".md"));
+        }
+        catch {
+            this.cache = [];
+            return this.cache;
+        }
+        const entries = [];
+        for (const name of files) {
+            const file = path.join(this.dir, name);
+            let raw;
+            try {
+                raw = await readFile(file, "utf8");
+            }
+            catch {
+                continue;
+            }
+            const { frontmatter, body } = splitFrontmatter(raw);
+            const summary = frontmatter["summary"]?.trim();
+            // Without a summary the entry cannot appear in the index, and an entry
+            // the model never sees is one it will never ask for.
+            if (!summary)
+                continue;
+            entries.push({
+                id: frontmatter["id"]?.trim() || name.replace(/\.md$/, ""),
+                summary,
+                body: body.trim(),
+                tags: (frontmatter["tags"] ?? "")
+                    .split(/[,\s]+/)
+                    .map((tag) => tag.trim())
+                    .filter((tag) => tag !== ""),
+                createdAt: Number(frontmatter["createdAt"]) || 0,
+                file,
+            });
+        }
+        entries.sort((a, b) => b.createdAt - a.createdAt);
+        this.cache = entries;
+        return entries;
+    }
+    async remember(input) {
+        await mkdir(this.dir, { recursive: true });
+        const existing = await this.load();
+        // Re-learning the same lesson should update the note, not add a duplicate
+        // that competes with it in the index.
+        const match = existing.find((entry) => entry.summary.toLowerCase() === input.summary.trim().toLowerCase());
+        const id = match?.id ?? `${slug(input.summary)}-${shortId(3)}`;
+        const createdAt = match?.createdAt || Date.now();
+        const file = match?.file ?? path.join(this.dir, `${id}.md`);
+        const frontmatter = [
+            "---",
+            `id: ${id}`,
+            `summary: ${input.summary.trim().replace(/\n/g, " ")}`,
+            `tags: ${(input.tags ?? []).join(", ")}`,
+            `createdAt: ${createdAt}`,
+            `updatedAt: ${Date.now()}`,
+            "---",
+            "",
+        ].join("\n");
+        await writeFile(file, `${frontmatter}${input.body.trim()}\n`, "utf8");
+        this.cache = undefined;
+        return {
+            id,
+            summary: input.summary.trim(),
+            body: input.body.trim(),
+            tags: input.tags ?? [],
+            createdAt,
+            file,
+        };
+    }
+    async forget(id) {
+        const entries = await this.load();
+        const match = entries.find((entry) => entry.id === id);
+        if (!match)
+            return false;
+        const { rm } = await import("node:fs/promises");
+        await rm(match.file, { force: true });
+        this.cache = undefined;
+        return true;
+    }
+    /** Full-text search across summaries, bodies and tags. */
+    async search(query) {
+        const needle = query.toLowerCase();
+        return (await this.load()).filter((entry) => entry.summary.toLowerCase().includes(needle) ||
+            entry.body.toLowerCase().includes(needle) ||
+            entry.tags.some((tag) => tag.toLowerCase().includes(needle)));
+    }
+    /**
+     * The index that goes into the system prompt: summaries only.
+     *
+     * Same reasoning as skills — putting every note's body in the prompt would
+     * grow without bound and crowd out the actual conversation. The model reads
+     * a summary, then asks for the body if it matters.
+     */
+    async promptSection() {
+        const entries = await this.load();
+        if (entries.length === 0)
+            return undefined;
+        const lines = [
+            "## Memory",
+            "",
+            "Lessons recorded in earlier sessions. Read the full note with the `memory` tool",
+            "before acting on one — these are summaries, not the whole story.",
+            "",
+        ];
+        let budget = MAX_PROMPT_CHARS;
+        let omitted = 0;
+        for (const entry of entries) {
+            const line = `- \`${entry.id}\` — ${entry.summary}`;
+            if (line.length > budget) {
+                omitted++;
+                continue;
+            }
+            lines.push(line);
+            budget -= line.length;
+        }
+        if (omitted > 0)
+            lines.push(`- … ${omitted} older notes; search them with the \`memory\` tool.`);
+        return lines.join("\n");
+    }
+}
+function slug(value) {
+    return (value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 40) || "note");
+}
+//# sourceMappingURL=memory.js.map

package/dist/agent/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/agent/memory.ts"],"names":[],"mappings":"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"}

package/dist/agent/overflow.d.ts

@@ -0,0 +1,35 @@
+import type { Message } from "../core/types.ts";
+import type { ToolResult } from "../tools/types.ts";
+/**
+ * Cap on a single tool result, in characters.
+ *
+ * The built-in tools cap their own output, but MCP and user-supplied tools do
+ * not — and a tool result enters the transcript *after* the compaction check
+ * has already run for this turn, so compaction cannot save a window that one
+ * oversized result just filled.
+ */
+export declare const DEFAULT_TOOL_RESULT_LIMIT = 30000;
+export interface OverflowResult {
+    /** What goes into the transcript. */
+    result: ToolResult;
+    /**
+     * A synthetic message holding the full output, to be archived. `recall`
+     * searches archived messages, so the overflow is retrievable by keyword
+     * with no extra machinery.
+     */
+    archived?: Message;
+    originalChars: number;
+}
+/**
+ * Trim a tool result that would otherwise dominate the context window.
+ *
+ * The full text is not discarded — it is handed back for archiving, and the
+ * truncation notice tells the model how to get it. Silently dropping the tail
+ * is worse than truncating loudly: the model cannot tell that it is reasoning
+ * from partial output.
+ */
+export declare function capToolResult(result: ToolResult, opts: {
+    toolName: string;
+    toolCallId: string;
+    limit?: number;
+}): OverflowResult;

package/dist/agent/overflow.js

@@ -0,0 +1,69 @@
+import { estimateStringTokens } from "../core/tokens.js";
+/**
+ * Cap on a single tool result, in characters.
+ *
+ * The built-in tools cap their own output, but MCP and user-supplied tools do
+ * not — and a tool result enters the transcript *after* the compaction check
+ * has already run for this turn, so compaction cannot save a window that one
+ * oversized result just filled.
+ */
+export const DEFAULT_TOOL_RESULT_LIMIT = 30_000;
+/** Keep the head and the tail: errors surface at both ends of long output. */
+const HEAD_FRACTION = 0.7;
+/**
+ * Trim a tool result that would otherwise dominate the context window.
+ *
+ * The full text is not discarded — it is handed back for archiving, and the
+ * truncation notice tells the model how to get it. Silently dropping the tail
+ * is worse than truncating loudly: the model cannot tell that it is reasoning
+ * from partial output.
+ */
+export function capToolResult(result, opts) {
+    const limit = opts.limit ?? DEFAULT_TOOL_RESULT_LIMIT;
+    const textBlocks = result.content.filter((block) => block.type === "text");
+    const total = textBlocks.reduce((sum, block) => sum + block.text.length, 0);
+    if (total <= limit)
+        return { result, originalChars: total };
+    const full = textBlocks.map((block) => block.text).join("\n");
+    const headChars = Math.floor(limit * HEAD_FRACTION);
+    const tailChars = limit - headChars;
+    const head = full.slice(0, headChars);
+    const tail = full.slice(full.length - tailChars);
+    const omitted = full.length - headChars - tailChars;
+    const notice = `\n\n… ${omitted.toLocaleString()} characters omitted ` +
+        `(${estimateStringTokens(String(omitted))} · full output was ${full.length.toLocaleString()} chars). ` +
+        `The complete output is archived — search it with the \`recall\` tool ` +
+        `(try \`recall\` with a keyword, or the tool name "${opts.toolName}").\n\n`;
+    // Non-text blocks (images) pass through: they are already bounded, and
+    // dropping them would silently change what the model sees.
+    const passthrough = result.content.filter((block) => block.type !== "text");
+    return {
+        result: {
+            ...result,
+            content: [{ type: "text", text: head + notice + tail }, ...passthrough],
+            metadata: {
+                ...result.metadata,
+                truncated: true,
+                originalChars: full.length,
+            },
+        },
+        archived: {
+            role: "user",
+            content: [
+                {
+                    type: "text",
+                    text: `<tool-output tool="${opts.toolName}" call="${opts.toolCallId}" chars="${full.length}">\n` +
+                        `${full}\n</tool-output>`,
+                },
+            ],
+            meta: {
+                timestamp: Date.now(),
+                synthetic: true,
+                overflowOf: opts.toolCallId,
+                toolName: opts.toolName,
+            },
+        },
+        originalChars: full.length,
+    };
+}
+//# sourceMappingURL=overflow.js.map

package/dist/agent/overflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overflow.js","sourceRoot":"","sources":["../../src/agent/overflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAIzD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAEhD,8EAA8E;AAC9E,MAAM,aAAa,GAAG,GAAG,CAAC;AAc1B;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAkB,EAClB,IAIC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,yBAAyB,CAAC;IAEtD,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CACtC,CAAC,KAAK,EAA2C,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAC1E,CAAC;IACF,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC5E,IAAI,KAAK,IAAI,KAAK;QAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;IAE5D,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,aAAa,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,KAAK,GAAG,SAAS,CAAC;IAEpC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IAEpD,MAAM,MAAM,GACV,SAAS,OAAO,CAAC,cAAc,EAAE,sBAAsB;QACvD,IAAI,oBAAoB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,sBAAsB,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,WAAW;QACtG,uEAAuE;QACvE,qDAAqD,IAAI,CAAC,QAAQ,SAAS,CAAC;IAE9E,uEAAuE;IACvE,2DAA2D;IAC3D,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;IAE5E,OAAO;QACL,MAAM,EAAE;YACN,GAAG,MAAM;YACT,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,EAAE,EAAE,GAAG,WAAW,CAAC;YACvE,QAAQ,EAAE;gBACR,GAAG,MAAM,CAAC,QAAQ;gBAClB,SAAS,EAAE,IAAI;gBACf,aAAa,EAAE,IAAI,CAAC,MAAM;aAC3B;SACF;QACD,QAAQ,EAAE;YACR,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EACF,sBAAsB,IAAI,CAAC,QAAQ,WAAW,IAAI,CAAC,UAAU,YAAY,IAAI,CAAC,MAAM,MAAM;wBAC1F,GAAG,IAAI,kBAAkB;iBAC5B;aACF;YACD,IAAI,EAAE;gBACJ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;gBACrB,SAAS,EAAE,IAAI;gBACf,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,QAAQ,EAAE,IAAI,CAAC,QAAQ;aACxB;SACF;QACD,aAAa,EAAE,IAAI,CAAC,MAAM;KAC3B,CAAC;AACJ,CAAC"}

package/dist/agent/permissions.d.ts

@@ -0,0 +1,181 @@
+import type { Tool } from "../tools/types.ts";
+import type { SettingsScope, SettingsStore } from "./settings.ts";
+/**
+ * `default`            — ask before anything that mutates state.
+ * `acceptEdits`        — auto-approve file edits, still ask for the rest.
+ * `plan`               — read-only; deny every mutating tool outright.
+ * `auto`               — approve edits and routine commands, ask for the rest.
+ * `bypassPermissions`  — approve everything (use only in sandboxes).
+ */
+export type PermissionMode = "default" | "acceptEdits" | "plan" | "auto" | "bypassPermissions";
+/** Every mode, in the order the picker shows them. */
+export declare const PERMISSION_MODES: PermissionMode[];
+export declare const MODE_LABELS: Record<PermissionMode, string>;
+export declare const MODE_DESCRIPTIONS: Record<PermissionMode, string>;
+export type PermissionBehavior = "allow" | "deny" | "ask";
+export interface PermissionRequest {
+    toolName: string;
+    input: unknown;
+    /** Human-readable rendering, e.g. `Bash(npm test)`. */
+    title: string;
+    /** Why the harness is asking, when it is not obvious. */
+    reason?: string;
+    suggestions?: string[];
+}
+export interface PermissionDecision {
+    behavior: PermissionBehavior;
+    /** Shown to the user on ask, and returned to the model on deny. */
+    message?: string;
+    /** Which rule decided this, for `/permissions` and debugging. */
+    rule?: string;
+    /**
+     * The trail entry this evaluation wrote, so the answer to an `ask` can be
+     * recorded against it. Present on every decision even though only `ask` is
+     * followed by an answer — a caller that has to check whether it got an id
+     * would eventually forget to.
+     */
+    auditId: string;
+}
+/** Prompts the user. Returning `false` denies the call. */
+export type PermissionPrompt = (request: PermissionRequest) => Promise<boolean | PermissionAnswer>;
+export interface PermissionAnswer {
+    allow: boolean;
+    /**
+     * Persist the decision. `"session"` keeps it in memory; the other scopes
+     * write it to settings so the same command is not re-approved tomorrow.
+     */
+    remember?: boolean | "session" | SettingsScope;
+}
+/**
+ * One line of the trail.
+ *
+ * Two kinds rather than one flat record, because a decision to *ask* is not an
+ * outcome: the old single-line trail said "asked" and then never said what the
+ * person answered, which is the one thing anybody reading an audit afterwards
+ * wants to know. `id` pairs them.
+ */
+export type AuditEntry = DecisionAudit | AnswerAudit;
+/** What the rules decided, before anyone was asked. */
+export interface DecisionAudit {
+    kind: "decision";
+    /** Pairs this with the answer that follows, when it asked for one. */
+    id: string;
+    at: number;
+    tool: string;
+    behavior: PermissionBehavior;
+    rule?: string;
+    /** The most specific candidate, e.g. `Bash(npm test)`. */
+    principal?: string;
+}
+/** What came back from asking. Exactly one per `ask` decision. */
+export interface AnswerAudit {
+    kind: "answer";
+    id: string;
+    at: number;
+    /**
+     * `unavailable` is the fail-closed case: nothing was able to ask, so the
+     * call was refused without a person ever seeing it. It reads very
+     * differently from a refusal somebody made, so it is not folded into `denied`.
+     */
+    outcome: "allowed" | "denied" | "unavailable";
+    /** The rule that was persisted, when the answer was remembered. */
+    remembered?: string;
+}
+/**
+ * A line off disk, or nothing.
+ *
+ * The trail is append-only and shared with future versions of this build, so a
+ * reader that cannot understand a line skips it rather than refusing the file.
+ */
+export declare function asAuditEntry(value: unknown): AuditEntry | undefined;
+export interface PermissionRules {
+    /** Auto-approved, e.g. `Bash(npm run test:*)`, `read`, `mcp__github__*`. */
+    allow?: string[];
+    /** Always denied; takes precedence over `allow`. */
+    deny?: string[];
+    /** Always prompts, even in `acceptEdits`. */
+    ask?: string[];
+}
+/**
+ * Decides whether a tool call may proceed.
+ *
+ * Rules are matched against `tool` and `Tool(argument)` forms so a policy can
+ * be as coarse as "all MCP GitHub tools" or as narrow as one bash command
+ * prefix.
+ */
+export declare class PermissionEngine {
+    private mode;
+    private readonly rules;
+    private readonly sessionAllow;
+    private settings?;
+    private readonly auditors;
+    constructor(mode?: PermissionMode, rules?: PermissionRules);
+    getMode(): PermissionMode;
+    setMode(mode: PermissionMode): void;
+    addRule(kind: keyof PermissionRules, pattern: string): void;
+    /**
+     * Remember an approval.
+     *
+     * The most specific candidate is what gets persisted — approving
+     * `Bash(npm test)` should not quietly grant every `Bash(...)`. Session-scoped
+     * approvals record every candidate because they expire with the process
+     * anyway.
+     */
+    rememberAllow(tool: Tool, input: unknown, scope?: "session" | SettingsScope): Promise<string | undefined>;
+    /** Where persisted rules are written; absent means session-only. */
+    attachSettings(settings: SettingsStore): void;
+    listRules(): Required<PermissionRules> & {
+        sessionAllow: string[];
+    };
+    /**
+     * Watch every decision. Returns the unsubscribe.
+     *
+     * A set rather than one slot, and a disposer rather than nothing, because
+     * there is more than one recorder now — the session's own trail and, when
+     * one is configured, a file — and because a recorder that can be attached
+     * but never detached is not something a switch can turn off.
+     */
+    onDecision(auditor: (entry: AuditEntry) => void): () => void;
+    /**
+     * Tell the recorders, without letting one of them break a tool call.
+     *
+     * A throwing recorder is dropped on the floor: the trail exists to describe
+     * what the harness did, and a description that can veto the thing it
+     * describes is a new failure mode in the permission path.
+     */
+    private announce;
+    evaluate(tool: Tool, input: unknown): PermissionDecision;
+    /**
+     * Close the pair an `ask` opened.
+     *
+     * Called by whoever did the asking, because only they know how it ended —
+     * the engine that decided to ask has already returned by then. An ask with
+     * no answer in the trail means the process died while the question was on
+     * screen, which is a true thing to be able to read.
+     */
+    recordAnswer(id: string, outcome: AnswerAudit["outcome"], remembered?: string): void;
+    private decide;
+}
+/**
+ * The strings a rule may match: the bare tool name, and `Tool(arg)` using the
+ * argument that best identifies the call.
+ */
+export declare function candidates(tool: Tool, input: unknown): string[];
+/**
+ * Throw for a denial that must abort the caller rather than be handed back to
+ * the model as a tool error. The agent loop reports denials in-band; this is
+ * for embedders driving tools directly.
+ */
+export declare function assertAllowed(decision: {
+    allowed: boolean;
+    reason?: string;
+}, title: string): void;
+/**
+ * Whether a call is risky enough that `auto` mode should still ask.
+ *
+ * This is a judgement about blast radius, not a security check. A rule in
+ * `deny` is the boundary you can rely on; this only decides which prompts
+ * `auto` mode is willing to skip. It answers "would a mistake here be
+ * expensive to undo?" and errs towards yes.
+ */
+export declare function isRisky(tool: Tool, input: unknown): boolean;