@sema-agent/client-core 0.7.0 → 0.8.1

package/dist/subagent/engineTaskHandleWire.js

@@ -0,0 +1,213 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6):cli `src/sema/engineTaskHandleWire.ts` 整搬。
+ *
+ * 🔴 搬迁差分:`wireConfig()` → `engineWireTarget()`;`getActiveEngineTaskId()` →
+ *    `activeEngineRunId()`;`logForDebugging` → `hostLog`;`process.env.SEMA_DEBUG` 前置判
+ *    → `engineWireDebugEnabled()`。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * engineTaskHandleWire — CC TaskOutput/TaskStop 人侧对位的 wire 消费([1501] server 1.246.0 /
+ * SDK 0.0.67 提货)。
+ *
+ * Wire(两面都是出生即强制带 `?session=`,与 subagentOutput 同姿势;非阻塞、副本本地):
+ *   · 读:`GET  /v1/runs/:id/tasks/:handle/output?session=` → SDK `runs.taskOutput`
+ *   · 停:`POST /v1/runs/:id/tasks/:handle/stop?session=`   → SDK `runs.taskStop`
+ *   · :id = 宿主 run;:handle = canonical 句柄 ONLY(b… bash / m… monitor / a… agent)——
+ *     不收名字、不收 legacy shellId,传了就是 404;workflow(w…/wa…)恒 404(journal 是那边的
+ *     读面,永不打这里)。
+ *   · 能力门 = capabilities.taskHandles(engineCapsCache 通用缓存,[1501] 明令:用能力位判断,
+ *     别 trial-by-501/404)。老引擎(≤1.245)缺该键 → 两动词都回落 null/不可用,version-safe。
+ *
+ * 读面游标语义([1501]§一 + [1505] must-fix 修正,UI 必须按此做):是否「读即消费」取决于句柄
+ * 形态——spooled 腿全量可重读、GET 幂等;cursor-only 腿每次 GET 只出新字节、读走就没了。
+ * 两形判别用 **wire 契约自带标记**(server [1505] 钉版承诺稳定,变更走 CHANGELOG+黑板;core
+ * CC-verbatim 固定形):content 含 `--- stdout (full, re-readable) ---` = spool 全量形 → 整体
+ * 替换;含 `--- new stdout ---` = cursor 增量形 → append。初版的「前缀延展」启发式被 [1505]
+ * 否决——spool content 首行 `status: <displayStatus>` 在任务完成时刻从 running 翻 exited,
+ * 前缀检测恰在最常见时刻失败 → 全量被 append = 输出重复。无标记(极端/未知形)按保守形
+ * append-if-changed 处理;空 content 不动累积。绝不假设重拉能拿到同样字节。
+ *
+ * ⚠️ cursor-only 腿双消费者 caveat([1505]):同一 b* 句柄若同时被模型侧 TaskOutput 工具读,
+ * 两个消费者互抢增量(工具读走的字节本读面拿不到,反之亦然),端侧累积在该形下不保证完整;
+ * spool 腿(server 正常接线下的常态)无此问题。UI 在 cursor 形下不承诺完整性。
+ *
+ * 停面语义([1501]§二):**只有 200 算停了**;409 `stop.not_landed` = kill 没落地、进程可能
+ * 还在跑(UI 绝不能渲染成「已停止」);终态句柄重复 stop 幂等诚实(200,状态照实)。
+ *
+ * `?filter=` 禁用(带了=400):CC 的 filter 语义由调用方拿回 content 后本地做,本模块不透传。
+ */
+import { TaskStopConflictError } from '@sema-agent/sdk';
+import { hostLog } from '../host.js';
+import { makeEngineWireClient } from '../engineWireSdk.js';
+import { engineWireDebugEnabled, engineWireTarget } from '../engineWireTarget.js';
+import { activeEngineRunId, engineSessionParamSpread } from '../engineSessionParam.js';
+import { getBgParentRun } from '../subagentContentStore.js';
+import { engineTaskHandlesCapable } from './engineRowStopGate.js';
+// 能力门同步读口:真源在零依赖叶 `engineRowStopGate`(batch-stop 同步分类不拉本模块 SDK 图)。
+// ⚠️ 此处**不再 re-export**——它与原定义同进 index.ts 的 `export *` barrel 会构成双出口,
+// esbuild 对 star-export 歧义直接 build 失败(tsc 同源 symbol 不报=假绿;0.8.0 壳收批实撞,
+// idle-terminal-settle 套逮住)。包内消费者直接 import 原叶。
+/** 宿主 run 解析:fleet 行/通知帧喂的 parent 映射优先(行 id=`${runId} ${handle}` 的 parentId
+ *  投影),缺席退当前交互 run(register 时刻的活跃 run 即宿主——engineSide bash 行的出生形)。 */
+function resolveHostRun(handle) {
+    return getBgParentRun(handle) ?? activeEngineRunId() ?? null;
+}
+// 游标累积(按 handle;进程内存态,与查看态生命周期同级——端重启即空,重读从引擎再取)
+const accumulated = new Map();
+/** 测试钩:清累积缓存。 */
+export function __resetTaskHandleWireForTests() {
+    accumulated.clear();
+}
+/**
+ * 读一个引擎侧任务句柄的输出(新面 A)。null = 读不到(无 wire / caps 缺 / 无宿主 run / 404
+ * 域外或已 reap / 网错)——调用方回落既有渲染(receipt/outputFile tail)。绝不 throw。
+ */
+export async function fetchEngineTaskOutput(handle, opts) {
+    const cfg = engineWireTarget();
+    if (!cfg || !engineTaskHandlesCapable())
+        return null;
+    const runId = resolveHostRun(handle);
+    if (!runId)
+        return null;
+    const client = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.token ? { token: cfg.token } : {}),
+        principal: cfg.principal,
+    });
+    if (!client)
+        return null;
+    try {
+        const r = await client.runs.taskOutput(runId, handle, {
+            ...(opts?.signal ? { signal: opts.signal } : {}),
+            ...engineSessionParamSpread(),
+        });
+        const fresh = typeof r?.content === 'string' ? r.content : '';
+        const prev = accumulated.get(handle) ?? '';
+        const merged = mergeTaskOutput(prev, fresh);
+        accumulated.set(handle, merged);
+        const out = r?.output ?? {};
+        if (engineWireDebugEnabled()) {
+            hostLog('debug', `[task-handle] output ${handle} via run ${runId}: ok fresh=${fresh.length}b merged=${merged.length}b status=${typeof out.status === 'string' ? out.status : '-'}`);
+        }
+        return {
+            content: merged,
+            ...(typeof out.status === 'string' ? { status: out.status } : {}),
+            ...(typeof out.stoppedBy === 'string' ? { stoppedBy: out.stoppedBy } : {}),
+            ...(out.partial_result === true ? { partialResult: true } : {}),
+        };
+    }
+    catch (e) {
+        const status = e?.status;
+        hostLog('debug', `[task-handle] output ${handle} via run ${runId}: ${typeof status === 'number' ? status : String(e).slice(0, 160)}`);
+        return null;
+    }
+}
+/**
+ * [1505] 契约标记判别(头注):spool 全量 → 替换;cursor 增量 → append;无标记 → 保守
+ * append-if-changed(与上次逐字节相同视为幂等重读,不重复)。空 content 不动累积。
+ * 🔴 B6 提出成具名纯函数 —— 它是这条读面唯一会「把输出显示成两遍」的地方,值得被直接断言。
+ */
+export function mergeTaskOutput(prev, fresh) {
+    if (fresh.length === 0)
+        return prev;
+    if (fresh.includes('--- stdout (full, re-readable) ---'))
+        return fresh;
+    if (fresh.includes('--- new stdout ---'))
+        return prev + fresh;
+    return fresh === prev ? prev : prev + fresh;
+}
+/**
+ * 🔴 **G13 删债(先红后绿)**:taskStop 的 409 冲突分类 —— 手抄 code 判 → typed
+ * `TaskStopConflictError`(SDK 把**任何** `stop.*` 前缀码映到该类,errors.js:277-278;
+ * SDK 自己的注释还点名了壳的手抄位置 `engineTaskHandleWire.ts:186-197`)。
+ *
+ * 手抄版的实际缺陷(pure 门先红实证):SDK 明列**五**形,手抄只认前四形 ⇒ 第五形
+ * `stop.park_arbiter_unreachable`(core 1.397 三分:仲裁店不可达 ⇒ **真相未知**)静默塌进
+ * `not_landed`。
+ * 🔴 后果方向先定正负号([anchor-on-the-deciding-quantity]):门控的量 = 「UI 翻不翻这一行」,
+ *    五形与 default **全都是不翻** ⇒ 这不是安全缺陷,是**诚实缺陷** —— 把「真相未知」渲染成
+ *    「kill 没落地」,用户与诊断双双被误导。所以修法是给第五形一个自己的名字,而不是调整门。
+ *
+ * 开集纪律:`switch` 留 `default`(未来新 `stop.*` 码落 `unknown_conflict`,照样不翻行、
+ * 照样带原始 `code`),绝不塌进任何一个已知形 —— 塌进去就等于替 server 编了一个它没说的原因。
+ */
+export function classifyTaskStopConflict(e) {
+    const detail = e instanceof Error ? e.message : String(e);
+    const raw = e?.code;
+    // typed 优先:SDK ≥0.0.11x 恒给 TaskStopConflictError 且 `code` 是 errorCode 原文。
+    // 兜底(老 SDK / 非 typed 抛点):code 非串时从 message 里认字面 —— 与手抄版同姿势,只是
+    // 现在是**回落**而不是主判据。
+    const code = typeof raw === 'string'
+        ? raw
+        : (STOP_CONFLICT_CODES.find(c => detail.includes(c)) ?? '');
+    switch (code) {
+        case 'stop.not_local':
+            return { ok: false, reason: 'not_local', detail };
+        case 'stop.parked':
+            return { ok: false, reason: 'parked', detail };
+        case 'stop.park_resume_won':
+            return { ok: false, reason: 'park_resume_won', detail };
+        case 'stop.park_arbiter_unreachable':
+            return { ok: false, reason: 'park_arbiter_unreachable', detail };
+        case 'stop.not_landed':
+            return { ok: false, reason: 'not_landed', detail };
+        default:
+            // 开集:未知/未来 `stop.*`(以及 code 完全缺席的残破形)。诚实说「有冲突但我不认识它」,
+            // 不冒充 not_landed。UI 处置与其余五形相同(不翻行)。
+            return { ok: false, reason: 'unknown_conflict', detail };
+    }
+}
+/** 兜底字面认码用的已知集(顺序 = 长码优先,避免 `stop.parked` 抢走 `stop.park_resume_won`)。 */
+const STOP_CONFLICT_CODES = [
+    'stop.park_arbiter_unreachable',
+    'stop.park_resume_won',
+    'stop.not_landed',
+    'stop.not_local',
+    'stop.parked',
+];
+/** 停一个引擎侧任务句柄(新面 B)。只有 ok:true(=HTTP 200)算停了。绝不 throw。 */
+export async function stopEngineTask(handle, opts) {
+    const cfg = engineWireTarget();
+    if (!cfg || !engineTaskHandlesCapable())
+        return { ok: false, reason: 'unavailable' };
+    const runId = resolveHostRun(handle);
+    if (!runId)
+        return { ok: false, reason: 'unavailable', detail: 'no host run mapping' };
+    const client = makeEngineWireClient({
+        baseUrl: cfg.baseUrl,
+        ...(cfg.token ? { token: cfg.token } : {}),
+        principal: cfg.principal,
+    });
+    if (!client)
+        return { ok: false, reason: 'unavailable' };
+    try {
+        const r = await client.runs.taskStop(runId, handle, {
+            ...(opts?.signal ? { signal: opts.signal } : {}),
+            ...engineSessionParamSpread(),
+        });
+        const out = r?.output ?? {};
+        if (engineWireDebugEnabled()) {
+            hostLog('debug', `[task-handle] stop ${handle} via run ${runId}: ok status=${typeof out.status === 'string' ? out.status : '-'} stoppedBy=${typeof out.stoppedBy === 'string' ? out.stoppedBy : '-'}`);
+        }
+        return {
+            ok: true,
+            ...(typeof out.status === 'string' ? { status: out.status } : {}),
+            ...(typeof out.stoppedBy === 'string' ? { stoppedBy: out.stoppedBy } : {}),
+        };
+    }
+    catch (e) {
+        const status = e?.status;
+        const detail = e instanceof Error ? e.message : String(e);
+        hostLog('debug', `[task-handle] stop ${handle} via run ${runId}: ${typeof status === 'number' ? status : detail.slice(0, 160)}`);
+        // [1521]F2 订正:server 文案句里不含 errorCode 字面(message 判恒 miss=死分形),而 SDK
+        // APIError.code 一直透 errorCode——锚 code(对文案措辞变化免疫),message 兜底保留。
+        // 🔴 G13:判别锚从 `status===409` 换成 **typed 类**(`TaskStopConflictError`)—— SDK 把任何
+        //   `stop.*` 码都映到它,以后 server 换 HTTP 码(或同码复用别的语义)时这条腿不会失灵;
+        //   status 判保留为兜底(老 SDK 不抛 typed 类时仍要认)。
+        if (e instanceof TaskStopConflictError || status === 409) {
+            return classifyTaskStopConflict(e);
+        }
+        return { ok: false, reason: 'error', detail };
+    }
+}

