@ckanner/dsh-plugin-flywheel 0.0.0-stage → 0.28.0

package/dist/client.js

@@ -0,0 +1,206 @@
+window.__ModuleLoader__.load({id:"@ckanner/dsh-plugin-flywheel",factory:(require)=>{
+const module={exports:{}};const exports=module.exports;
+// The build wraps this file in rc.5's browser ModuleLoader factory.
+const React = require('react');
+const h = React.createElement;
+
+const taskLabels = {
+  pending: '待开始', paused: '已暂停', stopped: '已停止', completed: '已完成',
+  escalated: '需要人工处理', 'budget-stopped': '预算已停止',
+};
+const packetLabels = {
+  pending: '待执行', 'awaiting-credentials': '等待凭证', executing: '执行中', executed: '待验收',
+  'l1-passed': '验收已通过', 'l1-failed': '验收未通过', 'review-failed': '评审退回',
+  completed: '已完成', interrupted: '已中断', escalated: '需要人工处理', inbox: '等待处理',
+};
+const checkLabels = { pass: '通过', fail: '失败', warn: '注意', unknown: '未验证', skipped: '跳过' };
+const roleLabels = { plan: '规划', execute: '执行', review: '评审', judge: '终验',
+  intake: '需求收集', garden: '知识维护', 'judge-panel': '第二意见' };
+const buttonStyle = { border: '1px solid #8888', padding: '4px 10px', borderRadius: 5 };
+const tableStyle = { width: '100%', textAlign: 'left', fontSize: 11, borderCollapse: 'collapse' };
+const cellStyle = { padding: '5px 8px 5px 0', verticalAlign: 'top', overflowWrap: 'anywhere' };
+const rawStyle = { fontSize: 11, whiteSpace: 'pre-wrap', overflowWrap: 'anywhere', maxHeight: 240, overflow: 'auto' };
+
+function taskLabel(value) {
+  if (value.running) return '运行中';
+  if (!value.state) return '尚未初始化';
+  if (value.state.status === 'running') return '引擎未运行，状态待核对';
+  return taskLabels[value.state.status] ?? `未知状态（${value.state.status ?? '未报告'}）`;
+}
+
+function Configuration({ value }) {
+  if (!value) return null;
+  return h('section', { 'aria-label': '实际模型配置' },
+    h('h4', { style: { marginBottom: 6 } }, '实际模型配置'),
+    h('p', { style: { overflowWrap: 'anywhere' } }, `来源：${value.source || '内嵌模板'} · 范围：${value.scope}`),
+    h('div', { style: { overflowX: 'auto' } }, h('table', { style: tableStyle },
+      h('thead', null, h('tr', null, ...['阶段 / 路由', '模型 / Profile', 'Harness / Provider / 渠道', '推理 / 阶段权限要求 / 会话']
+        .map(title => h('th', { key: title, scope: 'col', style: cellStyle }, title)))),
+      h('tbody', null, ...value.bindings.map(binding => h('tr', { key: binding.id },
+        h('td', { style: cellStyle }, h('strong', null, roleLabels[binding.role] ?? binding.role),
+          h('div', null, binding.route || binding.id),
+          binding.inScope === false && h('div', null, '未用于本次检查')),
+        h('td', { style: cellStyle }, h('code', null, binding.model || '未配置'),
+          binding.profile && h('div', null, `Profile：${binding.profile}`)),
+        h('td', { style: cellStyle }, h('div', null, binding.harness),
+          h('div', null, `Provider：${binding.provider || (binding.harness === 'dsh' ? '未配置' : '由原生 CLI 管理')}`),
+          h('div', null, `渠道：${binding.channel || '未配置'}`)),
+        h('td', { style: cellStyle }, h('div', null, `推理：${binding.thinking || '默认'}`),
+          h('div', null, `阶段权限要求：${binding.permissionMode || '未声明'}`),
+          h('div', null, binding.residentSession ? '会话恢复：启用' : '会话恢复：关闭'))))))));
+}
+
+function Diagnostic({ value }) {
+  if (!value) return null;
+  return h('section', { 'aria-label': '环境检查结果' },
+    h('h4', { style: { marginBottom: 6 } }, value.ok ? '检查结束：未发现阻断项' : '检查结束：存在阻断项'),
+    h('p', null, value.probeRequested ? '已请求 SDK 无推理检查。' : '本次只检查本地环境，未启动 SDK 探测。'),
+    h('p', null, '未发送推理请求；账号授权、额度和真实模型能力未通过本次检查验证。'),
+    h('ul', { style: { paddingLeft: 20 } }, ...value.checks.map((check, index) =>
+      h('li', { key: `${check.id}:${index}`, style: { marginBottom: 9, overflowWrap: 'anywhere' } },
+        h('strong', null, `${checkLabels[check.status]} · ${check.id}`),
+        h('div', null, check.summary),
+        check.code && h('div', null, `错误码：${check.code}`),
+        check.remedy && h('div', null, `处理建议：${check.remedy}`)))));
+}
+
+function Budget({ value }) {
+  if (!value) return null;
+  const cost = value.totals?.['cost-usd'];
+  const unknownCost = value['unknown-cost-calls'] ?? 0;
+  const unknownUsage = value['unknown-usage-calls'] ?? 0;
+  let costText = Number.isFinite(cost) ? `已报告成本合计：$${cost.toFixed(4)}` : '成本：未知';
+  if (unknownCost > 0) {
+    costText = Number.isFinite(cost) && cost > 0 ?
+      `已知成本合计：$${cost.toFixed(4)}；另有 ${unknownCost} 次调用成本未知，合计不完整` :
+      `成本：未知（${unknownCost} 次调用未报告结算成本）`;
+  }
+  return h('section', { 'aria-label': '用量与成本' },
+    h('p', null, costText),
+    h('p', null, `已报告 Token：${value.totals?.tokens ?? '未知'}` +
+      (unknownUsage > 0 ? `；${unknownUsage} 次调用用量未知，合计不完整` : '')),
+    value['daily-token-limit'] != null && h('p', null,
+      `每日 Token 限额：${value['daily-token-limit']} · 预算策略：${value.enforce}`),
+    ...(value.warnings ?? []).map((warning, index) => h('p', { key: index }, `预算提示：${warning}`)));
+}
+
+function Panel({ execute }) {
+  const [open, setOpen] = React.useState(false);
+  const [taskDir, setTaskDir] = React.useState('');
+  const [cwd, setCwd] = React.useState('');
+  const [busy, setBusy] = React.useState(false);
+  const [status, setStatus] = React.useState(null);
+  const [configuration, setConfiguration] = React.useState(null);
+  const [diagnostic, setDiagnostic] = React.useState(null);
+  const [raw, setRaw] = React.useState(null);
+  const [error, setError] = React.useState('');
+  const requestVersion = React.useRef(0);
+  const panelId = React.useId();
+  React.useEffect(() => () => { requestVersion.current += 1; }, []);
+  const changePath = (setPath, value) => {
+    // Editing a path changes the view's identity, even while a request is in
+    // flight. It never implies stopping an independently running Go task.
+    requestVersion.current += 1;
+    setPath(value);
+    setBusy(false);
+    setStatus(null);
+    setConfiguration(null);
+    setDiagnostic(null);
+    setRaw(null);
+    setError('');
+  };
+  const packets = Object.entries(status?.state?.packets ?? {});
+  const run = async (action, probe = false) => {
+    const version = ++requestVersion.current;
+    setBusy(true);
+    setError('');
+    try {
+      const request = { action, ...(taskDir.trim() ? { taskDir: taskDir.trim() } : {}),
+        ...(cwd.trim() ? { cwd: cwd.trim() } : {}), ...(probe ? { probe: true } : {}) };
+      const value = await execute(request);
+      if (version !== requestVersion.current) return;
+      if (['start', 'status', 'stop'].includes(action)) setStatus(value);
+      if (['config', 'doctor'].includes(action)) {
+        setConfiguration(value.configuration ?? value.diagnostic?.configuration ?? null);
+        setDiagnostic(value.diagnostic ?? null);
+      }
+      setRaw(value);
+    } catch (error) {
+      if (version === requestVersion.current) setError(error instanceof Error ? error.message : String(error));
+    } finally {
+      if (version === requestVersion.current) setBusy(false);
+    }
+  };
+  const button = (action, label, needsTask, probe = false) => h('button', {
+    key: label, type: 'button', disabled: busy || (needsTask && !taskDir.trim()),
+    onClick: () => run(action, probe), style: buttonStyle,
+  }, label);
+  return h('div', { style: { position: 'relative', fontSize: 12 } },
+    h('button', { type: 'button', onClick: () => setOpen(!open), 'aria-expanded': open, 'aria-controls': panelId,
+      style: { border: '1px solid currentColor', borderRadius: 6, padding: '2px 8px' } },
+    `Flywheel${status ? ` · ${taskLabel(status)}` : ''}`),
+    open && h('section', { id: panelId, 'aria-label': 'Flywheel 任务控制', style: {
+      position: 'absolute', bottom: 'calc(100% + 8px)', left: 0, width: 'min(720px, 88vw)',
+      maxHeight: '70vh', overflow: 'auto', padding: 14, border: '1px solid #8888', borderRadius: 10,
+      background: 'var(--color-background, Canvas)', color: 'var(--color-foreground, CanvasText)',
+      boxShadow: '0 8px 32px #0003', zIndex: 40,
+    } },
+    h('strong', null, 'Flywheel · Go 引擎'),
+    h('p', { style: { margin: '8px 0' } }, '任务独立于桌面会话运行。切换下方路径只切换查看对象；停止任务请使用“停止”。'),
+    h('label', { style: { display: 'block' } }, '任务目录（绝对路径，配置与环境检查可留空）',
+      h('input', { value: taskDir, onChange: e => changePath(setTaskDir, e.target.value),
+        placeholder: '/path/to/repo/docs/task',
+        style: { width: '100%', boxSizing: 'border-box', padding: 6, border: '1px solid #8888', borderRadius: 4, margin: '4px 0 8px' } })),
+    h('label', { style: { display: 'block' } }, '仓库目录（留空使用当前 DSH 会话目录）',
+      h('input', { value: cwd, onChange: e => changePath(setCwd, e.target.value), placeholder: '/path/to/repo',
+        style: { width: '100%', boxSizing: 'border-box', padding: 6, border: '1px solid #8888', borderRadius: 4, margin: '4px 0 8px' } })),
+    h('div', { style: { display: 'flex', flexWrap: 'wrap', gap: 8, marginBottom: 8 } },
+      button('status', '刷新状态', true), button('start', '启动', true), button('stop', '停止', true)),
+    h('div', { style: { display: 'flex', flexWrap: 'wrap', gap: 8, marginBottom: 8 } },
+      button('config', '查看模型配置', false), button('doctor', '检查环境', false),
+      button('doctor', 'SDK 无推理检查', false, true)),
+    busy && h('p', { role: 'status' }, '正在等待引擎确认…'),
+    error && h('p', { role: 'alert', style: { color: '#d34b4b', whiteSpace: 'pre-wrap' } }, error),
+    status && h('section', { 'aria-label': '任务状态' },
+      h('h4', { style: { marginBottom: 6 } }, '任务状态（上次刷新）'),
+      h('p', null, `${status.state?.slug ?? '任务'} · ${taskLabel(status)}` + (status.running && status.pid > 0 ? ` · PID ${status.pid}` : '')),
+      status.state?.['current-milestone'] && h('p', null, `当前里程碑：${status.state['current-milestone']}`),
+      packets.length > 0 && h('div', { style: { maxHeight: 260, overflow: 'auto' } },
+        h('table', { 'aria-label': '工作单元', style: tableStyle },
+          h('caption', { style: { textAlign: 'left' } }, `工作单元（共 ${packets.length} 个）`),
+          h('thead', null, h('tr', null, ...['工作单元', '状态', '路由'].map(title => h('th', { key: title, scope: 'col', style: cellStyle }, title)))),
+          h('tbody', null, ...packets.map(([id, packet]) => h('tr', { key: id },
+            h('td', { style: cellStyle }, id),
+            h('td', { style: cellStyle }, packetLabels[packet?.status] ?? packet?.status ?? '未知'),
+            h('td', { style: cellStyle }, packet?.route ?? '—')))))),
+      h(Budget, { value: status.state?.budget }),
+      status.state?.inbox?.length > 0 && h('details', null,
+        h('summary', null, `待人工处理记录：${status.state.inbox.length} 条`),
+        h('pre', { style: rawStyle }, JSON.stringify(status.state.inbox, null, 2)))),
+    h(Diagnostic, { value: diagnostic }),
+    h(Configuration, { value: configuration }),
+    raw && h('details', null, h('summary', null, '引擎原始结果（JSON）'),
+      h('pre', { style: rawStyle }, JSON.stringify(raw, null, 2))),
+    ));
+}
+
+exports.inject = ['slots', 'remote', 'remote.commands'];
+exports.apply = function apply(ctx) {
+  ctx.slots.inject('conversation.composer.dock', () => ctx.slots.register({
+    name: 'conversation.composer.dock', id: 'flywheel', order: 50,
+    inject: sessionId => ({
+      execute: async request => {
+        const reply = await ctx.remote.commands.execute(sessionId, `/flywheel ${JSON.stringify(request)}`, []);
+        if (!reply?.ok) throw new Error(reply?.error?.message ?? 'DSH command transport failed');
+        const result = reply.value?.result;
+        if (result?.kind !== 'success') throw new Error(result?.text ?? 'Flywheel command unavailable');
+        const value = JSON.parse(result.text);
+        if (value?.protocol !== 1) throw new Error('Flywheel control protocol mismatch');
+        return value;
+      },
+    }),
+  }, Panel));
+};
+
+return module.exports;
+}});

