dsh-coding-subscription-oauth 0.5.0

package/lib/capability-routes.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Plugin-owned same-origin Web routes for the capability-settings namespace.
+ * Arbitrary Host settings namespaces are not remotely exposed, so this plugin
+ * publishes only the secret-free snapshot and the two optional read surfaces.
+ * @module dsh-coding-subscription-oauth/capability-routes
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type CapabilitySettings, type CapabilitySettingsPatch, type CapabilitySettingsSnapshot } from "./capability-settings.js";
+export declare const CAPABILITY_SETTINGS_PATH = "/plugins/dsh-grok-build/capabilities";
+export declare const CODEX_USAGE_PATH = "/plugins/dsh-grok-build/codex/usage";
+export declare const IMAGINE_CREDENTIAL_STATUS_PATH = "/plugins/dsh-grok-build/imagine/credential-status";
+/** Structural `ctx.webServer` + `ctx.effect` surface used by the registrar. */
+export interface CapabilityRouteContext {
+    readonly webServer: {
+        register(route: {
+            kind: "exact" | "prefix";
+            path: string;
+            handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+        }): () => void;
+    };
+    effect(callback: () => () => void | Promise<void>, label?: string): unknown;
+}
+/** Owner-facing subset of {@link import("./capability-settings.js").CapabilitySettingsController}. */
+export interface CapabilityRouteController {
+    snapshot(): CapabilitySettingsSnapshot;
+    current(): CapabilitySettings;
+    patch(patch: CapabilitySettingsPatch, expectedRevision: number): Promise<CapabilitySettingsSnapshot>;
+    replace(section: CapabilitySettingsPatch, expectedRevision: number): Promise<CapabilitySettingsSnapshot>;
+}
+/** Secret-free Imagine credential probe returned on the optional status route. */
+export interface ImagineCredentialStatus {
+    readonly configured: boolean;
+    readonly source: string;
+    readonly writable: boolean;
+}
+export interface CapabilityRouteOptions {
+    readonly controller: CapabilityRouteController;
+    readonly usage?: () => unknown | Promise<unknown>;
+    readonly credentialInfo?: () => unknown | Promise<unknown>;
+}
+/** Register the plugin-owned capability routes. Owns and returns the route disposer. */
+export declare function registerCapabilityRoutes(ctx: CapabilityRouteContext, options: CapabilityRouteOptions): () => void;
+//# sourceMappingURL=capability-routes.d.ts.map

package/lib/capability-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-routes.d.ts","sourceRoot":"","sources":["../../src/capability-routes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAEN,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAI/B,MAAM,0BAA0B,CAAC;AAMlC,eAAO,MAAM,wBAAwB,yCAAyC,CAAC;AAC/E,eAAO,MAAM,gBAAgB,wCAAwC,CAAC;AACtE,eAAO,MAAM,8BAA8B,sDAAsD,CAAC;AAElG,+EAA+E;AAC/E,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,SAAS,EAAE;QACnB,QAAQ,CAAC,KAAK,EAAE;YACf,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;YACzB,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;SAC7E,GAAG,MAAM,IAAI,CAAC;KACf,CAAC;IACF,MAAM,CAAC,QAAQ,EAAE,MAAM,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5E;AAED,sGAAsG;AACtG,MAAM,WAAW,yBAAyB;IACzC,QAAQ,IAAI,0BAA0B,CAAC;IACvC,OAAO,IAAI,kBAAkB,CAAC;IAC9B,KAAK,CAAC,KAAK,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACrG,OAAO,CAAC,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;CACzG;AAED,kFAAkF;AAClF,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,UAAU,EAAE,yBAAyB,CAAC;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3D;AAYD,wFAAwF;AACxF,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,sBAAsB,EAAE,OAAO,EAAE,sBAAsB,GAAG,MAAM,IAAI,CA4BjH"}

