@cjhyy/code-shell-core 0.5.0-rc.1 → 0.5.0-rc.2

package/dist/protocol/redact.js

@@ -0,0 +1,71 @@
+import { redactSecrets } from "../logging/sanitize-messages.js";
+/**
+ * Redaction helpers for protocol query responses.
+ *
+ * The protocol exposes config snapshots to any connected client. Raw API keys,
+ * provider credentials, and authorization headers must never leave this
+ * boundary verbatim — the client can use derived fields (`hasApiKey`,
+ * `apiKeyPreview`) to render provider/model status without holding the secret.
+ *
+ * Two entry points:
+ *   - redactConfigForResponse: rewrites the LLM section of the config-query
+ *     payload, removing `apiKey` and adding derived presence/preview fields.
+ *   - maskSecretValue: scrubs a single (key, value) pair returned by
+ *     config_get, where the client picks the key — including `llm.apiKey`.
+ */
+/** Match dotted/camel/snake variants of obviously secret keys. */
+const SECRET_KEY_RE = /(^|[._-])(api[_-]?key|authorization|x[_-]api[_-]key|bearer[_-]?token|access[_-]?token|refresh[_-]?token|secret|password|client[_-]?secret)($|[._-])/i;
+/** Produce a short preview (`sk-…abcd`) so UIs can render presence without revealing the secret. */
+export function makeApiKeyPreview(apiKey) {
+    if (typeof apiKey !== "string" || apiKey.length === 0)
+        return undefined;
+    if (apiKey.length <= 8)
+        return "…";
+    return `${apiKey.slice(0, 3)}…${apiKey.slice(-4)}`;
+}
+/**
+ * Return true when a dotted setting key path points at a secret field.
+ * Used to decide whether `config_get`'s response should redact the value.
+ */
+export function isSecretKeyPath(key) {
+    return SECRET_KEY_RE.test(key);
+}
+/**
+ * Redact a single value returned by config_get.
+ *
+ * Two-stage rule:
+ *   1. If the caller-supplied key path itself looks secret
+ *      ("llm.apiKey", "headers.authorization", …) → collapse to "[redacted]".
+ *   2. Otherwise, if the value is an object/array (e.g. config_get("llm") or
+ *      config_get("providers")), walk it with the shared secret redactor
+ *      from logging/sanitize-messages so nested apiKey / token / Bearer
+ *      fields don't slip through verbatim. Primitives pass unchanged.
+ *
+ * Pre-fix this only inspected the top-level key string, so
+ * config_get("providers") returned an array of provider objects with raw
+ * apiKey values intact. That defeated the purpose of the boundary.
+ */
+export function maskSecretValue(key, value) {
+    if (isSecretKeyPath(key))
+        return "[redacted]";
+    if (value && typeof value === "object") {
+        return redactSecrets(value);
+    }
+    return value;
+}
+/**
+ * Rewrite the LLM section of a config snapshot for transport. We only forward
+ * fields the client legitimately needs to render status; secrets become
+ * derived flags.
+ */
+export function redactLlmConfig(llm) {
+    const preview = makeApiKeyPreview(llm.apiKey);
+    return {
+        provider: llm.provider,
+        model: llm.model,
+        baseUrl: llm.baseUrl,
+        maxTokens: llm.maxTokens,
+        hasApiKey: typeof llm.apiKey === "string" && llm.apiKey.length > 0,
+        ...(preview ? { apiKeyPreview: preview } : {}),
+    };
+}

package/dist/protocol/server.d.ts

@@ -15,6 +15,7 @@
  */
 import type { Transport } from "./transport.js";
 import type { Engine } from "../engine/engine.js";
