@threadbase-sh/streamer 1.63.0 → 1.65.0

package/dist/claude-flags.d.ts

@@ -0,0 +1,76 @@
+/** Claude Code `--permission-mode` values, as accepted by CLI v2.1.x. */
+export declare const PERMISSION_MODES: readonly ["acceptEdits", "auto", "bypassPermissions", "manual", "dontAsk", "plan"];
+export type PermissionMode = (typeof PERMISSION_MODES)[number];
+export declare function isPermissionMode(value: unknown): value is PermissionMode;
+export declare const DANGEROUS_PERMISSION_MODES: readonly PermissionMode[];
+export declare function isDangerousPermissionMode(mode: PermissionMode): boolean;
+/**
+ * The mode sessions will actually spawn with, for callers that need to know
+ * before any spawn happens (the boot warning). Mirrors the precedence
+ * `StreamerServer.spawnFlagOverrides()` applies — `claudeFlags.permissionMode`
+ * wins over the `--default-permission-mode` fallback — so the two must not
+ * drift: a warning that reads the fallback would stay silent while a
+ * `claude_flags:` bypass is what actually reaches argv.
+ */
+export declare function effectivePermissionMode(flags: ClaudeFlagValues | undefined, fallback: string | undefined): PermissionMode | undefined;
+/** Claude Code `--effort` levels, as accepted by CLI v2.1.x. */
+export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+export type EffortLevel = (typeof EFFORT_LEVELS)[number];
+export declare function isEffortLevel(value: unknown): value is EffortLevel;
+export type FlagValueType = "boolean" | "string" | "enum" | "list";
+/** How risky enabling a flag is. Drives the client's confirmation UX. */
+export type FlagRisk = "low" | "elevated" | "dangerous";
+export interface FlagDefinition {
+    /** Stable config/wire key. Never the CLI spelling. */
+    id: string;
+    /** The literal CLI token, e.g. "--add-dir". */
+    flag: string;
+    valueType: FlagValueType;
+    /** Allowed values when valueType === "enum". */
+    enumValues?: readonly string[];
+    /**
+     * Baseline risk. `permissionMode` is the exception: it is only dangerous for
+     * the values in DANGEROUS_PERMISSION_MODES, so clients must call
+     * `flagValueRisk()` rather than reading this field directly.
+     */
+    risk: FlagRisk;
+}
+export type ClaudeFlagValue = string | string[] | boolean;
+export type ClaudeFlagValues = Record<string, ClaudeFlagValue>;
+export declare const CLAUDE_FLAGS: readonly FlagDefinition[];
+export declare function findFlag(id: string): FlagDefinition | undefined;
+/**
+ * Effective risk of a specific value. Only `permissionMode` is value-dependent
+ * (`acceptEdits` is routine; `bypassPermissions` is not).
+ */
+export declare function flagValueRisk(id: string, value: ClaudeFlagValue): FlagRisk;
+/**
+ * Drop everything that isn't a known id carrying a well-typed value.
+ *
+ * This is a TRUST BOUNDARY, not a convenience: values arrive from a
+ * user-editable server.yaml and from HTTP, and they become process argv. Never
+ * skip it. Unknown/invalid entries are dropped rather than throwing so one bad
+ * key can't prevent the server from booting.
+ */
+export declare function validateFlagValues(raw: unknown): ClaudeFlagValues;
+/**
+ * Split a free-text extra-args string into argv tokens, honouring single and
+ * double quotes so a path with spaces survives. Deliberately not a full shell
+ * parser — no variable expansion, no globbing, no escapes beyond the quotes.
+ */
+export declare function tokenizeExtraArgs(input: string | undefined): string[];
+/**
+ * Turn validated flag values + extra args into argv tokens.
+ *
+ * The SPAWN_POSITIONAL_FLAG_IDS are intentionally NOT emitted here: both PTY
+ * spawn paths already pass them as explicit positionals, and emitting them
+ * twice would put a duplicate flag on the command line. They flow through
+ * `options.permissionMode` / `options.model` / `options.effort` instead, which
+ * StreamerServer.spawnFlagOverrides() sources from these same flag values.
+ *
+ * Extra args land LAST so the escape hatch can override anything the allowlist
+ * set.
+ */
+export declare function buildFlagArgs(values: ClaudeFlagValues | undefined, extraArgs?: string): string[];
+export declare function buildSettingsJson(permissionMode: PermissionMode): string;
+//# sourceMappingURL=claude-flags.d.ts.map

