@oharness/engine 0.1.0

package/dist/agent/permissions.js

@@ -0,0 +1,289 @@
+import { matchPattern } from "../tools/registry.js";
+import { shortId } from "../util/id.js";
+import { PermissionDeniedError } from "../core/errors.js";
+/** Every mode, in the order the picker shows them. */
+export const PERMISSION_MODES = [
+    "default",
+    "acceptEdits",
+    "plan",
+    "auto",
+    "bypassPermissions",
+];
+export const MODE_LABELS = {
+    default: "Manual",
+    acceptEdits: "Accept edits",
+    plan: "Plan",
+    auto: "Auto",
+    bypassPermissions: "Bypass permissions",
+};
+export const MODE_DESCRIPTIONS = {
+    default: "ask before anything that changes state",
+    acceptEdits: "file edits go through, everything else asks",
+    plan: "read-only; refuse every change",
+    auto: "edits and routine commands go through, risky ones ask",
+    bypassPermissions: "approve everything — only where a mistake is cheap",
+};
+/**
+ * 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 function asAuditEntry(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const line = value;
+    if (typeof line["id"] !== "string" || typeof line["at"] !== "number")
+        return undefined;
+    if (line["kind"] === "decision") {
+        return typeof line["tool"] === "string" && typeof line["behavior"] === "string"
+            ? line
+            : undefined;
+    }
+    if (line["kind"] === "answer") {
+        return typeof line["outcome"] === "string" ? line : undefined;
+    }
+    return undefined;
+}
+const EDIT_TOOLS = new Set(["write", "edit"]);
+/**
+ * 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 class PermissionEngine {
+    mode;
+    rules;
+    sessionAllow = new Set();
+    settings;
+    auditors = new Set();
+    constructor(mode = "default", rules = {}) {
+        this.mode = mode;
+        this.rules = {
+            allow: rules.allow ?? [],
+            deny: rules.deny ?? [],
+            ask: rules.ask ?? [],
+        };
+    }
+    getMode() {
+        return this.mode;
+    }
+    setMode(mode) {
+        this.mode = mode;
+    }
+    addRule(kind, pattern) {
+        this.rules[kind].push(pattern);
+    }
+    /**
+     * 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.
+     */
+    async rememberAllow(tool, input, scope = "session") {
+        const keys = candidates(tool, input);
+        for (const candidate of keys)
+            this.sessionAllow.add(candidate);
+        if (scope === "session" || !this.settings)
+            return undefined;
+        const pattern = keys[keys.length - 1] ?? tool.name;
+        await this.settings.addRule(scope, "allow", pattern);
+        this.rules.allow.push(pattern);
+        return pattern;
+    }
+    /** Where persisted rules are written; absent means session-only. */
+    attachSettings(settings) {
+        this.settings = settings;
+    }
+    listRules() {
+        return { ...this.rules, sessionAllow: [...this.sessionAllow] };
+    }
+    /**
+     * 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) {
+        this.auditors.add(auditor);
+        return () => void this.auditors.delete(auditor);
+    }
+    /**
+     * 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.
+     */
+    announce(entry) {
+        for (const auditor of this.auditors) {
+            try {
+                auditor(entry);
+            }
+            catch {
+                // See above.
+            }
+        }
+    }
+    evaluate(tool, input) {
+        const decision = this.decide(tool, input);
+        const id = `dec_${shortId(8)}`;
+        this.announce({
+            kind: "decision",
+            id,
+            at: Date.now(),
+            tool: tool.name,
+            behavior: decision.behavior,
+            rule: decision.rule,
+            principal: candidates(tool, input).at(-1),
+        });
+        return { ...decision, auditId: id };
+    }
+    /**
+     * 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, outcome, remembered) {
+        this.announce({ kind: "answer", id, at: Date.now(), outcome, remembered });
+    }
+    decide(tool, input) {
+        const keys = candidates(tool, input);
+        // Deny wins over everything, including bypass mode — an explicit deny rule
+        // is the one thing a user can rely on absolutely.
+        const denied = firstMatch(keys, this.rules.deny);
+        if (denied) {
+            return { behavior: "deny", rule: denied, message: `denied by rule ${denied}` };
+        }
+        if (this.mode === "plan" && !tool.readOnly) {
+            return {
+                behavior: "deny",
+                message: "Plan mode is active: no tool that modifies state may run. Present the plan instead.",
+            };
+        }
+        if (this.mode === "bypassPermissions")
+            return { behavior: "allow", rule: "bypass" };
+        // Read-only tools never need approval; that is the point of the flag.
+        if (tool.readOnly)
+            return { behavior: "allow", rule: "readOnly" };
+        // Neither do tools whose only effect is on this session's own scratch
+        // state. Deliberately below the plan-mode gate above: plan mode is about
+        // whether anything changes at all, and these do change something. This is
+        // about whether a human answering yes or no is protecting anything, and
+        // for a Map that dies with the process they are not — they are being
+        // charged a dialog for it. An explicit deny rule still wins, because it is
+        // matched before any of this.
+        if (tool.sessionLocal)
+            return { behavior: "allow", rule: "sessionLocal" };
+        const mustAsk = firstMatch(keys, this.rules.ask);
+        if (mustAsk)
+            return { behavior: "ask", rule: mustAsk };
+        const allowed = firstMatch(keys, this.rules.allow);
+        if (allowed)
+            return { behavior: "allow", rule: allowed };
+        if (keys.some((key) => this.sessionAllow.has(key))) {
+            return { behavior: "allow", rule: "session" };
+        }
+        if ((this.mode === "acceptEdits" || this.mode === "auto") &&
+            EDIT_TOOLS.has(tool.name)) {
+            return { behavior: "allow", rule: this.mode };
+        }
+        // Auto mode buys flow by approving routine commands. The classifier is
+        // deliberately conservative — anything it does not recognise as routine
+        // still asks — because the failure that matters is approving a command
+        // that destroys something, not asking about one more `ls`.
+        if (this.mode === "auto" && !isRisky(tool, input)) {
+            return { behavior: "allow", rule: "auto" };
+        }
+        return { behavior: "ask" };
+    }
+}
+/**
+ * The strings a rule may match: the bare tool name, and `Tool(arg)` using the
+ * argument that best identifies the call.
+ */
+export function candidates(tool, input) {
+    const keys = [tool.name];
+    const arg = principalArgument(tool.name, input);
+    if (arg !== undefined) {
+        keys.push(`${tool.name}(${arg})`);
+        // Capitalized form so `Bash(...)` reads naturally in a config file.
+        keys.push(`${capitalize(tool.name)}(${arg})`);
+    }
+    return keys;
+}
+function principalArgument(toolName, input) {
+    if (input === null || typeof input !== "object")
+        return undefined;
+    const record = input;
+    const field = toolName === "bash"
+        ? "command"
+        : "path" in record
+            ? "path"
+            : "pattern" in record
+                ? "pattern"
+                : "url" in record
+                    ? "url"
+                    : undefined;
+    if (!field)
+        return undefined;
+    const value = record[field];
+    return typeof value === "string" ? value : undefined;
+}
+function firstMatch(keys, patterns) {
+    for (const pattern of patterns) {
+        if (keys.some((key) => matchPattern(key, pattern)))
+            return pattern;
+    }
+    return undefined;
+}
+function capitalize(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}
+/**
+ * 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 function assertAllowed(decision, title) {
+    if (!decision.allowed) {
+        throw new PermissionDeniedError(decision.reason ?? `${title} was denied`);
+    }
+}
+/**
+ * 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 function isRisky(tool, input) {
+    if (tool.name !== "bash") {
+        // Any non-shell tool that mutates is already handled by the edit-tool set
+        // above; whatever is left reaches the network or the system.
+        return !tool.readOnly && !EDIT_TOOLS.has(tool.name);
+    }
+    const command = input?.command;
+    if (typeof command !== "string")
+        return true;
+    return RISKY_COMMAND.test(command);
+}
+/**
+ * Destroys data, changes the world outside this machine, or escalates.
+ *
+ * Kept explicit rather than clever: a maintainer should be able to read this
+ * and say whether they agree, which is not true of a heuristic that scores
+ * commands.
+ */
+const RISKY_COMMAND = /\b(rm|rmdir|dd|mkfs|shutdown|reboot|kill|pkill|killall|chown|chmod|sudo|su|ssh|scp|rsync)\b|\bgit\s+(push|reset|clean|checkout\s+--|rebase)\b|\bnpm\s+(publish|unpublish)\b|\b(docker|kubectl|terraform|aws|gcloud|az)\b|\bcurl\b.*\B-[a-zA-Z]*d|>\s*\/(?!tmp\/)/;
+//# sourceMappingURL=permissions.js.map

