@nimbalyst/extension-sdk 0.1.5 → 0.2.1

package/CHANGELOG.md

@@ -8,11 +8,41 @@ The SDK is versioned independently of the Nimbalyst app. Each release declares i
 
 | SDK version | Minimum Nimbalyst app version |
 | --- | --- |
+| 0.2.1 | 0.58.5 |
+| 0.2.0 | 0.58.5 |
 | 0.1.5 | 0.58.5 |
 | 0.1.0 | 0.58.5 |
 
 ## [Unreleased]
 
+## [0.2.1]
+
+### Added
+
+- `ExtensionAITool.access` declares whether a tool uses filesystem, editor-read, or editor-write access; `readOnly` remains as a compatibility alias.
+- `useCollaborativeEditor` accepts `{ codec, bind }` so an editor's pure collab codec is defined once and shared with the host's headless seeding; the previous `createBinding`/`initializeFromContent` config keeps working.
+- `CollaborationContext.flushWithAck` (server-persisted flush) and optional `hasUndecodedContent`.
+
+### Fixed
+
+- The first-open seed no longer runs from empty initial content or when the transport skipped payloads it could not decode — both cases wrote a default document over the shared room's real content.
+
+## [0.2.0]
+
+Adds opt-in collaborative editing for custom editors. Backwards-compatible: extensions built against 0.2.0 continue to work on older Nimbalyst hosts -- the collaboration hook detects the absence of `host.collaboration` and reports `isCollaborative: false` so the editor falls back to local-only editing.
+
+### Added
+
+- `useCollaborativeEditor(host, options)` hook for wiring a custom editor to a shared Y.Doc through `host.collaboration`. Handles binding lifecycle, awareness, status, and the empty-doc seed path.
+- `CollaborationContext` type on `EditorHost.collaboration` exposing the Y.Doc, awareness, doc id, local user info, and connection status.
+- Manifest field `contributions.customEditors[].collaboration = { supported: boolean, awarenessFields?: string[] }` so extensions declare collab support and the awareness shape they publish.
+- `yjs` and `y-protocols` declared as optional peer dependencies, externalized by the host so a single Y.Doc instance is shared with the rest of Nimbalyst (mismatched copies fragment the document).
+
+### Notes
+
+- Existing extensions need no changes; if `collaboration.supported` is absent the editor continues to be loaded as before.
+- See `docs/COLLABORATION_GUIDE.md` for the binding pattern (Excalidraw and CSV are reference implementations).
+
 ## [0.1.5]
 
 First release published via GitHub Actions Trusted Publishing (OIDC). No API changes from 0.1.0.

package/dist/__tests__/createTextCollabContentAdapter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=createTextCollabContentAdapter.test.d.ts.map

package/dist/__tests__/createTextCollabContentAdapter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTextCollabContentAdapter.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/createTextCollabContentAdapter.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/createTextCollabContentAdapter.test.js

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import * as Y from 'yjs';
+import { createTextCollabContentAdapter } from '../collab/createTextCollabContentAdapter';
+const adapter = createTextCollabContentAdapter({
+    documentType: 'calc.md',
+    fileExtensions: ['.calc.md'],
+    mimeType: 'text/markdown',
+    textField: 'content',
+});
+describe('createTextCollabContentAdapter', () => {
+    it('reports identity (documentType, extensions, version)', () => {
+        expect(adapter.documentType).toBe('calc.md');
+        expect(adapter.fileExtensions).toEqual(['.calc.md']);
+        expect(adapter.layoutVersion).toBe(1);
+    });
+    it('isEmpty is true for a fresh Y.Doc and false after seeding', () => {
+        const doc = new Y.Doc();
+        expect(adapter.isEmpty(doc)).toBe(true);
+        adapter.seedFromFile(doc, 'price = 100 USD\n');
+        expect(adapter.isEmpty(doc)).toBe(false);
+    });
+    it('round-trips file content through seed -> export -> plain text', () => {
+        const doc = new Y.Doc();
+        const source = '# Inputs\nprice = 100 USD\nqty = 3\n';
+        adapter.seedFromFile(doc, source);
+        expect(adapter.exportToFile(doc)).toBe(source);
+        expect(adapter.toPlainText(doc)).toBe(source);
+    });
+    it('decodes Uint8Array file sources', () => {
+        const doc = new Y.Doc();
+        const source = 'total = price * qty\n';
+        adapter.seedFromFile(doc, new TextEncoder().encode(source));
+        expect(adapter.exportToFile(doc)).toBe(source);
+    });
+    it('seedFromFile is a no-op when the Y.Text is already populated (open race)', () => {
+        const doc = new Y.Doc();
+        adapter.seedFromFile(doc, 'first');
+        adapter.seedFromFile(doc, 'second');
+        expect(adapter.exportToFile(doc)).toBe('first');
+    });
+    it('applyFromFile replaces existing content on a populated Y.Doc', () => {
+        const doc = new Y.Doc();
+        adapter.seedFromFile(doc, 'old content');
+        adapter.applyFromFile(doc, 'brand new content');
+        expect(adapter.exportToFile(doc)).toBe('brand new content');
+    });
+    it('does not re-seed a doc that already received content via sync (race guard)', () => {
+        // Models the bootstrap race on a SINGLE shared doc: another client's seed
+        // arrives over the wire first, then this client (which had decided the doc
+        // was empty) calls seedFromFile. The length guard makes the late seed a
+        // no-op, so the synced content is preserved verbatim (no concatenation).
+        // The hook layer additionally re-checks isEmpty before seeding.
+        const remote = new Y.Doc();
+        adapter.seedFromFile(remote, 'a = 1\nb = 2\n');
+        const local = new Y.Doc();
+        Y.applyUpdate(local, Y.encodeStateAsUpdate(remote)); // remote seed arrives
+        adapter.seedFromFile(local, 'a = 1\nb = 2\n'); // late local seed -> no-op
+        expect(adapter.exportToFile(local)).toBe('a = 1\nb = 2\n');
+    });
+});

