@zyntax/extension-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zyntax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# Zyntax Extension SDK
+
+`@zyntax/extension-sdk` is the canonical public contract for executable Zyntax
+extension providers. It contains plain-data manifest and RPC types, canonical
+capability names, and small authoring helpers. It has no editor, WebView,
+filesystem, network, native-command, or app-private dependencies.
+
+Provider code is bundled by the Zyntax extension tooling into a self-contained
+`providers/*.js` module. Import only this package for host DTOs and provider
+helpers; do not import application source or tooling internals.
+
+Tooling consumes the `provider-methods`, `manifest-constants`, and `capabilities`
+subpaths so manifest validation and provider bundle validation share one public
+vocabulary.
+
+```ts
+import {
+  EXTENSION_API_VERSION,
+  defineCompletionProvider,
+  type ExtensionCompletionProvider,
+} from "@zyntax/extension-sdk";
+
+export const extensionApiVersion = EXTENSION_API_VERSION;
+
+export const createCompletionProvider = defineCompletionProvider(
+  (): ExtensionCompletionProvider => ({
+    provideCompletions(request, cancellation) {
+      cancellation.throwIfCancellationRequested();
+      return null;
+    },
+    dispose() {},
+  }),
+);
+```
+
+Manifest validation remains host/tooling-owned. The SDK does not grant
+permissions or platform access.
+
+Language-server mappings declare only verified routes. Position routes are
+`completion`, `hover`, `signatureHelp`, `definition`, `implementation`,
+`typeDefinition`, `references`, `rename`, `codeActions`, `typeHierarchy`, and
+`documentHighlights`. Document/workspace routes are `diagnostics`,
+`semanticTokens`, `workspaceSymbols`, `documentSymbols`, `foldingRanges`, and
+`documentFormatting`. The host negotiates the matching standard LSP methods and
+routes parser-owned source or virtual coordinates; it never infers a claim from
+the server, language, filename, or installed package.
+
+Declarative TextMate contributions reference exact UTF-8 JSON
+(`syntaxes/*.tmLanguage.json`) or XML plist (`syntaxes/*.tmLanguage`) assets. The
+host validates and loads the declared format directly; extensions do not convert
+or execute grammar assets. A primary grammar declares its sorted canonical
+`languages` bindings; one immutable asset may serve multiple identities when the
+upstream grammar is genuinely shared. Injection-only grammars omit `languages`.
+
+The published package contains compiled ESM and declaration files in `dist/`.
+Extension builds never execute TypeScript source directly from `node_modules`.
+
+The SDK also defines bounded plain-data contracts for inline completions,
+assisted edits, AI code actions, decorations, document colors, hover, tasks, terminal
+profiles, SCM state, and project templates. A task provider returns one reviewed
+execution plan. A `terminal` plan contains only a command name, literal argument
+array, and project-relative working-directory segments and requires the explicit
+`terminal` permission. A `managedTool` plan contains only an exact manifest-declared
+tool and entrypoint, bounded literal arguments, and project-relative working-directory
+segments and requires `tools.execute`. The host resolves either plan only after
+approval, owns its lifetime and cancellation, and never exposes a native path,
+environment, shell fragment, or process handle to the provider. Terminal-profile
+and project-template providers likewise return descriptors or host-reviewed plans
+while the host owns process launch, filesystem writes, approvals, and transactions.
+Assisted-edit providers expose both bounded unary proposals and one ordered push
+stream. A streaming invocation emits progress or proposal events through the
+host-provided sink, observes the cancellation token, and completes once. The native
+transport owns ordering, byte/count limits, cancellation, and terminal delivery;
+providers never poll or open a second request.
+
+Hover providers receive the exact parser-owned source region at the requested
+position and return only bounded plain-text or Markdown content with a
+snapshot-bound source range. The host sanitizes and renders that content in the
+same tooltip surface as LSP hover, suppresses the surface while completion is
+pending or active, and owns pointer and touch activation. Providers cannot
+return HTML, DOM, editor objects, or infer embedded languages from filenames or
+source scans.
+
+Managed-tool adapters use the exported `EXTENSION_MANAGED_TOOL_INVOCATION_METHOD`
+and JSON-RPC request/response types over the host's Content-Length-framed stdio
+transport. Extension code selects only a manifest-declared tool and entrypoint;
+it never supplies an executable path, environment, or terminal command.
+
+Long-running managed tools use the declarative `persistentServices` contribution and the
+`services.manage` permission. A service selects only a signed tool and entrypoint and declares
+bounded stop, health-probe, and log policy; it cannot declare argv, an environment, a path, or
+shell text. Providers operate only their own symbolic service ids. The host owns the canonical
+workspace/trust decision, process group, health, bounded UTF-8 logs, and exact activation cleanup.
+
+Terminal development dependencies use `contributes.developmentStacks` and the independent
+`terminal.packages` permission. A stack contains one to 32 required package symbols from the fixed
+host-known `zyntax` or `termux-main` repository identity. It cannot contain repository URLs, keys,
+versions, package-manager options, commands, paths, environment values, or scripts. The
+`terminal.packages` host API accepts only a declared stack id and `install`, `repair`, or `update`;
+the host resolves signed candidates, presents the complete Package Manager review, owns the one
+durable mutation queue, and returns only a bounded symbolic transaction snapshot. This permission
+does not grant `terminal`, `network`, or `tools.execute`.
+
+```json
+{
+  "permissions": ["extension.execute", "terminal.packages"],
+  "contributes": {
+    "developmentStacks": [{
+      "id": "web-runtime",
+      "label": "Web runtime",
+      "packages": [{ "repository": "termux-main", "package": "nodejs-lts" }]
+    }]
+  }
+}
+```
+
+Managed execution arguments may contain a signed resource reference instead of
+a literal string. The native host resolves it immediately before launch and the
+path never enters extension-provider code. Node entrypoints may additionally
+declare a sorted `nodeModules` array which binds a valid npm package name to a
+signed package-directory resource. The host projects the entrypoint and those
+packages into one immutable module tree and launches it with normal Node module
+resolution. Manifests never declare `NODE_PATH`, installation directories, or
+package-specific host behavior; each resource package must carry a matching
+`package.json` name.
+
+Managed document formatters declare their exact stdio protocol. Use
+`framed-jsonrpc` for an adapter that implements the canonical formatting RPC, or
+`raw-stdio` for a direct CLI which accepts the exact document bytes on stdin and
+returns one bounded UTF-8 document on stdout. Raw formatter arguments are fixed
+manifest strings or signed resource references; the host does not substitute a
+language, URI, option, or shell fragment at runtime. The explicit current-document
+path reference is available only to document formatters. Contribute separate formatter descriptors when a CLI
+requires a different constant argument for each canonical language.
+
+Project-template providers return either an atomic UTF-8 file plan or a
+symbolic managed-tool plan. Managed generators run only after host review, in a
+new app-owned staging root, and must produce the declared regular-file markers
+before the host atomically publishes the project. The provider and managed tool
+receive JSON and canonical URIs only; native paths never cross the provider
+boundary.
+
+Debugger configuration providers receive the active project and document as
+canonical URIs. Use `debugDocumentPath(documentUri)` for configuration fields
+such as `program`; the host validates that URI against the active project and
+resolves the native path only when it sends the DAP launch or attach request.
+Providers and manifests never contain app-private filesystem paths.
+
+For a launch field which the user must select, use
+`debugProjectPath(id, label, kind)`. Zyntax reviews and persists the selected
+canonical document URI per project. The symbolic slot remains in provider
+requests; only the managed DAP host resolves it to a native path immediately
+before adapter launch.
+
+Providers with `workspace.read` can query the host-owned project index through
+`findFiles({ include, exclude?, maxResults }, cancellation)`. Globs are relative
+to the open project; a basename-only glob matches at any depth. Results contain
+only canonical document URIs and project-relative paths, are deterministic and
+bounded, and remain subject to the same project-confined `readText` boundary.
+`relativePath(uri, cancellation)` resolves a canonical document URI to its
+project-relative identity, or `null` when the document is outside the open
+project. The isolated provider never receives a native path or direct filesystem
+access.
+
+Preview providers may select registered editor languages or declare strict
+project-relative `paths` globs. Path selectors route host-safe previews without
+claiming syntax or language support. Every provider declares one `input` mode.
+`text` receives the bounded canonical text snapshot and may return structured,
+table, text, design-token, or bounded inspector data. `document` receives metadata
+only and may select a declared HTML, SVG, or raster renderer for the exact source
+snapshot; it never receives bytes, resource URLs, markup, DOM, Vue, filesystem or
+native handles, or a WebView. HTML resources declare their script, console, and
+project-subresource policy explicitly. The host validates the bounded result,
+mints and disposes the canonical resource session, confines project resources,
+and owns the renderer.

