@ottimis/jack-provider-sdk 0.9.0 → 0.13.0

package/dist/cjs/defaults.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Provider-declared user defaults — per-provider "what you want this provider
+ * to pick when a new session is created".
+ *
+ * Three field kinds are supported today: `model`, `effort`, and
+ * `permission_mode`. Each provider declares which of those are meaningful
+ * for its runtime and the catalog of legal values for each. The host owns
+ * storage (via `HostServices.kv`) and resolution (`resolveProviderDefaults`
+ * merges global → workspace → agent layers in the future; v1 is global
+ * only). The provider only declares the **catalog**; it never persists or
+ * resolves values itself.
+ *
+ * Design notes
+ * ------------
+ * - Catalog-only contract. The provider is authoritative on "what's
+ *   settable" and "with which values". The host validates writes against
+ *   this catalog and silently ignores stored values that fall outside it
+ *   (e.g. after a provider bump removed a model).
+ * - Presence-based gating. A provider that doesn't declare `defaults`
+ *   simply doesn't appear in `Settings → Provider defaults` and no
+ *   pre-fill happens. No `CapabilityMatrix` flag needed.
+ * - Open for layering. The resolver signature (`workspaceId?`,
+ *   `agentSlotId?`) is in v1 even though only the global layer is
+ *   implemented, so adding workspace/agent overrides later is a host-only
+ *   change without touching the SDK.
+ *
+ * Cross-references in the existing SDK surface
+ * --------------------------------------------
+ * - `model` overlaps with `JackProvider.modelOptions` (live dropdown) and
+ *   `ProviderModelDefaults.oneShot` (host suggester tasks). The
+ *   `ProviderDefaultsApi` is distinct: it answers "what model do new
+ *   sessions get". A provider typically reuses `modelOptions` as the
+ *   defaults catalog but it's not required (e.g. a provider could hide
+ *   experimental models from the default-picker while keeping them in
+ *   the live switcher).
+ * - `effort` mirrors `JackProvider.effortLevels` semantics. Codex applies
+ *   effort at spawn time; declaring it as a default is how the host
+ *   honours that without an extra dropdown in `NewSessionDialog`.
+ * - `permission_mode` mirrors `CapabilityMatrix.permissionModes`. The
+ *   default is the mode every freshly-created session starts in
+ *   (the user can still cycle it live via Shift-Tab if
+ *   `livePermissionModeSwitch` is true).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=defaults.js.map

package/dist/cjs/defaults.js.map

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

package/dist/cjs/index.js

@@ -49,4 +49,6 @@ __exportStar(require("./usage"), exports);
 __exportStar(require("./host"), exports);
 __exportStar(require("./profiles"), exports);
 __exportStar(require("./sandbox"), exports);
