@threadbase-sh/streamer 1.36.3 → 1.37.0

package/dist/index.d.cts

@@ -78,6 +78,30 @@ interface Logger {
     pino: Logger$1;
 }
 
+/** Claude Code `--permission-mode` values, as accepted by CLI v2.1.x. */
+declare const PERMISSION_MODES: readonly ["acceptEdits", "auto", "bypassPermissions", "manual", "dontAsk", "plan"];
+type PermissionMode = (typeof PERMISSION_MODES)[number];
+type FlagValueType = "boolean" | "string" | "enum" | "list";
+/** How risky enabling a flag is. Drives the client's confirmation UX. */
+type FlagRisk = "low" | "elevated" | "dangerous";
+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;
+}
+type ClaudeFlagValue = string | string[] | boolean;
+type ClaudeFlagValues = Record<string, ClaudeFlagValue>;
+
 declare const CLAUDE_CODE_PROVIDER: "claude-code";
 declare const CODEX_CLI_PROVIDER: "codex-cli";
 type ProviderName = typeof CLAUDE_CODE_PROVIDER | typeof CODEX_CLI_PROVIDER;
@@ -85,6 +109,34 @@ declare function isProviderName(value: unknown): value is ProviderName;
 declare function isProviderResumable(_provider: string | null | undefined, availabilityResumable: boolean): boolean;
 
 type SessionStatus = "running" | "waiting_input" | "idle";
