@nimbalyst/extension-sdk 0.2.0 → 0.2.2

package/dist/agents/AgentProtocolHost.d.ts

@@ -0,0 +1,190 @@
+/**
+ * AgentProtocolHost
+ * -----------------
+ *
+ * Surface that the host (Nimbalyst) provides to an extension-owned
+ * `AgentProtocol` implementation at runtime. The protocol implementation
+ * lives in an extension's backend module and is brokered to the host by
+ * the privileged-host backend-module runtime; it must never reach for
+ * host internals directly.
+ *
+ * Identity fields are immutable for the lifetime of the host: they
+ * identify which extension contribution this protocol instance belongs
+ * to and which backend module is hosting it. Per-turn inputs (session
+ * id, workspace path, model, abort signal, permission mode, MCP
+ * servers, environment) are immutable for the lifetime of a single
+ * turn but may differ between turns on the same host instance.
+ *
+ * All async methods reject when the underlying broker call is rejected
+ * by the host (missing permission, unknown session, workspace
+ * mismatch, etc.) -- the protocol implementation is expected to
+ * surface those rejections as protocol-level errors rather than
+ * swallowing them.
+ *
+ * -------------------------------------------------------------------
+ * Q7 -- scope of this host (Phase-4 SDK proposal, resolved 2026-06-02)
+ * -------------------------------------------------------------------
+ *
+ * Per Q7 (Phase-4 SDK proposal, resolved 2026-06-02):
+ * emitEvent / requestPermission / askUserQuestion stay provider-private
+ * per the established upstream pattern (OpenAICodexProvider:1422-1491,
+ * claudeCode/askUserQuestion.ts:10, ProviderSessionManager.ts:49).
+ * Section 4.3's full facade is the agreed end-state, hoisted
+ * incrementally when each in-tree provider is next touched. Phase 4
+ * therefore ships the minimal 5-method host below; the missing
+ * methods are NOT a regression -- they live on the provider's own
+ * surface today and migrate behind a stable facade as each provider
+ * is reworked.
+ *
+ * See `docs/EXTENSION_ARCHITECTURE.md` and the Phase 4 SDK design doc
+ * (Section 4.3) for the full host contract.
+ */
+import type { MCPServerConfig } from './index';
+/**
+ * Permission posture the host has set for the current turn.
+ *
+ * - `ask`   -- prompt the user for every tool call that requires
+ *              consent.
+ * - `auto`  -- pre-approved tool calls run without prompting;
+ *              everything else still goes through the provider's own
+ *              permission path (see Q7 above).
+ * - `plan`  -- read-only / planning posture; the protocol
+ *              implementation MUST NOT invoke side-effecting tools
+ *              and SHOULD use this hint to bias the model toward
+ *              planning output.
+ *
+ * This is advisory metadata about the host's posture. The provider's
+ * own permission code (kept provider-private per Q7) is still the
+ * authoritative gate at tool-call time.
+ */
+export type PermissionMode = 'ask' | 'auto' | 'plan';
+/**
+ * MCP tool the protocol implementation wants to register with the
+ * host for this session. The host federates these into the
+ * session-wide tool registry and exposes them to the model alongside
+ * built-in tools.
+ */
+export interface McpToolDefinition {
+    /**
+     * Tool name as the model will see it (e.g.
+     * `mcp__antigravity__plan`).
+     */
+    name: string;
+    /**
+     * Short description for the model and for the consent prompt.
+     */
+    description: string;
+    /**
+     * JSON Schema for the tool's input. The host validates calls
+     * against this before invoking the handler.
+     */
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * Host surface passed to an extension's `AgentProtocol`
+ * implementation.
+ *
+ * Identity fields are constant; per-turn inputs are constant for the
+ * lifetime of a single turn. Methods may be invoked multiple times
+ * per turn (subject to the host's rate-limits and permission gates).
+ *
+ * Surface size is intentionally minimal -- see the Q7 note in the
+ * file header for why emitEvent / requestPermission /
+ * askUserQuestion are not on this interface.
+ */
+export interface AgentProtocolHost {
+    /** Extension that owns the protocol implementation. */
+    readonly extensionId: string;
+    /**
+     * Contribution id this host instance was created for (matches the
+     * `id` field on an `AiAgentProviderContribution`).
+     */
+    readonly providerContributionId: string;
+    /**
+     * Backend module id hosting the protocol implementation (matches
+     * the `id` on a `BackendModuleContribution`).
+     */
+    readonly backendModuleId: string;
+    /** Active AI session id this turn belongs to. */
+    readonly sessionId: string;
+    /** Absolute workspace path the session is scoped to. */
+    readonly workspacePath: string;
+    /**
+     * Model id the user picked for this turn (`undefined` if the
+     * provider does not require a model selection).
+     */
+    readonly model?: string;
+    /**
+     * Abort signal that fires when the user cancels the turn or the
+     * host tears the session down. Protocol implementations MUST
+     * honour it promptly.
+     */
+    readonly abortSignal: AbortSignal;
+    /** Permission posture the host has set for this turn. */
+    readonly permissionMode: PermissionMode;
+    /**
+     * MCP servers the user has configured for this session. The
+     * protocol implementation may pass these through to the
+     * underlying agent runtime; the host is responsible for credential
+     * resolution.
+     */
+    readonly mcpServers: readonly MCPServerConfig[];
+    /**
+     * Environment overrides the host wants applied when the protocol
+     * spawns its agent runtime. Keys are environment variable names;
+     * values are already-resolved strings (no template substitution).
+     */
+    readonly env: Readonly<Record<string, string>>;
+    /**
+     * Append a raw provider-native payload to `ai_agent_messages`.
+     * This is the single source of truth for the transcript; the
+     * host's transcript transformer derives canonical events from it.
+     *
+     * `direction` is `'input'` for payloads the host sent to the
+     * provider and `'output'` for payloads the provider returned.
+     * `metadata` is opaque to the host; surfaced verbatim in raw-log
+     * tooling.
+     *
+     * Resolves once the row is durably written.
+     */
+    logRaw(sessionId: string, direction: 'input' | 'output', content: string, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * Resolve an API key for the given provider id from the host's
+     * settings store (the same store the user manages from Settings).
+     *
+     * Resolves to `undefined` when no key is configured; the protocol
+     * implementation MUST NOT fall back to `process.env` (see the
+     * "Never Use Environment Variables as Implicit API Key Sources"
+     * rule in the project CLAUDE.md).
+     */
+    getApiKey(providerId: string): Promise<string | undefined>;
+    /**
+     * Read a workspace file via the host's filesystem broker. The
+     * path is resolved against `workspacePath`; reads outside the
+     * workspace are rejected.
+     *
+     * Returns the raw bytes; the protocol implementation is
+     * responsible for decoding.
+     */
+    readWorkspaceFile(path: string): Promise<Uint8Array>;
+    /**
+     * Write a workspace file via the host's filesystem broker.
+     * Subject to the extension's granted workspace-files permission;
+     * writes outside the workspace are rejected.
+     */
+    writeWorkspaceFile(path: string, content: Uint8Array): Promise<void>;
+    /**
+     * Register a batch of MCP tools with the host's session-scoped
+     * tool registry for the lifetime of this session. The returned
+     * promise resolves once the tools are visible to the model.
+     *
+     * Calling again replaces the prior registration for this host
+     * instance; pass an empty array to clear it. Tool handlers
+     * themselves are NOT part of this contract -- per Q7, the
+     * provider keeps its own dispatch path. The host only needs the
+     * advertised name / description / schema to expose the tool to
+     * the model and (eventually) to the provider's permission path.
+     */
+    registerMcpTools(tools: McpToolDefinition[]): Promise<void>;
+}
+//# sourceMappingURL=AgentProtocolHost.d.ts.map

package/dist/agents/AgentProtocolHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentProtocolHost.d.ts","sourceRoot":"","sources":["../../src/agents/AgentProtocolHost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAErD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAGhC,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IAExC;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAIjC,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,wDAAwD;IACxD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAElC,yDAAyD;IACzD,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IAExC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IAEhD;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAI/C;;;;;;;;;;;OAWG;IACH,MAAM,CACJ,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,OAAO,GAAG,QAAQ,EAC7B,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;OAQG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE3D;;;;;;;OAOG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAErD;;;;OAIG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D"}

package/dist/agents/AgentProtocolHost.js

@@ -0,0 +1,42 @@
+/**
+ * AgentProtocolHost
+ * -----------------
+ *
+ * Surface that the host (Nimbalyst) provides to an extension-owned
+ * `AgentProtocol` implementation at runtime. The protocol implementation
+ * lives in an extension's backend module and is brokered to the host by
+ * the privileged-host backend-module runtime; it must never reach for
+ * host internals directly.
+ *
+ * Identity fields are immutable for the lifetime of the host: they
+ * identify which extension contribution this protocol instance belongs
+ * to and which backend module is hosting it. Per-turn inputs (session
+ * id, workspace path, model, abort signal, permission mode, MCP
+ * servers, environment) are immutable for the lifetime of a single
+ * turn but may differ between turns on the same host instance.
+ *
+ * All async methods reject when the underlying broker call is rejected
+ * by the host (missing permission, unknown session, workspace
+ * mismatch, etc.) -- the protocol implementation is expected to
+ * surface those rejections as protocol-level errors rather than
+ * swallowing them.
+ *
+ * -------------------------------------------------------------------
+ * Q7 -- scope of this host (Phase-4 SDK proposal, resolved 2026-06-02)
+ * -------------------------------------------------------------------
+ *
+ * Per Q7 (Phase-4 SDK proposal, resolved 2026-06-02):
+ * emitEvent / requestPermission / askUserQuestion stay provider-private
+ * per the established upstream pattern (OpenAICodexProvider:1422-1491,
+ * claudeCode/askUserQuestion.ts:10, ProviderSessionManager.ts:49).
+ * Section 4.3's full facade is the agreed end-state, hoisted
+ * incrementally when each in-tree provider is next touched. Phase 4
+ * therefore ships the minimal 5-method host below; the missing
+ * methods are NOT a regression -- they live on the provider's own
+ * surface today and migrate behind a stable facade as each provider
+ * is reworked.
+ *
+ * See `docs/EXTENSION_ARCHITECTURE.md` and the Phase 4 SDK design doc
+ * (Section 4.3) for the full host contract.
+ */
+export {};

package/dist/agents/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Public agent-provider surface for the Nimbalyst extension SDK.
+ *
+ * Extensions that ship an `AiAgentProviderContribution` import the
+ * `AgentProtocol`, `AgentProtocolHost`, and supporting types from
+ * this subpath:
+ *
+ *     import type {
+ *       AgentProtocol,
+ *       AgentProtocolHost,
+ *       PermissionMode,
+ *     } from '@nimbalyst/extension-sdk/agents';
+ *
+ * Ownership model (post Phase-4 dependency inversion):
+ *
+ *   - The transport types (`AgentProtocol`, `ProtocolEvent`, ...) are
+ *     owned by the SDK in `./AgentProtocol`. The runtime re-exports
+ *     them from its own `ProtocolInterface` module so existing
+ *     runtime imports stay source-stable.
+ *   - The host-surface types (`AgentProtocolHost`, `PermissionMode`,
+ *     `McpToolDefinition`) live in this package because they only
+ *     have meaning at the extension boundary.
+ */
+export type { AgentProtocol, ProtocolEvent, ProtocolMessage, ProtocolSession, ProtocolAttachment, SessionOptions, ProtocolEventType, ToolResult, MCPServerConfig, RawProtocolSession, } from './AgentProtocol.js';
+export type { AgentProtocolHost, PermissionMode, McpToolDefinition, } from './AgentProtocolHost.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,YAAY,EACV,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAc5B,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,wBAAwB,CAAC"}

package/dist/agents/index.js

@@ -0,0 +1,24 @@
+/**
+ * Public agent-provider surface for the Nimbalyst extension SDK.
+ *
+ * Extensions that ship an `AiAgentProviderContribution` import the
+ * `AgentProtocol`, `AgentProtocolHost`, and supporting types from
+ * this subpath:
+ *
+ *     import type {
+ *       AgentProtocol,
+ *       AgentProtocolHost,
+ *       PermissionMode,
+ *     } from '@nimbalyst/extension-sdk/agents';
+ *
+ * Ownership model (post Phase-4 dependency inversion):
+ *
+ *   - The transport types (`AgentProtocol`, `ProtocolEvent`, ...) are
+ *     owned by the SDK in `./AgentProtocol`. The runtime re-exports
+ *     them from its own `ProtocolInterface` module so existing
+ *     runtime imports stay source-stable.
+ *   - The host-surface types (`AgentProtocolHost`, `PermissionMode`,
+ *     `McpToolDefinition`) live in this package because they only
+ *     have meaning at the extension boundary.
+ */
+export {};

package/dist/collab/createTextCollabContentAdapter.d.ts

@@ -0,0 +1,26 @@
+import type { CollabAdapterDescriptor, CollabContentAdapter } from '../types/collab.js';
+/** Default `Y.Text` field name used when none is supplied. */
+export declare const TEXT_COLLAB_DEFAULT_FIELD = "content";
+export interface TextCollabContentAdapterOptions {
+    /** Logical document type. Matches the shared doc's documentType and, by
+     *  convention, the custom-editor suffix without its dot (e.g. 'calc.md'). */
+    documentType: string;
+    /** On-disk extensions this adapter is the codec for (leading dot). The
+     *  first entry is the default for save-a-copy / export. */
+    fileExtensions: string[];
+    /** Optional MIME type for save dialogs / asset uploads. */
+    mimeType?: string;
+    /** Y.Text field name carrying the document text. Default 'content'. The
+     *  live binding MUST use the same field. */
+    textField?: string;
+    /** Layout schema version. Default 1. */
+    layoutVersion?: number;
+}
+export declare function createTextCollabContentAdapter(options: TextCollabContentAdapterOptions): CollabContentAdapter;
+/**
+ * Rebuild a CollabContentAdapter from a serializable descriptor (produced by a
+ * host factory and shipped across the process boundary). Returns null for an
+ * unknown descriptor kind so callers can fall back gracefully.
+ */
+export declare function reconstructCollabContentAdapterFromDescriptor(descriptor: CollabAdapterDescriptor): CollabContentAdapter | null;
+//# sourceMappingURL=createTextCollabContentAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createTextCollabContentAdapter.d.ts","sourceRoot":"","sources":["../../src/collab/createTextCollabContentAdapter.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EAErB,MAAM,oBAAoB,CAAC;AAE5B,8DAA8D;AAC9D,eAAO,MAAM,yBAAyB,YAAY,CAAC;AAEnD,MAAM,WAAW,+BAA+B;IAC9C;iFAC6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB;+DAC2D;IAC3D,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;gDAC4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAWD,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,oBAAoB,CAoDtB;AAED;;;;GAIG;AACH,wBAAgB,6CAA6C,CAC3D,UAAU,EAAE,uBAAuB,GAClC,oBAAoB,GAAG,IAAI,CAW7B"}

package/dist/collab/createTextCollabContentAdapter.js

@@ -0,0 +1,79 @@
+/** Default `Y.Text` field name used when none is supplied. */
+export const TEXT_COLLAB_DEFAULT_FIELD = 'content';
+function decodeSource(source) {
+    if (typeof source === 'string')
+        return source;
+    try {
+        return new TextDecoder('utf-8').decode(source);
+    }
+    catch {
+        return '';
+    }
+}
+export function createTextCollabContentAdapter(options) {
+    const field = options.textField ?? TEXT_COLLAB_DEFAULT_FIELD;
+    const layoutVersion = options.layoutVersion ?? 1;
+    const getText = (yDoc) => yDoc.getText(field);
+    return {
+        documentType: options.documentType,
+        fileExtensions: options.fileExtensions,
+        mimeType: options.mimeType,
+        layoutVersion,
+        // Lets the host rebuild this adapter in another process (e.g. Electron
+        // main) without loading the extension. See reconstruct fn below.
+        serializableDescriptor: {
+            kind: 'text',
+            documentType: options.documentType,
+            fileExtensions: options.fileExtensions,
+            mimeType: options.mimeType,
+            textField: field,
+            layoutVersion,
+        },
+        isEmpty(yDoc) {
+            return getText(yDoc).length === 0;
+        },
+        seedFromFile(yDoc, source) {
+            const text = decodeSource(source);
+            if (!text)
+                return;
+            const yText = getText(yDoc);
+            // Guard against a concurrent seed during the open race.
+            if (yText.length > 0)
+                return;
+            yText.insert(0, text);
+        },
+        applyFromFile(yDoc, source) {
+            const text = decodeSource(source);
+            yDoc.transact(() => {
+                const yText = getText(yDoc);
+                if (yText.length > 0)
+                    yText.delete(0, yText.length);
+                if (text.length > 0)
+                    yText.insert(0, text);
+            });
+        },
+        exportToFile(yDoc) {
+            return getText(yDoc).toString();
+        },
+        toPlainText(yDoc) {
+            return getText(yDoc).toString();
+        },
+    };
+}
+/**
+ * Rebuild a CollabContentAdapter from a serializable descriptor (produced by a
+ * host factory and shipped across the process boundary). Returns null for an
+ * unknown descriptor kind so callers can fall back gracefully.
+ */
+export function reconstructCollabContentAdapterFromDescriptor(descriptor) {
+    if (descriptor.kind === 'text') {
+        return createTextCollabContentAdapter({
+            documentType: descriptor.documentType,
+            fileExtensions: descriptor.fileExtensions,
+            mimeType: descriptor.mimeType,
+            textField: descriptor.textField,
+            layoutVersion: descriptor.layoutVersion,
+        });
+    }
+    return null;
+}

package/dist/externalsPlugin.js

@@ -224,6 +224,16 @@ function generateCommonExports(externalKey) {
     else if (externalKey === '@nimbalyst/runtime/ui/icons/MaterialSymbol') {
         exports = ['MaterialSymbol'];
     }
+    else if (externalKey === '@nimbalyst/runtime') {
+        exports = [
+            'MaterialSymbol', 'useDocumentPath', 'useEditorLifecycle',
+            'useCollaborativeEditor', 'COLLAB_INIT_ORIGIN',
+            'setTranscriptMarkdownContributions', 'clearTranscriptMarkdownContributions',
+            'MarkdownEditor', 'MonacoEditor', 'MonacoCodeEditor',
+            'TrackerReferenceChip', 'TrackerReferencePicker',
+            'useResolvedTrackerReference', 'navigateToTrackerReference',
+        ];
+    }
     else if (externalKey === '@nimbalyst/screenshot-service') {
         exports = ['screenshotService'];
     }

package/dist/fileDirectoryTree.d.ts

@@ -0,0 +1,19 @@
+export interface FileDirectoryNode<T> {
+    path: string;
+    displayPath: string;
+    files: T[];
+    subdirectories: Map<string, FileDirectoryNode<T>>;
+    fileCount: number;
+}
+/** Normalize filesystem separators for renderer-side path comparison and display. */
+export declare function normalizeFilePath(filePath: string): string;
+export declare function getFilePathBasename(filePath: string): string;
+/**
+ * Return a forward-slash path relative to the workspace when the file is inside it.
+ * Windows drive paths are compared case-insensitively to match filesystem behavior.
+ */
+export declare function getWorkspaceRelativeFilePath(filePath: string, workspacePath?: string): string;
+/** Build a collapsed directory tree for arbitrary file records. */
+export declare function buildFileDirectoryTree<T>(files: T[], getFilePath: (file: T) => string, workspacePath?: string): FileDirectoryNode<T>;
+export declare function getFileDirectoryPaths<T>(node: FileDirectoryNode<T>): string[];
+//# sourceMappingURL=fileDirectoryTree.d.ts.map

package/dist/fileDirectoryTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileDirectoryTree.d.ts","sourceRoot":"","sources":["../src/fileDirectoryTree.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAkB7F;AA6BD,mEAAmE;AACnE,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,KAAK,EAAE,CAAC,EAAE,EACV,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,EAChC,aAAa,CAAC,EAAE,MAAM,GACrB,iBAAiB,CAAC,CAAC,CAAC,CAwCtB;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,CAM7E"}

package/dist/fileDirectoryTree.js

@@ -0,0 +1,98 @@
+/** Normalize filesystem separators for renderer-side path comparison and display. */
+export function normalizeFilePath(filePath) {
+    return filePath.replace(/[\\/]+/g, '/');
+}
+export function getFilePathBasename(filePath) {
+    const normalizedPath = normalizeFilePath(filePath);
+    return normalizedPath.slice(normalizedPath.lastIndexOf('/') + 1);
+}
+/**
+ * Return a forward-slash path relative to the workspace when the file is inside it.
+ * Windows drive paths are compared case-insensitively to match filesystem behavior.
+ */
+export function getWorkspaceRelativeFilePath(filePath, workspacePath) {
+    const normalizedFile = normalizeFilePath(filePath);
+    if (!workspacePath)
+        return normalizedFile;
+    const normalizedWorkspace = normalizeFilePath(workspacePath).replace(/\/$/, '');
+    const windowsDrivePath = /^[A-Za-z]:\//.test(normalizedFile)
+        && /^[A-Za-z]:\//.test(normalizedWorkspace);
+    const comparableFile = windowsDrivePath ? normalizedFile.toLowerCase() : normalizedFile;
+    const comparableWorkspace = windowsDrivePath
+        ? normalizedWorkspace.toLowerCase()
+        : normalizedWorkspace;
+    if (comparableFile === comparableWorkspace)
+        return '';
+    if (comparableFile.startsWith(`${comparableWorkspace}/`)) {
+        return normalizedFile.slice(normalizedWorkspace.length + 1);
+    }
+    return normalizedFile;
+}
+function collapseDirectoryTree(node) {
+    node.subdirectories.forEach((subdirectory, key) => {
+        node.subdirectories.set(key, collapseDirectoryTree(subdirectory));
+    });
+    if (node.subdirectories.size === 1 && node.files.length === 0) {
+        const childNode = node.subdirectories.values().next().value;
+        return {
+            ...childNode,
+            displayPath: node.displayPath
+                ? `${node.displayPath}/${childNode.displayPath}`
+                : childNode.displayPath,
+        };
+    }
+    return node;
+}
+function updateFileCounts(node) {
+    let count = node.files.length;
+    node.subdirectories.forEach(subdirectory => {
+        count += updateFileCounts(subdirectory);
+    });
+    node.fileCount = count;
+    return count;
+}
+/** Build a collapsed directory tree for arbitrary file records. */
+export function buildFileDirectoryTree(files, getFilePath, workspacePath) {
+    const root = {
+        path: '',
+        displayPath: '',
+        files: [],
+        subdirectories: new Map(),
+        fileCount: 0,
+    };
+    files.forEach(file => {
+        const relativePath = getWorkspaceRelativeFilePath(getFilePath(file), workspacePath);
+        const parts = relativePath.split('/').filter(Boolean);
+        if (parts.length <= 1) {
+            root.files.push(file);
+            return;
+        }
+        let currentNode = root;
+        const directoryParts = parts.slice(0, -1);
+        directoryParts.forEach((part, index) => {
+            const path = directoryParts.slice(0, index + 1).join('/');
+            let childNode = currentNode.subdirectories.get(part);
+            if (!childNode) {
+                childNode = {
+                    path,
+                    displayPath: part,
+                    files: [],
+                    subdirectories: new Map(),
+                    fileCount: 0,
+                };
+                currentNode.subdirectories.set(part, childNode);
+            }
+            currentNode = childNode;
+        });
+        currentNode.files.push(file);
+    });
+    updateFileCounts(root);
+    return collapseDirectoryTree(root);
+}
+export function getFileDirectoryPaths(node) {
+    const paths = node.path ? [node.path] : [];
+    node.subdirectories.forEach(subdirectory => {
+        paths.push(...getFileDirectoryPaths(subdirectory));
+    });
+    return paths;
+}

package/dist/index.d.ts

@@ -26,9 +26,14 @@ export { REQUIRED_EXTERNALS, EXTERNAL_PATTERNS, ROLLUP_EXTERNALS, type RequiredE
 export * from './types/index.js';
 export { useEditorLifecycle, type UseEditorLifecycleOptions, type UseEditorLifecycleResult, type DiffState, } from './useEditorLifecycle.js';
 export { useCollaborativeEditor, COLLAB_INIT_ORIGIN, type UseCollaborativeEditorConfig, type UseCollaborativeEditorResult, } from './useCollaborativeEditor.js';
+export { createTextCollabContentAdapter, reconstructCollabContentAdapterFromDescriptor, TEXT_COLLAB_DEFAULT_FIELD, type TextCollabContentAdapterOptions, } from './collab/createTextCollabContentAdapter.js';
 export { useDocumentPath, type DocumentPathContextValue, } from './documentPath.js';
 export { MaterialSymbol } from './MaterialSymbol.js';
+export { TrackerReferenceChip, TrackerReferencePicker, navigateToTrackerReference, useResolvedTrackerReference, type ResolvedTrackerReference, type TrackerReferenceChipProps, type TrackerReferencePickerProps, } from './trackerReferences.js';
 export { createReadOnlyHost, type ReadOnlyHost, type ReadOnlyHostOptions, } from './createReadOnlyHost.js';
 export { copyToClipboard, readClipboard } from './clipboard.js';
+export { buildFileDirectoryTree, getFileDirectoryPaths, getFilePathBasename, getWorkspaceRelativeFilePath, normalizeFilePath, type FileDirectoryNode, } from './fileDirectoryTree.js';
 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';
 //# 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,sBAAsB,EACtB,kBAAkB,EAClB,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,GAClC,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,eAAe,EACf,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,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,uBAAuB,EACvB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,eAAe,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,sBAAsB,EACtB,kBAAkB,EAClB,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,GAClC,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,8BAA8B,EAC9B,6CAA6C,EAC7C,yBAAyB,EACzB,KAAK,+BAA+B,GACrC,MAAM,4CAA4C,CAAC;AAGpD,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"}

package/dist/index.js

@@ -29,12 +29,19 @@ export * from './types/index.js';
 // Re-export hooks
 export { useEditorLifecycle, } from './useEditorLifecycle.js';
 export { useCollaborativeEditor, COLLAB_INIT_ORIGIN, } from './useCollaborativeEditor.js';
+export { createTextCollabContentAdapter, reconstructCollabContentAdapterFromDescriptor, TEXT_COLLAB_DEFAULT_FIELD, } from './collab/createTextCollabContentAdapter.js';
 // Re-export host-provided editor context and UI helpers for extensions.
 export { useDocumentPath, } from './documentPath.js';
 export { MaterialSymbol } from './MaterialSymbol.js';
+// Re-export host-owned tracker reference UI. Extensions persist only reference
+// keys while Nimbalyst owns live resolution, previews, selection, and opening.
+export { TrackerReferenceChip, TrackerReferencePicker, navigateToTrackerReference, useResolvedTrackerReference, } from './trackerReferences.js';
 // Re-export read-only host factory (for web viewers and testing)
 export { createReadOnlyHost, } from './createReadOnlyHost.js';
 // Re-export clipboard utilities
 export { copyToClipboard, readClipboard } from './clipboard.js';
+// Re-export cross-platform file tree utilities for host and extension UIs.
+export { buildFileDirectoryTree, getFileDirectoryPaths, getFilePathBasename, getWorkspaceRelativeFilePath, normalizeFilePath, } from './fileDirectoryTree.js';
 // Re-export validation
 export { validateExtensionBundle, printValidationResult, } from './validate.js';
+export { validateBackendModules, assertBackendModulesValid, effectiveModulePermissions, validateAgentProviders, assertAgentProvidersValid, extractBackendModuleIds, MAX_AGENT_PROVIDERS_PER_EXTENSION, } from './manifestValidation.js';