package/dist/agent/permissions.js.map

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

package/dist/agent/prompt.d.ts

@@ -0,0 +1,25 @@
+import type { ModelSpec } from "../providers/types.ts";
+import type { PermissionMode } from "./permissions.ts";
+export interface SystemPromptInput {
+    /** Replaces the built-in base prompt entirely. */
+    systemPrompt?: string;
+    /** Appended after the base prompt — the usual extension point. */
+    appendSystemPrompt?: string;
+    cwd: string;
+    model: ModelSpec;
+    permissionMode: PermissionMode;
+    /** Project instructions (an AGENTS.md / CLAUDE.md equivalent). */
+    projectInstructions?: string;
+    /** `instructions` strings advertised by connected MCP servers. */
+    mcpInstructions?: string[];
+    toolNames: string[];
+    extraSections?: string[];
+}
+/**
+ * Assemble the system prompt.
+ *
+ * Ordering is deliberate: stable content first, volatile content last, so
+ * providers with prefix-based prompt caching get a long reusable prefix.
+ */
+export declare function buildSystemPrompt(input: SystemPromptInput): string;
+export declare const COMPACTION_PROMPT = "Summarize the conversation so far so that another agent can continue the work without seeing the original transcript.\n\nWrite it under these headings, omitting any that do not apply:\n1. **Goal** \u2014 what the user asked for, in their own terms.\n2. **Decisions** \u2014 choices made and the reasoning, including approaches ruled out.\n3. **Work done** \u2014 files created or modified with paths, commands run and their outcomes.\n4. **Current state** \u2014 what is working, what is broken, what was verified versus assumed.\n5. **Next steps** \u2014 what remains, specifically enough to act on.\n6. **Key details** \u2014 exact identifiers, paths, versions, error strings, and user preferences stated during the session.\n\nBe specific and concrete. Preserve exact names and paths verbatim \u2014 a summary that loses them is useless. Do not add commentary about the summarization itself.";