+/**
+ * Process-lifetime axis for a managed session (C1 durable session runtime).
+ * Orthogonal to SessionStatus — see SessionResponse.lifecycle for why the two
+ * are separate, and docs/architecture/2026-07-24-durable-session-runtime.md.
+ */
+type SessionLifecycle = "attached" | "detached" | "orphaned" | "resumable" | "completed" | "failed";
+/**
+ * How a SessionStatus was derived (C3).
+ * See docs/architecture/2026-07-24-session-state-confidence.md.
+ *
+ * The runners already compute this at every transition — it was written to a log
+ * line and discarded, so a status reached by a timer expiring was indistinguishable
+ * on the wire from one reached by observing a prompt marker.
+ */
+type StatusSource = "spawn" | "prompt-marker" | "screen-marker" | "user-input" | "process-exit" | "timeout-fallback" | "quiet-fallback" | "shutdown";
+/**
+ * How much to trust the status.
+ *
+ * `observed` — something in the stream or the process told us.
+ * `inferred` — a timer expired and we picked the most likely state.
+ *
+ * Deliberately two buckets rather than a numeric score: a percentage would imply
+ * a calibration we have no data to support. The point is that a guess must never
+ * be presented as an observation.
+ */
+type StatusConfidence = "observed" | "inferred";
+/** Confidence implied by each source. Inference is exactly the timer-driven paths. */
+declare function confidenceForSource(source: StatusSource): StatusConfidence;
 interface ManagedSession {
     id: string;
     provider?: ProviderName;
@@ -108,6 +160,12 @@ interface ManagedSession {
     lastMessageText?: string;
     lastMessageAt?: Date;
     lastActivityAt?: Date;
+    /**
+     * How `status` was derived, and when (C3). Confidence is derived from the
+     * source via confidenceForSource — storing both would let them disagree.
+     */
+    statusSource?: StatusSource;
+    statusUpdatedAt?: Date;
     filePath?: string;
     resumedFromConversationId?: string;
     /**
@@ -297,6 +355,31 @@ interface SessionResponse {
     startedAt: string;
     completedAt: string | null;
     ptyAttached: boolean;
+    /**
+     * Process-lifetime axis, orthogonal to `status` (C1).
+     *
+     * `status` answers "what is the agent doing" (running / waiting_input /
+     * idle); `lifecycle` answers "does this process still exist and do we own
+     * it". They were conflated before: `idle` meant finished, killed-to-save-
+     * resources, and externally-discovered all at once, so a client could not
+     * tell a completed session from one we terminated.
+     *
+     * Additive and optional — `ptyAttached` keeps its meaning (=== "attached"),
+     * so a client that ignores this behaves exactly as it did before.
+     */
+    /**
+     * How `status` was derived and how far to trust it (C3). Additive: `status`
+     * keeps its exact meaning, so a client ignoring these behaves as before.
+     * An `inferred` confidence means a timer expired and we assumed — not that
+     * anything in the stream confirmed the state.
+     */
+    statusSource?: StatusSource;
+    statusConfidence?: StatusConfidence;
+    statusUpdatedAt?: string;
+    lifecycle?: SessionLifecycle;
+    /** How `lifecycle` was determined, so stale values are visible not implied. */
+    lifecycleSource?: "spawn" | "exit" | "probe" | "reconcile";
+    lifecycleUpdatedAt?: string;
     failureReason?: string;
     pid?: number;
     sessionName?: string;
@@ -404,9 +487,11 @@ interface ServerConfig {
     tailSize?: number;
     directoryScanDebounceMs?: number;
     defaultSystemPrompt?: string;
-    defaultPermissionMode?: "acceptEdits" | "manual";
+    defaultPermissionMode?: PermissionMode;
     defaultModel?: string;
     defaultEffort?: "low" | "medium" | "high" | "xhigh" | "max";
+    claudeFlags?: ClaudeFlagValues;
+    claudeExtraArgs?: string;
 }
 interface PTYManagerOptions {
     onOutput?: (sessionId: string, data: string) => void;
@@ -427,17 +512,21 @@ interface StartSessionOptions {
     projectPath: string;
     projectName?: string;
     branch?: string;
-    permissionMode?: "acceptEdits" | "manual";
+    permissionMode?: PermissionMode;
     model?: string;
     effort?: "low" | "medium" | "high" | "xhigh" | "max";
+    claudeFlags?: ClaudeFlagValues;
+    claudeExtraArgs?: string;
 }
 interface StartFreshSessionOptions {
     projectPath: string;
     projectName?: string;
     systemPrompt?: string;
-    permissionMode?: "acceptEdits" | "manual";
+    permissionMode?: PermissionMode;
     model?: string;
     effort?: "low" | "medium" | "high" | "xhigh" | "max";
+    claudeFlags?: ClaudeFlagValues;
+    claudeExtraArgs?: string;
 }
 interface SessionRunner {
     start(sessionId: string, options: StartSessionOptions): Promise<ManagedSession>;
@@ -450,12 +539,38 @@ interface SessionRunner {
     getOutput(sessionId: string): string;
     getOutputLines(sessionId: string, maxLines: number): Promise<string[]>;
     getInputHistory(sessionId: string): UserMessage[];
+    getPid(sessionId: string): number | null;
     getSession(sessionId: string): ManagedSession | null;
     hasSession(sessionId: string): boolean;
     listSessions(): ManagedSession[];
     dispose(): void;
 }
 
+/**
+ * Scoped device capabilities (C5).
+ * See docs/architecture/2026-07-24-device-identity-and-capabilities.md.
+ *
+ * Authorization was all-or-nothing: authMiddleware asked one question — is this
+ * token the API key — and answered 401 or full access. A device paired merely to
+ * glance at session status held exactly the authority of the one driving the
+ * agent, because there was only ever one credential and no principal to scope.
+ */
+declare const CAPABILITIES: readonly ["history:read", "session:control", "fs:browse", "fs:upload", "notifications", "admin"];
+type Capability = (typeof CAPABILITIES)[number];
+type CapabilityPreset = "full" | "read-only";
+/**
+ * The principal behind a request.
+ *
+ * `legacy` is the shared API key: it predates device identity, so it carries the
+ * full preset and no device id. Keeping it working is what lets this ship
+ * without breaking every already-paired device.
+ */
+interface Principal {
+    kind: "device" | "legacy";
+    deviceId?: string;
+    capabilities: Capability[];
+}
+
 interface LineSpan {
     /** Absolute byte offset of the line's first byte in the file. */
     byteOffset: number;
@@ -818,6 +933,74 @@ declare class ConversationsRepository {
     hasOrphanRows(): boolean;
 }
 
+/**
+ * Paired-device registry (C5).
+ * See docs/architecture/2026-07-24-device-identity-and-capabilities.md.
+ *
+ * Stores identity and authority for each paired device. Never stores a usable
+ * credential: only the SHA-256 of a device token, so reading this table cannot
+ * impersonate a device.
+ */
+interface DeviceRow {
+    device_id: string;
+    public_key: string;
+    token_hash: string;
+    name: string | null;
+    capabilities: string;
+    created_at: number;
+    last_seen_at: number | null;
+    revoked_at: number | null;
+}
+/** A device as reported over the API. Deliberately carries no credential. */
+interface DeviceView {
+    deviceId: string;
+    name: string | null;
+    capabilities: Capability[];
+    createdAt: number;
+    lastSeenAt: number | null;
+    revokedAt: number | null;
+}
+interface RegisteredDevice {
+    deviceId: string;
+    /** Returned to the client exactly once, at pairing. Never persisted raw. */
+    deviceToken: string;
+    capabilities: Capability[];
+}
+declare class DevicesRepository {
+    private insertStmt;
+    private byTokenHashStmt;
+    private byIdStmt;
+    private listStmt;
+    private revokeStmt;
+    private touchStmt;
+    constructor(db: Database.Database);
+    /**
+     * Record a newly paired device and mint its token.
+     *
+     * The raw token is returned to the caller and never stored — this is the only
+     * moment it exists outside the client.
+     */
+    register(args: {
+        publicKey: string;
+        name?: string | null;
+        preset?: CapabilityPreset;
+        now?: number;
+    }): RegisteredDevice;
+    /**
+     * Resolve a presented token to a device, or null.
+     *
+     * Returns null for a revoked device, so revocation takes effect on the very
+     * next request with no cache to go stale.
+     */
+    authenticate(token: string): DeviceRow | null;
+    get(deviceId: string): DeviceRow | null;
+    /** All devices, including revoked ones — an audit surface needs the history. */
+    list(): DeviceView[];
+    /** Revoke one device. Others are untouched — no key rotation, no collateral. */
+    revoke(deviceId: string, now?: number): boolean;
+    touch(deviceId: string, now?: number): void;
+}
+
 /**
  * Persisted Project row. Mirrors the projects SQLite table.
  */
@@ -862,6 +1045,74 @@ declare class ProjectsRepository {
     upsertProjectByPath(rawPath: string, input?: UpsertProjectInput): Project;
 }
 
+interface PushTokenRow {
+    token: string;
+    platform: string;
+    device_id: string | null;
+    registered_at: number;
+    last_success_at: number | null;
+    last_failure_at: number | null;
+    last_failure_code: string | null;
+    failure_streak: number;
+    revoked_at: number | null;
+}
+/**
+ * Health as reported to a client. Deliberately omits the token itself — a push
+ * token is a delivery credential, and a health endpoint has no reason to echo
+ * one back.
+ */
+interface PushTokenHealth {
+    platform: string;
+    deviceId: string | null;
+    registeredAt: number;
+    lastSuccessAt: number | null;
+    lastFailureAt: number | null;
+    lastFailureCode: string | null;
+    failureStreak: number;
+    revokedAt: number | null;
+    /**
+     * Never delivered vs delivering vs failing vs revoked. The distinction the
+     * user actually needs: "not yet" and "broken" look identical without it.
+     */
+    state: "never-delivered" | "healthy" | "failing" | "dead" | "revoked";
+}
+declare class PushRepository {
+    private upsertStmt;
+    private getStmt;
+    private listActiveStmt;
+    private listAllStmt;
+    private successStmt;
+    private failureStmt;
+    private revokeStmt;
+    private claimEventStmt;
+    private markDeliveredStmt;
+    constructor(db: Database.Database);
+    register(args: {
+        token: string;
+        platform: string;
+        deviceId?: string | null;
+        now?: number;
+    }): void;
+    get(token: string): PushTokenRow | null;
+    /** Tokens eligible for delivery — not revoked, not past the failure limit. */
+    listDeliverable(): PushTokenRow[];
+    /** Every token, including dead and revoked ones, for the health report. */
+    listHealth(): PushTokenHealth[];
+    recordSuccess(token: string, now?: number): void;
+    recordFailure(token: string, code: string, now?: number): void;
+    revoke(token: string, now?: number): boolean;
+    /**
+     * Claim an event id for delivery.
+     *
+     * Returns true exactly once per event id. A retry, a reconnect
+     * reconciliation, or two triggers firing for the same underlying event all
+     * get false and must not notify — the user should never be told twice about
+     * one thing.
+     */
+    claimEvent(eventId: string, sessionId: string | null, now?: number): boolean;
+    markDelivered(eventId: string, now?: number): void;
+}
+
 declare class SessionStore {
     private managed;
     private discovered;
@@ -914,6 +1165,7 @@ declare class LiveSessionManager {
     getOutputLines(sessionId: string, maxLines: number): Promise<string[]>;
     getInputHistory(sessionId: string): UserMessage[];
     getSession(sessionId: string): ManagedSession | null;
+    getPid(sessionId: string): number | null;
     hasSession(sessionId: string): boolean;
     listSessions(): ManagedSession[];
     dispose(): void;
@@ -1025,6 +1277,17 @@ type ApiDeps = {
         newKey: string;
         persisted: boolean;
     };
+    claudeFlagsConfig: () => {
+        registry: readonly FlagDefinition[];
+        values: ClaudeFlagValues;
+        extraArgs: string | null;
+        persisted: boolean;
+    };
+    setClaudeFlagsConfig: (values: ClaudeFlagValues, extraArgs: string | undefined) => {
+        values: ClaudeFlagValues;
+        extraArgs: string | null;
+        persisted: boolean;
+    };
     publicUrl: string | null;
     browseRoot: string | null;
     browserCors: string | undefined;
@@ -1033,6 +1296,10 @@ type ApiDeps = {
     wsHub: WSHub;
     cache: () => ConversationCache | null;
     cacheMonitor: () => CacheIntegrityMonitor | null;
+    /** Push registration + delivery state (C7). Null when the cache DB is unavailable. */
+    pushRepo: () => PushRepository | null;
+    /** Paired-device registry (C5). Null when the cache DB is unavailable. */
+    devicesRepo: () => DevicesRepository | null;
     projectsRepo: () => ProjectsRepository | null;
     conversationsRepo: () => ConversationsRepository | null;
     sessionsRepo: () => SessionsRepository | null;
@@ -1078,6 +1345,8 @@ type AppEnv = {
         requestId?: string;
         validatedBody?: unknown;
         validatedQuery?: unknown;
+        /** Who is making this request (C5). Set by authMiddleware. */
+        principal?: Principal;
     };
 };
 
@@ -1168,6 +1437,7 @@ declare class PTYManager implements SessionRunner {
     getOutput(sessionId: string): string;
     getOutputLines(sessionId: string, maxLines: number): Promise<string[]>;
     getInputHistory(sessionId: string): UserMessage[];
+    getPid(sessionId: string): number | null;
     private recordUserMessage;
     getSession(sessionId: string): ManagedSession | null;
     hasSession(sessionId: string): boolean;
@@ -1195,6 +1465,7 @@ declare class StreamerServer {
     private selfPtyEndedAt;
     private pendingQuestionKey;
     private pendingPermission;
+    private pendingPermissionKey;
     private scanner;
     private scannerPersistenceDisabled;
     private allScanners;
@@ -1227,9 +1498,16 @@ declare class StreamerServer {
     private defaultPermissionMode;
     private defaultModel;
     private defaultEffort;
+    private claudeFlags;
+    private claudeExtraArgs;
+    private claudeFlagsPersistable;
     private ptyGraceTimers;
     private ptyGraceDeferCounts;
     private sessionSubscribers;
+    private lastAgentChunkAt;
+    private idempotency;
+    private sessionLifecycles;
+    private idleReaperTimer;
     private clientIdToWs;
     private wsToClientId;
     private cache;
@@ -1237,7 +1515,11 @@ declare class StreamerServer {
     private projectsRepo;
     private conversationsRepo;
     private sessionsRepo;
+    private managedSessionsRepo;
+    private readonly streamerInstanceId;
     private cacheMetadataRepo;
+    private pushRepo;
+    private devicesRepo;
     private discoveryCache;
     private cacheDir;
     private tailSize;
@@ -1262,7 +1544,86 @@ declare class StreamerServer {
      * a full broadcast if no match exists (old clients, or no WS registered yet).
      */
     private broadcastOrUnicastSessionList;
+    /**
+     * Overlay boot-reconciliation verdicts onto session responses.
+     *
+     * A session left by a previous run is not in the in-memory store, so
+     * SessionStore cannot classify it — it only ever sees what this run spawned.
+     * Discovery may still surface the process, in which case the reconciler knows
+     * strictly more about it than discovery does: it can tell `detached` (alive
+     * and confirmed ours) from `orphaned` (alive but identity unconfirmed), which
+     * a pid enumeration alone cannot.
+     *
+     * Only applied when the session is NOT live here: a session this run owns has
+     * an authoritative lifecycle already, and a stale verdict must never override
+     * it.
+     */
+    private withReconciledLifecycle;
     private addSessionSubscriber;
+    /**
+     * Classify sessions left behind by previous streamer runs (C1 Phase 3a).
+     *
+     * Agents already outlive the streamer today on the crash and dev-takeover
+     * paths, which exit without reaching ptyManager.dispose() — they are just
+     * invisible when they do, because nothing recorded that they existed. This
+     * turns those rows into an explicit verdict per session.
+     *
+     * Read-only with respect to processes: it probes and classifies, and never
+     * signals anything. `orphaned` is a report, not a cleanup trigger.
+     */
+    private reconcilePreviousSessions;
+    /**
+     * Pick a token guaranteed to appear in the spawned process's argv, for the
+     * reconciler's pid-reuse guard.
+     *
+     * Claude always passes the session id (`--resume <id>` or `--session-id
+     * <id>`), so it is both present and unique. Codex only does on *resume*
+     * (`codex resume <id>`); a fresh Codex spawn is `codex --cd <path>
+     * --no-alt-screen` with no id at all, because the rollout id does not exist
+     * until the CLI writes it. boundConversationId is what distinguishes the two:
+     * it is set once that rollout has been discovered.
+     */
+    private spawnArgvToken;
+    /**
+     * Mirror a freshly-spawned session into the durable registry (C1 Phase 2).
+     *
+     * Called at each addManaged() site rather than inside SessionStore, because
+     * the store is a pure in-memory structure with no DB dependency and adding
+     * one would drag persistence into every unit test that touches it.
+     *
+     * Best-effort by design: a failed registry write must never break session
+     * start. Losing a row costs post-restart *visibility* for that session, which
+     * is strictly better than refusing to run the agent at all.
+     */
+    private recordSessionSpawn;
+    /**
+     * Stamp every live session as ended-by-shutdown before dispose() kills it.
+     *
+     * PTYManager.dispose() signals each child directly and fires no
+     * onStatusChange, so the registry would otherwise keep rows sitting at
+     * `running` forever and the next boot could not tell a deliberate restart
+     * from a crash. Recording `shutdown` as the status source makes that
+     * distinction explicit rather than inferred.
+     *
+     * Not a `completed_at` write for the agent's own work — the agent did not
+     * finish, we stopped it — but the session is genuinely terminal, so it must
+     * leave the reconciler's probe set.
+     */
+    private recordShutdownState;
+    /**
+     * Release PTYs whose agent has been silent past IDLE_REAP_AFTER_MS.
+     *
+     * This is the bound that lets handleWsClose stop arming kill timers. The
+     * distinction that matters: the old timer measured how long nobody was
+     * *watching*, which is uncorrelated with whether work is in flight. This
+     * measures how long the *agent* has produced nothing, and only ever considers
+     * sessions that are already settled — a `running` PTY is skipped regardless of
+     * age, so a long silent turn is never interrupted.
+     *
+     * Exposed (not private) so tests can drive one sweep deterministically instead
+     * of waiting on the interval.
+     */
+    reapIdleSessions(now?: number): string[];
     private startGraceTimer;
     get port(): number;
     private currentWarmupState;
@@ -1282,6 +1643,19 @@ declare class StreamerServer {
     private handlePairStart;
     private handlePairExchange;
     private rotateApiKey;
+    private getClaudeFlagsConfig;
+    /**
+     * Replace the per-server flag set. Applies to the NEXT spawn — a live PTY
+     * keeps the argv it was started with.
+     *
+     * Mirrors rotateApiKey(): when the values were pinned by a CLI flag we still
+     * apply them in memory but skip the server.yaml write, because the flag would
+     * win again on restart and silently revert them.
+     *
+     * Logged with old→new at info level on purpose: this can disable the
+     * permission prompts entirely, so it needs a forensic trail.
+     */
+    private setClaudeFlagsConfig;
     private checkRateLimit;
     private checkExchangeRateLimit;
     private checkSessionStartRateLimit;
@@ -1482,4 +1856,4 @@ declare class ConversationWatcher {
     private readNewLines;
 }
 
-export { type AgentClient, type AgentClientOpts, type AgentConfig, type AppendArgs, type AskOption, type AskQuestion, CLAUDE_CODE_PROVIDER, CODEX_CLI_PROVIDER, type CacheAlertResolveAction, type ConversationListResponse, ConversationWatcher, type ConversationWriter, type DbConfig, type DiscoveredProcess, LiveSessionManager, type ManagedSession, PTYManager, type PTYManagerOptions, type PermissionOption, type ProcessLiveness, type ProgressDedupeLRU, type ProviderName, type ServerConfig, type ServerWarmingUpResponse, type ServerWarmupState, type SessionActivity, type SessionCursor, type SessionListPage, type SessionListQuery, type SessionOwnership, type SessionResponse, type SessionRunner, type SessionSortKey, type SessionStatus, SessionStore, type SortOrder, type StartFreshSessionOptions, type StartSessionOptions, StreamerServer, type UserMessage, WSHub, type WSMessage, createAgentClient, createConversationWriter, createPool, createProgressDedupeLRU, createProgressRoutes, discoverClaudeProcesses, generateApiKey, getDbConfig, isDbEnabled, isProviderName, isProviderResumable, loadOrCreateApiKey, maskConnectionString, readAgentConfig, validateApiKey };
+export { type AgentClient, type AgentClientOpts, type AgentConfig, type AppendArgs, type AskOption, type AskQuestion, CLAUDE_CODE_PROVIDER, CODEX_CLI_PROVIDER, type CacheAlertResolveAction, type ConversationListResponse, ConversationWatcher, type ConversationWriter, type DbConfig, type DiscoveredProcess, LiveSessionManager, type ManagedSession, PTYManager, type PTYManagerOptions, type PermissionOption, type ProcessLiveness, type ProgressDedupeLRU, type ProviderName, type ServerConfig, type ServerWarmingUpResponse, type ServerWarmupState, type SessionActivity, type SessionCursor, type SessionLifecycle, type SessionListPage, type SessionListQuery, type SessionOwnership, type SessionResponse, type SessionRunner, type SessionSortKey, type SessionStatus, SessionStore, type SortOrder, type StartFreshSessionOptions, type StartSessionOptions, type StatusConfidence, type StatusSource, StreamerServer, type UserMessage, WSHub, type WSMessage, confidenceForSource, createAgentClient, createConversationWriter, createPool, createProgressDedupeLRU, createProgressRoutes, discoverClaudeProcesses, generateApiKey, getDbConfig, isDbEnabled, isProviderName, isProviderResumable, loadOrCreateApiKey, maskConnectionString, readAgentConfig, validateApiKey };