charness 0.0.0-stage → 3.1.0

package/dist/utils/jsonStreamHost.d.ts

@@ -0,0 +1,238 @@
+/**
+ * @description Host layout + IO primitives for the json-stream Claude backend's
+ * EXTERNAL process transport (plan 2026-07-05-jsonstream-restart-isolation).
+ *
+ * The `claude -p … stream-json` process is NOT a bot child any more: a `#!/bin/sh`
+ * wrapper hosts it inside a detached tmux session, with stdio rerouted to files
+ * under `DATA_DIR/jsonstream/<serialized key with ":" → "_">/` (Telegram:
+ * `<chatId>_<threadId>`):
+ *
+ *   stdin.fifo    ← the bot's control/user-turn writes (claude holds it `0<>`,
+ *                   i.e. open read-write on fd 0, so a bot restart — the writer
+ *                   dying — never EOFs claude's stdin; proven by the P1 probe)
+ *   stdout.jsonl  ← append-only stream-json event log the bot TAILS from a byte
+ *                   offset (deltas keep landing while the bot is down)
+ *   stderr.log    ← passive; read only for spawn-fail / exit diagnostics
+ *   pid, exitcode ← written by the wrapper; the adapter's poll tick uses them
+ *                   for exit detection (pid-alive + exitcode file)
+ *   wrapper.sh    ← the generated host script itself
+ *   question.json ← the pending AskUserQuestion control_request (written when
+ *                   surfaced, removed when resolved) so an adopt after a bot
+ *                   restart can still answer it over the FIFO
+ *
+ * Everything here is either pure decision logic (tail offsets, wrapper text,
+ * name codecs) or a thin fs primitive (FIFO open/write, pid/exitcode readers)
+ * — the orchestration lives in `adapters/claudeJsonStreamAdapter.ts`.
+ */
+import { StringDecoder } from 'string_decoder';
+import { type SessionKey } from '../sessionKey';
+import type { JsonStreamTailOffset } from '../types';
+/** Subdirectory of `DATA_DIR` that holds every thread's json-stream host dir. */
+export declare const jsonStreamRootDirName = "jsonstream";
+/** tmux session-name prefix for this backend — distinct from the scrape
+ *  backend's `claude` and the terminal's `term`, so adopt-at-boot scans never
+ *  cross-talk (locked decision). */
+export declare const jsonStreamTmuxPrefix = "cjson";
+/** Exit code the wrapper reports when `cd <workDir>` fails (folder vanished
+ *  between bind and spawn) — claude must never run in the wrong directory. */
+export declare const wrapperCdFailExitCode = 96;
+/** How long a fresh spawn waits for the wrapper to write the `pid` file. */
+export declare const pidFileWaitTimeoutMs = 5000;
+export declare const pidFilePollIntervalMs = 100;
+/** FIFO write-open guard (P1 probe): `O_WRONLY|O_NONBLOCK` raises `ENXIO`
+ *  while nothing holds the read end — a BLOCKING open would hang forever.
+ *  Retried because claude opens its `0<>` end asynchronously during spawn;
+ *  `ENXIO` persisting past the retries means the process is dead. */
+export declare const fifoOpenMaxTries = 10;
+export declare const fifoOpenRetryDelayMs = 500;
+/** A full FIFO buffer raises `EAGAIN` on a non-blocking write — transient,
+ *  claude drains it. Bounded so a truly wedged reader can't spin forever. */
+export declare const fifoWriteMaxRetries = 100;
+export declare const fifoWriteRetryDelayMs = 50;
+/** No rotation in v1 (locked decision): the file is per-session and deleted on
+ *  stop/release. Past this size we log ONE warning, never rotate. */
+export declare const stdoutOversizeWarnBytes: number;
+/** Cap for the stderr excerpt quoted into spawn-fail / unexpected-exit logs. */
+export declare const stderrTailMaxChars = 400;
+/** Absolute paths of every file in one thread's json-stream host dir. */
+export interface JsonStreamSessionPaths {
+    dir: string;
+    stdinFifo: string;
+    stdoutFile: string;
+    stderrFile: string;
+    pidFile: string;
+    exitCodeFile: string;
+    wrapperFile: string;
+    questionFile: string;
+}
+/** Absolute path of the `jsonstream/` root under a given data dir. */
+export declare function resolveJsonStreamRoot(dataDir: string): string;
+/** Absolute path of one thread's json-stream host dir. */
+export declare function resolveJsonStreamSessionDir(dataDir: string, key: SessionKey): string;
+/**
+ * @description Inverse of the host-dir naming for the orphan-dir janitor.
+ * Strictness lives in the connector's codec (mirrors `parseTmuxSessionName`),
+ * so a foreign dir that happens to sit under `jsonstream/` is skipped, never
+ * swept by a mis-parse.
+ */
+export declare function parseJsonStreamDirName(name: string): SessionKey | null;
+export declare function getJsonStreamSessionPaths(dir: string): JsonStreamSessionPaths;
+/** tmux session name for a json-stream thread (`cjson-<chatId>-<threadId>`). */
+export declare function buildJsonStreamTmuxSessionName(key: SessionKey): string;
+/** Inverse of {@link buildJsonStreamTmuxSessionName}; `null` for foreign names. */
+export declare function parseJsonStreamTmuxSessionName(name: string): SessionKey | null;
+/**
+ * @description The `#!/bin/sh` host script (exact shape proven by the P1 probe
+ * `p1-probe2.mjs`): background claude with its stdio rerouted to the host files,
+ * record the child pid, then `wait` and record the exit code. `0<>` opens the
+ * stdin FIFO READ-WRITE on fd 0 — the load-bearing trick: claude itself holds a
+ * read end open, so the bot (a plain writer) can die and reconnect freely.
+ * `env -u ANTHROPIC_API_KEY` keeps subscription billing (`apiKeySource:"none"`)
+ * even if the tmux server environment carries a key. With an `environment`
+ * (a tracker conversation, R32) claude gets exactly those variables instead —
+ * `env -i`, so nothing of the tmux server's environment reaches it (no API key
+ * either). A non-default Claude account profile adds `CLAUDE_CONFIG_DIR=<dir>` to
+ * either `env` form (`utils/claudeProfiles.ts`); the default profile adds nothing,
+ * so the wrapper of a topic that never picked an account is byte-identical to
+ * the golden shape. The variable sits in the process environment — not only in
+ * the CLI's own reading of it — so a child `claude` the agent starts inherits the
+ * same account. All embedded strings are single-quoted; `claudePath` must be
+ * ABSOLUTE (tmux server PATH differs).
+ */
+export declare function buildWrapperScript(claudePath: string, args: readonly string[], workDir: string, paths: JsonStreamSessionPaths, environment?: Readonly<Record<string, string>> | null, configDir?: string | null): string;
+/**
+ * @description The `CLAUDE_CONFIG_DIR` a persisted wrapper script starts claude with, `null` for the default
+ * profile or an unreadable script. Read at adopt: the running process keeps the account it was spawned with,
+ * and the bot compares it with the profile its topic has now.
+ */
+export declare function readWrapperScriptConfigDir(wrapperFile: string): string | null;
+/**
+ * @description Open the stdin FIFO for writing WITHOUT ever blocking: a plain
+ * `open(O_WRONLY)` on a FIFO with no reader hangs forever (the P1 probe's first
+ * attempt did exactly that). `O_NONBLOCK` turns "no reader" into `ENXIO`,
+ * retried on a short delay while claude is still coming up. Returns the fd, or
+ * `null` when `ENXIO` persists — i.e. the claude process is NOT holding the
+ * FIFO, so the session is dead.
+ */
+export declare function openFifoWriterNonBlocking(fifoPath: string, maxTries?: number): Promise<number | null>;
+/**
+ * @description Write `text` to a non-blocking FIFO fd, retrying transient
+ * `EAGAIN` (buffer full — claude drains it) with a bounded backoff and
+ * continuing partial writes (a payload larger than the FIFO buffer lands in
+ * chunks). Anything else (`EPIPE` after claude died, `EBADF` after close)
+ * propagates to the caller's per-session write chain, which logs it.
+ */
+export declare function writeFifoText(fd: number, text: string): Promise<void>;
+export declare function readPidFile(pidFile: string): number | null;
+export declare function readExitCodeFile(exitCodeFile: string): number | null;
+/** `kill(pid, 0)` liveness probe (no signal actually delivered). */
+export declare function checkIsPidAlive(pid: number): boolean;
+/** Wait (bounded) for the wrapper to write the `pid` file after tmux spawn.
+ *  Returns the pid, or `null` on timeout (spawn diagnostics read stderr). */
+export declare function waitForPidFile(pidFile: string, timeoutMs?: number): Promise<number | null>;
+/** Last `maxChars` of the passive stderr log — spawn-fail / exit diagnostics
+ *  only (locked decision: no live stderr consumer). Empty when absent. */
+export declare function readStderrTail(stderrFile: string, maxChars?: number): string;
+/** File size in bytes, or `null` when the file doesn't exist (yet). */
+export declare function getFileSize(filePath: string): number | null;
+/** Read the byte range `[startOffset..endOffset)` of a file. May return fewer
+ *  bytes than asked on a race — the tail accounts by ACTUAL bytes consumed. */
+export declare function readFileByteRange(filePath: string, startOffset: number, endOffset: number): Buffer;
+/** Where an adopting bot resumes the stdout tail, and the background-task list
+ *  in force at that point (see {@link resolveAdoptedTail}). */
+export interface AdoptedTailStart {
+    startOffset: number;
+    backgroundTaskIds: string[];
+    isTurnInFlight: boolean;
+    outstandingToolUseIds: string[];
+    claudeCodeVersion: string | null;
+}
+/**
+ * @description Decide where an ADOPT resumes the stdout tail. A persisted offset
+ * is trusted only when it was recorded for the SAME claude session — a foreign /
+ * unknown offset seeds to the current EOF (no backlog flood, the first-migration
+ * case) — and is clamped to the file size (an externally truncated file). The
+ * background-task list persisted with the offset is restored on the same
+ * condition: the frames that built it lie before the offset and will not
+ * replay, so without it an adopted session with a running background task
+ * would read as idle and could be stopped (L-D2). The turn-in-flight flag and
+ * the outstanding tool calls are restored the same way — a turn in a long,
+ * silent tool call leaves no frame after the offset either, and the outstanding
+ * tool is what keeps the busy-idle watchdog from clearing the restored turn.
+ */
+export declare function resolveAdoptedTail(persistedTail: JsonStreamTailOffset | null, claudeSessionId: string, stdoutSizeBytes: number): AdoptedTailStart;
+/**
+ * @description Tail bookkeeping for ONE session's `stdout.jsonl` (the pattern of
+ * `claudeSubagentTail`, adapted to a single file feeding the stream-json line
+ * reader). Byte-exact so the offset persisted across bot restarts always lands
+ * on a LINE BOUNDARY — the restarted tail resumes on clean JSON, never a torn
+ * line:
+ *
+ *   consumedBytes        — file bytes read + fed to the utf8 decoder
+ *   decoderRetainedBytes — bytes the decoder holds back (a multi-byte char split
+ *                          at a read boundary; stdout is block-buffered, so
+ *                          splits mid-char DO happen with non-ASCII deltas)
+ *
+ * The line-boundary offset additionally subtracts the line reader's pending
+ * partial line ({@link getStdoutLineBoundaryOffset}) — those bytes were consumed
+ * but not yet processed, so a restart re-reads exactly them and nothing twice.
+ */
+export interface StdoutTailState {
+    consumedBytes: number;
+    decoderRetainedBytes: number;
+    decoder: StringDecoder;
+}
+export declare function createStdoutTailState(startOffsetBytes: number): StdoutTailState;
+/** What one tail poll should do given the file's current size. */
+export type StdoutTailDecision = 
+/** Nothing new. */
+{
+    kind: 'none';
+}
+/** Read `[startOffset..endOffset)` and feed it through the decoder/reader. */
+ | {
+    kind: 'read';
+    startOffset: number;
+    endOffset: number;
+}
+/** The file SHRANK below the consumed offset (external truncation — should
+ *  not happen for the append-only log). State was reset to the new EOF; the
+ *  caller must reset its line reader too (a stale partial would corrupt the
+ *  next line). */
+ | {
+    kind: 'reseed';
+};
+/**
+ * @description Decide the next tail action. Does NOT advance offsets on a
+ * `read` — {@link decodeStdoutTailChunk} advances by the bytes ACTUALLY read,
+ * so a short read (race with a concurrent append) self-heals next poll.
+ */
+export declare function getStdoutTailDecision(state: StdoutTailState, sizeBytes: number): StdoutTailDecision;
+/**
+ * @description Feed one appended byte chunk through the stateful utf8 decoder.
+ * Returns the decoded text (possibly empty while a multi-byte char is split);
+ * advances `consumedBytes` by the chunk length and re-derives the decoder's
+ * retained-byte count (`retainedNew = retainedPrior + chunkLen - decodedLen`,
+ * clamped defensively — invalid utf8 replacement chars could otherwise skew it
+ * negative).
+ */
+export declare function decodeStdoutTailChunk(state: StdoutTailState, chunk: Buffer): string;
+/**
+ * @description The byte offset up to which every COMPLETE line has been
+ * processed — the value persisted across bot restarts. `pendingLineText` is the
+ * line reader's buffered partial line (`ClaudeStreamLineReader.pending`): those
+ * bytes were consumed but not yet processed, so the persisted offset excludes
+ * them and a restarted tail re-reads exactly the unprocessed remainder.
+ */
+export declare function getStdoutLineBoundaryOffset(state: StdoutTailState, pendingLineText: string): number;
+/**
+ * @description Janitor: remove `jsonstream/` host dirs whose thread no longer
+ * owns a json-stream session (crash leftovers — the normal stop/release paths
+ * delete the dir themselves, and reattach handles live tmux sessions).
+ * `checkIsThreadOwned` is injected by the bot (persisted json-stream agent row
+ * with a session id, or a currently-active adapter session). Unparseable dir
+ * names are skipped, never swept. Returns the number of dirs removed. Runs at
+ * boot + the daily file sweep.
+ */
+export declare function sweepOrphanJsonStreamDirs(jsonStreamRoot: string, checkIsThreadOwned: (key: SessionKey) => boolean): Promise<number>;
+//# sourceMappingURL=jsonStreamHost.d.ts.map

