@oharness/engine 0.1.0

package/dist/agent/session.js

@@ -0,0 +1,231 @@
+import { dropDanglingTail } from "./compaction.js";
+import { titleFromMessage } from "./titles.js";
+import { addUsage, emptyUsage, messageText } from "../core/types.js";
+import { getArtifactStore, rehydrateArtifacts, restoreArtifacts } from "../artifacts/store.js";
+import { estimateCost } from "../providers/types.js";
+import { sessionId as newSessionId } from "../util/id.js";
+import { PermissionEngine } from "./permissions.js";
+import { SessionStore } from "./store.js";
+/**
+ * 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 class Session {
+    /** How many messages compaction has already archived, for stable seq numbers. */
+    archivedCount = 0;
+    id;
+    cwd;
+    providers;
+    permissions;
+    /** Shared scratch space handed to tools via `ToolHost`. */
+    state = new Map();
+    messages;
+    title;
+    usage = emptyUsage();
+    costUsd = 0;
+    /** Session this one was branched from, surfaced in meta and `/sessions`. */
+    forkedFrom;
+    turns = 0;
+    /**
+     * 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.
+     */
+    droppedOnLoad;
+    spec;
+    store;
+    createdAt;
+    constructor(opts) {
+        this.id = opts.id ?? newSessionId();
+        this.cwd = opts.cwd ?? process.cwd();
+        this.providers = opts.providers;
+        this.spec = opts.providers.resolve(opts.model);
+        // Every path that hydrates history runs through here — resume, fork, and
+        // whatever an embedder hands in — so this is the one place the invariant
+        // "history never ends on an unanswered tool call" can be made total.
+        const history = opts.messages ?? [];
+        this.messages = dropDanglingTail(history);
+        this.droppedOnLoad = history.length - this.messages.length;
+        // Artifacts come back from whichever source knows the most, and only one
+        // of them: the log carries the version numbers and the authorship that
+        // actually happened, while replaying the transcript can only count writes
+        // and cannot see a revision a person made by hand. Running both would
+        // renumber the history and duplicate every revision.
+        //
+        // The replay stays as the fallback because every session recorded before
+        // artifacts were written down has no log, and those still deserve to come
+        // back with the things their messages made.
+        let seedArtifactLog = false;
+        if (opts.artifactRevisions && opts.artifactRevisions.length > 0) {
+            restoreArtifacts(getArtifactStore(this.state), opts.artifactRevisions);
+        }
+        else if (this.messages.length > 0) {
+            // Nothing written down, so this session predates the log. Whatever the
+            // replay finds is seeded into it below, or the first revision written
+            // from here would become the whole of a history that starts at v1.
+            seedArtifactLog = rehydrateArtifacts(getArtifactStore(this.state), this.messages) > 0;
+        }
+        this.title = opts.title;
+        this.permissions = new PermissionEngine(opts.permissionMode ?? "default", opts.permissionRules ?? {});
+        this.store = opts.store === false ? undefined : (opts.store ?? new SessionStore());
+        this.createdAt = Date.now();
+        // Every revision, from either writer, goes to disk. Fire-and-forget on
+        // purpose: an artifact is a scratch surface, and making the model's turn
+        // wait on a file write — or fail with it — would be paying for durability
+        // in the wrong currency. A revision that does not land is one the session
+        // still holds and can be written again by the next one.
+        if (this.store) {
+            const store = this.store;
+            const id = this.id;
+            const artifacts = getArtifactStore(this.state);
+            artifacts.onRevision = (revision) => {
+                void store.appendArtifactRevision(id, revision).catch(() => { });
+            };
+            // One-time migration for a session whose artifacts came from the
+            // transcript. Ordinary appends, so a crash mid-way leaves a shorter log
+            // rather than a corrupt one, and the next resume replays and seeds again.
+            if (seedArtifactLog) {
+                for (const revision of artifacts.export()) {
+                    void store.appendArtifactRevision(id, revision).catch(() => { });
+                }
+            }
+        }
+    }
+    /** Restore a persisted session, keeping its id and transcript. */
+    static async resume(id, opts) {
+        const store = opts.store ?? new SessionStore();
+        const record = await store.load(id);
+        if (!record)
+            return undefined;
+        const artifactRevisions = await store.artifactRevisions(id);
+        const session = new Session({
+            ...opts,
+            artifactRevisions,
+            id: record.meta.id,
+            cwd: record.meta.cwd,
+            // Prefer the model the session was using, unless the caller overrode it.
+            model: opts.model || record.meta.model,
+            messages: record.messages,
+            title: record.meta.title,
+            store,
+        });
+        session.usage = record.meta.usage;
+        session.costUsd = record.meta.costUsd;
+        session.turns = record.meta.turns;
+        session.forkedFrom = record.meta.forkedFrom;
+        return session;
+    }
+    /**
+     * 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 async fork(sourceId, opts) {
+        const store = opts.store ?? new SessionStore();
+        const forked = await store.fork(sourceId, {
+            ...(opts.keepMessages !== undefined ? { keepMessages: opts.keepMessages } : {}),
+            ...(opts.title !== undefined ? { title: opts.title } : {}),
+        });
+        if (!forked)
+            return undefined;
+        const session = new Session({
+            ...opts,
+            id: forked.id,
+            cwd: forked.meta.cwd,
+            model: opts.model || forked.meta.model,
+            messages: forked.messages,
+            title: forked.meta.title,
+            store,
+        });
+        session.forkedFrom = sourceId;
+        // The branch starts its own accounting; the parent keeps its own.
+        return session;
+    }
+    get model() {
+        return this.spec;
+    }
+    /**
+     * Switch models mid-session. Because history is provider-neutral, the next
+     * request simply renders it for the new provider — no conversion needed.
+     */
+    setModel(ref) {
+        const from = this.spec;
+        this.spec = this.providers.resolve(ref);
+        return { from, to: this.spec };
+    }
+    async addMessage(message) {
+        this.messages.push(message);
+        // The first thing asked names the session. Without this every list — the
+        // CLI's /sessions, the web sidebar — shows a column of timestamps and
+        // hex, which tells the user nothing about which one they want.
+        if (!this.title && message.role === "user")
+            this.title = titleFromMessage(message);
+        await this.store?.appendMessage(this.id, message);
+    }
+    /** 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.
+     */
+    async compactTo(messages, dropped) {
+        if (dropped.length > 0) {
+            await this.store?.archiveMessages(this.id, dropped.map((message, i) => ({ seq: this.archivedCount + i, message })));
+            this.archivedCount += dropped.length;
+        }
+        await this.replaceMessages(messages);
+    }
+    /**
+     * Archive a message that never entered the transcript — the full text of a
+     * tool result that was too large to keep in context.
+     */
+    async archiveOverflow(message) {
+        await this.store?.archiveMessages(this.id, [{ seq: this.archivedCount, message }]);
+        this.archivedCount += 1;
+    }
+    /** Everything compaction has archived, oldest first. */
+    async archive() {
+        return (await this.store?.readArchive(this.id)) ?? [];
+    }
+    async replaceMessages(messages) {
+        this.messages = messages;
+        await this.store?.replaceMessages(this.id, messages);
+    }
+    recordUsage(usage) {
+        if (!usage)
+            return;
+        this.usage = addUsage(this.usage, usage);
+        this.costUsd += estimateCost(this.spec, usage);
+    }
+    meta() {
+        return {
+            id: this.id,
+            createdAt: this.createdAt,
+            updatedAt: Date.now(),
+            cwd: this.cwd,
+            model: this.spec.id,
+            title: this.title,
+            turns: this.turns,
+            usage: this.usage,
+            costUsd: this.costUsd,
+            // Lineage has to survive a persist/reload round trip, or a forked
+            // session forgets its parent the moment it is resumed.
+            ...(this.forkedFrom ? { forkedFrom: this.forkedFrom } : {}),
+        };
+    }
+    async persist() {
+        await this.store?.writeMeta(this.meta());
+    }
+    /** Create the on-disk session directory. Safe to call more than once. */
+    async init() {
+        await this.store?.create(this.meta());
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/agent/session.js.map

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

package/dist/agent/settings.d.ts

@@ -0,0 +1,37 @@
+import type { PermissionRules } from "./permissions.ts";
+/**
+ * Where a remembered permission decision goes.
+ *
+ * Three scopes because the answers genuinely differ. "Always allow `npm test`"
+ * belongs to the project and should be reviewed like any other config.
+ * "Always allow `gh pr create`" is a personal habit. And a decision made while
+ * poking at someone else's repo should not turn into a commit.
+ */
+export type SettingsScope = "user" | "project" | "local";
+export interface Settings {
+    permissions?: PermissionRules;
+}
+export interface SettingsPaths {
+    user: string;
+    project: string;
+    local: string;
+}
+export declare function settingsPaths(cwd: string, home?: string): SettingsPaths;
+export declare class SettingsStore {
+    private readonly paths;
+    constructor(cwd: string, home?: string);
+    pathFor(scope: SettingsScope): string;
+    read(scope: SettingsScope): Promise<Settings>;
+    /** All three scopes merged, user first so project and local win. */
+    readAll(): Promise<PermissionRules>;
+    /**
+     * Add a rule to one scope, preserving whatever else the file holds.
+     *
+     * Read-modify-write rather than overwrite: these files are hand-edited, and
+     * clobbering a comment-laden config to record one approval would be a poor
+     * trade.
+     */
+    addRule(scope: SettingsScope, kind: keyof PermissionRules, pattern: string): Promise<void>;
+    removeRule(scope: SettingsScope, kind: keyof PermissionRules, pattern: string): Promise<boolean>;
+    private write;
+}

package/dist/agent/settings.js

@@ -0,0 +1,113 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { userPath } from "../paths.js";
+import { parseJson } from "../util/json.js";
+export function settingsPaths(cwd, home) {
+    // The user scope goes through the shared resolver, so `OHARNESS_HOME`
+    // redirects settings along with everything else rather than settings being
+    // the one thing still landing in the real home directory.
+    return {
+        user: home ? path.join(home, ".oharness", "settings.json") : userPath("settings.json"),
+        project: path.join(cwd, ".oharness", "settings.json"),
+        // Local settings are per-checkout and belong in .gitignore, which is why
+        // they are a separate file rather than a field in the project one.
+        local: path.join(cwd, ".oharness", "settings.local.json"),
+    };
+}
+export class SettingsStore {
+    paths;
+    constructor(cwd, home) {
+        this.paths = settingsPaths(cwd, home);
+    }
+    pathFor(scope) {
+        return this.paths[scope];
+    }
+    async read(scope) {
+        let raw;
+        try {
+            raw = await readFile(this.paths[scope], "utf8");
+        }
+        catch {
+            return {};
+        }
+        const parsed = parseJson(raw);
+        // A hand-edited file with a syntax error should not block every tool
+        // call; the user finds out when their rule fails to apply.
+        return parsed.ok ? parsed.value : {};
+    }
+    /** All three scopes merged, user first so project and local win. */
+    async readAll() {
+        const merged = { allow: [], deny: [], ask: [] };
+        for (const scope of ["user", "project", "local"]) {
+            const settings = await this.read(scope);
+            merged.allow.push(...(settings.permissions?.allow ?? []));
+            merged.deny.push(...(settings.permissions?.deny ?? []));
+            merged.ask.push(...(settings.permissions?.ask ?? []));
+        }
+        return {
+            allow: dedupe(merged.allow),
+            // Denials accumulate across scopes and are never overridden — a project
+            // must be able to forbid something the user allowed globally.
+            deny: dedupe(merged.deny),
+            ask: dedupe(merged.ask),
+        };
+    }
+    /**
+     * Add a rule to one scope, preserving whatever else the file holds.
+     *
+     * Read-modify-write rather than overwrite: these files are hand-edited, and
+     * clobbering a comment-laden config to record one approval would be a poor
+     * trade.
+     */
+    async addRule(scope, kind, pattern) {
+        const settings = await this.read(scope);
+        const rules = settings.permissions ?? {};
+        const existing = rules[kind] ?? [];
+        if (existing.includes(pattern))
+            return;
+        const updated = {
+            ...settings,
+            permissions: { ...rules, [kind]: [...existing, pattern] },
+        };
+        await this.write(scope, updated);
+    }
+    async removeRule(scope, kind, pattern) {
+        const settings = await this.read(scope);
+        const existing = settings.permissions?.[kind] ?? [];
+        if (!existing.includes(pattern))
+            return false;
+        await this.write(scope, {
+            ...settings,
+            permissions: {
+                ...settings.permissions,
+                [kind]: existing.filter((entry) => entry !== pattern),
+            },
+        });
+        return true;
+    }
+    async write(scope, settings) {
+        const file = this.paths[scope];
+        await mkdir(path.dirname(file), { recursive: true });
+        // Temp file plus rename, so an interrupted write cannot leave a truncated
+        // settings file that silently drops every rule in it.
+        const temp = tempName(file);
+        await writeFile(temp, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+        await rename(temp, file);
+    }
+}
+function dedupe(values) {
+    return [...new Set(values)];
+}
+/**
+ * A unique name for each in-flight write.
+ *
+ * `file.<pid>.tmp` collides when one process writes twice at once: the first
+ * rename moves the shared temp file away and the second fails with ENOENT.
+ * The counter makes concurrent writers independent.
+ */
+let tempSeq = 0;
+function tempName(file) {
+    tempSeq += 1;
+    return `${file}.${process.pid}.${tempSeq}.tmp`;
+}
+//# sourceMappingURL=settings.js.map

package/dist/agent/settings.js.map

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

package/dist/agent/skills.d.ts

@@ -0,0 +1,58 @@
+import type { Logger } from "../util/logger.ts";
+/**
+ * Skills: packaged instructions loaded on demand.
+ *
+ * The point is progressive disclosure. A skill's *description* costs a line in
+ * the system prompt; its body — which can be thousands of tokens of workflow
+ * detail — is only loaded when the model decides the task matches. Putting
+ * every skill body in the prompt would defeat the purpose.
+ */
+export interface Skill {
+    name: string;
+    /** The one line the model sees up front; this is what triggers loading. */
+    description: string;
+    /** Full instructions, loaded by the `skill` tool. */
+    body: string;
+    /** Directory holding SKILL.md, so the body can reference scripts/ etc. */
+    directory: string;
+    /** Where it came from, for `/skills`. */
+    source: "builtin" | "project" | "user" | "config";
+}
+export declare class SkillRegistry {
+    private readonly skills;
+    private readonly logger;
+    constructor(logger?: Logger);
+    register(skill: Skill): this;
+    get(name: string): Skill | undefined;
+    list(): Skill[];
+    get size(): number;
+    /**
+     * Discover skills from the conventional locations. Project skills override
+     * user skills of the same name, so a repo can pin its own version.
+     */
+    discover(cwd: string, extraDirs?: string[]): Promise<void>;
+    /**
+     * The block injected into the system prompt: names and descriptions only.
+     * Returns undefined when there is nothing to advertise, so the prompt does
+     * not carry an empty section.
+     */
+    promptSection(): string | undefined;
+}
+/**
+ * Render a loaded skill for the model.
+ *
+ * The base directory and file listing matter: skills routinely say "run
+ * `scripts/check.py`", and without knowing where they live the model cannot
+ * act on that.
+ */
+export declare function renderSkill(skill: Skill): Promise<string>;
+/** Parse YAML-ish frontmatter. Only `name` and `description` are meaningful. */
+export declare function parseSkillFile(raw: string, fallbackName: string): {
+    name: string;
+    description: string;
+    body: string;
+} | undefined;
+export declare function splitFrontmatter(raw: string): {
+    frontmatter: Record<string, string>;
+    body: string;
+};