@oharness/engine 0.1.0

package/dist/artifacts/store.d.ts

@@ -0,0 +1,324 @@
+import type { Message } from "../core/types.ts";
+/**
+ * Artifacts: the things a turn produces, as opposed to the things it says.
+ *
+ * A file written to the working tree is already a deliverable and the review
+ * pane already shows it as a diff. This is for the other case — a chart, a
+ * rendered page, a document the model is iterating on — where the deliverable
+ * has no natural home on disk and where the interesting question is "what does
+ * it look like now", not "what changed since last time".
+ *
+ * The two properties that make this more than `write` to a temp file:
+ *
+ *   - Identity. An artifact has an id chosen by the model, so a second call
+ *     with the same id is a revision rather than a new object. That is the
+ *     whole mechanism: without it every edit would litter the panel with a
+ *     near-duplicate and the frontend would have no way to know which one is
+ *     current.
+ *   - Versions. Every revision is kept, so a frontend can offer "back to the
+ *     one before you broke it" without the model having to re-derive it.
+ *
+ * Content lives here and never travels in the event stream. Artifacts are
+ * routinely tens of kilobytes and are rewritten in full on every revision;
+ * putting that in an event would push it through the SSE relay and into every
+ * frontend's memory on every keystroke of a rewrite. Frontends get a
+ * descriptor and fetch the body if and when they are going to show it.
+ */
+/**
+ * How much a frontend has to be able to do to show an artifact honestly.
+ *
+ * This list is the contract between the engine and every frontend, and it is
+ * deliberately short. It is not "which mime types exist" — it is "how many
+ * fundamentally different rendering capabilities do we ask a frontend for",
+ * and every entry costs each frontend an implementation or an honest refusal.
+ * Adding one is a decision, which is why the list is closed and why
+ * test/artifacts.test.ts fails when a frontend has no declared answer for a
+ * member of it.
+ *
+ *   text     Plain prose or data. Any frontend can show this.
+ *   markdown Structured prose. A frontend without a renderer shows the source,
+ *            which is still readable — that is why it is separate from `code`.
+ *   code     Source, with a language hint. Degrades to text.
+ *   image    Raster bytes. A terminal generally cannot; see the TUI's answer.
+ *   vector   SVG. Renderable as a document, but also readable as source.
+ *   page     Self-contained HTML that must execute to mean anything. This is
+ *            the only kind that requires a sandbox, and the only one with no
+ *            honest textual degradation.
+ */
+export declare const ARTIFACT_KINDS: readonly ["text", "markdown", "code", "image", "vector", "page"];
+export type ArtifactKind = (typeof ARTIFACT_KINDS)[number];
+/**
+ * The mime that means "this is a canvas".
+ *
+ * Deliberately a mime and not a seventh entry in ARTIFACT_KINDS. That list is
+ * the set of *rendering capabilities* we ask every frontend for, and a canvas
+ * asks for nothing new: it is HTML that has to execute, which is exactly what
+ * `page` already means. What differs is who wrote the surrounding document —
+ * for a `page` the model did, for a canvas the harness does, wrapping the
+ * model's artboards in an editor. A frontend that knows nothing about canvases
+ * still shows one correctly, because what it receives from /artifact/view is a
+ * complete page. Adding a kind would instead have forced every frontend, the
+ * website and a database enum to declare an answer to a question none of them
+ * actually needed to be asked.
+ */
+export declare const CANVAS_MIME = "text/canvas+html";
+/** Whether a mime names a canvas, tolerant of charset parameters and case. */
+export declare function isCanvas(mime: string): boolean;
+/**
+ * The capability a mime type implies, falling back by family.
+ *
+ * Unknown types resolve to `text` rather than throwing: a model that invents
+ * `text/x-rst` should get a usable artifact showing its source, not a tool
+ * error that costs a turn. The fallback is deliberately the least capable
+ * kind — guessing upward would mean handing an unvetted string to a renderer.
+ */
+export declare function kindForMime(mime: string): ArtifactKind;
+/** True for kinds whose body is only meaningful when executed by a browser. */
+export declare function needsSandbox(kind: ArtifactKind): boolean;
+/**
+ * Where an artifact was published, once it has been.
+ *
+ * Held here rather than only in the browser tab that clicked Publish, so a
+ * reload does not offer to publish something that already has a link.
+ * Memory, like the rest of the store: a restarted process forgets the link
+ * but the row on the site is still there, and republishing finds it again by
+ * `source_id` and returns the same URL.
+ */
+export interface ArtifactPublication {
+    url: string;
+    visibility: "unlisted" | "team";
+    teamId?: string;
+    /**
+     * The revision that was sent.
+     *
+     * A published link does NOT follow later revisions — the site holds a copy,
+     * and only another publish overwrites it. Keeping the number here is what
+     * lets a frontend say "the link is showing v2, you are on v4" instead of
+     * quietly serving stale content to whoever was sent it.
+     */
+    version: number;
+}
+/** One revision. Bodies are immutable once stored; a change makes a new one. */
+export interface ArtifactVersion {
+    version: number;
+    content: string;
+    /** Milliseconds since the epoch, for ordering and for "3 revisions ago". */
+    createdAt: number;
+    bytes: number;
+    /**
+     * Who wrote this revision.
+     *
+     * Absent means the model, which is every revision that arrives through
+     * `artifact_write`. `"user"` means a person edited it in a frontend — today
+     * only the canvas editor can do that. Worth recording because the two have
+     * different consequences: the model overwriting its own last revision is
+     * ordinary iteration, and the model overwriting a person's edit is a
+     * surprise that it should be told about (see the artifact_write receipt).
+     */
+    author?: "user";
+}
+export interface Artifact {
+    id: string;
+    title: string;
+    mime: string;
+    kind: ArtifactKind;
+    /** Language hint for `code`, e.g. "python". Advisory: only affects display. */
+    language?: string;
+    versions: ArtifactVersion[];
+    /** Set once the artifact has been copied to the site. */
+    publication?: ArtifactPublication;
+}
+/**
+ * What a frontend is told when an artifact changes.
+ *
+ * Everything needed to draw a row in a list and decide whether this frontend
+ * can render the body — and nothing else. Notably not the content.
+ */
+export interface ArtifactDescriptor {
+    id: string;
+    title: string;
+    mime: string;
+    kind: ArtifactKind;
+    language?: string;
+    version: number;
+    bytes: number;
+    /** Set when the revision on screen was authored by a person, not the model. */
+    author?: "user";
+    /** Total revisions kept, so a frontend can offer history without a fetch. */
+    versionCount: number;
+    /** Present once published. Compare `version` with this one to spot a stale link. */
+    publication?: ArtifactPublication;
+}
+/**
+ * One artifact revision, as it is written to disk and as it crosses the sync
+ * feed.
+ *
+ * Everything needed to rebuild the artifact without the transcript. Flat
+ * rather than nested under an artifact object because the file is a log: each
+ * line stands alone, and an artifact is what you get by folding its lines
+ * together in order.
+ */
+export interface StoredArtifactRevision {
+    /**
+     * Stable across devices, so the server dedupes and a retried push is free.
+     *
+     * These three — id, seq, device — are the same fields `mergeRecords` names
+     * as the ones that must survive the trip, and for the same reason: without
+     * them a merge cannot tell a record it already holds from a new one.
+     *
+     * Optional because a line written before revisions travelled has none, and
+     * those still have to load.
+     */
+    id?: string;
+    /** Lamport counter, shared with the session's messages so one watermark covers both. */
+    seq?: number;
+    device?: string;
+    artifact: string;
+    title: string;
+    mime: string;
+    language?: string;
+    version: number;
+    content: string;
+    at: number;
+    /** Absent for the model, "user" for a revision a person made by hand. */
+    author?: "user";
+}
+/** Reject a log line this build cannot make sense of, rather than half-read it. */
+export declare function asArtifactRevision(value: unknown): StoredArtifactRevision | undefined;
+export declare function isValidArtifactId(id: string): boolean;
+/** Refused rather than truncated: half a document renders as a broken one. */
+export declare const MAX_ARTIFACT_BYTES: number;
+export declare class ArtifactStore {
+    private readonly items;
+    /**
+     * Told about every revision this store accepts.
+     *
+     * A callback rather than a store reference, so this file keeps knowing
+     * nothing about disks, projects or sync — it holds artifacts, and whoever
+     * owns it decides what durability means. It is also what keeps the two
+     * writers symmetrical: a model's `put` and a person's `edit` are the same
+     * kind of event to anything downstream, which is the property that was
+     * missing when only one of them left a trace.
+     */
+    onRevision?: (revision: StoredArtifactRevision) => void;
+    private announce;
+    /**
+     * Record a revision, creating the artifact if this id is new.
+     *
+     * Returns the descriptor rather than the artifact so callers cannot hold a
+     * reference into the store and mutate a stored version in place.
+     */
+    put(input: {
+        id: string;
+        title: string;
+        mime: string;
+        content: string;
+        language?: string;
+    }): ArtifactDescriptor;
+    /**
+     * Record a revision a *person* wrote, in a frontend, to an artifact that
+     * already exists.
+     *
+     * Separate from `put` rather than a flag on it, because the two have
+     * different preconditions and different failure modes. `put` may create, and
+     * takes a title and a mime because the model is declaring what the thing is.
+     * An edit may only revise: there is no such thing as a person creating an
+     * artifact out of nothing here, and letting an edit invent one would give a
+     * frontend a way to conjure artifacts the transcript has no record of. It
+     * also leaves title and mime alone — the canvas editor changes content, and
+     * silently relabelling the artifact because a save round-tripped a field is
+     * not something anybody asked for.
+     *
+     * Returns undefined for an unknown id so the caller can answer 404 rather
+     * than distinguishing exception types; the size ceiling still throws,
+     * because that one is a rejected write and not a missing thing.
+     */
+    edit(id: string, content: string): ArtifactDescriptor | undefined;
+    /**
+     * Put back a revision that was read from disk or arrived over sync.
+     *
+     * Separate from `put` and `edit` because it is not a new event: the version
+     * number and the author were decided when it first happened, and inventing
+     * fresh ones here would renumber a history that other things already refer
+     * to. It also stays silent — announcing would write the log back to the log.
+     */
+    restore(revision: StoredArtifactRevision): void;
+    /** The latest revision, or a specific one. Undefined if either is unknown. */
+    get(id: string, version?: number): {
+        artifact: Artifact;
+        revision: ArtifactVersion;
+    } | undefined;
+    /** Every artifact at its latest revision, oldest first. */
+    list(): ArtifactDescriptor[];
+    /**
+     * Every revision this store holds, oldest first, in the shape it is written
+     * down in.
+     *
+     * Exists for the one-time seeding of a session whose artifacts were rebuilt
+     * by replaying its transcript: without it that session's log would start at
+     * whatever happened next, and the versions that came before would vanish the
+     * moment the log took precedence over the replay.
+     */
+    export(): StoredArtifactRevision[];
+    /** Record that this artifact now has a URL on the site. */
+    markPublished(id: string, publication: ArtifactPublication): ArtifactDescriptor | undefined;
+    /** Forget a publication after it has been withdrawn from the site. */
+    clearPublication(id: string): ArtifactDescriptor | undefined;
+    delete(id: string): boolean;
+    get size(): number;
+}
+/**
+ * Where the store hangs off the session.
+ *
+ * In `session.state` rather than a field on Session, for the same reason the
+ * todo list is: that map is already the session-scoped scratch space tools
+ * reach through `ctx.host.state`, and it is already copied into and out of
+ * subagents. A field would need both of those paths taught about it.
+ *
+ * Consequence worth stating plainly: this is memory, so artifacts live as long
+ * as the process. That matches the todo list and is the right default for a
+ * scratch surface — but it means a frontend must not treat an artifact as a
+ * durable deliverable. Anything that needs to outlive the session gets written
+ * to the working tree with `write`.
+ */
+export declare const ARTIFACTS_KEY = "artifacts:store";
+/**
+ * Rebuild a session's artifacts from its transcript.
+ *
+ * The store is memory, so resuming a conversation used to bring back every
+ * message and none of the things those messages made: the panel was empty, the
+ * cards were gone, and an artifact the user had been looking at ten minutes
+ * earlier had no way back. The content was never actually lost — an artifact's
+ * body is the argument of the `artifact_write` call that made it, and that is
+ * in the transcript like any other tool call. This replays those calls.
+ *
+ * Replaying in order is what restores the version history for free: the second
+ * call for an id becomes v2 exactly as it did the first time round.
+ *
+ * Calls whose result came back an error are skipped — they never made an
+ * artifact, and re-running them here would invent one that never existed.
+ *
+ * What this cannot bring back is a revision written by a person — a canvas
+ * edit is not a tool call and so leaves no trace in the transcript. A resumed
+ * session therefore shows the model's last version as the latest, and the
+ * edits made on top of it are gone. Stated here rather than fixed, because
+ * fixing it means deciding where a human-authored revision is durably stored,
+ * and every cheap answer (a synthetic tool call, a user message carrying the
+ * body) either lies about who acted or pays the artifact's full size in
+ * transcript tokens on every save.
+ */
+export declare function rehydrateArtifacts(store: ArtifactStore, messages: readonly Message[]): number;
+/**
+ * Rebuild a session's artifacts from what was written down, in order.
+ *
+ * Preferred over `rehydrateArtifacts` wherever a log exists, and the two must
+ * not both run: replay derives version numbers by counting writes, the log
+ * carries the numbers that actually happened, and applying one on top of the
+ * other would renumber the history and duplicate every revision.
+ *
+ * The transcript replay stays as the fallback, and has to: every session
+ * recorded before artifacts were written down has no log, and refusing to
+ * rebuild those would take away something that works today.
+ */
+export declare function restoreArtifacts(store: ArtifactStore, revisions: readonly StoredArtifactRevision[]): number;
+export declare function getArtifactStore(state: Map<string, unknown>): ArtifactStore;