@threadbase-sh/streamer 1.46.1 → 1.47.0

package/dist/index.d.cts

@@ -128,7 +128,7 @@ type SessionStatus = "running" | "waiting_input" | "idle";
  * 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";
+type SessionLifecycle = "attached" | "starting" | "detached" | "orphaned" | "resumable" | "completed" | "failed";
 /**
  * How a SessionStatus was derived (C3).
  * See docs/architecture/2026-07-24-session-state-confidence.md.
@@ -164,6 +164,13 @@ interface ManagedSession {
     promptCount: number;
     lastOutput: string;
     failureReason?: string;
+    /**
+     * Machine-readable companion to `failureReason`, set only when the runner
+     * recognised the failure. Currently just `codex_active_writer` (Codex's
+     * single-writer lock), which the resume path maps to a structured 409 rather
+     * than reporting a spawn as successful. Absent for every other failure.
+     */
+    failureCode?: string;
     sessionName?: string;
     model?: string;
     account?: string;
@@ -213,6 +220,13 @@ interface ManagedSession {
      * lifetime of a live PTY) — must never be written into either of those.
      */
     boundConversationId?: string;
+    /**
+     * Source conversation this session was FORKED from (`codex fork`). Distinct
+     * from `resumedFromConversationId`: a resume continues one conversation, a
+     * fork starts a second one whose history diverges from the source at the fork
+     * point — and the source keeps its own owner, which is the entire point.
+     */
+    forkedFromConversationId?: string;
     /**
      * Multi-agent mode only. Per-session in-memory LRU of progress event ids
      * seen by the webhook receiver. Used to drop Temporal-replay duplicates
@@ -403,7 +417,10 @@ interface SessionResponse {
      * 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.
+     * so a client that ignores this behaves exactly as it did before. `"starting"`
+     * is additive in the same way: a session we hold no PTY for and have observed
+     * no exit for reports it instead of the `"completed"` it used to, so a client
+     * can tell "not attached yet" from "ended" (tb-mobile #508).
      */
     /**
      * How `status` was derived and how far to trust it (C3). Additive: `status`
@@ -451,6 +468,8 @@ interface SessionResponse {
     lastActivityAt?: string;
     filePath?: string;
     resumedFromConversationId?: string;
+    /** See `ManagedSession.forkedFromConversationId`. Additive; older clients ignore it. */
+    forkedFromConversationId?: string;
     /** See `ManagedSession.boundConversationId` — never repurposes `conversationId`. */
     boundConversationId?: string;
     /**
@@ -588,6 +607,17 @@ interface StartSessionOptions {
     claudeFlags?: ClaudeFlagValues;
     claudeExtraArgs?: string;
 }
+interface StartForkSessionOptions {
+    /**
+     * Provider-side id of the conversation to fork FROM (for Codex, the rollout
+     * id — never a local placeholder). The forked session gets its own id; the
+     * two identities are deliberately kept distinct.
+     */
+    forkFromId: string;
+    projectPath: string;
+    projectName?: string;
+    branch?: string;
+}
 interface StartFreshSessionOptions {
     projectPath: string;
     projectName?: string;
@@ -1218,7 +1248,6 @@ declare const ProjectSchema: z.ZodObject<{
     lastIndexedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     latestMessageAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     latestMessageId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    messageCount: z.ZodOptional<z.ZodNumber>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
 }, z.core.$strip>;
@@ -1512,6 +1541,15 @@ declare class LiveSessionManager {
     startFresh(options: StartFreshSessionOptions & {
         provider?: ProviderName;
     }): Promise<ManagedSession>;
+    /**
+     * Fork an existing conversation into a new session. Codex-only: `codex fork`
+     * has no Claude Code equivalent, and there is no safe generic fallback — a
+     * silent downgrade to resume would attach to the very writer the caller is
+     * trying to leave alone.
+     */
+    startFork(options: StartForkSessionOptions & {
+        provider?: ProviderName;
+    }): Promise<ManagedSession>;
     sendInput(sessionId: string, input: string): number;
     sendKeys(sessionId: string, keys: string): void;
     cancel(sessionId: string): void;
@@ -1696,6 +1734,7 @@ type ApiDeps = {
     handleSetSessionEffort: (sessionId: string, req: IncomingMessage, res: ServerResponse) => Promise<void>;
     handleUploadFile: (sessionId: string, req: IncomingMessage, res: ServerResponse) => Promise<void>;
     handleAdopt: (sessionId: string, res: ServerResponse) => Promise<void>;
+    handleFork: (sessionId: string, req: IncomingMessage, res: ServerResponse) => Promise<void>;
     handleResume: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
     handleStartSession: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
     handleListConversations: (url: URL, res: ServerResponse) => Promise<void>;
@@ -1916,6 +1955,7 @@ declare class StreamerServer {
     private liveActivityNotifier;
     private liveActivityRenewal;
     private discoveryCache;
+    private discoveryInFlight;
     private cacheDir;
     private runtimeDbPath;
     private tailSize;
@@ -2183,6 +2223,12 @@ declare class StreamerServer {
     private maybeAttachExternalTail;
     /** Stop tailing an external file and drop its bookkeeping. */
     private detachExternalTail;
+    /**
+     * 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).
+     */
+    private handleJsonlDeleted;
     /** Make room for one more tail by evicting the least recently active ones. */
     private evictExternalTailsIfNeeded;
     /**
@@ -2216,8 +2262,28 @@ declare class StreamerServer {
     private handleSearchTarget;
     private handleSearch;
     private handleListSessions;
+    /**
+     * Refresh the discovered-process list, sharing one in-flight enumeration
+     * across concurrent callers and honouring the 15s TTL cache.
+     */
+    private refreshDiscovery;
     private handleGetSession;
     private handleResume;
+    /**
+     * `POST /api/sessions/:id/fork` — continue a conversation this streamer is
+     * not allowed to resume, without touching whoever owns it.
+     *
+     * Codex only (`codex fork <id>`): Claude Code has no equivalent, and there is
+     * no safe generic fallback — quietly resuming instead would attach to the
+     * exact writer the caller is trying to leave alone, which is the failure this
+     * endpoint exists to avoid.
+     *
+     * NOT idempotent by default: every accepted call starts another Codex
+     * process and another rollout. Clients that retry on timeout must send
+     * `idempotencyKey`, which replays the first outcome for 10 minutes (same
+     * store and semantics as `POST /:id/input`).
+     */
+    private handleFork;
     /**
      * Resume a session, from an HTTP request or from the boot path.
      *
@@ -2231,6 +2297,36 @@ declare class StreamerServer {
      * maps it to a status code and the boot caller logs it.
      */
     private resumeSession;
+    /**
+     * Resolve a client-supplied session/conversation id into everything needed to
+     * launch against it: the id the PROVIDER filed the history under, that
+     * history's path, the project cwd, and which CLI owns it.
+     *
+     * Shared by resume and fork so the two can never disagree about identity —
+     * which for Codex is the whole difficulty: the id a client navigated to may
+     * be a local placeholder, and only the registry knows the rollout id behind
+     * it.
+     */
+    private resolveConversationTarget;
+    /**
+     * Block until a freshly spawned session reaches `waiting_input` (ready) or
+     * `idle` (failed), or until `timeoutMs` elapses with the process still alive.
+     *
+     * "timeout" is not an error: it is the pre-existing asynchronous contract —
+     * the session keeps booting and the caller answers with a pending shape.
+     */
+    private waitForStartupOutcome;
+    /**
+     * Drop every trace of a session that never became usable, and hand back what
+     * it failed with.
+     *
+     * The runner has already torn itself down (failStartup / handleExit); what
+     * remains is server-side bookkeeping that would otherwise leave a dead
+     * session in the list, a registry row claiming a spawn, and a `selfPtyEndedAt`
+     * marker that would suppress the mtime collision signal on the NEXT resume —
+     * i.e. it would help hide the very owner we just collided with.
+     */
+    private abandonFailedStart;
     private enrichResumedSessionAsync;
     private handleSendInput;
     private processJsonlQuestions;
@@ -2368,4 +2464,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 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$1 as StatusSource, StreamerServer, type UserMessage, WSHub, type WSMessage, confidenceForSource, 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 StartForkSessionOptions, type StartFreshSessionOptions, type StartSessionOptions, type StatusConfidence, type StatusSource$1 as StatusSource, StreamerServer, type UserMessage, WSHub, type WSMessage, confidenceForSource, createAgentClient, createConversationWriter, createPool, createProgressDedupeLRU, createProgressRoutes, discoverClaudeProcesses, generateApiKey, getDbConfig, isDbEnabled, isProviderName, isProviderResumable, loadOrCreateApiKey, maskConnectionString, readAgentConfig, validateApiKey };

package/dist/index.d.ts

@@ -128,7 +128,7 @@ type SessionStatus = "running" | "waiting_input" | "idle";
  * 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";
+type SessionLifecycle = "attached" | "starting" | "detached" | "orphaned" | "resumable" | "completed" | "failed";
 /**
  * How a SessionStatus was derived (C3).
  * See docs/architecture/2026-07-24-session-state-confidence.md.
@@ -164,6 +164,13 @@ interface ManagedSession {
     promptCount: number;
     lastOutput: string;
     failureReason?: string;
+    /**
+     * Machine-readable companion to `failureReason`, set only when the runner
+     * recognised the failure. Currently just `codex_active_writer` (Codex's
+     * single-writer lock), which the resume path maps to a structured 409 rather
+     * than reporting a spawn as successful. Absent for every other failure.
+     */
+    failureCode?: string;
     sessionName?: string;
     model?: string;
     account?: string;
@@ -213,6 +220,13 @@ interface ManagedSession {
      * lifetime of a live PTY) — must never be written into either of those.
      */
     boundConversationId?: string;
+    /**
+     * Source conversation this session was FORKED from (`codex fork`). Distinct
+     * from `resumedFromConversationId`: a resume continues one conversation, a
+     * fork starts a second one whose history diverges from the source at the fork
+     * point — and the source keeps its own owner, which is the entire point.
+     */
+    forkedFromConversationId?: string;
     /**
      * Multi-agent mode only. Per-session in-memory LRU of progress event ids
      * seen by the webhook receiver. Used to drop Temporal-replay duplicates
@@ -403,7 +417,10 @@ interface SessionResponse {
      * 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.
+     * so a client that ignores this behaves exactly as it did before. `"starting"`
+     * is additive in the same way: a session we hold no PTY for and have observed
+     * no exit for reports it instead of the `"completed"` it used to, so a client
+     * can tell "not attached yet" from "ended" (tb-mobile #508).
      */
     /**
      * How `status` was derived and how far to trust it (C3). Additive: `status`
@@ -451,6 +468,8 @@ interface SessionResponse {
     lastActivityAt?: string;
     filePath?: string;
     resumedFromConversationId?: string;
+    /** See `ManagedSession.forkedFromConversationId`. Additive; older clients ignore it. */
+    forkedFromConversationId?: string;
     /** See `ManagedSession.boundConversationId` — never repurposes `conversationId`. */
     boundConversationId?: string;
     /**
@@ -588,6 +607,17 @@ interface StartSessionOptions {
     claudeFlags?: ClaudeFlagValues;
     claudeExtraArgs?: string;
 }
+interface StartForkSessionOptions {
+    /**
+     * Provider-side id of the conversation to fork FROM (for Codex, the rollout
+     * id — never a local placeholder). The forked session gets its own id; the
+     * two identities are deliberately kept distinct.
+     */
+    forkFromId: string;
+    projectPath: string;
+    projectName?: string;
+    branch?: string;
+}
 interface StartFreshSessionOptions {
     projectPath: string;
     projectName?: string;
@@ -1218,7 +1248,6 @@ declare const ProjectSchema: z.ZodObject<{
     lastIndexedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     latestMessageAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     latestMessageId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    messageCount: z.ZodOptional<z.ZodNumber>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
 }, z.core.$strip>;
@@ -1512,6 +1541,15 @@ declare class LiveSessionManager {
     startFresh(options: StartFreshSessionOptions & {
         provider?: ProviderName;
     }): Promise<ManagedSession>;
+    /**
+     * Fork an existing conversation into a new session. Codex-only: `codex fork`
+     * has no Claude Code equivalent, and there is no safe generic fallback — a
+     * silent downgrade to resume would attach to the very writer the caller is
+     * trying to leave alone.
+     */
+    startFork(options: StartForkSessionOptions & {
+        provider?: ProviderName;
+    }): Promise<ManagedSession>;
     sendInput(sessionId: string, input: string): number;
     sendKeys(sessionId: string, keys: string): void;
     cancel(sessionId: string): void;
@@ -1696,6 +1734,7 @@ type ApiDeps = {
     handleSetSessionEffort: (sessionId: string, req: IncomingMessage, res: ServerResponse) => Promise<void>;
     handleUploadFile: (sessionId: string, req: IncomingMessage, res: ServerResponse) => Promise<void>;
     handleAdopt: (sessionId: string, res: ServerResponse) => Promise<void>;
+    handleFork: (sessionId: string, req: IncomingMessage, res: ServerResponse) => Promise<void>;
     handleResume: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
     handleStartSession: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
     handleListConversations: (url: URL, res: ServerResponse) => Promise<void>;
@@ -1916,6 +1955,7 @@ declare class StreamerServer {
     private liveActivityNotifier;
     private liveActivityRenewal;
     private discoveryCache;
+    private discoveryInFlight;
     private cacheDir;
     private runtimeDbPath;
     private tailSize;
@@ -2183,6 +2223,12 @@ declare class StreamerServer {
     private maybeAttachExternalTail;
     /** Stop tailing an external file and drop its bookkeeping. */
     private detachExternalTail;
+    /**
+     * 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).
+     */
+    private handleJsonlDeleted;
     /** Make room for one more tail by evicting the least recently active ones. */
     private evictExternalTailsIfNeeded;
     /**
@@ -2216,8 +2262,28 @@ declare class StreamerServer {
     private handleSearchTarget;
     private handleSearch;
     private handleListSessions;
+    /**
+     * Refresh the discovered-process list, sharing one in-flight enumeration
+     * across concurrent callers and honouring the 15s TTL cache.
+     */
+    private refreshDiscovery;
     private handleGetSession;
     private handleResume;
+    /**
+     * `POST /api/sessions/:id/fork` — continue a conversation this streamer is
+     * not allowed to resume, without touching whoever owns it.
+     *
+     * Codex only (`codex fork <id>`): Claude Code has no equivalent, and there is
+     * no safe generic fallback — quietly resuming instead would attach to the
+     * exact writer the caller is trying to leave alone, which is the failure this
+     * endpoint exists to avoid.
+     *
+     * NOT idempotent by default: every accepted call starts another Codex
+     * process and another rollout. Clients that retry on timeout must send
+     * `idempotencyKey`, which replays the first outcome for 10 minutes (same
+     * store and semantics as `POST /:id/input`).
+     */
+    private handleFork;
     /**
      * Resume a session, from an HTTP request or from the boot path.
      *
@@ -2231,6 +2297,36 @@ declare class StreamerServer {
      * maps it to a status code and the boot caller logs it.
      */
     private resumeSession;
+    /**
+     * Resolve a client-supplied session/conversation id into everything needed to
+     * launch against it: the id the PROVIDER filed the history under, that
+     * history's path, the project cwd, and which CLI owns it.
+     *
+     * Shared by resume and fork so the two can never disagree about identity —
+     * which for Codex is the whole difficulty: the id a client navigated to may
+     * be a local placeholder, and only the registry knows the rollout id behind
+     * it.
+     */
+    private resolveConversationTarget;
+    /**
+     * Block until a freshly spawned session reaches `waiting_input` (ready) or
+     * `idle` (failed), or until `timeoutMs` elapses with the process still alive.
+     *
+     * "timeout" is not an error: it is the pre-existing asynchronous contract —
+     * the session keeps booting and the caller answers with a pending shape.
+     */
+    private waitForStartupOutcome;
+    /**
+     * Drop every trace of a session that never became usable, and hand back what
+     * it failed with.
+     *
+     * The runner has already torn itself down (failStartup / handleExit); what
+     * remains is server-side bookkeeping that would otherwise leave a dead
+     * session in the list, a registry row claiming a spawn, and a `selfPtyEndedAt`
+     * marker that would suppress the mtime collision signal on the NEXT resume —
+     * i.e. it would help hide the very owner we just collided with.
+     */
+    private abandonFailedStart;
     private enrichResumedSessionAsync;
     private handleSendInput;
     private processJsonlQuestions;
@@ -2368,4 +2464,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 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$1 as StatusSource, StreamerServer, type UserMessage, WSHub, type WSMessage, confidenceForSource, 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 StartForkSessionOptions, type StartFreshSessionOptions, type StartSessionOptions, type StatusConfidence, type StatusSource$1 as StatusSource, StreamerServer, type UserMessage, WSHub, type WSMessage, confidenceForSource, createAgentClient, createConversationWriter, createPool, createProgressDedupeLRU, createProgressRoutes, discoverClaudeProcesses, generateApiKey, getDbConfig, isDbEnabled, isProviderName, isProviderResumable, loadOrCreateApiKey, maskConnectionString, readAgentConfig, validateApiKey };