package/dist/agent/capabilities.d.ts

@@ -0,0 +1,29 @@
+import { AI_MODEL_CAPABILITIES, AI_PROVIDER_CAPABILITIES } from "../capabilities.js";
+export { AI_MODEL_CAPABILITIES, AI_PROVIDER_CAPABILITIES };
+export type AIModelCapability = (typeof AI_MODEL_CAPABILITIES)[number];
+export type AIProviderCapability = (typeof AI_PROVIDER_CAPABILITIES)[number];
+/** Exact capabilities a harness needs from one provider/model pair. */
+export interface AgentProviderRequirements {
+    readonly providerCapabilities: readonly AIProviderCapability[];
+    readonly modelCapabilities: readonly AIModelCapability[];
+}
+/** Capabilities advertised by a provider contribution before activation. */
+export interface AIProviderCapabilitySelector {
+    readonly providerCapabilities: readonly AIProviderCapability[];
+    /** Capabilities offered by at least one model exposed by this provider. */
+    readonly modelCapabilities: readonly AIModelCapability[];
+}
+export interface AIModelDescriptor {
+    readonly id: string;
+    readonly label: string;
+    readonly capabilities: readonly AIModelCapability[];
+    readonly contextWindow?: number;
+    readonly maximumOutputTokens?: number;
+}
+/**
+ * Capability matching is conjunctive and exact. An unadvertised capability is
+ * incompatible; the host never guesses support or substitutes another model.
+ */
+export declare function providerMatchesAgentRequirements(selector: AIProviderCapabilitySelector, requirements: AgentProviderRequirements): boolean;
+export declare function modelMatchesAgentRequirements(model: Pick<AIModelDescriptor, "capabilities">, requirements: Pick<AgentProviderRequirements, "modelCapabilities">): boolean;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/agent/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/agent/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,CAAC;AAE3D,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E,uEAAuE;AACvE,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,oBAAoB,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC/D,QAAQ,CAAC,iBAAiB,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC1D;AAED,4EAA4E;AAC5E,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,oBAAoB,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC/D,2EAA2E;IAC3E,QAAQ,CAAC,iBAAiB,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC1D;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACpD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAUD;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,4BAA4B,EACtC,YAAY,EAAE,yBAAyB,GACtC,OAAO,CAQT;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,IAAI,CAAC,iBAAiB,EAAE,cAAc,CAAC,EAC9C,YAAY,EAAE,IAAI,CAAC,yBAAyB,EAAE,mBAAmB,CAAC,GACjE,OAAO,CAET"}

