@deepwatch/dsh-client-settings 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oxbshw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @deepwatch/dsh-client-settings
+
+Browser half: the Watch Technology & Capability Center — role bindings, engines, sources, memory, verification, diagnostics, about
+
+Part of **DeepWatch** — the agent workspace built on the official
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+and powered by [Watch Skill](https://github.com/oxbshw/watch-skill) for perception, evidence, memory and
+independent verification.
+
+> **Browser half — runs in the workspace UI.**
+> Composed by the bundle and loaded by the DSH client loader.
+
+## Exports
+
+- `@deepwatch/dsh-client-settings`
+- `@deepwatch/dsh-client-settings/client`
+- `@deepwatch/dsh-client-settings/components`
+
+## Peers
+
+Provided by the host rather than installed here:
+
+- `@deepseek-ai/cordis@4.0.2`
+- `@deepseek-ai/dsh-client-ui-primitives@0.1.1-rc.2`
+- `react@^18.2.0`
+
+## Install
+
+> **Not on npm yet.** Nothing exists under the `@deepwatch` scope. This
+> package is published for the first time by the `deepwatch-v0.1.0`
+> release; until then the command below resolves nothing, and
+> [the workspace README](https://github.com/oxbshw/watch-skill/tree/main/workspace#readme) has the path
+> that works from a checkout.
+
+```sh
+npm install @deepwatch/dsh-client-settings
+```
+
+Rarely on its own. [`@deepwatch/dsh-bundle`](https://github.com/oxbshw/watch-skill/tree/main/workspace/packages/watch/bundle#readme)
+composes this package with the rest of DeepWatch and is what a profile
+normally depends on; installing this one directly is for embedding a
+single piece in a composition you control.
+
+## Requirements
+
+- Node `^22.19.0 || >=24.0.0`
+- The peers above, supplied by the host composition
+
+## Stability
+
+`0.1.0` — a stable release.
+
+Stable means tested, documented and supported — not 1.0. This is a
+pre-1.0 line, and semantic versioning gives `0.x` no compatibility
+guarantee across minor versions: **a `0.MINOR` bump may change or remove
+surface, and a patch will not.** Depend on it with a tilde range
+(`~0.1.0`) if you want that difference enforced by your lockfile
+rather than by a changelog. The usual major-version promise starts at 1.0.
+
+## Side effects
+
+Importing a module from this package evaluates no side effects, so a
+bundler may drop what a build does not use. Mounting it in a host is a
+separate matter: what it then reads or writes is governed by the
+workspace boundary and the host's permissions, not by this flag.
+
+## Where this fits
+
+The Technology & Capability Center: role bindings, engines, sources, memory, verification and diagnostics. This is the screen that says what is ready and what is missing.
+
+The twenty packages and how they compose:
+[the package map](https://github.com/oxbshw/watch-skill/blob/main/workspace/docs/packages.md).
+Running DeepWatch, and the gates a change has to pass:
+[the workspace README](https://github.com/oxbshw/watch-skill/tree/main/workspace#readme).
+
+## Attribution
+
+Built on DeepSeek Harness · Powered by Watch Skill
+
+DeepWatch and Watch Skill are independent projects and are not affiliated
+with or endorsed by DeepSeek. MIT licensed; third-party notices are in
+[THIRD_PARTY_NOTICES.md](https://github.com/oxbshw/watch-skill/blob/main/workspace/THIRD_PARTY_NOTICES.md).

package/lib/client/binding-state.d.ts

@@ -0,0 +1,334 @@
+/**
+ * The browser's view of what is configured, assembled from four Host answers.
+ *
+ * A person saved an OpenRouter credential, saw a green dot and the words
+ * "Saved openrouter.", and reasonably concluded the product was ready. It was
+ * not: no model had been chosen and nothing had been assigned to anything. The
+ * dot was answering "is a credential stored?" while the reader was asking "can
+ * I send a message?", and those turn out to be four separate questions.
+ *
+ * So this store never derives readiness itself. It gathers the four facts —
+ * from `llm.providers`, `llm.models`, `credentials.describe` and the stored
+ * bindings in `settings.describe` — and hands them to `roleReadiness`, which
+ * is the only thing in this product allowed to answer "ready". A surface that
+ * wanted to shade a dot green would have to go through the same gate.
+ *
+ * **Nothing here contacts a provider.** Opening a settings page must not spend
+ * somebody's money or rate budget, so reachability stays `unknown` until a
+ * person asks for a check. That is why a freshly saved credential reads
+ * "Credential saved · not yet assigned" rather than a claim about whether it
+ * works: the honest state after a save is *stored*, and the product says so.
+ *
+ * **No value crosses this boundary.** `credentials.describe` is structurally
+ * value-free — it answers `configured`, `source`, `writable` and has no slot
+ * for a value — and the binding this store writes holds a reference the Host
+ * resolves. There is nowhere in this file for a key to be, which is the
+ * property that makes the store safe to render, log and screenshot.
+ *
+ * @module @deepwatch/dsh-client-settings/binding-state
+ */
+import type { BindableRole, ProviderCredentialStatus, ProviderReachability, RoleReadiness, WatchBindings } from '@deepwatch/dsh-contracts';
+/**
+ * Upstream's own settings section for the selection a new session starts with.
+ *
+ * Spelled here rather than imported: `AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE`
+ * lives in a Host package, and a browser bundle that imported it would carry
+ * the Harness's server-side settings machinery to learn one string.
+ * `tests/binding-flow.test.mjs` holds it to the value the pinned baseline
+ * composes.
+ */
+export declare const DEFAULT_MODEL_NAMESPACE = "agent-default-model";
+/**
+ * The RPC envelope, narrowed to what a caller reads.
+ *
+ * Declared structurally rather than imported, which is the same choice
+ * `./index.tsx` makes for the slot service. A browser bundle that imported the
+ * Host's contract package for four method signatures would carry the whole
+ * gateway's types to describe calls it makes by name anyway.
+ */
+type Rpc<T> = {
+    readonly result: {
+        ok: true;
+        value: T;
+    } | {
+        ok: false;
+        error: {
+            code: string;
+            message: string;
+        };
+    };
+};
+/** One namespace as the settings domain describes it. */
+export interface NamespaceView {
+    readonly ns: string;
+    readonly value: unknown;
+    readonly user?: unknown;
+    readonly revision: number;
+}
+/** One provider route, as the provider directory describes it. */
+export interface ProviderView {
+    readonly provider: string;
+    readonly displayName: string;
+    readonly settingsNs: string;
+    readonly settingsPath: readonly string[];
+    /** Whether an adapter currently serves the route. */
+    readonly active: boolean;
+}
+/** One model a provider advertised. */
+export interface CatalogModel {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+}
+/** One provider and the models it advertised. */
+export interface ModelGroup {
+    readonly id: string;
+    readonly name: string;
+    readonly models: readonly CatalogModel[];
+}
+/** What the Host will answer about a credential. Never a value. */
+export interface CredentialView {
+    readonly configured: boolean;
+    readonly source?: string;
+    readonly writable: boolean;
+}
+/** The Host methods this store calls, by the names the gateway gives them. */
+export interface HostApi {
+    readonly settings: {
+        describe(payload: Record<string, never>): Promise<Rpc<{
+            writable: boolean;
+            namespaces: readonly NamespaceView[];
+        }>>;
+        replace(payload: {
+            ns: string;
+            section: object;
+            expectedRevision?: number;
+        }): Promise<Rpc<NamespaceView>>;
+    };
+    readonly llm: {
+        providers(payload: Record<string, never>): Promise<Rpc<{
+            providers: readonly ProviderView[];
+        }>>;
+        models(payload: Record<string, never>): Promise<Rpc<{
+            groups: readonly ModelGroup[];
+            failures: readonly {
+                id: string;
+                message: string;
+            }[];
+        }>>;
+    };
+    readonly credentials: {
+        describe(payload: {
+            refs: string[];
+        }): Promise<Rpc<{
+            credentials: Record<string, CredentialView>;
+        }>>;
+    };
+}
+/**
+ * The identity a provider test result belongs to.
+ *
+ * Provider and model alone are not enough. Rebinding a role to a route served
+ * through a different credential must not inherit the previous verdict — that
+ * is the same "saved means working" claim this whole file exists to remove,
+ * wearing a route it was never asked about. So the credential *reference* is
+ * part of the key.
+ *
+ * What it deliberately cannot see: a value rotated behind a reference that
+ * did not change. No credential value crosses this boundary, so the browser
+ * half has nothing to compare. A result therefore lives only as long as the
+ * session that produced it, and is never persisted or restored — an untested
+ * binding after a reload reads as untested, which is the truthful answer.
+ */
+export declare function providerTestKey(provider: string, model: string, credentialRef: string | null): string;
+/** Provider-neutral result of the explicit, user-triggered one-token test. */
+export interface ProviderTestFacts {
+    readonly provider: string;
+    readonly model: string;
+    readonly ok: boolean;
+    readonly credential: 'configured_unverified' | 'verified' | 'rejected';
+    readonly reachability: Exclude<ProviderReachability, 'unknown'>;
+    readonly message: string;
+}
+export type ProviderTester = (provider: string, model: string, signal: AbortSignal) => Promise<ProviderTestFacts>;
+/** The Host's own verdict on one route, and why, when it is not ready. */
+export interface RouteReadinessFacts {
+    readonly proved: boolean;
+    readonly reason: 'proved' | 'never_tested' | 'configuration_changed' | 'unreadable';
+}
+/**
+ * Ask the Host whether it would serve a route, without spending anything.
+ *
+ * Optional, because a deployment may mount this panel against a Host without
+ * the read plane. Absent, the tab falls back to its own memory of the tests it
+ * ran — which is what this exists to stop being the only answer, and is still
+ * better than refusing to draw the screen.
+ */
+export type RouteReadinessReader = (provider: string, model: string, signal: AbortSignal) => Promise<RouteReadinessFacts>;
+/** One provider, with everything a setup screen needs to talk about it. */
+export interface ProviderRow {
+    readonly provider: string;
+    readonly displayName: string;
+    /** Whether an adapter serves the route right now. */
+    readonly active: boolean;
+    /** The opaque handle the Host resolves a credential through. Never a value. */
+    readonly credentialRef: string | null;
+    readonly credential: ProviderCredentialStatus;
+    /** Models the provider advertised, empty when it advertised none. */
+    readonly models: readonly CatalogModel[];
+    /** Why the catalogue is empty, when the provider said. */
+    readonly catalogError: string | null;
+}
+/** One role, its stored decision, and whether that decision can run. */
+export interface RoleRow {
+    readonly role: BindableRole;
+    readonly provider: string | null;
+    readonly model: string | null;
+    readonly readiness: RoleReadiness;
+}
+/** Everything a binding surface reads. */
+export interface BindingSnapshot {
+    readonly status: 'idle' | 'loading' | 'ready' | 'error';
+    /** A message for the reader when the Host could not be asked. */
+    readonly error: string | null;
+    /** False when the settings document cannot be written here. */
+    readonly writable: boolean;
+    readonly providers: readonly ProviderRow[];
+    readonly roles: readonly RoleRow[];
+    /** The stored document, for a surface that needs the raw decision. */
+    readonly bindings: WatchBindings;
+    /** True while a write is in flight, so a form can disable itself. */
+    readonly saving: boolean;
+    readonly testingRole: BindableRole | null;
+    readonly testMessage: string | null;
+}
+/**
+ * The credential reference a provider's own settings section names.
+ *
+ * Walked out of the described value rather than asked for separately: the
+ * settings domain already returns each namespace's resolved value, and
+ * `apiKeyEnv` is a field in it. The walk is plain property access because the
+ * described value is plain JSON — the secret slots have already been removed
+ * by the seam, which is what makes reading this safe.
+ */
+export declare function credentialRefOf(view: NamespaceView | undefined, path: readonly string[]): string | null;
+/**
+ * What is known about a provider's credential.
+ *
+ * `configured_unverified` rather than `verified` is the whole point. The Host
+ * can say a value resolves; only a provider can say it works, and nothing here
+ * has asked one. Calling a stored credential verified is the claim that sent a
+ * prompt to a provider nobody had configured.
+ */
+export declare function credentialStatusOf(ref: string | null, described: Record<string, CredentialView>, readable: boolean): ProviderCredentialStatus;
+/** Everything known about one role, folded through the single readiness gate. */
+export declare function roleRowOf(role: BindableRole, bindings: WatchBindings, providers: readonly ProviderRow[], tests?: ReadonlyMap<string, ProviderTestFacts>): RoleRow;
+/**
+ * The binding store, shaped for `useSyncExternalStore`.
+ *
+ * Deliberately a plain object with `subscribe`/`getSnapshot` rather than a
+ * framework store: this package's browser half is loaded into somebody else's
+ * React tree, and bringing a state library into a plugin bundle to hold six
+ * fields is how a distribution ends up shipping two of them.
+ */
+export declare class BindingStore {
+    private readonly api;
+    private readonly providerTester?;
+    private readonly readinessReader?;
+    private snapshot;
+    private readonly listeners;
+    /** Guards against a slow load landing after a newer one. */
+    private generation;
+    private revision;
+    private defaultRevision;
+    private readonly providerTests;
+    private providerTestAbort;
+    constructor(api: HostApi, providerTester?: ProviderTester | undefined, readinessReader?: RouteReadinessReader | undefined);
+    /**
+     * Replace what this tab believes about tested routes with what the Host says.
+     *
+     * The browser used to be the only place a provider-test verdict lived, and a
+     * tab cannot see a Host restart, an edit made in another tab, or a key
+     * rotated behind a reference that did not change. It drew a tested badge over
+     * routes the Host had already stopped being willing to serve, and the
+     * composer that badge unlocks opened onto a refusal.
+     *
+     * So the Host is asked, per bound route, and its answer wins in both
+     * directions: a route it still proves is tested even in a tab that has just
+     * been reloaded and ran no test, and a route it no longer proves stops being
+     * tested here the moment this is read.
+     */
+    private reconcileReadiness;
+    /** @returns the current snapshot; stable between changes. */
+    getSnapshot: () => BindingSnapshot;
+    /** @param listener - called after every change. @returns the unsubscriber. */
+    subscribe: (listener: () => void) => (() => void);
+    private publish;
+    /**
+     * Ask the Host everything, and fold it into one snapshot.
+     *
+     * The three reads run together because they are independent and a settings
+     * page that took three round trips in series felt broken on a slow link.
+     * Their failures are not equal, though: providers and settings are the page,
+     * so losing either is an error, while a credential describe that fails
+     * downgrades those providers to `inaccessible` and leaves the rest readable.
+     */
+    load(): Promise<void>;
+    /**
+     * Write the Harness selection only when it disagrees with the binding.
+     *
+     * Guarded on disagreement because this runs on every load: rewriting an
+     * already-correct section would bump its revision, invalidate every other
+     * open editor's `expectedRevision`, and turn a read into a source of write
+     * conflicts.
+     */
+    private reconcileDefaultSelection;
+    /**
+     * Bind one role to one provider and model, and persist the decision.
+     *
+     * `replace` rather than `update`, because unbinding has to be expressible:
+     * a merge cannot remove a key, and a role that could be added but not
+     * removed is a role somebody is stuck with. The whole document is rewritten
+     * from the snapshot the caller is looking at, and `expectedRevision` is what
+     * turns a concurrent edit into a refusal rather than a silent overwrite.
+     */
+    bind(role: BindableRole, provider: string, model: string): Promise<void>;
+    /** Remove one role's binding. The role becomes unbound, never inherited. */
+    unbind(role: BindableRole): Promise<void>;
+    /** Run the exact bound route once; saving a credential never calls this. */
+    testRole(role: BindableRole): Promise<void>;
+    /** Cancel only the explicit provider probe; no Chat turn is involved. */
+    cancelProviderTest(): void;
+    /**
+     * Point the Harness's own default selection at what Chat is bound to.
+     *
+     * The link this subsystem was missing, and the failure it caused is worth
+     * stating plainly: a person added a provider, chose a model and assigned it
+     * to Chat, and still could not send. Every DeepWatch surface agreed the
+     * binding existed. It did — in DeepWatch's document. But the thing that
+     * actually routes a prompt is the Harness's model selection, which this
+     * distribution had *emptied* so that nothing would be chosen for anybody,
+     * and binding Chat never filled it in. Two records of one decision, and the
+     * one the runtime reads was the one nobody was writing.
+     *
+     * So a Chat binding writes both. `agent-default-model` is upstream's own
+     * settings section, read live by `AgentDefaultModelConfig` and re-read by a
+     * blank session on every look — so a session opened before the binding
+     * picks it up without being told.
+     *
+     * Only Chat. The other roles are DeepWatch's own concepts and have no
+     * upstream selection to keep in step; writing one for them would point the
+     * conversation at a model chosen for something else.
+     */
+    private syncDefaultSelection;
+    private write;
+}
+/**
+ * Whether the capability a conversation needs can actually run.
+ *
+ * The one question the composer asks, given its own name so no surface has to
+ * remember which role Chat is or re-derive readiness to find out.
+ */
+export declare function chatReadiness(snapshot: BindingSnapshot): RoleReadiness | null;
+export {};
+//# sourceMappingURL=binding-state.d.ts.map