@ottimis/jack-provider-sdk 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# `@ottimis/jack-provider-sdk`
+
+Plugin contract for AI provider integrations in [Jack](https://github.com/ottimis/JACK). Every package that drives an AI coding agent inside Jack — `jack-claude`, `jack-codex`, `jack-gemini`, future `jack-<name>` — depends on this SDK and exports a single `JackProvider` object that satisfies the contract here.
+
+## What's in the box
+
+Three layers, all re-exported from the package root:
+
+- **`./backend`** — neutral wire-shape contract: `AgentBackend`, `AgentQueryOptions`, `AgentSession`, `AgentPermissionMode`, `AgentEffortLevel`, `AgentHooks`, `BackendName` (open string union — `'sdk'`, `'cli'`, `'acp'`, …), `AgentForkSessionOptions`, `AgentListSessionsOptions`.
+- **`./spawner`** — process-spawning primitives shared by every backend: `ProcessSpawner`, `ProcessHandle`, `SpawnArgs`, `localSpawner`. The host can swap `localSpawner` for a Docker variant (`createDockerSpawner()`) and providers won't notice.
+- **`./provider`** — plugin-level contract: `JackProvider`, `CapabilityMatrix`, `ToolDescriptor`, `ProviderBranding`, `ProviderModelOption`, `ProviderModelDefaults`, `KnowledgeContext`, `KnowledgeMcpResolution`, `SlashCommandSupport`, `SlashCommandDef`, `PrepareSpawnContext`, `InProcessMcpServerSpec`, `PersistedPermissionsApi`, `ProviderDetectResult`, `BackendDescriptor`.
+
+`NormalizedMessage` and other wire-shape canonicals are re-exported from `@ottimis/jack-chat-core` so consumers don't need a direct dep on chat-core when their only entrypoint is the wire shape.
+
+## Install
+
+```bash
+pnpm add @ottimis/jack-provider-sdk @ottimis/jack-chat-core
+```
+
+`@ottimis/jack-chat-core` is a peer dep — pin a compatible version in your provider package.
+
+## Implementing a `JackProvider`
+
+```ts
+import type { JackProvider } from '@ottimis/jack-provider-sdk'
+
+export const myProvider: JackProvider = {
+  id: 'my-agent',
+  label: 'My Agent',
+  branding: { accentColor: '#ff6b6b', iconKey: 'sparkles' },
+  detect: async () => ({ installed: true }),
+  backends: [{ id: 'sdk', label: 'SDK backend', factory: () => myBackend }],
+  defaultBackendId: 'sdk',
+  capabilities: { /* honest declaration — see CapabilityMatrix */ },
+  modelDefaults: { oneShot: 'my-cheap-model' },
+  toolCatalog: [/* ToolDescriptor[] */],
+  parseToolName: (raw) => ({ kind: 'native', toolName: raw }),
+  applyKnowledgeContext: (ctx, opts) => { /* fold into native opts */ },
+  readSessionTranscript: async (opts) => { /* on-disk replay */ }
+}
+```
+
+Full contract documented in the consumer repo: [`docs/provider-package-spec.md`](https://github.com/ottimis/JACK/blob/main/docs/provider-package-spec.md).
+
+## Versioning
+
+- **Minor** bumps add optional fields to `JackProvider` / `CapabilityMatrix` / `ToolShape`. Existing providers keep working.
+- **Major** bumps rename or restructure required fields. Provider authors update their pinned range.
+
+The host (Jack) declares the minimum SDK version it supports. The plugin loader (Phase 5 follow-up) rejects packages whose declared `peerDependencies.@ottimis/jack-provider-sdk` doesn't satisfy the host's range.
+
+## Build & test
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+`pnpm build` produces dual ESM (`dist/`) + CJS (`dist/cjs/`) output with declaration files. `dist/cjs/package.json` is auto-written with `{ "type": "commonjs" }` so Node resolves the right module format.

package/dist/backend.d.ts

@@ -0,0 +1,256 @@
+/**
+ * AgentBackend — abstraction that lets the host talk to an AI provider via
+ * one of its concrete backends (Claude SDK / Claude CLI / Codex / Gemini ACP / …).
+ *
+ * Every type on this surface is **provider-neutral**: no SDK/Claude type
+ * leaks past this boundary. Each provider package translates between its
+ * native wire format and these neutral types inside the backend
+ * implementation. The host never imports from a provider's native SDK
+ * directly.
+ *
+ *   - The output stream is {@link NormalizedMessage} (parsed by the
+ *     provider's translator).
+ *   - The {@link AgentQueryOptions.canUseTool} callback receives a
+ *     {@link NormalizedPermissionRequest} and resolves to a
+ *     {@link NormalizedPermissionResult} — the provider does the wire
+ *     translation on both sides.
+ *   - The {@link AgentHooks} pipeline is fed {@link NormalizedHookEvent}s.
+ *   - Provider-private spawn details (e.g. Claude SDK's `executable` +
+ *     `pathToClaudeCodeExecutable`) ride in the
+ *     {@link AgentQueryOptions.providerSpawnHints} escape hatch — the host
+ *     populates them via `JackProvider.prepareSpawnOptions` and never
+ *     inspects the contents.
+ *
+ * Selection happens in the host's `backendFactory` → which delegates to
+ * the provider registry.
+ */
+import type { ProcessSpawner } from './spawner';
+import type { NormalizedMessage, NormalizedPermissionRequest, NormalizedPermissionResult, NormalizedHookEvent } from '@ottimis/jack-chat-core';
+/**
+ * Open string union — every provider declares its own backend ids. Today
+ * `'sdk'` and `'cli'` are Claude-specific; Gemini ships `'acp'`. The host
+ * resolves the active backend by id against the provider's `backends[]`
+ * list, so widening to `string` is required for non-Claude providers.
+ */
+export type BackendName = string;
+/** Permission gate behaviour. Strings the host may toggle live. */
+export type AgentPermissionMode = 'default' | 'acceptEdits' | 'plan' | 'bypassPermissions';
+/** Settings layers the provider should consult at boot. */
+export type AgentSettingSource = 'user' | 'project' | 'local';
+/**
+ * System prompt shape: a plain string (provider replaces its default), or
+ * a preset envelope with an optional append (provider extends its default).
+ * The preset name is provider-specific; today only `'claude_code'` exists.
+ */
+export type AgentSystemPrompt = string | {
+    type: 'preset';
+    preset: string;
+    append?: string;
+};
+/**
+ * MCP server configuration — opaque to the host. The host never inspects
+ * the inner shape; each provider validates / consumes its own format.
+ */
+export type AgentMcpServerConfig = unknown;
+/** Reasoning-effort knob. Provider-validated; not all providers honor every value. */
+export type AgentEffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/**
+ * Hook handler — receives a normalized lifecycle event and may return an
+ * opaque object the provider interprets (e.g. `{ continue: false }` to
+ * abort a tool call). Most handlers just return `undefined`.
+ */
+export type AgentHookHandler = (event: NormalizedHookEvent) => Promise<unknown> | unknown;
+export type AgentHookMatcher = {
+    /**
+     * Glob over tool names. `'*'` matches every tool. Semantics provider-side
+     * but every provider understands `'*'`.
+     */
+    matcher: string;
+    hooks: AgentHookHandler[];
+    timeout?: number;
+};
+export type AgentHooks = {
+    preToolUse?: AgentHookMatcher[];
+    postToolUse?: AgentHookMatcher[];
+};
+/**
+ * Context window usage snapshot returned by {@link AgentSession.getContextUsage}.
+ * Loose-typed because providers expose different breakdowns; the renderer
+ * picks `totalTokens` / `maxTokens` / `percentage` and falls back to the
+ * raw bag for advanced UI.
+ */
+export type AgentContextUsage = {
+    total?: number;
+    totalTokens?: number;
+    maxTokens?: number;
+    rawMaxTokens?: number;
+    percentage?: number;
+    model?: string;
+    by_category?: Record<string, number>;
+    [k: string]: unknown;
+};
+/**
+ * Listing entry for `~/.claude/projects/<encoded>/<uuid>.jsonl` (or its
+ * equivalent under future providers). Loose-typed: providers may expose
+ * extra fields that the scanner just passes through.
+ */
+export type AgentSessionInfo = {
+    sessionId: string;
+    cwd?: string;
+    summary?: string;
+    customTitle?: string | null;
+    firstPrompt?: string | null;
+    lastModified?: number;
+    createdAt?: number | null;
+    gitBranch?: string | null;
+    fileSize?: number;
+    [k: string]: unknown;
+};
+/**
+ * One turn of input the host pushes onto the prompt queue. Plain text today
+ * — providers wrap it into their wire-native user-message envelope. When a
+ * future host needs to push richer turns (e.g. images), this can grow into
+ * a structured union without breaking the queue contract.
+ */
+export type AgentUserPrompt = string;
+/**
+ * Options the host hands to {@link AgentBackend.query}. All fields are
+ * neutral; provider-private extras live behind {@link providerSpawnHints}.
+ */
+export type AgentQueryOptions = {
+    cwd?: string;
+    permissionMode?: AgentPermissionMode;
+    includePartialMessages?: boolean;
+    settingSources?: AgentSettingSource[];
+    agentProgressSummaries?: boolean;
+    allowedTools?: string[];
+    systemPrompt?: AgentSystemPrompt;
+    /**
+     * Extra working directories beyond `cwd` that the agent can Read/Write
+     * across. Populated via `JackProvider.applyKnowledgeContext` from the
+     * merged KnowledgeContext (workspace tree + AgentDefinition `kind=dir`
+     * knowledge sources).
+     */
+    additionalDirectories?: string[];
+    mcpServers?: Record<string, AgentMcpServerConfig>;
+    resume?: string;
+    /**
+     * Initial model for the spawn. Live switches use
+     * {@link AgentSession.setModel}.
+     */
+    model?: string;
+    /**
+     * Initial effort level for the spawn. Live switches use
+     * {@link AgentSession.applyFlagSettings} with `{ effortLevel: ... }`.
+     */
+    effort?: AgentEffortLevel;
+    /**
+     * Process spawner — decides how the provider's child process is launched.
+     * Defaults to running locally. For sandboxed sessions, the host passes a
+     * spawner created by `createDockerSpawner()`.
+     */
+    spawner?: ProcessSpawner;
+    /** Extra env vars merged into the spawned process environment. */
+    env?: {
+        [key: string]: string | undefined;
+    };
+    /**
+     * Provider-private spawn details. Populated by
+     * `JackProvider.prepareSpawnOptions` and consumed by the matching backend
+     * implementation. The host treats this bag as opaque — never read or
+     * mutate the inner fields outside the provider package.
+     *
+     * Today the Claude provider stores `executable` and
+     * `pathToClaudeCodeExecutable` here so the SDK backend can locate the
+     * asar-unpacked `cli.js` + the macOS Electron Helper.
+     */
+    providerSpawnHints?: Record<string, unknown>;
+    /**
+     * Permission gate. Receives a {@link NormalizedPermissionRequest} and
+     * resolves to a {@link NormalizedPermissionResult}. Each provider's
+     * backend translates between its wire format and these neutral shapes.
+     */
+    canUseTool?: (req: NormalizedPermissionRequest) => Promise<NormalizedPermissionResult>;
+    hooks?: AgentHooks;
+};
+export type AgentQueryInput = {
+    prompt: AgentUserPrompt | AsyncIterable<AgentUserPrompt>;
+    options: AgentQueryOptions;
+};
+/**
+ * Session-like object returned by backend.query(). Mirrors the subset of
+ * the provider's runtime control surface that the host actually depends
+ * on — intentionally narrow to keep backend implementations small.
+ */
+export interface AgentSession extends AsyncIterable<NormalizedMessage> {
+    interrupt(): Promise<void>;
+    close(): void;
+    getContextUsage(): Promise<AgentContextUsage>;
+    stopTask(taskId: string): Promise<void>;
+    /**
+     * Switch permission mode live, without respawning the child process.
+     * Mirrors the CLI's Shift+Tab cycle (Claude provider).
+     */
+    setPermissionMode(mode: AgentPermissionMode | undefined): Promise<void>;
+    /**
+     * Switch the model live. Pass `undefined` to clear any override and
+     * fall back to the provider default.
+     */
+    setModel(model?: string): Promise<void>;
+    /**
+     * Merge arbitrary settings into the flag-settings layer at runtime.
+     * Used for values the provider exposes only as persisted flags
+     * (notably `effortLevel` on Claude).
+     */
+    applyFlagSettings(settings: Record<string, unknown>): Promise<void>;
+    /**
+     * Read the effective merged settings layer. The response shape is
+     * `{ effective, sources }` where `effective` is the deep-merged result.
+     * The host uses it to discover the runtime `effortLevel` the provider
+     * booted with.
+     */
+    getSettings(): Promise<AgentSettingsResponse>;
+}
+/**
+ * Slimmed-down shape of the `get_settings` response. Providers may surface
+ * hundreds of fields; we only look at the bits the host cares about and
+ * keep the rest opaque.
+ */
+export type AgentSettingsResponse = {
+    effective?: {
+        effortLevel?: string;
+        [key: string]: unknown;
+    };
+    sources?: Record<string, unknown>;
+};
+/** Options for backend.listSessions(). */
+export type AgentListSessionsOptions = {
+    dir?: string;
+    limit?: number;
+    offset?: number;
+};
+/** Options for backend.forkSession(). */
+export type AgentForkSessionOptions = {
+    dir?: string;
+    upToMessageId?: string;
+    title?: string;
+};
+export interface AgentBackend {
+    readonly name: BackendName;
+    query(input: AgentQueryInput): AgentSession;
+    /**
+     * List provider sessions on disk. Each backend reads its provider's
+     * native transcript layout (`~/.claude/projects/...`,
+     * `~/.codex/sessions/...`, `~/.gemini/tmp/.../chats/...`).
+     */
+    listSessions(opts?: AgentListSessionsOptions): Promise<AgentSessionInfo[]>;
+    /** Persist a custom title for a session. */
+    renameSession(sessionId: string, title: string, opts?: {
+        dir?: string;
+    }): Promise<void>;
+    /** Fork a session into a new one (optionally truncated at a cutoff message). */
+    forkSession(sessionId: string, opts?: AgentForkSessionOptions): Promise<{
+        sessionId: string;
+    }>;
+}
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

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

package/dist/backend.js

@@ -0,0 +1,28 @@
+/**
+ * AgentBackend — abstraction that lets the host talk to an AI provider via
+ * one of its concrete backends (Claude SDK / Claude CLI / Codex / Gemini ACP / …).
+ *
+ * Every type on this surface is **provider-neutral**: no SDK/Claude type
+ * leaks past this boundary. Each provider package translates between its
+ * native wire format and these neutral types inside the backend
+ * implementation. The host never imports from a provider's native SDK
+ * directly.
+ *
+ *   - The output stream is {@link NormalizedMessage} (parsed by the
+ *     provider's translator).
+ *   - The {@link AgentQueryOptions.canUseTool} callback receives a
+ *     {@link NormalizedPermissionRequest} and resolves to a
+ *     {@link NormalizedPermissionResult} — the provider does the wire
+ *     translation on both sides.
+ *   - The {@link AgentHooks} pipeline is fed {@link NormalizedHookEvent}s.
+ *   - Provider-private spawn details (e.g. Claude SDK's `executable` +
+ *     `pathToClaudeCodeExecutable`) ride in the
+ *     {@link AgentQueryOptions.providerSpawnHints} escape hatch — the host
+ *     populates them via `JackProvider.prepareSpawnOptions` and never
+ *     inspects the contents.
+ *
+ * Selection happens in the host's `backendFactory` → which delegates to
+ * the provider registry.
+ */
+export {};
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

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

package/dist/cjs/backend.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * AgentBackend — abstraction that lets the host talk to an AI provider via
+ * one of its concrete backends (Claude SDK / Claude CLI / Codex / Gemini ACP / …).
+ *
+ * Every type on this surface is **provider-neutral**: no SDK/Claude type
+ * leaks past this boundary. Each provider package translates between its
+ * native wire format and these neutral types inside the backend
+ * implementation. The host never imports from a provider's native SDK
+ * directly.
+ *
+ *   - The output stream is {@link NormalizedMessage} (parsed by the
+ *     provider's translator).
+ *   - The {@link AgentQueryOptions.canUseTool} callback receives a
+ *     {@link NormalizedPermissionRequest} and resolves to a
+ *     {@link NormalizedPermissionResult} — the provider does the wire
+ *     translation on both sides.
+ *   - The {@link AgentHooks} pipeline is fed {@link NormalizedHookEvent}s.
+ *   - Provider-private spawn details (e.g. Claude SDK's `executable` +
+ *     `pathToClaudeCodeExecutable`) ride in the
+ *     {@link AgentQueryOptions.providerSpawnHints} escape hatch — the host
+ *     populates them via `JackProvider.prepareSpawnOptions` and never
+ *     inspects the contents.
+ *
+ * Selection happens in the host's `backendFactory` → which delegates to
+ * the provider registry.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=backend.js.map

package/dist/cjs/backend.js.map

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

package/dist/cjs/index.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * `@ottimis/jack-provider-sdk` — public surface for AI provider plugins.
+ *
+ * In-tree providers (Claude, Codex, Gemini) and any future external
+ * package import every neutral type + primitive from here. The host
+ * imports from here too so a provider package depends only on this SDK
+ * (not on Jack's main process internals) and Jack stays free to evolve
+ * its host code without breaking provider authors.
+ *
+ * Re-exports cover three layers:
+ *   - `./backend` — neutral wire-shape contract (`AgentBackend`,
+ *     `AgentQueryOptions`, `AgentSession`, …)
+ *   - `./spawner` — process-spawning primitives shared by every backend
+ *     (`ProcessSpawner`, `ProcessHandle`, `localSpawner`, …)
+ *   - `./provider` — plugin-level contract (`JackProvider`,
+ *     `CapabilityMatrix`, `ToolDescriptor`, `ProviderBranding`, …)
+ *
+ * Companion runtime types from `@ottimis/jack-chat-core` (`NormalizedMessage`,
+ * `ClientToolHandler`, `ToolShape`, …) are re-exported through `./provider`
+ * so consumers don't need to import from chat-core directly when they only
+ * need the canonical wire shapes.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./backend"), exports);
+__exportStar(require("./spawner"), exports);
+__exportStar(require("./provider"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;;;;;;;;;;;;;;AAEH,4CAAyB;AACzB,4CAAyB;AACzB,6CAA0B"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/provider.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * JackProvider — plugin contract for an AI provider integration.
+ *
+ * A provider package (in-tree `providers/claude/`, future external
+ * `jack-codex`, `jack-gemini`, …) registers a single `JackProvider` object
+ * that wires up everything the host needs to drive that AI:
+ *
+ *   - one or more {@link BackendDescriptor}s (the wire-protocol implementations)
+ *   - a {@link CapabilityMatrix} so the UI knows what features to show
+ *   - a {@link ToolDescriptor} catalog so the renderer can map provider-native
+ *     tool names to canonical Jack shapes
+ *   - a {@link JackProvider.detect} probe so the gate UI can warn when the
+ *     host lacks a usable installation
+ *
+ * This file is the boundary between Jack core and a provider package — keep
+ * it free of provider-specific imports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=provider.js.map

package/dist/cjs/provider.js.map

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

package/dist/cjs/spawner.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * ProcessSpawner — abstraction over "how we get a running provider CLI
+ * with stdin/stdout pipes attached". Consumed by every backend so they
+ * don't need to know whether the process runs locally or inside a Docker
+ * container.
+ *
+ * Design goals:
+ *   - The shape matches the Anthropic SDK's `SpawnedProcess` / `SpawnOptions`
+ *     exactly, so a single spawner can be fed to that SDK without
+ *     translation. Other providers happily reuse the same shape.
+ *   - The only Docker-aware code lives in the host's `docker/sandbox.ts`
+ *     which exposes a `createDockerSpawner()` that returns a ProcessSpawner.
+ *   - The host decides which spawner to use based on `session.sandboxed`
+ *     and hands it to the provider via `AgentQueryOptions.spawner`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localSpawner = void 0;
+const node_child_process_1 = require("node:child_process");
+/**
+ * Default local spawner — plain `child_process.spawn`. The returned
+ * ChildProcess satisfies ProcessHandle because we pipe all three streams.
+ */
+const localSpawner = ({ command, args, cwd, env, signal }) => {
+    const cp = (0, node_child_process_1.spawn)(command, args, {
+        cwd,
+        env,
+        stdio: ['pipe', 'pipe', 'pipe']
+    });
+    signal.addEventListener('abort', () => {
+        if (!cp.killed) {
+            try {
+                cp.kill('SIGTERM');
+            }
+            catch { /* ignore */ }
+        }
+    });
+    return cp;
+};
+exports.localSpawner = localSpawner;
+//# sourceMappingURL=spawner.js.map

package/dist/cjs/spawner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawner.js","sourceRoot":"","sources":["../../src/spawner.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAEH,2DAA+E;AAqC/E;;;GAGG;AACI,MAAM,YAAY,GAAmB,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE;IAClF,MAAM,EAAE,GAAmC,IAAA,0BAAK,EAAC,OAAO,EAAE,IAAI,EAAE;QAC9D,GAAG;QACH,GAAG;QACH,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KAChC,CAAC,CAAA;IACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;QACpC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC;YACf,IAAI,CAAC;gBAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;QACnD,CAAC;IACH,CAAC,CAAC,CAAA;IACF,OAAO,EAAE,CAAA;AACX,CAAC,CAAA;AAZY,QAAA,YAAY,gBAYxB"}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `@ottimis/jack-provider-sdk` — public surface for AI provider plugins.
+ *
+ * In-tree providers (Claude, Codex, Gemini) and any future external
+ * package import every neutral type + primitive from here. The host
+ * imports from here too so a provider package depends only on this SDK
+ * (not on Jack's main process internals) and Jack stays free to evolve
+ * its host code without breaking provider authors.
+ *
+ * Re-exports cover three layers:
+ *   - `./backend` — neutral wire-shape contract (`AgentBackend`,
+ *     `AgentQueryOptions`, `AgentSession`, …)
+ *   - `./spawner` — process-spawning primitives shared by every backend
+ *     (`ProcessSpawner`, `ProcessHandle`, `localSpawner`, …)
+ *   - `./provider` — plugin-level contract (`JackProvider`,
+ *     `CapabilityMatrix`, `ToolDescriptor`, `ProviderBranding`, …)
+ *
+ * Companion runtime types from `@ottimis/jack-chat-core` (`NormalizedMessage`,
+ * `ClientToolHandler`, `ToolShape`, …) are re-exported through `./provider`
+ * so consumers don't need to import from chat-core directly when they only
+ * need the canonical wire shapes.
+ */
+export * from './backend';
+export * from './spawner';
+export * from './provider';
+/**
+ * Re-export of `NormalizedMessage` from chat-core so consumers don't need
+ * to depend on it directly when their only entrypoint into the wire shape
+ * is via `AgentBackend`. Mirrors the legacy
+ * `src/main/agent/backend.ts` re-export.
+ */
+export type { NormalizedMessage } from '@ottimis/jack-chat-core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAE1B;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * `@ottimis/jack-provider-sdk` — public surface for AI provider plugins.
+ *
+ * In-tree providers (Claude, Codex, Gemini) and any future external
+ * package import every neutral type + primitive from here. The host
+ * imports from here too so a provider package depends only on this SDK
+ * (not on Jack's main process internals) and Jack stays free to evolve
+ * its host code without breaking provider authors.
+ *
+ * Re-exports cover three layers:
+ *   - `./backend` — neutral wire-shape contract (`AgentBackend`,
+ *     `AgentQueryOptions`, `AgentSession`, …)
+ *   - `./spawner` — process-spawning primitives shared by every backend
+ *     (`ProcessSpawner`, `ProcessHandle`, `localSpawner`, …)
+ *   - `./provider` — plugin-level contract (`JackProvider`,
+ *     `CapabilityMatrix`, `ToolDescriptor`, `ProviderBranding`, …)
+ *
+ * Companion runtime types from `@ottimis/jack-chat-core` (`NormalizedMessage`,
+ * `ClientToolHandler`, `ToolShape`, …) are re-exported through `./provider`
+ * so consumers don't need to import from chat-core directly when they only
+ * need the canonical wire shapes.
+ */
+export * from './backend';
+export * from './spawner';
+export * from './provider';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA"}