package/dist/codex-pro-bridge.js

@@ -0,0 +1,60 @@
+// Public machine API consumer. Go remains the owner of scheduling and acceptance.
+import { createRequire } from 'node:module';
+
+export const ADAPTER = Object.freeze({ package: 'dsh-subagent-codex-pro', version: '0.8.0', protocol: 1 });
+export const LIMITS = Object.freeze({ requestBytes: 1024 * 1024, machineOutputBytes: 1024 * 1024,
+  progressBytes: 1024 * 1024, receiptFrameBytes: 8 * 1024 * 1024, admissionMs: 10000 });
+const require = createRequire(import.meta.url);
+
+export class WorkerError extends Error {
+  constructor(code, message) { super(message); this.name = 'WorkerError'; this.code = code; }
+}
+
+/** The doctor executes this same import, but never calls runMachine. */
+export async function loadAdapter() {
+  const [major, minor] = process.versions.node.split('.').map(Number);
+  if (major < 22 || (major === 22 && minor < 18)) throw new WorkerError('UNSUPPORTED_RUNTIME', 'Codex Pro requires Node.js 22.18.0 or newer');
+  if (!['darwin', 'linux'].includes(process.platform)) throw new WorkerError('UNSUPPORTED_RUNTIME', 'Codex Pro requires a supported POSIX platform');
+  let manifest, api;
+  try {
+    manifest = require('dsh-subagent-codex-pro/package.json');
+  } catch {
+    throw new WorkerError('ADAPTER_UNAVAILABLE', 'Install the exact dsh-subagent-codex-pro@0.8.0 dependency with Flywheel');
+  }
+  if (manifest.name !== ADAPTER.package || manifest.version !== ADAPTER.version) {
+    throw new WorkerError('ADAPTER_MISMATCH', 'Codex Pro package identity or version does not match the pinned contract');
+  }
+  try { api = await import('dsh-subagent-codex-pro/machine'); }
+  catch { throw new WorkerError('ADAPTER_UNAVAILABLE', 'The pinned Codex Pro public machine API could not be imported'); }
+  if (api.MACHINE_PROTOCOL_VERSION !== ADAPTER.protocol ||
+      typeof api.parseMachineRequest !== 'function' || typeof api.runMachine !== 'function' || typeof api.MachineInputError !== 'function') {
+    throw new WorkerError('ADAPTER_MISMATCH', 'Codex Pro package identity, version or public machine API does not match the pinned contract');
+  }
+  return api;
+}
+
+/** Reject unsupported fields and permissions before any process or prompt starts. */
+export function machineRequest(value, api, env) {
+  const keys = new Set(['type', 'protocol', 'requestId', 'cwd', 'model', 'reasoningEffort', 'permissionMode', 'prompt', 'timeoutMs']);
+  if (value === null || typeof value !== 'object' || Array.isArray(value) || value.type !== 'start' || value.protocol !== 1 ||
+      Object.keys(value).some(key => !keys.has(key)) || typeof value.requestId !== 'string' || value.requestId.length > 256 ||
+      !['read-only', 'workspace-write'].includes(value.permissionMode)) {
+    throw new WorkerError('INVALID_REQUEST', 'Expected one protocol=1 start request with an explicit supported permission mode');
+  }
+  if (value.timeoutMs !== undefined && (!Number.isSafeInteger(value.timeoutMs) || value.timeoutMs < 1 || value.timeoutMs > 2147483647)) {
+    throw new WorkerError('INVALID_REQUEST', 'timeoutMs must be a positive safe integer no greater than 2147483647');
+  }
+  try {
+    return api.parseMachineRequest({ protocol: 1, requestId: value.requestId, cwd: value.cwd, model: value.model,
+      effort: value.reasoningEffort, permissionMode: value.permissionMode, prompt: value.prompt,
+      ...(value.timeoutMs === undefined ? {} : { timeoutMs: value.timeoutMs }),
+      command: env.FLYWHEEL_CODEX_BIN || 'codex', threadMode: 'ephemeral', maxOutputBytes: LIMITS.machineOutputBytes });
+  } catch (error) {
+    throw new WorkerError('INVALID_REQUEST', error instanceof api.MachineInputError ? error.message : 'Invalid Codex Pro machine request');
+  }
+}
+
+export function doctorResult() {
+  return { protocol: 1, type: 'doctor', package: ADAPTER.package, version: ADAPTER.version,
+    machineProtocol: ADAPTER.protocol, available: true, inferenceTested: false };
+}