package/dist/workflowClient.d.ts

@@ -0,0 +1,42 @@
+import type { WorkflowRun } from '@sema-agent/sdk';
+import type { WorkflowRunState } from './workflowMonitor.js';
+/** The live controller the host drives — a projected-snapshot reader + diagnostics + teardown. */
+export interface LiveWorkflowController {
+    /** the latest projected run state, or null (not yet resolved / degraded 501-404 / empty). */
+    snapshot(): WorkflowRunState | null;
+    /** connection + degrade diagnostics for the empty/degraded render + verify cross-check. */
+    status(): {
+        connected: boolean;
+        /** true when the endpoint is unavailable (501 = S8 flag off) / the run is absent (404) / the list is empty. */
+        degraded: boolean;
+        /** the HTTP status behind a degrade (501 / 404), else null. */
+        code: number | null;
+        /** the resolved workflow run id (null until list()/config resolves one). */
+        runId: string | null;
+        lastError: string | null;
+    };
+    /** abort the underlying SSE stream + stop the background loop (host unmount). */
+    dispose(): void;
+}
+export interface LiveWorkflowConfig {
+    baseUrl: string;
+    authToken: string;
+    /** SDK Principal — e.g. 'anon:sema' (workflows are owner-scoped by principal). */
+    principal: string;
+    /** explicit workflow run id; when absent the source picks the first RUNNING run from list() (else the first). */
+    workflowId?: string;
+}
+/** THE projector: SDK `WorkflowRun` (client.workflows.get) → the monitor's `WorkflowRunState`. Pure/total —
+ *  tolerates absent/permissive fields and never throws (the graceful-degrade contract lives above, in the
+ *  source loop; this just maps a well-formed run). Exported for the mock-parity unit cross-check. */
+export declare function projectWorkflowRun(run: WorkflowRun): WorkflowRunState;
+/**
+ * createLiveWorkflowSource({ baseUrl, authToken, principal, workflowId? }) — the LIVE workflow-monitor source.
+ *
+ * Constructs the AgentClient and kicks off a background loop that (1) resolves a run id (explicit config, else
+ * the first running run from `list()`), (2) snapshots it via `get()` → project → store, and (3) follows
+ * `stream()` as a change-ticker (re-`get()` throttled on each frame). Every step is degrade-safe: a 501 (S8
+ * off) / 404 (non-owner/absent) / empty list / connection error is RECORDED (status().degraded/code) and
+ * leaves `snapshot()` null so the host falls back to the mock/empty state — the source never throws into it.
+ */
+export declare function createLiveWorkflowSource(config: LiveWorkflowConfig): LiveWorkflowController;