@ottimis/jack-provider-sdk 0.4.0 → 0.9.0

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

@@ -17,6 +17,9 @@
  */
 
 import type { AgentBackend, AgentPermissionMode, AgentQueryOptions, McpServerSpec } from './backend'
+import type { HostServices } from './host'
+import type { ProfilesApi } from './profiles'
+import type { SandboxApi } from './sandbox'
 import type { UsageApi } from './usage'
 import type { ZodType } from 'zod'
 import type {
@@ -273,6 +276,28 @@ 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
+  /**
+   * Provider can run inside Jack's Docker sandbox. When `true`,
+   * {@link JackProvider.sandbox} MUST be defined; the host enables the
+   * sandbox toggle in the new-session dialog and renders an entry for this
+   * provider in `Settings → Sandbox`.
+   *
+   * When `false` (or omitted), sandbox mode is unavailable for this
+   * provider — the toggle is hidden / disabled in the UI, and a spawn-time
+   * sandbox request returns a clear error.
+   */
+  sandbox: boolean
   /**
    * Permission modes the provider actually supports. Drives the
    * Shift-Tab cycle in the renderer (`MessageInputBar`) and any
@@ -291,6 +316,23 @@ export type CapabilityMatrix = {
    * or settings); the catalog only governs UI affordances.
    */
   permissionModes: readonly AgentPermissionMode[]
+  /**
+   * Suggested prompt-cache TTL in milliseconds — how long the provider's
+   * server-side prompt cache stays warm between user turns before a new
+   * cache-write is required. Optional: providers without prompt caching
+   * (or without a documented TTL) leave it undefined and the host hides
+   * the cache-countdown chip entirely for sessions on that provider.
+   *
+   * This is only the **suggested default**: the user can override per
+   * provider in `Settings → Prompt cache` and disable the chip outright.
+   * The host treats this as a UI-only countdown hint — never as a
+   * contract for actual cache eviction (the provider is the source of
+   * truth at request time).
+   *
+   * Claude declares 300_000 (5 min) per its prompt-caching docs. Codex
+   * and Gemini leave it undefined.
+   */
+  cacheTtlMs?: number
 }
 
 /**
@@ -676,6 +718,45 @@ 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
+  /**
+   * Docker sandbox capability — provider declares the image, binary name,
+   * and config-dir mount the host needs to spawn a sandboxed session for
+   * this provider. See {@link SandboxApi}. Optional; when undefined
+   * `capabilities.sandbox` MUST be `false` and the host disables sandbox
+   * mode for this provider's sessions.
+   */
+  sandbox?: SandboxApi
+  /**
+   * 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>
 }
 
 /**

package/src/sandbox.ts

@@ -0,0 +1,108 @@
+/**
+ * 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.
+ */
+
+/**
+ * Mount the provider's host-side config directory into the container.
+ * Most providers persist auth + sessions + per-user settings in a dotfile
+ * dir under `$HOME` (Claude `~/.claude`, Codex `~/.codex`, Gemini
+ * `~/.gemini`). The host mounts this dir into the container at
+ * {@link containerPath} so the CLI inside the container has access to the
+ * same auth state as the host.
+ *
+ * Read-only by default — the container shouldn't be writing back to the
+ * user's persistent config from inside the sandbox. Set `readOnly: false`
+ * only when the provider's CLI genuinely needs to mutate state inside the
+ * config dir (e.g. session JSONL append).
+ */
+export type SandboxConfigMount = {
+  /**
+   * Absolute host path. Provider implementations resolve this lazily — call
+   * `os.homedir()` + `path.join(...)` at the time `configMount` is read,
+   * not at module-load time, so test environments and per-process HOME
+   * overrides work correctly.
+   */
+  hostPath: string
+  /** Absolute container path. */
+  containerPath: string
+  /** When `true`, the host adds `:ro` to the bind. Default: `true` recommended. */
+  readOnly: boolean
+}
+
+/**
+ * Provider-declared Docker sandbox capability. Optional on
+ * {@link JackProvider}; when present the matching
+ * {@link CapabilityMatrix.sandbox} flag MUST be `true`.
+ */
+export interface SandboxApi {
+  /**
+   * Default image reference, pinned per provider release. Format:
+   * `<registry>/<repo>:<tag>`. Users can override per-provider via the host
+   * setting `sandbox.image.<providerId>`.
+   *
+   * For Jack's first-party providers the recommended location is
+   * `ghcr.io/ottimis/jack-sandbox-<providerId>:<X.Y.Z>` (monorepo built
+   * from `github.com/ottimis/JACK-sandbox`). Third-party plugins are free
+   * to host elsewhere.
+   */
+  readonly defaultImage: string
+
+  /**
+   * CLI binary name as it should be invoked inside the container (e.g.
+   * `'claude'`, `'codex'`, `'gemini'`). Used by the host's spawner to
+   * rewrite host-resolved absolute binary paths to a bare command the
+   * container's PATH resolves.
+   *
+   * The image MUST install this binary at a location reachable from
+   * `$PATH` (typically `/usr/local/bin/<binaryName>` via `npm install -g`).
+   */
+  readonly binaryName: string
+
+  /**
+   * Mount the provider's host-side config directory into the container.
+   * Optional — providers that are stateless on the host (none today)
+   * leave this undefined.
+   */
+  readonly configMount?: SandboxConfigMount
+
+  /**
+   * Optional environment extras to inject into the container. Layered AFTER
+   * the spawn-arg env so provider-specific overrides can win, but BEFORE
+   * the user can override (the user-facing override is per-provider via
+   * the host setting, not per-env-var).
+   *
+   * Most provider env is already on `SpawnArgs.env` from the backend's
+   * spawn pipeline. Use this only when the SDK contract doesn't expose a
+   * cleaner channel — e.g. forcing a CLI to disable telemetry inside the
+   * sandbox even when the user has it on globally.
+   */
+  envExtras?(): Record<string, string>
+}

package/src/usage.ts

@@ -180,32 +180,60 @@ 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): Promise<UsageConnectResult>
+  selectOption?(optionId: string, profileId?: string): Promise<UsageConnectResult>
 
-  /** Drop credentials and stop any provider-side polling. */
-  disconnect(): Promise<void>
+  /**
+   * Drop credentials and stop any provider-side polling for the
+   * specified profile. Omit `profileId` to disconnect the default profile.
+   */
+  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.