@ottimis/jack-provider-sdk 0.9.0 → 0.13.0

package/src/provider.ts

@@ -17,7 +17,9 @@
  */
 
 import type { AgentBackend, AgentPermissionMode, AgentQueryOptions, McpServerSpec } from './backend'
+import type { ProviderDefaultsApi } from './defaults'
 import type { HostServices } from './host'
+import type { OneshotApi } from './oneshot'
 import type { ProfilesApi } from './profiles'
 import type { SandboxApi } from './sandbox'
 import type { UsageApi } from './usage'
@@ -38,7 +40,13 @@ export type ProviderId = string
  * commands carry `body` + `filePath`, builtin and wire-sourced ones
  * don't (they don't *have* a markdown file behind them).
  */
-export type SlashCommandScope = 'builtin' | 'wire' | 'user' | 'project' | (string & {})
+export type SlashCommandScope =
+  | 'builtin'
+  | 'wire'
+  | 'user'
+  | 'project'
+  | 'jack-builtin'
+  | (string & {})
 
 /**
  * Common surface every slash command def carries regardless of source.
@@ -51,7 +59,7 @@ type SlashCommandDefBase = {
 }
 
 /**
- * Slash-command definition surfaced by a provider. Three sources can
+ * Slash-command definition surfaced by a provider. Four sources can
  * coexist (see {@link SlashCommandSupport}):
  *
  *   - `'builtin'` — static catalog the runtime intercepts. The renderer
@@ -64,6 +72,14 @@ type SlashCommandDefBase = {
  *     `filePath` + `body` are required so the renderer can offer "open
  *     in editor" affordances and the host can expand `$ARGUMENTS` /
  *     `$N` placeholders.
+ *   - `'jack-builtin'` — host-shipped slash command pack distributed
+ *     inside the Jack app bundle (e.g. `/changelog-turn`,
+ *     `/save-decision` for the user-data-tables feature). Read-only
+ *     for the user (no edit/delete), expanded the same way as
+ *     `'user'/'project'` (`$ARGUMENTS` + `$N` substitution). The body
+ *     comes from `resources/slash-commands/builtin/<name>.md`; the
+ *     renderer treats the catalog like any file-sourced command but
+ *     hides authoring affordances behind the `readonly` flag.
  *
  * Discriminated by `scope` so consumers narrow before reading the
  * file-only fields. Replaces the legacy uniform shape that forced
@@ -74,6 +90,31 @@ export type SlashCommandDef =
   | (SlashCommandDefBase & { scope: 'builtin' })
   | (SlashCommandDefBase & { scope: 'wire' })
   | (SlashCommandDefBase & { scope: 'user' | 'project'; body: string; filePath: string })
+  | (SlashCommandDefBase & { scope: 'jack-builtin'; body: string; readonly: true })
+
+/**
+ * Input shape for {@link SlashCommandSupport.createCommand}. The host
+ * collects these fields from a dialog form and hands them verbatim to
+ * the provider, which writes the markdown file in its native layout
+ * (Claude: `~/.claude/commands/<name>.md` for user scope,
+ * `<projectPath>/.claude/commands/<name>.md` for project).
+ *
+ * `name` may include subdirectory namespacing via `:` — e.g.
+ * `git:review` → file at `git/review.md` under the scope root.
+ * Provider validates the name (regex `[a-z][a-z0-9:-]*` typically) and
+ * rejects with an error when the file already exists (caller decides
+ * whether to retry with `overwrite`, omitted in v1 to avoid
+ * accidental clobbering).
+ */
+export type CreateSlashCommandInput = {
+  name: string
+  scope: 'user' | 'project'
+  description?: string
+  argumentHint?: string
+  body: string
+  /** Required when `scope === 'project'`. */
+  projectPath?: string
+}
 
 /**
  * Parsed envelope a provider's CLI may wrap slash commands in when it logs
@@ -148,6 +189,71 @@ export type SlashCommandSupport = {
     sessionId: string,
     callback: (commands: SlashCommandDef[]) => void
   ): () => void
+  /**
+   * Authoring: create a new file-sourced slash command on disk. Only
+   * meaningful for providers that surface file-based commands (Claude
+   * `.claude/commands/*.md`); providers without an on-disk format leave
+   * this undefined and the host hides the "+ New" affordance.
+   *
+   * Contract:
+   *   - Validates `input.name` against the provider's naming convention
+   *     (typical regex: `[a-z][a-z0-9:-]*` with `:` for subdirectory
+   *     namespacing).
+   *   - Resolves the target file path under the scope root, creating
+   *     intermediate directories as needed.
+   *   - Refuses overwrite when the file already exists (throws an
+   *     error with a stable code so the host can render a clear
+   *     conflict message).
+   *   - Writes frontmatter (`description`, `argument-hint`) plus the
+   *     body verbatim. Returns the absolute file path.
+   *
+   * The host calls this from `provider:slash-commands:create` IPC and
+   * the new file is picked up by {@link subscribeFsChanges} so the
+   * renderer's palette refreshes without a manual reload.
+   */
+  createCommand?(input: CreateSlashCommandInput): Promise<{ filePath: string }>
+  /**
+   * Authoring: delete a file-sourced slash command. The host passes the
+   * absolute `filePath` previously returned in a {@link SlashCommandDef}.
+   * `projectPath` (when provided) lets the provider validate
+   * project-scoped deletes too — without it, only files inside the user
+   * root are accepted (delete-by-path on a project file requires the
+   * caller to thread the project path through, which the host knows
+   * from the active session's cwd).
+   *
+   * Contract:
+   *   - Verifies that `filePath` is contained inside one of the provider's
+   *     known scope roots (path normalisation + `path.relative()` check)
+   *     to prevent the host from accidentally requesting deletion of a
+   *     file outside the slash-commands tree.
+   *   - Deletes the file. Idempotent: a missing file is treated as a
+   *     successful no-op (no `ENOENT` thrown).
+   *
+   * Like {@link createCommand}, omitting this field hides the "Delete"
+   * affordance for file-sourced rows in the renderer.
+   */
+  deleteCommand?(filePath: string, projectPath?: string): Promise<{ ok: true }>
+  /**
+   * Subscribe to filesystem changes in the provider's user/project
+   * command roots. Distinct from {@link subscribeToWireCommands}: this
+   * is fs-driven (markdown files added/edited/deleted on disk),
+   * whereas the wire variant is provider-pushed runtime state.
+   *
+   * Contract:
+   *   - The provider invokes the callback whenever a `.md` file under
+   *     a known root is added, modified, or deleted (debounce is the
+   *     provider's concern; the host treats the callback as "your
+   *     cached list is stale, refetch").
+   *   - The callback receives no payload — it's a stale-flag, not a
+   *     diff. The host responds by re-running `scanCommands` and
+   *     emitting `slashCommands:changed` to its renderers.
+   *   - Returns an unsubscribe function. The host calls it on shutdown
+   *     or provider switch.
+   *   - Optional. Providers without a file-based source (Codex,
+   *     Gemini today) leave this undefined and the host's cache is
+   *     invalidated only on session boundary events.
+   */
+  subscribeFsChanges?(callback: () => void): () => void
 }
 
 /**
@@ -170,6 +276,19 @@ export type ReadSessionTranscriptOptions = {
    * current consumers.
    */
   includeSystemMessages?: boolean
