@skrr-ai/cli 0.1.110 → 0.1.111

package/dist/node_modules/@skrr-ai/auth-core/dist/cjs/daemonWire.d.ts

@@ -0,0 +1,118 @@
+/**
+ * daemonWire.ts — the ONE declaration of every name the daemon and the API
+ * put on the wire between them, with what each name is for (OSK-16617).
+ *
+ * `computerWire.ts` proved the pattern for one family: the names live in the
+ * published package every end can import, and a boundary spec fails on a
+ * second spelling. This module generalises it to the whole daemon wire. Each
+ * entry declares:
+ *
+ *   - `direction` — who sends it. `bidirectional` means both ends send AND
+ *     handle the same name (`rpc:request`, the model-proxy relay);
+ *   - `delivery` — `acked` when the sender learns that it arrived (a Socket.IO
+ *     acknowledgement callback, or an answer event named in `answeredBy`),
+ *     `fire_and_forget` otherwise;
+ *   - `stability` — `stable`: every supported daemon and API speak it, and a
+ *     change needs a new capability; `experimental`: newer than the fleet, or
+ *     declared ahead of a speaker (`dormant` says which), and its shape may
+ *     still move; `deprecated`: kept only so an older peer is heard, never
+ *     newly sent;
+ *   - `capability` — the capability the daemon announces before the API may
+ *     send it (or before the daemon itself sends it). `null` means the event
+ *     predates capability gating and every supported daemon speaks it;
+ *   - `payload` — the zod schema that validates it, NAMED (an export of
+ *     `@skrr-ai/data-provider`, which owns every zod schema; this module stays
+ *     zod-free so the browser, React Native and a bun-compiled daemon all load
+ *     it), or `unvalidated`. "This event has no schema" is a recorded fact
+ *     here, counted by `scripts/daemon-wire/unvalidated-ratchet.mjs`, which
+ *     lets the count fall and never rise.
+ *
+ * Who checks it:
+ *
+ *   - `daemon/src/daemon-wire-registry.test.ts` parses the daemon's source and
+ *     fails on an event the daemon handles or sends that is not declared here,
+ *     or that it handles or sends against its declared direction;
+ *   - `api/server/websocket/__tests__/daemonWireRegistry.spec.js` holds the
+ *     API's SSE ingress table (`EXACT_DAEMON_INGRESS`) and its daemon-socket
+ *     listeners to the same declarations. The API keeps its own table on
+ *     purpose: the routing kind is server-owned, and an API booting on a stale
+ *     package build must not lose routes;
+ *   - `scripts/daemon-wire/generate-schema.mjs` writes
+ *     `docs/protocol/daemon-wire.schema.json` from here (the Codex
+ *     `generate-json-schema` analogue), and a spec fails when it is stale.
+ *
+ * Event names, never routing: a `{provider}` placeholder stands for one
+ * session-provider spelling (`daemon:{provider}:request`). Which spellings are
+ * heard is `firstPartyHarness.ts`'s and the API's `sessionProvider.js`'s
+ * decision, not this table's.
+ */
+export declare const DAEMON_WIRE_DIRECTIONS: readonly ["server_to_daemon", "daemon_to_server", "bidirectional"];
+export type DaemonWireDirection = (typeof DAEMON_WIRE_DIRECTIONS)[number];
+export declare const DAEMON_WIRE_DELIVERIES: readonly ["fire_and_forget", "acked"];
+export type DaemonWireDelivery = (typeof DAEMON_WIRE_DELIVERIES)[number];
+export declare const DAEMON_WIRE_STABILITIES: readonly ["stable", "experimental", "deprecated"];
+export type DaemonWireStability = (typeof DAEMON_WIRE_STABILITIES)[number];
+/**
+ * How a name travels. `event` is its own Socket.IO / SSE event; `rpc` is a
+ * `method` inside `rpc:request`, answered on `rpc:response` — the shape SSE
+ * needs because it has no acknowledgement callback. Several older methods are
+ * still ALSO their own event for a Socket.IO daemon, and are declared once
+ * with both.
+ */
+export declare const DAEMON_WIRE_CARRIERS: readonly ["event", "rpc"];
+export type DaemonWireCarrier = (typeof DAEMON_WIRE_CARRIERS)[number];
+/**
+ * The zod schema that validates a payload, by its export name in
+ * `@skrr-ai/data-provider` (a dotted path reaches into an exported table:
+ * `DAEMON_COMPUTER_EVENT_PAYLOAD_SCHEMAS.attach`). `unvalidated` is a recorded
+ * gap, not a default: both ends read the payload field by field.
+ */
+export type DaemonWirePayload = {
+    readonly kind: 'zod';
+    readonly schema: string;
+} | {
+    readonly kind: 'unvalidated';
+};
+export interface DaemonWireEntry {
+    readonly name: string;
+    readonly direction: DaemonWireDirection;
+    readonly delivery: DaemonWireDelivery;
+    /** The name carrying the answer, when `delivery` is `acked` by an answer rather than a callback. */
+    readonly answeredBy?: string;
+    readonly stability: DaemonWireStability;
+    readonly capability: string | null;
+    /**
+     * A capability the API announces in `daemon:registered.serverCaps` that
+     * changes this name's delivery (`toolResponseAck` turns a fire-and-forget
+     * `daemon:tool:response` into an acked one). Absent: the API's version alone decides.
+     */
+    readonly serverCapability?: string;
+    readonly carriers: readonly DaemonWireCarrier[];
+    readonly payload: DaemonWirePayload;
+    readonly purpose: string;
+    /**
+     * The API also accepts this name from a person's client socket and relays
+     * it to the daemon under the same name (`daemon:list-dirs`). Without this, a
+     * server-side listener of a server → daemon name would read as a direction error.
+     */
+    readonly relayedFromClient?: boolean;
+    /**
+     * Declared, and one end has no speaker for it: why. A dormant entry is exempt
+     * from "somebody speaks this" and is still subject to every other check.
+     */
+    readonly dormant?: string;
+}
+/** Every daemon ⇄ API name, in declaration order (which the generated schema keeps). */
+export declare const DAEMON_WIRE: readonly DaemonWireEntry[];
+export declare const DAEMON_WIRE_NAMES: readonly string[];
+/**
+ * The declaration a concrete name belongs to, or null. An exact declaration
+ * wins over a templated one: `daemon:ping:response` is its own event, not a
+ * `daemon:{provider}:response`. A templated match says only that the SHAPE is
+ * declared; whether a provider spelling is heard is the API's decision.
+ */
+export declare function daemonWireEntry(name: string): DaemonWireEntry | null;
+/** Whether `direction` lets `end` send the name. */
+export declare function daemonWireSends(entry: DaemonWireEntry, end: 'daemon' | 'server'): boolean;
+/** Whether `direction` lets `end` handle the name. */
+export declare function daemonWireHandles(entry: DaemonWireEntry, end: 'daemon' | 'server'): boolean;