package/dist/agent/capabilities.js

@@ -0,0 +1,18 @@
+import { AI_MODEL_CAPABILITIES, AI_PROVIDER_CAPABILITIES, } from "../capabilities.js";
+export { AI_MODEL_CAPABILITIES, AI_PROVIDER_CAPABILITIES };
+function containsEvery(available, required) {
+    const availableSet = new Set(available);
+    return required.every((capability) => availableSet.has(capability));
+}
+/**
+ * Capability matching is conjunctive and exact. An unadvertised capability is
+ * incompatible; the host never guesses support or substitutes another model.
+ */
+export function providerMatchesAgentRequirements(selector, requirements) {
+    return (containsEvery(selector.providerCapabilities, requirements.providerCapabilities) &&
+        containsEvery(selector.modelCapabilities, requirements.modelCapabilities));
+}
+export function modelMatchesAgentRequirements(model, requirements) {
+    return containsEvery(model.capabilities, requirements.modelCapabilities);
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/agent/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/agent/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,CAAC;AA2B3D,SAAS,aAAa,CACpB,SAAuB,EACvB,QAAsB;IAEtB,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;IACxC,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gCAAgC,CAC9C,QAAsC,EACtC,YAAuC;IAEvC,OAAO,CACL,aAAa,CACX,QAAQ,CAAC,oBAAoB,EAC7B,YAAY,CAAC,oBAAoB,CAClC;QACD,aAAa,CAAC,QAAQ,CAAC,iBAAiB,EAAE,YAAY,CAAC,iBAAiB,CAAC,CAC1E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,KAA8C,EAC9C,YAAkE;IAElE,OAAO,aAAa,CAAC,KAAK,CAAC,YAAY,EAAE,YAAY,CAAC,iBAAiB,CAAC,CAAC;AAC3E,CAAC"}

package/dist/agent/contributions.d.ts

@@ -0,0 +1,32 @@
+import type { AgentProviderRequirements, AIProviderCapabilitySelector } from "./capabilities.js";
+export interface AgentHarnessContribution {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+    /** Competing harnesses in the same group require a deterministic selection. */
+    readonly group: string;
+    readonly priority: number;
+    readonly composition: "exclusive";
+    /** Symbolic package module resolved from the verified active manifest. */
+    readonly module: string;
+    readonly export: string;
+    readonly providerRequirements: AgentProviderRequirements;
+    readonly lifecycle: {
+        /** Delay after final session demand ends before the harness is disposed. */
+        readonly idleTimeoutMs: number;
+    };
+}
+export interface AIProviderContribution {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+    /** Competing providers in the same group require a deterministic selection. */
+    readonly group: string;
+    readonly priority: number;
+    readonly composition: "exclusive";
+    /** Symbolic package module resolved from the verified active manifest. */
+    readonly module: string;
+    readonly export: string;
+    readonly selector: AIProviderCapabilitySelector;
+}
+//# sourceMappingURL=contributions.d.ts.map

package/dist/agent/contributions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contributions.d.ts","sourceRoot":"","sources":["../../src/agent/contributions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,yBAAyB,EACzB,4BAA4B,EAC7B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,oBAAoB,EAAE,yBAAyB,CAAC;IACzD,QAAQ,CAAC,SAAS,EAAE;QAClB,4EAA4E;QAC5E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;KAChC,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,4BAA4B,CAAC;CACjD"}

package/dist/agent/contributions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contributions.js.map

package/dist/agent/contributions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contributions.js","sourceRoot":"","sources":["../../src/agent/contributions.ts"],"names":[],"mappings":""}

package/dist/agent/protocol.d.ts

@@ -0,0 +1,211 @@
+import type { ExtensionJsonObject, ExtensionJsonValue } from "../contracts/json.js";
+import type { ExtensionStreamSink } from "../contract.js";
+import type { AIModelDescriptor } from "./capabilities.js";
+export interface AgentContributionReference {
+    readonly extensionId: string;
+    readonly contributionId: string;
+}
+export type AgentMessageRole = "system" | "user" | "assistant" | "tool";
+export type AgentMessagePart = {
+    readonly kind: "text";
+    readonly text: string;
+} | {
+    readonly kind: "asset";
+    /** Host-owned opaque asset reference; never a filesystem path. */
+    readonly assetId: string;
+    readonly mediaType: string;
+    readonly name?: string;
+} | {
+    readonly kind: "toolCall";
+    readonly callId: string;
+    readonly tool: string;
+    readonly input: ExtensionJsonObject;
+} | {
+    readonly kind: "toolResult";
+    readonly callId: string;
+    readonly output: ExtensionJsonValue;
+    readonly isError: boolean;
+};
+export interface AgentConversationMessage {
+    readonly id: string;
+    readonly role: AgentMessageRole;
+    readonly parts: readonly AgentMessagePart[];
+}
+export interface AgentToolDescriptor {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: ExtensionJsonObject;
+}
+export interface AgentSessionOpenRequest {
+    readonly sessionId: string;
+    readonly workspaceId: string;
+    readonly harness: AgentContributionReference;
+    readonly provider: AgentContributionReference;
+    readonly modelId: string;
+    /** Host-owned persisted transcript supplied as an immutable snapshot. */
+    readonly history: readonly AgentConversationMessage[];
+}
+export interface AgentPromptRequest {
+    readonly requestId: string;
+    readonly sessionId: string;
+    readonly message: AgentConversationMessage;
+}
+export type AgentCancellationReason = "user" | "superseded" | "sessionClosed" | "hostShutdown";
+/** Serializable cancellation message sent across the extension boundary. */
+export interface AgentCancellationRequest {
+    readonly requestId: string;
+    readonly sessionId: string;
+    readonly reason: AgentCancellationReason;
+}
+export type AgentSessionCloseReason = "idle" | "user" | "hostShutdown";
+export interface AgentSessionCloseRequest {
+    readonly sessionId: string;
+    readonly reason: AgentSessionCloseReason;
+}
+export interface AgentHostToolRequest {
+    readonly requestId: string;
+    readonly sessionId: string;
+    readonly tool: string;
+    readonly input: ExtensionJsonObject;
+}
+export interface AgentHostToolResult {
+    readonly requestId: string;
+    readonly output: ExtensionJsonValue;
+    readonly isError: boolean;
+}
+export interface AgentWorkspaceTextEdit {
+    readonly uri: string;
+    readonly version: number;
+    readonly edits: readonly {
+        readonly from: number;
+        readonly to: number;
+        readonly text: string;
+    }[];
+}
+export interface AgentWorkspaceEditProposalRequest {
+    readonly requestId: string;
+    readonly sessionId: string;
+    readonly summary: string;
+    readonly changes: readonly AgentWorkspaceTextEdit[];
+}
+export interface AgentWorkspaceEditProposalResult {
+    readonly requestId: string;
+    readonly proposalId: string;
+    readonly status: "pendingReview";
+}
+export interface AIProviderModelListRequest {
+    readonly requestId: string;
+    readonly provider: AgentContributionReference;
+}
+export interface AIProviderModelListResult {
+    readonly requestId: string;
+    readonly models: readonly AIModelDescriptor[];
+}
+export interface AIProviderStreamRequest {
+    readonly requestId: string;
+    readonly sessionId: string;
+    readonly provider: AgentContributionReference;
+    readonly modelId: string;
+    readonly messages: readonly AgentConversationMessage[];
+    readonly tools: readonly AgentToolDescriptor[];
+    /** Validated provider-owned settings. Credentials stay in the host vault. */
+    readonly settings: ExtensionJsonObject;
+}
+export interface AIProviderUsage {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly cachedInputTokens?: number;
+    readonly reasoningTokens?: number;
+}
+export interface AgentProtocolError {
+    readonly code: string;
+    readonly message: string;
+    readonly retryable: boolean;
+}
+/** JSON-only stream frames emitted independently by a selected provider. */
+export type AIProviderStreamEvent = {
+    readonly kind: "started";
+    readonly requestId: string;
+} | {
+    readonly kind: "textDelta";
+    readonly requestId: string;
+    readonly delta: string;
+} | {
+    readonly kind: "reasoningDelta";
+    readonly requestId: string;
+    readonly delta: string;
+} | {
+    readonly kind: "toolCall";
+    readonly requestId: string;
+    readonly callId: string;
+    readonly tool: string;
+    readonly input: ExtensionJsonObject;
+} | {
+    readonly kind: "usage";
+    readonly requestId: string;
+    readonly usage: AIProviderUsage;
+} | {
+    readonly kind: "completed";
+    readonly requestId: string;
+    readonly finishReason: "stop" | "length" | "toolCalls";
+} | {
+    readonly kind: "cancelled";
+    readonly requestId: string;
+    readonly reason: AgentCancellationReason;
+} | {
+    readonly kind: "failed";
+    readonly requestId: string;
+    readonly error: AgentProtocolError;
+};
+export type AgentHarnessStreamEvent = AIProviderStreamEvent | {
+    readonly kind: "status";
+    readonly requestId: string;
+    readonly status: "planning" | "runningTool" | "waitingForApproval";
+    readonly label?: string;
+} | {
+    readonly kind: "workspaceEdit";
+    readonly requestId: string;
+    /** Opaque host-staged edit proposal; application remains host-owned. */
+    readonly proposalId: string;
+    readonly summary: string;
+};
+export type AgentStreamSink<TEvent> = ExtensionStreamSink<TEvent>;
+/** Exact selected-provider route. The host owns dispatch and permissions. */
+export interface AgentAIProviderBroker {
+    listModels(request: AIProviderModelListRequest): Promise<AIProviderModelListResult>;
+    stream(request: AIProviderStreamRequest, sink: AgentStreamSink<AIProviderStreamEvent>): Promise<void>;
+    cancel(request: AgentCancellationRequest): Promise<void>;
+}
+export interface AgentToolBroker {
+    invoke(request: AgentHostToolRequest): Promise<AgentHostToolResult>;
+}
+export interface AgentWorkspaceEditBroker {
+    stage(request: AgentWorkspaceEditProposalRequest): Promise<AgentWorkspaceEditProposalResult>;
+}
+/** Services mediated by the host; none grants direct native or WebView access. */
+export interface AgentHarnessHostServices {
+    readonly provider: AgentAIProviderBroker;
+    readonly tools: AgentToolBroker;
+    readonly workspaceEdits: AgentWorkspaceEditBroker;
+}
+/** Runtime object returned by the one selected harness contribution. */
+export interface AgentHarnessSession {
+    submit(request: AgentPromptRequest, sink: AgentStreamSink<AgentHarnessStreamEvent>): Promise<void>;
+    cancel(request: AgentCancellationRequest): Promise<void>;
+    dispose(request: AgentSessionCloseRequest): Promise<void>;
+}
+export interface AgentHarnessSessionActivator {
+    activate(request: AgentSessionOpenRequest, host: AgentHarnessHostServices): Promise<AgentHarnessSession>;
+}
+/** Package-level harness instance; individual sessions dispose independently. */
+export interface AgentHarnessAdapter extends AgentHarnessSessionActivator {
+    dispose(): void | Promise<void>;
+}
+/** Runtime object returned by the one selected provider contribution. */
+export interface AIProviderAdapter {
+    listModels(request: AIProviderModelListRequest): Promise<AIProviderModelListResult>;
+    stream(request: AIProviderStreamRequest, sink: AgentStreamSink<AIProviderStreamEvent>): Promise<void>;
+    cancel(request: AgentCancellationRequest): Promise<void>;
+    dispose(): void | Promise<void>;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/agent/protocol.d.ts.map

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

package/dist/agent/protocol.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=protocol.js.map

package/dist/agent/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/agent/protocol.ts"],"names":[],"mappings":""}

package/dist/capabilities.d.ts

@@ -0,0 +1,17 @@
+export declare const AI_MODEL_CAPABILITIES: readonly [
+  "text",
+  "vision",
+  "multipleImages",
+  "toolCalling",
+  "reasoning",
+  "structuredOutput",
+];
+
+export declare const AI_PROVIDER_CAPABILITIES: readonly [
+  "modelDiscovery",
+  "streaming",
+  "usage",
+  "endpointSelection",
+  "serviceTier",
+  "providerWebSearch",
+];

package/dist/capabilities.js

@@ -0,0 +1,17 @@
+export const AI_MODEL_CAPABILITIES = Object.freeze([
+  "text",
+  "vision",
+  "multipleImages",
+  "toolCalling",
+  "reasoning",
+  "structuredOutput",
+]);
+
+export const AI_PROVIDER_CAPABILITIES = Object.freeze([
+  "modelDiscovery",
+  "streaming",
+  "usage",
+  "endpointSelection",
+  "serviceTier",
+  "providerWebSearch",
+]);