+  /**
+   * Provider-config root for transcript lookup (Claude `CLAUDE_CONFIG_DIR`,
+   * Codex `CODEX_HOME`, …). When set, the provider reads transcripts from
+   * `<configDir>/<provider-native-subpath>` instead of its implicit default
+   * — required when the session was spawned under a non-default
+   * {@link ProviderProfile} so the JSONL/rollout file resolves correctly.
+   *
+   * The host resolves this from the session's pinned `profile_id` and
+   * passes it verbatim. Providers without a profile concept ignore the
+   * field; providers with profiles MUST treat it as authoritative when
+   * present.
+   */
+  configDir?: string
 }
 
 /**
@@ -298,6 +417,15 @@ export type CapabilityMatrix = {
    * sandbox request returns a clear error.
    */
   sandbox: boolean
+  /**
+   * Provider exposes a non-agentic single-shot completion via
+   * {@link JackProvider.oneshot}. When `false` the host hides any UI
+   * affordance that depends on it (e.g. CommitComposer's "AI commit
+   * message" button is disabled with an explanatory tooltip).
+   *
+   * When `true`, {@link JackProvider.oneshot} MUST be defined.
+   */
+  oneshot: boolean
   /**
    * Permission modes the provider actually supports. Drives the
    * Shift-Tab cycle in the renderer (`MessageInputBar`) and any
@@ -736,6 +864,27 @@ export type JackProvider = {
    * mode for this provider's sessions.
    */
   sandbox?: SandboxApi