+import type { ValidatedSettings } from "../settings/schema.js";
 import type { ChatSessionManager } from "./chat-session-manager.js";
 export interface AgentServerOptions {
     /**
@@ -29,11 +30,38 @@ export interface AgentServerOptions {
      */
     engine?: Engine;
     transport: Transport;
+    /**
+     * Reads fresh settings from disk for config hot-reload (layer 2). MUST be
+     * the SAME closure the engineFactory uses for new sessions (e.g.
+     * agent-server-stdio's `freshSettings`) so a reloaded running session and a
+     * newly-created session converge on identical disk config — no divergence.
+     * When absent, `configure({ reloadSettings })` returns an explicit error.
+     */
+    settingsReader?: () => ValidatedSettings;
 }
 export declare class AgentServer {
     private readonly chatManager;
     private readonly legacyEngine;
+    private globalQueryEngine;
     private transport;
+    /** Fresh-disk settings reader for config hot-reload; null when not wired. */
+    private readonly settingsReader;
+    /**
+     * Monotonic config-reload version, bumped per reloadSettings request so each
+     * Engine.refreshRuntimeConfig can drop out-of-order (stale) deliveries (Q5).
+     */
+    private configVersion;
+    /**
+     * JSON of the last disk-default patch broadcast to ALL live sessions (#6).
+     * When a new reloadSettings request produces a byte-identical patch we SKIP
+     * the entire forEachSession broadcast — every session's refreshRuntimeConfig
+     * would otherwise unconditionally reloadHooks() (invalidate + full disk
+     * re-read + hook teardown/re-register) per call, and the personalization UI
+     * auto-saves on a 600ms debounce, so identical re-saves caused K× hook churn
+     * per keystroke-pause. A genuine change still differs in JSON → propagates.
+     * null until the first broadcast.
+     */
+    private lastBroadcastPatch;
     private running;
     private abortController;
     /** Pending approval requests: requestId → resolve function (legacy path) */
@@ -67,11 +95,22 @@ export declare class AgentServer {
     /**
      * Ask the client to answer a question from the agent (legacy single-engine path).
      */
+    /**
+     * Per-session AskUserQuestion for the chatManager path. Mirrors
+     * requestAskUserFromClient but resolves via the SESSION's pendingApprovals
+     * (the chatManager approve handler looks there, keyed by sessionId+requestId)
+     * and tags the notify with sessionId so the renderer routes the question to
+     * the right chat tab.
+     */
+    private requestAskUserForSession;
     private requestAskUserFromClient;
     private notify;
     /**
-     * Get any available engine — used for global query ops when chatManager is
-     * present but no legacyEngine was supplied. Borrows the first live session.
+     * Get any available engine — used for global query/configure ops when
+     * chatManager is present but no legacyEngine was supplied. Prefer a live chat
+     * session; before the first user turn, lazily build a detached engine through
+     * the manager's factory so global UI surfaces (/login, model manager, model
+     * selector) can query models/providers without requiring a chat session first.
      */
     private anyEngine;
     close(): void;

package/dist/protocol/server.js

@@ -14,14 +14,36 @@
  * falls back to borrowing any live session's engine for those reads.
  */
 import { Methods, ErrorCodes, createResponse, createErrorResponse, createNotification, isRequest, } from "./types.js";
+import { diskDefaultsFrom } from "../engine/engine.js";
 import { setInteractiveApprovalFn } from "../tool-system/permission.js";
 import { getArenaStatus } from "../tool-system/builtin/arena.js";
 import { agentNotificationBus } from "../tool-system/builtin/agent-notifications.js";
 import { nanoid } from "nanoid";
+import { redactLlmConfig, maskSecretValue } from "./redact.js";
+import { redactSecrets } from "../logging/sanitize-messages.js";
 export class AgentServer {
     chatManager;
     legacyEngine;
+    globalQueryEngine = null;
     transport;
+    /** Fresh-disk settings reader for config hot-reload; null when not wired. */
+    settingsReader;
+    /**
+     * Monotonic config-reload version, bumped per reloadSettings request so each
+     * Engine.refreshRuntimeConfig can drop out-of-order (stale) deliveries (Q5).
+     */
+    configVersion = 0;
+    /**
+     * JSON of the last disk-default patch broadcast to ALL live sessions (#6).
+     * When a new reloadSettings request produces a byte-identical patch we SKIP
+     * the entire forEachSession broadcast — every session's refreshRuntimeConfig
+     * would otherwise unconditionally reloadHooks() (invalidate + full disk
+     * re-read + hook teardown/re-register) per call, and the personalization UI
+     * auto-saves on a 600ms debounce, so identical re-saves caused K× hook churn
+     * per keystroke-pause. A genuine change still differs in JSON → propagates.
+     * null until the first broadcast.
+     */
+    lastBroadcastPatch = null;
     // ── Legacy single-engine state (used when chatManager is null) ──
     running = false;
     abortController = null;
@@ -41,6 +63,7 @@ export class AgentServer {
     constructor(options) {
         this.chatManager = options.chatManager ?? null;
         this.legacyEngine = options.engine ?? null;
+        this.settingsReader = options.settingsReader ?? null;
         if (!this.chatManager && !this.legacyEngine) {
             throw new Error("AgentServer: either chatManager or engine must be supplied");
         }
@@ -53,16 +76,19 @@ export class AgentServer {
                 });
             }
         });
-        // Wire approval flow for the legacy single-engine path.
-        // In the chatManager path approval flows are per-session and registered
-        // when the session's engine raises an approval request via onStream.
+        setInteractiveApprovalFn((request) => {
+            return this.requestApprovalFromClient(request);
+        });
         if (this.legacyEngine) {
-            setInteractiveApprovalFn((request) => {
-                return this.requestApprovalFromClient(request);
-            });
-            this.legacyEngine.setAskUser((question, opts) => {
-                return this.requestAskUserFromClient(question, opts);
-            });
+            // Only wire an interactive askUser when a human is present. For
+            // unattended (headless) runs we leave askUser undefined so
+            // AskUserQuestion hits its headless-error branch and returns immediately
+            // instead of suspending until the tool-exec timeout (~300s).
+            if (!this.legacyEngine.isHeadless()) {
+                this.legacyEngine.setAskUser((question, opts) => {
+                    return this.requestAskUserFromClient(question, opts);
+                });
+            }
         }
         // B2.2 — forward background sub-agent completion events through the
         // protocol so Desktop / SDK / remote AgentClients see them too. The
@@ -140,9 +166,24 @@ export class AgentServer {
             session.engine.setPlanMode(params.planMode);
         }
         const sid = params.sessionId;
+        // Wire AskUserQuestion for this interactive session. The chatManager path
+        // builds a fresh per-session Engine via engineFactory, which (unlike the
+        // legacy single-engine path) never had askUser wired — so AskUserQuestion
+        // always fell into its "not available in headless mode" branch in normal
+        // chat (and in a resumed automation session). Route it to the client with
+        // this session's id so the renderer attributes the question to the right
+        // tab, resolving via the session's own pendingApprovals. Skip genuinely
+        // headless engines (no human to answer).
+        if (!session.engine.isHeadless()) {
+            session.engine.setAskUser((question, opts) => this.requestAskUserForSession(session, sid, question, opts));
+        }
         try {
             const result = await session.enqueueTurn(params.task, {
                 cwd: params.cwd,
+                goal: typeof params.goal === "string" ||
+                    (params.goal != null && typeof params.goal === "object")
+                    ? params.goal
+                    : undefined,
                 onStream: (event) => this.notify(Methods.StreamEvent, { sessionId: sid, event }),
             });
             const runResult = {
@@ -191,12 +232,20 @@ export class AgentServer {
         };
         // TodoWrite emits task_update directly through ToolContext.streamCallback;
         // no module singleton wiring needed anymore.
+        // Snapshot the controller for the catch block — `this.abortController`
+        // is nulled in the `finally`, so by the time we'd want to check
+        // `signal.aborted` below it's already gone.
+        const runController = this.abortController;
         try {
             const result = await this.legacyEngine.run(params.task, {
                 cwd: params.cwd,
                 sessionId: params.sessionId,
-                signal: this.abortController.signal,
+                signal: runController.signal,
                 onStream: streamToClient,
+                goal: typeof params.goal === "string" ||
+                    (params.goal != null && typeof params.goal === "object")
+                    ? params.goal
+                    : undefined,
             });
             const runResult = {
                 text: result.text,
@@ -208,7 +257,28 @@ export class AgentServer {
             this.transport.send(createResponse(req.id, runResult));
         }
         catch (err) {
-            this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
+            // ESC / Stop path. If the user cancelled, the engine's
+            // in-flight LLM call or Bash spawn rejects with an AbortError
+            // that bubbles up here. Don't surface it as InternalError —
+            // the user already knows they pressed stop; clients should
+            // just clear busy.
+            const errName = err.name;
+            const aborted = runController.signal.aborted ||
+                errName === "AbortError" ||
+                errName === "APIUserAbortError";
+            if (aborted) {
+                const cancelledResult = {
+                    text: "",
+                    reason: "aborted_streaming",
+                    sessionId: params.sessionId ?? "",
+                    turnCount: 0,
+                    usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+                };
+                this.transport.send(createResponse(req.id, cancelledResult));
+            }
+            else {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
+            }
         }
         finally {
             this.running = false;
@@ -306,6 +376,29 @@ export class AgentServer {
             if (typeof params.permissionMode === "string") {
                 s.engine.setPermissionMode(params.permissionMode);
             }
+            // Per-session model switch — the missing piece that made model changes
+            // worker-global (session-isolation research §3). requestModelSwitch
+            // applies immediately when idle, defers to the run boundary when busy
+            // so it never swaps the model under a running LLM client.
+            if (typeof params.model === "string") {
+                try {
+                    s.requestModelSwitch(params.model);
+                }
+                catch (err) {
+                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, err.message));
+                    return;
+                }
+            }
+            // Hot-reload disk-default config onto this one session (layer 2).
+            if (params.reloadSettings === true) {
+                if (!this.settingsReader) {
+                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "reloadSettings is not supported by this AgentServer: no settingsReader is wired"));
+                    return;
+                }
+                const settings = this.settingsReader();
+                const version = ++this.configVersion;
+                s.engine.refreshRuntimeConfig(diskDefaultsFrom(settings), version);
+            }
             this.transport.send(createResponse(req.id, { ok: true }));
             return;
         }
@@ -335,6 +428,42 @@ export class AgentServer {
         if (params.planMode !== undefined && engine) {
             engine.setPlanMode(params.planMode);
         }
+        // Config hot-reload layer 2: re-read disk settings once and push the
+        // disk-default config patch (+ settings-hook reload + incremental MCP
+        // connect) onto every live session. Parallel to reloadModels; no new
+        // protocol method. In-flight turns are untouched — refreshRuntimeConfig
+        // only mutates this.config, picked up at the next turn boundary.
+        if (params.reloadSettings === true) {
+            if (!this.settingsReader) {
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "reloadSettings is not supported by this AgentServer: no settingsReader is wired"));
+                return;
+            }
+            if (!this.chatManager) {
+                // Single-engine host (legacyEngine / anyEngine, no chatManager): there
+                // are no sessions to fan out to, but the one engine must still pick up
+                // the reload — otherwise we'd report ok:true while silently dropping it.
+                // Mirrors how reloadModels/model/planMode above act on `engine`.
+                if (engine) {
+                    const settings = this.settingsReader();
+                    engine.refreshRuntimeConfig(diskDefaultsFrom(settings), ++this.configVersion);
+                }
+                this.transport.send(createResponse(req.id, { ok: true }));
+                return;
+            }
+            const settings = this.settingsReader();
+            const patch = diskDefaultsFrom(settings);
+            // #6: content short-circuit. If the disk-default patch is byte-identical
+            // to the last one we broadcast, the disk config that matters to running
+            // sessions hasn't changed — skip the whole forEachSession (and the per-
+            // session reloadHooks churn it triggers). Still return ok; a genuine
+            // change differs in JSON and propagates normally.
+            const patchJson = JSON.stringify(patch);
+            if (patchJson !== this.lastBroadcastPatch) {
+                this.lastBroadcastPatch = patchJson;
+                const version = ++this.configVersion;
+                this.chatManager.forEachSession((s) => s.engine.refreshRuntimeConfig(patch, version));
+            }
+        }
         this.transport.send(createResponse(req.id, { ok: true }));
     }
     // ─── Query ──────────────────────────────────────────────────────
