@ottimis/jack-provider-sdk 0.4.0 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # `@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.
+Plugin contract for AI provider integrations in 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
 
@@ -41,7 +41,7 @@ export const myProvider: JackProvider = {
 }
 ```
 
-Full contract documented in the consumer repo: [`docs/provider-package-spec.md`](https://github.com/ottimis/JACK/blob/main/docs/provider-package-spec.md).
+Step-by-step walkthrough (Pattern A vs Pattern B, capability matrix, knowledge context, gotchas): [`docs/implementing-a-provider.md`](./docs/implementing-a-provider.md). Full type reference lives in the JSDoc on each exported type.
 
 ## Versioning
 

package/dist/cjs/host.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Host primitives exposed to providers — handed in via
+ * {@link JackProvider.activate} so provider code never imports `electron`,
+ * `better-sqlite3`, or any other host-internal module directly.
+ *
+ * Why this exists
+ * ---------------
+ * In Jack v0.4.x the Claude provider reached into Electron (`safeStorage`,
+ * `BrowserWindow`, `session`) and Jack's settings table (`getSetting` /
+ * `setSetting`) to persist its login cookie. That breaks two goals:
+ *
+ *   1. **Out-of-tree packages.** A future `@third-party/jack-provider-foo`
+ *      installed from npm shouldn't need to know about the host's storage
+ *      layer or its windowing toolkit.
+ *   2. **Testability.** Provider unit tests on plain Node want a fake host
+ *      that returns canned credentials, not a real `safeStorage`.
+ *
+ * `HostServices` is the contract that satisfies both: a tiny set of
+ * primitives the host implements once (with whatever it has — Electron in
+ * Jack's case, but a CLI host could use `keytar` + headless puppeteer)
+ * and providers consume through dependency injection.
+ *
+ * Surface stays intentionally small. New capabilities grow this file as
+ * specific providers need them — but the rule is "host-side knowledge
+ * doesn't leak out the SDK". A provider that needs deep host integration
+ * is a sign that the integration belongs in the host, not in the
+ * provider.
+ *
+ * Lifecycle
+ * ---------
+ * The host calls `provider.activate(host)` once during registration. The
+ * provider stores the `host` reference and uses it lazily — no host
+ * primitive may be invoked before activation. Methods that need the host
+ * must guard accordingly (typically by deferring all work to a closure).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=host.js.map

package/dist/cjs/host.js.map

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

package/dist/cjs/index.js

@@ -8,13 +8,19 @@
  * (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:
+ * Re-exports cover four 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`, …)
+ *   - `./usage` — provider-owned billing/usage surface (`UsageApi`,
+ *     `UsageMetric`, …)
+ *   - `./host` — host primitives injected at activation
+ *     (`HostServices`, `HostKvScope`, `HostAuthService`, …) — providers
+ *     consume these via `JackProvider.activate(host)` instead of
+ *     reaching into Electron / host internals directly.
  *
  * Companion runtime types from `@ottimis/jack-chat-core` (`NormalizedMessage`,
  * `ClientToolHandler`, `ToolShape`, …) are re-exported through `./provider`
@@ -40,4 +46,7 @@ __exportStar(require("./backend"), exports);
 __exportStar(require("./spawner"), exports);
 __exportStar(require("./provider"), exports);
 __exportStar(require("./usage"), exports);
+__exportStar(require("./host"), exports);
+__exportStar(require("./profiles"), exports);
+__exportStar(require("./sandbox"), exports);
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

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

package/dist/cjs/profiles.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Profiles — multiple isolated identities for a single provider.
+ *
+ * A "profile" is an isolated config/identity directory the provider's runtime
+ * can be pointed at via an env var (Claude `CLAUDE_CONFIG_DIR`, Codex
+ * `CODEX_HOME`, Gemini `GEMINI_CONFIG_DIR`, …). Two profiles = two distinct
+ * accounts / login states / agent customizations / history sets, all running
+ * the same provider binary.
+ *
+ * The user-facing scenario this exists for: an employee with separate
+ * "claude-personal" and "claude-work" shell aliases that point CLAUDE_CONFIG_DIR
+ * at different folders. The host turns that into a first-class concept —
+ * choosable per session, with a default per workspace-agent slot — instead of
+ * making the user re-shell their alias every time they switch context.
+ *
+ * Provider opts in by:
+ *   - declaring `capabilities.profiles = true`
+ *   - implementing `JackProvider.profiles` with a {@link ProfilesApi}
+ *   - injecting the right env var inside `applyProfile`
+ *
+ * Storage of the profile *list* lives on the host's per-provider kv (provider
+ * stores it via `host.kv` at activation time). Storage of the profile
+ * *content* (auth, sessions, agents, history) lives inside `configDir` on
+ * disk and is the runtime's concern, not the host's — Jack never reads or
+ * writes inside `configDir`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=profiles.js.map

