@cortexkit/claustrum-client 0.11.0 → 0.13.0

package/README.md

@@ -23,6 +23,21 @@ credential caching, refresh, account scheduling, and retry policy.
   as a version older than every real one.
 • Unknown server error classes are bounded to `transient`; callers must retry them
   rather than treating a forward-compatible class as permanent.
+• **Changed in 0.13.0:** a transport `Error` frame whose answer no retry or reconnect
+  can change is reported as `permanent` with action `gone`, and the client no longer
+  reconnects for it: `unknown_method`, `invalid_params`, `invalid_request`,
+  `flow_scopes_unsupported`, `invalid_control_body`, `unknown_module`, and the SDK's
+  pre-send `missing_identity`. These are not verdicts about a credential: do not mark
+  anything gone or needing re-authentication on them; stop retrying and surface the
+  code. `unknown_method` from a vault means the vault predates that operation (for
+  example an enrollment op against a vault older than the enrollment ceremony):
+  update the vault. `watchScoped` is the exception: there `unknown_method` resolves
+  `closed` as `unsupported`, the signal to fall back to polling `listScoped`. Before 0.13.0 these were `transient`/`retry`. Every other
+  transport failure is still `transient`/`retry`.
+• Since 0.13.0, when a terminal transport failure makes the client reconnect and the
+  reconnect or the retried call then fails, the error carries the ORIGINAL call's code
+  and class. Earlier versions threw the reconnect's error instead, usually
+  `transport_error`, hiding the original call's code.
 • `listScoped` rows always carry `providerIds` (a required field since 0.6.0, so code
   that builds rows by hand, such as test fixtures, must set it). An empty array means
   no provider ids are set. Since 0.6.2 a daemon too old to send the field decodes the
@@ -47,6 +62,76 @@ copy. One behaviour reaches callers: while the vault is restarting or refusing r
 opens as retryable, a call now keeps retrying for up to 90 s (paced, with jitter) instead
 of 30 s. Give every vault call on a latency-sensitive path its own timeout.
 
