@nowcrew/daemon 0.6.98-beta.7 → 0.6.98-beta.8

package/dist/runtime-observation.js

@@ -0,0 +1,219 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+export const OBSERVABILITY_ENV = "NOWWORK_OBSERVABILITY_POLICY";
+export const ObservabilityPolicySchema = z.object({
+    version: z.literal(1), captureId: z.string().min(1).max(128),
+    contentMode: z.enum(["metadata", "redacted"]),
+}).strict();
+const Id = z.string().min(1).max(200);
+const Count = z.number().int().nonnegative().safe();
+export const RuntimeObservationSchema = z.object({
+    kind: z.literal("agent_observation"), version: z.literal(1), captureId: z.string().min(1).max(128),
+    sourceEventIndex: z.number().int().positive().safe(),
+    runtime: z.enum(["codex", "claude", "kimi", "hermes", "deepseek-harness", "opencode", "pi"]),
+    observationId: Id, parentObservationId: Id.optional(), nativeSessionId: Id.optional(),
+    nativeTurnId: Id.optional(), nativeCallId: Id.optional(),
+    type: z.enum(["agent", "tool", "generation", "event", "span", "retriever"]),
+    phase: z.enum(["start", "end", "event"]), name: z.string().min(1).max(200),
+    observedAt: z.string().datetime({ offset: true }), status: z.enum(["ok", "error"]).optional(),
+    input: z.string().max(8192).optional(), output: z.string().max(8192).optional(), inputBytes: Count.optional(), outputBytes: Count.optional(), model: z.string().min(1).max(200).optional(),
+    usage: z.object({ inputTokens: Count.optional(), outputTokens: Count.optional(), cacheReadTokens: Count.optional(),
+        cacheCreationTokens: Count.optional(), reasoningTokens: Count.optional(), costUsd: z.number().finite().nonnegative().optional() }).strict().optional(),
+    usageScope: z.enum(["generation", "turn", "execution"]).optional(),
+    unavailable: z.array(z.string().min(1).max(120)).max(30).optional(), truncated: z.boolean().optional(),
+    expectedCount: z.number().int().nonnegative().safe().optional(), dropped: z.number().int().nonnegative().safe().optional(),
+}).strict().superRefine((event, ctx) => {
+    if (event.name === "capture.summary") {
+        if (event.phase !== "event" || event.type !== "event" || event.expectedCount === undefined
+            || event.sourceEventIndex !== event.expectedCount + 1)
+            ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Invalid capture summary" });
+    }
+    else if (event.expectedCount !== undefined || event.dropped !== undefined) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Only capture summary carries counts" });
+    }
+});
+export function parseObservabilityPolicy(raw) {
+    const parsed = ObservabilityPolicySchema.safeParse(raw);
+    return parsed.success ? parsed.data : undefined;
+}
+export function observationPolicyFromEnvironment(env) {
+    try {
+        return parseObservabilityPolicy(JSON.parse(env[OBSERVABILITY_ENV] ?? "null"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 最后应用，清掉继承/用户配置中的同名变量，旧执行默认关闭。 */
+export function observationEnvironment(env, policy) {
+    const clean = Object.fromEntries(Object.entries(env).filter(([key]) => key.toUpperCase() !== OBSERVABILITY_ENV));
+    const parsed = parseObservabilityPolicy(policy);
+    return parsed ? { ...clean, [OBSERVABILITY_ENV]: JSON.stringify(parsed) } : clean;
+}
+const REDACTED = "[REDACTED]";
+// 与 Server 保持相同的边界规则；原 env/spec 不能先进入本地 journal 再由 Server 清洗。
+const normalizeKey = (key) => key.toLowerCase().replace(/[^a-z0-9]/gu, "");
+const forbiddenContainer = (key) => /^(?:env|envvars|runtimeenv|childenv|inheritedenv|environmentvariables|processenv|environmentplan|spec|executionspec|runtimeconfig|providerconfig)$/u.test(normalizeKey(key));
+const sensitiveKey = (key) => /(?:apikey|accesskey(?:id)?|secretkey|secret|password|passwd|token|authorization|cookie|credential|privatekey|signature)$/u.test(normalizeKey(key))
+    || /^(?:key|sig|session|auth|authkey|authstring)$/u.test(normalizeKey(key));
+function clip(value, limit) {
+    const end = value.charCodeAt(limit - 1);
+    return value.slice(0, end >= 0xd800 && end <= 0xdbff ? limit - 1 : limit);
+}
+function cleanUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (url.username || url.password) {
+            url.username = REDACTED;
+            url.password = "";
+        }
+        for (const name of [...url.searchParams.keys()]) {
+            if (sensitiveKey(name) || /^(?:code|ticket|sessionid|sas)$/iu.test(name) || /^(?:x-amz-|x-oss-|x-goog-)/iu.test(name))
+                url.searchParams.set(name, REDACTED);
+        }
+        if (url.hash && /(?:token|secret|password|credential|key|signature)/iu.test(url.hash))
+            url.hash = REDACTED;
+        return url.toString();
+    }
+    catch {
+        return REDACTED;
+    }
+}
+export function redactObservationText(value) {
+    const urls = [];
+    const text = value.replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s<>"'`]+/giu, raw => {
+        const index = urls.push(cleanUrl(raw)) - 1;
+        return `__NOWWORK_TRACE_URL_${index}__`;
+    });
+    return text
+        .replace(/-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z ]+ )?PRIVATE KEY-----/gu, REDACTED)
+        .replace(/\b(?:sk|pk)[-_]lf[-_][A-Za-z0-9_-]+\b/gu, REDACTED)
+        .replace(/\b(?:sk[-_][A-Za-z0-9_-]{6,}|gh[pousr]_[A-Za-z0-9_]{12,}|github_pat_[A-Za-z0-9_]{12,}|npm_[A-Za-z0-9]{12,})\b/gu, REDACTED)
+        .replace(/\b(authorization\s*[:=]\s*)(?:(?:bearer|basic)\s+)?[^\r\n,;]+/giu, `$1${REDACTED}`)
+        .replace(/((?:[A-Za-z0-9_]*(?:api[_-]?key|access[_-]?key|secret|password|passwd|token|cookie|credential|signature)|\b(?:key|session))\s*["']?\s*[:=]\s*)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s,;}]+)/giu, `$1${REDACTED}`)
+        .replace(/(\/\/[^\s"'`]+\/:_auth(?:token)?\s*=)\s*[^\s"'`]+/giu, `$1${REDACTED}`)
+        .replace(/__NOWWORK_TRACE_URL_(\d+)__/gu, (_match, index) => urls[Number(index)] ?? REDACTED);
+}
+function safeIdentity(value) {
+    // 含敏感值的 ID 用稳定别名，不能把不同调用都改成同一个 [REDACTED]。
+    return redactObservationText(value) === value ? value : `redacted-id:${createHash("sha256").update(value).digest("hex")}`;
+}
+function content(value) {
+    let truncated = false;
+    let remaining = 2000;
+    const visit = (item, depth) => {
+        if (--remaining < 0 || depth > 12) {
+            truncated = true;
+            return "[TRUNCATED]";
+        }
+        if (typeof item === "string") {
+            const text = redactObservationText(item);
+            if (text.length > 8192)
+                truncated = true;
+            return clip(text, 8192);
+        }
+        if (item === null || typeof item === "number" || typeof item === "boolean")
+            return item;
+        if (Array.isArray(item)) {
+            if (item.length > 100)
+                truncated = true;
+            return item.slice(0, 100).map(child => visit(child, depth + 1));
+        }
+        if (typeof item === "object") {
+            const entries = Object.entries(item);
+            if (entries.length > 100)
+                truncated = true;
+            return Object.fromEntries(entries.slice(0, 100).map(([key, child]) => [redactObservationText(key), forbiddenContainer(key) || sensitiveKey(key)
+                    || (normalizeKey(key) === "environment" && typeof child === "object") ? REDACTED : visit(child, depth + 1)]));
+        }
+        return String(item);
+    };
+    let structured = value;
+    if (typeof value === "string" && /^[\s]*[\[{]/u.test(value)) {
+        try {
+            structured = JSON.parse(value);
+        }
+        catch { /* 不是完整JSON则走文本清洗 */ }
+    }
+    const safe = visit(structured, 0);
+    const text = typeof safe === "string" ? safe : JSON.stringify(safe);
+    return { text: clip(text, 8192), truncated: truncated || text.length > 8192 };
+}
+/** 校验与本地内容策略在进入现有 telemetry journal 前再执行一次。 */
+export function safeRuntimeObservation(raw, policy) {
+    if (!policy)
+        return undefined;
+    const result = RuntimeObservationSchema.safeParse(raw);
+    if (!result.success || result.data.captureId !== policy.captureId)
+        return undefined;
+    const { input, output, ...metadata } = result.data;
+    const cleanMetadata = { ...metadata, name: redactObservationText(metadata.name),
+        ...(metadata.model ? { model: redactObservationText(metadata.model) } : {}),
+        ...(metadata.unavailable ? { unavailable: metadata.unavailable.map(value => clip(redactObservationText(value), 120)) } : {}),
+        ...Object.fromEntries(["observationId", "parentObservationId", "nativeSessionId", "nativeTurnId", "nativeCallId"]
+            .flatMap(key => metadata[key] === undefined ? [] : [[key, safeIdentity(metadata[key])]])),
+    };
+    const inputContent = policy.contentMode === "redacted" && input !== undefined ? content(input) : undefined;
+    const outputContent = policy.contentMode === "redacted" && output !== undefined ? content(output) : undefined;
+    const safe = policy.contentMode === "metadata" ? cleanMetadata : {
+        ...cleanMetadata,
+        ...(inputContent ? { input: inputContent.text } : {}),
+        ...(outputContent ? { output: outputContent.text } : {}),
+        ...(inputContent?.truncated || outputContent?.truncated ? { truncated: true } : {}),
+    };
+    const checked = RuntimeObservationSchema.safeParse(safe);
+    return checked.success && Buffer.byteLength(JSON.stringify(checked.data)) <= 24 * 1024 ? checked.data : undefined;
+}
+/** 仅短命 runner 使用；不持久化、不联网、不影响业务事件流。 */
+export function createRuntimeObservationCapture(runtime, env = process.env, emit = event => { process.stdout.write(`${JSON.stringify(event)}\n`); }) {
+    const policy = observationPolicyFromEnvironment(env);
+    let index = 0;
+    let dropped = 0;
+    let finished = false;
+    const send = (fields, summary = false) => {
+        if (!policy || finished)
+            return;
+        if (!summary && index >= 20_000) {
+            dropped += 1;
+            return;
+        }
+        try {
+            const { input, output, ...metadata } = fields;
+            const bytes = (value) => Buffer.byteLength(typeof value === "string" ? value : JSON.stringify(value));
+            const inputText = policy.contentMode === "redacted" && input !== undefined ? content(input) : undefined;
+            const outputText = policy.contentMode === "redacted" && output !== undefined ? content(output) : undefined;
+            let candidate = {
+                ...metadata, kind: "agent_observation", version: 1, captureId: policy.captureId,
+                runtime, sourceEventIndex: index + 1, observedAt: fields.observedAt ?? new Date().toISOString(),
+                ...(input === undefined ? {} : { inputBytes: bytes(input) }), ...(output === undefined ? {} : { outputBytes: bytes(output) }),
+                ...(inputText ? { input: inputText.text } : {}), ...(outputText ? { output: outputText.text } : {}),
+                ...(inputText?.truncated || outputText?.truncated ? { truncated: true } : {}),
+            };
+            if (Buffer.byteLength(JSON.stringify(candidate)) > 24 * 1024) {
+                candidate = { ...candidate, ...(inputText ? { input: clip(inputText.text, 1500) } : {}),
+                    ...(outputText ? { output: clip(outputText.text, 1500) } : {}), truncated: true };
+            }
+            const safe = safeRuntimeObservation(candidate, policy);
+            if (!safe) {
+                dropped += 1;
+                return;
+            }
+            index += 1;
+            emit({ type: "nowwork.observation", observation: safe });
+        }
+        catch {
+            dropped += 1; /* 诊断永远不改变 runtime 结果 */
+        }
+    };
+    return {
+        enabled: policy !== undefined,
+        observe: fields => send(fields),
+        finish() {
+            if (finished)
+                return;
+            send({ observationId: "capture.summary", type: "event", phase: "event", name: "capture.summary",
+                expectedCount: index, dropped, ...(index === 0 ? { unavailable: ["runtime_events"] } : {}) }, true);
+            finished = true;
+        },
+    };
+}

package/dist/runtime-tool-update-bridge.js

@@ -0,0 +1,126 @@
+import { createHash } from "node:crypto";
+import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { RuntimeToolResponseSchema } from "./runtime-tool-update-protocol.js";
+export function runtimeToolEnvironment(env) {
+    // Keep only machine identity and lookup settings. Never pass runtime/control-plane credentials or Node injection flags.
+    return Object.fromEntries(Object.entries(env).filter(([key]) => /^(PATH|HOME|USER|LOGNAME|SHELL|TMPDIR|TMP|TEMP|LANG|LC_[A-Z_]+|XDG_CONFIG_HOME|XDG_CACHE_HOME)$/u.test(key)));
+}
+async function readReport(dir) {
+    const file = join(dir, "report.json");
+    if ((await stat(file)).size > 256_000)
+        throw new Error("invalid_report");
+    return RuntimeToolResponseSchema.parse(JSON.parse(await readFile(file, "utf8")));
+}
+async function stopGroup(pid) {
+    if (!pid)
+        return true;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
+    const deadline = Date.now() + 3000;
+    while (Date.now() < deadline) {
+        try {
+            process.kill(-pid, 0);
+        }
+        catch (error) {
+            return error.code === "ESRCH";
+        }
+        await new Promise(resolve => setTimeout(resolve, 50));
+    }
+    return false;
+}
+export function createRuntimeToolProgressPoller(read, progress, intervalMs = 250) {
+    let active = true;
+    let pending = null;
+    const interval = setInterval(() => {
+        if (!active || pending || !progress)
+            return;
+        pending = read().then(async (data) => { if (active)
+            await progress(data); })
+            .catch(() => { }).finally(() => { pending = null; });
+    }, intervalMs);
+    return { async stop() { active = false; clearInterval(interval); await pending; } };
+}
+async function supervise(dir, env, start, progress, protectProcessGroup) {
+    const child = spawn(process.execPath, [join(dir, "runner.mjs"), "--managed-worker"], { cwd: dir, env, detached: true, stdio: ["ignore", "ignore", "ignore", "ipc"] });
+    const closed = new Promise(resolve => { child.once("error", () => resolve(null)); child.once("close", resolve); });
+    const polling = createRuntimeToolProgressPoller(() => readReport(dir), progress);
+    let expired = false;
+    const timer = setTimeout(() => { expired = true; void stopGroup(child.pid); }, start ? 12 * 60_000 : 120_000);
+    let launchFailed = false;
+    try {
+        if (start) {
+            if (!protectProcessGroup || !child.pid)
+                throw new Error("lease_protection_unavailable");
+            await protectProcessGroup(child.pid);
+        }
+        await new Promise((resolve, reject) => child.send({ type: "runtime-tools:go" }, error => error ? reject(error) : resolve()));
+    }
+    catch {
+        launchFailed = true;
+        await stopGroup(child.pid);
+    }
+    const code = await closed;
+    clearTimeout(timer);
+    await polling.stop();
+    // A successful parent exit does not prove its package-manager descendants stopped.
+    const stopped = await stopGroup(child.pid);
+    return { stopped, success: stopped && !expired && !launchFailed && code === 0 };
+}
+export async function runRuntimeToolBridge(config, request, acquireEnv, progress, deps = {}) {
+    let dir;
+    let started = false;
+    let processStopped = true;
+    const failure = (errorCode) => ({ processStopped, data: request.action === "start" ? { operation: {
+                operationId: request.operationId, state: started ? "unknown" : "failed", currentIndex: 0, targets: request.targets,
+                items: request.targets.map(t => ({ runtime: t.installation.runtime, state: started ? "unknown" : "failed", errorCode })),
+                updatedAt: new Date().toISOString(), errorCode,
+            } } : {} });
+    try {
+        const response = await (deps.fetch ?? fetch)(`${config.serverUrl.replace(/\/+$/, "")}/machine/runtime-tool-updates/runner/${request.runner.releaseId}`, {
+            headers: { authorization: `Bearer ${config.machineToken}` }, redirect: "error", signal: AbortSignal.timeout(15_000),
+        });
+        if (!response.ok || !response.body)
+            return failure("runner_unavailable");
+        const chunks = [];
+        let bytes = 0;
+        for await (const chunk of response.body) {
+            bytes += chunk.length;
+            if (bytes > 512_000)
+                return failure("runner_unavailable");
+            chunks.push(chunk);
+        }
+        const content = Buffer.concat(chunks);
+        if (createHash("sha256").update(content).digest("hex") !== request.runner.sha256)
+            return failure("runner_unavailable");
+        const env = runtimeToolEnvironment(await acquireEnv());
+        dir = await mkdtemp(join(tmpdir(), "nowwork-runtime-update-"));
+        await writeFile(join(dir, "runner.mjs"), content, { mode: 0o600 });
+        await writeFile(join(dir, "request.json"), JSON.stringify(request), { mode: 0o600 });
+        started = true;
+        processStopped = false;
+        const outcome = await supervise(dir, env, request.action === "start", progress, deps.protectProcessGroup);
+        processStopped = outcome.stopped;
+        if (!outcome.success)
+            return failure("operation_unknown");
+        const data = await readReport(dir);
+        if (request.action === "start" && data.operation?.operationId !== request.operationId)
+            return failure("operation_unknown");
+        if (request.action === "inspect" && !data.snapshot)
+            return failure("inspection_failed");
+        return { data, processStopped };
+    }
+    catch {
+        return failure(started ? "operation_unknown" : "runner_unavailable");
+    }
+    finally {
+        if (dir && processStopped)
+            await rm(dir, { recursive: true, force: true });
+    }
+}

package/dist/runtime-tool-update-controller.js

@@ -0,0 +1,151 @@
+import { RuntimeToolRequestSchema, RuntimeToolResponseSchema } from "./runtime-tool-update-protocol.js";
+const finalStates = new Set(["completed", "failed", "unknown", "cancelled"]);
+const phaseRank = (state) => ({ queued: 0, preflight: 1, installing: 2, verifying: 3, completed: 4, failed: 4, unknown: 4, cancelled: 4 })[state];
+function advancesProgress(previous, next) {
+    if (finalStates.has(previous.state) || finalStates.has(next.state)
+        || next.operationId !== previous.operationId || JSON.stringify(next.targets) !== JSON.stringify(previous.targets)
+        || next.currentIndex < previous.currentIndex || next.currentIndex >= previous.targets.length
+        || (next.currentIndex === previous.currentIndex && phaseRank(next.state) < phaseRank(previous.state)))
+        return false;
+    return previous.items.every((item, index) => {
+        const candidate = next.items[index];
+        if (!candidate || candidate.runtime !== item.runtime)
+            return false;
+        return finalStates.has(item.state) ? candidate.state === item.state && candidate.errorCode === item.errorCode
+            : phaseRank(candidate.state) >= phaseRank(item.state);
+    });
+}
+export function createRuntimeToolUpdateController(deps) {
+    const entries = new Map();
+    let current = null;
+    let stopped = false;
+    let orphaned = false;
+    const now = deps.now ?? Date.now;
+    const date = () => new Date(now()).toISOString();
+    const wait = deps.wait ?? (() => new Promise(resolve => setTimeout(resolve, 500)));
+    const fail = (error) => ({ ok: false, error });
+    const result = (data) => ({ ok: true, data });
+    const set = (entry, patch) => { entry.operation = { ...entry.operation, ...patch, updatedAt: date() }; };
+    async function execute(entry) {
+        const deadline = now() + 10 * 60_000;
+        let acceptingProgress = false;
+        let lease = null;
+        try {
+            while (!stopped && entry.operation.state === "queued" && now() < deadline && !lease) {
+                lease = await deps.acquire();
+                if (!lease)
+                    await wait();
+            }
+            if (entry.operation.state === "cancelled")
+                return;
+            if (!lease || stopped || now() >= deadline) {
+                set(entry, { state: "failed", errorCode: "runtime_busy" });
+                return;
+            }
+            set(entry, { state: "preflight" });
+            // Mark unsafe before spawning: an exception or lost response cannot authorize another writer.
+            entry.processStopped = false;
+            acceptingProgress = true;
+            const output = await deps.run(entry.request, raw => {
+                if (!acceptingProgress)
+                    return;
+                const parsed = RuntimeToolResponseSchema.safeParse(raw);
+                if (parsed.success && parsed.data.operation && advancesProgress(entry.operation, parsed.data.operation))
+                    entry.operation = parsed.data.operation;
+            }, lease.protectProcessGroup);
+            acceptingProgress = false;
+            const data = RuntimeToolResponseSchema.parse(output.data);
+            entry.processStopped = output.processStopped;
+            if (!data.operation || data.operation.operationId !== entry.operation.operationId
+                || JSON.stringify(data.operation.targets) !== JSON.stringify(entry.request.targets)
+                || data.operation.currentIndex < entry.operation.currentIndex || !finalStates.has(data.operation.state))
+                throw new Error("operation_mismatch");
+            entry.operation = data.operation;
+            if (!entry.processStopped)
+                set(entry, { state: "unknown", errorCode: "operation_unknown" });
+        }
+        catch {
+            acceptingProgress = false;
+            set(entry, { state: "unknown", errorCode: "operation_unknown" });
+        }
+        finally {
+            acceptingProgress = false;
+            // Retain the barrier if process-group termination could not be proved.
+            if (entry.processStopped) {
+                try {
+                    await lease?.release();
+                }
+                catch {
+                    entry.processStopped = false;
+                    set(entry, { state: "unknown", errorCode: "operation_unknown" });
+                }
+            }
+        }
+    }
+    return {
+        async handle(raw) {
+            const parsed = RuntimeToolRequestSchema.safeParse(raw);
+            if (!parsed.success || stopped)
+                return fail("invalid_request");
+            const request = parsed.data;
+            if (request.action === "inspect") {
+                try {
+                    const data = RuntimeToolResponseSchema.parse((await deps.run(request)).data);
+                    return data.snapshot ? result(data) : fail("inspection_failed");
+                }
+                catch {
+                    return fail("inspection_failed");
+                }
+            }
+            const entry = entries.get(request.operationId);
+            if (request.action === "start") {
+                if (entry)
+                    return result({ operation: entry.operation });
+                if (orphaned || [...entries.values()].some(x => x.operation.state === "unknown"))
+                    return fail("operation_unknown");
+                if (current)
+                    return fail("runtime_busy");
+                if (entries.size >= 100)
+                    return fail("operation_limit");
+                if (new Set(request.targets.map(t => t.installation.runtime)).size !== request.targets.length)
+                    return fail("invalid_request");
+                const operation = { operationId: request.operationId, state: "queued", currentIndex: 0, targets: request.targets,
+                    items: request.targets.map(t => ({ runtime: t.installation.runtime, state: "queued", errorCode: null })), updatedAt: date(), errorCode: null };
+                const next = { operation, request, processStopped: true };
+                entries.set(request.operationId, next);
+                current = execute(next).finally(() => { current = null; });
+                return result({ operation });
+            }
+            if (!entry) {
+                orphaned = true;
+                return fail("operation_unknown");
+            }
+            if (request.action === "status")
+                return result({ operation: entry.operation });
+            if (request.action === "cancel") {
+                if (entry.operation.state !== "queued")
+                    return fail("already_started");
+                set(entry, { state: "cancelled", items: entry.operation.items.map(x => ({ ...x, state: "cancelled" })) });
+                return result({ operation: entry.operation });
+            }
+            if (!entry.processStopped || current)
+                return fail("operation_unknown");
+            try {
+                const output = await deps.run({ action: "inspect", runner: entry.request.runner });
+                const snapshot = RuntimeToolResponseSchema.parse(output.data).snapshot;
+                if (!snapshot || !output.processStopped)
+                    return fail("operation_unknown");
+                const matches = entry.operation.targets.every(target => snapshot.tools.some(tool => tool.runtime === target.installation.runtime
+                    && tool.version === target.targetVersion && tool.path === target.installation.path && tool.source === target.installation.source
+                    && tool.prefix === target.installation.prefix && tool.brewPath === target.installation.brewPath && tool.automatic));
+                set(entry, { state: matches ? "completed" : "failed", errorCode: matches ? null : "verification_failed", snapshot,
+                    items: entry.operation.items.map(x => ({ ...x, state: matches ? "completed" : "failed", errorCode: matches ? null : "verification_failed" })) });
+                return result({ operation: entry.operation, snapshot });
+            }
+            catch {
+                return fail("inspection_failed");
+            }
+        },
+        async stop() { stopped = true; await current; },
+    };
+}

package/dist/runtime-tool-update-protocol.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export const RUNTIME_TOOL_UPDATES_CAPABILITY = "runtime_tool_updates_v1";
+const boundedPath = z.string().min(1).max(4096);
+export const RuntimeToolRunnerSchema = z.object({ releaseId: z.string().regex(/^[a-f0-9]{64}$/), sha256: z.string().regex(/^[a-f0-9]{64}$/) }).strict();
+export const RuntimeToolInstallationSchema = z.object({
+    runtime: z.enum(["codex", "claude"]), path: boundedPath, realPath: boundedPath,
+    version: z.string().max(100).nullable(), source: z.enum(["npm", "homebrew", "native", "unknown"]),
+    nodeVersion: z.string().max(100).nullable(), nodePath: boundedPath.nullable(), npmPath: boundedPath.nullable(), prefix: boundedPath.nullable(),
+    brewPath: boundedPath.nullable(), brewKind: z.enum(["formula", "cask"]).nullable(), brewName: z.enum(["codex", "claude-code"]).nullable(),
+    fingerprint: z.string().regex(/^[a-f0-9]{64}$/), alternatives: z.array(boundedPath).max(32), automatic: z.boolean(), reason: z.string().max(100).nullable(),
+}).strict();
+export const RuntimeToolSnapshotSchema = z.object({ checkedAt: z.string().datetime(), tools: z.array(RuntimeToolInstallationSchema).max(2) }).strict();
+export const RuntimeToolTargetSchema = z.object({ installation: RuntimeToolInstallationSchema, targetVersion: z.string().regex(/^\d+\.\d+\.\d+$/).max(100) }).strict();
+export const RuntimeToolStateSchema = z.enum(["queued", "preflight", "installing", "verifying", "completed", "failed", "unknown", "cancelled"]);
+export const RuntimeToolOperationSchema = z.object({ operationId: z.string().uuid(), state: RuntimeToolStateSchema, currentIndex: z.number().int().min(0).max(2),
+    targets: z.array(RuntimeToolTargetSchema).min(1).max(2), items: z.array(z.object({ runtime: z.enum(["codex", "claude"]), state: RuntimeToolStateSchema, errorCode: z.string().max(100).nullable() }).strict()).max(2),
+    updatedAt: z.string().datetime(), errorCode: z.string().max(100).nullable(), snapshot: RuntimeToolSnapshotSchema.optional(),
+}).strict();
+export const RuntimeToolRequestSchema = z.discriminatedUnion("action", [
+    z.object({ action: z.literal("inspect"), runner: RuntimeToolRunnerSchema }).strict(),
+    z.object({ action: z.literal("start"), operationId: z.string().uuid(), targets: z.array(RuntimeToolTargetSchema).min(1).max(2), runner: RuntimeToolRunnerSchema }).strict(),
+    ...["status", "cancel", "verify"].map(action => z.object({ action: z.literal(action), operationId: z.string().uuid() }).strict()),
+]);
+export const RuntimeToolResponseSchema = z.object({ snapshot: RuntimeToolSnapshotSchema.optional(), operation: RuntimeToolOperationSchema.optional() }).strict();

package/dist/runtime-tool-update-serve.js

@@ -0,0 +1,54 @@
+import { prepareDaemonRestart } from "./daemon-updater.js";
+import { createRuntimeToolUpdateController } from "./runtime-tool-update-controller.js";
+import { augmentedPath } from "./runtime-path.js";
+import { runRuntimeToolBridge } from "./runtime-tool-update-bridge.js";
+export async function acquireRuntimeToolLease(localSlots, host) {
+    const local = await prepareDaemonRestart({ localSlots });
+    if (!local.ok)
+        return null;
+    try {
+        const shared = await host.tryAcquireExclusiveExecution();
+        if (!shared) {
+            await local.release();
+            return null;
+        }
+        let released = false;
+        return { protectProcessGroup: async (pid) => {
+                if (!shared.protectProcessGroup)
+                    throw new Error("lease protection unavailable");
+                await shared.protectProcessGroup(pid);
+            }, async release() { if (released)
+                return; await shared.release(); await local.release(); released = true; } };
+    }
+    catch (error) {
+        await local.release();
+        throw error;
+    }
+}
+export function createServeRuntimeToolUpdates(config, localSlots, host, acquireEnv, refresh) {
+    const controller = createRuntimeToolUpdateController({ acquire: () => acquireRuntimeToolLease(localSlots, host),
+        run: async (request, progress, protectProcessGroup) => {
+            const result = await runRuntimeToolBridge(config, request, async () => {
+                const env = await acquireEnv();
+                return { ...env, PATH: augmentedPath(env, {}, process.platform, "append") };
+            }, progress, { ...(protectProcessGroup ? { protectProcessGroup } : {}) });
+            if (request.action === "start" && result.processStopped)
+                refresh();
+            return result;
+        } });
+    return {
+        handle(raw, send) {
+            if (!raw || typeof raw !== "object" || !("type" in raw) || raw.type !== "runtime-tools:operation")
+                return false;
+            const { reqId, type: _type, ...request } = raw;
+            if (typeof reqId === "string") {
+                if (process.platform !== "linux" && process.platform !== "darwin")
+                    send({ type: "fs:result", reqId, ok: false, error: "unsupported_platform" });
+                else
+                    void controller.handle(request).then(result => send({ type: "fs:result", reqId, ...result })).catch(() => send({ type: "fs:result", reqId, ok: false, error: "operation_unknown" }));
+            }
+            return true;
+        },
+        stop: controller.stop,
+    };
+}

package/dist/runtimes/claude-observation-runner.js

@@ -0,0 +1,55 @@
+/** 无线程 Claude 的短命观察桥：保留原命令/参数，不引入线程或原生会话约束。 */
+import { createInterface } from "node:readline";
+import { pathToFileURL } from "node:url";
+import spawn from "cross-spawn";
+import { z } from "zod";
+import { createRuntimeObservationCapture } from "../runtime-observation.js";
+import { createObservationMapper } from "./observation-mapper.js";
+import { observeClaudeContext } from "./observation-context.js";
+const Input = z.object({ bin: z.string().min(1), args: z.array(z.string()) }).strict();
+export async function runClaudeObservation(bin, args) {
+    const capture = createRuntimeObservationCapture("claude");
+    const observer = createObservationMapper("claude", capture);
+    await observeClaudeContext(observer, args, args.at(-1) ?? "");
+    const child = spawn(bin, [...args], { cwd: process.cwd(), env: process.env, stdio: ["ignore", "pipe", "pipe"], detached: false });
+    const stopped = new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("close", (code, signal) => resolve(code ?? (signal ? 128 : 1)));
+    });
+    void stopped.catch(() => undefined);
+    const cancel = () => { child.kill("SIGTERM"); };
+    process.once("SIGTERM", cancel);
+    process.once("SIGINT", cancel);
+    try {
+        if (!child.stdout || !child.stderr)
+            throw new Error("Claude observation runner requires output streams");
+        child.stderr.pipe(process.stderr, { end: false });
+        for await (const line of createInterface({ input: child.stdout })) {
+            try {
+                observer.observe(JSON.parse(line));
+            }
+            catch { /* 原非 JSON 输出仍透传 */ }
+            process.stdout.write(`${line}\n`);
+        }
+        return await stopped;
+    }
+    finally {
+        observer.finish();
+        capture.finish();
+        process.off("SIGTERM", cancel);
+        process.off("SIGINT", cancel);
+    }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    let raw = "";
+    for await (const chunk of process.stdin) {
+        raw += String(chunk);
+        if (Buffer.byteLength(raw) > 8 * 1024 * 1024)
+            throw new Error("Claude observation input too large");
+    }
+    const input = Input.parse(JSON.parse(raw));
+    runClaudeObservation(input.bin, input.args).then(code => { process.exitCode = code; }).catch(() => {
+        process.stderr.write("Claude observation runner failed\n");
+        process.exitCode = 1;
+    });
+}