package/dist/__tests__/hasSeedableContent.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hasSeedableContent.test.d.ts.map

package/dist/__tests__/hasSeedableContent.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hasSeedableContent.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/hasSeedableContent.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/hasSeedableContent.test.js

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { hasSeedableContent } from '../useCollaborativeEditor';
+/**
+ * NIM-1520 fallout guard: a host with no bytes for a collab doc returns ''
+ * from loadInitialContent; seeding from that writes a DEFAULT document over
+ * the room's real content ("Untitled map" clobber). Empty content must never
+ * be considered seedable.
+ */
+describe('hasSeedableContent', () => {
+    it('rejects null/undefined/empty/whitespace strings', () => {
+        expect(hasSeedableContent(null)).toBe(false);
+        expect(hasSeedableContent(undefined)).toBe(false);
+        expect(hasSeedableContent('')).toBe(false);
+        expect(hasSeedableContent('   \n\t')).toBe(false);
+    });
+    it('rejects empty binary buffers', () => {
+        expect(hasSeedableContent(new ArrayBuffer(0))).toBe(false);
+        expect(hasSeedableContent(new Uint8Array(0))).toBe(false);
+    });
+    it('accepts real content', () => {
+        expect(hasSeedableContent('# Title')).toBe(true);
+        expect(hasSeedableContent(new Uint8Array([1, 2, 3]))).toBe(true);
+        expect(hasSeedableContent(new ArrayBuffer(8))).toBe(true);
+    });
+});

package/dist/__tests__/manifestValidation.agentProviders.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=manifestValidation.agentProviders.test.d.ts.map

package/dist/__tests__/manifestValidation.agentProviders.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifestValidation.agentProviders.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/manifestValidation.agentProviders.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/manifestValidation.agentProviders.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { validateAgentProviders } from '../manifestValidation';
+// The validator must agree with the AiAgentProviderContribution /
+// AiAgentProviderModel types: the provider label field is `displayName`, and
+// model entries carry no per-entry `provider`. A manifest matching the shipped
+// gemini-antigravity contribution should pass cleanly. Before the alignment,
+// the validator required `name` and `model.provider`, so the real manifest
+// failed its own validator (#558 review, point 1).
+const backendModules = [{ id: 'antigravity-server', entry: 'backend/index.js' }];
+function geminiLikeProvider(overrides = {}) {
+    return {
+        id: 'antigravity-gemini-agent',
+        displayName: 'Gemini',
+        platform: 'antigravity-gemini',
+        backendModuleId: 'antigravity-server',
+        modelDiscovery: 'static',
+        models: [
+            { id: 'antigravity-gemini-agent:gemini-3-flash-agent', name: 'Gemini 3.5 Flash (High)', default: true },
+            { id: 'antigravity-gemini-agent:gemini-3.5-flash-low', name: 'Gemini 3.5 Flash (Medium)' },
+        ],
+        ...overrides,
+    };
+}
+describe('validateAgentProviders - alignment with the SDK type (#558)', () => {
+    it('accepts a provider that uses displayName and models without a provider field', () => {
+        const issues = validateAgentProviders([geminiLikeProvider()], backendModules);
+        expect(issues).toEqual([]);
+    });
+    it('flags a provider missing displayName', () => {
+        const { displayName, ...noDisplayName } = geminiLikeProvider();
+        const issues = validateAgentProviders([noDisplayName], backendModules);
+        expect(issues.some((i) => i.message.includes('displayName'))).toBe(true);
+    });
+    it('does not require a per-model provider field', () => {
+        // A model entry with only id + name is valid; the host derives the
+        // provider from the contribution id.
+        const issues = validateAgentProviders([geminiLikeProvider({ models: [{ id: 'm1', name: 'Model One' }] })], backendModules);
+        expect(issues).toEqual([]);
+    });
+    it('still requires a model name', () => {
+        const issues = validateAgentProviders([geminiLikeProvider({ models: [{ id: 'm1' }] })], backendModules);
+        expect(issues.some((i) => i.message.includes('.name must be a non-empty string'))).toBe(true);
+    });
+});

