@oharness/engine 0.1.0

package/dist/agent/skills.js

@@ -0,0 +1,225 @@
+import { userPath } from "../paths.js";
+import { readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createLogger } from "../util/logger.js";
+const SKILL_FILE = "SKILL.md";
+/**
+ * Skills that ship with the harness.
+ *
+ * Three, and the bar for a fourth is high: a skill's *description* sits in the
+ * system prompt of every request forever, so anything a model already knows
+ * from pretraining — reviewing a diff, debugging, writing tests — is a tax
+ * with no return. What is here is only what cannot be guessed: the rules this
+ * harness imposes on artifacts, the artboard format a canvas is written in,
+ * and the file format skills themselves use.
+ *
+ * `canvas` earned its own entry rather than a section inside
+ * artifact-authoring because it is not advice about a mime — it is a format
+ * the model has no way to derive (which element, which attributes, who writes
+ * the editor) plus a set of consequences that only exist for canvases (a
+ * person's edits become revisions, and a revision of yours can replace them).
+ *
+ * The path is the same from `src/agent/` and from `dist/agent/`, which is why
+ * these live beside the package rather than inside src — no build step has to
+ * remember to copy them, and forgetting one would ship an install whose
+ * built-in skills silently do not exist.
+ */
+function builtinSkillsDir() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
+}
+/** Enough for the model to know what is there without dumping a tree. */
+const MAX_LISTED_FILES = 20;
+export class SkillRegistry {
+    skills = new Map();
+    logger;
+    constructor(logger) {
+        this.logger = (logger ?? createLogger("skills")).child("registry");
+    }
+    register(skill) {
+        this.skills.set(skill.name, skill);
+        return this;
+    }
+    get(name) {
+        return this.skills.get(name);
+    }
+    list() {
+        return [...this.skills.values()].sort((a, b) => a.name.localeCompare(b.name));
+    }
+    get size() {
+        return this.skills.size;
+    }
+    /**
+     * Discover skills from the conventional locations. Project skills override
+     * user skills of the same name, so a repo can pin its own version.
+     */
+    async discover(cwd, extraDirs = []) {
+        const roots = [
+            // First, so everything else can override one by name. A user who
+            // disagrees with a built-in replaces it rather than being stuck with it.
+            { dir: builtinSkillsDir(), source: "builtin" },
+            { dir: userPath("skills"), source: "user" },
+            { dir: path.join(cwd, ".oharness", "skills"), source: "project" },
+            ...extraDirs.map((dir) => ({ dir: path.resolve(cwd, dir), source: "config" })),
+        ];
+        for (const root of roots) {
+            for (const skill of await scanDirectory(root.dir, root.source, this.logger)) {
+                this.register(skill);
+            }
+        }
+    }
+    /**
+     * 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() {
+        const skills = this.list();
+        if (skills.length === 0)
+            return undefined;
+        const lines = [
+            "## Available skills",
+            "",
+            "Skills are packaged instructions for specific kinds of work. When a task matches",
+            "one of the descriptions below, call the `skill` tool with its name to load the full",
+            "instructions before you start. Do not guess at a skill's contents from its description.",
+            "",
+        ];
+        for (const skill of skills) {
+            lines.push(`- **${skill.name}** — ${skill.description}`);
+        }
+        return lines.join("\n");
+    }
+}
+/**
+ * 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 async function renderSkill(skill) {
+    const files = await listSkillFiles(skill.directory);
+    const parts = [
+        `<skill name="${skill.name}">`,
+        skill.body.trim(),
+        "",
+        `Base directory: ${skill.directory}`,
+        "Relative paths in this skill (scripts/, reference/, …) resolve against that directory.",
+    ];
+    if (files.length > 0) {
+        parts.push("", "Files in this skill:");
+        for (const file of files.slice(0, MAX_LISTED_FILES))
+            parts.push(`  ${file}`);
+        if (files.length > MAX_LISTED_FILES) {
+            parts.push(`  … ${files.length - MAX_LISTED_FILES} more`);
+        }
+    }
+    parts.push("</skill>");
+    return parts.join("\n");
+}
+// ---------------------------------------------------------------------------
+async function scanDirectory(root, source, logger) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return []; // The directory simply does not exist.
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() && !entry.isSymbolicLink())
+            continue;
+        const directory = path.join(root, entry.name);
+        const file = path.join(directory, SKILL_FILE);
+        let raw;
+        try {
+            const info = await stat(file);
+            if (!info.isFile())
+                continue;
+            raw = await readFile(file, "utf8");
+        }
+        catch {
+            continue; // A directory without SKILL.md is not a skill.
+        }
+        const parsed = parseSkillFile(raw, entry.name);
+        if (!parsed) {
+            // A skill with no description can never be selected, since the
+            // description is the only thing the model sees.
+            logger.warn("skill has no description; skipping", { directory });
+            continue;
+        }
+        out.push({ ...parsed, directory, source });
+    }
+    return out;
+}
+/** Parse YAML-ish frontmatter. Only `name` and `description` are meaningful. */
+export function parseSkillFile(raw, fallbackName) {
+    const { frontmatter, body } = splitFrontmatter(raw);
+    const name = frontmatter["name"]?.trim() || fallbackName;
+    const description = frontmatter["description"]?.trim();
+    if (!description)
+        return undefined;
+    return { name, description, body };
+}
+export function splitFrontmatter(raw) {
+    const normalized = raw.replace(/^/, "");
+    if (!normalized.startsWith("---"))
+        return { frontmatter: {}, body: normalized };
+    const end = normalized.indexOf("\n---", 3);
+    if (end === -1)
+        return { frontmatter: {}, body: normalized };
+    const block = normalized.slice(normalized.indexOf("\n") + 1, end);
+    const body = normalized.slice(normalized.indexOf("\n", end + 1) + 1);
+    const frontmatter = {};
+    let currentKey;
+    for (const line of block.split("\n")) {
+        const match = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+        if (match) {
+            currentKey = match[1];
+            frontmatter[currentKey] = stripQuotes(match[2].trim());
+            continue;
+        }
+        // Continuation of a folded value, e.g. a description wrapped over lines.
+        if (currentKey && /^\s+\S/.test(line)) {
+            frontmatter[currentKey] = `${frontmatter[currentKey]} ${line.trim()}`.trim();
+        }
+    }
+    return { frontmatter, body };
+}
+function stripQuotes(value) {
+    if (value.length >= 2 && (value.startsWith('"') || value.startsWith("'"))) {
+        const quote = value[0];
+        if (value.endsWith(quote))
+            return value.slice(1, -1);
+    }
+    return value;
+}
+/** Relative paths of the files a skill ships, excluding SKILL.md itself. */
+async function listSkillFiles(directory, prefix = "") {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue;
+        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            // One level deep is enough to show structure without walking a tree.
+            if (prefix === "")
+                out.push(...(await listSkillFiles(path.join(directory, entry.name), relative)));
+            continue;
+        }
+        if (relative === SKILL_FILE)
+            continue;
+        out.push(relative);
+    }
+    return out.sort();
+}
+//# sourceMappingURL=skills.js.map