package/dist/cjs/profiles.js.map

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

package/dist/cjs/sandbox.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * SandboxApi — provider-declared Docker sandbox capability.
+ *
+ * Jack runs sessions in a Docker container ("sandbox mode") to isolate the
+ * provider's CLI from the host filesystem and network. The container itself
+ * is generic — Jack owns the Docker orchestration, security policy (CapDrop,
+ * memory cap, non-privileged), project mount, and user-defined shared
+ * volumes. The PROVIDER-SPECIFIC bits live here:
+ *
+ *   - which image to pull (each provider needs its own CLI installed)
+ *   - which binary name to invoke inside the container (used by the host to
+ *     rewrite host-resolved absolute paths like
+ *     `/Users/foo/.local/bin/claude` to a bare command the container's
+ *     PATH resolves)
+ *   - which config dir to mount (`~/.claude`, `~/.codex`, `~/.gemini`, …)
+ *   - optional env extras
+ *
+ * A provider declaring `sandbox` opts itself into sandbox mode. The
+ * matching capability flag {@link CapabilityMatrix.sandbox} MUST be `true`
+ * — the host derives it from `provider.sandbox != null` at registration.
+ *
+ * Providers that don't declare `sandbox` (or set it to `undefined`) are
+ * treated as sandbox-incompatible: the host hides the toggle in the UI and
+ * blocks spawn-time requests with a clear error.
+ *
+ * The host's distribution model expects images at
+ * `ghcr.io/ottimis/jack-sandbox-<provider-id>:<X.Y.Z>` (monorepo
+ * `github.com/ottimis/JACK-sandbox`). Providers can point `defaultImage`
+ * elsewhere — third-party plugin authors who maintain their own image are
+ * free to host wherever they like.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=sandbox.js.map

package/dist/cjs/sandbox.js.map

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

