@threadbase-sh/streamer 1.63.0 → 1.64.0

package/dist/e2ee/noise.d.ts

@@ -0,0 +1,261 @@
+import { type KeyObject } from "crypto";
+export declare const NOISE_PROTOCOL_NAME = "Noise_IKpsk1_25519_ChaChaPoly_SHA256";
+/**
+ * Prologue for the PAIRING handshake, mixed into the transcript before any
+ * token (spec §5.3, `MixHash(prologue)`).
+ *
+ * Not in design.md, and added deliberately. The design has two `IK` handshakes:
+ * this one at `/api/pair/exchange` with the pair token as PSK, and a later one
+ * at `/api/e2ee/open` against stored static keys with no PSK. Without a
+ * prologue the two transcripts differ only by the presence of the PSK, so
+ * "could a message from one be replayed into the other" becomes a question you
+ * answer by reasoning about the PSK. A prologue answers it by construction, and
+ * it costs one hash.
+ *
+ * **`"threadbase-e2ee/<version> <purpose>"` is a namespace, not one string.**
+ * Its sibling is `"threadbase-e2ee/1 open"` for `/api/e2ee/open`, named here
+ * rather than left for that phase to invent: half a domain separation is a
+ * property nobody has, and a convention chosen once with both instances visible
+ * is the one that survives a third handshake. The constant itself is not
+ * declared until something uses it.
+ *
+ * Changing this string is a silent, total incompatibility with tb-mobile — it
+ * is hashed into `h` before any token, so the only symptom is "decryption
+ * failed". It is pinned by a committed vector for that reason.
+ */
+export declare const PAIR_PROLOGUE: Buffer<ArrayBuffer>;
+/** `e` (32) + `s` sealed (32 + 16) — everything before message 1's payload. */
+export declare const NOISE_MESSAGE_1_OVERHEAD: number;
+/** `e` (32) — everything before message 2's payload. */
+export declare const NOISE_MESSAGE_2_OVERHEAD: number;
+/**
+ * Cap on a handshake message, checked BEFORE anything is allocated or parsed.
+ *
+ * The Noise spec's own transport limit is 65535 bytes. This is far below it
+ * because our payloads are a handful of JSON fields, and because
+ * `/api/pair/exchange` is a public, unauthenticated endpoint — the same
+ * reasoning D-9 applies to the unseal middleware, reaching this far forward.
+ */
+export declare const NOISE_MAX_MESSAGE_BYTES = 4096;
+export declare class NoiseError extends Error {
+    constructor(message: string);
+}
+export interface KeyPair {
+    publicKey: KeyObject;
+    privateKey: KeyObject;
+    /** Raw 32 bytes, which is what goes on the wire. */
+    publicKeyRaw: Buffer;
+}
+export declare function generateKeyPair(): KeyPair;
+/**
+ * A `KeyPair` around a private key this process already holds.
+ *
+ * The bridge from `loadOrCreateServerIdentity()`, which owns the key file and
+ * returns a bare `KeyObject`, to the handshake, which needs the public half
+ * alongside it. Kept here rather than in server-identity.ts so that module
+ * stays about storing a key rather than about the protocol that uses it.
+ */
+export declare function keyPairFrom(privateKey: KeyObject): KeyPair;
+/**
+ * Raw 32 bytes out of a KeyObject. JWK OKP `x` is base64url of exactly that.
+ *
+ * Accepts either half: `createPublicKey` derives the public key from a private
+ * one but rejects a KeyObject that is already public, so the type is checked
+ * rather than the call being made unconditionally.
+ */
+export declare function rawPublicKey(key: KeyObject): Buffer;
+/**
+ * A KeyObject from raw bytes, or a `NoiseError`.
+ *
+ * This is a trust boundary: the bytes are the QR's `spk` on the client side and
+ * an attacker-supplied handshake message on the server side. A wrong length is
+ * rejected here rather than being padded, truncated, or handed to a DH that
+ * would fail somewhere less legible.
+ */
+export declare function publicKeyFromRaw(raw: Buffer): KeyObject;
+/**
+ * A keypair from a raw 32-byte private scalar.
+ *
+ * Exists for the committed test vectors: a vector is only a contract if the
+ * keys are fixed, and there is no other way to hand Node a chosen X25519
+ * private key. Not used by any production path — every real keypair comes from
+ * `generateKeyPair()` or the identity key file.
+ *
+ * Goes through PKCS#8 DER rather than JWK because a JWK OKP private key must
+ * carry a matching `x`, and the point here is to supply only `d`. The prefix is
+ * the fixed X25519 PrivateKeyInfo header (RFC 8410): SEQUENCE, version 0,
+ * AlgorithmIdentifier 1.3.101.110, then an OCTET STRING wrapping the 32-byte
+ * scalar.
+ */
+export declare function keyPairFromRawPrivate(raw: Buffer): KeyPair;
+/**
+ * The pair token as a 32-byte PSK.
+ *
+ * The token is `pt_<32 hex chars>` — 35 bytes of ASCII, and the spec requires
+ * the PSK to be exactly 32. Hashing with a domain-separating label is the
+ * standard way to fit it, and the label means this value can never collide with
+ * some other use of the same token elsewhere in the system.
+ *
+ * Both implementations must compute this identically or the handshake fails
+ * with no diagnostic beyond "decryption failed", which is why it is pinned by a
+ * test vector rather than left as an obvious detail.
+ */
+export declare function pskFromPairToken(token: string): Buffer;
+/**
+ * Noise's `CipherState` (spec §5.1).
+ *
+ * Exported for two reasons, neither of them scaffolding. Phase 3's record layer
+ * has to build a transport cipher from the buffers `split()` returns, so this is
+ * the type it will construct. And the §5.1 rule that a failed decryption must
+ * not advance `n` is unobservable through the handshake API — every AEAD
+ * operation there runs at `n = 0`, because each is preceded by a `MixKey` that
+ * calls `initializeKey`. Without a way to reach a cipher state directly, that
+ * rule is protected by nothing: a "simplification" that advances before
+ * verifying passes every other test in the suite.
+ */
+export declare class CipherState {
+    private k;
+    private n;
+    initializeKey(key: Buffer | null): void;
+    hasKey(): boolean;
+    encryptWithAd(ad: Buffer, plaintext: Buffer): Buffer;
+    decryptWithAd(ad: Buffer, ciphertext: Buffer): Buffer;
+}
+declare class SymmetricState {
+    private ck;
+    private h;
+    private readonly cipher;
+    constructor(protocolName: string);
+    /**
+     * Noise's HKDF (spec §4.3) is RFC 5869 with `salt = chaining_key`,
+     * `ikm = input_key_material` and an EMPTY info, so Node's `hkdfSync` is
+     * exactly it rather than approximately it. Using the platform's HKDF removes
+     * the HMAC chain that would otherwise be the easiest thing here to get
+     * subtly wrong.
+     */
+    private hkdf;
+    mixKey(ikm: Buffer): void;
+    mixHash(data: Buffer): void;
+    /** Spec §5.2. Used only by the `psk` token. */
+    mixKeyAndHash(ikm: Buffer): void;
+    encryptAndHash(plaintext: Buffer): Buffer;
+    decryptAndHash(ciphertext: Buffer): Buffer;
+    /** The transcript hash. Both sides must arrive at the same value. */
+    handshakeHash(): Buffer;
+    /** Spec §5.2 `Split()`: the two directional transport keys. */
+    split(): {
+        k1: Buffer;
+        k2: Buffer;
+    };
+}
+export interface HandshakeKeys {
+    /** Transcript hash. `ctxId` is derived from it, so both sides agree without a round trip. */
+    handshakeHash: Buffer;
+    /** Initiator → responder traffic key. */
+    clientToServer: Buffer;
+    /** Responder → initiator traffic key. */
+    serverToClient: Buffer;
+}
+/**
+ * Message 1, from the phone.
+ *
+ * Exported from the *server* module although the server never sends one. It is
+ * the only way to drive the responder in a test, and it generates the committed
+ * vectors the tb-mobile implementation is checked against — a second, drifting
+ * initiator written inside a test file is the precise failure two independent
+ * implementations invite.
+ */
+export declare function writeMessage1(args: {
+    staticKeyPair: KeyPair;
+    responderStaticPub: Buffer;
+    psk: Buffer;
+    payload: Buffer;
+    prologue?: Buffer;
+    /** Test seam only. Production always generates a fresh ephemeral. */
+    ephemeral?: KeyPair;
+}): {
+    message: Buffer;
+    state: HandshakeInitiatorState;
+};
+export interface HandshakeInitiatorState {
+    symmetric: SymmetricState;
+    ephemeral: KeyPair;
+    staticKeyPair: KeyPair;
+}
+/** Message 2, read by the phone. Completes the handshake. */
+export declare function readMessage2(state: HandshakeInitiatorState, message: Buffer): {
+    payload: Buffer;
+    keys: HandshakeKeys;
+};
+export interface ResponderResult {
+    /** The initiator's static public key, authenticated by the handshake. */
+    initiatorStaticPub: Buffer;
+    payload: Buffer;
+    message2: Buffer;
+    keys: HandshakeKeys;
+}
+/**
+ * Half-completed responder state, between reading message 1 and writing 2.
+ *
+ * Deliberately only ever a local: it is handed straight back into
+ * `writeMessage2` within the same synchronous stretch of one request, never
+ * stored, never keyed by anything a caller supplies. A responder state that
+ * outlived a request would be a thing to allocate and expire on a public
+ * endpoint, which is what the single-call shape originally avoided.
+ */
+export interface HandshakeResponderState {
+    symmetric: SymmetricState;
+    /** The initiator's static public key, authenticated by message 1. */
+    initiatorStaticPub: Buffer;
+    /** Message 1's decrypted payload. */
+    payload: Buffer;
+    initiatorEphemeral: KeyObject;
+    initiatorStatic: KeyObject;
+    staticKeyPair: KeyPair;
+}
+/**
+ * Read message 1. Authenticates the initiator and recovers its static key.
+ *
+ * Split from `writeMessage2` because the server DOES now have something to do
+ * between them: message 2's payload carries the `deviceId`, and the device row
+ * cannot be written until the pair token has been spent, which cannot happen
+ * until this half has succeeded. The original single-call shape assumed nothing
+ * sat in the middle; the pairing handler is the caller that proved otherwise.
+ *
+ * SYNCHRONOUS on purpose, and it must stay that way: the caller runs this
+ * between validating the pair token and consuming it, and `PairTokenStore` has
+ * no lock. An `await` in that gap would let two concurrent requests with the
+ * same token both pass validation.
+ */
+export declare function readMessage1(args: {
+    staticKeyPair: KeyPair;
+    psk: Buffer;
+    message1: Buffer;
+    prologue?: Buffer;
+}): HandshakeResponderState;
+/** Write message 2 and derive the transport keys. Completes the handshake. */
+export declare function writeMessage2(state: HandshakeResponderState, responsePayload: Buffer, 
+/** Test seam only. Production always generates a fresh ephemeral. */
+ephemeral?: KeyPair): {
+    message2: Buffer;
+    keys: HandshakeKeys;
+};
+/**
+ * Both halves in one call.
+ *
+ * Kept because most callers — every test, and any future responder with nothing
+ * to do in the middle — want the whole handshake, and because the two halves
+ * being separable should not force every one of them to sequence it by hand.
+ */
+export declare function respond(args: {
+    staticKeyPair: KeyPair;
+    psk: Buffer;
+    message1: Buffer;
+    /** Built from the authenticated message-1 payload; sealed into message 2. */
+    buildPayload: (initiatorStaticPub: Buffer, payload: Buffer) => Buffer;
+    prologue?: Buffer;
+    /** Test seam only. */
+    ephemeral?: KeyPair;
+}): ResponderResult;
+export {};
+//# sourceMappingURL=noise.d.ts.map