package/dist/codex-pro-worker.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// One owned invocation. stdin remains a lifeline to the Go parent after admission.
+import { ADAPTER, LIMITS, WorkerError, loadAdapter, machineRequest, doctorResult } from './codex-pro-bridge.js';
+
+const controller = new AbortController();
+let cancelledBy, inputFailure, outputFailure, requestId = 'invalid-request', finished = false;
+const cancel = signal => { cancelledBy ??= signal; controller.abort(); };
+const handlers = new Map(['SIGTERM', 'SIGINT', 'SIGHUP'].map(signal => [signal, () => cancel(signal)]));
+for (const [signal, handler] of handlers) process.on(signal, handler);
+process.stdout.on('error', () => {
+  outputFailure ??= new WorkerError('OUTPUT_ERROR', 'The result consumer closed or failed');
+  process.exitCode = 1;
+  controller.abort();
+});
+
+function write(frame) {
+  if (outputFailure) return;
+  const line = JSON.stringify(frame) + '\n';
+  if (Buffer.byteLength(line) > LIMITS.receiptFrameBytes) throw new WorkerError('OUTPUT_LIMIT', 'Codex Pro result exceeded the complete receipt frame limit');
+  process.stdout.write(line);
+}
+
+/** Do not close stdin after the first line: parent death must cancel the run. */
+function input() {
+  let bytes = 0, buffer = Buffer.alloc(0), admitted = false, resolveInput, rejectInput;
+  const promise = new Promise((resolve, reject) => { resolveInput = resolve; rejectInput = reject; });
+  const fail = (code, message) => {
+    if (finished) return;
+    inputFailure ??= new WorkerError(code, message);
+    clearTimeout(timer);
+    rejectInput(inputFailure);
+    controller.abort();
+  };
+  const timer = setTimeout(() => fail('INPUT_TIMEOUT', 'No complete start request arrived within 10 seconds'), LIMITS.admissionMs);
+  const onData = chunk => {
+    bytes += chunk.length;
+    if (bytes > LIMITS.requestBytes) { fail('INPUT_LIMIT', 'The request exceeded the 1 MiB input limit'); return; }
+    if (admitted) {
+      if (chunk.toString('utf8').trim() !== '') fail('INVALID_REQUEST', 'Only one start request is allowed');
+      return;
+    }
+    buffer = Buffer.concat([buffer, chunk]);
+    const newline = buffer.indexOf(10);
+    if (newline < 0) return;
+    admitted = true;
+    clearTimeout(timer);
+    if (buffer.subarray(newline + 1).toString('utf8').trim() !== '') { fail('INVALID_REQUEST', 'Only one start request is allowed'); return; }
+    try { resolveInput(JSON.parse(buffer.subarray(0, newline).toString('utf8'))); }
+    catch { fail('INVALID_REQUEST', 'The first line must contain one JSON request'); }
+    buffer = Buffer.alloc(0);
+  };
+  const onEnd = () => fail('PARENT_DISCONNECTED', 'The parent stdin lifeline closed before completion');
+  const onError = () => fail('INPUT_ERROR', 'The parent stdin lifeline failed');
+  const onAbort = () => { clearTimeout(timer); rejectInput(new WorkerError('CANCELLED', 'Codex Pro worker was cancelled before admission')); };
+  process.stdin.on('data', onData);
+  process.stdin.once('end', onEnd);
+  process.stdin.once('error', onError);
+  controller.signal.addEventListener('abort', onAbort, { once: true });
+  if (controller.signal.aborted) onAbort();
+  return { promise, stop() {
+    clearTimeout(timer);
+    process.stdin.off('data', onData); process.stdin.off('end', onEnd); process.stdin.off('error', onError);
+    controller.signal.removeEventListener('abort', onAbort);
+    process.stdin.pause();
+    process.stdin.destroy();
+  } };
+}
+
+let lifeline;
+try {
+  const args = process.argv.slice(2);
+  if (args.length > 1 || (args.length === 1 && args[0] !== '--doctor')) throw new WorkerError('INVALID_REQUEST', 'Use flywheel-codex-pro-worker [--doctor]');
+  if (args[0] === '--doctor') {
+    await loadAdapter();
+    write(doctorResult());
+    process.exitCode = 0;
+  } else {
+    lifeline = input();
+    const value = await lifeline.promise;
+    if (typeof value?.requestId === 'string' && value.requestId.trim() !== '' && value.requestId.length <= 256) requestId = value.requestId;
+    const api = await loadAdapter();
+    if (controller.signal.aborted) throw inputFailure || new WorkerError('CANCELLED', 'Codex Pro worker was cancelled before the run');
+    const request = machineRequest(value, api, process.env);
+    requestId = request.requestId;
+    let progressBytes = 0;
+    const receipt = await api.runMachine(request, { signal: controller.signal, env: process.env, onProgress(text) {
+      if (controller.signal.aborted) return;
+      const frame = { protocol: 1, type: 'progress', requestId, text };
+      progressBytes += Buffer.byteLength(JSON.stringify(frame) + '\n');
+      if (progressBytes > LIMITS.progressBytes) {
+        outputFailure ??= new WorkerError('OUTPUT_LIMIT', 'Codex Pro progress exceeded the 1 MiB stream limit');
+        controller.abort();
+      } else write(frame);
+    } });
+    finished = true;
+    lifeline.stop();
+    const error = inputFailure || outputFailure;
+    // An output-limit error still allows a bounded terminal receipt. A broken
+    // stdout cannot, but the run has already settled and cleanup was awaited.
+    if (outputFailure?.code === 'OUTPUT_LIMIT') outputFailure = undefined;
+    write({ protocol: 1, type: 'result', requestId, adapter: ADAPTER, receipt,
+      error: error ? { code: error.code, message: error.message } : null });
+    process.exitCode = receipt.ok && !error && !controller.signal.aborted ? 0 : 1;
+  }
+} catch (error) {
+  finished = true;
+  lifeline?.stop();
+  const known = error instanceof WorkerError ? error : new WorkerError('WORKER_ERROR', 'Codex Pro worker failed before a complete receipt was available');
+  write({ protocol: 1, type: 'result', requestId, adapter: ADAPTER, receipt: null,
+    error: { code: known.code, message: known.message } });
+  process.exitCode = 1;
+} finally {
+  finished = true;
+  lifeline?.stop();
+  if (cancelledBy) process.exitCode = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 }[cancelledBy];
+  for (const [signal, handler] of handlers) process.off(signal, handler);
+}

