@ottimis/jack-provider-sdk 0.1.0

package/dist/provider.js

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

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

package/dist/spawner.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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`.
+ */
+import type { Readable, Writable } from 'node:stream';
+/**
+ * Minimal process handle that both `ChildProcess` (node) and the Anthropic
+ * SDK's `SpawnedProcess` satisfy. Deliberately identical to the SDK
+ * interface so that values of this type can be handed back to the SDK
+ * verbatim.
+ */
+export interface ProcessHandle {
+    stdin: Writable;
+    stdout: Readable;
+    readonly killed: boolean;
+    readonly exitCode: number | null;
+    kill(signal?: NodeJS.Signals): boolean;
+    on(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+    on(event: 'error', listener: (error: Error) => void): void;
+    once(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+    once(event: 'error', listener: (error: Error) => void): void;
+    off(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+    off(event: 'error', listener: (error: Error) => void): void;
+}
+/**
+ * Arguments handed to a spawner. Matches the Anthropic SDK `SpawnOptions`
+ * shape so the same function can be plugged into `spawnClaudeCodeProcess`.
+ */
+export interface SpawnArgs {
+    command: string;
+    args: string[];
+    cwd?: string;
+    env: {
+        [k: string]: string | undefined;
+    };
+    signal: AbortSignal;
+}
+export type ProcessSpawner = (args: SpawnArgs) => ProcessHandle;
+/**
+ * Default local spawner — plain `child_process.spawn`. The returned
+ * ChildProcess satisfies ProcessHandle because we pipe all three streams.
+ */
+export declare const localSpawner: ProcessSpawner;
+//# sourceMappingURL=spawner.d.ts.map

package/dist/spawner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawner.d.ts","sourceRoot":"","sources":["../src/spawner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAErD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,QAAQ,CAAA;IACf,MAAM,EAAE,QAAQ,CAAA;IAChB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAA;IACtC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAA;IAC/F,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAA;IAC1D,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAA;IACjG,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAA;IAC5D,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAA;IAChG,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAA;CAC5D;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,CAAA;IACxC,MAAM,EAAE,WAAW,CAAA;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,SAAS,KAAK,aAAa,CAAA;AAE/D;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,cAY1B,CAAA"}

package/dist/spawner.js

@@ -0,0 +1,37 @@
+/**
+ * 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`.
+ */
+import { spawn } from 'node:child_process';
+/**
+ * Default local spawner — plain `child_process.spawn`. The returned
+ * ChildProcess satisfies ProcessHandle because we pipe all three streams.
+ */
+export const localSpawner = ({ command, args, cwd, env, signal }) => {
+    const cp = spawn(command, args, {
+        cwd,
+        env,
+        stdio: ['pipe', 'pipe', 'pipe']
+    });
+    signal.addEventListener('abort', () => {
+        if (!cp.killed) {
+            try {
+                cp.kill('SIGTERM');
+            }
+            catch { /* ignore */ }
+        }
+    });
+    return cp;
+};
+//# sourceMappingURL=spawner.js.map

package/dist/spawner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawner.js","sourceRoot":"","sources":["../src/spawner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,KAAK,EAAuC,MAAM,oBAAoB,CAAA;AAqC/E;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAmB,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE;IAClF,MAAM,EAAE,GAAmC,KAAK,CAAC,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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ottimis/jack-provider-sdk",
+  "version": "0.1.0",
+  "description": "Plugin contract for AI provider integrations in Jack — backend interface, capability matrix, spawner primitives, knowledge context. Consumed both by in-tree providers and external packages.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ottimis/JACK-provider-sdk.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "pnpm clean && tsc && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'}))\"",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --import tsx tests/*.test.ts",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "@ottimis/jack-chat-core": ">=0.5.5"
+  },
+  "devDependencies": {
+    "@ottimis/jack-chat-core": "^0.5.5",
+    "@types/node": "^22.14.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.8.3"
+  }
+}

package/src/backend.ts

@@ -0,0 +1,291 @@
+/**
+ * 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
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Neutral option types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 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
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Query options & input
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 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 interface
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 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 }>
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * `@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'