package/dist/utils/jsonStreamHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonStreamHost.d.ts","sourceRoot":"","sources":["../../src/utils/jsonStreamHost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAA6B,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAKrD,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAElD;;oCAEoC;AACpC,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C;8EAC8E;AAC9E,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,OAAO,CAAC;AACzC,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;qEAGqE;AACrE,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;6EAC6E;AAC7E,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC;qEACqE;AACrE,eAAO,MAAM,uBAAuB,QAAoB,CAAC;AAEzD,gFAAgF;AAChF,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,yEAAyE;AACzE,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,sEAAsE;AACtE,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE7D;AAcD,0DAA0D;AAC1D,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,CAEpF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAEtE;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,sBAAsB,CAW7E;AAED,gFAAgF;AAChF,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAEtE;AAED,mFAAmF;AACnF,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAE9E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,sBAAsB,EAC7B,WAAW,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAW,EAC3D,SAAS,GAAE,MAAM,GAAG,IAAW,GAC9B,MAAM,CAeR;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM7E;AAED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAyB,GAClC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAUxB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAa3E;AAaD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE1D;AAED,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEpE;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOpD;AAED;6EAC6E;AAC7E,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,MAA6B,GACvC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQxB;AAED;0EAC0E;AAC1E,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,GAAE,MAA2B,GAAG,MAAM,CAOhG;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAED;+EAC+E;AAC/E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAUlG;AAED;+DAC+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,oBAAoB,GAAG,IAAI,EAC1C,eAAe,EAAE,MAAM,EACvB,eAAe,EAAE,MAAM,GACtB,gBAAgB,CAWlB;AAMD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,eAAe,CAE/E;AAED,kEAAkE;AAClE,MAAM,MAAM,kBAAkB;AAC5B,mBAAmB;AACjB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;AAClB,8EAA8E;GAC5E;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE;AAC1D;;;kBAGkB;GAChB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEvB;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,kBAAkB,CASnG;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMnF;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAEnG;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,cAAc,EAAE,MAAM,EACtB,kBAAkB,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,GAC/C,OAAO,CAAC,MAAM,CAAC,CAuBjB"}