package/lib/capability-runtime.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Side-effect coordination for default-off optional capabilities.
+ *
+ * This module contains no Cordis service lookup. The parent supplies structural
+ * registries, which keeps live flag transitions deterministic and unit-testable.
+ * @module dsh-coding-subscription-oauth/capability-runtime
+ */
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+import { type CapabilitySettings } from "./capability-settings.js";
+import type { CodexModelCapabilities } from "./codex-model-capabilities.js";
+import type { CodexSearchProvider } from "./codex-search.js";
+export type CapabilityRuntimeListener = (settings: CapabilitySettings) => void | Promise<void>;
+/** Process-local live projection shared by optional service fibers. */
+export declare class CapabilityRuntimeState {
+    private value;
+    private readonly listeners;
+    private readonly onListenerError;
+    constructor(initial?: CapabilitySettings, onListenerError?: (error: unknown) => void);
+    current(): CapabilitySettings;
+    set(next: unknown): CapabilitySettings;
+    /** Re-run live bindings after an external dependency (for example OAuth) changed. */
+    refresh(): void;
+    reset(): CapabilitySettings;
+    subscribe(listener: CapabilityRuntimeListener, emitCurrent?: boolean): () => void;
+}
+export interface CapabilitySearchRegistry {
+    registerSearchProvider(provider: CodexSearchProvider): () => void;
+}
+/** Dynamically expose search and clamp every request to the live result limit. */
+export declare function bindCapabilitySearch(state: CapabilityRuntimeState, registry: CapabilitySearchRegistry, provider: CodexSearchProvider): () => void;
+export interface CapabilityToolRegistry {
+    register(definition: ToolDefinition): () => void;
+}
+/** Return whether one optional tool should currently be advertised. */
+export declare function capabilityToolEnabled(name: string, settings: CapabilitySettings): boolean;
+/** Dynamically advertise only enabled tools; execute-time guards remain in each definition. */
+export declare function bindCapabilityTools(state: CapabilityRuntimeState, registry: CapabilityToolRegistry, definitions: readonly ToolDefinition[]): () => void;
+export interface ReplaceableAdapterRegistration {
+    replace(routes: string[]): void;
+}
+export interface CapabilityTimer {
+    setInterval(callback: () => void, ms: number): unknown;
+    clearInterval(handle: unknown): void;
+}
+export interface CodexFastBindingOptions {
+    readonly refreshIntervalMs?: number;
+    readonly timer?: CapabilityTimer;
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * Publish the Fast route only after a fresh live catalog explicitly lists at
+ * least one priority-eligible model. Disabling is synchronous; stale or failed
+ * refreshes atomically withdraw the optional route.
+ */
+export declare function bindCodexFastRoute(state: CapabilityRuntimeState, capabilities: CodexModelCapabilities, registration: ReplaceableAdapterRegistration, options?: CodexFastBindingOptions): () => void;
+//# sourceMappingURL=capability-runtime.d.ts.map

package/lib/capability-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-runtime.d.ts","sourceRoot":"","sources":["../../src/capability-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EACN,KAAK,kBAAkB,EAGvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAyC,MAAM,mBAAmB,CAAC;AAIpG,MAAM,MAAM,yBAAyB,GAAG,CAAC,QAAQ,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/F,uEAAuE;AACvE,qBAAa,sBAAsB;IAClC,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA2B;gBAG1D,OAAO,GAAE,kBAAgD,EACzD,eAAe,GAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAsB;IAM5D,OAAO,IAAI,kBAAkB;IAI7B,GAAG,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB;IAQtC,qFAAqF;IACrF,OAAO,IAAI,IAAI;IAWf,KAAK,IAAI,kBAAkB;IAI3B,SAAS,CAAC,QAAQ,EAAE,yBAAyB,EAAE,WAAW,UAAO,GAAG,MAAM,IAAI;CAoB9E;AAED,MAAM,WAAW,wBAAwB;IACxC,sBAAsB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,IAAI,CAAC;CAClE;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,CACnC,KAAK,EAAE,sBAAsB,EAC7B,QAAQ,EAAE,wBAAwB,EAClC,QAAQ,EAAE,mBAAmB,GAC3B,MAAM,IAAI,CAmCZ;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,UAAU,EAAE,cAAc,GAAG,MAAM,IAAI,CAAC;CACjD;AAED,uEAAuE;AACvE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAczF;AAED,+FAA+F;AAC/F,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,sBAAsB,EAC7B,QAAQ,EAAE,sBAAsB,EAChC,WAAW,EAAE,SAAS,cAAc,EAAE,GACpC,MAAM,IAAI,CAyBZ;AAED,MAAM,WAAW,8BAA8B;IAC9C,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC/B,WAAW,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACvD,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC5C;AAID;;;;GAIG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,sBAAsB,EAC7B,YAAY,EAAE,sBAAsB,EACpC,YAAY,EAAE,8BAA8B,EAC5C,OAAO,GAAE,uBAA4B,GACnC,MAAM,IAAI,CAoFZ"}

package/lib/capability-settings.d.ts

@@ -0,0 +1,263 @@
+import Schema from "@deepseek-ai/schemastery";
+/**
+ * Integration-ready capability settings controller for the
+ * `coding-subscription-oauth` namespace. Schema defaults sit under the
+ * composition/YAML `base`, and the user section layers on top. The controller
+ * talks to an injected structural settings service while registering a real
+ * Schemastery section that the Host settings service can render and validate.
+ * @module dsh-coding-subscription-oauth/capability-settings
+ */
+/** Settings namespace owned by this plugin. */
+export declare const CAPABILITY_SETTINGS_NAMESPACE = "coding-subscription-oauth";
+/** Default-off capability flags. Presence in the user section marks an override. */
+export declare const CAPABILITY_FLAG_KEYS: readonly ["codexSearch", "codexImages", "codexImageEdits", "codexUsage", "codexFast", "grokImagineImage", "grokImagineVideo"];
+/** Conservative numeric limits persisted beside the flags. */
+export declare const CAPABILITY_LIMIT_KEYS: readonly ["searchResults", "imageCount", "videoArtifactTtlMs"];
+/** Every key the controller admits into secret-free state. */
+export declare const CAPABILITY_SETTINGS_KEYS: readonly ["codexSearch", "codexImages", "codexImageEdits", "codexUsage", "codexFast", "grokImagineImage", "grokImagineVideo", "searchResults", "imageCount", "videoArtifactTtlMs"];
+export type CapabilityFlagKey = (typeof CAPABILITY_FLAG_KEYS)[number];
+export type CapabilityLimitKey = (typeof CAPABILITY_LIMIT_KEYS)[number];
+export type CapabilitySettingsKey = (typeof CAPABILITY_SETTINGS_KEYS)[number];
+/** Resolved, secret-free capability section. */
+export interface CapabilitySettings {
+    readonly codexSearch: boolean;
+    readonly codexImages: boolean;
+    readonly codexImageEdits: boolean;
+    readonly codexUsage: boolean;
+    readonly codexFast: boolean;
+    readonly grokImagineImage: boolean;
+    readonly grokImagineVideo: boolean;
+    readonly searchResults: number;
+    readonly imageCount: number;
+    readonly videoArtifactTtlMs: number;
+}
+/** Sparse overlay used for YAML/composition `base` and the user section. */
+export type CapabilitySettingsPatch = Partial<CapabilitySettings>;
+/** Inclusive bounds and schema defaults for each numeric limit. */
+export declare const CAPABILITY_SETTINGS_BOUNDS: {
+    readonly searchResults: {
+        readonly min: 1;
+        readonly max: 20;
+        readonly default: 5;
+    };
+    readonly imageCount: {
+        readonly min: 1;
+        readonly max: 4;
+        readonly default: 1;
+    };
+    readonly videoArtifactTtlMs: {
+        readonly min: number;
+        readonly max: number;
+        readonly default: number;
+    };
+};
+/** Schema defaults: every flag off, every limit at its conservative default. */
+export declare const DEFAULT_CAPABILITY_SETTINGS: CapabilitySettings;
+/**
+ * Real Schemastery schema registered with the Host settings service. Defaults
+ * remain conservative, and bounds are enforced before a user document commits.
+ */
+export declare const CapabilitySettingsSchema: Schema<Schemastery.ObjectS<{
+    codexSearch: Schema<boolean, boolean>;
+    codexImages: Schema<boolean, boolean>;
+    codexImageEdits: Schema<boolean, boolean>;
+    codexUsage: Schema<boolean, boolean>;
+    codexFast: Schema<boolean, boolean>;
+    grokImagineImage: Schema<boolean, boolean>;
+    grokImagineVideo: Schema<boolean, boolean>;
+    searchResults: Schema<number, number>;
+    imageCount: Schema<number, number>;
+    videoArtifactTtlMs: Schema<number, number>;
+}>, Schemastery.ObjectT<{
+    codexSearch: Schema<boolean, boolean>;
+    codexImages: Schema<boolean, boolean>;
+    codexImageEdits: Schema<boolean, boolean>;
+    codexUsage: Schema<boolean, boolean>;
+    codexFast: Schema<boolean, boolean>;
+    grokImagineImage: Schema<boolean, boolean>;
+    grokImagineVideo: Schema<boolean, boolean>;
+    searchResults: Schema<number, number>;
+    imageCount: Schema<number, number>;
+    videoArtifactTtlMs: Schema<number, number>;
+}>>;
+/** Serialized schema metadata consumed by Settings UI tests and diagnostics. */
+export declare const CAPABILITY_SETTINGS_SCHEMA_JSON: Schema<Schemastery.ObjectS<{
+    codexSearch: Schema<boolean, boolean>;
+    codexImages: Schema<boolean, boolean>;
+    codexImageEdits: Schema<boolean, boolean>;
+    codexUsage: Schema<boolean, boolean>;
+    codexFast: Schema<boolean, boolean>;
+    grokImagineImage: Schema<boolean, boolean>;
+    grokImagineVideo: Schema<boolean, boolean>;
+    searchResults: Schema<number, number>;
+    imageCount: Schema<number, number>;
+    videoArtifactTtlMs: Schema<number, number>;
+}>, Schemastery.ObjectT<{
+    codexSearch: Schema<boolean, boolean>;
+    codexImages: Schema<boolean, boolean>;
+    codexImageEdits: Schema<boolean, boolean>;
+    codexUsage: Schema<boolean, boolean>;
+    codexFast: Schema<boolean, boolean>;
+    grokImagineImage: Schema<boolean, boolean>;
+    grokImagineVideo: Schema<boolean, boolean>;
+    searchResults: Schema<number, number>;
+    imageCount: Schema<number, number>;
+    videoArtifactTtlMs: Schema<number, number>;
+}>>;
+export type CapabilitySettingsSchemaType = typeof CapabilitySettingsSchema;
+/** Revision-bearing, secret-free snapshot used for CAS writes and UI. */
+export interface CapabilitySettingsSnapshot {
+    readonly ns: typeof CAPABILITY_SETTINGS_NAMESPACE;
+    readonly value: CapabilitySettings;
+    readonly base?: CapabilitySettingsPatch;
+    readonly user?: CapabilitySettingsPatch;
+    readonly revision: number;
+    readonly writable: boolean;
+    readonly applies: "live";
+    readonly secrets: readonly [];
+}
+/** Owner-facing subset of `ctx.settings.register()` used when the parent injects a provider. */
+export interface CapabilitySettingsScope {
+    get(): unknown;
+    watch(callback: (next: unknown, prev: unknown) => void | Promise<void>): () => void;
+    update(patch: object): Promise<void>;
+    replace(section: object): Promise<void>;
+}
+/** One namespace descriptor as returned by a structural `describe()`. */
+export interface CapabilitySettingsDescriptor {
+    readonly ns: string;
+    readonly value?: unknown;
+    readonly base?: unknown;
+    readonly user?: unknown;
+    readonly revision?: number;
+    readonly applies?: "live" | "restart";
+    readonly secrets?: readonly {
+        readonly path?: readonly string[];
+        readonly set?: boolean;
+    }[];
+}
+/**
+ * Duck-typed settings service. A real `ctx.settings` satisfies this without a
+ * compile-time dependency on `@deepseek-ai/dsh-settings`.
+ */
+export interface CapabilitySettingsService {
+    readonly writable?: boolean;
+    describe?(options?: {
+        readonly redactSecrets?: boolean;
+    }): readonly CapabilitySettingsDescriptor[];
+    get?(ns: string): unknown;
+    update?(ns: string, patch: object, expectedRevision?: number): Promise<void>;
+    replace?(ns: string, section: object, expectedRevision?: number): Promise<void>;
+    register?(ns: string, schema: CapabilitySettingsSchemaType, options?: {
+        readonly base?: CapabilitySettingsPatch;
+        readonly applies?: "live" | "restart";
+        readonly validate?: (value: CapabilitySettings) => void;
+    }): CapabilitySettingsScope;
+}
+/** Construction options. `base` is the YAML / composition entry layered under the user section. */
+export interface CapabilitySettingsControllerOptions {
+    readonly settings?: CapabilitySettingsService | undefined;
+    readonly base?: CapabilitySettingsPatch | undefined;
+    /** Contain both synchronous and asynchronous observer failures. */
+    readonly onListenerError?: ((error: unknown) => void) | undefined;
+}
+/** Listener invoked after a committed snapshot change. */
+export type CapabilitySettingsListener = (snapshot: CapabilitySettingsSnapshot) => void | Promise<void>;
+/**
+ * A write refused because the namespace moved since the caller read it.
+ * `code` matches the Host settings seam so a later wire layer can map it.
+ */
+export declare class CapabilitySettingsConflictError extends Error {
+    readonly code = "SETTINGS_CONFLICT";
+    readonly ns = "coding-subscription-oauth";
+    readonly expected: number;
+    readonly actual: number;
+    constructor(expected: number, actual: number);
+}
+/** A write refused because no writable settings provider is attached. */
+export declare class CapabilitySettingsReadOnlyError extends Error {
+    readonly code: "SETTINGS_PROVIDER_ABSENT" | "SETTINGS_READ_ONLY" | "SETTINGS_DISPOSED";
+    readonly ns = "coding-subscription-oauth";
+    readonly reason: "absent" | "read-only" | "disposed";
+    constructor(reason: "absent" | "read-only" | "disposed");
+}
+export declare function isCapabilitySettingsConflictError(error: unknown): error is CapabilitySettingsConflictError;
+export declare function isCapabilitySettingsReadOnlyError(error: unknown): error is CapabilitySettingsReadOnlyError;
+/** Pick every independently default-off flag from a resolved section. */
+export declare function capabilityFlags(settings: CapabilitySettings): Pick<CapabilitySettings, CapabilityFlagKey>;
+/** Pick the conservative numeric limits from a resolved section. */
+export declare function capabilityLimits(settings: CapabilitySettings): Pick<CapabilitySettings, CapabilityLimitKey>;
+/** Layer schema defaults, then YAML/composition `base`, then the user section. */
+export declare function resolveCapabilitySettings(base?: CapabilitySettingsPatch | undefined, user?: CapabilitySettingsPatch | undefined): CapabilitySettings;
+/**
+ * Admit a candidate section: known keys only, flags default off, limits clamped,
+ * secret-shaped keys dropped. Used for both reads and the structural schema.
+ */
+export declare function normalizeCapabilitySettings(input?: unknown): CapabilitySettings;
+/**
+ * Normalize a sparse overlay. Invalid or secret fields are omitted so a lower
+ * layer (YAML base / schema default) remains authoritative for that key.
+ */
+export declare function normalizeCapabilitySettingsPatch(input?: unknown): CapabilitySettingsPatch;
+/**
+ * Strictly admit a caller-authored sparse section before normalizing it. Reads
+ * remain compatibility-tolerant, but writes must never silently drop unknown
+ * fields, coerce types, truncate decimals, or clamp out-of-range limits.
+ */
+export declare function assertCapabilitySettingsPatch(input: unknown, label?: string): asserts input is CapabilitySettingsPatch;
+/** Reject a resolved section the owner could not act on. Schema-valid by construction after normalize. */
+export declare function assertServiceableCapabilitySettings(value: CapabilitySettings): void;
+/**
+ * Live capability-settings controller. Without an injected provider the
+ * resolved state is the YAML/default layer and every write fails explicitly.
+ */
+export declare class CapabilitySettingsController {
+    readonly ns = "coding-subscription-oauth";
+    private readonly settings;
+    private readonly base;
+    private readonly onListenerError;
+    private readonly listeners;
+    private scope;
+    private scopeDisposer;
+    private localRevision;
+    private lastSnapshot;
+    private disposed;
+    constructor(options?: CapabilitySettingsControllerOptions);
+    /** Current revision-bearing snapshot. Re-reads the injected provider when present. */
+    snapshot(): CapabilitySettingsSnapshot;
+    /** Resolved capability section (schema defaults ← YAML base ← user). */
+    current(): CapabilitySettings;
+    /**
+     * Merge a secret-free patch into the user layer using compare-and-swap on
+     * `expectedRevision` from a previously read {@link snapshot}.
+     */
+    patch(patch: CapabilitySettingsPatch, expectedRevision: number): Promise<CapabilitySettingsSnapshot>;
+    /**
+     * Replace the user section wholesale (`{}` re-inherits YAML base and defaults).
+     * Compare-and-swap uses the same revision token as {@link patch}.
+     */
+    replace(section: CapabilitySettingsPatch, expectedRevision: number): Promise<CapabilitySettingsSnapshot>;
+    /**
+     * Observe committed snapshot changes. The disposer removes this listener;
+     * an invocation already running still settles.
+     */
+    subscribe(listener: CapabilitySettingsListener): () => void;
+    /**
+     * Re-read the injected provider (or the local YAML/default layer) and notify
+     * listeners when the secret-free snapshot moved.
+     */
+    reconcile(): CapabilitySettingsSnapshot;
+    /** Drop the register() watcher and every listener. Further writes fail. */
+    dispose(): void;
+    private attachScope;
+    private writeReason;
+    private isWritable;
+    private write;
+    private readSnapshot;
+    private readResolvedFromService;
+    private readDescribed;
+    private publish;
+}
+/** Construct a {@link CapabilitySettingsController}. */
+export declare function createCapabilitySettingsController(options?: CapabilitySettingsControllerOptions): CapabilitySettingsController;
+//# sourceMappingURL=capability-settings.d.ts.map

package/lib/capability-settings.d.ts.map

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

package/lib/capability-tools.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Optional Codex / Grok Imagine tool definitions. The factory only returns
+ * public `ToolDefinition` objects — it never registers on `ctx.tools`.
+ * Feature flags and `imageCount` are re-read from `current()` at execute time.
+ * @module dsh-coding-subscription-oauth/capability-tools
+ */
+import type { ToolDefinition, ToolRunContext } from "@deepseek-ai/dsh-tools";
+import { type CapabilitySettings } from "./capability-settings.js";
+import type { CodexAuthSession } from "./codex-http.js";
+import { type CodexImageAttachmentStore, type CodexImageController, type CodexImageRoute, type CodexImageSessionContext } from "./codex-images.js";
+import { type GrokImagineClient } from "./grok-imagine.js";
+export declare const CODEX_IMAGE_GENERATE_TOOL = "codex_image_generate";
+export declare const CODEX_IMAGE_EDIT_TOOL = "codex_image_edit";
+export { GROK_IMAGINE_IMAGE_TOOL, GROK_IMAGINE_VIDEO_STATUS_TOOL, GROK_IMAGINE_VIDEO_TOOL, } from "./grok-imagine.js";
+/** Shared client surface; production passes one `GrokImagineClient` so video status can see started jobs. */
+export type CapabilityImagineClient = Pick<GrokImagineClient, "generateImage" | "startVideo" | "videoStatus">;
+/** Per-exec Codex controller factory. Tests inject a fake; production binds auth + attachments. */
+export type CreateCodexImageController = (session: CodexImageSessionContext) => CodexImageController;
+/** Resolve authoritative host model metadata for the calling route. */
+export type ResolveCodexImageRoute = (exec: ToolRunContext) => Promise<CodexImageRoute | undefined>;
+/** Exact provider/model identity from the live request header, then agent options. */
+export declare function callingRouteIdentity(exec: ToolRunContext): {
+    provider: string;
+    model: string;
+} | undefined;
+/**
+ * Copy host-resolved modalities onto the calling identity. Never invents
+ * `inputModalities`; lookup failures keep the identity and omit the field so
+ * the image-capability gate fails closed.
+ */
+export declare function resolveCodexImageRouteFromLlm(exec: ToolRunContext, resolveModelInfo: (provider: string, model: string, signal?: AbortSignal) => Promise<{
+    inputModalities?: readonly string[];
+}>): Promise<CodexImageRoute | undefined>;
+export interface CapabilityToolsOptions {
+    /** Live capability section. Re-read on every execute so a disable takes effect immediately. */
+    current(): CapabilitySettings;
+    readonly auth: CodexAuthSession;
+    readonly attachments: CodexImageAttachmentStore;
+    readonly imagine: CapabilityImagineClient;
+    readonly createCodexController?: CreateCodexImageController;
+    readonly resolveCodexImageRoute?: ResolveCodexImageRoute;
+}
+/**
+ * Build the five optional capability tools. Callers register the returned
+ * definitions; this function has no Cordis / registry side effects. The tools
+ * peer is loaded only after Cordis has composed the optional `tools` service.
+ */
+export declare function createCapabilityTools(options: CapabilityToolsOptions): Promise<readonly ToolDefinition[]>;
+export declare const CAPABILITY_TOOL_NAMES: readonly ["codex_image_generate", "codex_image_edit", "grok_imagine_image", "grok_imagine_video", "grok_imagine_video_status"];
+//# sourceMappingURL=capability-tools.d.ts.map

package/lib/capability-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-tools.d.ts","sourceRoot":"","sources":["../../src/capability-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAA8B,KAAK,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC/F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAMN,KAAK,yBAAyB,EAE9B,KAAK,oBAAoB,EAGzB,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAG7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAON,KAAK,iBAAiB,EAkBtB,MAAM,mBAAmB,CAAC;AAG3B,eAAO,MAAM,yBAAyB,yBAAyB,CAAC;AAChE,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD,OAAO,EACN,uBAAuB,EACvB,8BAA8B,EAC9B,uBAAuB,GACvB,MAAM,mBAAmB,CAAC;AAO3B,6GAA6G;AAC7G,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,iBAAiB,EAAE,eAAe,GAAG,YAAY,GAAG,aAAa,CAAC,CAAC;AAE9G,mGAAmG;AACnG,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,EAAE,wBAAwB,KAAK,oBAAoB,CAAC;AAErG,uEAAuE;AACvE,MAAM,MAAM,sBAAsB,GAAG,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAAC;AAEpG,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,cAAc,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAS1G;AAED;;;;GAIG;AACH,wBAAsB,6BAA6B,CAClD,IAAI,EAAE,cAAc,EACpB,gBAAgB,EAAE,CACjB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,KAChB,OAAO,CAAC;IAAE,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC,GACnD,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAatC;AAED,MAAM,WAAW,sBAAsB;IACtC,+FAA+F;IAC/F,OAAO,IAAI,kBAAkB,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,yBAAyB,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAC1C,QAAQ,CAAC,qBAAqB,CAAC,EAAE,0BAA0B,CAAC;IAC5D,QAAQ,CAAC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;CACzD;AAiQD;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CA6Q/G;AAED,eAAO,MAAM,qBAAqB,gIAMxB,CAAC"}

package/lib/catalog.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Account-specific Grok Build catalog: live GET /v1/models-v2 merged onto the
+ * static baseline descriptors. Failures keep the last good list, then the
+ * static baseline.
+ * @module dsh-coding-subscription-oauth/catalog
+ */
+import type { Api, Model, ThinkingLevelMap } from "@earendil-works/pi-ai";
+export type CatalogSource = "live" | "cache" | "fallback";
+/** Vendor listing fields we keep after a live `/models-v2` fetch. */
+export interface LiveModelDescriptor {
+    id: string;
+    name?: string;
+    contextWindow?: number;
+    reasoning?: boolean;
+    thinkingLevelMap?: ThinkingLevelMap;
+}
+/**
+ * Translate Grok Build `reasoning_efforts` into a pi-ai map. Undeclared
+ * extended levels (especially `xhigh`) must be pinned to null — pi-ai treats
+ * an absent xhigh/max key as unsupported, and an absent low/medium/high key
+ * as supported.
+ */
+export declare function thinkingLevelMapFromLiveEfforts(efforts: unknown): ThinkingLevelMap | undefined;
+/** Pull the live listing, including per-model reasoning levels when present. */
+export declare function extractLiveModels(body: unknown): LiveModelDescriptor[];
+/**
+ * Pull model ids from a listing body. The `/v1/models-v2` response shape is
+ * not a published contract, so accept the common envelopes: a bare array, an
+ * OpenAI-style `{ data: [...] }`, or `{ models: [...] }`; rows may be plain
+ * ids or objects with an `id` field.
+ */
+export declare function extractModelIds(body: unknown): string[];
+/** Turn a live id into a pi-ai model, inheriting baseline metadata when possible. */
+export declare function materializeLiveModel(id: string, catalog?: readonly Model<Api>[], overlay?: LiveModelDescriptor): Model<Api>;
+/**
+ * If `liveIds` is missing or empty, serve the baseline catalog.
+ * Otherwise serve only the live ids, each materialized against the baseline
+ * and optionally overlaid with live `/models-v2` reasoning metadata.
+ */
+export declare function mergeLiveCatalog(catalog: readonly Model<Api>[], liveIds: readonly string[] | undefined, liveModels?: readonly LiveModelDescriptor[]): Model<Api>[];
+export declare function preferredGrokBuildModelFrom(models: readonly {
+    id: string;
+}[]): string;
+/**
+ * Fetch the account-visible models from `/v1/models-v2` with the CLI
+ * fingerprint headers. Throws a secret-free error on failure.
+ */
+export declare function fetchLiveModels(accessToken: string, signal?: AbortSignal): Promise<LiveModelDescriptor[]>;
+/** Fetch only the account-visible model ids from `/v1/models-v2`. */
+export declare function fetchLiveModelIds(accessToken: string, signal?: AbortSignal): Promise<string[]>;
+/** Re-exported so callers can normalise cached descriptors onto the route. */
+export declare function asRouteModel(model: Model<Api>): Model<Api>;
+//# sourceMappingURL=catalog.d.ts.map

package/lib/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAS1E,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAE1D,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACpC;AAoBD;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAmB9F;AAyBD,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,mBAAmB,EAAE,CAUtE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,CAEvD;AAyCD,qFAAqF;AACrF,wBAAgB,oBAAoB,CACnC,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,SAAS,KAAK,CAAC,GAAG,CAAC,EAAoB,EAChD,OAAO,CAAC,EAAE,mBAAmB,GAC3B,KAAK,CAAC,GAAG,CAAC,CAIZ;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,SAAS,KAAK,CAAC,GAAG,CAAC,EAAE,EAC9B,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACtC,UAAU,GAAE,SAAS,mBAAmB,EAAO,GAC7C,KAAK,CAAC,GAAG,CAAC,EAAE,CAId;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,MAAM,CAIrF;AA6BD;;;GAGG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAwC/G;AAED,qEAAqE;AACrE,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEpG;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAE1D"}