+## Watching for changes
+
+Since 0.12.0, `client.watchScoped(onNotice, { enrollmentToken? })` holds an
+`auth.watch_scoped` request on a dedicated route. It returns `{ stop(), closed }`.
+`stop()` is idempotent and resolves `closed` as `{ kind: 'stopped' }`. Notices have
+exactly `{ kind: 'changed', epoch, seq, view, keys }`; malformed notices reject
+`closed` with `ScopedWatchError` (`code: 'invalid_notice'`). Callback exceptions
+also reject it (`callback_failed`); async callbacks must handle their own rejection.
+Sequence gaps and new epochs are delivered, not silently filtered.
+
+**The caller owns reconnecting and re-subscribing.** Read `listScoped` on connect.
+On every notice, re-read if `view` differs from the last listing actually read,
+`epoch` is new, or `seq` skipped. Notices are sheddable hints, not an event journal.
+`keys` matters only to consumers that announce vault-held public keys: re-read
+those keys when that digest changes, independently of the inventory view.
+
+`@cortexkit/subc-client` 0.22 reports Response (including refusal) and STREAM_END
+frames as the same successful subscription close, without the Response body.
+Every accepted vault watch immediately sends notice seq 1, so the client uses
+whether any notices arrived to interpret that ambiguous close:
+
+| `closed` outcome | Caller action |
+| --- | --- |
+| `ended` (closed after notices) | Re-read and re-subscribe once for this close. A mid-watch revocation may take this extra round trip to discover. |
+| `refused`, with the existing typed credential `error` | Stop. Never reconnect for that refusal. |
+| `not_accepting` | Zero notices, then one successful `listScoped` confirmation. The vault may be draining: wait for reconnect or a caller-chosen delay, not a tight re-subscribe loop. |
+| `transport_lost`, with the original SDK `error` (including `route_closed`) | Reconnect, re-read, then re-watch. |
+| `unsupported` (`unknown_method`) | Fall back to polling `listScoped`. |
+
+A zero-notice close performs exactly one `listScoped` using the same enrollment
+token: its refusal becomes `refused`, its success becomes `not_accepting`. There is
+no automatic retry or reconnection in that confirmation read. Malformed replies
+reject `closed` with `ScopedWatchError('invalid_response')`.
+
+```ts
+let client = await ClaustrumClient.connect(connectionOptions)
+for (;;) {
+  let lastView = (await client.listScoped(token)).view // read on every connect/reopen
+  let epoch: string | undefined
+  let seq = 0
+  let reads = Promise.resolve()
+  let readError: unknown
+  const watch = client.watchScoped((notice) => {
+    const discontinuity = notice.epoch !== epoch || notice.seq !== seq + 1
+    epoch = notice.epoch
+    seq = notice.seq
+    reads = reads.then(async () => {
+      if (discontinuity || notice.view !== lastView) {
+        const listing = await client.listScoped(token)
+        lastView = listing.view // acknowledge the digest actually read, not the hint
+        useInventory(listing)
+      }
+    }).catch((error) => { readError = error; watch.stop() })
+    // Key-announcing callers separately compare notice.keys and re-read held keys.
+  }, { enrollmentToken: token })
+  let outcome
+  try { outcome = await watch.closed; await reads; if (readError) throw readError }
+  catch (error) { watch.stop(); throw error } // malformed notice/read/callback failure
+  if (outcome.kind === 'ended') continue // one new watch per close, never hidden retries
+  if (outcome.kind === 'transport_lost') {
+    client.close()
+    client = await ClaustrumClient.connect(connectionOptions)
+    continue
+  }
+  if (outcome.kind === 'not_accepting') { await callerBackoff(); continue }
+  if (outcome.kind === 'unsupported') await pollScopedInventory(client, token)
+  break // refused or explicitly stopped
+}
+```
+
 ## OpenCode handle-file exports
 
 `defaultHandleFilePath`, `readHandleFile`, `handleFileRevision`, and `parseHandleFile`

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export { writeEnrollmentTokenFile, type EnrollmentTokenFile, } from './enrollmen
 export { MANIFEST_LOCK, manifestLockQuarantinePrefix, withManifestLock, writeHandleFileLocked, type ManifestHandleAccount, type ManifestHandleFile, type ManifestHandleProvider, type ManifestLockError, type ManifestLockErrorCode, } from './manifest-lock.js';
 export { ClaustrumCredentialError, credentialErrorAction, ERROR_CLASS_WIRE_SET, type ClaustrumCredentialErrorAction, type ClaustrumCredentialErrorClass, } from './errors.js';
 export { ClaustrumClient, type ClaustrumClientOptions, type ClaustrumConnector, type ClaustrumReporterSource, type CredentialStatus, type EnrollmentPollOutcome, type ScopedGrantTuple, type ScopedInventory, type ScopedInventoryRow, type ServedCredential, } from './wire.js';
+export { ScopedWatchError, type ScopedWatch, type ScopedWatchNotice, type ScopedWatchOptions, type ScopedWatchOutcome, } from './watch.js';
 export { HANDLE_FILE_CONTRACT, HandleFileValidationError, credentialIdMatchesProvider, defaultHandleFilePath, handleFileRevision, identifierIsValid, parseHandleFile, readHandleFile, type HandleAccount, type HandleFileIo, type HandleProvider, type OpenCodeHandleFileV1, } from './handles.js';

package/dist/index.js

@@ -4,4 +4,5 @@ export { writeEnrollmentTokenFile, } from './enrollment.js';
 export { MANIFEST_LOCK, manifestLockQuarantinePrefix, withManifestLock, writeHandleFileLocked, } from './manifest-lock.js';
 export { ClaustrumCredentialError, credentialErrorAction, ERROR_CLASS_WIRE_SET, } from './errors.js';
 export { ClaustrumClient, } from './wire.js';
+export { ScopedWatchError, } from './watch.js';
 export { HANDLE_FILE_CONTRACT, HandleFileValidationError, credentialIdMatchesProvider, defaultHandleFilePath, handleFileRevision, identifierIsValid, parseHandleFile, readHandleFile, } from './handles.js';

package/dist/watch.d.ts