+__exportStar(require("./oneshot"), exports);
+__exportStar(require("./defaults"), 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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;;;;;;;;;;;;;;;;AAEH,4CAAyB;AACzB,4CAAyB;AACzB,6CAA0B;AAC1B,0CAAuB;AACvB,yCAAsB;AACtB,6CAA0B;AAC1B,4CAAyB"}
+{"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;AACzB,4CAAyB;AACzB,6CAA0B"}

package/dist/cjs/oneshot.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=oneshot.js.map

package/dist/cjs/oneshot.js.map

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

package/dist/defaults.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Provider-declared user defaults — per-provider "what you want this provider
+ * to pick when a new session is created".
+ *
+ * Three field kinds are supported today: `model`, `effort`, and
+ * `permission_mode`. Each provider declares which of those are meaningful
+ * for its runtime and the catalog of legal values for each. The host owns
+ * storage (via `HostServices.kv`) and resolution (`resolveProviderDefaults`
+ * merges global → workspace → agent layers in the future; v1 is global
+ * only). The provider only declares the **catalog**; it never persists or
+ * resolves values itself.
+ *
+ * Design notes
+ * ------------
+ * - Catalog-only contract. The provider is authoritative on "what's
+ *   settable" and "with which values". The host validates writes against
+ *   this catalog and silently ignores stored values that fall outside it
+ *   (e.g. after a provider bump removed a model).
+ * - Presence-based gating. A provider that doesn't declare `defaults`
+ *   simply doesn't appear in `Settings → Provider defaults` and no
+ *   pre-fill happens. No `CapabilityMatrix` flag needed.
+ * - Open for layering. The resolver signature (`workspaceId?`,
+ *   `agentSlotId?`) is in v1 even though only the global layer is
+ *   implemented, so adding workspace/agent overrides later is a host-only
+ *   change without touching the SDK.
+ *
+ * Cross-references in the existing SDK surface
+ * --------------------------------------------
+ * - `model` overlaps with `JackProvider.modelOptions` (live dropdown) and
+ *   `ProviderModelDefaults.oneShot` (host suggester tasks). The
+ *   `ProviderDefaultsApi` is distinct: it answers "what model do new
+ *   sessions get". A provider typically reuses `modelOptions` as the
+ *   defaults catalog but it's not required (e.g. a provider could hide
+ *   experimental models from the default-picker while keeping them in
+ *   the live switcher).
+ * - `effort` mirrors `JackProvider.effortLevels` semantics. Codex applies
+ *   effort at spawn time; declaring it as a default is how the host
+ *   honours that without an extra dropdown in `NewSessionDialog`.
+ * - `permission_mode` mirrors `CapabilityMatrix.permissionModes`. The
+ *   default is the mode every freshly-created session starts in
+ *   (the user can still cycle it live via Shift-Tab if
+ *   `livePermissionModeSwitch` is true).
+ */
+import type { AgentEffortLevel, AgentPermissionMode } from './backend';
+/**
+ * One field a provider exposes in the defaults form. Discriminated union
+ * keyed on `kind` so the host renders the right widget (string-id select
+ * for model, enum select for effort, etc.) without provider-specific code.
+ *
+ * `options` is the catalog of legal values. Empty → host hides the field
+ * (parity with `JackProvider.modelOptions` / `effortLevels` semantics).
+ */
+export type ProviderDefaultsField = {
+    kind: 'model';
+    /**
+     * Catalog of model identifiers. `value` is what the host writes into
+     * `sessions.model` at create time; `label` is the human display.
+     * Typically reuses `JackProvider.modelOptions` 1:1 but providers MAY
+     * filter (e.g. hide experimental models from new-session pre-fill).
+     */
+    options: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+} | {
+    kind: 'effort';
+    /**
+     * Catalog of effort tiers. `value` MUST be a member of
+     * {@link AgentEffortLevel}. Renderer falls back to the raw string as
+     * the label.
+     */
+    options: ReadonlyArray<AgentEffortLevel>;
+} | {
+    kind: 'permission_mode';
+    /**
+     * Catalog of permission modes available as session-start defaults.
+     * Typically equals `CapabilityMatrix.permissionModes` but providers
+     * MAY narrow (e.g. exclude `'bypassPermissions'` from the default
+     * picker even when the cycle supports it — the user has to opt in
+     * deliberately).
+     */
+    options: ReadonlyArray<AgentPermissionMode>;
+};
+/**
+ * Provider-declared catalog of configurable defaults. Static — the host
+ * reads `fields` once per provider listing and validates user writes
+ * against it. Empty array would technically be valid but pointless; the
+ * convention is "omit `JackProvider.defaults` entirely" for providers
+ * with no defaults to expose.
+ */
+export type ProviderDefaultsApi = {
+    readonly fields: ReadonlyArray<ProviderDefaultsField>;
+};
+/**
+ * Resolved defaults as the host serialises them per-provider in kv. Every
+ * field is optional — "not set" means "use the provider's runtime default"
+ * (model NULL, effort NULL, permission_mode 'default').
+ *
+ * Stored as a single JSON blob at `provider.<id>.defaults` so partial
+ * writes are atomic and the host can wipe the whole bag in one call.
+ */
+export type ProviderDefaultsValues = {
+    model?: string;
+    effort?: AgentEffortLevel;
+    permissionMode?: AgentPermissionMode;
+};
+/**
+ * Context the host resolver consumes. v1 only honours `providerId` (global
+ * defaults). `workspaceId` and `agentSlotId` are reserved placeholders for
+ * future per-workspace and per-agent overrides — the resolver signature
+ * accepts them today so the call sites can be written once and the host
+ * gains layering later without a callsite change.
+ *
+ * Resolution order (when layering lands): agent slot > workspace > global.
+ * Per-field merge: each field is resolved independently, so an agent slot
+ * can override `model` while letting `permissionMode` fall through to the
+ * global value.
+ */
+export type ProviderDefaultsResolveContext = {
+    providerId: string;
+    /** Reserved for future per-workspace defaults; ignored in v1. */
+    workspaceId?: string;
+    /** Reserved for future per-agent-slot defaults; ignored in v1. */
+    agentSlotId?: string;
+};
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAEtE;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IACE,IAAI,EAAE,OAAO,CAAA;IACb;;;;;OAKG;IACH,OAAO,EAAE,aAAa,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACzD,GACD;IACE,IAAI,EAAE,QAAQ,CAAA;IACd;;;;OAIG;IACH,OAAO,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAA;CACzC,GACD;IACE,IAAI,EAAE,iBAAiB,CAAA;IACvB;;;;;;OAMG;IACH,OAAO,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAA;CAC5C,CAAA;AAEL;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAA;CACtD,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,gBAAgB,CAAA;IACzB,cAAc,CAAC,EAAE,mBAAmB,CAAA;CACrC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,UAAU,EAAE,MAAM,CAAA;IAClB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA"}

