@zhushanwen/subagent-engine-sdk 0.6.0 → 0.7.0

package/dist/index.cjs

@@ -6581,12 +6581,11 @@ __export(src_exports, {
   DEFAULT_NATIVE_INTERRUPT_GRACE_MS: () => DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
   DEFAULT_STDERR_KEEP_DAYS: () => DEFAULT_STDERR_KEEP_DAYS,
   DEFAULT_STDERR_MAX_BYTES: () => DEFAULT_STDERR_MAX_BYTES,
+  ENGINE_ABORT_KILL_GRACE_MS: () => ENGINE_ABORT_KILL_GRACE_MS,
   ENGINE_ENV_DENY_LIST: () => ENGINE_ENV_DENY_LIST,
   ENGINE_ENV_L0_INFRA_KEYS: () => ENGINE_ENV_L0_INFRA_KEYS,
   ENGINE_ENV_PREFIXES: () => ENGINE_ENV_PREFIXES,
   ENGINE_ERROR_CODE_PREFIX: () => ENGINE_ERROR_CODE_PREFIX,
-  ENGINE_EVENT_COALESCE_DEFAULT: () => ENGINE_EVENT_COALESCE_DEFAULT,
-  ENGINE_EVENT_COALESCE_ENV: () => ENGINE_EVENT_COALESCE_ENV,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV: () => ENGINE_HOST_REQUEST_TIMEOUT_ENV,
   ENGINE_NODE_ENV: () => ENGINE_NODE_ENV,
   ENGINE_PROTOCOL_ERROR_CODES: () => ENGINE_PROTOCOL_ERROR_CODES,
@@ -6607,7 +6606,10 @@ __export(src_exports, {
   RELAY_ENV_SESSION_ID: () => RELAY_ENV_SESSION_ID,
   RELAY_ENV_SOCKET: () => RELAY_ENV_SOCKET,
   RELAY_EXIT_CODES: () => RELAY_EXIT_CODES,
+  RELAY_FRAME_DIRS: () => RELAY_FRAME_DIRS,
+  RELAY_FRAME_KINDS: () => RELAY_FRAME_KINDS,
   RELAY_PROTOCOL_VERSION: () => RELAY_PROTOCOL_VERSION,
+  RELAY_REJECT_REASONS: () => RELAY_REJECT_REASONS,
   REVERSE_CHANNELS: () => REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS: () => REVERSE_CHANNEL_TIMEOUT_CLASS,
   REVERSE_REQUEST_TIMEOUT_MS: () => REVERSE_REQUEST_TIMEOUT_MS,
@@ -6653,10 +6655,12 @@ __export(src_exports, {
   isReverseRequestFrame: () => isReverseRequestFrame,
   isUiResponse: () => isUiResponse,
   killChain: () => killChain,
+  killPidChain: () => killPidChain,
   notificationFrameSchema: () => notificationFrameSchema,
   parseChannel: () => parseChannel,
   parseCtxModel: () => parseCtxModel,
   probeNodeExecutor: () => probeNodeExecutor,
+  probePidAlive: () => probePidAlive,
   protocolErrorSchema: () => protocolErrorSchema,
   pumpNdjsonLines: () => pumpNdjsonLines,
   readRelayForwardEnv: () => readRelayForwardEnv,
@@ -6675,6 +6679,7 @@ __export(src_exports, {
   rotateStderrLogIfNeeded: () => rotateStderrLogIfNeeded,
   runEngineCliEntry: () => runEngineCliEntry,
   runSessionParamsSchema: () => runSessionParamsSchema,
+  safeKill: () => safeKill,
   sanitizeSeg: () => sanitizeSeg,
   schemaEmulationFailedDetail: () => schemaEmulationFailedDetail,
   sessionIdFromHandle: () => sessionIdFromHandle,
@@ -6709,8 +6714,6 @@ var CRASH_REBUILD_BACKOFF_MS = [
   CRASH_REBUILD_BACKOFF_STEP_3_MS
 ];
 var STDERR_TAIL_CHARS = 400;
-var ENGINE_EVENT_COALESCE_ENV = "TAIJI_ENGINE_EVENT_COALESCE";
-var ENGINE_EVENT_COALESCE_DEFAULT = "0";
 
 // src/protocol/frames.ts
 function isRecord(v) {
@@ -6856,8 +6859,10 @@ var AGENT_EVENT_TYPE_NAMES = [
   // noop-safe: 事件无载荷且现行 reducer 即直接 return——丢弃与处理零差异
   "activity",
   // noop-safe: 纯活性信号，双侧 reducer 恒 no-op（协议语义见 AgentEvent 头注），丢弃零差异
-  "error"
+  "error",
   // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺 lastError 诊断留痕，已写状态不回滚
+  "armed"
+  // noop-safe: 旧宿主无武装等待窗消费点（fail-fast 属宿主新增逻辑），丢弃仅缺武装留痕，schema 强制第一道防线（引擎自查断言）不受损
 ];
 
 // src/protocol/schema.ts
@@ -7243,6 +7248,38 @@ function safeKill(child, signal) {
     );
   }
 }
+function probePidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err.code === "ESRCH") return false;
+    return void 0;
+  }
+}
+function killPidChain(pid, opts = {}) {
+  const graceMs = opts.graceMs ?? DEFAULT_KILL_GRACE_MS;
+  signalPid(pid, "SIGTERM");
+  const escalation = setTimeout(() => {
+    if (probePidAlive(pid) === false) return;
+    if (opts.note !== void 0) {
+      logger.warn(
+        `[kill-chain] ${opts.note} still alive ${graceMs / MS_PER_SECOND}s after SIGTERM, escalating to SIGKILL (pid ${pid})`
+      );
+    }
+    signalPid(pid, "SIGKILL");
+  }, graceMs);
+  if (typeof escalation.unref === "function") escalation.unref();
+}
+function signalPid(pid, signal) {
+  try {
+    process.kill(pid, signal);
+  } catch (err) {
+    logger.debug(
+      `[kill-chain] ${signal} to pid ${pid} failed (already dead = expected): ${toErrorMessage(err)}`
+    );
+  }
+}
 function synthesizeTimeoutOutcome(task, stdoutTail, engineId) {
   return {
     content: "",
@@ -7491,6 +7528,11 @@ function updateFromEvent(record, event) {
     // ── activity：纯活性信号，reducer no-op（协议语义见 contract-types）──
     case "activity":
       return;
+    // ── armed：武装确认回执（[D3 协议版 P6]，协议语义见 contract-types）——监控
+    //    信号不进 record 投影，消费方 = 宿主等待门 + run 事件 journal（C3 第④步
+    //    双侧 reducer no-op 义务的 SDK 侧）
+    case "armed":
+      return;
     default: {
       const _exhaustive = event;
       return _exhaustive;
@@ -7824,6 +7866,7 @@ function buildOutboundChildEnv(opts) {
 // src/spawn.ts
 var import_node_child_process = require("child_process");
 var logger4 = getLogger("engine-sdk/spawn");
+var ENGINE_ABORT_KILL_GRACE_MS = 3e4;
 var FORBIDDEN_OPTION_KEYS = ["detached", "stdio", "stdin", "windowsHide"];
 function spawnEngineChild(opts) {
   for (const key of FORBIDDEN_OPTION_KEYS) {
@@ -7844,7 +7887,12 @@ function spawnEngineChild(opts) {
     opts.signal.addEventListener(
       "abort",
       () => {
-        child.kill("SIGTERM");
+        safeKill(child, "SIGCONT");
+        void killChain(child, {
+          graceMs: ENGINE_ABORT_KILL_GRACE_MS,
+          unrefTimers: true,
+          escalationNote: `engine child (pid ${child.pid ?? "unknown"}) abort`
+        });
       },
       { once: true }
     );
@@ -8192,6 +8240,34 @@ function readRelayForwardEnv(env) {
   return { socket, node, script };
 }
 
+// src/relay-frames.ts
+var RELAY_FRAME_KINDS = {
+  handshake: "handshake",
+  accept: "accept",
+  reject: "reject",
+  data: "data",
+  exit: "exit",
+  /**
+   * goodbye（代理 → runtime，v1）：代理被宿主终止（SIGTERM/SIGINT）前的预告帧——
+   * 宿主侧的正常收割（agent_settled 后杀代理）与异常断连（宿主崩溃/主 pi 死）在
+   * runtime 侧都表现为 socket close，无法区分；goodbye 让正常收割显式自报，runtime
+   * 据此把后续 close 的日志从 warn（kill-on-disconnect）降级为 info（reaped，正常
+   * teardown）。kill 行为本身不变（预告后 child 仍由 runtime 收割）。
+   */
+  goodbye: "goodbye"
+};
+var RELAY_FRAME_DIRS = {
+  down: "down",
+  up: "up",
+  upStderr: "up-stderr"
+};
+var RELAY_REJECT_REASONS = {
+  version: "version",
+  identity: "identity",
+  duplicate: "duplicate",
+  malformed: "malformed"
+};
+
 // src/best-effort.ts
 var logger5 = getLogger("subagents");
 function bestEffort(err, context, level = "debug") {
@@ -8298,12 +8374,11 @@ function runEngineCliEntry(opts) {
   DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
   DEFAULT_STDERR_KEEP_DAYS,
   DEFAULT_STDERR_MAX_BYTES,
+  ENGINE_ABORT_KILL_GRACE_MS,
   ENGINE_ENV_DENY_LIST,
   ENGINE_ENV_L0_INFRA_KEYS,
   ENGINE_ENV_PREFIXES,
   ENGINE_ERROR_CODE_PREFIX,
-  ENGINE_EVENT_COALESCE_DEFAULT,
-  ENGINE_EVENT_COALESCE_ENV,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV,
   ENGINE_NODE_ENV,
   ENGINE_PROTOCOL_ERROR_CODES,
@@ -8324,7 +8399,10 @@ function runEngineCliEntry(opts) {
   RELAY_ENV_SESSION_ID,
   RELAY_ENV_SOCKET,
   RELAY_EXIT_CODES,
+  RELAY_FRAME_DIRS,
+  RELAY_FRAME_KINDS,
   RELAY_PROTOCOL_VERSION,
+  RELAY_REJECT_REASONS,
   REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
   REVERSE_REQUEST_TIMEOUT_MS,
@@ -8370,10 +8448,12 @@ function runEngineCliEntry(opts) {
   isReverseRequestFrame,
   isUiResponse,
   killChain,
+  killPidChain,
   notificationFrameSchema,
   parseChannel,
   parseCtxModel,
   probeNodeExecutor,
+  probePidAlive,
   protocolErrorSchema,
   pumpNdjsonLines,
   readRelayForwardEnv,
@@ -8392,6 +8472,7 @@ function runEngineCliEntry(opts) {
   rotateStderrLogIfNeeded,
   runEngineCliEntry,
   runSessionParamsSchema,
+  safeKill,
   sanitizeSeg,
   schemaEmulationFailedDetail,
   sessionIdFromHandle,

package/dist/index.d.cts

@@ -1,17 +1,16 @@
-export { CANCEL_SETTLE_GRACE_MS, CRASH_REBUILD_BACKOFF_MS, CRASH_REBUILD_MAX_ATTEMPTS, CancelParams, CancelResult, DisposeParams, DisposeResult, ENGINE_EVENT_COALESCE_DEFAULT, ENGINE_EVENT_COALESCE_ENV, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, HostAskUserParams, HostAskUserResult, HostChildSpawnedParams, HostChildStateChangedParams, HostHandleReadyParams, HostLogParams, HostStreamDeltaParams, InitializeParams, InitializeResult, ListModelsParams, ListModelsResult, PROTOCOL_METHODS, PingParams, PingResult, ProbeParams, ProtocolMethod, ProtocolParamsMap, ProtocolResultMap, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, ReadParams, ReverseChannel, ReverseRequestTimeoutClass, RunContextParams, RunParams, RunResult, RunResumeParams, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, ValidateModelParams, ValidateModelResult, errorResponseFrameSchema, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema } from './protocol/index.cjs';
-export { E as ENGINE_ERROR_CODE_PREFIX, a as ENGINE_PROTOCOL_ERROR_CODES, b as ENGINE_TIMEOUT_RECOVERY, c as EngineProtocolErrorCode, d as EngineSdkError, e as ErrorResponseFrame, f as EventNotificationParams, N as NotificationFrame, P as ProtocolError, R as RequestFrame, g as ResponseFrame, h as ReverseRequestFrame, i as ReverseResponseResult, S as STDOUT_TAIL_ECHO_CHARS, j as SuccessResponseFrame, k as assertChatConversationSupported, l as engineConversationUnsupportedError, m as engineProtocolMismatchError, n as engineTimeoutDetail, o as isEngineErrorPassthroughCode, p as isEngineProtocolErrorCode, q as isNotificationFrame, r as isRequestFrame, s as isResponseFrame, t as isReverseRequestFrame, u as schemaEmulationFailedDetail } from './error-codes-CFTOAxva.cjs';
-export { A as AGENT_EVENT_TYPE_NAMES, a as AgentCallOpts, b as AgentEvent, c as AgentEventTypeName, d as AgentFailureKind, e as AgentOutcome, f as AgentOutcomeUsage, g as AgentUsage, h as AgentUsageTotal, i as AssertMutuallyAssignable, E as EngineCapabilities, j as EngineHandleData, I as InternalToolCall, M as ModelCatalogEntry, P as ProbeReport, R as ReplayedTurn, k as ResumeAnchor, S as SessionView, T as ToolCall, l as ToolCallEntry, m as ToolCallResult, n as Turn, W as WorktreeHandle } from './contract-types-DaULkdpG.cjs';
+export { CANCEL_SETTLE_GRACE_MS, CRASH_REBUILD_BACKOFF_MS, CRASH_REBUILD_MAX_ATTEMPTS, CancelParams, CancelResult, DisposeParams, DisposeResult, ENGINE_ERROR_CODE_PREFIX, ENGINE_PROTOCOL_ERROR_CODES, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, ENGINE_TIMEOUT_RECOVERY, EngineProtocolErrorCode, EngineSdkError, ErrorResponseFrame, EventNotificationParams, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, HostAskUserParams, HostAskUserResult, HostChildSpawnedParams, HostChildStateChangedParams, HostHandleReadyParams, HostLogParams, HostStreamDeltaParams, InitializeParams, InitializeResult, ListModelsParams, ListModelsResult, NotificationFrame, PROTOCOL_METHODS, PingParams, PingResult, ProbeParams, ProtocolError, ProtocolMethod, ProtocolParamsMap, ProtocolResultMap, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, ReadParams, RequestFrame, ResponseFrame, ReverseChannel, ReverseRequestFrame, ReverseRequestTimeoutClass, ReverseResponseResult, RunContextParams, RunParams, RunResult, RunResumeParams, STDERR_TAIL_CHARS, STDOUT_TAIL_ECHO_CHARS, SUPPORTED_PROTOCOL_RANGE, SuccessResponseFrame, ValidateModelParams, ValidateModelResult, assertChatConversationSupported, engineConversationUnsupportedError, engineProtocolMismatchError, engineTimeoutDetail, errorResponseFrameSchema, isEngineErrorPassthroughCode, isEngineProtocolErrorCode, isNotificationFrame, isProtocolVersionCompatible, isRequestFrame, isResponseFrame, isReverseRequestFrame, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, schemaEmulationFailedDetail, successResponseFrameSchema } from './protocol/index.cjs';
+export { A as AGENT_EVENT_TYPE_NAMES, a as AgentCallOpts, b as AgentEvent, c as AgentEventTypeName, d as AgentFailureKind, e as AgentOutcome, f as AgentOutcomeUsage, g as AgentUsage, h as AgentUsageTotal, i as AssertMutuallyAssignable, E as EngineCapabilities, j as EngineHandleData, k as EngineProcessModel, I as InternalToolCall, M as ModelCatalogEntry, P as ProbeReport, R as ReplayedTurn, l as ResumeAnchor, S as SessionView, T as ToolCall, m as ToolCallEntry, n as ToolCallResult, o as Turn, W as WorktreeHandle } from './contract-types-DiWyGRXr.cjs';
 export { SCHEMA_EMULATION_TAIL_CHARS, StructuredOutputResult, buildSchemaEmulationSegment, extractAndValidateStructuredOutput } from './schema-emulation.cjs';
 export { ExecutionNestingContext, ExecutionNestingState, NESTED_SPAWN_ENV, NestedSpawnRejectedError, SpawnEnv, assertNotNestedSpawn, buildNestedSpawnEnv } from './nesting-guard.cjs';
 export { CoreLogger, LogLevel, LoggerSink, configureLoggerSink, getLogger, resetLoggerSinkForTests } from './logger.cjs';
-export { DEFAULT_KILL_GRACE_MS, DEFAULT_NATIVE_INTERRUPT_GRACE_MS, HOST_TIMEOUT_ABORT_REASON, KillChainOptions, KillableChild, abortWithFallback, killChain, synthesizeTimeoutOutcome } from './kill-chain.cjs';
+export { DEFAULT_KILL_GRACE_MS, DEFAULT_NATIVE_INTERRUPT_GRACE_MS, HOST_TIMEOUT_ABORT_REASON, KillChainOptions, KillableChild, PidChainOptions, abortWithFallback, killChain, killPidChain, probePidAlive, safeKill, synthesizeTimeoutOutcome } from './kill-chain.cjs';
 export { ReplayRecordView, aggregateUsage, createReplayRecord, eventsToSessionView, sessionIdFromHandle, toReplayedTurn, updateFromEvent } from './journal-replay.cjs';
 export { TAIJI_DATA_DIR_ENV, resetDataDirWarnForTests, resolveEngineDataDir } from './data-dir.cjs';
 export { resolveEngineDir, resolveEnginesRoot, resolveJournalPath, resolvePoolDir, sanitizeSeg } from './paths.cjs';
 export { UiMethod, UiRequest, UiRequestHandler, UiResponse, isUiResponse } from './ui-types.cjs';
 export { ChannelHandler, ExtensionUiRequestLike, ParsedChannel, UiChannelRegistry, createUiChannelRegistry, parseChannel } from './ui-channels.cjs';
 export { BuildOutboundChildEnvOptions, ENGINE_ENV_DENY_LIST, ENGINE_ENV_L0_INFRA_KEYS, ENGINE_ENV_PREFIXES, EngineChildEnvOptions, EngineRelayEnv, buildEngineChildEnv, buildOutboundChildEnv } from './env.cjs';
-export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, EngineChildEnv, EngineSelfDestructOptions, ReverseRequestClock, SpawnEngineChildOptions, armEngineSelfDestruct, pumpNdjsonLines, spawnEngineChild } from './spawn.cjs';
+export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_ABORT_KILL_GRACE_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, EngineChildEnv, EngineSelfDestructOptions, ReverseRequestClock, SpawnEngineChildOptions, armEngineSelfDestruct, pumpNdjsonLines, spawnEngineChild } from './spawn.cjs';
 export { ENGINE_NODE_ENV, EngineNodeHostKind, EngineNodeLaunch, EngineNodeLaunchOptions, hostKindOf, probeNodeExecutor, resetEngineNodeProbeCache, resolveEngineNodeLaunch } from './node-executor.cjs';
 export { CleanupResult, DEFAULT_STDERR_KEEP_DAYS, DEFAULT_STDERR_MAX_BYTES, StderrRotationParams, cleanupSiblingStderrLogs, cleanupStaleStderrLogs, isPidAlive, rotateStderrLogIfNeeded, stderrLogPathFor, stderrLogPidOf, stderrRotationParams } from './logs/stderr-rotation.cjs';
 export { ZCODE_HOST_DB_SUFFIX, ZCODE_ISOLATED_DB_SEGMENTS } from './zcode-db-paths.cjs';
@@ -22,3 +21,38 @@ export { replayJournal } from './journal-io.cjs';
 export { EngineAgentCallOpts, EngineCtxModel, EngineHandle, EnginePort, EngineRunResult, EngineStream, RunContext, SHARED_POOL_KEY, parseCtxModel } from './port-contract.cjs';
 export { CliProtocolServerSink, RunEngineCliEntryOptions, runEngineCliEntry } from './cli-entry.cjs';
 import 'node:child_process';
+
+/** 帧类型判别值（kind 字段词表）。as const 值即字面量类型——类型位置同样可用。 */
+declare const RELAY_FRAME_KINDS: {
+    readonly handshake: "handshake";
+    readonly accept: "accept";
+    readonly reject: "reject";
+    readonly data: "data";
+    readonly exit: "exit";
+    /**
+     * goodbye（代理 → runtime，v1）：代理被宿主终止（SIGTERM/SIGINT）前的预告帧——
+     * 宿主侧的正常收割（agent_settled 后杀代理）与异常断连（宿主崩溃/主 pi 死）在
+     * runtime 侧都表现为 socket close，无法区分；goodbye 让正常收割显式自报，runtime
+     * 据此把后续 close 的日志从 warn（kill-on-disconnect）降级为 info（reaped，正常
+     * teardown）。kill 行为本身不变（预告后 child 仍由 runtime 收割）。
+     */
+    readonly goodbye: "goodbye";
+};
+/** 数据泵方向（data 帧 dir 字段词表）。 */
+declare const RELAY_FRAME_DIRS: {
+    readonly down: "down";
+    readonly up: "up";
+    readonly upStderr: "up-stderr";
+};
+/** reject 帧 reason 词表（runtime→代理的拒绝理由；代理对 version 以退出码 10 应答）。 */
+declare const RELAY_REJECT_REASONS: {
+    readonly version: "version";
+    readonly identity: "identity";
+    readonly duplicate: "duplicate";
+    readonly malformed: "malformed";
+};
+type RelayFrameKind = (typeof RELAY_FRAME_KINDS)[keyof typeof RELAY_FRAME_KINDS];
+type RelayFrameDir = (typeof RELAY_FRAME_DIRS)[keyof typeof RELAY_FRAME_DIRS];
+type RelayRejectReason = (typeof RELAY_REJECT_REASONS)[keyof typeof RELAY_REJECT_REASONS];
+
+export { RELAY_FRAME_DIRS, RELAY_FRAME_KINDS, RELAY_REJECT_REASONS, type RelayFrameDir, type RelayFrameKind, type RelayRejectReason };

package/dist/index.d.ts

@@ -1,17 +1,16 @@
-export { CANCEL_SETTLE_GRACE_MS, CRASH_REBUILD_BACKOFF_MS, CRASH_REBUILD_MAX_ATTEMPTS, CancelParams, CancelResult, DisposeParams, DisposeResult, ENGINE_EVENT_COALESCE_DEFAULT, ENGINE_EVENT_COALESCE_ENV, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, HostAskUserParams, HostAskUserResult, HostChildSpawnedParams, HostChildStateChangedParams, HostHandleReadyParams, HostLogParams, HostStreamDeltaParams, InitializeParams, InitializeResult, ListModelsParams, ListModelsResult, PROTOCOL_METHODS, PingParams, PingResult, ProbeParams, ProtocolMethod, ProtocolParamsMap, ProtocolResultMap, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, ReadParams, ReverseChannel, ReverseRequestTimeoutClass, RunContextParams, RunParams, RunResult, RunResumeParams, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, ValidateModelParams, ValidateModelResult, errorResponseFrameSchema, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema } from './protocol/index.js';
-export { E as ENGINE_ERROR_CODE_PREFIX, a as ENGINE_PROTOCOL_ERROR_CODES, b as ENGINE_TIMEOUT_RECOVERY, c as EngineProtocolErrorCode, d as EngineSdkError, e as ErrorResponseFrame, f as EventNotificationParams, N as NotificationFrame, P as ProtocolError, R as RequestFrame, g as ResponseFrame, h as ReverseRequestFrame, i as ReverseResponseResult, S as STDOUT_TAIL_ECHO_CHARS, j as SuccessResponseFrame, k as assertChatConversationSupported, l as engineConversationUnsupportedError, m as engineProtocolMismatchError, n as engineTimeoutDetail, o as isEngineErrorPassthroughCode, p as isEngineProtocolErrorCode, q as isNotificationFrame, r as isRequestFrame, s as isResponseFrame, t as isReverseRequestFrame, u as schemaEmulationFailedDetail } from './error-codes-C9BOUI5H.js';
-export { A as AGENT_EVENT_TYPE_NAMES, a as AgentCallOpts, b as AgentEvent, c as AgentEventTypeName, d as AgentFailureKind, e as AgentOutcome, f as AgentOutcomeUsage, g as AgentUsage, h as AgentUsageTotal, i as AssertMutuallyAssignable, E as EngineCapabilities, j as EngineHandleData, I as InternalToolCall, M as ModelCatalogEntry, P as ProbeReport, R as ReplayedTurn, k as ResumeAnchor, S as SessionView, T as ToolCall, l as ToolCallEntry, m as ToolCallResult, n as Turn, W as WorktreeHandle } from './contract-types-DaULkdpG.js';
+export { CANCEL_SETTLE_GRACE_MS, CRASH_REBUILD_BACKOFF_MS, CRASH_REBUILD_MAX_ATTEMPTS, CancelParams, CancelResult, DisposeParams, DisposeResult, ENGINE_ERROR_CODE_PREFIX, ENGINE_PROTOCOL_ERROR_CODES, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, ENGINE_TIMEOUT_RECOVERY, EngineProtocolErrorCode, EngineSdkError, ErrorResponseFrame, EventNotificationParams, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, HostAskUserParams, HostAskUserResult, HostChildSpawnedParams, HostChildStateChangedParams, HostHandleReadyParams, HostLogParams, HostStreamDeltaParams, InitializeParams, InitializeResult, ListModelsParams, ListModelsResult, NotificationFrame, PROTOCOL_METHODS, PingParams, PingResult, ProbeParams, ProtocolError, ProtocolMethod, ProtocolParamsMap, ProtocolResultMap, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, ReadParams, RequestFrame, ResponseFrame, ReverseChannel, ReverseRequestFrame, ReverseRequestTimeoutClass, ReverseResponseResult, RunContextParams, RunParams, RunResult, RunResumeParams, STDERR_TAIL_CHARS, STDOUT_TAIL_ECHO_CHARS, SUPPORTED_PROTOCOL_RANGE, SuccessResponseFrame, ValidateModelParams, ValidateModelResult, assertChatConversationSupported, engineConversationUnsupportedError, engineProtocolMismatchError, engineTimeoutDetail, errorResponseFrameSchema, isEngineErrorPassthroughCode, isEngineProtocolErrorCode, isNotificationFrame, isProtocolVersionCompatible, isRequestFrame, isResponseFrame, isReverseRequestFrame, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, schemaEmulationFailedDetail, successResponseFrameSchema } from './protocol/index.js';
+export { A as AGENT_EVENT_TYPE_NAMES, a as AgentCallOpts, b as AgentEvent, c as AgentEventTypeName, d as AgentFailureKind, e as AgentOutcome, f as AgentOutcomeUsage, g as AgentUsage, h as AgentUsageTotal, i as AssertMutuallyAssignable, E as EngineCapabilities, j as EngineHandleData, k as EngineProcessModel, I as InternalToolCall, M as ModelCatalogEntry, P as ProbeReport, R as ReplayedTurn, l as ResumeAnchor, S as SessionView, T as ToolCall, m as ToolCallEntry, n as ToolCallResult, o as Turn, W as WorktreeHandle } from './contract-types-DiWyGRXr.js';
 export { SCHEMA_EMULATION_TAIL_CHARS, StructuredOutputResult, buildSchemaEmulationSegment, extractAndValidateStructuredOutput } from './schema-emulation.js';
 export { ExecutionNestingContext, ExecutionNestingState, NESTED_SPAWN_ENV, NestedSpawnRejectedError, SpawnEnv, assertNotNestedSpawn, buildNestedSpawnEnv } from './nesting-guard.js';
 export { CoreLogger, LogLevel, LoggerSink, configureLoggerSink, getLogger, resetLoggerSinkForTests } from './logger.js';
-export { DEFAULT_KILL_GRACE_MS, DEFAULT_NATIVE_INTERRUPT_GRACE_MS, HOST_TIMEOUT_ABORT_REASON, KillChainOptions, KillableChild, abortWithFallback, killChain, synthesizeTimeoutOutcome } from './kill-chain.js';
+export { DEFAULT_KILL_GRACE_MS, DEFAULT_NATIVE_INTERRUPT_GRACE_MS, HOST_TIMEOUT_ABORT_REASON, KillChainOptions, KillableChild, PidChainOptions, abortWithFallback, killChain, killPidChain, probePidAlive, safeKill, synthesizeTimeoutOutcome } from './kill-chain.js';
 export { ReplayRecordView, aggregateUsage, createReplayRecord, eventsToSessionView, sessionIdFromHandle, toReplayedTurn, updateFromEvent } from './journal-replay.js';
 export { TAIJI_DATA_DIR_ENV, resetDataDirWarnForTests, resolveEngineDataDir } from './data-dir.js';
 export { resolveEngineDir, resolveEnginesRoot, resolveJournalPath, resolvePoolDir, sanitizeSeg } from './paths.js';
 export { UiMethod, UiRequest, UiRequestHandler, UiResponse, isUiResponse } from './ui-types.js';
 export { ChannelHandler, ExtensionUiRequestLike, ParsedChannel, UiChannelRegistry, createUiChannelRegistry, parseChannel } from './ui-channels.js';
 export { BuildOutboundChildEnvOptions, ENGINE_ENV_DENY_LIST, ENGINE_ENV_L0_INFRA_KEYS, ENGINE_ENV_PREFIXES, EngineChildEnvOptions, EngineRelayEnv, buildEngineChildEnv, buildOutboundChildEnv } from './env.js';
-export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, EngineChildEnv, EngineSelfDestructOptions, ReverseRequestClock, SpawnEngineChildOptions, armEngineSelfDestruct, pumpNdjsonLines, spawnEngineChild } from './spawn.js';
+export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_ABORT_KILL_GRACE_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, EngineChildEnv, EngineSelfDestructOptions, ReverseRequestClock, SpawnEngineChildOptions, armEngineSelfDestruct, pumpNdjsonLines, spawnEngineChild } from './spawn.js';
 export { ENGINE_NODE_ENV, EngineNodeHostKind, EngineNodeLaunch, EngineNodeLaunchOptions, hostKindOf, probeNodeExecutor, resetEngineNodeProbeCache, resolveEngineNodeLaunch } from './node-executor.js';
 export { CleanupResult, DEFAULT_STDERR_KEEP_DAYS, DEFAULT_STDERR_MAX_BYTES, StderrRotationParams, cleanupSiblingStderrLogs, cleanupStaleStderrLogs, isPidAlive, rotateStderrLogIfNeeded, stderrLogPathFor, stderrLogPidOf, stderrRotationParams } from './logs/stderr-rotation.js';
 export { ZCODE_HOST_DB_SUFFIX, ZCODE_ISOLATED_DB_SEGMENTS } from './zcode-db-paths.js';
@@ -22,3 +21,38 @@ export { replayJournal } from './journal-io.js';
 export { EngineAgentCallOpts, EngineCtxModel, EngineHandle, EnginePort, EngineRunResult, EngineStream, RunContext, SHARED_POOL_KEY, parseCtxModel } from './port-contract.js';
 export { CliProtocolServerSink, RunEngineCliEntryOptions, runEngineCliEntry } from './cli-entry.js';
 import 'node:child_process';
+
+/** 帧类型判别值（kind 字段词表）。as const 值即字面量类型——类型位置同样可用。 */
+declare const RELAY_FRAME_KINDS: {
+    readonly handshake: "handshake";
+    readonly accept: "accept";
+    readonly reject: "reject";
+    readonly data: "data";
+    readonly exit: "exit";
+    /**
+     * goodbye（代理 → runtime，v1）：代理被宿主终止（SIGTERM/SIGINT）前的预告帧——
+     * 宿主侧的正常收割（agent_settled 后杀代理）与异常断连（宿主崩溃/主 pi 死）在
+     * runtime 侧都表现为 socket close，无法区分；goodbye 让正常收割显式自报，runtime
+     * 据此把后续 close 的日志从 warn（kill-on-disconnect）降级为 info（reaped，正常
+     * teardown）。kill 行为本身不变（预告后 child 仍由 runtime 收割）。
+     */
+    readonly goodbye: "goodbye";
+};
+/** 数据泵方向（data 帧 dir 字段词表）。 */
+declare const RELAY_FRAME_DIRS: {
+    readonly down: "down";
+    readonly up: "up";
+    readonly upStderr: "up-stderr";
+};
+/** reject 帧 reason 词表（runtime→代理的拒绝理由；代理对 version 以退出码 10 应答）。 */
+declare const RELAY_REJECT_REASONS: {
+    readonly version: "version";
+    readonly identity: "identity";
+    readonly duplicate: "duplicate";
+    readonly malformed: "malformed";
+};
+type RelayFrameKind = (typeof RELAY_FRAME_KINDS)[keyof typeof RELAY_FRAME_KINDS];
+type RelayFrameDir = (typeof RELAY_FRAME_DIRS)[keyof typeof RELAY_FRAME_DIRS];
+type RelayRejectReason = (typeof RELAY_REJECT_REASONS)[keyof typeof RELAY_REJECT_REASONS];
+
+export { RELAY_FRAME_DIRS, RELAY_FRAME_KINDS, RELAY_REJECT_REASONS, type RelayFrameDir, type RelayFrameKind, type RelayRejectReason };

package/dist/index.js

@@ -38,18 +38,19 @@ import {
 } from "./chunk-YL5W5EMV.js";
 import {
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
+  ENGINE_ABORT_KILL_GRACE_MS,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV,
   armEngineSelfDestruct,
   pumpNdjsonLines,
   spawnEngineChild
-} from "./chunk-CNQTJJF5.js";
+} from "./chunk-HERD6RIR.js";
 import {
   ENGINE_NODE_ENV,
   hostKindOf,
   probeNodeExecutor,
   resetEngineNodeProbeCache,
   resolveEngineNodeLaunch
-} from "./chunk-W3BKI2BP.js";
+} from "./chunk-3WC36CHI.js";
 import {
   DEFAULT_STDERR_KEEP_DAYS,
   DEFAULT_STDERR_MAX_BYTES,
@@ -90,7 +91,7 @@ import {
   reverseRequestFrameSchema,
   runSessionParamsSchema,
   successResponseFrameSchema
-} from "./chunk-63ZNJHM5.js";
+} from "./chunk-W23PAAGX.js";
 import {
   SCHEMA_EMULATION_TAIL_CHARS,
   buildSchemaEmulationSegment,
@@ -109,8 +110,11 @@ import {
   HOST_TIMEOUT_ABORT_REASON,
   abortWithFallback,
   killChain,
+  killPidChain,
+  probePidAlive,
+  safeKill,
   synthesizeTimeoutOutcome
-} from "./chunk-QOEXD2FT.js";
+} from "./chunk-RCT7L777.js";
 import {
   toErrorMessage
 } from "./chunk-PYO3YR7W.js";
@@ -119,8 +123,6 @@ import {
   CRASH_REBUILD_BACKOFF_MS,
   CRASH_REBUILD_MAX_ATTEMPTS,
   ENGINE_ERROR_CODE_PREFIX,
-  ENGINE_EVENT_COALESCE_DEFAULT,
-  ENGINE_EVENT_COALESCE_ENV,
   ENGINE_PROTOCOL_ERROR_CODES,
   ENGINE_PROTOCOL_VERSION,
   ENGINE_TIMEOUT_RECOVERY,
@@ -138,7 +140,7 @@ import {
   isEngineProtocolErrorCode,
   isProtocolVersionCompatible,
   schemaEmulationFailedDetail
-} from "./chunk-WMDMXP2F.js";
+} from "./chunk-SFNTX7Q3.js";
 import {
   aggregateUsage,
   createReplayRecord,
@@ -146,7 +148,7 @@ import {
   sessionIdFromHandle,
   toReplayedTurn,
   updateFromEvent
-} from "./chunk-AIG5LSGK.js";
+} from "./chunk-SGAIDL63.js";
 import {
   TAIJI_DATA_DIR_ENV,
   resetDataDirWarnForTests,
@@ -158,6 +160,34 @@ import {
   resetLoggerSinkForTests
 } from "./chunk-75QEMUGV.js";
 import "./chunk-JSBRDJBE.js";
+
+// src/relay-frames.ts
+var RELAY_FRAME_KINDS = {
+  handshake: "handshake",
+  accept: "accept",
+  reject: "reject",
+  data: "data",
+  exit: "exit",
+  /**
+   * goodbye（代理 → runtime，v1）：代理被宿主终止（SIGTERM/SIGINT）前的预告帧——
+   * 宿主侧的正常收割（agent_settled 后杀代理）与异常断连（宿主崩溃/主 pi 死）在
+   * runtime 侧都表现为 socket close，无法区分；goodbye 让正常收割显式自报，runtime
+   * 据此把后续 close 的日志从 warn（kill-on-disconnect）降级为 info（reaped，正常
+   * teardown）。kill 行为本身不变（预告后 child 仍由 runtime 收割）。
+   */
+  goodbye: "goodbye"
+};
+var RELAY_FRAME_DIRS = {
+  down: "down",
+  up: "up",
+  upStderr: "up-stderr"
+};
+var RELAY_REJECT_REASONS = {
+  version: "version",
+  identity: "identity",
+  duplicate: "duplicate",
+  malformed: "malformed"
+};
 export {
   AGENT_EVENT_TYPE_NAMES,
   CANCEL_SETTLE_GRACE_MS,
@@ -168,12 +198,11 @@ export {
   DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
   DEFAULT_STDERR_KEEP_DAYS,
   DEFAULT_STDERR_MAX_BYTES,
+  ENGINE_ABORT_KILL_GRACE_MS,
   ENGINE_ENV_DENY_LIST,
   ENGINE_ENV_L0_INFRA_KEYS,
   ENGINE_ENV_PREFIXES,
   ENGINE_ERROR_CODE_PREFIX,
-  ENGINE_EVENT_COALESCE_DEFAULT,
-  ENGINE_EVENT_COALESCE_ENV,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV,
   ENGINE_NODE_ENV,
   ENGINE_PROTOCOL_ERROR_CODES,
@@ -194,7 +223,10 @@ export {
   RELAY_ENV_SESSION_ID,
   RELAY_ENV_SOCKET,
   RELAY_EXIT_CODES,
+  RELAY_FRAME_DIRS,
+  RELAY_FRAME_KINDS,
   RELAY_PROTOCOL_VERSION,
+  RELAY_REJECT_REASONS,
   REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
   REVERSE_REQUEST_TIMEOUT_MS,
@@ -240,10 +272,12 @@ export {
   isReverseRequestFrame,
   isUiResponse,
   killChain,
+  killPidChain,
   notificationFrameSchema,
   parseChannel,
   parseCtxModel,
   probeNodeExecutor,
+  probePidAlive,
   protocolErrorSchema,
   pumpNdjsonLines,
   readRelayForwardEnv,
@@ -262,6 +296,7 @@ export {
   rotateStderrLogIfNeeded,
   runEngineCliEntry,
   runSessionParamsSchema,
+  safeKill,
   sanitizeSeg,
   schemaEmulationFailedDetail,
   sessionIdFromHandle,

package/dist/journal-io.d.cts

@@ -1,4 +1,4 @@
-import { b as AgentEvent } from './contract-types-DaULkdpG.cjs';
+import { b as AgentEvent } from './contract-types-DiWyGRXr.cjs';
 
 /**
  * 重放 journal：读取路径下全部事件，重放即得 AgentEvent 流（read 第②级）。

package/dist/journal-io.d.ts

@@ -1,4 +1,4 @@
-import { b as AgentEvent } from './contract-types-DaULkdpG.js';
+import { b as AgentEvent } from './contract-types-DiWyGRXr.js';
 
 /**
  * 重放 journal：读取路径下全部事件，重放即得 AgentEvent 流（read 第②级）。

package/dist/journal-replay.cjs

@@ -196,6 +196,11 @@ function updateFromEvent(record, event) {
     // ── activity：纯活性信号，reducer no-op（协议语义见 contract-types）──
     case "activity":
       return;
+    // ── armed：武装确认回执（[D3 协议版 P6]，协议语义见 contract-types）——监控
+    //    信号不进 record 投影，消费方 = 宿主等待门 + run 事件 journal（C3 第④步
+    //    双侧 reducer no-op 义务的 SDK 侧）
+    case "armed":
+      return;
     default: {
       const _exhaustive = event;
       return _exhaustive;

package/dist/journal-replay.d.cts

@@ -1,4 +1,4 @@
-import { n as Turn, h as AgentUsageTotal, b as AgentEvent, S as SessionView, j as EngineHandleData, R as ReplayedTurn } from './contract-types-DaULkdpG.cjs';
+import { o as Turn, h as AgentUsageTotal, b as AgentEvent, S as SessionView, j as EngineHandleData, R as ReplayedTurn } from './contract-types-DiWyGRXr.cjs';
 
 /**
  * reducer 的 record 视图（core ExecutionRecord 的结构子集：reducer 只触碰这四个字段）。

package/dist/journal-replay.d.ts

@@ -1,4 +1,4 @@
-import { n as Turn, h as AgentUsageTotal, b as AgentEvent, S as SessionView, j as EngineHandleData, R as ReplayedTurn } from './contract-types-DaULkdpG.js';
+import { o as Turn, h as AgentUsageTotal, b as AgentEvent, S as SessionView, j as EngineHandleData, R as ReplayedTurn } from './contract-types-DiWyGRXr.js';
 
 /**
  * reducer 的 record 视图（core ExecutionRecord 的结构子集：reducer 只触碰这四个字段）。

package/dist/journal-replay.js

@@ -5,7 +5,7 @@ import {
   sessionIdFromHandle,
   toReplayedTurn,
   updateFromEvent
-} from "./chunk-AIG5LSGK.js";
+} from "./chunk-SGAIDL63.js";
 import "./chunk-JSBRDJBE.js";
 export {
   aggregateUsage,

package/dist/kill-chain.cjs

@@ -23,9 +23,11 @@ __export(kill_chain_exports, {
   DEFAULT_KILL_GRACE_MS: () => DEFAULT_KILL_GRACE_MS,
   DEFAULT_NATIVE_INTERRUPT_GRACE_MS: () => DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
   HOST_TIMEOUT_ABORT_REASON: () => HOST_TIMEOUT_ABORT_REASON,
-  STDOUT_TAIL_ECHO_CHARS: () => STDOUT_TAIL_ECHO_CHARS,
   abortWithFallback: () => abortWithFallback,
   killChain: () => killChain,
+  killPidChain: () => killPidChain,
+  probePidAlive: () => probePidAlive,
+  safeKill: () => safeKill,
   synthesizeTimeoutOutcome: () => synthesizeTimeoutOutcome
 });
 module.exports = __toCommonJS(kill_chain_exports);
@@ -131,6 +133,38 @@ function safeKill(child, signal) {
     );
   }
 }
+function probePidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err.code === "ESRCH") return false;
+    return void 0;
+  }
+}
+function killPidChain(pid, opts = {}) {
+  const graceMs = opts.graceMs ?? DEFAULT_KILL_GRACE_MS;
+  signalPid(pid, "SIGTERM");
+  const escalation = setTimeout(() => {
+    if (probePidAlive(pid) === false) return;
+    if (opts.note !== void 0) {
+      logger.warn(
+        `[kill-chain] ${opts.note} still alive ${graceMs / MS_PER_SECOND}s after SIGTERM, escalating to SIGKILL (pid ${pid})`
+      );
+    }
+    signalPid(pid, "SIGKILL");
+  }, graceMs);
+  if (typeof escalation.unref === "function") escalation.unref();
+}
+function signalPid(pid, signal) {
+  try {
+    process.kill(pid, signal);
+  } catch (err) {
+    logger.debug(
+      `[kill-chain] ${signal} to pid ${pid} failed (already dead = expected): ${toErrorMessage(err)}`
+    );
+  }
+}
 function synthesizeTimeoutOutcome(task, stdoutTail, engineId) {
   return {
     content: "",
@@ -214,8 +248,10 @@ function raceTimeout(p, ms, unref = false) {
   DEFAULT_KILL_GRACE_MS,
   DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
   HOST_TIMEOUT_ABORT_REASON,
-  STDOUT_TAIL_ECHO_CHARS,
   abortWithFallback,
   killChain,
+  killPidChain,
+  probePidAlive,
+  safeKill,
   synthesizeTimeoutOutcome
 });