package/dist/e2ee/noise.d.ts.map

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

package/dist/e2ee/pair-payload.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The device-registration inputs message 1 authenticates.
+ *
+ * `deviceName` is the one optional field in the contract, and is normalised to
+ * `null` when absent so both pairing paths hand `devicesRepo.register` the same
+ * shape. The 100-character bound is the legacy path's, kept identical rather
+ * than re-chosen: authenticating a value is not a reason to stop bounding it.
+ */
+export interface E2eePairRegistration {
+    version: number;
+    deviceName: string | null;
+    readOnly: boolean;
+}
+/**
+ * Parse message 1's decrypted payload.
+ *
+ * Throws rather than defaulting. A client that completed the handshake and then
+ * sent an unreadable payload is a protocol violation, not an older client — an
+ * older client cannot reach this function at all, because it sends no `e2ee`
+ * field and no handshake is performed. Defaulting a missing `readOnly` to
+ * `false` would silently grant the wider capability preset off a payload the
+ * device never actually stated, which is the exact substitution this contract
+ * exists to prevent, arrived at through a parser instead of an intermediary.
+ *
+ * `v` is checked against the same version and with the same ordering as
+ * `parseE2eeRequest`: a version mismatch is not a malformed payload, and saying
+ * so is what lets a future client fall back deliberately.
+ */
+export declare function parseE2eeMsg1Payload(payload: Buffer): E2eePairRegistration;
+/**
+ * Every pairing result a new client persists or presents as verified.
+ *
+ * The outer response still carries compatibility copies of `deviceId`,
+ * `deviceToken`, `capabilities`, `publicUrl` and `machineName` for released
+ * clients that can read nothing else, and a new client ignores all of them —
+ * so this shape is the one that has to be complete. A field missing here is a
+ * field the new client would have to take from the unauthenticated outer copy,
+ * which is the same as not authenticating it at all.
+ *
+ * `deviceId` and `deviceToken` are non-nullable on purpose: an E2EE pairing
+ * that cannot produce them is a failed pairing, not a success carrying nulls.
+ */
+export interface E2eeMsg2Payload {
+    v: number;
+    deviceId: string;
+    deviceToken: string;
+    capabilities: string[];
+    publicUrl: string | null;
+    machineName: string;
+    serverVersion: string;
+    /**
+     * Always `true`. Completing a handshake is what pins the device, and
+     * design.md §6.3 says nothing a client sends ever clears it — so this is a
+     * literal here rather than an argument, and there is no call site that can
+     * pass `false` by accident.
+     */
+    e2eeRequired: true;
+}
+export declare function encodeE2eeMsg2Payload(fields: Omit<E2eeMsg2Payload, "v" | "e2eeRequired">): Buffer;
+//# sourceMappingURL=pair-payload.d.ts.map

