@ottimis/jack-provider-sdk 0.3.0 → 0.7.0

package/dist/provider.d.ts

@@ -15,7 +15,9 @@
  * This file is the boundary between Jack core and a provider package — keep
  * it free of provider-specific imports.
  */
-import type { AgentBackend, AgentQueryOptions, McpServerSpec } from './backend';
+import type { AgentBackend, AgentPermissionMode, AgentQueryOptions, McpServerSpec } from './backend';
+import type { HostServices } from './host';
+import type { ProfilesApi } from './profiles';
 import type { UsageApi } from './usage';
 import type { ZodType } from 'zod';
 import type { ClientToolHandler, NormalizedMessage, NormalizedToolRef, ProviderUserContentPolicy, ToolShape } from '@ottimis/jack-chat-core';
@@ -257,6 +259,35 @@ export type CapabilityMatrix = {
      * usage bars and no Connect affordance is offered.
      */
     usage: boolean;
+    /**
+     * Provider supports multiple isolated config/identity directories
+     * ("profiles") — distinct accounts, login states, agent customizations,
+     * and history sets all selectable per-session at runtime. When `true`,
+     * {@link JackProvider.profiles} MUST be defined; the host renders the
+     * profile picker UI and routes spawn-time `applyProfile` calls.
+     *
+     * When `false` the provider's runtime always uses its implicit default
+     * config dir; the host hides every profile-related affordance.
+     */
+    profiles: boolean;
+    /**
+     * Permission modes the provider actually supports. Drives the
+     * Shift-Tab cycle in the renderer (`MessageInputBar`) and any
+     * provider-aware UI that picks a mode (settings, slash commands).
+     * Order matters — it's the cycle order on Shift-Tab.
+     *
+     * Each provider declares only the modes that have a meaningful
+     * behaviour for its runtime: Claude's `['default', 'acceptEdits',
+     * 'plan', 'auto']`, Codex's `['default', 'acceptEdits',
+     * 'bypassPermissions']` (no `'plan'` because there's no ExitPlanMode
+     * primitive — mapping `'plan'` to read-only sandbox would be
+     * misleading), Gemini's set inherited from ACP `available_modes`.
+     *
+     * Modes outside this list MAY still be accepted by
+     * `setPermissionMode()` (e.g. set programmatically via slash command
+     * or settings); the catalog only governs UI affordances.
+     */
+    permissionModes: readonly AgentPermissionMode[];
 };
 /**
  * Re-exports of canonical wire-shape types from chat-core so consumers of
@@ -604,6 +635,37 @@ export type JackProvider = {
      * decodes.
      */
     usage?: UsageApi;