package/dist/agent/prompt.js

@@ -0,0 +1,63 @@
+import { platform } from "node:os";
+const BASE_PROMPT = `You are an agent operating through a tool-calling harness. You act on the user's behalf by calling tools, observing the results, and continuing until the task is done.
+
+## Working style
+- When you have enough information to act, act. Don't re-derive facts already established, and don't narrate options you won't pursue.
+- Prefer the dedicated tools over shell equivalents: they are safer, produce better output, and let the harness show the user what is happening.
+- Independent tool calls should be issued together in one turn so they run in parallel. Calls that depend on each other must be sequential.
+- Read a file before editing it. Edits are rejected if the file changed since your last read.
+- Report outcomes faithfully. If a command failed, say so and include the output; if you skipped a step, say that.
+
+## Scope
+Deliver what was asked, at the scope intended. Make routine judgment calls yourself; check in only when different readings would lead to materially different work. Don't add abstractions, error handling for impossible states, or refactors that weren't requested. Finish the whole task — report completion only when it is actually complete.
+
+## Communicating
+Lead with the outcome. Keep responses focused: the user is reading a terminal, not a report. Use complete sentences and spell out identifiers rather than compressing into shorthand.`;
+const PLAN_MODE_NOTE = `## Plan mode is active
+Tools that modify state are blocked. Investigate using read-only tools, then present a concrete plan and wait for approval. Do not attempt to make changes.`;
+/**
+ * Assemble the system prompt.
+ *
+ * Ordering is deliberate: stable content first, volatile content last, so
+ * providers with prefix-based prompt caching get a long reusable prefix.
+ */
+export function buildSystemPrompt(input) {
+    const sections = [];
+    sections.push(input.systemPrompt ?? BASE_PROMPT);
+    if (input.appendSystemPrompt)
+        sections.push(input.appendSystemPrompt);
+    if (input.permissionMode === "plan")
+        sections.push(PLAN_MODE_NOTE);
+    if (input.projectInstructions?.trim()) {
+        sections.push(`# Project instructions\n${input.projectInstructions.trim()}`);
+    }
+    if (input.mcpInstructions?.length) {
+        sections.push(`# MCP server instructions\n${input.mcpInstructions.join("\n\n")}`);
+    }
+    for (const extra of input.extraSections ?? []) {
+        if (extra.trim())
+            sections.push(extra.trim());
+    }
+    // Environment last: it is the part most likely to change between sessions.
+    sections.push([
+        "# Environment",
+        `Working directory: ${input.cwd}`,
+        `Platform: ${platform()}`,
+        `Model: ${input.model.displayName ?? input.model.model} (${input.model.provider})`,
+        `Permission mode: ${input.permissionMode}`,
+        `Available tools: ${input.toolNames.join(", ") || "(none)"}`,
+    ].join("\n"));
+    return sections.join("\n\n");
+}
+export const COMPACTION_PROMPT = `Summarize the conversation so far so that another agent can continue the work without seeing the original transcript.
+
+Write it under these headings, omitting any that do not apply:
+1. **Goal** — what the user asked for, in their own terms.
+2. **Decisions** — choices made and the reasoning, including approaches ruled out.
+3. **Work done** — files created or modified with paths, commands run and their outcomes.
+4. **Current state** — what is working, what is broken, what was verified versus assumed.
+5. **Next steps** — what remains, specifically enough to act on.
+6. **Key details** — exact identifiers, paths, versions, error strings, and user preferences stated during the session.
+
+Be specific and concrete. Preserve exact names and paths verbatim — a summary that loses them is useless. Do not add commentary about the summarization itself.`;
+//# sourceMappingURL=prompt.js.map