package/dist/e2ee/pair-payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pair-payload.d.ts","sourceRoot":"","sources":["../../src/e2ee/pair-payload.ts"],"names":[],"mappings":"AAoBA;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAKD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,oBAAoB,CA+C1E;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,CAAC,EAAE,MAAM,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,YAAY,EAAE,IAAI,CAAC;CACpB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,GAAG,GAAG,cAAc,CAAC,GAAG,MAAM,CAOjG"}

package/dist/e2ee/pair-request.d.ts

@@ -0,0 +1,24 @@
+/** Envelope version this build speaks. Matches `E2EE_PROTOCOL_VERSION`. */
+export declare const E2EE_EXCHANGE_VERSION = 1;
+export declare class E2eeRequestError extends Error {
+    /** Stable code for the client, so a version mismatch is not a parse failure. */
+    readonly code: "E2EE_MALFORMED" | "E2EE_VERSION_UNSUPPORTED";
+    constructor(code: E2eeRequestError["code"], message: string);
+}
+export interface E2eeExchangeRequest {
+    version: number;
+    /** Noise `IK` message 1, decoded. */
+    message1: Buffer;
+}
+/**
+ * `null` for a client that did not ask for encryption; a parsed request for one
+ * that did; a throw for one that asked incoherently.
+ *
+ * The three are deliberately distinct. Collapsing "absent" into "malformed"
+ * breaks every released client, and collapsing "malformed" into "absent" would
+ * silently pair a client that believed it was encrypting — which is the
+ * downgrade the whole negotiation exists to prevent, arrived at through a
+ * parser rather than an attacker.
+ */
+export declare function parseE2eeRequest(raw: unknown): E2eeExchangeRequest | null;
+//# sourceMappingURL=pair-request.d.ts.map