package/dist/defaults.js

@@ -0,0 +1,45 @@
+/**
+ * Provider-declared user defaults — per-provider "what you want this provider
+ * to pick when a new session is created".
+ *
+ * Three field kinds are supported today: `model`, `effort`, and
+ * `permission_mode`. Each provider declares which of those are meaningful
+ * for its runtime and the catalog of legal values for each. The host owns
+ * storage (via `HostServices.kv`) and resolution (`resolveProviderDefaults`
+ * merges global → workspace → agent layers in the future; v1 is global
+ * only). The provider only declares the **catalog**; it never persists or
+ * resolves values itself.
+ *
+ * Design notes
+ * ------------
+ * - Catalog-only contract. The provider is authoritative on "what's
+ *   settable" and "with which values". The host validates writes against
+ *   this catalog and silently ignores stored values that fall outside it
+ *   (e.g. after a provider bump removed a model).
+ * - Presence-based gating. A provider that doesn't declare `defaults`
+ *   simply doesn't appear in `Settings → Provider defaults` and no
+ *   pre-fill happens. No `CapabilityMatrix` flag needed.
+ * - Open for layering. The resolver signature (`workspaceId?`,
+ *   `agentSlotId?`) is in v1 even though only the global layer is
+ *   implemented, so adding workspace/agent overrides later is a host-only
+ *   change without touching the SDK.
+ *
+ * Cross-references in the existing SDK surface
+ * --------------------------------------------
+ * - `model` overlaps with `JackProvider.modelOptions` (live dropdown) and
+ *   `ProviderModelDefaults.oneShot` (host suggester tasks). The
+ *   `ProviderDefaultsApi` is distinct: it answers "what model do new
+ *   sessions get". A provider typically reuses `modelOptions` as the
+ *   defaults catalog but it's not required (e.g. a provider could hide
+ *   experimental models from the default-picker while keeping them in
+ *   the live switcher).
+ * - `effort` mirrors `JackProvider.effortLevels` semantics. Codex applies
+ *   effort at spawn time; declaring it as a default is how the host
+ *   honours that without an extra dropdown in `NewSessionDialog`.
+ * - `permission_mode` mirrors `CapabilityMatrix.permissionModes`. The
+ *   default is the mode every freshly-created session starts in
+ *   (the user can still cycle it live via Shift-Tab if
+ *   `livePermissionModeSwitch` is true).
+ */
+export {};
+//# sourceMappingURL=defaults.js.map

package/dist/defaults.js.map

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

package/dist/host.d.ts

@@ -157,5 +157,22 @@ export type HostServices = {
     kv: HostKvScope;
     /** Auth flow primitives (cookie login today; OAuth / device-code in the future). */
     auth: HostAuthService;
+    /**
+     * Number of sessions currently pinned to a given profile id. Used by
+     * providers that surface profiles (`JackProvider.profiles`) to gate
+     * destructive operations:
+     *
+     *   - `remove(profileId)` refuses when count > 0 so the user can't
+     *     orphan the chat history of any pinned session.
+     *   - `update(profileId, { configDir })` may surface a confirm dialog
+     *     when count > 0 (UI-side concern; the API itself stays open since
+     *     the user can move the on-disk `projects/`/rollouts folder
+     *     manually to preserve history).
+     *
+     * Optional: providers without a profile concept never call it. The
+     * host implementation reads `SELECT COUNT(*) FROM sessions WHERE
+     * profile_id = ?`.
+     */
+    profileUsageCount?(profileId: string): number;
 };
 //# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -1 +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"}
+{"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;IACrB;;;;;;;;;;;;;;;OAeG;IACH,iBAAiB,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAA;CAC9C,CAAA"}

package/dist/index.d.ts

@@ -33,6 +33,8 @@ export * from './usage';
 export * from './host';
 export * from './profiles';
 export * from './sandbox';