package/dist/claude-flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-flags.d.ts","sourceRoot":"","sources":["../src/claude-flags.ts"],"names":[],"mappings":"AAcA,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,YAC3B,aAAa,EACb,MAAM,EACN,mBAAmB,EACnB,QAAQ,EACR,SAAS,EACT,MAAM,CACE,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAOD,eAAO,MAAM,0BAA0B,EAAE,SAAS,cAAc,EAG/D,CAAC;AAEF,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAEvE;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,gBAAgB,GAAG,SAAS,EACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,cAAc,GAAG,SAAS,CAG5B;AAED,gEAAgE;AAChE,eAAO,MAAM,aAAa,YAAI,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAU,CAAC;AAEhF,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEnE,yEAAyE;AACzE,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,UAAU,GAAG,WAAW,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,aAAa,CAAC;IACzB,gDAAgD;IAChD,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;OAIG;IACH,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;AAC1D,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAyB/D,eAAO,MAAM,YAAY,EAAE,SAAS,cAAc,EAajD,CAAC;AAQF,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAE/D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,QAAQ,CAO1E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CA2BjE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CA+BrE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAsBhG;AAUD,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,cAAc,GAAG,MAAM,CAMxE"}

package/dist/cli.cjs

@@ -28235,7 +28235,7 @@ var require_permessage_deflate = __commonJS({
       acceptAsServer(offers) {
         const opts = this._options;
         const accepted = offers.find((params) => {
-          if (opts.serverNoContextTakeover === false && params.server_no_context_takeover || params.server_max_window_bits && (opts.serverMaxWindowBits === false || typeof opts.serverMaxWindowBits === "number" && opts.serverMaxWindowBits > params.server_max_window_bits) || typeof opts.clientMaxWindowBits === "number" && !params.client_max_window_bits) {
+          if (opts.serverNoContextTakeover === false && params.server_no_context_takeover || params.server_max_window_bits && (opts.serverMaxWindowBits === false || typeof opts.serverMaxWindowBits === "number" && opts.serverMaxWindowBits > params.server_max_window_bits) || typeof opts.clientMaxWindowBits === "number" && (typeof params.client_max_window_bits === "number" ? opts.clientMaxWindowBits > params.client_max_window_bits : !params.client_max_window_bits)) {
             return false;
           }
           return true;
@@ -128383,7 +128383,7 @@ function formatIdentityBanner(fingerprint2, keyPath) {
     "",
     `  ${fingerprint2}`,
     "",
-    "Compare this with the fingerprint your phone shows when you add this server."
+    "Compare this with the identity code your phone shows when you add this server."
   ].join("\n");
 }
 var init_identity = __esm({
@@ -148735,6 +148735,19 @@ var SessionHandlers = class {
       sessions: this.sessionStore.list(this.deps.ptyAttachedIds())
     });
   }
+  /**
+   * Same empty-unused check stop uses (promptCount === 0 and no cache row,
+   * including boundConversationId / resumedFromConversationId). Safe after
+   * putOnHold: the runner may already have dropped the live session.
+   */
+  forgetIfEmptyUnused(sessionId) {
+    const live = this.ptyManager.getSession(sessionId);
+    const stored = this.sessionStore.getManaged(sessionId);
+    const session = live ?? stored;
+    if (!session) return;
+    if (!this.shouldForgetEmptySession(session)) return;
+    this.forgetEmptyStoppedSession(sessionId);
+  }
   async handleAdopt(sessionId, res) {
     const discovered = await discoverClaudeProcesses();
     this.sessionStore.setDiscovered(discovered);
@@ -151118,6 +151131,7 @@ function createLiveSessionOptions(deps) {
       void deps.liveActivityNotifier()?.onStatusChange(session, previousStatus);
       void deps.waitingInputNotifier()?.onStatusChange(session, previousStatus);
       deps.sessionStatusBus.emit(`status:${session.id}`, session.status, session);
+      deps.maybeFireHoldWhenIdle?.(session);
     }
   };
 }
@@ -151266,7 +151280,20 @@ function createApiDeps(deps) {
             deny(msg.type, "session:control");
             return;
           }
-          deps.startGraceTimer(msg.sessionId, deps.ptyGracePeriodMs);
+          const when = msg.when;
+          if (when === void 0 || when === "grace") {
+            deps.startGraceTimer(msg.sessionId, deps.ptyGracePeriodMs);
+            return;
+          }
+          if (when === "waiting_input") {
+            deps.armHoldWhenIdle(msg.sessionId);
+            return;
+          }
+          deps.log().warn(`[pty.hold_when_unknown] hold_session when=${String(when)}`, {
+            event: "pty.hold_when_unknown",
+            sessionId: msg.sessionId,
+            when
+          });
         }
       } catch {
       }
@@ -153866,6 +153893,10 @@ var StreamerServer = class {
   // Consecutive grace-timer defers for a still-`running` session (see
   // GRACE_MAX_DEFERS). Reset when a subscriber reconnects or the PTY settles.
   ptyGraceDeferCounts = /* @__PURE__ */ new Map();
+  // Session ids that should be putOnHold at the next waiting_input/idle.
+  // Same lifetime as ptyGraceTimers: in-memory, dropped on close/restart.
+  // Last writer wins against the grace timer — never both armed.
+  holdWhenIdle = /* @__PURE__ */ new Set();
   // Map of sessionId → set of subscribed WS clients
   sessionSubscribers = /* @__PURE__ */ new Map();
   // sessionId → wall-clock ms of the last PTY chunk. Written from onOutput for
@@ -154093,7 +154124,8 @@ var StreamerServer = class {
         waitingInputNotifier: () => this.waitingInputNotifier,
         ptyAttachedIds: () => this.ptyAttachedIds(),
         cancelPendingQuestion: (sessionId) => this.cancelPendingQuestion(sessionId),
-        rememberSelfPtyEnded: (conversationId) => this.rememberSelfPtyEnded(conversationId)
+        rememberSelfPtyEnded: (conversationId) => this.rememberSelfPtyEnded(conversationId),
+        maybeFireHoldWhenIdle: (session) => this.maybeFireHoldWhenIdle(session)
       })
     );
     this.sessionWatchers = new SessionWatchers({
@@ -154256,6 +154288,7 @@ var StreamerServer = class {
       currentWarmupState: () => this.currentWarmupState(),
       addSessionSubscriber: (sessionId, ws2) => this.addSessionSubscriber(sessionId, ws2),
       startGraceTimer: (sessionId, delayMs) => this.startGraceTimer(sessionId, delayMs),
+      armHoldWhenIdle: (sessionId) => this.armHoldWhenIdle(sessionId),
       handleSessionsCount: (res) => this.handleSessionsCount(res),
       applyLiveSessionSetting: (id, req, res, setting) => this.applyLiveSessionSetting(id, req, res, setting),
       handlePairStart: (res) => this.handlePairStart(res),
@@ -154375,6 +154408,13 @@ var StreamerServer = class {
       this.ptyGraceTimers.delete(sessionId);
     }
     this.ptyGraceDeferCounts.delete(sessionId);
+    if (this.holdWhenIdle.delete(sessionId)) {
+      this.log.info(
+        `[hold-when-idle] cancelled ${sessionId} (subscribe)`,
+        { sessionId, event: "pty.hold_when_idle_cancel", reason: "subscribe" },
+        "pino"
+      );
+    }
   }
   /**
    * Bring up Live Activity push, if credentials are present (Feature 12).
@@ -154482,6 +154522,7 @@ var StreamerServer = class {
     return reaped;
   }
   startGraceTimer(sessionId, delayMs) {
+    this.holdWhenIdle.delete(sessionId);
     const existing = this.ptyGraceTimers.get(sessionId);
     if (existing) clearTimeout(existing);
     const timer = setTimeout(() => {
@@ -154523,6 +154564,63 @@ var StreamerServer = class {
     }, delayMs);
     this.ptyGraceTimers.set(sessionId, timer);
   }
+  clearGrace(sessionId) {
+    const existing = this.ptyGraceTimers.get(sessionId);
+    if (existing) {
+      clearTimeout(existing);
+      this.ptyGraceTimers.delete(sessionId);
+    }
+    this.ptyGraceDeferCounts.delete(sessionId);
+  }
+  /**
+   * Arm the in-app "Kill on idle" latch: hold now if already settled, otherwise
+   * on the next running → waiting_input (or idle). No grace delay, no defer cap.
+   * A subscribed leaving socket must not block an immediate hold.
+   */
+  armHoldWhenIdle(sessionId) {
+    if (!this.ptyManager.hasSession(sessionId)) return;
+    this.clearGrace(sessionId);
+    const status = this.ptyManager.getSession(sessionId)?.status ?? this.sessionStore.getManaged(sessionId)?.status;
+    if (status === "waiting_input" || status === "idle") {
+      this.holdWhenIdle.delete(sessionId);
+      this.ptyManager.putOnHold(sessionId);
+      this.forgetIfEmptyUnused(sessionId);
+      return;
+    }
+    this.holdWhenIdle.add(sessionId);
+    this.log.info(
+      `[hold-when-idle] armed ${sessionId}`,
+      { sessionId, event: "pty.hold_when_idle_armed" },
+      "pino"
+    );
+  }
+  /**
+   * Fire the Kill-on-idle latch from the shared onStatusChange funnel.
+   * Delete first so the ensuing idle transition cannot re-enter.
+   */
+  maybeFireHoldWhenIdle(session) {
+    if (session.status !== "waiting_input" && session.status !== "idle") return;
+    if (!this.holdWhenIdle.has(session.id)) return;
+    this.holdWhenIdle.delete(session.id);
+    if (this.hasSessionSubscriber(session.id)) {
+      this.log.info(
+        `[hold-when-idle] cancelled ${session.id} (subscriber)`,
+        { sessionId: session.id, event: "pty.hold_when_idle_cancel", reason: "subscriber" },
+        "pino"
+      );
+      return;
+    }
+    this.log.info(
+      `[hold-when-idle] holding ${session.id}`,
+      { sessionId: session.id, event: "pty.hold_when_idle_fire" },
+      "pino"
+    );
+    this.ptyManager.putOnHold(session.id);
+    this.forgetIfEmptyUnused(session.id);
+  }
+  forgetIfEmptyUnused(sessionId) {
+    this.sessionHandlers.forgetIfEmptyUnused(sessionId);
+  }
   get port() {
     const addr = this.httpServer.address();
     return typeof addr === "object" && addr ? addr.port : 0;
@@ -154955,6 +155053,7 @@ var StreamerServer = class {
   async close() {
     for (const timer of this.ptyGraceTimers.values()) clearTimeout(timer);
     this.ptyGraceTimers.clear();
+    this.holdWhenIdle.clear();
     if (this.idleReaperTimer) {
       clearInterval(this.idleReaperTimer);
       this.idleReaperTimer = null;
@@ -159375,7 +159474,8 @@ function generateQr(payload) {
 function printUrlBanner({
   url: url2,
   qr: qr2,
-  expiresAt
+  expiresAt,
+  fingerprint: fingerprint2
 }) {
   const contentLines = ["Threadbase Streamer \u2014 server address", "", url2];
   if (qr2) {
@@ -159389,6 +159489,14 @@ function printUrlBanner({
       contentLines.push("", "Scan to pair a mobile client");
     }
   }
+  if (fingerprint2) {
+    contentLines.push(
+      "",
+      "Identity code",
+      fingerprint2,
+      "This should match the code your phone shows after you scan."
+    );
+  }
   const width = Math.max(...contentLines.map((l) => l.length));
   const pad = (l) => `\u2551 ${l}${" ".repeat(width - l.length)} \u2551`;
   const top = `\u2554${"\u2550".repeat(width + 2)}\u2557`;
@@ -159452,9 +159560,15 @@ async function printServerBanner({
   }
   const { token, expiresAt, expiresInSeconds } = await res.json();
   const expSeconds = Math.floor(expiresAt / 1e3);
-  const payload = `threadbase://pair?url=${encodeURIComponent(url2)}&token=${token}&exp=${expSeconds}` + (e2eeOffered ? `&spk=${identityKey()}&v=1` : "");
+  let fingerprint2;
+  let payload = `threadbase://pair?url=${encodeURIComponent(url2)}&token=${token}&exp=${expSeconds}`;
+  if (e2eeOffered) {
+    const spk = identityKey();
+    payload += `&spk=${spk}&v=1`;
+    fingerprint2 = serverIdentityFingerprint(spk);
+  }
   const qr2 = await generateQr(payload);
-  log15.info(printUrlBanner({ url: url2, qr: qr2, expiresAt }));
+  log15.info(printUrlBanner({ url: url2, qr: qr2, expiresAt, fingerprint: fingerprint2 }));
   log15.info(`Pair URL: ${payload}`);
   log15.info(`Expires in ${expiresInSeconds}s`);
 }