package/dist/e2ee/pair-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pair-request.d.ts","sourceRoot":"","sources":["../../src/e2ee/pair-request.ts"],"names":[],"mappings":"AAgBA,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAYvC,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,0BAA0B,CAAC;IAE7D,YAAY,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAI1D;CACF;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,mBAAmB,GAAG,IAAI,CAsCzE"}

package/dist/external-tails.d.ts

@@ -0,0 +1,91 @@
+import { ConversationCache } from "./conversation-cache";
+import type { CacheIntegrityMonitor } from "./services/cache-integrity/cacheIntegrityMonitor";
+import type { ConversationWatcher } from "./services/conversations/conversationWatcher";
+import type { SessionActivity, SessionResponse } from "./types";
+import type { WSHub } from "./ws-hub";
+export declare const EXTERNAL_TAIL_RECENCY_MS = 120000;
+export declare const EXTERNAL_TAIL_MAX = 32;
+export declare const EXTERNAL_TAIL_IDLE_MS = 300000;
+export declare const EXTERNAL_ACTIVE_WRITING_MS = 30000;
+export type ExternalTailEntry = {
+    conversationId: string;
+    lastActivityAt: number;
+};
+/**
+ * Everything ExternalTailManager reads from the server. Nullable collaborators
+ * are thunks rather than values because they are opened during listen() and
+ * rebound by the integrity monitor's reset-and-rescan — the same reason
+ * ApiDeps passes `cache: () => ConversationCache | null`.
+ *
+ * `tails` and `sessionFileMap` are the server's own Maps, held by reference:
+ * the server still owns them as instance fields (both are reached directly
+ * elsewhere in server.ts, and the tests read `externalTails` off the server),
+ * this class only drives them.
+ */
+export type ExternalTailManagerDeps = {
+    tails: Map<string, ExternalTailEntry>;
+    sessionFileMap: Map<string, string>;
+    fileWatcher: ConversationWatcher;
+    wsHub: WSHub;
+    cache: () => ConversationCache | null;
+    cacheMonitor: () => CacheIntegrityMonitor | null;
+    broadcastConversationLines: (sessionId: string, lines: string[], seqs?: (number | null)[] | null) => void;
+};
+/**
+ * Owns the live tails on JSONLs no PTY session is writing: when one attaches,
+ * when it is evicted or swept, the inferred activity it feeds into session
+ * responses, and the transcript lines it pushes.
+ *
+ * Extracted from StreamerServer so external-tail work stops editing the server
+ * file, continuing the split in docs/plans/2026-07-12-server-ts-split.md.
+ */
+export declare class ExternalTailManager {
+    private deps;
+    private log;
+    constructor(deps: ExternalTailManagerDeps);
+    private get externalTails();
+    /** True when a managed (PTY) session owns the tail for this canonical path. */
+    isManagedTailPath(key: string): boolean;
+    /**
+     * Attach a live tail to a JSONL nobody is tailing yet, when it was touched
+     * recently enough to look actively written by an external agent. Capped at
+     * EXTERNAL_TAIL_MAX with LRU eviction.
+     */
+    maybeAttachExternalTail(filePath: string): void;
+    /** Stop tailing an external file and drop its bookkeeping. */
+    detachExternalTail(key: string): void;
+    /**
+     * Shared unlink path for the per-file watcher and the directory watcher.
+     * Detaches any external tail and drops the cache row (unless an integrity
+     * alert is freezing deletes).
+     */
+    handleJsonlDeleted(filePath: string): void;
+    /** Make room for one more tail by evicting the least recently active ones. */
+    evictExternalTailsIfNeeded(): void;
+    /**
+     * INFERRED activity for an externally-owned conversation, derived purely from
+     * how recently its JSONL grew (the external tail's bookkeeping). Returns
+     * undefined when we hold no tail for it, so a session we know nothing about
+     * reports no activity rather than a fabricated "quiet".
+     *
+     * This can never distinguish a generating agent from one blocked on a
+     * permission gate — gates render on the PTY screen and never reach the JSONL —
+     * which is why it is a separate field and not folded into `status`.
+     */
+    externalActivityFor(conversationId: string, now?: number): SessionActivity | undefined;
+    /** Attach inferred `activity` to externally-owned sessions in a response set. */
+    withExternalActivity(sessions: readonly SessionResponse[]): readonly SessionResponse[];
+    /** Detach external tails idle past EXTERNAL_TAIL_IDLE_MS. */
+    sweepIdleExternalTails(now?: number): void;
+    /**
+     * Push appended lines from an externally-owned conversation. Reuses the exact
+     * conversation_events / conversation_event shapes mobile already consumes,
+     * keyed by the conversation UUID — an external session has no PTY, so it must
+     * never produce terminal_output / terminal_replay / session_ready, and never a
+     * session_update whose session.id is a conversation UUID (that would mint a
+     * phantom session row in the mobile cache). Question cards are likewise never
+     * derived here: with no PTY there is nothing that could deliver an answer.
+     */
+    broadcastExternalTailLines(filePath: string, lines: string[], seqs?: (number | null)[] | null): void;
+}
+//# sourceMappingURL=external-tails.d.ts.map