package/dist/host.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Host primitives exposed to providers — handed in via
+ * {@link JackProvider.activate} so provider code never imports `electron`,
+ * `better-sqlite3`, or any other host-internal module directly.
+ *
+ * Why this exists
+ * ---------------
+ * In Jack v0.4.x the Claude provider reached into Electron (`safeStorage`,
+ * `BrowserWindow`, `session`) and Jack's settings table (`getSetting` /
+ * `setSetting`) to persist its login cookie. That breaks two goals:
+ *
+ *   1. **Out-of-tree packages.** A future `@third-party/jack-provider-foo`
+ *      installed from npm shouldn't need to know about the host's storage
+ *      layer or its windowing toolkit.
+ *   2. **Testability.** Provider unit tests on plain Node want a fake host
+ *      that returns canned credentials, not a real `safeStorage`.
+ *
+ * `HostServices` is the contract that satisfies both: a tiny set of
+ * primitives the host implements once (with whatever it has — Electron in
+ * Jack's case, but a CLI host could use `keytar` + headless puppeteer)
+ * and providers consume through dependency injection.
+ *
+ * Surface stays intentionally small. New capabilities grow this file as
+ * specific providers need them — but the rule is "host-side knowledge
+ * doesn't leak out the SDK". A provider that needs deep host integration
+ * is a sign that the integration belongs in the host, not in the
+ * provider.
+ *
+ * Lifecycle
+ * ---------
+ * The host calls `provider.activate(host)` once during registration. The
+ * provider stores the `host` reference and uses it lazily — no host
+ * primitive may be invoked before activation. Methods that need the host
+ * must guard accordingly (typically by deferring all work to a closure).
+ */
+/**
+ * Per-provider key/value store. Keys are namespaced automatically by the
+ * calling provider's id, so `kv.set('token', x)` from `claudeProvider`
+ * lands in a different bucket than the same call from `codexProvider`.
+ *
+ * Values are strings — callers serialize JSON / numbers / booleans
+ * themselves. `null` from `get` / `getSecret` means "no value stored",
+ * not "value is null"; explicit removal goes through `remove`.
+ *
+ * `setSecret` / `getSecret` route through the host's OS-level keychain
+ * encryption when available (Electron's `safeStorage`, `keytar`, etc.).
+ * `setSecret` MUST throw when no secure storage is available so providers
+ * never silently degrade to plaintext on unsupported systems.
+ */
+export type HostKvScope = {
+    /** Plain (unencrypted) read. */
+    get(key: string): string | null;
+    /** Plain (unencrypted) write. */
+    set(key: string, value: string): void;
+    /** Remove the value at `key`. Idempotent (no-op when the key is absent). */
+    remove(key: string): void;
+    /** Encrypted read. Returns `null` when the key is absent OR the host's secret store can't decrypt (e.g. user wiped keychain). */
+    getSecret(key: string): string | null;
+    /** Encrypted write. Throws when secure storage isn't available — providers should surface a clear error to the user, not fall back to plaintext. */
+    setSecret(key: string, value: string): void;
+};
+/**
+ * Options for {@link HostAuthService.openCookieLoginWindow}.
+ *
+ * The host opens a child auth window at `url` and polls the cookie jar
+ * until `cookieName` appears on `cookieDomain`. When the cookie shows up
+ * the host returns its value and closes the window.
+ *
+ * Each provider's auth flow lives in its own session partition so two
+ * providers can be "logged in" simultaneously without their cookies
+ * colliding in the host's shared cookie store.
+ */
+export type CookieLoginOptions = {
+    /** URL to open in the child window. */
+    url: string;
+    /** Name of the cookie the provider waits for (e.g. `'sessionKey'`). */
+    cookieName: string;
+    /** Cookie domain to scope the lookup (e.g. `'https://claude.ai'`). */
+    cookieDomain: string;
+    /**
+     * Storage partition string for session isolation. Convention:
+     * `persist:<provider-id>-<flow-name>` (e.g. `persist:claude-usage`).
+     * Different partition strings keep parallel logins independent.
+     */
+    partition: string;
+    /** Window title shown in the OS chrome. Default: `'Connect'`. */
+    title?: string;
+    /** Hard timeout in milliseconds. Default: 5 minutes. */
+    timeoutMs?: number;
+    /** Window width in pixels. Default: 520. */
+    width?: number;
+    /** Window height in pixels. Default: 720. */
+    height?: number;
+    /**
+     * Optional parent window the host narrows internally to attach
+     * modality. Typed as `unknown` so the SDK doesn't depend on Electron.
+     */
+    parentWindow?: unknown;
+};
+/**
+ * Result of a cookie-login flow.
+ *
+ *   - `'success'` — cookie captured; `cookieValue` is the raw value.
+ *   - `'cancelled'` — user closed the window before the cookie appeared.
+ *   - `'timeout'` — `timeoutMs` elapsed without the cookie being set.
+ *   - `'error'` — host couldn't open the window (e.g. running headless,
+ *     no display server, partition rejected). Providers should surface
+ *     `error` to the user as an actionable message.
+ */
+export type CookieLoginResult = {
+    kind: 'success';
+    cookieValue: string;
+} | {
+    kind: 'cancelled';
+} | {
+    kind: 'timeout';
+} | {
+    kind: 'error';
+    error: string;
+};
+/**
+ * Auth primitives the host provides. Today only cookie-based login;
+ * OAuth / device-code flows can be added as future providers need them
+ * without breaking existing implementations (`HostAuthService` is an
+ * open-shape type — additions are purely additive).
+ */
+export type HostAuthService = {
+    /**
+     * Open a child window at the given URL and wait for the named cookie
+     * to appear. Used by providers whose login flow is "send the user to
+     * a web page, scrape the session cookie when they sign in".
+     *
+     * The host is responsible for: opening the window, polling cookies,
+     * closing the window when the cookie shows up (or the user cancels /
+     * times out), and isolating the session partition. The provider
+     * doesn't see Electron, BrowserWindow, or any windowing detail.
+     */
+    openCookieLoginWindow(opts: CookieLoginOptions): Promise<CookieLoginResult>;
+};
+/**
+ * The bag of host services injected into a provider via
+ * {@link JackProvider.activate}. Providers store the reference and
+ * pull primitives lazily.
+ *
+ * Adding a new capability:
+ *   1. Define the new service interface in this file (or a sibling).
+ *   2. Add it as an optional field here so older providers that don't
+ *      use it keep compiling.
+ *   3. Document the feature flag — providers that need the capability
+ *      should guard with `if (!host.newCapability) return undefined`
+ *      and the host implements it.
+ *
+ * Concrete services exposed today are documented in their own types.
+ */
+export type HostServices = {
+    /** Per-provider key/value store. Namespaced by provider id by the host. */
+    kv: HostKvScope;
+    /** Auth flow primitives (cookie login today; OAuth / device-code in the future). */
+    auth: HostAuthService;
+};
+//# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,gCAAgC;IAChC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IAC/B,iCAAiC;IACjC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC,4EAA4E;IAC5E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,iIAAiI;IACjI,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IACrC,oJAAoJ;IACpJ,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5C,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAA;IACX,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAA;IAClB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpC;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;;;;;;OASG;IACH,qBAAqB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;CAC5E,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,2EAA2E;IAC3E,EAAE,EAAE,WAAW,CAAA;IACf,oFAAoF;IACpF,IAAI,EAAE,eAAe,CAAA;CACtB,CAAA"}

package/dist/host.js

@@ -0,0 +1,37 @@
+/**
+ * Host primitives exposed to providers — handed in via
+ * {@link JackProvider.activate} so provider code never imports `electron`,
+ * `better-sqlite3`, or any other host-internal module directly.
+ *
+ * Why this exists
+ * ---------------
+ * In Jack v0.4.x the Claude provider reached into Electron (`safeStorage`,
+ * `BrowserWindow`, `session`) and Jack's settings table (`getSetting` /
+ * `setSetting`) to persist its login cookie. That breaks two goals:
+ *
+ *   1. **Out-of-tree packages.** A future `@third-party/jack-provider-foo`
+ *      installed from npm shouldn't need to know about the host's storage
+ *      layer or its windowing toolkit.
+ *   2. **Testability.** Provider unit tests on plain Node want a fake host
+ *      that returns canned credentials, not a real `safeStorage`.
+ *
+ * `HostServices` is the contract that satisfies both: a tiny set of
+ * primitives the host implements once (with whatever it has — Electron in
+ * Jack's case, but a CLI host could use `keytar` + headless puppeteer)
+ * and providers consume through dependency injection.
+ *
+ * Surface stays intentionally small. New capabilities grow this file as
+ * specific providers need them — but the rule is "host-side knowledge
+ * doesn't leak out the SDK". A provider that needs deep host integration
+ * is a sign that the integration belongs in the host, not in the
+ * provider.
+ *
+ * Lifecycle
+ * ---------
+ * The host calls `provider.activate(host)` once during registration. The
+ * provider stores the `host` reference and uses it lazily — no host
+ * primitive may be invoked before activation. Methods that need the host
+ * must guard accordingly (typically by deferring all work to a closure).
+ */
+export {};
+//# sourceMappingURL=host.js.map

package/dist/host.js.map

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

package/dist/index.d.ts

@@ -7,13 +7,19 @@
  * (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:
+ * Re-exports cover four 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`, …)
+ *   - `./usage` — provider-owned billing/usage surface (`UsageApi`,
+ *     `UsageMetric`, …)
+ *   - `./host` — host primitives injected at activation
+ *     (`HostServices`, `HostKvScope`, `HostAuthService`, …) — providers
+ *     consume these via `JackProvider.activate(host)` instead of
+ *     reaching into Electron / host internals directly.
  *
  * Companion runtime types from `@ottimis/jack-chat-core` (`NormalizedMessage`,
  * `ClientToolHandler`, `ToolShape`, …) are re-exported through `./provider`
@@ -24,6 +30,9 @@ export * from './backend';
 export * from './spawner';
 export * from './provider';
 export * from './usage';
+export * from './host';
+export * from './profiles';
+export * from './sandbox';
 /**
  * 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

package/dist/index.d.ts.map

@@ -1 +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;AAC1B,cAAc,SAAS,CAAA;AAEvB;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,QAAQ,CAAA;AACtB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AAEzB;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/index.js

@@ -7,13 +7,19 @@
  * (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:
+ * Re-exports cover four 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`, …)
+ *   - `./usage` — provider-owned billing/usage surface (`UsageApi`,
+ *     `UsageMetric`, …)
+ *   - `./host` — host primitives injected at activation
+ *     (`HostServices`, `HostKvScope`, `HostAuthService`, …) — providers
+ *     consume these via `JackProvider.activate(host)` instead of
+ *     reaching into Electron / host internals directly.
  *
  * Companion runtime types from `@ottimis/jack-chat-core` (`NormalizedMessage`,
  * `ClientToolHandler`, `ToolShape`, …) are re-exported through `./provider`
@@ -24,4 +30,7 @@ export * from './backend';
 export * from './spawner';
 export * from './provider';
 export * from './usage';
+export * from './host';
+export * from './profiles';
+export * from './sandbox';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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;AAC1B,cAAc,SAAS,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,QAAQ,CAAA;AACtB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA"}

package/dist/profiles.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Profiles — multiple isolated identities for a single provider.
+ *
+ * A "profile" is an isolated config/identity directory the provider's runtime
+ * can be pointed at via an env var (Claude `CLAUDE_CONFIG_DIR`, Codex
+ * `CODEX_HOME`, Gemini `GEMINI_CONFIG_DIR`, …). Two profiles = two distinct
+ * accounts / login states / agent customizations / history sets, all running
+ * the same provider binary.
+ *
+ * The user-facing scenario this exists for: an employee with separate
+ * "claude-personal" and "claude-work" shell aliases that point CLAUDE_CONFIG_DIR
+ * at different folders. The host turns that into a first-class concept —
+ * choosable per session, with a default per workspace-agent slot — instead of
+ * making the user re-shell their alias every time they switch context.
+ *
+ * Provider opts in by:
+ *   - declaring `capabilities.profiles = true`
+ *   - implementing `JackProvider.profiles` with a {@link ProfilesApi}
+ *   - injecting the right env var inside `applyProfile`
+ *
+ * Storage of the profile *list* lives on the host's per-provider kv (provider
+ * stores it via `host.kv` at activation time). Storage of the profile
+ * *content* (auth, sessions, agents, history) lives inside `configDir` on
+ * disk and is the runtime's concern, not the host's — Jack never reads or
+ * writes inside `configDir`.
+ */
+import type { AgentQueryOptions } from './backend';
+/**
+ * One profile entry. `id` is host-generated and stable; the human edits
+ * `label` + `configDir` freely.
+ *
+ * `isDefault` is exclusive within a provider — exactly one profile carries
+ * the flag at any time. Provider implementations enforce that invariant in
+ * `update`/`create` (when `setDefault` is true, demote the previous default).
+ */
+export type ProviderProfile = {
+    /** Stable identifier — host-generated UUID; never edited by user. */
+    id: string;
+    /** User-facing display label ("Work", "Personal", …). */
+    label: string;
+    /** Absolute path to the runtime config dir on the host filesystem. */
+    configDir: string;
+    /** Exactly one profile per provider carries this flag. */
+    isDefault: boolean;
+    /** ISO 8601 — when the profile was first created in Jack's registry. */
+    createdAt: string;
+};
+/**
+ * Result of {@link ProfilesApi.probeProfile} — best-effort introspection of
+ * what's already stored under `configDir` so the UI can show the user
+ * "Connected as <X>" instead of an opaque path.
+ *
+ * Provider populates whichever fields it can read cheaply (no network
+ * round-trips) — fields it can't infer stay undefined.
+ */
+export type ProviderProfileProbe = {
+    /** True when the dir exists and looks like a valid runtime config. */
+    exists: boolean;
+    /** True when the dir contains usable credentials. Tri-state: false = present-but-invalid, undefined = N/A. */
+    authenticated?: boolean;
+    /** Human-readable identity hint (email, account label) when discoverable. */
+    accountLabel?: string;
+};
+/**
+ * Input shape for {@link ProfilesApi.create}. The `id` is host-generated by
+ * the provider implementation (typically `crypto.randomUUID()`); the caller
+ * supplies the human bits.
+ */
+export type CreateProfileInput = {
+    label: string;
+    configDir: string;
+    /** When true, the new profile becomes the default (demotes previous default). */
+    setDefault?: boolean;
+};
+/**
+ * Provider-owned profiles capability. Optional on {@link JackProvider} —
+ * absent = the provider's runtime always uses its implicit default config dir
+ * and the host hides every profiles-related affordance.
+ */
+export type ProfilesApi = {
+    /**
+     * Enumerate the registered profiles in stable order. Provider MUST seed
+     * a "Default" profile pointing at its implicit config dir on first call
+     * (lazy migration — preserves the user's existing setup without manual
+     * intervention).
+     */
+    list(): Promise<ProviderProfile[]>;
+    /**
+     * Register a new profile. Provider generates the `id` and persists the
+     * row. Returns the freshly-created profile so the caller doesn't have to
+     * round-trip through `list()`.
+     */
+    create(input: CreateProfileInput): Promise<ProviderProfile>;
+    /**
+     * Patch an existing profile. Empty patch = no-op. Setting `isDefault: true`
+     * demotes whichever profile currently holds the default flag.
+     */
+    update(id: string, patch: Partial<Pick<ProviderProfile, 'label' | 'configDir' | 'isDefault'>>): Promise<ProviderProfile>;
+    /**
+     * Remove a profile by id. MUST refuse to remove the last remaining profile
+     * (the provider always needs a default to fall back to). MUST refuse to
+     * remove the default profile when other profiles exist — caller has to
+     * promote a replacement first.
+     *
+     * Note: this only removes the registry entry. Files inside `configDir`
+     * stay on disk untouched — destructive cleanup is the user's responsibility
+     * (we never `rm -rf` a directory the user gave us).
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * Mutate spawn options in place to point the runtime at the chosen
+     * profile's `configDir`. Each provider injects its native env var
+     * (Claude: `CLAUDE_CONFIG_DIR`; Codex: `CODEX_HOME`; …) and any other
+     * spawn-time wiring the runtime needs.
+     *
+     * Called once per spawn by the host, after `applyKnowledgeContext` and
+     * `prepareSpawnOptions`. Unknown `profileId` MUST be a silent no-op
+     * (caller falls back to the implicit default behavior).
+     */
+    applyProfile(options: AgentQueryOptions, profileId: string): Promise<void>;
+    /**
+     * Best-effort introspection of what's stored under `configDir` so the
+     * UI can show "Connected as X" / "Empty profile" hints. Provider returns
+     * what it can read cheaply (file presence, parsed credentials file) —
+     * no network calls. Optional: providers that can't introspect their
+     * own config dir omit this and the UI falls back to a path-only display.
+     */
+    probeProfile?(configDir: string): Promise<ProviderProfileProbe>;
+};
+//# sourceMappingURL=profiles.d.ts.map

