@nimbalyst/extension-sdk 0.5.0 → 0.7.0

package/dist/gitOperationLog.js

@@ -0,0 +1,88 @@
+/**
+ * Wire contract and pure selectors for the host's Git operation journal.
+ *
+ * The journal lives in the Electron main process and is published over two host
+ * channels: `git:operation-log:get` (hydration) and `git:operation-log-changed`
+ * (live upsert/clear). Both the Git extension's Output tab and Nimbalyst's own
+ * menu-bar indicator project the same journal, so the merge and "what is running
+ * right now" rules have to agree exactly -- two surfaces disagreeing about
+ * whether a push is still in flight is the bug this module exists to prevent.
+ *
+ * Everything here is pure: no React, no IPC, no host runtime.
+ */
+/**
+ * Window CustomEvent the host dispatches when the user asks to see Git activity
+ * detail (for example from the menu-bar indicator's running-command row).
+ *
+ * The Git panel owns which tab is showing, and that state is private to the
+ * extension bundle. Rather than let the host reach into it, the host states the
+ * intent and the panel decides how to honour it. `detail.workspacePath` lets a
+ * panel bound to a different workspace ignore the request.
+ */
+export const GIT_SHOW_OUTPUT_REQUEST_EVENT = 'nimbalyst:git-show-output';
+function toMillis(timestamp) {
+    return typeof timestamp === 'number' ? timestamp : timestamp.getTime();
+}
+/**
+ * Fill in metadata that predates the field. A journal written before agent
+ * activity existed only ever recorded app-owned direct `git` invocations, so
+ * that is what an absent `source`/`executor` means -- resolved here at the
+ * projection boundary rather than by rewriting the persisted journal.
+ */
+export function normalizeGitOperationEntry(entry) {
+    return {
+        ...entry,
+        source: entry.source ?? 'nimbalyst',
+        executor: entry.executor ?? 'git',
+    };
+}
+/**
+ * Fold incoming entries into the current list, newest write per id wins.
+ *
+ * `updatedAt` is the tiebreak rather than arrival order because hydration and
+ * the live subscription race: a `git:operation-log:get` response can land after
+ * upserts it predates, and applying it blindly would rewind a finished
+ * operation back to `running`.
+ */
+export function mergeGitOperationEntries(current, incoming) {
+    const byId = new Map(current.map((entry) => [entry.id, entry]));
+    for (const entry of incoming) {
+        const existing = byId.get(entry.id);
+        if (!existing || entry.updatedAt >= existing.updatedAt) {
+            byId.set(entry.id, entry);
+        }
+    }
+    return Array.from(byId.values()).sort((a, b) => toMillis(a.timestamp) - toMillis(b.timestamp));
+}
+/** Every entry still in flight, oldest first. */
+export function selectRunningGitOperations(entries) {
+    return entries.filter((entry) => entry.status === 'running');
+}
+/**
+ * The entry a single-line indicator should name. Newest start wins: when an
+ * agent kicks off a fetch while a push is already running, the thing the user
+ * just caused is the more informative label.
+ */
+export function selectLatestRunningGitOperation(entries) {
+    let latest;
+    for (const entry of entries) {
+        if (entry.status !== 'running')
+            continue;
+        if (!latest || toMillis(entry.timestamp) >= toMillis(latest.timestamp)) {
+            latest = entry;
+        }
+    }
+    return latest;
+}
+/** The most recently updated entry that has already settled, if any. */
+export function selectLatestTerminalGitOperation(entries) {
+    let latest;
+    for (const entry of entries) {
+        if (entry.status === 'running')
+            continue;
+        if (!latest || entry.updatedAt >= latest.updatedAt) {
+            latest = entry;
+        }
+    }
+    return latest;
+}

package/dist/index.d.ts