package/dist/agent/skills.js.map

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

package/dist/agent/store.d.ts

@@ -0,0 +1,308 @@
+import type { Message, Usage } from "../core/types.ts";
+import type { AuditEntry } from "./permissions.ts";
+import type { StoredArtifactRevision } from "../artifacts/store.ts";
+import type { MessageRecord } from "../storage/records.ts";
+export interface SessionMeta {
+    id: string;
+    createdAt: number;
+    updatedAt: number;
+    cwd: string;
+    model: string;
+    title?: string;
+    turns: number;
+    usage: Usage;
+    costUsd: number;
+    /** Session this one was branched from, if any. */
+    forkedFrom?: string;
+    /** How many messages the parent had at the branch point. */
+    forkedAt?: number;
+    /**
+     * The project the session belongs to — a repository, not a path. Sessions
+     * recorded before this existed are assigned one when they are read.
+     */
+    projectId?: string;
+    /**
+     * Bumped when the transcript is rewritten rather than appended to, which is
+     * what compaction does. A merge takes the highest generation whole: replaying
+     * appends from before a rewrite would resurrect what compaction dropped.
+     */
+    gen?: number;
+    /** Highest sequence number handed out in this session's log. */
+    seq?: number;
+}
+/**
+ * Cap on how much of an archive a single `recall` loads. Generous enough that
+ * ordinary sessions read in full, small enough that a runaway one cannot
+ * exhaust memory.
+ */
+export declare const MAX_ARCHIVE_READ_BYTES: number;
+/**
+ * Cap on how much of a permission trail one read loads. Smaller than the
+ * archive's: these are short lines, and a page showing the trail wants the
+ * recent end of it, not a session's entire history of tool calls.
+ */
+export declare const MAX_DECISION_READ_BYTES: number;
+export interface SessionRecord {
+    meta: SessionMeta;
+    messages: Message[];
+}
+/** One archived message, as written when compaction dropped it. */
+export interface ArchivedMessage {
+    /** Position in the original transcript, stable across compactions. */
+    seq: number;
+    /** When the compaction that archived it ran. */
+    archivedAt: number;
+    message: Message;
+}
+/**
+ * Where sessions live.
+ *
+ * Keyed files under one root rather than a directory per session:
+ *
+ *     storage/migration                        how many layout changes have run
+ *     storage/device.json                      this machine's id, for merges
+ *     storage/project/<projectId>.json         a repository, by its root commit
+ *     storage/session/<projectId>/<id>.json    session metadata
+ *     storage/message/<id>.jsonl               the transcript, one record a line
+ *     storage/archive/<id>.jsonl               what compaction dropped
+ *     storage/decision/<id>.jsonl              every permission decision
+ *
+ * Grouping sessions under a project makes listing one project's history a
+ * single directory read instead of opening every session on the machine, and
+ * gives sync something to scope to. Messages stay in a flat log per session
+ * because appending is the hot path and appending must not rewrite.
+ */
+/**
+ * A local write, as reported to whoever is watching.
+ *
+ * `meta` is carried on a deletion too, and captured before the files go: a
+ * tombstone has to travel or the other device restores what was deleted, and
+ * after `remove` there is nothing left to describe.
+ */
+export interface StoreChange {
+    kind: "write" | "delete";
+    id: string;
+    projectId: string;
+    meta: SessionMeta;
+}
+export declare class SessionStore {
+    private readonly kv;
+    private readonly legacyRoot;
+    private ready;
+    private deviceId;
+    /** Which project a session was found under, so a second read is a direct hit. */
+    private readonly located;
+    private readonly watchers;
+    constructor(root?: string);
+    get root(): string;
+    /**
+     * Watch local writes. Returns the unsubscribe.
+     *
+     * Sync needs to know when to push, and the alternatives are worse: polling
+     * the directory turns an event into a delay, and calling a client from the
+     * write paths would put a network dependency inside the only thing here that
+     * must not be able to fail. A watcher is told what changed and decides for
+     * itself, so nothing above this file is reachable from below it.
+     *
+     * Listeners are called after the write has landed, and one that throws is
+     * ignored — a mirror falling over is not a reason to lose a transcript.
+     */
+    watch(listener: (change: StoreChange) => void): () => void;
+    private announce;
+    /** A session's transcript as records, ordered and deduplicated. */
+    recordsOf(id: string): Promise<MessageRecord[]>;
+    /** A session's metadata, without being told which project it is under. */
+    readMeta(id: string): Promise<SessionMeta | undefined>;
+    /**
+     * Take records that were written somewhere else.
+     *
+     * Distinct from `appendMessage`, which mints an id, a seq and this device —
+     * exactly the three fields that must survive the trip for a merge to work.
+     * The log is append-only and `orderRecords` deduplicates on read, so writing
+     * a record that is already held costs a line and changes nothing, which is
+     * what makes a retried pull safe.
+     */
+    mergeRecords(id: string, incoming: MessageRecord[]): Promise<number>;
+    /**
+     * Take metadata written somewhere else, if it is newer.
+     *
+     * Generation first, then wall clock. A generation is bumped by a rewrite, so
+     * a device that compacted a session wins over one that merely kept appending
+     * to it — no amount of clock skew should let a stale full transcript
+     * overwrite a summary that replaced it.
+     */
+    mergeMeta(incoming: SessionMeta): Promise<boolean>;
+    /** Layout changes run once, on first use, before anything reads. */
+    private prepare;
+    /**
+     * This machine's id.
+     *
+     * Two devices appending to one session need to be distinguishable, and the
+     * tiebreak has to survive restarts — so it is stored rather than generated
+     * per process.
+     */
+    private device;
+    private projectOf;
+    /** Find a session's metadata without being told which project it is in. */
+    private findMeta;
+    create(meta: SessionMeta): Promise<void>;
+    writeMeta(meta: SessionMeta): Promise<void>;
+    /**
+     * The write itself, without telling anyone.
+     *
+     * Applying what a pull returned goes through here: announcing it would have
+     * the mirror push back what it had just received, and while the server
+     * deduplicates that, a loop that is merely harmless is still a loop.
+     */
+    private putMeta;
+    private touchProject;
+    appendMessage(id: string, message: Message): Promise<void>;
+    /**
+     * Record one artifact revision on disk.
+     *
+     * A log rather than a document, for the same reason the transcript is one:
+     * a revision is a thing that happened, appending never rewrites what is
+     * already there, and a crashed process still leaves everything written
+     * before it. It also means the version history comes free — the file is the
+     * history, in order.
+     *
+     * Keyed by session alone, like `message` and `archive`, because an artifact
+     * belongs to the conversation that made it and is found the same way.
+     *
+     * This is what makes an artifact something other than a by-product of the
+     * transcript. A model's write was always recoverable, because the content is
+     * the argument of a tool call and tool calls are in the transcript. A
+     * revision a person made in the canvas is not a tool call and was therefore
+     * nowhere: a restart brought the model's version back as the newest one and
+     * said nothing about what it had replaced.
+     */
+    appendArtifactRevision(id: string, revision: StoredArtifactRevision): Promise<void>;
+    /**
+     * Take artifact revisions written on another device.
+     *
+     * The counterpart to `mergeRecords`, and deliberately its shape: dedupe on
+     * the record id, append what is new, and let the reader fold the file
+     * together. A revision already held costs a line and changes nothing, which
+     * is what makes a retried pull safe.
+     */
+    mergeArtifactRevisions(id: string, incoming: StoredArtifactRevision[]): Promise<number>;
+    /**
+     * Sessions that have written an artifact, whether or not they are loaded.
+     *
+     * A directory read, not a transcript read. Artifacts belong to sessions and
+     * a session's store is memory, so "everything on this machine" used to mean
+     * "everything currently open" — which is a listing that changes depending on
+     * which tabs happen to be open, and that is not a listing anybody can trust.
+     * The logs are the durable record; this says which ones exist so a caller
+     * can fold the ones it wants without opening a session to ask.
+     */
+    artifactSessions(): Promise<string[]>;
+    /**
+     * Every artifact revision recorded for a session, oldest first.
+     *
+     * `maxBytes` reads the tail, for a caller that is building a listing rather
+     * than restoring a session: the newest lines are the ones a listing shows,
+     * and a log with a megabyte of superseded revisions in it should not cost a
+     * megabyte to summarise.
+     */
+    artifactRevisions(id: string, maxBytes?: number): Promise<StoredArtifactRevision[]>;
+    /**
+     * Record one permission decision, with the session it happened in.
+     *
+     * Beside the transcript rather than in a file of its own somewhere else,
+     * because a decision is a thing that happened *in this conversation*: kept
+     * here it is found the way everything else about the session is found,
+     * deleted when the session is deleted, and readable next to the tool call it
+     * was about. A separate audit file is a second truth that has to be
+     * correlated by timestamp, and correlating by timestamp is how two records
+     * of the same event end up disagreeing.
+     *
+     * No seq and no device, unlike messages and artifact revisions: nothing
+     * merges this log. It stays on the machine that wrote it — see `SessionMirror`,
+     * which pushes messages and artifacts and deliberately not this.
+     */
+    appendDecision(id: string, entry: AuditEntry): Promise<void>;
+    /**
+     * A session's permission trail, oldest first.
+     *
+     * Bounded like the archive read: the trail grows for the life of a session —
+     * every tool call adds a line — and a long unattended run should not be able
+     * to make reading it the most expensive thing the harness does.
+     */
+    decisions(id: string, maxBytes?: number): Promise<AuditEntry[]>;
+    /**
+     * Append messages to the archive before they leave the live transcript.
+     *
+     * Compaction replaces history with a lossy summary; without this the
+     * originals would be unrecoverable — not just to the agent, but to anyone
+     * debugging the session afterwards. The archive is append-only and is never
+     * rewritten.
+     */
+    archiveMessages(id: string, entries: Array<{
+        seq: number;
+        message: Message;
+    }>): Promise<void>;
+    /**
+     * Read the archive, newest-biased and bounded.
+     *
+     * The archive is append-only and grows for the life of a session — every
+     * compaction and every oversized tool result adds to it. Reading all of it
+     * into memory to answer one `recall` would eventually be the most expensive
+     * thing the harness does, so only the tail is loaded past a threshold.
+     */
+    readArchive(id: string, maxBytes?: number): Promise<ArchivedMessage[]>;
+    /**
+     * Branch a session into a new one.
+     *
+     * The parent is never touched — that is the whole point. Exploring a
+     * different approach should not cost you the transcript that got you here,
+     * and mutating in place makes "go back and try the other thing" impossible.
+     */
+    fork(sourceId: string, opts?: {
+        keepMessages?: number;
+        title?: string;
+        newId?: string;
+    }): Promise<{
+        id: string;
+        meta: SessionMeta;
+        messages: Message[];
+    } | undefined>;
+    /** Permanently remove a session and everything it recorded. */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Every session recorded in one tree, deleted.
+     *
+     * By working directory rather than by project id, because that is what the
+     * sidebar groups by and therefore what somebody is looking at when they ask
+     * for this. Deleting one at a time is the same work either way — there is no
+     * bulk primitive underneath — but each one still announces its own tombstone,
+     * so a device syncing with this one loses exactly the same set.
+     *
+     * Returns the ids that went, so a caller holding open tabs knows which of
+     * them are now pointing at nothing.
+     */
+    deleteIn(cwd: string): Promise<string[]>;
+    rename(id: string, title: string): Promise<boolean>;
+    /** Sessions branched from a given one. */
+    children(id: string): Promise<SessionMeta[]>;
+    /**
+     * Delete old sessions.
+     *
+     * Nothing reclaimed these before, so a machine used daily accumulates every
+     * transcript and archive it ever produced. Returns the ids removed.
+     */
+    prune(opts?: {
+        maxAgeDays?: number;
+        keep?: number;
+    }): Promise<string[]>;
+    /** Rewrite the transcript wholesale — used after compaction. */
+    replaceMessages(id: string, messages: Message[]): Promise<void>;
+    private records;
+    load(id: string): Promise<SessionRecord | undefined>;
+    list(limit?: number, opts?: {
+        projectId?: string;
+    }): Promise<SessionMeta[]>;
+    private backfillTitle;
+    /** Most recently updated session for a directory, for `--continue`. */
+    mostRecent(cwd?: string): Promise<SessionMeta | undefined>;
+}