package/dist/external-tails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-tails.d.ts","sourceRoot":"","sources":["../src/external-tails.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kDAAkD,CAAC;AAC9F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AAExF,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAEhE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAWtC,eAAO,MAAM,wBAAwB,SAAwB,CAAC;AAK9D,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAKpC,eAAO,MAAM,qBAAqB,SAAU,CAAC;AAI7C,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD,MAAM,MAAM,iBAAiB,GAAG;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACtC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,EAAE,mBAAmB,CAAC;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,MAAM,iBAAiB,GAAG,IAAI,CAAC;IACtC,YAAY,EAAE,MAAM,qBAAqB,GAAG,IAAI,CAAC;IACjD,0BAA0B,EAAE,CAC1B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI,KAC5B,IAAI,CAAC;CACX,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,mBAAmB;IAGlB,OAAO,CAAC,IAAI;IAFxB,OAAO,CAAC,GAAG,CAAuB;IAElC,YAAoB,IAAI,EAAE,uBAAuB,EAAI;IAErD,OAAO,KAAK,aAAa,GAExB;IAED,+EAA+E;IAC/E,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAKtC;IAED;;;;OAIG;IACH,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAgC9C;IAED,8DAA8D;IAC9D,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAOpC;IAED;;;;OAIG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAkBzC;IAED,8EAA8E;IAC9E,0BAA0B,IAAI,IAAI,CAmBjC;IAED;;;;;;;;;OASG;IACH,mBAAmB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,eAAe,GAAG,SAAS,CAWzF;IAED,iFAAiF;IACjF,oBAAoB,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,eAAe,EAAE,CAQrF;IAED,6DAA6D;IAC7D,sBAAsB,CAAC,GAAG,SAAa,GAAG,IAAI,CAS7C;IAED;;;;;;;;OAQG;IACH,0BAA0B,CACxB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI,GAC9B,IAAI,CAyBN;CACF"}