@@ -38,4 +38,5 @@ export { buildFileDirectoryTree, getFileDirectoryPaths, getFilePathBasename, get
 export { validateExtensionBundle, printValidationResult, type ValidationResult, } from './validate.js';
 export { validateBackendModules, assertBackendModulesValid, effectiveModulePermissions, validateAgentProviders, assertAgentProvidersValid, extractBackendModuleIds, MAX_AGENT_PROVIDERS_PER_EXTENSION, type BackendModuleValidationIssue, type AgentProviderValidationIssue, } from './manifestValidation.js';
 export type { AgentProtocol, ProtocolEvent, ProtocolMessage, ProtocolSession, SessionOptions, ProtocolEventType, ToolResult as ProtocolToolResult, MCPServerConfig, RawProtocolSession, AgentProtocolHost, PermissionMode, McpToolDefinition, } from './agents/index.js';
+export { screenshotService } from '@nimbalyst/runtime';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC;AAGxB,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,SAAS,GACf,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,EACjC,KAAK,0BAA0B,GAChC,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,8BAA8B,EAC9B,6CAA6C,EAC7C,yBAAyB,EACzB,KAAK,+BAA+B,GACrC,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,aAAa,EACb,YAAY,EACZ,KAAK,aAAa,GACnB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,eAAe,EACf,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAIrD,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,2BAA2B,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,GACjC,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGhE,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,4BAA4B,EAC5B,iBAAiB,EACjB,KAAK,iBAAiB,GACvB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,EACvB,iCAAiC,EACjC,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,GAClC,MAAM,yBAAyB,CAAC;AAYjC,YAAY,EACV,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,UAAU,IAAI,kBAAkB,EAChC,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC;AAGxB,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,SAAS,GACf,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,EACjC,KAAK,0BAA0B,GAChC,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,8BAA8B,EAC9B,6CAA6C,EAC7C,yBAAyB,EACzB,KAAK,+BAA+B,GACrC,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,aAAa,EACb,YAAY,EACZ,KAAK,aAAa,GACnB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,eAAe,EACf,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAIrD,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,2BAA2B,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,GACjC,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGhE,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,4BAA4B,EAC5B,iBAAiB,EACjB,KAAK,iBAAiB,GACvB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,EACvB,iCAAiC,EACjC,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,GAClC,MAAM,yBAAyB,CAAC;AAYjC,YAAY,EACV,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,UAAU,IAAI,kBAAkB,EAChC,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -47,3 +47,5 @@ export { buildFileDirectoryTree, getFileDirectoryPaths, getFilePathBasename, get
 // Re-export validation
 export { validateExtensionBundle, printValidationResult, } from './validate.js';
 export { validateBackendModules, assertBackendModulesValid, effectiveModulePermissions, validateAgentProviders, assertAgentProvidersValid, extractBackendModuleIds, MAX_AGENT_PROVIDERS_PER_EXTENSION, } from './manifestValidation.js';
+// Host-owned native screenshots for every built-in and extension editor.
+export { screenshotService } from '@nimbalyst/runtime';

package/dist/manifestValidation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifestValidation.d.ts","sourceRoot":"","sources":["../src/manifestValidation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAGV,qBAAqB,EACtB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;GAQG;AACH,eAAO,MAAM,iCAAiC,IAAI,CAAC;AAuCnD,MAAM,WAAW,4BAA4B;IAC3C,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,cAAc,EAAE,OAAO,GACtB,4BAA4B,EAAE,CAoKhC;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,OAAO,GACtB,IAAI,CAYN;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,GACX,qBAAqB,EAAE,CAazB;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAW5E;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,sBAAsB,CACpC,gBAAgB,EAAE,OAAO,EACzB,cAAc,EAAE,OAAO,GACtB,4BAA4B,EAAE,CAgMhC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,OAAO,EACzB,cAAc,EAAE,OAAO,GACtB,IAAI,CAYN"}
+{"version":3,"file":"manifestValidation.d.ts","sourceRoot":"","sources":["../src/manifestValidation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAGV,qBAAqB,EACtB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;GAQG;AACH,eAAO,MAAM,iCAAiC,IAAI,CAAC;AAwCnD,MAAM,WAAW,4BAA4B;IAC3C,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,cAAc,EAAE,OAAO,GACtB,4BAA4B,EAAE,CAoKhC;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,OAAO,GACtB,IAAI,CAYN;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,GACX,qBAAqB,EAAE,CAazB;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAW5E;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,sBAAsB,CACpC,gBAAgB,EAAE,OAAO,EACzB,cAAc,EAAE,OAAO,GACtB,4BAA4B,EAAE,CAgMhC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,OAAO,EACzB,cAAc,EAAE,OAAO,GACtB,IAAI,CAYN"}

package/dist/manifestValidation.js

@@ -30,6 +30,7 @@ const KNOWN_PERMISSION_IDS = [
     'nimbalyst-database-write',
     'secrets-read',
     'mcp-server-register',
+    'ai-sessions',
 ];
 /**
  * Permission ids that used to be in the catalog but never enforced anything

package/dist/types/backendPanels.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Backend-module panel API: `ctx.services.panels`.
+ *
+ * Lets a backend module update its own panels' gutter buttons while the panel
+ * is not mounted (a fullscreen panel unmounts when the user leaves it), so an
+ * event the module sees in the background (a new flag, a budget crossing)
+ * reaches the gutter without the user reopening the panel.
+ *
+ * No permission is required: the only thing a module can change is the badge
+ * on a panel its own manifest declares.
+ */
+export type PanelGutterBadgeTone = 'default' | 'warning';
+export interface BackendPanelsService {
+    /**
+     * Show a badge on one of this extension's panel gutter buttons, in the
+     * windows showing this module's workspace. Same values as the panel's own
+     * `host.setGutterBadge`: `null` clears, `0` shows a dot, a positive number
+     * shows the count. Whichever of the two writes last wins.
+     *
+     * `panelId` is the id from this extension's manifest `contributions.panels`
+     * (not prefixed with the extension id). Rejects for any other id.
+     */
+    setGutterBadge(panelId: string, value: number | null, options?: {
+        tone?: PanelGutterBadgeTone;
+    }): Promise<void>;
+}
+//# sourceMappingURL=backendPanels.d.ts.map

package/dist/types/backendPanels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backendPanels.d.ts","sourceRoot":"","sources":["../../src/types/backendPanels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,SAAS,CAAC;AAEzD,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,oBAAoB,CAAA;KAAE,GACxC,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}

package/dist/types/backendPanels.js

@@ -0,0 +1,12 @@
+/**
+ * Backend-module panel API: `ctx.services.panels`.
+ *
+ * Lets a backend module update its own panels' gutter buttons while the panel
+ * is not mounted (a fullscreen panel unmounts when the user leaves it), so an
+ * event the module sees in the background (a new flag, a budget crossing)
+ * reaches the gutter without the user reopening the panel.
+ *
+ * No permission is required: the only thing a module can change is the badge
+ * on a panel its own manifest declares.
+ */
+export {};

package/dist/types/backendSessions.d.ts

@@ -0,0 +1,262 @@
+/**
+ * Backend-module session API and tool call context.
+ *
+ * These types describe what a privileged backend module (see
+ * `BackendModuleContribution` in `./permissions`) receives from the host when
+ * it drives AI agent sessions:
+ *
+ *   - `BackendToolCallContext`: passed to a backend MCP tool handler as
+ *     `ctx.call`, so the handler knows which session called it.
+ *   - `BackendSessionsService`: `ctx.services.sessions`, gated by the
+ *     `ai-sessions` permission. Every call is scoped by the host to the
+ *     calling module's extension and bound workspace; a module can only read
+ *     or drive sessions its own extension owns.
+ *   - `BackendMcpToolDefinition`: the shape passed to
+ *     `ctx.services.registerMcpTools`, including `panelOnly`.
+ *
+ * Ownership lives in the session row's metadata (`sessionOwner`), written at
+ * creation. Sessions an owned session spawns (`spawn_session`, `create_session`,
+ * a child created under it in the UI) inherit the owner, but not the directive.
+ */
+/**
+ * Which extension owns a session, and under what key. `key` is the owner's own
+ * grouping id (for example a member slug); the host never interprets it.
+ */
+export interface SessionOwner {
+    extensionId: string;
+    key: string;
+    /**
+     * When true, an owned child's settle does NOT queue a `[Child Session
+     * Update]` prompt on the session that spawned it and does not re-drive that
+     * session. The owner gets the settle through `sessions.onSettled` instead.
+     */
+    routeChildUpdatesToOwner?: boolean;
+}
+/**
+ * Identity of the caller of a backend MCP tool. Present on `ctx.call` when the
+ * method was invoked as a tool; absent for plain RPC calls.
+ */
+export interface BackendToolCallContext {
+    /** Calling AI session, or null when the call did not come from a session (panel, voice). */
+    sessionId: string | null;
+    /** Workspace the module is bound to. */
+    workspacePath: string;
+    /**
+     * The calling session's owner, populated ONLY when that session is owned by
+     * this same extension. Null for unowned sessions and for sessions another
+     * extension owns.
+     */
+    sessionOwner: SessionOwner | null;
+    /** Where the call came from. */
+    caller: 'agent' | 'panel' | 'voice';
+}
+/**
+ * One tool passed to `ctx.services.registerMcpTools`. The advertised name is
+ * namespaced by the host as `<extension short name>.<name>`; `name` is also the
+ * backend method the host invokes.
+ */
+export interface BackendMcpToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    /** Also expose the tool to the voice agent. Ignored when `panelOnly` is set. */
+    voiceAgent?: boolean;
+    scope?: 'global' | 'editor';
+    /**
+     * Callable only from this extension's own renderer via `callBackendTool`.
+     * The tool is not listed to agents or the voice agent, and an agent call to
+     * it is rejected.
+     */
+    panelOnly?: boolean;
+    /**
+     * Which agent sessions see the tool. `'all'` (default) lists it to every
+     * session in the workspace. `'owned-sessions'` lists it only to sessions this
+     * extension owns (`metadata.sessionOwner.extensionId`, inherited by spawned
+     * descendants); any other session's call is rejected as an unknown tool, and
+     * the voice agent never sees it. Use it for tools that only make sense inside
+     * the extension's own sessions, so they cost other sessions no context.
+     */
+    audience?: 'all' | 'owned-sessions';
+}
+/** Session lifecycle states as stored by the host. */
+export type OwnedSessionStatus = 'idle' | 'running' | 'waiting_for_input' | 'error' | 'interrupted';
+export interface CreateOwnedSessionOptions {
+    /** Owner key recorded in `sessionOwner.key`. The extension id is supplied by the host. */
+    ownerKey: string;
+    /** Session title. The session is treated as named, so it does not rename itself. */
+    name: string;
+    /** Agent provider id, e.g. `claude-code`, `openai-codex`. */
+    provider: string;
+    /** Model id, either `provider:model` or a bare model for `provider`. */
+    model: string;
+    /** Optional first prompt. Queued and dispatched immediately when present. */
+    prompt?: string;
+    /** Reasoning effort (`low` | `medium` | `high` | `xhigh` | `max`), clamped to the model. */
+    effortLevel?: string;
+    /**
+     * Text appended to the session's system prompt, frozen at the first turn.
+     * `create` rejects it for providers that do not apply it: the chat
+     * providers (`claude`, `openai`, `lmstudio`), `claude-code-cli`, and
+     * extension-contributed agent providers.
+     */
+    directive?: string;
+    /** Owned workstream container to file the session under (see `createWorkstream`). */
+    workstreamId?: string;
+    /**
+     * Owned session that logically spawned this one. Its settle routing follows
+     * `routeChildUpdatesToOwner`.
+     */
+    createdBySessionId?: string;
+    /** Initial owner metadata bag. Only this extension can change it later. */
+    ownerMetadata?: Record<string, unknown>;
+    /** See `SessionOwner.routeChildUpdatesToOwner`. Inherited by descendants. */
+    routeChildUpdatesToOwner?: boolean;
+}
+export interface CreateOwnedWorkstreamOptions {
+    ownerKey: string;
+    name: string;
+    /** Provider recorded on the container row. Defaults to `claude-code`. */
+    provider?: string;
+    ownerMetadata?: Record<string, unknown>;
+}
+export interface OwnedSessionStatusResult {
+    sessionId: string;
+    status: OwnedSessionStatus;
+    title: string;
+    lastActivity: number | null;
+    updatedAt: number | null;
+    /** The session has an unanswered durable prompt (question, plan approval, permission). */
+    hasPendingPrompt: boolean;
+    /** Queued prompts not yet delivered. */
+    queuedPromptCount: number;
+}
+export interface OwnedSessionContextFill {
+    /** Tokens currently in the context window. */
+    tokens: number;
+    contextWindow: number;
+}
+export interface OwnedSessionResult {
+    sessionId: string;
+    status: OwnedSessionStatus;
+    /** Text of the last assistant turn, or null if the session has not answered. */
+    lastResponse: string | null;
+    errorMessage: string | null;
+    /** Current context fill as last reported by the provider; null before the first report. */
+    contextFill: OwnedSessionContextFill | null;
+    pendingPrompt: {
+        promptId: string;
+        promptType: string;
+    } | null;
+    editedFiles: string[];
+}
+export interface OwnedSessionSummary {
+    sessionId: string;
+    key: string;
+    sessionType: 'session' | 'workstream' | string;
+    title: string;
+    /** Owned workstream container this session is filed under, if any. */
+    workstreamId: string | null;
+    /** Session that spawned this one, if any. */
+    createdBySessionId: string | null;
+    status: OwnedSessionStatus;
+    hasPendingPrompt: boolean;
+    queuedPromptCount: number;
+    createdAt: number;
+    updatedAt: number;
+    ownerMetadata: Record<string, unknown>;
+}
+/**
+ * Token usage for one session over its whole lifetime, as persisted by the
+ * host (the same counters the session's usage display reads). `costUSD` is
+ * 0 when the provider does not report cost.
+ *
+ * The four token counters are disjoint: `inputTokens` is uncached input only,
+ * and cache reads/writes are counted separately (0 for providers that report
+ * no cache split, and for sessions recorded before the host stored them).
+ * `totalTokens` keeps its historical meaning, input + output without cache;
+ * budget over `allTokens` to count everything the session consumed.
+ */
+export interface OwnedSessionUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    costUSD: number;
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+    /** inputTokens + outputTokens + cacheReadInputTokens + cacheCreationInputTokens. */
+    allTokens: number;
+}
+/**
+ * Usage is session-granular: a session counts in full when its last activity
+ * is at or after `since`. The host keeps no per-turn usage history. For an
+ * exact time window, record `OwnedSessionSettledEvent.tokenUsage` deltas in
+ * the module's own storage.
+ */
+export interface OwnedUsageReport {
+    since: number;
+    totals: OwnedSessionUsage;
+    sessions: Array<OwnedSessionUsage & {
+        sessionId: string;
+        key: string;
+        lastActivity: number;
+    }>;
+}
+export type OwnedSessionSettleOutcome = 'completed' | 'error' | 'waiting' | 'interrupted';
+/**
+ * Delivered to `onSettled` handlers. `completed` fires once the session's
+ * prompt queue is empty, not between queued prompts.
+ */
+export interface OwnedSessionSettledEvent {
+    sessionId: string;
+    ownerKey: string;
+    outcome: OwnedSessionSettleOutcome;
+    createdBySessionId: string | null;
+    workstreamId: string | null;
+    at: number;
+    /** The session's lifetime usage at settle time; diff consecutive events for per-turn usage. */
+    tokenUsage: OwnedSessionUsage;
+}
+export interface NotifyUserOptions {
+    /** Owned session the notification is about; clicking it opens this session. */
+    sessionId: string;
+    title: string;
+    body: string;
+    /** `critical` also pushes to the user's phone. Defaults to `normal`. */
+    urgency?: 'low' | 'normal' | 'critical';
+}
+/**
+ * `ctx.services.sessions`. Requires the `ai-sessions` permission. Every method
+ * that takes a session id rejects sessions this extension does not own.
+ */
+export interface BackendSessionsService {
+    create(options: CreateOwnedSessionOptions): Promise<{
+        sessionId: string;
+        queuedPromptId: string | null;
+    }>;
+    createWorkstream(options: CreateOwnedWorkstreamOptions): Promise<{
+        workstreamId: string;
+    }>;
+    /** Queue a prompt; it is delivered when the session is idle. */
+    sendPrompt(sessionId: string, prompt: string): Promise<{
+        queuedPromptId: string;
+    }>;
+    getStatus(sessionId: string): Promise<OwnedSessionStatusResult>;
+    getResult(sessionId: string): Promise<OwnedSessionResult>;
+    /** Owned sessions in this workspace, optionally filtered to one owner key. Newest first. */
+    listOwned(options?: {
+        key?: string;
+    }): Promise<OwnedSessionSummary[]>;
+    /** Lifetime usage of owned sessions active at or after `since` (epoch ms). See `OwnedUsageReport`. */
+    getUsage(options: {
+        key?: string;
+        since: number;
+    }): Promise<OwnedUsageReport>;
+    /** Shallow-merge `patch` into the session's owner metadata bag. A `null` value deletes the key. */
+    updateOwnerMetadata(sessionId: string, patch: Record<string, unknown>): Promise<{
+        ownerMetadata: Record<string, unknown>;
+    }>;
+    notifyUser(options: NotifyUserOptions): Promise<void>;
+    /** Subscribe to settle events for sessions this extension owns in this workspace. Returns an unsubscribe. */
+    onSettled(handler: (event: OwnedSessionSettledEvent) => void): () => void;
+}
+//# sourceMappingURL=backendSessions.d.ts.map