package/dist/control.js

@@ -0,0 +1,128 @@
+import { spawn } from 'node:child_process';
+import { directory, nonempty, record } from './protocol.js';
+
+const actions = ['start', 'status', 'stop', 'config', 'doctor'];
+const checkStatuses = ['pass', 'fail', 'warn', 'unknown', 'skipped'];
+
+export async function validateControl(input, defaultCwd) {
+  if (!record(input) || !actions.includes(input.action)) {
+    throw new Error('action must be start, status, stop, config, or doctor');
+  }
+  if (Object.keys(input).some(key => !['action', 'taskDir', 'cwd', 'probe'].includes(key))) {
+    throw new Error('unknown Flywheel control argument');
+  }
+  if ('probe' in input && (input.action !== 'doctor' || typeof input.probe !== 'boolean')) {
+    throw new Error('probe must be a boolean and is only supported by doctor');
+  }
+  const needsTask = !['config', 'doctor'].includes(input.action);
+  return {
+    action: input.action,
+    taskDir: needsTask || 'taskDir' in input ? await directory(input.taskDir, 'taskDir') : '',
+    cwd: await directory(input.cwd ?? defaultCwd, 'cwd'),
+    ...(input.action === 'doctor' ? { probe: input.probe ?? false } : {}),
+  };
+}
+
+function validConfiguration(value) {
+  return record(value) && typeof value.source === 'string' && typeof value.scope === 'string' &&
+    Array.isArray(value.bindings) && value.bindings.every(binding => record(binding) &&
+      ['id', 'role', 'harness'].every(key =>
+        typeof binding[key] === 'string' && binding[key].trim() !== '') &&
+      ['route', 'profile', 'provider', 'channel', 'model', 'thinking', 'permissionMode'].every(key =>
+        binding[key] === undefined || typeof binding[key] === 'string') &&
+      ['residentSession', 'inScope'].every(key => binding[key] === undefined || typeof binding[key] === 'boolean'));
+}
+
+function validDiagnostic(value, request) {
+  return record(value) && value.kind === 'doctor' && typeof value.ok === 'boolean' &&
+    typeof value.cwd === 'string' && value.cwd.trim() !== '' && value.taskDir === request.taskDir &&
+    value.probeRequested === request.probe && value.inferenceTested === false &&
+    (value.configuration === undefined || validConfiguration(value.configuration)) &&
+    Array.isArray(value.checks) && value.checks.every(check => record(check) &&
+      typeof check.id === 'string' && check.id.trim() !== '' && checkStatuses.includes(check.status) &&
+      typeof check.summary === 'string' && check.summary.trim() !== '' &&
+      ['code', 'remedy'].every(key => check[key] === undefined || typeof check[key] === 'string'));
+}
+
+/** Only the engine executable can mutate engine state. No shell interpolation. */
+export async function runControl(input, { binary = 'flywheel', defaultCwd, signal, timeoutMs = 60000 } = {}) {
+  nonempty(binary, 'flywheelBinary', 4096);
+  if (binary.startsWith('-')) throw new Error('flywheelBinary must name an executable');
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 120000) {
+    throw new Error('controlTimeoutMs must be between 100 and 120000');
+  }
+  const request = await validateControl(input, defaultCwd);
+  if (signal?.aborted) throw new Error('Flywheel control request cancelled');
+  // Diagnostic commands own watchdog child groups. Its TERM grace, pipe
+  // WaitDelay, and quiescence confirmation may each take 5s; keep the Go owner
+  // alive long enough to finish all three instead of orphaning its workers.
+  const killGraceMs = ['config', 'doctor'].includes(request.action) ? 20000 : 500;
+  const args = ['control', request.action, '--cwd', request.cwd];
+  if (request.taskDir) args.push('--task-dir', request.taskDir);
+  if (request.probe) args.push('--probe');
+  return new Promise((resolve, reject) => {
+    const child = spawn(binary, args, {
+      cwd: request.cwd, detached: false, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    let failure;
+    let killTimer;
+    const stop = error => {
+      if (failure) return;
+      failure = error;
+      clearTimeout(timer);
+      child.kill('SIGTERM');
+      killTimer = setTimeout(() => child.kill('SIGKILL'), killGraceMs);
+    };
+    const cancel = () => stop(new Error('Flywheel control request cancelled'));
+    const timer = setTimeout(() => stop(new Error('Flywheel control request timed out')), timeoutMs);
+    signal?.addEventListener('abort', cancel, { once: true });
+    // Decode across chunks so a split UTF-8 code point is not replaced in a
+    // Chinese diagnostic, model name, or path.
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', chunk => {
+      if (failure) return;
+      stdout += chunk;
+      if (Buffer.byteLength(stdout) > 1024 * 1024) stop(new Error('Flywheel control response exceeds 1 MiB'));
+    });
+    child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-8192); });
+    child.on('error', error => { failure = error; });
+    child.on('close', (code, childSignal) => {
+      clearTimeout(timer);
+      clearTimeout(killTimer);
+      signal?.removeEventListener('abort', cancel);
+      if (failure) return reject(failure);
+      let response;
+      try { response = JSON.parse(stdout); } catch {
+        return reject(new Error(`Flywheel returned invalid JSON (exit ${code}): ${stderr.trim()}`));
+      }
+      if (!record(response) || response.protocol !== 1 || response.taskDir !== request.taskDir ||
+          typeof response.ok !== 'boolean') {
+        return reject(new Error('Flywheel control response has incompatible protocol or taskDir'));
+      }
+      if ((response.configuration !== undefined && !validConfiguration(response.configuration)) ||
+          (response.diagnostic !== undefined && !validDiagnostic(response.diagnostic, request))) {
+        return reject(new Error('Flywheel control returned a malformed configuration or diagnostic'));
+      }
+      if (request.action === 'doctor' && response.diagnostic !== undefined &&
+          response.diagnostic.ok !== response.ok) {
+        return reject(new Error('Flywheel doctor result disagrees with its control envelope'));
+      }
+      // A failed preflight is a usable report, unlike transport/protocol errors.
+      // Only the documented failure exit is allowed through this exception.
+      if (request.action === 'doctor' && code === 1 && !childSignal && response.ok === false &&
+          response.diagnostic?.ok === false) return resolve(response);
+      if (code !== 0 || childSignal || response.ok !== true) {
+        return reject(new Error(typeof response.error === 'string' ? response.error :
+          `Flywheel control failed (exit ${code}): ${stderr.trim()}`));
+      }
+      if ((request.action === 'config' && !response.configuration) ||
+          (request.action === 'doctor' && !response.diagnostic)) {
+        return reject(new Error('Flywheel control response is missing its requested report'));
+      }
+      resolve(response);
+    });
+  });
+}