+  /**
+   * One-shot completion capability — non-agentic, no tools, no session.
+   * See {@link OneshotApi}. Optional; when undefined `capabilities.oneshot`
+   * MUST be `false` and the host disables any UI affordance that relies
+   * on this primitive (e.g. CommitComposer's AI commit message button).
+   */
+  oneshot?: OneshotApi
+  /**
+   * User-configurable defaults applied to newly-created sessions —
+   * which model, reasoning-effort tier, and permission mode the host
+   * should pre-fill on the session row when the user spawns a new
+   * session against this provider. See {@link ProviderDefaultsApi}.
+   *
+   * Optional + presence-based. A provider that omits the field doesn't
+   * appear in `Settings → Provider defaults` and no pre-fill happens for
+   * its sessions (the runtime falls back to its built-in default model /
+   * effort / permission_mode at spawn time). Catalog-only contract: the
+   * provider declares the legal values, the host owns storage (kv) and
+   * resolution.
+   */
+  defaults?: ProviderDefaultsApi
   /**
    * Optional one-shot activation hook. Called once by the host during
    * registration with a {@link HostServices} bag scoped to this

package/src/sandbox.ts

@@ -31,30 +31,36 @@
  */
 
 /**
- * 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.
+ * Mount a named Docker volume into the container at {@link containerPath}.
+ * The pattern Anthropic recommends for CLI config dirs (see
+ * https://code.claude.com/docs/en/devcontainer#persist-authentication-and-settings-across-rebuilds):
+ * the volume is auto-created on demand, persists across container
+ * restarts, and isolates writes from the host filesystem entirely.
+ * Best fit for `~/.claude`, `~/.codex`, `~/.gemini` since they hold auth
+ * tokens, session JSONLs, and CLI-mutated settings.
  *
- * 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).
+ * Read-only is recommended whenever the CLI doesn't genuinely need to
+ * mutate state. Set `readOnly: false` when the CLI writes back — Claude
+ * writes session-env, project history, MCP additions; Codex appends
+ * thread JSONL; etc.
  */
 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.
+   * Docker volume name. The host auto-creates the volume if missing
+   * (via `docker volume create <name>`). Use a stable, namespaced name
+   * like `jack-sandbox-<provider>-config` so volumes can be inspected
+   * / pruned predictably from the Docker CLI.
+   *
+   * Volumes are NOT scoped per session by default — sharing one volume
+   * across sandbox sessions of the same provider is the common case
+   * and matches Anthropic's reference. If you need per-session
+   * isolation, embed the session id in the name.
    */
-  hostPath: string
+  readonly volumeName: string
   /** Absolute container path. */
-  containerPath: string
-  /** When `true`, the host adds `:ro` to the bind. Default: `true` recommended. */
-  readOnly: boolean
+  readonly containerPath: string
+  /** When `true`, the host adds `:ro` to the bind. */
+  readonly readOnly: boolean
 }
 
 /**
@@ -87,11 +93,17 @@ export interface SandboxApi {
   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.
+   * Mount provider-side config artifacts (directories and/or files) into
+   * the container. Optional — providers that are stateless on the host
+   * (none today) leave this undefined or pass an empty array.
+   *
+   * Multiple entries support providers whose CLI splits state across more
+   * than one path (e.g. Claude needs both `~/.claude/` for the dotfile dir
+   * and `~/.claude.json` for the main config file). Order is preserved
+   * but mounts are independent — if two entries overlap, Docker resolves
+   * them in declaration order.
    */
-  readonly configMount?: SandboxConfigMount
+  readonly configMounts?: readonly SandboxConfigMount[]
 
   /**
    * Optional environment extras to inject into the container. Layered AFTER
@@ -105,4 +117,54 @@ export interface SandboxApi {
    * sandbox even when the user has it on globally.
    */
   envExtras?(): Record<string, string>
+
+  /**
+   * Optional spawn-time setup hook. Runs once on the host before the
+   * container starts and lets the provider produce per-session artifacts
+   * (e.g. a sanitized `settings.json` with hooks stripped, a generated
+   * MCP manifest) and mount them into the container alongside the static
+   * {@link configMounts}.
+   *
+   * Returned `extraMounts` are appended to {@link configMounts} in
+   * declaration order. The `cleanup` callback (if provided) is invoked
+   * after the container exits so the provider can unlink temp files.
+   *
+   * Errors thrown here propagate as spawn failures — keep the work fast
+   * and synchronous-friendly (file I/O, not network calls).
+   */
+  prepareSpawn?(
+    ctx: SandboxSpawnContext
+  ): SandboxSpawnSetup | Promise<SandboxSpawnSetup>
+}
+
+/**
+ * Context passed to {@link SandboxApi.prepareSpawn}. Identifies the Jack
+ * session and the project root being mounted at `/workspace`. Providers
+ * use these to namespace temp files (one settings overlay per session)
+ * and avoid collisions across concurrent sandbox sessions.
+ */
+export interface SandboxSpawnContext {
+  /** Stable per-session id. Safe to embed in temp filenames. */
+  readonly sessionId: string
+  /** Absolute host path mounted at `/workspace` inside the container. */
+  readonly projectPath: string
+}
+
+/**
+ * Return value of {@link SandboxApi.prepareSpawn}. Both fields optional —
+ * a no-op setup just returns `{}`.
+ */
+export interface SandboxSpawnSetup {
+  /**
+   * Mounts to merge with the provider's static {@link configMounts}.
+   * Useful for overlaying generated files (e.g. a sanitized settings.json
+   * mounted on top of a config-dir mount shadows the original entry).
+   */
+  readonly extraMounts?: readonly SandboxConfigMount[]
+  /**
+   * Optional teardown. Invoked once after the container exits, even if
+   * the spawn fails after `prepareSpawn` resolved. Errors are logged but
+   * not propagated — cleanup is best-effort.
+   */
+  cleanup?(): void | Promise<void>
 }