@@ -0,0 +1,38 @@
+import type { BindIdentity, SubcClient } from '@cortexkit/subc-client';
+import { ClaustrumCredentialError } from './errors.js';
+export type ScopedWatchNotice = {
+    kind: 'changed';
+    epoch: string;
+    seq: number;
+    view: string;
+    keys: string;
+};
+export type ScopedWatchOutcome = {
+    kind: 'refused';
+    error: ClaustrumCredentialError;
+} | {
+    kind: 'ended';
+} | {
+    kind: 'not_accepting';
+} | {
+    kind: 'transport_lost';
+    error: unknown;
+} | {
+    kind: 'unsupported';
+} | {
+    kind: 'stopped';
+};
+export declare class ScopedWatchError extends Error {
+    readonly code: 'invalid_notice' | 'callback_failed' | 'invalid_response';
+    constructor(code: 'invalid_notice' | 'callback_failed' | 'invalid_response');
+}
+export type ScopedWatch = {
+    stop(): void;
+    closed: Promise<ScopedWatchOutcome>;
+};
+export type ScopedWatchOptions = {
+    enrollmentToken?: string;
+};
+/** Decode only the notice schema; sequence gaps and new epochs belong to the consumer. */
+export declare function decodeScopedWatchNotice(bytes: Uint8Array): ScopedWatchNotice;
+export declare function openScopedWatch(client: Pick<SubcClient, 'routeOpen' | 'subscribe' | 'closeRoute'>, identity: BindIdentity, onNotice: (notice: ScopedWatchNotice) => void, options: ScopedWatchOptions, readScoped: () => Promise<unknown>): ScopedWatch;

package/dist/watch.js

@@ -0,0 +1,104 @@
+import { ClaustrumCredentialError } from './errors.js';
+export class ScopedWatchError extends Error {
+    code;
+    constructor(code) {
+        super(`Scoped watch failed: ${code}`);
+        this.code = code;
+        this.name = 'ScopedWatchError';
+    }
+}
+/** Decode only the notice schema; sequence gaps and new epochs belong to the consumer. */
+export function decodeScopedWatchNotice(bytes) {
+    try {
+        const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        if (value === null || typeof value !== 'object' || Array.isArray(value) ||
+            Object.keys(value).sort().join(',') !== 'epoch,keys,kind,seq,view' ||
+            value.kind !== 'changed' || typeof value.epoch !== 'string' || value.epoch.length === 0 ||
+            !Number.isSafeInteger(value.seq) || value.seq <= 0 ||
+            typeof value.view !== 'string' || typeof value.keys !== 'string')
+            throw new ScopedWatchError('invalid_notice');
+        return value;
+    }
+    catch {
+        throw new ScopedWatchError('invalid_notice');
+    }
+}
+export function openScopedWatch(client, identity, onNotice, options, readScoped) {
+    let settled = false;
+    let notices = 0;
+    let subscription;
+    let route;
+    let resolve;
+    let reject;
+    const closed = new Promise((yes, no) => { resolve = yes; reject = no; });
+    const finish = (outcome) => {
+        if (settled)
+            return;
+        settled = true;
+        subscription?.unsubscribe();
+        if (route)
+            void client.closeRoute(route).catch(() => { });
+        if (outcome instanceof ScopedWatchError)
+            reject(outcome);
+        else
+            resolve(outcome);
+    };
+    void (async () => {
+        try {
+            route = await client.routeOpen({ kind: 'management_surface', module_id: 'claustrum' }, identity, { consumerIdentity: null });
+            if (settled) {
+                await client.closeRoute(route);
+                return;
+            }
+            subscription = client.subscribe(route, {
+                method: 'auth.watch_scoped',
+                params: options.enrollmentToken === undefined ? {} : { enrollment_token: options.enrollmentToken },
+            }, (bytes) => {
+                if (settled)
+                    return;
+                let notice;
+                try {
+                    notice = decodeScopedWatchNotice(bytes);
+                }
+                catch {
+                    finish(new ScopedWatchError('invalid_notice'));
+                    return;
+                }
+                notices++;
+                try {
+                    onNotice(notice);
+                }
+                catch {
+                    finish(new ScopedWatchError('callback_failed'));
+                }
+            });
+            await subscription.closed;
+            if (settled)
+                return;
+            // The SDK erases Response bodies. Only an immediate close needs a confirming
+            // list read; after notices, the caller reopens once to discover a revocation.
+            if (notices > 0)
+                finish({ kind: 'ended' });
+            else {
+                try {
+                    await readScoped();
+                    finish({ kind: 'not_accepting' });
+                }
+                catch (error) {
+                    if (error instanceof ClaustrumCredentialError && error.code !== 'invalid_response') {
+                        finish({ kind: 'refused', error });
+                    }
+                    else if (error instanceof ClaustrumCredentialError)
+                        finish(new ScopedWatchError('invalid_response'));
+                    else
+                        finish({ kind: 'transport_lost', error });
+                }
+            }
+        }
+        catch (error) {
+            const code = error !== null && typeof error === 'object' && 'code' in error ? error.code : undefined;
+            finish(code === 'unknown_method' ? { kind: 'unsupported' } : { kind: 'transport_lost', error });
+        }
+    })();
+    return { stop: () => finish({ kind: 'stopped' }), closed };
+}