package/dist/profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../src/profiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAElD;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAA;IACV,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAA;IACjB,0DAA0D;IAC1D,SAAS,EAAE,OAAO,CAAA;IAClB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,sEAAsE;IACtE,MAAM,EAAE,OAAO,CAAA;IACf,8GAA8G;IAC9G,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,iFAAiF;IACjF,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB;;;;;OAKG;IACH,IAAI,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAAA;IAElC;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IAE3D;;;OAGG;IACH,MAAM,CACJ,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,OAAO,GAAG,WAAW,GAAG,WAAW,CAAC,CAAC,GACzE,OAAO,CAAC,eAAe,CAAC,CAAA;IAE3B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjC;;;;;;;;;OASG;IACH,YAAY,CAAC,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE1E;;;;;;OAMG;IACH,YAAY,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;CAChE,CAAA"}

package/dist/profiles.js

@@ -0,0 +1,28 @@
+/**
+ * Profiles — multiple isolated identities for a single provider.
+ *
+ * A "profile" is an isolated config/identity directory the provider's runtime
+ * can be pointed at via an env var (Claude `CLAUDE_CONFIG_DIR`, Codex
+ * `CODEX_HOME`, Gemini `GEMINI_CONFIG_DIR`, …). Two profiles = two distinct
+ * accounts / login states / agent customizations / history sets, all running
+ * the same provider binary.
+ *
+ * The user-facing scenario this exists for: an employee with separate
+ * "claude-personal" and "claude-work" shell aliases that point CLAUDE_CONFIG_DIR
+ * at different folders. The host turns that into a first-class concept —
+ * choosable per session, with a default per workspace-agent slot — instead of
+ * making the user re-shell their alias every time they switch context.
+ *
+ * Provider opts in by:
+ *   - declaring `capabilities.profiles = true`
+ *   - implementing `JackProvider.profiles` with a {@link ProfilesApi}
+ *   - injecting the right env var inside `applyProfile`
+ *
+ * Storage of the profile *list* lives on the host's per-provider kv (provider
+ * stores it via `host.kv` at activation time). Storage of the profile
+ * *content* (auth, sessions, agents, history) lives inside `configDir` on
+ * disk and is the runtime's concern, not the host's — Jack never reads or
+ * writes inside `configDir`.
+ */
+export {};
+//# sourceMappingURL=profiles.js.map

package/dist/profiles.js.map

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