package/dist/agent/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/agent/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAoBnC,MAAM,WAAW,GAAG;;;;;;;;;;;;;sLAakK,CAAC;AAEvL,MAAM,cAAc,GAAG;4JACqI,CAAC;AAE7J;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAwB;IACxD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,IAAI,WAAW,CAAC,CAAC;IACjD,IAAI,KAAK,CAAC,kBAAkB;QAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACtE,IAAI,KAAK,CAAC,cAAc,KAAK,MAAM;QAAE,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAEnE,IAAI,KAAK,CAAC,mBAAmB,EAAE,IAAI,EAAE,EAAE,CAAC;QACtC,QAAQ,CAAC,IAAI,CAAC,2BAA2B,KAAK,CAAC,mBAAmB,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,IAAI,KAAK,CAAC,eAAe,EAAE,MAAM,EAAE,CAAC;QAClC,QAAQ,CAAC,IAAI,CAAC,8BAA8B,KAAK,CAAC,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACpF,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,aAAa,IAAI,EAAE,EAAE,CAAC;QAC9C,IAAI,KAAK,CAAC,IAAI,EAAE;YAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CACX;QACE,eAAe;QACf,sBAAsB,KAAK,CAAC,GAAG,EAAE;QACjC,aAAa,QAAQ,EAAE,EAAE;QACzB,UAAU,KAAK,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,CAAC,QAAQ,GAAG;QAClF,oBAAoB,KAAK,CAAC,cAAc,EAAE;QAC1C,oBAAoB,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,EAAE;KAC7D,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;IAEF,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;gKAU+H,CAAC"}

package/dist/agent/session.d.ts