@@ -361,12 +490,15 @@ export class AgentServer {
             case "sessions": {
                 if (this.chatManager) {
                     // Return the ChatSessionManager's live sessions
-                    const sessions = [...this.chatManager.sessions.entries()].map(([id, s]) => ({
-                        sessionId: id,
-                        busy: s.isBusy(),
-                        queueDepth: s.queueDepth(),
-                        lastActivityAt: s.lastActivityAt,
-                    }));
+                    const sessions = [];
+                    this.chatManager.forEachSession((s) => {
+                        sessions.push({
+                            sessionId: s.id,
+                            busy: s.isBusy(),
+                            queueDepth: s.queueDepth(),
+                            lastActivityAt: s.lastActivityAt,
+                        });
+                    });
                     this.transport.send(createResponse(req.id, { type: "sessions", data: sessions }));
                 }
                 else if (engine) {
@@ -393,15 +525,9 @@ export class AgentServer {
                         model: config.llm.model,
                         cwd: config.cwd,
                         maxContextTokens: config.maxContextTokens,
-                        llm: {
-                            provider: config.llm.provider,
-                            model: config.llm.model,
-                            apiKey: config.llm.apiKey,
-                            baseUrl: config.llm.baseUrl,
-                            temperature: config.llm.temperature,
-                            maxTokens: config.llm.maxTokens,
-                            enableStreaming: config.llm.enableStreaming,
-                        },
+                        // apiKey is redacted at this boundary: clients only get
+                        // hasApiKey + optional apiKeyPreview. See protocol/redact.ts.
+                        llm: redactLlmConfig(config.llm),
                     },
                 }));
                 break;