package/dist/types/backendSessions.d.ts.map

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

package/dist/types/backendSessions.js

@@ -0,0 +1,21 @@
+/**
+ * Backend-module session API and tool call context.
+ *
+ * These types describe what a privileged backend module (see
+ * `BackendModuleContribution` in `./permissions`) receives from the host when
+ * it drives AI agent sessions:
+ *
+ *   - `BackendToolCallContext`: passed to a backend MCP tool handler as
+ *     `ctx.call`, so the handler knows which session called it.
+ *   - `BackendSessionsService`: `ctx.services.sessions`, gated by the
+ *     `ai-sessions` permission. Every call is scoped by the host to the
+ *     calling module's extension and bound workspace; a module can only read
+ *     or drive sessions its own extension owns.
+ *   - `BackendMcpToolDefinition`: the shape passed to
+ *     `ctx.services.registerMcpTools`, including `panelOnly`.
+ *
+ * Ownership lives in the session row's metadata (`sessionOwner`), written at
+ * creation. Sessions an owned session spawns (`spawn_session`, `create_session`,
+ * a child created under it in the UI) inherit the owner, but not the directive.
+ */
+export {};

package/dist/types/collab.d.ts

@@ -30,6 +30,7 @@
  * @see CollabContentAdapter -- the former name, kept as a deprecated alias.
  */
 import type { Doc } from 'yjs';