@@ -0,0 +1,108 @@
+import type { StoredArtifactRevision } from "../artifacts/store.ts";
+import type { Message, Usage } from "../core/types.ts";
+import type { ModelSpec } from "../providers/types.ts";
+import type { ProviderRegistry } from "../providers/registry.ts";
+import { PermissionEngine } from "./permissions.ts";
+import type { PermissionMode, PermissionRules } from "./permissions.ts";
+import { SessionStore } from "./store.ts";
+import type { ArchivedMessage, SessionMeta } from "./store.ts";
+export interface SessionOptions {
+    id?: string;
+    cwd?: string;
+    model: string;
+    providers: ProviderRegistry;
+    permissionMode?: PermissionMode;
+    permissionRules?: PermissionRules;
+    store?: SessionStore | false;
+    /**
+     * Artifact revisions read from disk, preferred over replaying the transcript.
+     *
+     * Passed in rather than read here because the constructor is synchronous and
+     * this comes off a file; `Session.resume` does the reading.
+     */
+    artifactRevisions?: StoredArtifactRevision[];
+    messages?: Message[];
+    title?: string;
+}
+/**
+ * Conversation state for one agent run: history, current model, permissions,
+ * accounting, and the scratch state tools share.
+ *
+ * History is stored provider-neutrally, which is what makes `setModel` a
+ * one-line operation instead of a migration.
+ */
+export declare class Session {
+    /** How many messages compaction has already archived, for stable seq numbers. */
+    private archivedCount;
+    readonly id: string;
+    readonly cwd: string;
+    readonly providers: ProviderRegistry;
+    readonly permissions: PermissionEngine;
+    /** Shared scratch space handed to tools via `ToolHost`. */
+    readonly state: Map<string, unknown>;
+    messages: Message[];
+    title?: string;
+    usage: Usage;
+    costUsd: number;
+    /** Session this one was branched from, surfaced in meta and `/sessions`. */
+    forkedFrom?: string;
+    turns: number;
+    /**
+     * Messages discarded as an incomplete tail when this session was loaded.
+     *
+     * Repairing the transcript silently would leave the user wondering where the
+     * last turn went, so the count is kept for the frontend to report.
+     */
+    readonly droppedOnLoad: number;
+    private spec;
+    private readonly store?;
+    private readonly createdAt;
+    constructor(opts: SessionOptions);
+    /** Restore a persisted session, keeping its id and transcript. */
+    static resume(id: string, opts: Omit<SessionOptions, "id" | "messages"> & {
+        store?: SessionStore;
+    }): Promise<Session | undefined>;
+    /**
+     * Branch a stored session into a new one.
+     *
+     * `keepMessages` rewinds the branch to an earlier point; omit it to branch
+     * from where the parent stands. The parent is left untouched either way.
+     */
+    static fork(sourceId: string, opts: Omit<SessionOptions, "id" | "messages"> & {
+        store?: SessionStore;
+        keepMessages?: number;
+        title?: string;
+    }): Promise<Session | undefined>;
+    get model(): ModelSpec;
+    /**
+     * Switch models mid-session. Because history is provider-neutral, the next
+     * request simply renders it for the new provider — no conversion needed.
+     */
+    setModel(ref: string): {
+        from: ModelSpec;
+        to: ModelSpec;
+    };
+    addMessage(message: Message): Promise<void>;
+    /** Replace the transcript (after compaction) and rewrite the persisted copy. */
+    /**
+     * Replace the live transcript, archiving whatever is being dropped.
+     *
+     * `archivedCount` keeps sequence numbers meaningful across repeated
+     * compactions: without it the second compaction would restart at 0 and
+     * overwrite the first one's numbering in the archive.
+     */
+    compactTo(messages: Message[], dropped: Message[]): Promise<void>;
+    /**
+     * Archive a message that never entered the transcript — the full text of a
+     * tool result that was too large to keep in context.
+     */
+    archiveOverflow(message: Message): Promise<void>;
+    /** Everything compaction has archived, oldest first. */
+    archive(): Promise<ArchivedMessage[]>;
+    replaceMessages(messages: Message[]): Promise<void>;
+    recordUsage(usage: Usage | undefined): void;
+    meta(): SessionMeta;
+    persist(): Promise<void>;
+    /** Create the on-disk session directory. Safe to call more than once. */
+    init(): Promise<void>;
+}