@@ -499,7 +625,15 @@ export class AgentServer {
                             cachedAt: cache ? cache.fetchedAt : undefined,
                         };
                     });
-                    this.transport.send(createResponse(req.id, { type: "providers", data: enriched }));
+                    // Strip apiKey / other secret-shaped fields from each provider
+                    // before sending. `...p` above spreads the whole provider record,
+                    // which includes apiKey verbatim — without this redact pass, any
+                    // protocol client could call query("providers") and harvest
+                    // credentials. The shared redactor preserves
+                    // presence-without-value (hasApiKey-style consumers still see the
+                    // field shape, just with [redacted] in place of the secret).
+                    const safe = redactSecrets(enriched);
+                    this.transport.send(createResponse(req.id, { type: "providers", data: safe }));
                 }
                 catch (err) {
                     this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
@@ -521,7 +655,11 @@ export class AgentServer {
                     if (!key)
                         throw new Error("key is required for config_set");
                     engine.updateConfig(key, value);
-                    this.transport.send(createResponse(req.id, { type: "config_set", data: { key, value } }));
+                    // Echo back through the same secret-aware masker as config_get so
+                    // a `config_set("llm.apiKey", "...")` confirmation doesn't ship
+                    // the new secret through the response/log path.
+                    const safeValue = maskSecretValue(key, value);
+                    this.transport.send(createResponse(req.id, { type: "config_set", data: { key, value: safeValue } }));
                 }
                 catch (err) {
                     this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
@@ -538,7 +676,9 @@ export class AgentServer {
                     if (!key)
                         throw new Error("key is required for config_get");
                     const value = engine.readSetting(key);
-                    this.transport.send(createResponse(req.id, { type: "config_get", data: { key, value } }));
+                    // Mask secret-looking keys (apiKey/token/secret/…) at the boundary.
+                    const safeValue = maskSecretValue(key, value);
+                    this.transport.send(createResponse(req.id, { type: "config_get", data: { key, value: safeValue } }));
                 }
                 catch (err) {
                     this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
@@ -743,6 +883,54 @@ export class AgentServer {
     /**
      * Ask the client to answer a question from the agent (legacy single-engine path).
      */
+    /**
+     * Per-session AskUserQuestion for the chatManager path. Mirrors
+     * requestAskUserFromClient but resolves via the SESSION's pendingApprovals
+     * (the chatManager approve handler looks there, keyed by sessionId+requestId)
+     * and tags the notify with sessionId so the renderer routes the question to
+     * the right chat tab.
+     */
+    requestAskUserForSession(session, sessionId, question, opts) {
+        return new Promise((resolve) => {
+            const requestId = nanoid(12);
+            session.pendingApprovals.set(requestId, (decision) => {
+                this.clearApprovalTimer(requestId);
+                const result = decision;
+                if (result && typeof result === "object" && "approved" in result) {
+                    resolve(result.approved ? (result.answer ?? "") : (result.reason ?? "(user declined to answer)"));
+                }
+                else {
+                    // chatManager approve handler resolves with the raw decision value.
+                    resolve(typeof decision === "string" ? decision : "");
+                }
+            });
+            const timer = setTimeout(() => {
+                if (session.pendingApprovals.has(requestId)) {
+                    session.pendingApprovals.delete(requestId);
+                    this.approvalTimers.delete(requestId);
+                    resolve("(approval timed out)");
+                }
+            }, AgentServer.APPROVAL_TIMEOUT_MS);
+            this.approvalTimers.set(requestId, timer);
+            const args = { question };
+            if (opts?.header !== undefined)
+                args.header = opts.header;
+            if (opts?.options !== undefined)
+                args.options = opts.options;
+            if (opts?.multiSelect !== undefined)
+                args.multiSelect = opts.multiSelect;
+            this.notify(Methods.ApprovalRequest, {
+                sessionId,
+                requestId,
+                request: {
+                    toolName: "__ask_user__",
+                    args,
+                    description: question,
+                    riskLevel: "low",
+                },
+            });
+        });
+    }
     requestAskUserFromClient(question, opts) {
         return new Promise((resolve) => {
             const requestId = nanoid(12);
@@ -785,16 +973,26 @@ export class AgentServer {
         this.transport.send(createNotification(method, params));
     }
     /**
-     * Get any available engine — used for global query ops when chatManager is
-     * present but no legacyEngine was supplied. Borrows the first live session.
+     * Get any available engine — used for global query/configure ops when
+     * chatManager is present but no legacyEngine was supplied. Prefer a live chat
+     * session; before the first user turn, lazily build a detached engine through
+     * the manager's factory so global UI surfaces (/login, model manager, model
+     * selector) can query models/providers without requiring a chat session first.
      */
     anyEngine() {
         if (!this.chatManager)
             return null;
-        // Access private `sessions` map — acceptable for same-package access.
         const sessions = this.chatManager.sessions;
         const first = sessions.values().next().value;
-        return first ? first.engine : null;
+        if (first)
+            return first.engine;
+        if (this.globalQueryEngine)
+            return this.globalQueryEngine;
+        const factory = this.chatManager.factory;
+        if (typeof factory !== "function")
+            return null;
+        this.globalQueryEngine = factory({});
+        return this.globalQueryEngine;
     }
     // ─── Lifecycle ──────────────────────────────────────────────────
     close() {

package/dist/protocol/tcp-transport.d.ts

@@ -0,0 +1,45 @@
+/**
+ * TcpTransport — newline-delimited JSON over a TCP socket (Duplex stream).
+ *
+ * Phase 6 of the automation plan: lets the same AgentServer that runs over
+ * stdio (agent-server-stdio) also serve over a network socket, so a headless
+ * host can be reached by a remote/local client. The transport implements the
+ * 3-method Transport interface (send/onMessage/close); AgentServer is unchanged
+ * (§0 of docs/automation-plan-2026-05-31.md).
+ *
+ * Framing mirrors StdioTransport: one JSON value per line. The socket core is
+ * separated from listen/accept (`listenTcp`) so the framing is unit-testable
+ * against any Duplex without opening a real port.
+ *
+ * v1 security: intended for localhost / SSH-tunnel use only. There is NO
+ * authentication here — do not bind to a public interface without adding auth.
+ */
+import { type Server, type Socket } from "node:net";
+import type { Duplex } from "node:stream";
+import type { Transport } from "./transport.js";
+import type { RpcMessage } from "./types.js";
+/** Wrap a connected Duplex socket as a Transport (NDJSON framing). */
+export declare class SocketTransport implements Transport {
+    private readonly socket;
+    private rl;
+    private handlers;
+    constructor(socket: Duplex);
+    send(message: RpcMessage): void;
+    onMessage(handler: (message: RpcMessage) => void): void;
+    close(): void;
+}
+export interface TcpListenResult {
+    server: Server;
+    /** The actual port bound (useful when 0 was requested). */
+    port: number;
+    close(): Promise<void>;
+}
+/**
+ * Listen on host:port and invoke `onConnection` with a SocketTransport for each
+ * accepted client. Resolves once listening. Defaults to 127.0.0.1 — never bind
+ * 0.0.0.0 without auth (v1 has none).
+ */
+export declare function listenTcp(opts: {
+    port: number;
+    host?: string;
+}, onConnection: (transport: SocketTransport, socket: Socket) => void): Promise<TcpListenResult>;

package/dist/protocol/tcp-transport.js

@@ -0,0 +1,74 @@
+/**
+ * TcpTransport — newline-delimited JSON over a TCP socket (Duplex stream).
+ *
+ * Phase 6 of the automation plan: lets the same AgentServer that runs over
+ * stdio (agent-server-stdio) also serve over a network socket, so a headless
+ * host can be reached by a remote/local client. The transport implements the
+ * 3-method Transport interface (send/onMessage/close); AgentServer is unchanged
+ * (§0 of docs/automation-plan-2026-05-31.md).
+ *
+ * Framing mirrors StdioTransport: one JSON value per line. The socket core is
+ * separated from listen/accept (`listenTcp`) so the framing is unit-testable
+ * against any Duplex without opening a real port.
+ *
+ * v1 security: intended for localhost / SSH-tunnel use only. There is NO
+ * authentication here — do not bind to a public interface without adding auth.
+ */
+import { createServer } from "node:net";
+import { createInterface } from "node:readline";
+/** Wrap a connected Duplex socket as a Transport (NDJSON framing). */
+export class SocketTransport {
+    socket;
+    rl;
+    handlers = [];
+    constructor(socket) {
+        this.socket = socket;
+        this.rl = createInterface({ input: socket });
+        this.rl.on("line", (line) => {
+            if (!line.trim())
+                return;
+            try {
+                const msg = JSON.parse(line);
+                for (const handler of this.handlers)
+                    handler(msg);
+            }
+            catch {
+                // Skip malformed lines (same policy as StdioTransport).
+            }
+        });
+    }
+    send(message) {
+        this.socket.write(JSON.stringify(message) + "\n");
+    }
+    onMessage(handler) {
+        this.handlers.push(handler);
+    }
+    close() {
+        this.rl.close();
+        this.handlers = [];
+        this.socket.end();
+    }
+}
+/**
+ * Listen on host:port and invoke `onConnection` with a SocketTransport for each
+ * accepted client. Resolves once listening. Defaults to 127.0.0.1 — never bind
+ * 0.0.0.0 without auth (v1 has none).
+ */
+export function listenTcp(opts, onConnection) {
+    const host = opts.host ?? "127.0.0.1";
+    return new Promise((resolve, reject) => {
+        const server = createServer((socket) => {
+            onConnection(new SocketTransport(socket), socket);
+        });
+        server.once("error", reject);
+        server.listen(opts.port, host, () => {
+            const addr = server.address();
+            const port = typeof addr === "object" && addr ? addr.port : opts.port;
+            resolve({
+                server,
+                port,
+                close: () => new Promise((res) => server.close(() => res())),
+            });
+        });
+    });
+}