@fnclaude/cli 0.7.7 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Butler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fnclaude/cli",
-  "version": "0.7.7",
+  "version": "1.0.0",
   "description": "fnclaude CLI implementation (TypeScript rewrite, in progress)",
   "license": "MIT",
   "repository": {

package/src/config.ts

@@ -9,6 +9,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { errorMessage } from './errors.js';
 
 /**
  * Resolve the user's home directory. Honors `$HOME` first (matches Go's
@@ -136,7 +137,7 @@ export function parseBoolEnv(v: string): boolean {
  */
 export interface NormalizeResult<T> {
   value: T;
-  warning: string | null;
+  warning: string | undefined;
 }
 
 /**
@@ -146,8 +147,8 @@ export interface NormalizeResult<T> {
  * absent-value default path and produces no warning).
  */
 export function normalizeTmuxMode(v: string): NormalizeResult<TmuxMode> {
-  if (v === 'never' || v === 'worktree') return { value: v, warning: null };
-  if (v === '') return { value: 'never', warning: null };
+  if (v === 'never' || v === 'worktree') return { value: v, warning: undefined };
+  if (v === '') return { value: 'never', warning: undefined };
   return {
     value: 'never',
     warning: `fnclaude: auto.tmux=${JSON.stringify(v)} is not a valid mode (use "never" or "worktree"), falling back to "never"`,
@@ -160,12 +161,12 @@ export function normalizeTmuxMode(v: string): NormalizeResult<TmuxMode> {
  * string). Valid: "never", "ask", or a non-negative integer (as a string).
  */
 export function normalizeHandoffMode(v: string): NormalizeResult<HandoffMode> {
-  if (v === 'never' || v === 'ask') return { value: v, warning: null };
-  if (v === '') return { value: 'ask', warning: null };
+  if (v === 'never' || v === 'ask') return { value: v, warning: undefined };
+  if (v === '') return { value: 'ask', warning: undefined };
   // Non-negative integer (no decimal, no unit). The regex guarantees the
   // template-literal shape, which TS's type narrowing can't infer from a
   // .test() call alone — so assert it explicitly once.
-  if (/^\d+$/.test(v)) return { value: v as `${number}`, warning: null };
+  if (/^\d+$/.test(v)) return { value: v as `${number}`, warning: undefined };
   return {
     value: 'ask',
     warning: `fnclaude: auto.handoff=${JSON.stringify(v)} is not a valid mode (use "never", "ask", or a non-negative integer), falling back to "ask"`,
@@ -174,12 +175,12 @@ export function normalizeHandoffMode(v: string): NormalizeResult<HandoffMode> {
 
 /**
  * parseDuration accepts a Go-style duration string (e.g., "3s", "150ms",
- * "1m30s") and returns the equivalent in milliseconds. Returns null on
- * parse failure. This is the same surface as Go's time.ParseDuration for
- * the config use-case (we don't need ns/us precision).
+ * "1m30s") and returns the equivalent in milliseconds. Returns undefined
+ * on parse failure. This is the same surface as Go's time.ParseDuration
+ * for the config use-case (we don't need ns/us precision).
  */
-export function parseDuration(s: string): number | null {
-  if (!s) return null;
+export function parseDuration(s: string): number | undefined {
+  if (!s) return undefined;
   // Whole number with unit suffix(es).
   // Units: ns, us, µs, ms, s, m, h. (We support all common units.)
   const unitToMs: Record<string, number> = {
@@ -195,17 +196,19 @@ export function parseDuration(s: string): number | null {
   let total = 0;
   let matched = 0;
   let consumed = 0;
+  // RegExp.exec returns null for "no match" — third-party API shape, kept
+  // as null rather than coerced.
   let m: RegExpExecArray | null;
   while ((m = re.exec(s)) !== null) {
-    if (m.index !== consumed) return null; // gap between matches
+    if (m.index !== consumed) return undefined; // gap between matches
     const num = parseFloat(m[1] as string);
     const unit = m[2] as string;
-    if (!Number.isFinite(num) || num < 0) return null;
+    if (!Number.isFinite(num) || num < 0) return undefined;
     total += num * (unitToMs[unit] as number);
     consumed = m.index + m[0].length;
     matched++;
   }
-  if (matched === 0 || consumed !== s.length) return null;
+  if (matched === 0 || consumed !== s.length) return undefined;
   return total;
 }
 
@@ -262,25 +265,25 @@ export function loadConfig(): LoadConfigResult {
     set: (v: T) => void,
   ): void => {
     set(r.value);
-    if (r.warning !== null) warnings.push(r.warning);
+    if (r.warning !== undefined) warnings.push(r.warning);
   };
 
   if (existsSync(path)) {
-    let raw: RawConfig | null = null;
+    let raw: RawConfig | undefined;
     try {
       const body = readFileSync(path, 'utf8');
       raw = Bun.TOML.parse(body) as RawConfig;
     } catch (err) {
       warnings.push(
-        `fnclaude: config file ${path} is malformed, using defaults: ${(err as Error).message}`,
+        `fnclaude: config file ${path} is malformed, using defaults: ${errorMessage(err)}`,
       );
-      raw = null;
+      raw = undefined;
     }
     if (raw) {
       if (raw.name?.model) cfg.name.model = raw.name.model;
       if (raw.name?.timeout) {
         const d = parseDuration(raw.name.timeout);
-        if (d !== null) {
+        if (d !== undefined) {
           cfg.name.timeout = d;
         } else {
           warnings.push(
@@ -318,7 +321,7 @@ export function loadConfig(): LoadConfigResult {
   if (e.FNCLAUDE_NAME_MODEL) cfg.name.model = e.FNCLAUDE_NAME_MODEL;
   if (e.FNCLAUDE_NAME_TIMEOUT) {
     const d = parseDuration(e.FNCLAUDE_NAME_TIMEOUT);
-    if (d !== null) {
+    if (d !== undefined) {
       cfg.name.timeout = d;
     } else {
       warnings.push(

package/src/errors.ts

@@ -0,0 +1,13 @@
+// Error-handling helpers shared across the CLI.
+//
+// `errorMessage` collapses the "throw value can be anything" branch into a
+// single safe path: real Errors yield their `.message`, anything else gets
+// stringified. Used at every catch-and-format site that previously did
+// `(err as Error).message` — a cast that silently produces `undefined` (and
+// then crashes the error-handling path itself) whenever the thrown value
+// isn't actually an Error instance.
+
+export function errorMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}

package/src/main.ts

@@ -50,6 +50,7 @@ import { seedNoop } from './noop.js';
 import { silentRelaunch, silentRelaunchHandoff } from './silentRelaunch.js';
 import { applyWorktreeIntercept, type GitRunner } from './worktree.js';
 import { flushWarnings } from './warnings.js';
+import { errorMessage } from './errors.js';
 
 /**
  * `RunIO` — process-shaped seams. Streams, paths, the launch environment,
@@ -77,8 +78,8 @@ export interface RunIO {
   /** Shell cwd at startup. */
   cwd?: string;
 
-  /** PATH lookup for the claude binary; returns null when not found. */
-  lookupClaude?: (name: string) => string | null;
+  /** PATH lookup for the claude binary; returns undefined when not found. */
+  lookupClaude?: (name: string) => string | undefined;
   /** Override the run-with-pty step. */
   runWithPTY?: typeof runWithPTY;
   /** Override the silent-relaunch step (cross-cwd resume). */
@@ -144,18 +145,19 @@ export interface RunDeps {
   data?: RunConfig;
 }
 
-function lookupClaudeFromPath(name: string): string | null {
-  // Bun's PATH lookup: Bun.which() returns null when not found.
-  // Falls back to a synchronous probe via process.env.PATH if needed.
+function lookupClaudeFromPath(name: string): string | undefined {
+  // Bun's PATH lookup: Bun.which() returns null when not found. Coerce to
+  // undefined to keep the absent-value sentinel consistent with the rest of
+  // the codebase.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const bunWhich = (globalThis as any).Bun?.which;
   if (typeof bunWhich === 'function') {
-    return bunWhich(name);
+    return bunWhich(name) ?? undefined;
   }
   // Fallback: walk PATH ourselves. Avoid `which` shell-out — synchronous and
   // brittle. Use spawnSync('which', [name]) only if Bun.which is unavailable
   // and we're not on Windows.
-  return null;
+  return undefined;
 }
 
 /**
@@ -232,7 +234,7 @@ export async function run(deps: RunDeps = {}): Promise<number> {
     try {
       parsed = parseArgs(argv, home);
     } catch (err) {
-      stderr.write(`${(err as Error).message}\n`);
+      stderr.write(`${errorMessage(err)}\n`);
       return 1;
     }
 
@@ -241,7 +243,7 @@ export async function run(deps: RunDeps = {}): Promise<number> {
       try {
         await seedNoopFn(parsed.cwd);
       } catch (err) {
-        warnings.push(`fnclaude: noop seed failed: ${(err as Error).message}`);
+        warnings.push(`fnclaude: noop seed failed: ${errorMessage(err)}`);
       }
     }
 
@@ -309,14 +311,13 @@ export async function run(deps: RunDeps = {}): Promise<number> {
               hostAliases: aliases,
             }));
       } catch (err) {
-        stderr.write(`${(err as Error).message}\n`);
+        stderr.write(`${errorMessage(err)}\n`);
         return 1;
       }
       // If the user's reference had a +workspace suffix AND they didn't
       // pass -w explicitly, propagate the workspace to the intercept
       // layer.
-      const promoteWorkspace =
-        result.workspace !== undefined && result.workspace !== '' && !parsed.worktreeSet;
+      const promoteWorkspace = !!result.workspace && !parsed.worktreeSet;
       resolved = withResolved(parsed, {
         cwd: result.path,
         ...(promoteWorkspace
@@ -351,9 +352,9 @@ export async function run(deps: RunDeps = {}): Promise<number> {
     if (shouldAutoName(named.passthrough)) {
       const prompt = extractPrompt(named.passthrough);
       const apiKey = process.env.ANTHROPIC_API_KEY ?? '';
-      let llmFn: LlmClientFn | undefined;
-      if (apiKey !== '') llmFn = defaultLlmClient(apiKey);
-      else llmFn = claudeCliFn(cfg.name.model);
+      const llmFn: LlmClientFn = apiKey
+        ? defaultLlmClient(apiKey)
+        : claudeCliFn(cfg.name.model);
       const name = await generateNameFn(prompt, cfg.name, apiKey, llmFn);
       named = withPassthroughUpdate(named, {
         passthrough: ['--name', name, ...named.passthrough],
@@ -380,7 +381,7 @@ export async function run(deps: RunDeps = {}): Promise<number> {
     const claudeArgv = buildArgv(sanitized, shellCWD, cfg, prompts);
 
     // ── Verify claude is on PATH before starting the PTY. ────────────────
-    if (lookupClaude('claude') === null) {
+    if (lookupClaude('claude') === undefined) {
       stderr.write(`fnclaude: claude not found in PATH\n`);
       return 1;
     }
@@ -400,7 +401,7 @@ export async function run(deps: RunDeps = {}): Promise<number> {
     });
 
     // ── Auto-handoff fires first. ────────────────────────────────────────
-    if (handoffArgv !== null && handoffArgv.length > 0) {
+    if (handoffArgv !== undefined && handoffArgv.length > 0) {
       // Flush deferred warnings before relaunch since execve replaces the
       // process image (the deferred flush below would be skipped).
       flushOnce();
@@ -410,9 +411,9 @@ export async function run(deps: RunDeps = {}): Promise<number> {
     }
 
     // ── Cross-cwd redirect detection. ────────────────────────────────────
-    if (tail !== null) {
+    if (tail !== undefined) {
       const hit = detectCrossCwd(tail);
-      if (hit !== null) {
+      if (hit !== undefined) {
         flushOnce();
         relaunch(argv, hit.dest, hit.uuid);
         // Same fallthrough as above.
@@ -434,7 +435,7 @@ export async function main(): Promise<void> {
   try {
     code = await run();
   } catch (err) {
-    process.stderr.write(`fnclaude: fatal: ${(err as Error).message}\n`);
+    process.stderr.write(`fnclaude: fatal: ${errorMessage(err)}\n`);
     code = 1;
   }
   process.exit(code);

package/src/mcp/client.ts

@@ -12,6 +12,7 @@
 import { Buffer } from 'node:buffer';
 import { connect, type Socket } from 'node:net';
 import type { Readable, Writable } from 'node:stream';
+import { errorMessage } from '../errors.js';
 import {
   encodeRequest,
   readResponse,
@@ -114,7 +115,7 @@ export const defaultDial: DialFn = async (socketPath, req) => {
 
   // Attach an error catcher up front so an early ECONNREFUSED doesn't
   // crash the process via 'error' before we await.
-  let earlyErr: Error | null = null;
+  let earlyErr: Error | undefined;
   sock.on('error', (e) => {
     if (!earlyErr) earlyErr = e;
   });
@@ -146,7 +147,7 @@ export const defaultDial: DialFn = async (socketPath, req) => {
 
     sock.write(encodeRequest(req));
     const resp = await readResponse(sock);
-    if (resp === null) {
+    if (resp === undefined) {
       throw new Error('read response: EOF before any line');
     }
     return resp;
@@ -189,7 +190,7 @@ const toolRestart: MCPTool = {
 const toolSwitchProject: MCPTool = {
   name: 'fnc_switch_project',
   description:
-    'Switch this fnclaude session to a different project, carrying a continuity summary. ONE-SHOT: call once and the session is killed and re-launched at the destination. Because the call ends this session, print a brief cancellation-window line to the user (e.g. "Transferring in 3 seconds. Ctrl-C to cancel.") and run a Bash sleep BEFORE calling this tool; if the sleep completes uninterrupted, call once. fnclaude preserves the user\'s startup flags (minus a denylist of destination-bound ones like --add-dir, --mcp-config, --from-pr, --name, etc.); the optional override args below replace individual flags. Args: destination (verbatim user reference: a short repo name like \'arch-setup\', a name@owner like \'arch-setup@fnrhombus\', an owner/name like \'fnrhombus/arch-setup\', a URL, or an absolute path; a +workspace suffix is supported for worktrees), name (a 3-6 word kebab-case session topic, e.g. \'fix-auth-bug\'), summary (a /compact-style continuity summary that lets the receiving session pick up where this one left off — what the user asked for, decisions made, files touched, work in flight, open questions, user-specific observations), session_id (the current session UUID, read from $CLAUDE_CODE_SESSION_ID; used by fnclaude to auto-capture the live permission-mode from this session\'s JSONL log). Optional overrides: model, effort, permission_mode, allowed_tools, agent, brief, chrome, ide, verbose. Response.action will be done (transfer in flight), paste_flow (auto-handoff disabled — copy/paste the rendered command), or error.',
+    'Switch this fnclaude session to a different project, carrying a continuity summary. Call as early in the turn as you recognize the user\'s intent belongs in another project — don\'t read/grep/test in this session as a pre-step, the destination session will do that with fresh context. Pre-investigating here wastes parent tokens and degrades the destination\'s research independence. ONE-SHOT: call once and the session is killed and re-launched at the destination. Because the call ends this session, print a brief cancellation-window line to the user (e.g. "Transferring in 3 seconds. Ctrl-C to cancel.") and run a Bash sleep BEFORE calling this tool; if the sleep completes uninterrupted, call once. fnclaude preserves the user\'s startup flags (minus a denylist of destination-bound ones like --add-dir, --mcp-config, --from-pr, --name, etc.); the optional override args below replace individual flags. Args: destination (verbatim user reference: a short repo name like \'arch-setup\', a name@owner like \'arch-setup@fnrhombus\', an owner/name like \'fnrhombus/arch-setup\', a URL, or an absolute path; a +workspace suffix is supported for worktrees), name (a 3-6 word kebab-case session topic, e.g. \'fix-auth-bug\'), summary (a /compact-style continuity summary that lets the receiving session pick up where this one left off — what the user asked for, decisions made, files touched, work in flight, open questions, user-specific observations), session_id (the current session UUID, read from $CLAUDE_CODE_SESSION_ID; used by fnclaude to auto-capture the live permission-mode from this session\'s JSONL log). Optional overrides: model, effort, permission_mode, allowed_tools, agent, brief, chrome, ide, verbose. Response.action will be done (transfer in flight), paste_flow (auto-handoff disabled — copy/paste the rendered command), or error.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -214,7 +215,7 @@ const toolSwitchProject: MCPTool = {
 const toolSpawnSession: MCPTool = {
   name: 'fnc_spawn_session',
   description:
-    "Spawn a sibling fnclaude session for a different project in a new terminal window, while leaving the CURRENT session running. Use when, in the middle of a task here, the user discovers an unrelated task in another project but doesn't want to abandon what's happening in this session. (Use fnc_switch_project instead when the current session should be replaced.) ONE-SHOT: call once; no countdown or cancellation window is needed — the current session keeps running regardless. Spawn is a fresh start — it does NOT preserve this session's startup flags; pass the optional override args when the user wants the sibling to start with explicit tooling choices. Args: destination (verbatim user reference: short repo name, name@owner, owner/name, URL, or absolute path; +workspace suffix supported), name (3-6 word kebab-case session topic for the new session, e.g. 'fix-css-bug'), summary (a /compact-style continuity summary for the new session — what the user wants done in that other project, with enough context to start cold). Optional overrides (applied to the sibling, not this session): model, effort, permission_mode, allowed_tools, agent, brief, chrome, ide, verbose. Response.action will be done (sibling launched), paste_flow (no launcher available — copy/paste the rendered command into a new terminal), or error.",
+    "Spawn a sibling fnclaude session for a different project in a new terminal window, while leaving the CURRENT session running. Use when, in the middle of a task here, the user discovers an unrelated task in another project but doesn't want to abandon what's happening in this session. (Use fnc_switch_project instead when the current session should be replaced.) Call as early in the turn as you recognize the work belongs in another project — don't read/grep/test in this session as a pre-step, the sibling will do that with fresh context. Pre-investigating here wastes parent tokens and degrades the sibling's research independence. ONE-SHOT: call once; no countdown or cancellation window is needed — the current session keeps running regardless. Spawn is a fresh start — it does NOT preserve this session's startup flags; pass the optional override args when the user wants the sibling to start with explicit tooling choices. Args: destination (verbatim user reference: short repo name, name@owner, owner/name, URL, or absolute path; +workspace suffix supported), name (3-6 word kebab-case session topic for the new session, e.g. 'fix-css-bug'), summary (a /compact-style continuity summary for the new session — what the user wants done in that other project, with enough context to start cold). Optional overrides (applied to the sibling, not this session): model, effort, permission_mode, allowed_tools, agent, brief, chrome, ide, verbose. Response.action will be done (sibling launched), paste_flow (no launcher available — copy/paste the rendered command into a new terminal), or error.",
   inputSchema: {
     type: 'object',
     properties: {
@@ -274,15 +275,14 @@ export async function runMCPServer(opts: MCPServerOptions): Promise<number> {
   // eslint-disable-next-line no-constant-condition
   while (true) {
     const line = await reader.readLine();
-    if (line === null) return 0; // clean EOF
+    if (line === undefined) return 0; // clean EOF
     try {
       await handleLine(opts, dial, line);
     } catch (err) {
       // Sending an error response is the right behavior; abort the loop
       // only if the write itself fails.
       try {
-        const msg = (err as Error).message;
-        sendError(opts.stdout, null, CODE_PARSE_ERROR, `parse error: ${msg}`);
+        sendError(opts.stdout, null, CODE_PARSE_ERROR, `parse error: ${errorMessage(err)}`);
       } catch {
         return 1;
       }
@@ -299,7 +299,7 @@ async function handleLine(
   try {
     req = JSON.parse(line) as JSONRPCRequest;
   } catch (err) {
-    sendError(opts.stdout, null, CODE_PARSE_ERROR, `parse error: ${(err as Error).message}`);
+    sendError(opts.stdout, null, CODE_PARSE_ERROR, `parse error: ${errorMessage(err)}`);
     return;
   }
 
@@ -348,7 +348,7 @@ async function handleToolsCall(
   try {
     params = (req.params ?? {}) as MCPCallToolParams;
   } catch (err) {
-    sendError(opts.stdout, req.id, CODE_INVALID_PARAMS, `invalid params: ${(err as Error).message}`);
+    sendError(opts.stdout, req.id, CODE_INVALID_PARAMS, `invalid params: ${errorMessage(err)}`);
     return;
   }
 
@@ -402,12 +402,12 @@ async function callRestart(
   id: unknown,
   args: Record<string, unknown>,
 ): Promise<void> {
-  if (opts.socketPath === '') {
+  if (!opts.socketPath) {
     sendToolError(opts.stdout, id, SOCKET_UNAVAILABLE_MSG);
     return;
   }
   const sid = readStringArg(args, 'session_id');
-  if (sid === '') {
+  if (!sid) {
     sendToolError(
       opts.stdout,
       id,
@@ -445,7 +445,7 @@ async function callSwitch(
   id: unknown,
   args: Record<string, unknown>,
 ): Promise<void> {
-  if (opts.socketPath === '') {
+  if (!opts.socketPath) {
     sendToolError(opts.stdout, id, SOCKET_UNAVAILABLE_MSG);
     return;
   }
@@ -475,7 +475,7 @@ async function callSpawn(
   id: unknown,
   args: Record<string, unknown>,
 ): Promise<void> {
-  if (opts.socketPath === '') {
+  if (!opts.socketPath) {
     sendToolError(opts.stdout, id, SOCKET_UNAVAILABLE_MSG);
     return;
   }
@@ -504,7 +504,7 @@ async function callCopy(
   id: unknown,
   args: Record<string, unknown>,
 ): Promise<void> {
-  if (opts.socketPath === '') {
+  if (!opts.socketPath) {
     sendToolError(opts.stdout, id, SOCKET_UNAVAILABLE_MSG);
     return;
   }
@@ -525,7 +525,7 @@ async function dialAndRelay(
   try {
     resp = await dial(opts.socketPath, req);
   } catch (err) {
-    sendToolError(opts.stdout, id, (err as Error).message);
+    sendToolError(opts.stdout, id, errorMessage(err));
     return;
   }
   sendToolResult(opts.stdout, id, resp);
@@ -573,7 +573,7 @@ function sendToolResult(stdout: Writable, id: unknown, resp: Response): void {
   try {
     text = JSON.stringify(resp);
   } catch (err) {
-    sendToolError(stdout, id, `internal marshal error: ${(err as Error).message}`);
+    sendToolError(stdout, id, `internal marshal error: ${errorMessage(err)}`);
     return;
   }
   sendResult(stdout, id, {
@@ -595,7 +595,7 @@ function writeResponse(stdout: Writable, resp: JSONRPCResponse): void {
 class LineReader {
   private buf: Buffer = Buffer.alloc(0);
   private ended = false;
-  private pending: ((line: string | null) => void) | null = null;
+  private pending: ((line: string | undefined) => void) | undefined;
 
   constructor(private readonly stream: Readable) {
     stream.on('data', (chunk: Buffer) => {
@@ -612,8 +612,8 @@ class LineReader {
     });
   }
 
-  readLine(): Promise<string | null> {
-    return new Promise<string | null>((resolve) => {
+  readLine(): Promise<string | undefined> {
+    return new Promise<string | undefined>((resolve) => {
       this.pending = resolve;
       this.tryDeliver();
     });
@@ -626,15 +626,15 @@ class LineReader {
       const line = this.buf.subarray(0, nl + 1).toString('utf8');
       this.buf = this.buf.subarray(nl + 1);
       const cb = this.pending;
-      this.pending = null;
+      this.pending = undefined;
       cb(line);
       return;
     }
     if (this.ended) {
       const cb = this.pending;
-      this.pending = null;
+      this.pending = undefined;
       if (this.buf.length === 0) {
-        cb(null);
+        cb(undefined);
       } else {
         const tail = this.buf.toString('utf8');
         this.buf = Buffer.alloc(0);

package/src/mcp/protocol.ts

@@ -370,9 +370,9 @@ export interface DataStream {
 
 /**
  * Read one newline-terminated JSON line from a data-emitting stream (a
- * `net.Socket` is the common case). Returns the decoded Request or null
- * if the stream ended cleanly before any line was seen (analogous to
- * Go's `io.EOF` return).
+ * `net.Socket` is the common case). Returns the decoded Request or
+ * undefined if the stream ended cleanly before any line was seen
+ * (analogous to Go's `io.EOF` return).
  *
  * Buffers across chunk boundaries. Stops at the first '\n'; bytes past
  * it are silently dropped (the wire protocol is one-line-per-connection).
@@ -382,22 +382,22 @@ export interface DataStream {
  * which would prevent the caller from writing the response back. The
  * event-listener form leaves the socket fully writable.
  */
-export async function readRequest(stream: DataStream): Promise<Request | null> {
+export async function readRequest(stream: DataStream): Promise<Request | undefined> {
   const line = await readLine(stream);
-  if (line === null) return null;
+  if (line === undefined) return undefined;
   return decodeRequest(line);
 }
 
 /** Read one newline-terminated JSON line and decode it as a Response. */
-export async function readResponse(stream: DataStream): Promise<Response | null> {
+export async function readResponse(stream: DataStream): Promise<Response | undefined> {
   const line = await readLine(stream);
-  if (line === null) return null;
+  if (line === undefined) return undefined;
   return decodeResponse(line);
 }
 
 /** Internal — read up to and including the first '\n' via stream events. */
-async function readLine(stream: DataStream): Promise<string | null> {
-  return new Promise<string | null>((resolve, reject) => {
+async function readLine(stream: DataStream): Promise<string | undefined> {
+  return new Promise<string | undefined>((resolve, reject) => {
     const chunks: Buffer[] = [];
     let total = 0;
     let settled = false;
@@ -408,7 +408,7 @@ async function readLine(stream: DataStream): Promise<string | null> {
       stream.off('close', onEnd);
       stream.off('error', onError);
     };
-    const settle = (value: string | null, err?: Error): void => {
+    const settle = (value: string | undefined, err?: Error): void => {
       if (settled) return;
       settled = true;
       cleanup();
@@ -430,12 +430,12 @@ async function readLine(stream: DataStream): Promise<string | null> {
     };
     const onEnd = (): void => {
       if (total === 0) {
-        settle(null);
+        settle(undefined);
         return;
       }
       settle(Buffer.concat(chunks).toString('utf8'));
     };
-    const onError = (err: Error): void => settle(null, err);
+    const onError = (err: Error): void => settle(undefined, err);
 
     stream.on('data', onData);
     stream.on('end', onEnd);