package/dist/wire.d.ts

@@ -1,4 +1,5 @@
 import { SubcClient, type BindIdentity } from '@cortexkit/subc-client';
+import { type ScopedWatch, type ScopedWatchNotice, type ScopedWatchOptions } from './watch.js';
 export type ClaustrumConnector = (options: {
     connectionFile: string;
     handshakeTimeoutMs?: number;
@@ -107,6 +108,8 @@ export declare class ClaustrumClient {
      * object, so a caller cannot ask a different question by omitting it.
      */
     listScoped(enrollmentToken?: string): Promise<ScopedInventory>;
+    /** One watch on a dedicated route. Reopen/reconnect policy belongs to the caller. */
+    watchScoped(onNotice: (notice: ScopedWatchNotice) => void, options?: ScopedWatchOptions): ScopedWatch;
     /**
      * Fetch by credential id, authorized by a grant rather than a bearer handle.
      *

package/dist/wire.js

@@ -2,8 +2,40 @@ import { SubcCallError, SubcClient, } from '@cortexkit/subc-client';
 import { resolveClaustrumConnectionPath } from './detect.js';
 import { asCredentialError, ClaustrumCredentialError, hasCredentialError, } from './errors.js';
 import { storeIdentity } from './identity.js';
+import { openScopedWatch } from './watch.js';
 const CLAUSTRUM_MODULE_ID = 'claustrum';
 const RECONNECT_BACKOFF_MS = 60_000;
+/**
+ * Transport `Error` frame codes whose answer neither a retry nor a fresh connection can
+ * change. A call failing with one of these is reported as `permanent`/`gone` and is never
+ * reconnected; every other transport failure stays `transient`/`retry`.
+ *
+ * This is the ONLY list of such codes: the error classification and the reconnect
+ * decision both read it, so the two cannot disagree about a code.
+ *
+ * - `unknown_method`: the vault does not implement the operation. From a released vault
+ *   this means the vault predates the operation, and the remedy is to update the vault.
+ * - `invalid_params`, `invalid_request`: the vault could not decode the request body or
+ *   its params. The same bytes are refused the same way on any connection.
+ * - `flow_scopes_unsupported`: the vault refuses routes opened under a flow scope.
+ * - `invalid_control_body`: the vault build cannot decode the daemon's route bind.
+ * - `unknown_module`: the daemon has no module with this id registered or supervised at
+ *   all. A vault that is restarting or warming up is reported as `module_warming` or
+ *   `target_unavailable` instead, which the SDK already retries in place. A fresh
+ *   connection to the same daemon gets the same answer, and the wasted reconnect would
+ *   also start the reconnect backoff, leaving a genuinely wedged connection unable to
+ *   recover for a minute.
+ * - `missing_identity`: the SDK refused before sending because no bind identity was set.
+ */
+const DEFINITIVE_TRANSPORT_CODES = new Set([
+    'unknown_method',
+    'invalid_params',
+    'invalid_request',
+    'flow_scopes_unsupported',
+    'invalid_control_body',
+    'unknown_module',
+    'missing_identity',
+]);
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -163,6 +195,14 @@ export class ClaustrumClient {
         const response = await this.#call('credential.list_scoped', enrollmentToken === undefined ? {} : { enrollment_token: enrollmentToken });
         return decodeScopedInventory(response, this.#logger);
     }
+    /** One watch on a dedicated route. Reopen/reconnect policy belongs to the caller. */
+    watchScoped(onNotice, options = {}) {
+        const client = this.#client;
+        return openScopedWatch(client, this.#identity, onNotice, options, async () => {
+            const response = await client.call('claustrum', 'credential.list_scoped', options.enrollmentToken === undefined ? {} : { enrollment_token: options.enrollmentToken }, { identity: this.#identity, consumerIdentity: null });
+            return decodeScopedInventory(response, this.#logger);
+        });
+    }
     /**
      * Fetch by credential id, authorized by a grant rather than a bearer handle.
      *
@@ -275,46 +315,45 @@ export class ClaustrumClient {
             });
         }
         catch (error) {
-            if (this.#shouldReconnect(error)) {
-                try {
-                    if (this.#client === sentClient)
-                        await this.#reconnect();
-                }
-                catch (reconnectError) {
-                    throw this.#asTransportError(reconnectError);
-                }
-                try {
-                    return await this.#client.call(CLAUSTRUM_MODULE_ID, method, params, {
-                        identity: this.#identity,
-                        consumerIdentity: null,
-                    });
-                }
-                catch (retryError) {
-                    throw this.#asTransportError(retryError);
-                }
+            if (!this.#shouldReconnect(error))
+                throw this.#asTransportError(error);
+            try {
+                if (this.#client === sentClient)
+                    await this.#reconnect();
+                return await this.#client.call(CLAUSTRUM_MODULE_ID, method, params, {
+                    identity: this.#identity,
+                    consumerIdentity: null,
+                });
+            }
+            catch (recoveryError) {
+                // Report the call's own failure, not the recovery's. A failed reconnect would
+                // otherwise replace the original call's code with `transport_error`, so
+                // the one actionable code would appear once and every later diagnostic would
+                // name a transport failure that never happened. Only a failure that carried no
+                // code at all has nothing to preserve.
+                throw this.#transportErrorCode(error) === undefined
+                    ? this.#asTransportError(recoveryError)
+                    : this.#asTransportError(error);
             }
-            throw this.#asTransportError(error);
         }
     }
+    #transportErrorCode(error) {
+        return error instanceof SubcCallError && error.code ? error.code : undefined;
+    }
     #asTransportError(error) {
         if (error instanceof ClaustrumCredentialError)
             return error;
-        const code = error instanceof SubcCallError && error.code ? error.code : 'transport_error';
-        return new ClaustrumCredentialError(code, 'transient', 'retry');
+        const code = this.#transportErrorCode(error);
+        if (code !== undefined && DEFINITIVE_TRANSPORT_CODES.has(code)) {
+            return new ClaustrumCredentialError(code, 'permanent', 'gone');
+        }
+        return new ClaustrumCredentialError(code ?? 'transport_error', 'transient', 'retry');
     }
     #shouldReconnect(error) {
         return (!this.#closed &&
             error instanceof SubcCallError &&
             error.kind === 'terminal' &&
-            error.code !== 'missing_identity' &&
-            error.code !== 'invalid_control_body' &&
-            // The daemon answers unknown_module only when no module with this id is
-            // registered or supervised at all; a vault that is restarting or warming up
-            // is reported as module_warming or target_unavailable, which the SDK already
-            // retries in place. A fresh connection to the same daemon gets the same
-            // answer, and the wasted reconnect would also start the reconnect backoff,
-            // leaving a genuinely wedged connection unable to recover for a minute.
-            error.code !== 'unknown_module');
+            !DEFINITIVE_TRANSPORT_CODES.has(error.code ?? ''));
     }
     async #reconnect() {
         if (this.#closed)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/claustrum-client",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "license": "MIT",
   "repository": {
     "type": "git",