@intentic/extension-api 1.176.3 → 1.209.1

package/src/api.ts

@@ -1,4 +1,7 @@
+import type { sandboxContract } from "@intentic/sandbox-contract";
+import type { ContractRouterClient } from "@orpc/contract";
 import type { Component } from "vue";
+import type { DiffPayload } from "./diff.js";
 import type { CapabilityFacts, RepoFacts } from "./facts.js";
 
 /* The host API an extension programs against. There is no ambient global: the implementation arrives as the
@@ -39,16 +42,44 @@ export interface ViewBadge {
     // be sent" is the whole message, and a number beside it would be read in the unit `count` established —
     // so the amount goes in the tooltip and the glyph carries the kind. A badge with neither renders nothing.
     readonly mark?: string | undefined;
-    // `info` is the resting tone every core count uses (unread agents, uncommitted changes, live terminals);
-    // `warning` marks a risk the user is carrying (an exposed port); `danger` means something is BROKEN.
-    // Reach for danger sparingly — its whole value is that it is rare enough to still mean something.
-    readonly tone?: "info" | "warning" | "danger" | undefined;
+    // THE FIRST QUESTION A BADGE ANSWERS IS "DO I OWE THIS ANYTHING?", and until `neutral` existed there was no
+    // way to say no. A count that means "three things are alive in here" (open browsers, running services) was
+    // drawn exactly like one that means "three things are waiting on you" — same pill, same tint, same digit —
+    // so a reader who chased one and found an inventory learned that badges do not repay being chased. That is
+    // the failure this vocabulary exists to prevent, arriving through the door it left open.
+    //
+    // `neutral` is an INVENTORY: true most of the day, nothing owed, quiet ink. `info` is the resting tone for
+    // work the user can act on (unread agents, uncommitted changes); `warning` marks a risk they are carrying
+    // (an exposed port); `danger` means something is BROKEN — reach for it sparingly, its whole value is that it
+    // is rare enough to still mean something. Absent still means `info`, so a badge that says nothing about its
+    // tone is still assumed to be asking for something.
+    readonly tone?: "neutral" | "info" | "warning" | "danger" | undefined;
     // Say what happened and how much, not just the number the user can already see. The host renders it
     // AFTER the view's own name — "Agents · 3 need you" on the rail, the chip's text in the mobile menu — so
     // phrase it as the continuation of a label, not as a standalone sentence that repeats the view.
     readonly tooltip?: string | undefined;
 }
 
+/* ONE CACHED READ, described rather than performed — the currency both `ViewRegistration.warm` and
+ * `api.sandbox.fetch` deal in.
+ *
+ * It is deliberately the shape a vue-query `useQuery` already takes, because that is the point: the entry a
+ * view warms, the entry its badge fills from a timer and the entry the view's own `useQuery` observes are ONE
+ * entry, and they are one entry because all three name it the same way. Two of the three used to be separate
+ * reads of the same route in this app's own extensions — the tile fetched the report every ten minutes and kept
+ * it privately, and the view it badged for started from nothing every time it was opened.
+ *
+ * The caching terms are optional and yours: `staleTime` is how long an answer stays believable without a
+ * refetch (Infinity for something only an invalidation can make wrong), `gcTime` how long it survives with
+ * nothing observing it. Both default to the host's. */
+export interface HostQuery<T = unknown> {
+    // MUST be scoped by api.sandbox.key(...), so nothing bleeds across a sandbox switch.
+    readonly queryKey: readonly unknown[];
+    readonly queryFn: () => Promise<T>;
+    readonly staleTime?: number | undefined;
+    readonly gcTime?: number | undefined;
+}
+
 // A view's runtime registration — for third-party extensions, `id`, `label` and `surface` must match a
 // `contributes.views` entry in the approved manifest or the host refuses the registration.
 export interface ViewRegistration {
@@ -75,6 +106,25 @@ export interface ViewRegistration {
     // The source has to stay alive while the view is UNMOUNTED (a badge you only see once you have already
     // navigated to the view is pointless), so it belongs in module state owned by activate(), not in the view.
     readonly badge?: ((activation: Activation) => ViewBadge | undefined) | undefined;
+    /* WHAT THIS VIEW WOULD LIKE IN HAND BEFORE ANYONE OPENS IT — read ahead by the host's background loader in
+     * the gaps between what the user is already doing, so the tile opens with content instead of a skeleton.
+     *
+     * A rail tile is at the far end of the loader's priority order (the user is not there, they might GO
+     * there), so this is a wish and never a guarantee: on a workspace busy enough that nothing is spare, none
+     * of it is read and the view costs exactly what it cost before. Nothing here is user-visible, nothing
+     * retries, and a failed warm is simply a warm that did not happen.
+     *
+     * DECLARE THE QUERY, not a function that fetches it — that is the whole reason this takes a HostQuery. The
+     * host's own wishes used to carry a cache key and a separate "how to read it" callback, and for most of
+     * them the callback fetched the data and returned it to its caller without ever filing it under that key.
+     * The wish could then never be satisfied, and since the loader always takes the first unsatisfied wish, one
+     * of them was enough to park it for the whole session. Handing over the query makes the two halves the same
+     * object. Use the SAME key your view's `useQuery` reads (api.sandbox.key(...)), or you are warming an entry
+     * nothing will look in.
+     *
+     * Called on every beat of the loader, so it must be cheap and pure — derive from state you already keep,
+     * never fetch. A throwing warm contributes nothing that beat. */
+    readonly warm?: (() => readonly HostQuery[]) | undefined;
     // A fallback view's activations are dropped for repos already claimed by a non-fallback one.
     readonly fallback?: true | undefined;
     // An AUXILIARY view adds a surface BESIDE whatever else serves the repo instead of replacing it — a test
@@ -105,6 +155,15 @@ export interface DocumentOffer {
     readonly tooltip: string;
     // The tab's label. Short: the strip already shows the directory's own name beside it.
     readonly title: string;
+    /* Whether the row keeps this icon when the pointer is elsewhere. A tree row's icons are revealed on hover,
+     * because a permanent column of them is what stops the eye reading names — but that rule assumes an icon is
+     * an ACTION you already know you want. An offer that is EVIDENCE is the opposite case: "there is a page about
+     * this package" is a fact nobody can act on until they see it, and finding it by sweeping fifty-five rows with
+     * the mouse is not finding it. Such an offer sets this, and the row carries it dimmed until hover.
+     *
+     * Left off (the default) by an offer every directory of its kind gets — a repo's git history is always there,
+     * so a permanent glyph states nothing and costs the same attention. */
+    readonly evidence?: boolean;
 }
 
 /* A DOCUMENT PROVIDER — an extension's answer to "there is something to READ about this directory".
@@ -131,6 +190,38 @@ export interface DocumentProviderRegistration {
     readonly view: () => Promise<Component>;
 }
 
+/* EVERYTHING THAT DECIDES WHO SERVES A TURN, as one value. The label is here because a view that shows a chosen
+ * model without showing the list would otherwise have to keep a catalog of its own — which is exactly the
+ * duplication `api.models` exists to end.
+ *
+ * The last two are optional because they are pins, and the unpinned state is the one most callers want: absent
+ * means "whatever the daemon resolves", which is what keeps a saved choice working after an account is
+ * disconnected or a harness gains a provider. A caller that only cares which model runs can ignore both and
+ * lose nothing. */
+export interface PickedModel {
+    // An `AgentProvider` — `claude`, `codex`, a configured model endpoint's id, an installed ACP agent's id.
+    // Open on purpose: the set grows with what the sandbox has connected, and an extension only carries it.
+    readonly provider: string;
+    readonly model: string;
+    readonly label: string;
+    /* WHICH CONNECTED ACCOUNT of that provider runs the turn, by its daemon-minted id — absent ⇒ whichever comes
+     * first. It is on the pick rather than left to the daemon because the surfaces that start UNATTENDED runs are
+     * the ones that need it: nobody is watching at 6am, so a first account that has run out of headroom (or whose
+     * organization switched the plan off) is a run that errors every time until someone reads the row. */
+    readonly account?: string | undefined;
+    /* What the shell calls that account — the sign-in identity, which is the only part of it the owner
+     * recognises ("Claude" is what three unrenamed accounts are all called).
+     *
+     * Absent means the shell cannot name it, which covers BOTH a pin whose credential has been disconnected and
+     * an account list this sandbox has not been read for yet. Do not render the first from the second: they are
+     * the same absence, and a view that reads it as "this automation is broken" says so about every row while the
+     * daemon is merely still starting. Show the name when there is one, and nothing when there isn't. */
+    readonly accountLabel?: string | undefined;
+    // `native` or `claude-code` — the agentic loop, an axis of its own since codex/grok run the same subscription
+    // model ids under either. Absent ⇒ native, which for every other provider is the only answer there is.
+    readonly harness?: string | undefined;
+}
+
 export type SettingValue = string | number | boolean;
 
 export interface ProcessStatus {
@@ -155,6 +246,17 @@ export interface IntenticApi {
     // renders one; the host draws the tree's affordance and owns the tab. See DocumentProviderRegistration.
     readonly documents: {
         register(provider: DocumentProviderRegistration): Disposable;
+        /* Open one of THIS extension's documents for a directory, as if its row icon had been clicked.
+         *
+         * The row is the ordinary way in, so this is for the directories that have no row: the workspace root,
+         * which the tree renders the contents of rather than a line for. Without it a command contributed
+         * alongside a document provider — "Show Git History" in the palette — has nothing it can actually open.
+         *
+         * `id` must be one of this extension's registered providers, and the provider must have an offer for
+         * `path` (the same `detect()` the tree asks); a provider that has nothing to say about the directory
+         * opens nothing rather than an empty tab. The title and glyph come from that offer, so the tab reads
+         * exactly as it would have from the row. */
+        open(id: string, path: string): void;
     };
     readonly commands: {
         // `command` must match a `contributes.commands` entry in the approved manifest.
@@ -168,11 +270,36 @@ export interface IntenticApi {
         onDidChange(listener: (key: string) => void): Disposable;
     };
     // The authenticated transport to the sandbox daemon's routes — auth is injected host-side; an extension
-    // never sees tokens. Reach is scoped: request/json are gated by the manifest's `permissions.sandbox`
+    // never sees tokens. Reach is scoped: every door here is gated by the manifest's `permissions.sandbox`
     // allowlist, so a call to an undeclared method+path throws rather than reaching the whole daemon.
     readonly sandbox: {
+        /* THE DAEMON, TYPED — the same contract the daemon implements, so a call names a procedure instead of
+         * building a URL. `rpc.git.stashApply({ repo, ref, pop })` carries the declared input shape and answers
+         * the declared output shape, both checked at build time.
+         *
+         * This is the door to reach for. `request`/`json` below take a path string, which means every caller
+         * re-derives what this already knows: the method, the escaping, the query encoding, and the shape of the
+         * answer — the last of those as an unchecked assertion that keeps compiling long after the daemon's reply
+         * has changed underneath it. Thirteen extensions between them hand-wrote a hundred such calls and
+         * re-validated half the responses against the very schemas the contract had already declared.
+         *
+         * Gated identically, and on the same evidence: the host resolves the procedure to its method and concrete
+         * path and checks THAT against `permissions.sandbox`, so a manifest neither gains nor loses reach by an
+         * extension switching doors, and the usage record stays comparable across both. */
+        readonly rpc: ContractRouterClient<typeof sandboxContract>;
         request(path: string, init?: RequestInit): Promise<Response>;
         json<T>(path: string, init?: RequestInit): Promise<T>;
+        /* READ THROUGH THE HOST'S CACHE, from outside a component — the door for the module-level timers that
+         * badge a rail tile, which is where `useQuery` cannot reach.
+         *
+         * Concurrent callers of one key share a single request, and a caller inside `staleTime` is answered
+         * from cache with no round trip at all. Which is what makes this worth using over `json`: a badge that
+         * polls a route on its own timer and hands the answer only to itself makes the view it badges for pay
+         * for the same read again on open. Through here, the badge's poll IS the view's first paint.
+         *
+         * The route is gated exactly as `json` is — `queryFn` is your function, and whatever it calls carries
+         * its own manifest check. */
+        fetch<T>(query: HostQuery<T>): Promise<T>;
         // Whether the active sandbox is currently reachable — reactive when read inside a computed, so it
         // drives host-provided vue-query `enabled` options.
         reachable(): boolean;
@@ -183,11 +310,76 @@ export interface IntenticApi {
         // endpoints. Undefined until the sandbox has registered its address. Not needed for `request`/`json`
         // (those take a path and inject auth) — only when the raw origin must be shown to the user.
         origin(): string | undefined;
+        /* THE SIGNED-IN USER'S TRUST TIER on the active sandbox — `owner`, `maintainer`, `collaborator` or
+         * `viewer` — reactive when read inside a computed, like `reachable`. For AFFORDANCES ONLY: every route
+         * is independently floored by the daemon, so what this gates is whether an Approve button renders, never
+         * whether the call would succeed. A view that shows a viewer buttons the daemon will refuse teaches them
+         * that buttons lie; this is how a view says less instead.
+         *
+         * The first consumer is the drafts queue (approve/reject are maintainer-and-up), and it existed as a
+         * private composable before it was public API — which is the pattern this package's history warns about:
+         * a surface only its own app needs is a surface nobody else can build the same feature on. */
+        role(): "owner" | "maintainer" | "collaborator" | "viewer";
     };
     readonly workspace: {
         repos(): readonly RepoFacts[];
         capabilities(): readonly CapabilityFacts[];
         onDidChange(listener: () => void): Disposable;
+        /* A REF MOVED IN ONE OF THESE REPOS — a commit, a branch, a checkout, a rebase, an aborted merge.
+         *
+         * Separate from `contributes.files` because no file contribution could ever carry it: the daemon's
+         * watcher descent-ignores `.git`, so a changed ref produces no `workspaceChanged` path to match a prefix
+         * against. The daemon diffs the git dirs itself and pushes the repos that moved, exactly as it does for
+         * the repo SET (which the same watcher cannot see either, and for the same reason).
+         *
+         * This matters most for work the user did not do: an agent commits, rebases or lands out-of-band, with no
+         * HTTP mutation in this browser to hang an invalidate on. Without this a git surface is only ever as fresh
+         * as the last thing the user clicked. `repos` are root-relative ids ("root" is the workspace repo itself).
+         */
+        onDidChangeRefs(listener: (repos: readonly string[]) => void): Disposable;
+        /* OPEN A DIFF IN THE EDITOR AREA — the host's tab strip, beside the files the diff is about.
+         *
+         * The shell owns the strip, the viewer, the close orchestration and the edit-buffer bookkeeping; the
+         * extension owns only the question of what changed. Re-opening the same `key`+`scope`+`path` focuses the
+         * tab that is already open rather than stacking a second copy — see DiffPayload for how that identity is
+         * built. On mobile, where there is no strip, the host navigates to the diff instead.
+         */
+        openDiff(payload: DiffPayload): void;
+        /* FILL A DIFF OPENED WITH `pending` — the second half of opening a tab before its content exists.
+         *
+         * Refreshes, never opens: a tab the user has since closed or replaced takes nothing, and the content is
+         * simply dropped. That is what makes the pending open safe to use for a slow source — a reader who has
+         * moved on to another file is never yanked back to this one, and never has it appear under them.
+         */
+        fillDiff(payload: DiffPayload): void;
+        /* READING AND WRITING WORKSPACE FILES — the daemon's file routes, without the encoding.
+         *
+         * Extensions keep their durable state in the workspace rather than in settings: an acceptance run's
+         * reports, a documentation set's staging tree, the "what has the rail badge already shown" file each of
+         * them keeps. That is the right home — it survives a reload, it is shared across the owner's browsers,
+         * and the agent writing into it out-of-band is the whole point — but it left every extension spelling
+         * `sandbox.json(\`/workspace/file?path=${encodeURIComponent(path)}\`)` and then parsing the envelope out
+         * of the answer. Three extensions had five byte-identical copies of that one function.
+         *
+         * Gated exactly as `sandbox.request`/`sandbox.json` are: these go through the same permission check, so
+         * an extension still declares `GET /workspace/file` and `POST /workspace/upload` in its manifest and one
+         * that doesn't is still refused. This removes the encoding, not the grant. */
+        // The file's text, or undefined when it is not there. Absent is the ordinary FIRST state for most of what
+        // extensions keep — nothing has been acknowledged because nothing has been seen — so it is a value here,
+        // not a throw every caller would have to wrap. The daemon reports it the same way (a 200 that says the
+        // path holds nothing), so a poll over files that do not exist yet is silent rather than a page of failed
+        // requests in the owner's console.
+        file(path: string): Promise<string | undefined>;
+        /* The file parsed as a JSON object, or undefined when it is absent, truncated, or not an object at all.
+         *
+         * One tolerant reader rather than one per caller. These files are written by agents and editable by
+         * hand, so a half-written or hand-mangled one is a case that WILL happen, and "skip it" is the right
+         * answer everywhere: one bad file must never blank the surface that reads it. Arrays answer undefined
+         * too — every caller of this wants a record. */
+        readJson<T>(path: string): Promise<T | undefined>;
+        // Create or replace a workspace file. Throws on failure, unlike the reads: a write that silently did
+        // nothing would lose the thing the caller was told was saved.
+        write(path: string, body: string): Promise<void>;
     };
     // The extension's OWN declared background processes — names outside the manifest are refused.
     readonly processes: {
@@ -210,6 +402,79 @@ export interface IntenticApi {
         // Open (or focus) the tab for a stored runtime session id — the same path the History menu and the fleet
         // board take. A session the daemon no longer holds opens an empty tab rather than failing.
         openSession(sessionId: string): void;
+        /* AIM A NEW CHAT AT A WORKFLOW: the host opens a session exactly as "New agent" does, with the
+         * composer's workflow badge set to this design — so the next message the user types becomes that run's
+         * request instead of a turn on the chat.
+         *
+         * It hands over the START of the work rather than performing it, and that is the point. An extension
+         * with a Run button used to have two bad options: start the run itself behind its own dialog (a second
+         * way to begin agent work, with its own box that looks like nothing else in the product), or navigate
+         * to a page about the run. This is the third: the extension names the design, and the user starts it
+         * where they start everything else.
+         *
+         * A workflow id, not a run id, and the id is all it can be: sandbox-contract imports THIS package, so
+         * nothing here can name a `Workflow` type.
+         */
+        composeWorkflow(workflowId: string): void;
+        /* AIM A NEW CHAT AT A SAVED LOOP — the same handover as `composeWorkflow` above, for the other kind of
+         * design: the host opens a session with the composer's loop badge set, so the next message the user
+         * types becomes the loop's GOAL and Send starts it running.
+         *
+         * It is a separate call rather than a flag on that one because the two badges are separate picks that
+         * cannot both be armed, and a single "compose with this id" would have had to guess which kind an id
+         * was. A loop id, not a running loop's — nothing has started, and nothing is spent until the send.
+         */
+        composeLoop(loopId: string): void;
+    };
+    /* WHICH MODEL A RUN THIS EXTENSION STARTS WILL SPEND, the way `terminal` is the shell's one terminal panel:
+     * the extension names the choice it is holding, the host owns the picker.
+     *
+     * It is an API rather than a kit component because the picker is not a widget — it is a live read of every
+     * connected provider's catalog, which credentials the sandbox actually holds, and what each model can do.
+     * An extension that rendered its own control could only ever offer a worse list: the acceptance view's did,
+     * fetching one provider's models behind a second dropdown for the provider itself, and so it happily
+     * offered models the sandbox had no credential for — a run that fails on a credential error minutes later.
+     *
+     * IT COVERS THE WHOLE CHOICE — provider, account, harness, model — because covering three quarters of it is
+     * what produced the copy this API exists to prevent. The automations form asked all four questions, found an
+     * API that answered three, and hand-rolled ROWS OF CHIPS for every one of them to keep its own fields
+     * consistent with each other: a static provider list that offered providers the sandbox had no credential for
+     * and could not offer a model endpoint or an ACP agent at all, and a model row eleven chips wide that grew
+     * with every release. Partial coverage does not buy partial reuse; it buys none. */
+    readonly models: {
+        // What a run opens on when nobody has chosen: the sandbox's Agent-runs model (Sandbox ▸ Agent ▸ Models),
+        // falling back to whatever the owner's own chat is set to. Reactive when read inside a computed.
+        agentRun(): PickedModel;
+        /* NAME A SELECTION THE EXTENSION ALREADY HOLDS — a pin read back from disk, which arrives as bare ids and
+         * has to be rendered before anyone opens the picker. This is what keeps `label` honest for the surfaces
+         * that SAVE a choice rather than spend it immediately: without it every one of them would keep a catalog
+         * to pretty-print its own stored ids, which is the duplication this API exists to end, and it would go
+         * stale the day a provider renames a model or the owner disconnects an account.
+         *
+         * Reactive when read inside a computed — a model that lands in the catalog, or an account that stops being
+         * connected, changes what a stored pin should say about itself. */
+        describe(selection: {
+            readonly provider: string;
+            readonly model: string;
+            readonly account?: string | undefined;
+            readonly harness?: string | undefined;
+        }): PickedModel;
+        /* Open the picker over `anchor` — a popover on desktop, a sheet on mobile — starting on the selection the
+         * caller is holding. Resolves with the pick, or undefined if it was dismissed. A second call supersedes
+         * the first, resolving it as a dismissal.
+         *
+         * EVERY ROW SETTLES IT, including an account and a harness row: each click is one complete answer, so a
+         * caller never has to reconcile a half-changed selection, and the picker never has to hold state that
+         * disagrees with what the caller is showing. Picking a model under a DIFFERENT provider clears the
+         * account with it — an account id is one provider's store key, so carrying it across would pin the run to
+         * an account that provider does not have. */
+        pick(options: {
+            readonly anchor: HTMLElement;
+            readonly provider: string;
+            readonly model: string;
+            readonly account?: string | undefined;
+            readonly harness?: string | undefined;
+        }): Promise<PickedModel | undefined>;
     };
     // Navigate the shell to an app path (e.g. "/capabilities", "/ext/<view>/<key>").
     readonly navigate: (path: string) => void;

package/src/diff.ts

@@ -0,0 +1,59 @@
+/* WHAT AN EXTENSION HANDS THE HOST TO OPEN A DIFF — the argument to `api.workspace.openDiff`.
+ *
+ * A diff belongs in the editor area beside the files it is about, in the same tab strip as everything else the
+ * user has open. That strip is the host's, so an extension that has computed a before/after pair has nowhere to
+ * put it: a view renders inside its own frame, and a document provider inside its own tab. This is the way out,
+ * and it is the whole shape of the contribution — the extension says what changed, the host owns the tab, the
+ * viewer, the close orchestration and the dirty-buffer bookkeeping.
+ *
+ * It lives in the PUBLIC api package rather than in the app because the app is downstream of it: the workspace's
+ * own review surfaces build the identical payload, and having two spellings of it is how the two would drift. */
+
+// Git's vocabulary for what happened to a file. "conflicted" is git's unmerged state (`U`) and is not a kind of
+// modification — there is no stage 0 for such a path, so nothing a commit could record. The host renders each of
+// these as its own letter and colour.
+export type ChangeStatus = "added" | "modified" | "deleted" | "renamed" | "type-changed" | "conflicted";
+
+/* A binary diff ships no text, so its two sides ride the payload as daemon URLs its BYTES are fetched from
+ * rather than as content. An absent side means that side does not exist — an added file has no before, a deleted
+ * one no after — and the viewer then gives the side that does exist the whole pane instead of drawing an empty
+ * half beside it. */
+export interface DiffRawSides {
+    readonly beforeRaw?: string;
+    readonly afterRaw?: string;
+}
+
+export interface DiffPayload extends DiffRawSides {
+    /* The diff SOURCE's identity — a commit sha, a snapshot id, `working:<repo>`. Together with `scope` and
+     * `path` it is the tab's identity, so re-opening the same file at the same commit focuses the tab that is
+     * already open rather than stacking a second copy of it. Pick something stable and collision-free; prefixing
+     * with the extension's own id is the safe habit. */
+    readonly key: string;
+    // Which repo (or snapshot scope) the path is relative to — the other half of the tab identity.
+    readonly scope: string;
+    // The tab's label. Short: the strip is narrow, and "file.ts @ a1b2c3d" reads better than a full path.
+    readonly label: string;
+    readonly status: ChangeStatus;
+    readonly path: string;
+    // The two sides as text. Absent where the side does not exist, or where the content is binary/oversized —
+    // `binary` and `truncated` are what the viewer renders instead of an empty pane.
+    readonly before?: string;
+    readonly after?: string;
+    readonly binary?: boolean;
+    readonly truncated?: boolean;
+    // What the row that opened this diff already knew about its size, carried onto the tab's toolbar. Absent
+    // where the source has no numstat to give (a binary file, a change list without line counts) — the toolbar
+    // then renders nothing rather than a zero.
+    readonly additions?: number;
+    readonly deletions?: number;
+    /* THE CONTENT IS STILL COMING — open the tab now and fill it in when it lands (`workspace.fillDiff`).
+     *
+     * Reading a file the source has to compute or fetch is a wait, and a wait that has nowhere to be drawn gets
+     * drawn on the click instead: the row is clicked, nothing on screen changes, and the reader clicks it again.
+     * Everything the tab needs to exist — its identity, its label, the status letter and the line counts — is
+     * known before the content is, so the tab opens on the click and the panes fill underneath it.
+     *
+     * Absent means the payload IS the content, which is what an extension handing over an already-computed
+     * before/after pair should send. */
+    readonly pending?: boolean;
+}

package/src/engines.ts

@@ -0,0 +1,31 @@
+// Minimal matcher for a manifest's `engines.intentic` range against the host's extension API version: an exact
+// version ("0.1.0") or a caret range ("^0.1", "^1", "^1.2.3"). Caret follows semver — same major at or above
+// the floor, and while the major is 0 the minor is breaking too. Anything unparseable fails closed: the loader
+// reports the extension incompatible rather than activating on a guess.
+
+const parse = (value: string): [number, number, number] | undefined => {
+    const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(value.trim());
+    if (match === null) {
+        return undefined;
+    }
+    return [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)];
+};
+
+export const satisfiesEngines = (range: string, version: string): boolean => {
+    const host = parse(version);
+    const caret = range.trim().startsWith(`^`);
+    const floor = parse(caret ? range.trim().slice(1) : range);
+    if (host === undefined || floor === undefined) {
+        return false;
+    }
+    if (!caret) {
+        return host[0] === floor[0] && host[1] === floor[1] && host[2] === floor[2];
+    }
+    if (host[0] !== floor[0] || (floor[0] === 0 && host[1] !== floor[1])) {
+        return false;
+    }
+    if (host[1] !== floor[1]) {
+        return host[1] > floor[1];
+    }
+    return host[2] >= floor[2];
+};

package/src/facts.ts

@@ -26,6 +26,12 @@ export interface RepoFacts {
     // Whether the repo describes its features as user stories (a docs/user-stories directory) — the one fact
     // here that is language-agnostic, and the evidence an acceptance-testing surface activates on.
     readonly userStories: boolean;
+    /* Whether the repo carries architecture documentation (a docs/architecture directory).
+     *
+     * Here so that a surface which READS documentation can tell, without asking the file routes, which repos
+     * have any. The alternative was a read per repo on a poll — an answer the daemon already has from the same
+     * one-pass scan that produces every other fact on this interface. */
+    readonly docs: boolean;
 }
 
 // One connected capability's secret-free echo — `kind` is an open string: new kinds appear without an API bump,

package/src/host.ts

@@ -0,0 +1,29 @@
+import type { IntenticApi } from "./api.js";
+
+/* THE AMBIENT HOST HANDLE, one slot per extension. `activate(api)` binds it once, before any view renders, so
+ * the extension's composables reach the authenticated daemon transport, cache scoping and workspace facts
+ * through `host()` — the way `vscode.*` is ambient to a VSCode extension. Not app internals: everything flows
+ * through the public IntenticApi.
+ *
+ * A FACTORY rather than a module-level slot here, and that is the whole reason this lives in the API package
+ * instead of being one shared `host()`. The web shell publishes ONE instance of this module to every bundle
+ * (extension-host/hostModules.ts), so a slot held at module scope would be a single global that the last
+ * extension to activate silently takes over. Each extension calls this once and keeps its own closure:
+ *
+ *     export const { bindHost, host } = hostSlot(`ext-activity`);
+ *
+ * The names come back already spelled the way call sites use them, so nothing downstream renames anything. */
+export const hostSlot = (extension: string): { bindHost: (api: IntenticApi) => void; host: () => IntenticApi } => {
+    let current: IntenticApi | undefined;
+    return {
+        bindHost: (api) => {
+            current = api;
+        },
+        host: () => {
+            if (current === undefined) {
+                throw new Error(`${extension}: host() called before activate()`);
+            }
+            return current;
+        },
+    };
+};

package/src/index.ts

@@ -1,7 +1,9 @@
 export * from "./api.js";
+export * from "./diff.js";
+export * from "./engines.js";
 export * from "./facts.js";
-export * from "./manifest.js";
-export * from "./permissions.js";
+export * from "./host.js";
 export * from "./route.js";
+export * from "./server.js";
 export * from "./stream.js";
 export * from "./version.js";

package/src/server.ts

@@ -0,0 +1,65 @@
+/* THE SERVER HALF an extension programs against — the daemon-side twin of IntenticApi (api.ts).
+ *
+ * A manifest `server` bundle exports `activateServer(api, context)`, and the daemon's BACKEND HOST — one
+ * separate supervised node process shared by every enabled extension with a backend — imports the bundle and
+ * calls it. A separate process rather than the daemon itself because loaded code can never be unloaded: the
+ * off switch, an upgrade to a new sha and a live-edited workspace extension all require the process holding
+ * the old code to die, and that process must never be the daemon (chat, terminals and file sync live there).
+ * A shared process rather than one per extension because the trust model is full trust (install is owner-only
+ * and sha-pinned) — isolation between extensions would buy robustness nobody is billed for.
+ *
+ * Full trust is also why this surface is deliberately small. The backend runs in the sandbox container as the
+ * same user the daemon does, so the workspace is reachable with plain `node:fs` — the api hands over PATHS,
+ * not a file service. What it does mediate is the two things a path cannot carry: the extension's route
+ * namespace (mount), and its reach into the daemon's own routes (daemon.*, gated by the manifest's
+ * `permissions.daemon` — the daemon refuses undeclared routes, same grammar and same honesty rule as the UI
+ * half's `permissions.sandbox`). */
+
+// One request into this extension's namespace. The host strips the `/x/<id>` prefix before dispatch, so the
+// handler sees the extension's OWN paths — the same paths its contract declares and its UI half calls.
+// `undefined` means "not mine": the host answers 404 without the extension having to speak HTTP for it.
+export type BackendRouteHandler = (request: Request) => Promise<Response | undefined>;
+
+export interface ExtensionServerApi {
+    // The host's @intentic/extension-api version — what `engines.intentic` was checked against.
+    readonly apiVersion: string;
+    // The workspace root (absolute). The backend reads and writes under it with node's own fs — full trust
+    // means no file service in between. Durable state belongs in workspace files (the same rule the UI half
+    // lives by): it survives restarts, is shared across browsers, and the agent editing it out-of-band is the
+    // product.
+    readonly workspaceRoot: string;
+    // This extension's own checkout (absolute) — where its bundled assets sit.
+    readonly extensionDir: string;
+    // A line in the daemon's log, attributed to this extension.
+    readonly log: (message: string) => void;
+    readonly routes: {
+        /* Serve this extension's route namespace. The daemon proxies /x/<id>/* here — through its ordinary
+         * auth (an owner's browser, a member at the route's role floor), so a backend never sees an
+         * unauthenticated request and never sees a credential. One handler per extension: the extension owns
+         * its whole namespace, and how it routes inside it (an oRPC handler over its own contract, a plain
+         * switch) is its own business. A second mount replaces the first. */
+        mount(handler: BackendRouteHandler): void;
+    };
+    /* The authenticated transport to the daemon's own routes — the backend's `api.sandbox`. Auth is a minted
+     * per-extension token injected here; the daemon's gate checks every call against the manifest's
+     * `permissions.daemon` allowlist, so a backend's reach into the core is declared, reviewable and refusable
+     * exactly like the UI half's. The extension's own namespace needs no declaration — but there is also no
+     * reason to dial yourself over HTTP. */
+    readonly daemon: {
+        request(path: string, init?: RequestInit): Promise<Response>;
+        json<T>(path: string, init?: RequestInit): Promise<T>;
+    };
+}
+
+export interface ExtensionServerContext {
+    // The extension's routing id — its /x/<id> namespace segment (the capability entry id for a git-installed
+    // extension, publisher.name otherwise; the same id the UI half sees as ExtensionSummary.id).
+    readonly extensionId: string;
+}
+
+// The shape of the manifest `server` bundle's default export (or its named exports): `activateServer` runs
+// once per backend-host start, after the engines check. There is no deactivate — retirement IS the host
+// process ending, which is the one teardown that cannot leak.
+export interface ExtensionServerModule {
+    activateServer(api: ExtensionServerApi, context: ExtensionServerContext): void | Promise<void>;
+}