+    /**
+     * Multi-profile capability — multiple isolated config/identity dirs
+     * selectable per session. See {@link ProfilesApi}. Optional; when
+     * undefined `capabilities.profiles` MUST be `false` and the host hides
+     * every profile-related affordance. When defined, the host calls
+     * `applyProfile(options, profileId)` once per spawn so the provider can
+     * inject its native config-dir env var (Claude `CLAUDE_CONFIG_DIR`,
+     * Codex `CODEX_HOME`, …).
+     */
+    profiles?: ProfilesApi;
+    /**
+     * Optional one-shot activation hook. Called once by the host during
+     * registration with a {@link HostServices} bag scoped to this
+     * provider's id (kv namespace, auth partition prefix). Providers that
+     * need host-side primitives (encrypted credential storage, child auth
+     * windows, …) store the `host` reference and use it lazily; providers
+     * that are pure (Codex, Gemini today) leave this undefined.
+     *
+     * Activation MUST be idempotent: calling `activate(host)` twice with
+     * the same host is allowed and should not duplicate state. Activation
+     * happens at registration time — well before any session spawns —
+     * but providers MUST NOT block on network or disk here. Defer all I/O
+     * to the methods that actually need it.
+     *
+     * The host calls `activate` synchronously enough that
+     * `provider.usage`, `provider.persistedPermissions`, etc. can read
+     * `host` from a closure / captured variable in subsequent invocations.
+     * Async work inside `activate` is OK but the host won't await it
+     * before exposing the provider — it's "fire and let it complete".
+     */
+    activate?(host: HostServices): void | Promise<void>;
 };
 /**
  * Provider-neutral spec for an in-process MCP server the host wants to

package/dist/provider.d.ts.map

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

package/dist/usage.d.ts

@@ -176,28 +176,56 @@ export type UsageConnectContext = {
  * Provider-owned usage capability. Optional on {@link JackProvider};
  * absent = host hides the chip's "Connect" affordance and the
  * capability flag is `false`.
+ *
+ * Multi-profile contract (SDK 0.7.0):
+ * Every account-level method accepts an optional `profileId`. Providers
+ * that ALSO declare `capabilities.profiles=true` MUST honor the param —
+ * different profile = different account = different credentials, polled
+ * independently. When omitted, the provider resolves to its DEFAULT
+ * profile (back-compat with hosts that don't yet thread profileId).
+ *
+ * Providers without profiles support (`capabilities.profiles=false`)
+ * MAY ignore the param and behave as if every call were singleton —
+ * the omission stays the canonical caller behavior, the param is just
+ * ignored.
+ *
+ * `formatSessionMetrics` stays profile-agnostic: per-session metrics
+ * derive from the live process's context tokens (already pinned to the
+ * session's profile via `applyProfile` at spawn time).
  */
 export type UsageApi = {
-    /** Current connection state — used for chip display + gating. */
-    status(): Promise<UsageStatus>;
+    /**
+     * Current connection state — used for chip display + gating.
+     * Profile-aware: omit `profileId` to query the default profile.
+     */
+    status(profileId?: string): Promise<UsageStatus>;
     /**
      * Open the provider's connect flow. Whatever modality the provider
      * needs (login window, API-key picker, OAuth redirect) lives here.
+     * Profile-aware: omit `profileId` to bind credentials to the default
+     * profile. Different profileIds use isolated storage AND isolated
+     * login surfaces (e.g. distinct cookie partitions for Claude) so two
+     * accounts can sign in side by side.
      */
-    connect(ctx: UsageConnectContext): Promise<UsageConnectResult>;
+    connect(ctx: UsageConnectContext, profileId?: string): Promise<UsageConnectResult>;
     /**
      * When `connect()` returned `'choose'`, host calls this with the
      * user's pick. Optional — providers that never choose omit it.
+     * Profile-aware: pass the SAME `profileId` you used for `connect()`.
+     */
+    selectOption?(optionId: string, profileId?: string): Promise<UsageConnectResult>;
+    /**
+     * Drop credentials and stop any provider-side polling for the
+     * specified profile. Omit `profileId` to disconnect the default profile.
      */
-    selectOption?(optionId: string): Promise<UsageConnectResult>;
-    /** Drop credentials and stop any provider-side polling. */
-    disconnect(): Promise<void>;
+    disconnect(profileId?: string): Promise<void>;
     /**
-     * Fetch one fresh account-level snapshot. Empty `metrics: []` is
-     * fine when the provider has no billing surface yet — the capability
-     * stays `true` for the per-session bridge.
+     * Fetch one fresh account-level snapshot for the specified profile.
+     * Empty `metrics: []` is fine when the provider has no billing surface
+     * yet — the capability stays `true` for the per-session bridge.
+     * Omit `profileId` to fetch the default profile.
      */
-    fetch(): Promise<UsageSnapshot>;
+    fetch(profileId?: string): Promise<UsageSnapshot>;
     /**
      * Recommended poll cadence (seconds). Host clamps to its bounds.
      * Optional — host falls back to its own default if unset.

package/dist/usage.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ottimis/jack-provider-sdk",
-  "version": "0.3.0",
+  "version": "0.7.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": {

package/src/backend.ts

@@ -45,12 +45,21 @@ export type BackendName = string
 // Neutral option types
 // ─────────────────────────────────────────────────────────────────────────────
 
-/** Permission gate behaviour. Strings the host may toggle live. */
+/**
+ * Permission gate behaviour. Open string union — providers declare which
+ * subset they support via {@link CapabilityMatrix.permissionModes}, and
+ * the host's permission-mode picker reads that catalog verbatim. Listed
+ * literals are the modes any in-tree provider has shipped to date;
+ * future providers may invent new strings without breaking the type.
+ */
 export type AgentPermissionMode =
   | 'default'
   | 'acceptEdits'
   | 'plan'
+  | 'auto'
   | 'bypassPermissions'
+  | 'dontAsk'
+  | (string & {})
 
 /** Settings layers the provider should consult at boot. */
 export type AgentSettingSource = 'user' | 'project' | 'local'

package/src/host.ts

@@ -0,0 +1,159 @@
+/**
+ * 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
+}

package/src/index.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`
@@ -25,6 +31,8 @@ export * from './backend'
 export * from './spawner'
 export * from './provider'
 export * from './usage'
+export * from './host'
+export * from './profiles'
 
 /**
  * Re-export of `NormalizedMessage` from chat-core so consumers don't need

package/src/profiles.ts

@@ -0,0 +1,142 @@
+/**
+ * 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>
+}

package/src/provider.ts

@@ -16,7 +16,9 @@
  * it free of provider-specific imports.
  */
 
-import type { AgentBackend, AgentQueryOptions, McpServerSpec } from './backend'
+import type { AgentBackend, AgentPermissionMode, AgentQueryOptions, McpServerSpec } from './backend'
+import type { HostServices } from './host'
+import type { ProfilesApi } from './profiles'
 import type { UsageApi } from './usage'
 import type { ZodType } from 'zod'
 import type {
@@ -273,6 +275,35 @@ export type CapabilityMatrix = {
    * usage bars and no Connect affordance is offered.
    */
   usage: boolean
+  /**
+   * Provider supports multiple isolated config/identity directories
+   * ("profiles") — distinct accounts, login states, agent customizations,
+   * and history sets all selectable per-session at runtime. When `true`,
+   * {@link JackProvider.profiles} MUST be defined; the host renders the
+   * profile picker UI and routes spawn-time `applyProfile` calls.
+   *
+   * When `false` the provider's runtime always uses its implicit default
+   * config dir; the host hides every profile-related affordance.
+   */
+  profiles: boolean
+  /**
+   * Permission modes the provider actually supports. Drives the
+   * Shift-Tab cycle in the renderer (`MessageInputBar`) and any
+   * provider-aware UI that picks a mode (settings, slash commands).
+   * Order matters — it's the cycle order on Shift-Tab.
+   *
+   * Each provider declares only the modes that have a meaningful
+   * behaviour for its runtime: Claude's `['default', 'acceptEdits',
+   * 'plan', 'auto']`, Codex's `['default', 'acceptEdits',
+   * 'bypassPermissions']` (no `'plan'` because there's no ExitPlanMode
+   * primitive — mapping `'plan'` to read-only sandbox would be
+   * misleading), Gemini's set inherited from ACP `available_modes`.
+   *
+   * Modes outside this list MAY still be accepted by
+   * `setPermissionMode()` (e.g. set programmatically via slash command
+   * or settings); the catalog only governs UI affordances.
+   */
+  permissionModes: readonly AgentPermissionMode[]
 }
 
 /**
@@ -658,6 +689,37 @@ export type JackProvider = {
    * decodes.
    */
   usage?: UsageApi
+  /**
+   * Multi-profile capability — multiple isolated config/identity dirs
+   * selectable per session. See {@link ProfilesApi}. Optional; when
+   * undefined `capabilities.profiles` MUST be `false` and the host hides
+   * every profile-related affordance. When defined, the host calls
+   * `applyProfile(options, profileId)` once per spawn so the provider can
+   * inject its native config-dir env var (Claude `CLAUDE_CONFIG_DIR`,
+   * Codex `CODEX_HOME`, …).
+   */
+  profiles?: ProfilesApi
+  /**
+   * Optional one-shot activation hook. Called once by the host during
+   * registration with a {@link HostServices} bag scoped to this
+   * provider's id (kv namespace, auth partition prefix). Providers that
+   * need host-side primitives (encrypted credential storage, child auth
+   * windows, …) store the `host` reference and use it lazily; providers
+   * that are pure (Codex, Gemini today) leave this undefined.
+   *
+   * Activation MUST be idempotent: calling `activate(host)` twice with
+   * the same host is allowed and should not duplicate state. Activation
+   * happens at registration time — well before any session spawns —
+   * but providers MUST NOT block on network or disk here. Defer all I/O
+   * to the methods that actually need it.
+   *
+   * The host calls `activate` synchronously enough that
+   * `provider.usage`, `provider.persistedPermissions`, etc. can read
+   * `host` from a closure / captured variable in subsequent invocations.
+   * Async work inside `activate` is OK but the host won't await it
+   * before exposing the provider — it's "fire and let it complete".
+   */
+  activate?(host: HostServices): void | Promise<void>
 }
 
 /**