package/dist/agents/AgentProtocol.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Protocol Interface for Agent SDK Adapters
+ *
+ * This interface normalizes the differences between various agent SDKs
+ * (Claude Agent SDK, OpenAI Codex SDK) to provide a unified abstraction
+ * layer for agent providers.
+ *
+ * The protocol adapters isolate platform-specific SDK details from the
+ * provider implementations, making it easier to:
+ * - Add new agent SDKs
+ * - Update SDK versions without touching provider logic
+ * - Test providers with mock protocols
+ * - Share common infrastructure across providers
+ *
+ * Ownership note: this module is the canonical home of the protocol
+ * contract. The runtime re-exports these types via
+ * `@nimbalyst/runtime/ai/server/protocols/ProtocolInterface` so that
+ * existing runtime imports keep working without source churn, but the
+ * SDK now owns the type bodies. Adding a new field, changing a tag, or
+ * tightening a discriminator happens here first; the runtime picks it
+ * up via the re-export.
+ */
+/**
+ * MCP server configuration
+ */
+export interface MCPServerConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    [key: string]: unknown;
+}
+/**
+ * Platform-specific session data for internal use
+ */
+export interface RawProtocolSession {
+    [key: string]: unknown;
+}
+/**
+ * Structured result from tool execution
+ */
+export interface ToolResult {
+    success: boolean;
+    result?: unknown;
+    output?: unknown;
+    error?: string | unknown;
+    status?: string;
+    command?: string;
+    exit_code?: number;
+    changes?: unknown;
+    query?: string;
+    action?: unknown;
+    fileSnapshots?: Record<string, {
+        content: string | null;
+        error?: string;
+        isBinary?: boolean;
+        truncated?: boolean;
+    }>;
+}
+/**
+ * Options for creating or resuming a session
+ */
+export interface SessionOptions {
+    /** Working directory path for the session */
+    workspacePath: string;
+    /** Model identifier (e.g., 'sonnet', 'gpt-5') */
+    model?: string;
+    /** System prompt to initialize the agent */
+    systemPrompt?: string;
+    /** Abort signal for cancelling the session */
+    abortSignal?: AbortSignal;
+    /** Permission mode for tool approvals ('ask', 'auto', 'plan') */
+    permissionMode?: string;
+    /** MCP server configurations */
+    mcpServers?: Record<string, MCPServerConfig>;
+    /** Environment variables for the session */
+    env?: Record<string, string>;
+    /** Tools to allow (whitelist) */
+    allowedTools?: string[];
+    /** Tools to disallow (blacklist) */
+    disallowedTools?: string[];
+    /** Platform-specific options that don't fit the common schema */
+    raw?: Record<string, unknown>;
+}
+/**
+ * Attachment shape used by ProtocolMessage.
+ *
+ * Inlined into the SDK (rather than re-imported from the runtime's
+ * `ChatAttachment`) so the protocol contract has no dependency on
+ * runtime types. The runtime's `ChatAttachment` is structurally
+ * assignable to this shape, so existing runtime call sites that pass
+ * `ChatAttachment[]` continue to type-check at the SDK boundary.
+ */
+export interface ProtocolAttachment {
+    id: string;
+    filename: string;
+    filepath: string;
+    mimeType: string;
+    size: number;
+    type: 'image' | 'pdf' | 'document';
+    thumbnail?: string;
+    addedAt: number;
+}
+/**
+ * Message sent to the agent
+ */
+export interface ProtocolMessage {
+    /** Text content of the message */
+    content: string;
+    /** Optional attachments (images, PDFs, documents) */
+    attachments?: ProtocolAttachment[];
+    /** Session ID for logging and tracking */
+    sessionId?: string;
+    /** AI mode when message was sent ('planning' or 'agent' or 'auto') */
+    mode?: 'planning' | 'agent' | 'auto';
+}
+/**
+ * Session created or resumed by the protocol
+ */
+export interface ProtocolSession {
+    /** Platform-specific session identifier */
+    id: string;
+    /** Platform identifier (e.g., 'claude-sdk', 'codex-sdk') */
+    platform: string;
+    /** Platform-specific session data (for internal use) */
+    raw?: RawProtocolSession;
+}
+/**
+ * Event types emitted during message streaming
+ */
+export type ProtocolEventType = 'raw_event' | 'text' | 'reasoning' | 'tool_call' | 'tool_result' | 'error' | 'complete' | 'usage' | 'planning_mode_entered' | 'planning_mode_exited';
+/**
+ * Event emitted during message streaming
+ */
+export interface ProtocolEvent {
+    /** Event type */
+    type: ProtocolEventType;
+    /** Text content (for 'text' events) */
+    content?: string;
+    /** Tool call data (for 'tool_call' events) */
+    toolCall?: {
+        id?: string;
+        name: string;
+        arguments?: Record<string, any>;
+        result?: ToolResult | string;
+    };
+    /** Tool result data (for 'tool_result' events) */
+    toolResult?: {
+        id?: string;
+        name: string;
+        result?: ToolResult | string;
+    };
+    /** Error message (for 'error' events) */
+    error?: string;
+    /** Token usage (for 'usage' or 'complete' events) */
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+        total_tokens: number;
+    };
+    /** Current context fill tokens for this turn (provider-reported snapshot) */
+    contextFillTokens?: number;
+    /** Maximum context window for the active model */
+    contextWindow?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Agent Protocol Interface
+ *
+ * All agent SDK adapters must implement this interface to provide
+ * a consistent abstraction layer for agent providers.
+ */
+export interface AgentProtocol {
+    /**
+     * Platform identifier (e.g., 'claude-sdk', 'codex-sdk')
+     */
+    readonly platform: string;
+    /**
+     * Create a new session
+     *
+     * @param options - Session configuration
+     * @returns Protocol session with platform-specific ID
+     */
+    createSession(options: SessionOptions): Promise<ProtocolSession>;
+    /**
+     * Resume an existing session
+     *
+     * @param sessionId - Platform-specific session ID to resume
+     * @param options - Session configuration
+     * @returns Protocol session
+     */
+    resumeSession(sessionId: string, options: SessionOptions): Promise<ProtocolSession>;
+    /**
+     * Fork an existing session (create a branch)
+     *
+     * Not all platforms support forking. If unsupported, implementations
+     * should either throw an error or create a new session.
+     *
+     * @param sessionId - Platform-specific session ID to fork from
+     * @param options - Session configuration for the fork
+     * @returns New protocol session branched from the source
+     */
+    forkSession(sessionId: string, options: SessionOptions): Promise<ProtocolSession>;
+    /**
+     * Send a message and receive streaming events
+     *
+     * @param session - Active protocol session
+     * @param message - Message to send
+     * @returns Async iterable of protocol events
+     */
+    sendMessage(session: ProtocolSession, message: ProtocolMessage): AsyncIterable<ProtocolEvent>;
+    /**
+     * Abort an active session
+     *
+     * @param session - Session to abort
+     */
+    abortSession(session: ProtocolSession): void;
+    /**
+     * Clean up session resources
+     *
+     * Called when a session is deleted or no longer needed.
+     *
+     * @param session - Session to clean up
+     */
+    cleanupSession(session: ProtocolSession): void;
+}
+//# sourceMappingURL=AgentProtocol.d.ts.map

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

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

package/dist/agents/AgentProtocol.js

@@ -0,0 +1,23 @@
+/**
+ * Protocol Interface for Agent SDK Adapters
+ *
+ * This interface normalizes the differences between various agent SDKs
+ * (Claude Agent SDK, OpenAI Codex SDK) to provide a unified abstraction
+ * layer for agent providers.
+ *
+ * The protocol adapters isolate platform-specific SDK details from the
+ * provider implementations, making it easier to:
+ * - Add new agent SDKs
+ * - Update SDK versions without touching provider logic
+ * - Test providers with mock protocols
+ * - Share common infrastructure across providers
+ *
+ * Ownership note: this module is the canonical home of the protocol
+ * contract. The runtime re-exports these types via
+ * `@nimbalyst/runtime/ai/server/protocols/ProtocolInterface` so that
+ * existing runtime imports keep working without source churn, but the
+ * SDK now owns the type bodies. Adding a new field, changing a tag, or
+ * tightening a discriminator happens here first; the runtime picks it
+ * up via the re-export.
+ */
+export {};

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"}