@tencent-ai/agent-harness 0.1.0 → 0.1.1

package/lib/runtime/codebuddy-v2-private-child.js

@@ -40,6 +40,7 @@ const process_runtime_context_js_1 = require("../effect-runtime/process-runtime-
 const async_js_1 = require("../internal/async.js");
 const codebuddy_prewarm_pool_js_1 = require("./codebuddy-prewarm-pool.js");
 const codebuddy_v2_child_js_1 = require("./codebuddy-v2-child.js");
+const node_runtime_js_1 = require("./node-runtime.js");
 const process_containment_js_1 = require("./process-containment.js");
 const STARTUP_ABORT_MESSAGE = 'Private CodeBuddy v2 startup aborted';
 function requestOptions(options) {
@@ -275,13 +276,24 @@ async function createCodeBuddyV2PrivateChildPrewarmRuntime(options) {
         if (!binPath || !path.isAbsolute(binPath)) {
             throw new Error('Private CodeBuddy prewarm requires an absolute CLI artifact');
         }
-        const nodeExecutable = defaults.nodeExecutable ?? process.execPath;
+        if (defaults.nodeExecutable !== undefined
+            && defaults.nodeRuntime !== undefined
+            && defaults.nodeExecutable !== defaults.nodeRuntime.executable) {
+            throw new Error('CodeBuddy Node runtime executable is ambiguous');
+        }
+        const nodeRuntime = defaults.nodeRuntime ?? (0, node_runtime_js_1.resolveNodeRuntimeLaunch)({
+            ...(defaults.nodeExecutable === undefined
+                ? {}
+                : { executable: defaults.nodeExecutable }),
+        });
+        const nodeExecutable = nodeRuntime.executable;
         const key = (0, codebuddy_prewarm_pool_js_1.createCodeBuddyPrewarmKey)({
             cliArtifactPath: binPath,
             cliVersion,
             cwd,
             env: defaults.env,
             nodeExecutablePath: nodeExecutable,
+            nodeRuntime,
             preserveManagedAuthenticationEnvironment: defaults.preserveManagedAuthenticationEnvironment,
             processEnv: defaults.processEnv,
             productLaunch: primeOptions.productLaunch,
@@ -295,6 +307,7 @@ async function createCodeBuddyV2PrivateChildPrewarmRuntime(options) {
                 dependencies: defaults.dependencies,
                 env: defaults.env,
                 nodeExecutable,
+                nodeRuntime,
                 posixContainmentMode: defaults.posixContainmentMode,
                 preserveManagedAuthenticationEnvironment: defaults.preserveManagedAuthenticationEnvironment,
                 processEnv: defaults.processEnv,

package/lib/runtime/node-runtime.d.ts

@@ -0,0 +1,35 @@
+export declare const ELECTRON_RUN_AS_NODE_ENV = "ELECTRON_RUN_AS_NODE";
+export interface NodeRuntimeEnvironment {
+    readonly ELECTRON_RUN_AS_NODE?: '1';
+}
+export interface NodeRuntimeLaunch {
+    /** Executable which evaluates the JavaScript entry passed as argv[1]. */
+    readonly executable: string;
+    /** Runtime-owned environment overlay required by that executable. */
+    readonly environment: Readonly<NodeRuntimeEnvironment>;
+}
+export interface ResolveNodeRuntimeLaunchOptions {
+    /** Defaults to the executable evaluating the current Harness process. */
+    readonly executable?: string;
+    /** Deterministic test seam; production uses `process.execPath`. */
+    readonly currentExecutable?: string;
+    /** Deterministic test seam; production uses `process.versions.electron`. */
+    readonly electronVersion?: string;
+    /** Explicit contract for a non-current Electron executable. */
+    readonly electronRunAsNode?: boolean;
+}
+/**
+ * Resolves a coherent JavaScript runtime launch contract.
+ *
+ * Electron keeps its Electron identity while running as Node. A child launch
+ * therefore needs both `process.execPath` and `ELECTRON_RUN_AS_NODE=1`; the
+ * executable alone is not a Node runtime. Ordinary custom executables are
+ * treated as Node unless their owner explicitly selects Electron-as-Node.
+ */
+export declare function resolveNodeRuntimeLaunch({ currentExecutable, electronRunAsNode, electronVersion, executable, }?: ResolveNodeRuntimeLaunchOptions): NodeRuntimeLaunch;
+/**
+ * Applies the runtime-owned overlay after removing ambient spellings of the
+ * same keys. Environment names are compared case-insensitively so Windows
+ * cannot retain a conflicting `electron_run_as_node` value.
+ */
+export declare function applyNodeRuntimeEnvironment(base: NodeJS.ProcessEnv, runtime?: NodeRuntimeLaunch): NodeJS.ProcessEnv;

package/lib/runtime/node-runtime.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ELECTRON_RUN_AS_NODE_ENV = void 0;
+exports.resolveNodeRuntimeLaunch = resolveNodeRuntimeLaunch;
+exports.applyNodeRuntimeEnvironment = applyNodeRuntimeEnvironment;
+exports.ELECTRON_RUN_AS_NODE_ENV = 'ELECTRON_RUN_AS_NODE';
+/**
+ * Resolves a coherent JavaScript runtime launch contract.
+ *
+ * Electron keeps its Electron identity while running as Node. A child launch
+ * therefore needs both `process.execPath` and `ELECTRON_RUN_AS_NODE=1`; the
+ * executable alone is not a Node runtime. Ordinary custom executables are
+ * treated as Node unless their owner explicitly selects Electron-as-Node.
+ */
+function resolveNodeRuntimeLaunch({ currentExecutable = process.execPath, electronRunAsNode, electronVersion = process.versions.electron, executable = currentExecutable, } = {}) {
+    const useElectronNode = electronRunAsNode
+        ?? (executable === currentExecutable
+            && typeof electronVersion === 'string'
+            && electronVersion.length > 0);
+    return Object.freeze({
+        executable,
+        environment: Object.freeze(useElectronNode
+            ? { [exports.ELECTRON_RUN_AS_NODE_ENV]: '1' }
+            : {}),
+    });
+}
+/**
+ * Applies the runtime-owned overlay after removing ambient spellings of the
+ * same keys. Environment names are compared case-insensitively so Windows
+ * cannot retain a conflicting `electron_run_as_node` value.
+ */
+function applyNodeRuntimeEnvironment(base, runtime = resolveNodeRuntimeLaunch()) {
+    if (Object.keys(runtime.environment).some(key => key !== exports.ELECTRON_RUN_AS_NODE_ENV)
+        || (runtime.environment.ELECTRON_RUN_AS_NODE !== undefined
+            && runtime.environment.ELECTRON_RUN_AS_NODE !== '1')) {
+        throw new Error('Node runtime environment contract is invalid');
+    }
+    const ownedKeys = new Set([exports.ELECTRON_RUN_AS_NODE_ENV].map(key => key.toUpperCase()));
+    const environment = Object.fromEntries(Object.entries(base).filter(([key]) => !ownedKeys.has(key.toUpperCase())));
+    return {
+        ...environment,
+        ...(runtime.environment.ELECTRON_RUN_AS_NODE === '1'
+            ? { [exports.ELECTRON_RUN_AS_NODE_ENV]: '1' }
+            : {}),
+    };
+}

package/lib/runtime/posix-contained-process.d.ts

@@ -1,6 +1,7 @@
 import { type ChildProcess, type SpawnOptions } from 'node:child_process';
 import { type PosixStdioMcpGuardian, type PosixStdioMcpGuardianOptions } from '../integration/stdio-guardian.js';
 import type { CodeBuddyCodeSpawnSpec } from './codebuddy-code.js';
+import { type NodeRuntimeLaunch } from './node-runtime.js';
 export interface ContainedTargetExit {
     readonly code: number | null;
     readonly signal: NodeJS.Signals | null;
@@ -68,6 +69,8 @@ export interface AcquirePosixContainedProcessOptions {
     readonly anchorEntryPath?: string;
     readonly containmentMode?: 'process-group' | 'process-tree';
     readonly killTimeoutMs?: number;
+    /** @internal JavaScript runtime used for the private anchor child. */
+    readonly nodeRuntime?: NodeRuntimeLaunch;
     readonly onAnchorSpawned?: (anchor: ChildProcess) => void;
     readonly onTargetStarted?: (anchorPid: number, targetPid: number) => void;
     readonly platform?: NodeJS.Platform;

package/lib/runtime/posix-contained-process.js

@@ -13,6 +13,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const stdio_guardian_js_1 = require("../integration/stdio-guardian.js");
 const async_js_1 = require("../internal/async.js");
 const errors_js_1 = require("../internal/errors.js");
+const node_runtime_js_1 = require("./node-runtime.js");
 const posix_process_group_anchor_protocol_js_1 = require("./posix-process-group-anchor-protocol.js");
 const DEFAULT_KILL_TIMEOUT_MS = 3_000;
 const DEFAULT_POLL_INTERVAL_MS = 50;
@@ -300,15 +301,16 @@ async function acquirePosixContainedProcess(input) {
     const attachGuardian = input.attachGuardian
         ?? stdio_guardian_js_1.attachPosixStdioMcpGuardian;
     let child;
+    const nodeRuntime = input.nodeRuntime ?? (0, node_runtime_js_1.resolveNodeRuntimeLaunch)();
     try {
-        child = spawnAnchor(process.execPath, [anchorEntryPath], {
+        child = spawnAnchor(nodeRuntime.executable, [anchorEntryPath], {
             cwd: node_path_1.default.dirname(anchorEntryPath),
             detached: true,
             // Target secrets/configuration cross private IPC only. The anchor
             // process itself receives no ambient Harness or user environment.
-            env: {
+            env: (0, node_runtime_js_1.applyNodeRuntimeEnvironment)({
                 AGENT_HARNESS_PRIVATE_PARENT_DEATH_OWNER: '1',
-            },
+            }, nodeRuntime),
             stdio: ['pipe', 'pipe', 'pipe', 'ipc'],
             windowsHide: true,
         });

package/lib/runtime/posix-process-snapshot.d.ts

@@ -0,0 +1,28 @@
+import { type PosixProcessRecord } from './process-tree.js';
+interface DarwinProcessSnapshotBinding {
+    captureOwnedProcessIds(rootPid: number, ownershipId: number, excludedPid: number, timeoutMs: number): unknown;
+}
+export interface PosixProcessSnapshotOptions {
+    /** Process which must never be classified as child-owned. */
+    readonly excludedPid?: number;
+    /** Detached process group/session which proves direct ownership. */
+    readonly ownershipId?: number;
+    /** Test seam for the in-process Darwin libproc binding. */
+    readonly darwinBinding?: DarwinProcessSnapshotBinding;
+    /** Test seam for resolving an installed package instead of this package. */
+    readonly packageRoot?: string;
+    /** Test seam for a synthetic procfs. */
+    readonly procRoot?: string;
+    readonly readDirectory?: (directory: string) => Promise<readonly string[]>;
+    readonly readTextFile?: (file: string) => Promise<string>;
+    readonly timeoutMs?: number;
+}
+/** Parses the stable ownership fields from one Linux `/proc/<pid>/stat`. */
+export declare function parseLinuxProcStat(expectedPid: number, stat: string): PosixProcessRecord;
+export declare function resolveDarwinProcessSnapshotAddonPath(arch?: NodeJS.Architecture, packageRoot?: string): string;
+/**
+ * Captures a containment-owned POSIX process tree without launching a global
+ * process utility. Any unsupported platform or incomplete snapshot rejects.
+ */
+export declare function capturePosixOwnedProcessIds(rootPid: number, platform: NodeJS.Platform, options?: PosixProcessSnapshotOptions): Promise<readonly number[]>;
+export {};

package/lib/runtime/posix-process-snapshot.js

@@ -0,0 +1,183 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseLinuxProcStat = parseLinuxProcStat;
+exports.resolveDarwinProcessSnapshotAddonPath = resolveDarwinProcessSnapshotAddonPath;
+exports.capturePosixOwnedProcessIds = capturePosixOwnedProcessIds;
+const promises_1 = require("node:fs/promises");
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+const process_tree_js_1 = require("./process-tree.js");
+const MAX_PROCESS_COUNT = 65_536;
+const PROC_READ_CONCURRENCY = 32;
+const loadNativeModule = (0, node_module_1.createRequire)(__filename);
+function assertPositivePid(pid, name) {
+    if (!Number.isSafeInteger(pid) || pid <= 0 || pid > 0x7fff_ffff) {
+        throw new TypeError(`${name} must be a positive 32-bit PID`);
+    }
+}
+function errorCode(error) {
+    return error instanceof Error && 'code' in error
+        ? String(error.code)
+        : undefined;
+}
+function isVanishedProcEntry(error) {
+    const code = errorCode(error);
+    return code === 'ENOENT' || code === 'ESRCH';
+}
+function assertWithinDeadline(deadlineAt) {
+    if (Date.now() >= deadlineAt) {
+        throw new Error('POSIX process snapshot deadline expired');
+    }
+}
+async function settleWithin(operation, timeoutMs) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        operation.catch(() => undefined);
+        throw new Error('POSIX process snapshot deadline expired');
+    }
+    let timer;
+    try {
+        return await Promise.race([
+            operation,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    reject(new Error('POSIX process snapshot deadline expired'));
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+}
+/** Parses the stable ownership fields from one Linux `/proc/<pid>/stat`. */
+function parseLinuxProcStat(expectedPid, stat) {
+    const commandEnd = stat.lastIndexOf(')');
+    const commandStart = stat.indexOf('(');
+    if (commandStart <= 0 || commandEnd <= commandStart) {
+        throw new Error(`Malformed /proc/${expectedPid}/stat`);
+    }
+    const parsedPid = Number(stat.slice(0, commandStart).trim());
+    const fields = stat.slice(commandEnd + 1).trim().split(/\s+/);
+    // fields[0] is state; fields[1..3] are PPID, PGRP, and session.
+    const parentPid = Number(fields[1]);
+    const ownershipId = Number(fields[3]);
+    if (parsedPid !== expectedPid
+        || !Number.isSafeInteger(parentPid)
+        || parentPid < 0
+        || !Number.isSafeInteger(ownershipId)
+        || ownershipId < 0) {
+        throw new Error(`Malformed /proc/${expectedPid}/stat`);
+    }
+    return { ownershipId, parentPid, pid: expectedPid };
+}
+async function captureLinuxProcessIds(rootPid, ownershipId, excludedPid, options) {
+    const procRoot = options.procRoot ?? '/proc';
+    const readDirectory = options.readDirectory
+        ?? (directory => (0, promises_1.readdir)(directory));
+    const readTextFile = options.readTextFile
+        ?? (file => (0, promises_1.readFile)(file, 'utf8'));
+    const timeoutMs = options.timeoutMs ?? 750;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new Error('POSIX process snapshot deadline expired');
+    }
+    const deadlineAt = Date.now() + timeoutMs;
+    const entries = await readDirectory(procRoot);
+    assertWithinDeadline(deadlineAt);
+    const processIds = entries
+        .filter(entry => /^[1-9]\d*$/.test(entry))
+        .map(Number)
+        .filter(pid => Number.isSafeInteger(pid) && pid <= 0x7fff_ffff);
+    if (processIds.length > MAX_PROCESS_COUNT) {
+        throw new Error(`Linux process snapshot exceeds ${MAX_PROCESS_COUNT} processes`);
+    }
+    const records = [];
+    let cursor = 0;
+    const worker = async () => {
+        while (cursor < processIds.length) {
+            assertWithinDeadline(deadlineAt);
+            const pid = processIds[cursor];
+            cursor += 1;
+            try {
+                const stat = await readTextFile(node_path_1.default.join(procRoot, String(pid), 'stat'));
+                records.push(parseLinuxProcStat(pid, stat));
+            }
+            catch (error) {
+                // Process exit is an expected snapshot race. All other read or
+                // parse failures make ancestry incomplete and therefore fail
+                // closed at the containment caller.
+                if (!isVanishedProcEntry(error)) {
+                    throw error;
+                }
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(PROC_READ_CONCURRENCY, processIds.length) }, worker));
+    assertWithinDeadline(deadlineAt);
+    return (0, process_tree_js_1.collectPosixOwnedProcessIds)(records, rootPid, excludedPid, ownershipId);
+}
+function resolveDarwinProcessSnapshotAddonPath(arch = process.arch, packageRoot = node_path_1.default.resolve(__dirname, '../..')) {
+    if (arch !== 'arm64' && arch !== 'x64') {
+        throw new Error(`Darwin process snapshots do not support architecture ${arch}`);
+    }
+    return node_path_1.default.join(packageRoot, 'bin', 'native', `darwin-${arch}`, 'agent-harness-process-snapshot.node');
+}
+function loadDarwinProcessSnapshotBinding(options) {
+    if (options.darwinBinding) {
+        return options.darwinBinding;
+    }
+    const module = loadNativeModule(resolveDarwinProcessSnapshotAddonPath(process.arch, options.packageRoot));
+    if (typeof module !== 'object'
+        || module === null
+        || !('captureOwnedProcessIds' in module)
+        || typeof module.captureOwnedProcessIds !== 'function') {
+        throw new Error('Darwin process snapshot binding has an invalid API');
+    }
+    return module;
+}
+function validateNativeProcessIds(result, rootPid, excludedPid) {
+    if (!Array.isArray(result) || result.length > MAX_PROCESS_COUNT) {
+        throw new Error('Darwin process snapshot binding returned invalid data');
+    }
+    const processIds = new Set();
+    for (const pid of result) {
+        if (!Number.isSafeInteger(pid)
+            || pid <= 0
+            || pid > 0x7fff_ffff) {
+            throw new Error('Darwin process snapshot binding returned an invalid PID');
+        }
+        if (pid !== rootPid && pid !== excludedPid) {
+            processIds.add(pid);
+        }
+    }
+    return [...processIds].sort((left, right) => left - right);
+}
+/**
+ * Captures a containment-owned POSIX process tree without launching a global
+ * process utility. Any unsupported platform or incomplete snapshot rejects.
+ */
+async function capturePosixOwnedProcessIds(rootPid, platform, options = {}) {
+    assertPositivePid(rootPid, 'rootPid');
+    const excludedPid = options.excludedPid ?? process.pid;
+    const ownershipId = options.ownershipId ?? rootPid;
+    const timeoutMs = options.timeoutMs ?? 750;
+    assertPositivePid(excludedPid, 'excludedPid');
+    assertPositivePid(ownershipId, 'ownershipId');
+    if (!Number.isSafeInteger(timeoutMs)
+        || timeoutMs <= 0
+        || timeoutMs > 0x7fff_ffff) {
+        throw new RangeError('timeoutMs must be a positive 32-bit integer');
+    }
+    if (platform === 'linux') {
+        return settleWithin(captureLinuxProcessIds(rootPid, ownershipId, excludedPid, options), timeoutMs);
+    }
+    if (platform === 'darwin') {
+        const binding = loadDarwinProcessSnapshotBinding(options);
+        return validateNativeProcessIds(binding.captureOwnedProcessIds(rootPid, ownershipId, excludedPid, timeoutMs), rootPid, excludedPid);
+    }
+    throw new Error(`POSIX process snapshots are unsupported on ${platform}`);
+}

package/lib/runtime/process-tree.d.ts

@@ -1,13 +1,11 @@
-/** Returns the native `ps` ownership key for a detached Node child. */
-export declare function posixProcessOwnershipColumn(platform: NodeJS.Platform): 'pgid' | 'sid';
-/** Builds a PATH-independent process snapshot command for containment checks. */
-export declare function buildPosixProcessListSpec(platform: NodeJS.Platform): {
-    args: readonly string[];
-    command: string;
-};
+export interface PosixProcessRecord {
+    readonly ownershipId: number;
+    readonly parentPid: number;
+    readonly pid: number;
+}
 /** ESRCH is the only proof of absence; EPERM still proves the process exists. */
 export declare function isMissingProcess(error: unknown): boolean;
 export declare function processExists(pid: number): boolean;
 export declare function processGroupExists(processGroupId: number): boolean;
 /** Collects both same-ownership-group members and transitive PPID descendants. */
-export declare function collectPosixOwnedProcessIds(output: string, rootPid: number, harnessPid: number): readonly number[];
+export declare function collectPosixOwnedProcessIds(processes: readonly PosixProcessRecord[], rootPid: number, harnessPid: number, ownershipId?: number): readonly number[];

package/lib/runtime/process-tree.js

@@ -1,26 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.posixProcessOwnershipColumn = posixProcessOwnershipColumn;
-exports.buildPosixProcessListSpec = buildPosixProcessListSpec;
 exports.isMissingProcess = isMissingProcess;
 exports.processExists = processExists;
 exports.processGroupExists = processGroupExists;
 exports.collectPosixOwnedProcessIds = collectPosixOwnedProcessIds;
-/** Returns the native `ps` ownership key for a detached Node child. */
-function posixProcessOwnershipColumn(platform) {
-    // A detached Node child leads its process group on Darwin, while procps
-    // Linux exposes the detached session directly. Darwin accepts `sess` but
-    // reports 0 here, so it cannot prove ownership of reparented descendants.
-    return platform === 'darwin' ? 'pgid' : 'sid';
-}
-/** Builds a PATH-independent process snapshot command for containment checks. */
-function buildPosixProcessListSpec(platform) {
-    const ownershipColumn = posixProcessOwnershipColumn(platform);
-    return {
-        args: ['-axo', `pid=,ppid=,${ownershipColumn}=`],
-        command: '/bin/ps',
-    };
-}
 /** ESRCH is the only proof of absence; EPERM still proves the process exists. */
 function isMissingProcess(error) {
     return error instanceof Error && 'code' in error && error.code === 'ESRCH';
@@ -44,23 +27,7 @@ function processGroupExists(processGroupId) {
     }
 }
 /** Collects both same-ownership-group members and transitive PPID descendants. */
-function collectPosixOwnedProcessIds(output, rootPid, harnessPid) {
-    const processes = [];
-    for (const line of output.split('\n')) {
-        const [rawPid, rawParentPid, rawOwnershipId] = line.trim().split(/\s+/, 3);
-        const pid = Number(rawPid);
-        const parentPid = Number(rawParentPid);
-        const ownershipId = Number(rawOwnershipId);
-        if (Number.isSafeInteger(pid)
-            && Number.isSafeInteger(parentPid)
-            && Number.isSafeInteger(ownershipId)
-            && pid > 0
-            && parentPid >= 0
-            && ownershipId >= 0
-            && pid !== harnessPid) {
-            processes.push({ ownershipId, parentPid, pid });
-        }
-    }
+function collectPosixOwnedProcessIds(processes, rootPid, harnessPid, ownershipId = rootPid) {
     // forkpty calls setsid(), so a PTY child is no longer in the CodeBuddy
     // root's session/process group even though its PPID ancestry still belongs
     // to that root. Combine both views while the root is alive.
@@ -69,13 +36,18 @@ function collectPosixOwnedProcessIds(output, rootPid, harnessPid) {
     while (changed) {
         changed = false;
         for (const entry of processes) {
-            if (!owned.has(entry.pid)
-                && (entry.ownershipId === rootPid || owned.has(entry.parentPid))) {
+            if (entry.pid !== harnessPid
+                && entry.pid > 0
+                && entry.parentPid >= 0
+                && entry.ownershipId >= 0
+                && !owned.has(entry.pid)
+                && (entry.ownershipId === ownershipId
+                    || owned.has(entry.parentPid))) {
                 owned.add(entry.pid);
                 changed = true;
             }
         }
     }
     owned.delete(rootPid);
-    return [...owned];
+    return [...owned].sort((left, right) => left - right);
 }

package/lib/transport/network.d.ts

@@ -41,6 +41,12 @@ export interface CreateAgentHarnessNetworkListenerOptions {
     /** Browser origins are denied unless they are present in this exact allowlist. */
     allowedOrigins?: readonly string[];
     limits?: Partial<AgentHarnessNetworkLimits>;
+    /** @internal Deterministic HTTP carrier lifecycle observer for transport tests. */
+    onHttpSseCarrierStateChange?: (event: {
+        readonly connectionId: string;
+        readonly sessionId?: string;
+        readonly state: 'attached' | 'detached';
+    }) => void;
     onWarning?: (message: string) => void;
     /** Injectable for deterministic platform checks. */
     platform?: NodeJS.Platform;
@@ -51,4 +57,4 @@ export interface CreateAgentHarnessNetworkListenerOptions {
  * Creates the network-side public listener. The protocol acceptor remains the
  * owner of JSON-RPC validation and initialize/initialized state.
  */
-export declare function createAgentHarnessNetworkListener({ acceptor, listen: rawListen, authenticator, allowInsecureRemote, allowedOrigins, limits: limitOverrides, onWarning, platform, getUid, }: CreateAgentHarnessNetworkListenerOptions): Promise<AgentHarnessListener>;
+export declare function createAgentHarnessNetworkListener({ acceptor, listen: rawListen, authenticator, allowInsecureRemote, allowedOrigins, limits: limitOverrides, onHttpSseCarrierStateChange, onWarning, platform, getUid, }: CreateAgentHarnessNetworkListenerOptions): Promise<AgentHarnessListener>;

package/lib/transport/network.js

@@ -1744,7 +1744,7 @@ function requestPath(request) {
  * Creates the network-side public listener. The protocol acceptor remains the
  * owner of JSON-RPC validation and initialize/initialized state.
  */
-async function createAgentHarnessNetworkListener({ acceptor, listen: rawListen, authenticator, allowInsecureRemote = false, allowedOrigins = [], limits: limitOverrides, onWarning, platform = process.platform, getUid = () => process.getuid?.(), }) {
+async function createAgentHarnessNetworkListener({ acceptor, listen: rawListen, authenticator, allowInsecureRemote = false, allowedOrigins = [], limits: limitOverrides, onHttpSseCarrierStateChange, onWarning, platform = process.platform, getUid = () => process.getuid?.(), }) {
     const listen = normalizeListenAddress(rawListen);
     if (listen.kind === 'unix' && platform === 'win32') {
         throw new Error('Agent Harness unix:// listeners are only supported on POSIX platforms');
@@ -2005,6 +2005,18 @@ async function createAgentHarnessNetworkListener({ acceptor, listen: rawListen,
         response.setHeader('Access-Control-Expose-Headers', `${exports.AGENT_HARNESS_CONNECTION_ID_HEADER}, ${exports.AGENT_HARNESS_SESSION_ID_HEADER}`);
         response.setHeader('Vary', 'Origin');
     }
+    function recordHttpSseCarrierState(connectionId, sessionId, state) {
+        try {
+            onHttpSseCarrierStateChange?.({
+                connectionId,
+                ...(sessionId === undefined ? {} : { sessionId }),
+                state,
+            });
+        }
+        catch {
+            // Observability must never alter carrier ownership or cleanup.
+        }
+    }
     function createHttpConnection(request) {
         const connectionId = (0, node_crypto_1.randomUUID)();
         const holder = {};
@@ -2159,6 +2171,7 @@ async function createAgentHarnessNetworkListener({ acceptor, listen: rawListen,
             sink = new SseSink(response, state.budget, outboundBudget, carrierDisconnected => {
                 if (state.sinks.get(scope) === sink) {
                     state.sinks.delete(scope);
+                    recordHttpSseCarrierState(state.connection.id, sessionId, 'detached');
                 }
                 releaseLease();
                 if (sessionId !== undefined) {
@@ -2177,6 +2190,7 @@ async function createAgentHarnessNetworkListener({ acceptor, listen: rawListen,
             throw error;
         }
         state.sinks.set(scope, sink);
+        recordHttpSseCarrierState(state.connection.id, sessionId, 'attached');
         const backlog = state.backlogs.get(scope) ?? [];
         state.backlogs.delete(scope);
         for (let index = 0; index < backlog.length; index += 1) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-ai/agent-harness",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Standalone JSON-RPC agent harness backed by CodeBuddy Code",
   "license": "MIT",
   "bin": {
@@ -133,8 +133,8 @@
     "@types/ws": "^8.18.1",
     "typescript": "npm:@typescript/typescript6@^6.0.0",
     "vitest": "^4.1.10",
-    "@genie/vitest-config": "0.0.0",
-    "@genie/style-guide": "0.0.0"
+    "@genie/style-guide": "0.0.0",
+    "@genie/vitest-config": "0.0.0"
   },
   "engines": {
     "node": ">=22 <=24"
@@ -253,7 +253,9 @@
     "build:lib": "pnpm --workspace-root exec nx run @genie/agent-harness:build:lib --skipSync",
     "build:lib:run": "pnpm run clean && pnpm run sync:codebuddy:product && tsc --build tsconfig.lib.json executor/tsconfig.json --force && pnpm --dir executor run build:capsule && node scripts/write-product-schema.mjs",
     "build:run": "pnpm run build:lib:run && pnpm run sync:codebuddy:runtime",
+    "build:native:darwin": "node scripts/build-darwin-process-snapshot.mjs",
     "build:native:windows": "node scripts/build-windows-job-launcher.mjs",
+    "check:native:darwin": "node scripts/build-darwin-process-snapshot.mjs --check",
     "check:native:windows": "node scripts/build-windows-job-launcher.mjs --check",
     "clean": "node -e \"const fs=require('node:fs'); for (const path of ['lib','cli','executor/lib']) fs.rmSync(path, { force: true, recursive: true })\"",
     "lint": "pnpm --dir executor run lint && genie-lint",