+import type { CommentAnchor } from './comments';
 export type CollabContentFileSource = string | Uint8Array;
 /**
  * Serializable description of a CollabContentAdapter that lets the HOST
@@ -52,6 +53,17 @@ export interface CollabCodecMigration {
     to: number;
     run(yDoc: Doc): void;
 }
+/**
+ * Structured-comment anchor support for headless hosts. Hosts invoke these
+ * reads against a detached, disposable Y.Doc snapshot rather than the live
+ * collaborative document, so an accidental mutation cannot alter or sync the
+ * real document. Codecs should still treat the snapshot as read-only.
+ */
+export interface CollabCommentAnchorCodec {
+    handles(anchor: CommentAnchor): boolean;
+    getState(snapshot: Doc, anchor: CommentAnchor): 'attached' | 'orphaned';
+    describe(snapshot: Doc, anchor: CommentAnchor): string;
+}
 /** @deprecated Renamed to {@link CollabCodecMigration}. */
 export type CollabContentAdapterMigration = CollabCodecMigration;
 export interface CollabCodec<TStructured = unknown> {
@@ -95,9 +107,26 @@ export interface CollabCodec<TStructured = unknown> {
      *  `applyStructuredPatch`. */
     toStructured?(yDoc: Doc): TStructured;
     /** Optional: write structured edits back. Paired with
-     *  `toStructured`. AI-write surface is gated on the presence of
-     *  both this and `toStructured`. */
+     *  `toStructured`. The PREFERRED AI-write surface: implementing
+     *  both lets an agent edit this document type structurally.
+     *
+     *  It is NOT a gate. When an adapter does not implement the pair,
+     *  an agent edit falls back to `exportToFile` -> text replacement
+     *  -> `applyFromFile`, so every adapter is AI-writable whether or
+     *  not it opted in. Two consequences an adapter author must know:
+     *
+     *   - `applyFromFile` is called with agent-authored content, not
+     *     just on-disk content, so it must be safe to call on a
+     *     populated Y.Doc (it already must be) AND must be able to
+     *     consume its own `exportToFile` output unchanged. That
+     *     round-trip is asserted for every registered adapter in
+     *     `codecOnlyHeadlessEdit.test.ts`.
+     *   - The fallback rewrites the whole document, so a concurrent
+     *     human edit can interleave. Implement the structured pair to
+     *     get minimal deltas instead. */
     applyStructuredPatch?(yDoc: Doc, patch: unknown): void;
+    /** Optional snapshot-isolated resolver for structured comment anchors. */
+    commentAnchors?: CollabCommentAnchorCodec;
     /** Optional: produce a snapshot for revision history. Defaults to
      *  `Y.encodeStateAsUpdateV2(yDoc)`. Override if you need a denser
      *  snapshot format. */

package/dist/types/collab.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collab.d.ts","sourceRoot":"","sources":["../../src/types/collab.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE/B,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,UAAU,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,uBAAuB,GAAG,2BAA2B,CAAC;AAElE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,CAAC;CACtB;AAED,2DAA2D;AAC3D,MAAM,MAAM,6BAA6B,GAAG,oBAAoB,CAAC;AAEjE,MAAM,WAAW,WAAW,CAAC,WAAW,GAAG,OAAO;IAChD,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IAErB;;qEAEiE;IACjE,cAAc,EAAE,MAAM,EAAE,CAAC;IAEzB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;oBAEgB;IAChB,aAAa,EAAE,MAAM,CAAC;IAEtB;;;yBAGqB;IACrB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAEpC;;oEAEgE;IAChE,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC;IAE5B;gEAC4D;IAC5D,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAE/D;;;;yCAIqC;IACrC,aAAa,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAEhE,gEAAgE;IAChE,YAAY,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,GAAG,UAAU,CAAC;IAE7C;qEACiE;IACjE,WAAW,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,CAAC;IAE/B;;kCAE8B;IAC9B,YAAY,CAAC,CAAC,IAAI,EAAE,GAAG,GAAG,WAAW,CAAC;IAEtC;;wCAEoC;IACpC,oBAAoB,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAEvD;;2BAEuB;IACvB,sBAAsB,CAAC,CAAC,IAAI,EAAE,GAAG,GAAG,UAAU,CAAC;IAE/C;0CACsC;IACtC,uBAAuB,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAE7D;;;qEAGiE;IACjE,sBAAsB,CAAC,EAAE,uBAAuB,CAAC;CAClD;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,CAAC,WAAW,GAAG,OAAO,IAAI,WAAW,CAAC,WAAW,CAAC,CAAC;AAEnF;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,sBAAsB,CAAC,KAAK,EAAE,WAAW,GAAG;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,CAAC;CACjE"}
+{"version":3,"file":"collab.d.ts","sourceRoot":"","sources":["../../src/types/collab.ts"],"names":[],"mappings":"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"}

package/dist/types/comments.d.ts

@@ -0,0 +1,104 @@
+/** Editor-neutral collaborative comment contracts exposed to extensions. */
+export type TextQuoteCommentAnchor = {
+    kind: 'text-quote';
+    exact: string;
+    prefix?: string;
+    suffix?: string;
+};
+export type EntityCommentAnchor = {
+    kind: 'entity';
+    entityType: string;
+    entityId: string;
+    field?: string;
+    labelSnapshot?: string;
+};
+export type CommentAnchor = TextQuoteCommentAnchor | EntityCommentAnchor;
+export type CollaborativeUserCommentActor = {
+    kind: 'user';
+    userId?: string;
+    displayName: string;
+};
+export type CollaborativeAgentCommentActor = {
+    kind: 'agent';
+    sessionId: string;
+    sessionName: string;
+    onBehalfOfUserId: string;
+    onBehalfOfDisplayName?: string;
+};
+export type CollaborativeCommentActor = CollaborativeUserCommentActor | CollaborativeAgentCommentActor;
+export interface CollaborativeComment {
+    readonly actor?: CollaborativeCommentActor;
+    readonly author: string;
+    readonly clientMutationId?: string;
+    readonly content: string;
+    readonly deleted: boolean;
+    readonly id: string;
+    readonly replyToCommentId?: string;
+    readonly timeStamp: number;
+    readonly type: 'comment';
+}
+export interface CollaborativeCommentThread {
+    readonly anchor?: CommentAnchor;
+    readonly comments: ReadonlyArray<CollaborativeComment>;
+    readonly id: string;
+    readonly quote: string;
+    readonly resolved: boolean;
+    readonly type: 'thread';
+}
+/** The immutable canonical view of the document's top-level comments array. */
+export type CollaborativeCommentsSnapshot = ReadonlyArray<CollaborativeComment | CollaborativeCommentThread>;
+export interface CommentCapabilities {
+    read: boolean;
+    comment: boolean;
+}
+export interface CommentMember {
+    userId: string;
+    name: string;
+    email?: string | null;
+    personalOrgId?: string | null;
+}
+export interface CreateCommentThreadInput {
+    anchor: CommentAnchor;
+    content: string;
+    clientMutationId: string;
+    mentionedUserIds?: string[];
+}
+export interface CreateCommentThreadResult {
+    comment: CollaborativeComment;
+    duplicate: boolean;
+    thread: CollaborativeCommentThread;
+}
+export interface ReplyToCommentInput {
+    threadId: string;
+    content: string;
+    clientMutationId: string;
+    mentionedUserIds?: string[];
+    replyToCommentId?: string;
+}
+export interface ReplyToCommentResult {
+    comment: CollaborativeComment;
+    duplicate: boolean;
+    threadId: string;
+}
+export interface MountedCommentAnchorAdapter {
+    handles(anchor: CommentAnchor): boolean;
+    getState(anchor: CommentAnchor): 'attached' | 'orphaned';
+    describe(anchor: CommentAnchor): string;
+    focus(anchor: CommentAnchor): boolean | Promise<boolean>;
+}
+export interface CollaborationCommentsService {
+    getSnapshot(): CollaborativeCommentsSnapshot;
+    subscribe(listener: () => void): () => void;
+    getCapabilities(): CommentCapabilities;
+    getMentionableMembers(): CommentMember[];
+    createThread(input: CreateCommentThreadInput): Promise<CreateCommentThreadResult>;
+    reply(input: ReplyToCommentInput): Promise<ReplyToCommentResult>;
+    setResolved(threadId: string, resolved: boolean): Promise<void>;
+    focusThread(threadId: string): Promise<boolean>;
+    openPanel(input?: {
+        threadId?: string;
+        anchor?: CommentAnchor;
+    }): void;
+    registerAnchorAdapter(adapter: MountedCommentAnchorAdapter): () => void;
+}
+//# sourceMappingURL=comments.d.ts.map

package/dist/types/comments.d.ts.map

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

package/dist/types/comments.js

@@ -0,0 +1,2 @@
+/** Editor-neutral collaborative comment contracts exposed to extensions. */
+export {};