+export * from './oneshot';
+export * from './defaults';
 /**
  * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"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;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAE1B;;;;;GAKG;AACH,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/index.js

@@ -33,4 +33,6 @@ export * from './usage';
 export * from './host';
 export * from './profiles';
 export * from './sandbox';
+export * from './oneshot';
+export * from './defaults';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"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"}
+{"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;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA"}

package/dist/oneshot.d.ts

@@ -0,0 +1,81 @@
+/**
+ * One-shot completion capability — fire-and-forget AI calls outside the
+ * lifetime of a session.
+ *
+ * Use cases the host wires this for:
+ *   - Auto-generate a commit message from a staged diff (CommitComposer).
+ *   - Future: summarize a tool result, propose a search query, name a
+ *     workspace from its first prompt, etc.
+ *
+ * Distinct from {@link AgentBackend.query} on purpose:
+ *   - No tools, no MCP, no permission flow, no resume.
+ *   - No persisted session — the provider MUST NOT leave artifacts on disk.
+ *   - Returns plain text, synchronously to the caller (no streaming UI).
+ *   - Reuses whatever auth/credentials the user already has (CLI cookie,
+ *     API key, OAuth token) — same source as session calls.
+ *
+ * Provider implementations are expected to be **cheap and fast**: pick the
+ * smallest reasonable model the user is authenticated for, no agentic
+ * loops, no tool definitions, no caching beyond what the platform does on
+ * its own. A typical call should complete in well under a second.
+ */
+export type OneshotCompleteOptions = {
+    /**
+     * The user prompt — what the model should respond to. The host builds
+     * this string by interpolating the relevant context (diff, branch,
+     * recent commit subjects, …) into a stable template; providers MUST
+     * NOT re-prompt or transform it beyond what's needed for their wire
+     * format.
+     */
+    prompt: string;
+    /**
+     * Optional system prompt. Use sparingly — keeping the host-side prompt
+     * provider-neutral means we can fan out the same call across providers
+     * without re-tuning. Implementations that don't have a system slot
+     * (rare) MAY prepend this to `prompt` and document the choice.
+     */
+    system?: string;
+    /**
+     * Cap on output tokens. Providers MUST honor it as best they can; the
+     * host treats overruns as warnings, not errors. Defaults are
+     * provider-specific.
+     */
+    maxOutputTokens?: number;
+    /**
+     * Cap on wall-clock time. Providers SHOULD abort the underlying request
+     * when the deadline is exceeded and reject the returned promise rather
+     * than block the caller forever. Default is provider-specific.
+     */
+    timeoutMs?: number;
+    /**
+     * AbortSignal — host-controlled cancellation. Providers MUST wire this
+     * into their underlying HTTP / process call so the renderer can drop a
+     * pending generation when the user closes the dialog or navigates away.
+     */
+    signal?: AbortSignal;
+};
+/**
+ * One-shot completion API — optional capability on {@link JackProvider}.
+ *
+ * Providers that expose this MUST also declare `capabilities.oneshot =
+ * true`. The host uses the capability flag to gate UI affordances (button
+ * disabled, tooltip explaining "active provider doesn't support this")
+ * before ever calling into the provider, so the API surface stays simple:
+ * providers don't need to throw a "not implemented" error — they just
+ * leave the field undefined.
+ */
+export type OneshotApi = {
+    /**
+     * Run a single non-agentic completion and return the assistant's text
+     * verbatim — no streaming, no tool calls, no follow-up turns.
+     *
+     * Errors:
+     *   - Network / auth: reject with the underlying error. Host catches and
+     *     surfaces a toast.
+     *   - AbortSignal aborted: reject with `DOMException('AbortError')`.
+     *   - Empty / malformed model output: return an empty string. Host
+     *     treats empty as "no suggestion" and keeps the textarea unchanged.
+     */
+    complete(opts: OneshotCompleteOptions): Promise<string>;
+};
+//# sourceMappingURL=oneshot.d.ts.map

package/dist/oneshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oneshot.d.ts","sourceRoot":"","sources":["../src/oneshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACxD,CAAA"}

package/dist/oneshot.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=oneshot.js.map

package/dist/oneshot.js.map

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

package/dist/provider.d.ts

@@ -16,7 +16,9 @@
  * it free of provider-specific imports.
  */
 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';
@@ -29,7 +31,7 @@ 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.
  * The renderer uses these for autocomplete + chip rendering.
@@ -40,7 +42,7 @@ type SlashCommandDefBase = {
     argumentHint?: string;
 };
 /**
- * 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
@@ -53,6 +55,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
@@ -67,7 +77,34 @@ export type SlashCommandDef = (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
  * them into the session transcript. Claude uses
@@ -137,6 +174,75 @@ export type SlashCommandSupport = {
      * collisions, since it reflects the agent's actual runtime state).
      */
     subscribeToWireCommands?(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;
 };
 /**
  * Options for {@link JackProvider.readSessionTranscript}. Provider-neutral
@@ -158,6 +264,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;
 };
 /**
  * Provider-declared model identifiers used by host one-shot tasks. These
@@ -282,6 +401,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
@@ -682,6 +810,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