package/dist/feature-flags.d.ts

@@ -0,0 +1,212 @@
+/** Spec for one flag in the keyed registry. The id is the object key, not a field. */
+export interface FeatureFlagSpec {
+    /** Shipped to clients alongside the values so a UI can render it. */
+    description: string;
+    default: boolean;
+    /** Full env var name. */
+    env: string;
+}
+/** Wire shape: the keyed spec plus its id, for GET /api/config/feature-flags. */
+export interface FeatureFlagDefinition extends FeatureFlagSpec {
+    /** Stable config/wire key. Used in server.yaml, on the CLI, and over HTTP. */
+    id: FeatureFlagId;
+}
+/**
+ * Values arriving from a config source. PARTIAL on purpose: server.yaml, the
+ * CLI and ServerConfig each speak about the flags they mention and stay silent
+ * on the rest, which is what lets the precedence chain fall through.
+ */
+export type FeatureFlagValues = Partial<Record<FeatureFlagId, boolean>>;
+/** Every flag, resolved. Total — see resolveFeatureFlags(). */
+export type ResolvedFeatureFlags = Record<FeatureFlagId, boolean>;
+/**
+ * Which rung of the precedence chain decided a flag.
+ *
+ * Kept because the resolved boolean alone cannot answer "why is this on?", and
+ * that is the first question asked of a flag that is on when nobody expected it.
+ * `override` is the legacy ServerConfig field (see resolveFeatureFlags).
+ */
+export type FeatureFlagSource = "override" | "env" | "cli" | "yaml" | "default";
+export interface FeatureFlagResolution {
+    values: ResolvedFeatureFlags;
+    sources: Record<FeatureFlagId, FeatureFlagSource>;
+}
+/**
+ * The registry, keyed by flag name.
+ *
+ * Prefer `FEATURE_FLAGS.ptyHost` over a string lookup. A typo is a compile
+ * error; `findFeatureFlag("…")` is only for untrusted yaml/CLI tokens.
+ *
+ * `as const` + `keyof` is what makes `flags.ptyHsot` a compile error instead of
+ * `undefined`. A TS enum would add a runtime object without a stronger type.
+ */
+export declare const FEATURE_FLAGS: {
+    readonly codexSystemPrompt: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_CODEX_SYSTEM_PROMPT";
+    };
+    readonly sessionRehydration: {
+        readonly description: string;
+        readonly default: true;
+        readonly env: "THREADBASE_FEATURE_SESSION_REHYDRATION";
+    };
+    readonly liveActivityPush: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_LIVE_ACTIVITY_PUSH";
+    };
+    readonly e2ee: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_E2EE";
+    };
+    readonly ptyHost: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_PTY_HOST";
+    };
+};
+/**
+ * The registry's ids as a union, derived rather than declared.
+ *
+ * This is what makes `flags.ptyHsot` a compile error instead of `undefined`.
+ * Under the old `Record<string, boolean>` an index signature accepted any key,
+ * so a typo in a consumer read as falsy and silently disabled the feature it
+ * was meant to gate — the exact failure the "total map" contract exists to
+ * prevent, reachable through the one door that contract left open.
+ */
+export type FeatureFlagId = keyof typeof FEATURE_FLAGS;
+/**
+ * The yaml / `--feature` ids, in registry order.
+ *
+ * These are the `FEATURE_FLAGS` object keys — not the `THREADBASE_FEATURE_*`
+ * env names. `feature_flags: {"ptyHost":true}` is valid;
+ * `{"THREADBASE_FEATURE_PTY_HOST":true}` is dropped as unknown.
+ */
+export declare const FEATURE_FLAG_IDS: FeatureFlagId[];
+/**
+ * Ordered list for iteration and the HTTP registry.
+ *
+ * The wire shape stays an array of `{ id, description, default, env }` so a
+ * keyed in-process registry is not a breaking GET /api/config/feature-flags
+ * change. Each `id` is the matching `FEATURE_FLAGS` key.
+ */
+export declare const FEATURE_FLAG_LIST: readonly FeatureFlagDefinition[];
+export declare function isFeatureFlagId(id: string): id is FeatureFlagId;
+/** Typed lookup. The flag is always present; unknown names do not type-check. */
+export declare function getFeatureFlag<K extends FeatureFlagId>(id: K): {
+    id: K;
+} & {
+    readonly codexSystemPrompt: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_CODEX_SYSTEM_PROMPT";
+    };
+    readonly sessionRehydration: {
+        readonly description: string;
+        readonly default: true;
+        readonly env: "THREADBASE_FEATURE_SESSION_REHYDRATION";
+    };
+    readonly liveActivityPush: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_LIVE_ACTIVITY_PUSH";
+    };
+    readonly e2ee: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_E2EE";
+    };
+    readonly ptyHost: {
+        readonly description: string;
+        readonly default: false;
+        readonly env: "THREADBASE_FEATURE_PTY_HOST";
+    };
+}[K];
+/**
+ * Look a flag up by an unvalidated string (yaml keys, `--feature` tokens).
+ *
+ * In-process code should use `FEATURE_FLAGS.ptyHost` or `getFeatureFlag("ptyHost")`.
+ */
+export declare function findFeatureFlag(id: string): FeatureFlagDefinition | undefined;
+/**
+ * Parse a boolean env var, tri-state.
+ *
+ * `undefined` means "this variable did not speak" — distinct from `false` — so
+ * an unset var lets the next precedence rung (CLI, then yaml) decide instead of
+ * silently forcing the flag off.
+ *
+ * That tri-state return is why this does not reuse one of the existing env
+ * parsers (`parseIncludeAgentsEnv` in server.ts, `isTruthy` in
+ * agent/agent-config.ts, the inline sets in api/middleware/cors.middleware.ts):
+ * all three collapse "absent" into a boolean, which is exactly the distinction
+ * the precedence chain needs. Consolidating those three is a separate change.
+ */
+export declare function parseBooleanEnv(raw: string | undefined): boolean | undefined;
+/**
+ * Drop everything that isn't a known id carrying a boolean.
+ *
+ * A TRUST BOUNDARY, mirroring validateFlagValues() in claude-flags.ts: values
+ * arrive from a user-editable server.yaml. Unknown ids and ill-typed values are
+ * dropped with a warning rather than throwing, so one stale or fat-fingered key
+ * can never stop the server from booting.
+ *
+ * Note the deliberate non-coercion: `"true"` (a string) is dropped, not read as
+ * true. A value that isn't already a boolean means the writer misunderstood the
+ * format, and guessing at intent is how a flag silently ends up on.
+ */
+export declare function validateFeatureFlagValues(raw: unknown): FeatureFlagValues;
+/**
+ * Parse repeatable `--feature <id=bool>` CLI tokens.
+ *
+ * Errors are returned rather than thrown so the caller owns the exit: a typo on
+ * the command line should print one legible message and stop, not surface a
+ * stack trace. Unlike the yaml path this is strict — a CLI typo is a mistake the
+ * operator is standing right there to fix, whereas a stale yaml key must not
+ * block an unattended boot.
+ */
+export declare function parseFeatureFlagArgs(entries: string[]): {
+    values: FeatureFlagValues;
+    errors: string[];
+};
+/**
+ * Resolve every flag once, at boot. Precedence, highest first:
+ *
+ *   override  →  env  →  CLI  →  server.yaml  →  registry default
+ *
+ * Env beats the CLI so an operator can flip a flag on a supervised instance
+ * (launchd/systemd/Task Scheduler) whose argv is fixed — the same reason
+ * THREADBASE_ALLOW_BROWSER_CORS overrides browser_cors: in server.yaml.
+ *
+ * `override` is the legacy explicit ServerConfig field (codexSystemPromptEnabled),
+ * kept so embedders and tests that set it directly keep working. It is a real
+ * rung here rather than a mutation applied to the finished map afterwards: the
+ * old shape meant the resolver was not actually the single source of truth, and
+ * an override was invisible to anything reporting where a value came from.
+ *
+ * The returned `values` map is TOTAL: every registry id is present, defaults
+ * filled in. Callers therefore index it without a `?? default`, and a flag added
+ * later cannot reach a boolean branch as `undefined` just because an older
+ * server.yaml predates it. `sources` is total for the same reason.
+ */
+export declare function resolveFeatureFlags(opts?: {
+    override?: FeatureFlagValues;
+    cli?: FeatureFlagValues;
+    yaml?: FeatureFlagValues;
+    env?: NodeJS.ProcessEnv;
+}): FeatureFlagResolution;
+/** Registry ids whose resolved value differs from the registry default. */
+export declare function nonDefaultFeatureFlags(values: ResolvedFeatureFlags): FeatureFlagId[];
+/**
+ * One line describing the whole resolution: `id=value(source)`, every flag.
+ *
+ * Replaces a boot log that printed only the ids differing from their defaults
+ * under the heading "Feature flags active". That heading was wrong for any
+ * flag whose default is ON — disabling `sessionRehydration` made it appear in
+ * a list of active flags, stating the opposite of what had happened. Printing
+ * the value removes the ambiguity, and printing every flag means the log
+ * answers "what was this process running with" instead of only ever hinting.
+ */
+export declare function describeFeatureFlags(resolution: FeatureFlagResolution): string;
+//# sourceMappingURL=feature-flags.d.ts.map