package/dist/index.js

@@ -0,0 +1,74 @@
+import { runControl } from './control.js';
+import { resolveFlywheelBinary } from './installation.js';
+
+export const inject = ['commands', 'tools'];
+
+export function apply(ctx, config = {}) {
+  // Loading the desktop package accidentally into the SDK profile must not
+  // give a worker a tool that launches another orchestrator.
+  if (process.env.FLYWHEEL_DSH_NATIVE_WORKER === '1') return;
+  const binary = resolveFlywheelBinary(config);
+  const active = new Set();
+  const control = async (input, agent, signal) => {
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    signal?.addEventListener('abort', cancel, { once: true });
+    if (signal?.aborted) cancel();
+    active.add(controller);
+    try {
+      return await runControl(input, {
+        binary,
+        defaultCwd: agent?.session?.header?.cwd,
+        timeoutMs: config.controlTimeoutMs ?? 60000,
+        signal: controller.signal,
+      });
+    } finally {
+      active.delete(controller);
+      signal?.removeEventListener('abort', cancel);
+    }
+  };
+  ctx.on('dispose', () => { for (const controller of active) controller.abort(); });
+  ctx.commands.register({
+    name: 'flywheel',
+    description: '通过 Go 引擎控制 Flywheel 任务、查看实际模型配置或执行无推理环境检查。',
+    input: { hint: '{"action":"doctor"} 或 {"action":"status","taskDir":"/absolute/docs/task"}' },
+    async handler({ rawInput, agent, signal }) {
+      try {
+        const value = await control(JSON.parse(rawInput), agent, signal);
+        return { kind: 'success', text: JSON.stringify(value, null, 2) };
+      } catch (error) {
+        return { kind: 'error', text: error.message };
+      }
+    },
+  });
+  // ToolDefinition is the public raw registry format. The same boundary
+  // validates both this entry and the human slash command before spawning.
+  ctx.tools.register({
+    name: 'flywheel_control',
+    description: 'Control an existing Flywheel task via its deterministic Go engine. ' +
+      'Use status to inspect progress, start to launch in the background, stop to await cancellation. ' +
+      'Use config to inspect effective model bindings or doctor for a local preflight; these may omit taskDir. ' +
+      'Only doctor accepts probe=true to check the SDK without sending an inference prompt. ' +
+      'A successful doctor does not prove account authorization, quota, or model inference. ' +
+      'This tool never writes state.json. Do not use it to create a recursive Flywheel run.',
+    parameters: {
+      type: 'object', additionalProperties: false,
+      properties: {
+        action: { type: 'string', enum: ['start', 'status', 'stop', 'config', 'doctor'] },
+        taskDir: { type: 'string', description: 'Absolute existing task ledger directory; required for start/status/stop' },
+        cwd: { type: 'string', description: 'Absolute target repository directory; defaults to this DSH session' },
+        probe: { type: 'boolean', description: 'Doctor only: explicitly enable SDK checks without inference; defaults to false' },
+      },
+      required: ['action'],
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    timeoutMs: config.controlTimeoutMs ?? 60000,
+    isConcurrencySafe: args => ['status', 'config', 'doctor'].includes(args.action),
+    async execute(args, execution) {
+      return JSON.stringify(await control(args, execution.agent, execution.signal));
+    },
+  });
+}

package/dist/installation.js

@@ -0,0 +1,37 @@
+import { accessSync, constants, lstatSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+
+// The npm installer owns this small receipt. A desktop host can find the exact
+// launcher without relying on the login shell's PATH or editing a user patch.
+export function resolveFlywheelBinary(config = {}, environment = process.env) {
+  if (config.flywheelBinary !== undefined) {
+    if (typeof config.flywheelBinary !== 'string' || !config.flywheelBinary.trim()) throw new Error('flywheelBinary must be a nonempty command or path');
+    return config.flywheelBinary;
+  }
+  const filename = join(environment.HOME || homedir(), '.config', 'flywheel', 'installation.json');
+  let receipt;
+  try {
+    const stat = lstatSync(filename);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16384) throw new Error('invalid installation record');
+    receipt = JSON.parse(readFileSync(filename, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return 'flywheel';
+    throw new Error('Flywheel installation record is invalid; rerun flywheel setup or set flywheelBinary explicitly');
+  }
+  const launcher = receipt?.launcher;
+  if (receipt?.protocol !== 1 || receipt?.owner !== '@ckanner/flywheel' || typeof launcher?.path !== 'string'
+    || !isAbsolute(launcher.path) || !/^[a-f0-9]{64}$/.test(launcher.sha256)) {
+    throw new Error('Flywheel installation record has an unsupported contract; rerun flywheel setup');
+  }
+  try {
+    const stat = lstatSync(launcher.path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 65536) throw new Error('invalid launcher');
+    accessSync(launcher.path, constants.X_OK);
+    if (createHash('sha256').update(readFileSync(launcher.path)).digest('hex') !== launcher.sha256) throw new Error('launcher was modified');
+  } catch {
+    throw new Error('Flywheel launcher is missing or changed; preserve custom edits and rerun setup or set flywheelBinary explicitly');
+  }
+  return launcher.path;
+}