@intentic/extension-api 1.248.0 → 1.249.0

package/src/server.ts

@@ -1,50 +1,27 @@
-/* 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`). */
+// Backend counterpart to `IntenticApi` (api.ts); a manifest `server` bundle's `activateServer` runs in a node process
+// shared by every enabled extension, separate from the daemon. Mediates only the extension's route namespace (mount)
+// and its reach into daemon routes (`daemon.*`, gated by `permissions.daemon`).
 
-// 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.
+// One request into this extension's `/x/<id>` namespace, prefix already stripped. Return `undefined` for "not mine":
+// the host answers 404.
 export type BackendRouteHandler = (request: Request) => Promise<Response | undefined>;
 
 export interface ExtensionServerApi {
-    // The host's @intentic/extension-api version, what `engines.intentic` was checked against.
+    // The host's @intentic/extension-api version, checked against `engines.intentic`.
     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.
+    // Absolute workspace root; the backend reads and writes it directly via node's `fs`, no file service in between.
     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. */
+        // Serves this extension's route namespace; the daemon proxies /x/<id>/* here through its ordinary auth. 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. */
+    // Authenticated transport to the daemon's own routes; every call is checked against the manifest's
+    // `permissions.daemon` allowlist.
     readonly daemon: {
         request(path: string, init?: RequestInit): Promise<Response>;
         json<T>(path: string, init?: RequestInit): Promise<T>;
@@ -52,14 +29,12 @@ export interface ExtensionServerApi {
 }
 
 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).
+    // This extension's routing id, its /x/<id> namespace segment.
     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.
+// Shape of the manifest `server` bundle's default (or named) export; `activateServer` runs once per backend-host start.
+// No deactivate: retirement is the host process ending.
 export interface ExtensionServerModule {
     activateServer(api: ExtensionServerApi, context: ExtensionServerContext): void | Promise<void>;
 }

package/src/stream.ts

@@ -1,15 +1,11 @@
-/* Reading a daemon SSE/ndjson stream, the transport half of `sandbox.request().body`. The daemon emits SSE
- * frames (blank-line separated, each a `data: <JSON>` line, an oRPC event-iterator failure as `event: error`),
- * so consuming a streamed apply/plan/provision means reframing + JSON-parsing. Pure (ReadableStream in, async
- * records out), no deps, extensions bundle it; the shim path never touches it. */
+// Reads a daemon SSE/ndjson stream: reframes blank-line-separated `data: <JSON>` frames and parses each. Pure
+// (ReadableStream in, async records out), no deps.
 
-// A silent daemon, one that accepts the stream then sends nothing and never closes, would park reader.read()
-// forever, hanging the consumer. A live daemon heartbeats (≤1s) over the stream, so no bytes for this long means
-// the connection is dead: cancel the reader and end the generator instead of waiting indefinitely.
+// A live daemon heartbeats over the stream at least this often; no bytes for this long means the connection is dead.
 const SSE_IDLE_MS = 120_000;
 
-// Yields each raw SSE frame (the text between blank-line separators), reassembling frames split across chunks.
-// Ends (cancelling the reader) if the daemon goes silent past SSE_IDLE_MS, so a half-open stream can't hang.
+// Yields each raw SSE frame, reassembling frames split across chunks; ends (cancelling the reader) after SSE_IDLE_MS of
+// silence.
 async function* sseFrames(body: ReadableStream<Uint8Array>): AsyncGenerator<string> {
     const reader = body.getReader();
     const decoder = new TextDecoder();
@@ -58,9 +54,8 @@ const dataOf = (frame: string): unknown => {
     }
 };
 
-// Reads a daemon stream as parsed ndjson records. An `event: error` frame is normalized to a
-// `{ kind: "error", message }` record so callers surface it and stop even when the daemon couldn't emit its
-// own error line; malformed frames are skipped.
+// Reads a daemon stream as parsed ndjson records. An `event: error` frame becomes a `{ kind: "error", message }`
+// record; malformed frames are skipped.
 export async function* readDaemonStream(body: ReadableStream<Uint8Array>): AsyncGenerator<Record<string, unknown>> {
     for await (const frame of sseFrames(body)) {
         const parsed = dataOf(frame);

package/src/surface.json

@@ -611,5 +611,89 @@
             "repos",
             "write"
         ]
+    },
+    "2.11.0": {
+        "manifest": [
+            "$schema",
+            "art",
+            "category",
+            "contributes",
+            "engines",
+            "entry",
+            "icon",
+            "logo",
+            "name",
+            "permissions",
+            "publisher",
+            "server",
+            "version"
+        ],
+        "contributes": [
+            "agent",
+            "automationTemplates",
+            "bin",
+            "capabilities",
+            "commands",
+            "documents",
+            "environment",
+            "files",
+            "listener",
+            "processes",
+            "settings",
+            "viewers",
+            "views"
+        ],
+        "api": [
+            "apiVersion",
+            "chat",
+            "commands",
+            "documents",
+            "href",
+            "models",
+            "navigate",
+            "processes",
+            "route",
+            "sandbox",
+            "settings",
+            "terminal",
+            "theme",
+            "viewers",
+            "views",
+            "workspace"
+        ],
+        "listener": ["automation", "events", "provider"],
+        "sandboxApi": ["fetch", "json", "key", "origin", "reachable", "request", "role", "rpc"],
+        "moduleExports": [
+            "extensionApiVersion",
+            "flattenQuery",
+            "hostSlot",
+            "mergeQuery",
+            "readDaemonStream",
+            "resetSandboxScope",
+            "sandboxLedger",
+            "sandboxPoll",
+            "sandboxRef",
+            "sandboxScopeGuard",
+            "sandboxValue",
+            "satisfiesEngines"
+        ],
+        "workspaceApi": [
+            "capabilities",
+            "file",
+            "fillDiff",
+            "onDidChange",
+            "onDidChangeFiles",
+            "onDidChangeRefs",
+            "openDiff",
+            "readJson",
+            "repos",
+            "write"
+        ],
+        "chatApi": [
+            "composeLoop",
+            "composeWorkflow",
+            "openAgent",
+            "openSession"
+        ]
     }
 }

package/src/version.ts

@@ -67,4 +67,9 @@
 // the slowest tile sat ten minutes behind the file it described. Additive, and the recorded surface grew a
 // `workspaceApi` member list with this release, the same grain `sandboxApi` got at 2.3.0 and for the same
 // reason: this is where the addition happened, and nothing could see it.
-export const extensionApiVersion = "2.10.0";
+// 2.11.0 adds `api.chat.openAgent`: open (or focus) the docked chat for a fleet agent by its id, the same
+// thing a card press on the agents board does. The agent's conversation appears in the chat panel rather
+// than navigating away from the current view. Two extensions were navigating to `/agents/<id>` on a plain
+// click, which left the view they were on; this is the call they should have had. The `chatApi` sub-surface
+// is recorded from this release on, for the same reason `workspaceApi` was recorded from 2.10.0.
+export const extensionApiVersion = "2.11.0";