@ckanner/flywheel 0.32.1 → 0.33.0

package/dist/protocol.mjs

@@ -0,0 +1,260 @@
+import { constants } from 'node:fs';
+import { open, realpath, stat } from 'node:fs/promises';
+import { dirname, isAbsolute } from 'node:path';
+
+export const PROTOCOL = 1;
+export const SESSION_PROTOCOL = 'dsh-sdk/session-resume/worker-v2';
+export const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+export const ERROR_CODES = new Set([
+  'AUTH', 'QUOTA', 'RATE_LIMIT', 'SERVER', 'TRANSPORT', 'TIMEOUT',
+  'EMPTY_RESPONSE', 'INVALID_REQUEST', 'CONTEXT_WINDOW_EXCEEDED',
+]);
+
+export class BridgeError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export function record(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+// The engine validates contract/report contents. The host validates the typed
+// envelope before dispatch so an invalid command cannot become an unknown run.
+export function validInvestigationCommand(value) {
+  if (!record(value) || !['start', 'run', 'status', 'report', 'cancel'].includes(value.action) ||
+      Object.keys(value).some(key => !['action', 'revision', 'contract', 'report'].includes(key))) return false;
+  if ('revision' in value && (!Number.isSafeInteger(value.revision) || value.revision < 0)) return false;
+  if (!['start', 'status'].includes(value.action) && !(value.revision > 0)) return false;
+  if ((value.action === 'start') !== ('contract' in value) ||
+      (value.action === 'report') !== ('report' in value)) return false;
+  return (!('contract' in value) || record(value.contract)) && (!('report' in value) || record(value.report));
+}
+
+export function nonempty(value, label, max = 512) {
+  if (typeof value !== 'string' || value.length > max || value.trim() === '' || value.includes('\0')) {
+    throw new BridgeError('INVALID_REQUEST', `${label} must be a non-empty string (max ${max})`);
+  }
+  return value;
+}
+
+export async function directory(value, label) {
+  nonempty(value, label, 4096);
+  if (!isAbsolute(value)) throw new BridgeError('INVALID_REQUEST', `${label} must be absolute`);
+  const resolved = await realpath(value);
+  if (!(await stat(resolved)).isDirectory()) {
+    throw new BridgeError('INVALID_REQUEST', `${label} must be a directory`);
+  }
+  return resolved;
+}
+
+export async function validateStart(value) {
+  if (!record(value) || value.type !== 'start' || ![PROTOCOL, 2].includes(value.protocol)) {
+    throw new BridgeError('INVALID_REQUEST', 'expected one protocol 1 or 2 start request');
+  }
+  const allowed = new Set(['type', 'protocol', 'requestId', 'cwd', 'provider', 'model',
+    'reasoningEffort', 'permissionMode', 'prompt', 'maxTokens', 'timeoutMs', 'workspaceCwd', 'sessionTitle']);
+  if (value.protocol === 2) {
+    allowed.add('sessionId');
+    allowed.add('persistent');
+    if (value.persistent !== true) throw new BridgeError('INVALID_REQUEST', 'protocol 2 requires explicit persistent history');
+    if (value.sessionId !== undefined) nonempty(value.sessionId, 'sessionId', 512);
+  }
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new BridgeError('INVALID_REQUEST', `unsupported start field: ${key}`);
+  }
+  const requestId = nonempty(value.requestId, 'requestId', 128);
+  const provider = nonempty(value.provider, 'provider');
+  const model = nonempty(value.model, 'model');
+  const prompt = nonempty(value.prompt, 'prompt', MAX_FRAME_BYTES);
+  if (!['read-only', 'workspace-write', 'danger-full-access'].includes(value.permissionMode)) {
+    throw new BridgeError('INVALID_REQUEST', 'permissionMode must be read-only, workspace-write or danger-full-access');
+  }
+  if (value.reasoningEffort !== undefined) nonempty(value.reasoningEffort, 'reasoningEffort', 64);
+  if (value.maxTokens !== undefined && (!Number.isSafeInteger(value.maxTokens) || value.maxTokens < 1)) {
+    throw new BridgeError('INVALID_REQUEST', 'maxTokens must be a positive integer');
+  }
+  const timeoutMs = value.timeoutMs ?? 30 * 60 * 1000;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 24 * 60 * 60 * 1000) {
+    throw new BridgeError('INVALID_REQUEST', 'timeoutMs must be between 1 and 86400000');
+  }
+  if (value.sessionTitle !== undefined) nonempty(value.sessionTitle, 'sessionTitle', 512);
+  const request = { ...value, requestId, provider, model, prompt, timeoutMs, cwd: await directory(value.cwd, 'cwd'),
+    ...(value.workspaceCwd === undefined ? {} : { workspaceCwd: await directory(value.workspaceCwd, 'workspaceCwd') }) };
+  if (request.workspaceCwd && request.workspaceCwd !== request.cwd && request.permissionMode === 'workspace-write') {
+    throw new BridgeError('INVALID_REQUEST', 'DSH workspace-write binds its sandbox to the session project; separate execution roots require an explicitly compatible permission mode');
+  }
+  return request;
+}
+
+export async function readPolicyReceipt(path, identity) {
+  if (!isAbsolute(path) || await realpath(dirname(path)) !== dirname(path)) {
+    throw new BridgeError('INVALID_REQUEST', 'policy receipt directory is not physical');
+  }
+  const parent = await stat(dirname(path));
+  if (!parent.isDirectory() || (parent.mode & 0o077) !== 0) {
+    throw new BridgeError('INVALID_REQUEST', 'policy receipt directory is not private');
+  }
+  // A malicious/incorrect SDK must not stall the worker by substituting a FIFO.
+  const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const info = await file.stat();
+    if (!info.isFile() || info.size > 65536 || (info.mode & 0o077) !== 0) {
+      throw new BridgeError('INVALID_REQUEST', 'policy receipt is not a bounded private regular file');
+    }
+    const buffer = Buffer.alloc(65537);
+    const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+    if (bytesRead !== info.size) throw new BridgeError('INVALID_REQUEST', 'policy receipt changed while being read');
+    const receipt = JSON.parse(buffer.subarray(0, bytesRead).toString('utf8'));
+    if (!record(receipt) || Object.entries(identity).some(([key, value]) => receipt[key] !== value)) {
+      throw new BridgeError('INVALID_REQUEST', 'policy receipt identity mismatch; prompt withheld');
+    }
+    return receipt;
+  } finally {
+    await file.close();
+  }
+}
+
+export function normalizedError(error) {
+  return {
+    code: ERROR_CODES.has(error?.code) ? error.code : 'TRANSPORT',
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+export function modelErrorCode(code) {
+  if (ERROR_CODES.has(code)) return code;
+  if (code === 'MISSING_CREDENTIAL' || code === 'INVALID_CREDENTIAL' ||
+      code === 'ACCOUNT_SIGN_IN_REQUIRED' || code === 'ACCOUNT_TOKEN_INVALID') return 'AUTH';
+  if (code === 'ACCOUNT_QUOTA') return 'QUOTA';
+  if (code === 'NO_ADAPTER' || code === 'UNSUPPORTED_REASONING_EFFORT') return 'INVALID_REQUEST';
+  return 'SERVER';
+}
+
+const ACCOUNT_RECOVERY = new Map([
+  ['ACCOUNT_SIGN_IN_REQUIRED', 'Sign in to DeepSeek in DSH, then ensure the SDK runtime can access that account and the configured endpoint permits account authentication before retrying.'],
+  ['ACCOUNT_TOKEN_INVALID', 'The DeepSeek account login was rejected. Sign in again in DSH and ensure the SDK runtime can access the renewed login before retrying.'],
+  ['ACCOUNT_QUOTA', 'Check the DeepSeek account balance and usage; retry when account quota is available.'],
+]);
+
+function modelErrorMessage(detail, fallback) {
+  const message = detail?.message ?? fallback;
+  const recovery = ACCOUNT_RECOVERY.get(detail?.code);
+  return recovery === undefined ? message : `${detail.code}: ${message}\n${recovery}`;
+}
+
+/** Fold committed per-call records; streamed usage snapshots are never summed. */
+export class SessionFold {
+  constructor(sessionId, { strict = false } = {}) {
+    this.sessionId = sessionId;
+    this.strict = strict;
+    this.seen = new Set();
+    this.policy = null;
+    this.beginCall();
+  }
+
+  // Resume may append model selection/policy facts, but those are not a paid
+  // invocation. Never inherit previous assistant output, terminal or usage.
+  beginCall() {
+    this.receipts = new Set();
+    this.text = '';
+    this.assistantCount = 0;
+    this.usageComplete = true;
+    this.usage = { input_tokens: 0, output_tokens: 0, reasoning_tokens: 0,
+      cache_read_tokens: 0, cache_write_tokens: 0, total_tokens: 0 };
+    this.terminal = null;
+    this.turnId = '';
+  }
+
+  accept(params) {
+    if (!record(params) || params.sessionId !== this.sessionId) return false;
+    const event = params.event;
+    if (!record(event) || typeof event.type !== 'string' ||
+        !Number.isSafeInteger(event.seq) || event.seq < 0 || !record(event.data)) {
+      throw new BridgeError('TRANSPORT', 'malformed DSH session event');
+    }
+    if (this.seen.has(event.seq)) return false;
+    this.seen.add(event.seq);
+    const data = event.data;
+    if (event.type === 'agent/inbox/spliced' && Array.isArray(data.inserted)) {
+      for (const message of data.inserted) if (typeof message?.id === 'string') this.receipts.add(message.id);
+    }
+    if (event.type === 'assistant/message') {
+      if (!Array.isArray(data.message?.content) || !data.message.content.every(block =>
+        record(block) && typeof block.type === 'string' &&
+        (block.type !== 'text' || typeof block.text === 'string'))) {
+        throw new BridgeError('TRANSPORT', 'malformed committed assistant message');
+      }
+      this.assistantCount += 1;
+      this.text = data.message.content.filter(block => block.type === 'text').map(block => block.text).join('');
+      this.addUsage(data.usage);
+    }
+    if (event.type === 'turn/end') {
+      if (!record(data.reason) || typeof data.reason.kind !== 'string' ||
+          (this.strict && (!Number.isSafeInteger(data.turn) || data.turn < 0 ||
+            !['completed', 'aborted', 'blocked', 'error', 'max-tokens'].includes(data.reason.kind)))) {
+        throw new BridgeError('TRANSPORT', 'malformed DSH turn terminal');
+      }
+      this.terminal = data.reason;
+      this.turnId = Number.isSafeInteger(data.turn) ? String(data.turn) : '';
+    }
+    return true;
+  }
+
+  addUsage(usage) {
+    const valid = value => Number.isSafeInteger(value) && value >= 0;
+    const fields = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens', 'totalTokens'];
+    if (!record(usage) || !valid(usage.inputTokens) || !valid(usage.outputTokens) ||
+        fields.some(key => usage[key] !== undefined && !valid(usage[key]))) {
+      this.usageComplete = false;
+      return;
+    }
+    const cacheRead = usage.cacheReadTokens ?? 0;
+    const cacheWrite = usage.cacheWriteTokens ?? 0;
+    const input = usage.inputTokens + cacheRead + cacheWrite;
+    const values = {
+      input_tokens: input, output_tokens: usage.outputTokens,
+      reasoning_tokens: usage.reasoningTokens ?? 0,
+      cache_read_tokens: cacheRead, cache_write_tokens: cacheWrite,
+      total_tokens: usage.totalTokens ?? input + usage.outputTokens,
+    };
+    for (const [key, value] of Object.entries(values)) {
+      if (!Number.isSafeInteger(this.usage[key] + value)) this.usageComplete = false;
+      else this.usage[key] += value;
+    }
+  }
+
+  verifiedPolicy(request) {
+    const policy = this.policy;
+    const fullAccess = request.permissionMode === 'danger-full-access';
+    if (!policy || policy.protocol !== PROTOCOL || policy.permissionMode !== request.permissionMode ||
+        policy.cwd !== (request.workspaceCwd ?? request.cwd) || policy.approvalPolicy !== 'never' ||
+        policy.confinedShell !== !fullAccess ||
+        (fullAccess ? policy.enforcement !== undefined : policy.enforcement !== 'full')) {
+      throw new BridgeError('INVALID_REQUEST', 'DSH did not attest the requested cwd and permission policy; prompt withheld');
+    }
+  }
+
+  finish(messageId) {
+    if (!this.receipts.has(messageId)) throw new BridgeError('TRANSPORT', 'missing durable prompt receipt');
+    if (!this.terminal) throw new BridgeError('TRANSPORT', 'idle without committed turn/end');
+    if (this.terminal.kind !== 'completed') {
+      // DSH's account-tasks hook cancels the active account turn after sign-out,
+      // including when rejecting an expired token. Do not infer this from text
+      // or treat other cancellation hooks as authentication failures.
+      if (this.terminal.kind === 'aborted' && this.terminal.reason?.kind === 'hook' &&
+          this.terminal.reason.reason === 'deepseek-account/signed-out') {
+        throw new BridgeError('AUTH', 'DeepSeek account signed out (deepseek-account/signed-out). Sign in again in DSH and ensure the SDK runtime can access that account before retrying.');
+      }
+      const detail = this.terminal.error;
+      throw new BridgeError(modelErrorCode(detail?.code),
+        modelErrorMessage(detail, `DSH turn ended as ${this.terminal.kind}`));
+    }
+    if (!this.assistantCount || this.text.trim() === '') {
+      throw new BridgeError('EMPTY_RESPONSE', 'DSH completed without assistant text');
+    }
+    return { text: this.text, usage: this.usageComplete ? this.usage : null };
+  }
+}

package/dist/task-association.mjs

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+import { validInvestigationCommand } from './protocol.mjs';
+
+// This read model folds existing public command/tool events. Third-party DSH
+// plugins must not invent Session.append event types or write engine state.
+export const taskProjectionKey = 'flywheelTask';
+const modes = ['auto', 'quick', 'full'];
+const taskActions = ['investigate', 'launch', 'start', 'status', 'stop', 'step', 'session', 'deliver'];
+export const mutatesTask = action => ['investigate', 'launch', 'start', 'stop', 'step', 'session', 'deliver'].includes(action);
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const path = value => typeof value === 'string' && value.startsWith('/') && !/[\0\r\n]/.test(value);
+const parse = value => { try { return JSON.parse(value); } catch { return null; } };
+const sameTask = (a, b) => a.taskDir === b.taskDir && a.cwd === b.cwd;
+const operationSchema = z.object({
+  operationId: z.string(), sequence: z.number().int().nonnegative(),
+  action: z.enum(taskActions), taskDir: z.string(), cwd: z.string(),
+});
+const taskViewSchema = operationSchema.extend({
+  outcome: z.enum(['pending', 'confirmed', 'unknown']), message: z.string(),
+});
+const viewSchema = taskViewSchema.extend({ tasks: z.array(taskViewSchema).optional() }).nullable();
+const stateSchema = z.object({
+  cwd: z.string(), inheritedEventCount: z.number().int().nonnegative(),
+  calls: z.record(z.string(), operationSchema), view: viewSchema, tasks: z.record(z.string(), taskViewSchema),
+});
+
+function request(input, cwd, operationId, sequence, launchOnly = false) {
+  if (!record(input)) return null;
+  const value = launchOnly ? { ...input, action: 'launch' } : input;
+  if (!taskActions.includes(value.action) || !path(value.taskDir) || !path(value.cwd ?? cwd) ||
+      Object.keys(input).some(key => !(launchOnly ? ['taskDir', 'cwd', 'mode'] : ['action', 'taskDir', 'cwd', 'mode', 'only', 'packet', 'revision', 'retryReason', 'session', 'delivery', 'investigation']).includes(key)) ||
+      ('mode' in value && (!['start', 'launch'].includes(value.action) || !modes.includes(value.mode)))) return null;
+  if (value.action === 'step' && (!['plan', 'execute', 'review', 'verify', 'integrate', 'final'].includes(value.only) || !Number.isSafeInteger(value.revision) || value.revision < 1)) return null;
+  if (value.action === 'investigate' ? !validInvestigationCommand(value.investigation) : 'investigation' in value) return null;
+  if (value.action === 'session' && (!record(value.session) || !['claim','send','return','reconcile','release'].includes(value.session.action) || !Number.isSafeInteger(value.session.revision) || value.session.revision < 1 || typeof value.session.key !== 'string')) return null;
+  if (value.action === 'deliver' && (!record(value.delivery) || value.delivery.confirmed !== true || !['create','merge'].includes(value.delivery.action))) return null;
+  return { operationId, sequence, action: value.action, taskDir: value.taskDir, cwd: value.cwd ?? cwd };
+}
+
+function begin(state, input, id, event, launchOnly = false) {
+  const operation = request(input, state.cwd, id, event.seq, launchOnly);
+  if (!operation) return state;
+  const unresolved = state.view && state.view.outcome !== 'confirmed';
+  // A second attempted mutation cannot erase the first uncertain target, even
+  // when a model calls a new tool before the earlier response reaches its view.
+  const binds = mutatesTask(operation.action) && !unresolved;
+  return { ...state, calls: { ...state.calls, [id]: operation },
+    view: binds ? { ...operation, outcome: 'pending', message: '', ...(Object.keys(state.tasks).length ? { tasks: Object.values(state.tasks) } : {}) } : state.view };
+}
+
+function settle(state, id, value, failed, error) {
+  const operation = state.calls[id];
+  if (!operation) return state;
+  const calls = { ...state.calls };
+  delete calls[id];
+  let view = state.view;
+  let tasks = state.tasks;
+  const owns = view?.operationId === id;
+  const successful = !failed && record(value) && value.protocol === 1 && value.ok === true &&
+    path(value.taskDir) && (value.cwd === undefined || path(value.cwd)) && typeof value.running === 'boolean';
+  if (successful && !(operation.action === 'status' && id.startsWith('command:') && (!view || !sameTask(operation, view)))) {
+    const task = { ...operation, taskDir: value.taskDir, cwd: value.cwd ?? operation.cwd, outcome: 'confirmed', message: '' };
+    const key = JSON.stringify([task.taskDir, task.cwd]);
+    if (!tasks[key] || tasks[key].sequence < operation.sequence) {
+      tasks = Object.fromEntries(Object.entries({ ...tasks, [key]: task }).sort((a,b) => b[1].sequence - a[1].sequence).slice(0,100));
+    }
+    // Compare the logged request, not lexical input against a realpath result.
+    // A later successful status explicitly reconciles the original target.
+    const reconciles = operation.action === 'status' && view && sameTask(operation, view) && operation.sequence > view.sequence;
+    if (owns || reconciles || (!view && operation.action === 'status') ||
+        (view?.outcome === 'confirmed' && operation.sequence > view.sequence && (['launch', 'start', 'investigate'].includes(operation.action) || operation.action === 'status' && id.startsWith('tool:')))) {
+      view = { ...operation, taskDir: value.taskDir, cwd: value.cwd ?? operation.cwd, outcome: 'confirmed', message: '' };
+    }
+  } else if (owns) {
+    const typed = record(value) && value.protocol === 1 && value.type === 'flywheel-control-error' &&
+      value.action === operation.action && ['not-dispatched', 'unknown'].includes(value.dispatch);
+    // Only host-produced structured proof can release an ambiguous mutation.
+    const notDispatched = typed && value.dispatch === 'not-dispatched' || error?.code === 'ABORTED_BEFORE_DISPATCH';
+    view = { ...view, outcome: notDispatched ? 'confirmed' : 'unknown',
+      message: typed && typeof value.message === 'string' ? value.message : '' };
+  }
+  if (view && tasks !== state.tasks) view = { ...view, tasks: Object.values(tasks) };
+  return { ...state, calls, view, tasks };
+}
+
+function contentValue(content) {
+  if (!Array.isArray(content)) return null;
+  const text = content.filter(block => block?.type === 'text').map(block => block.text).join('\n');
+  return parse(text);
+}
+
+export const taskAssociationProjection = {
+  key: taskProjectionKey,
+  stateVersion: 3,
+  stateSchema,
+  init: (header, inheritedEventCount) => ({
+    cwd: typeof header.cwd === 'string' ? header.cwd : '', inheritedEventCount,
+    calls: {}, view: null, tasks: {},
+  }),
+  apply(state, event) {
+    if (event.type === 'working-directory/change') return { ...state, cwd: event.data.cwd };
+    // A fork is a new conversation: inherited Flywheel tools are context, not
+    // permission to control the parent conversation's background task.
+    if (event.seq < state.inheritedEventCount) return state;
+    const data = event.data;
+    if (event.type === 'command/run' && data.name === 'flywheel') {
+      return begin(state, parse(data.args), 'command:' + data.commandId, event);
+    }
+    if (event.type === 'command/done') {
+      return settle(state, 'command:' + data.commandId, parse(data.text), data.kind !== 'success');
+    }
+    if (event.type === 'tool/call' && ['flywheel_launch', 'flywheel_control'].includes(data.name)) {
+      return begin(state, parse(data.arguments), 'tool:' + data.callId, event, data.name === 'flywheel_launch');
+    }
+    if (event.type === 'tool/result') {
+      return settle(state, 'tool:' + data.message.toolCallId, contentValue(data.message.content), data.message.isError, data.error);
+    }
+    if (event.type === 'tool/ptc-dispatch-start' && ['flywheel_launch', 'flywheel_control'].includes(data.name)) {
+      return begin(state, data.arguments, 'tool:' + data.subCallId, event, data.name === 'flywheel_launch');
+    }
+    if (event.type === 'tool/ptc-dispatch') {
+      return settle(state, 'tool:' + data.subCallId, contentValue(data.content), data.isError, data.error);
+    }
+    return state;
+  },
+  wire: { viewSchema, view: state => state.view },
+};

package/dist/worker.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { runWorker } from './bridge.mjs';
+import { prewarmInput } from './prewarm.mjs';
+import { BridgeError, MAX_FRAME_BYTES, normalizedError } from './protocol.mjs';
+
+const controller = new AbortController();
+process.once('SIGTERM', () => controller.abort());
+process.once('SIGINT', () => controller.abort());
+process.once('SIGHUP', () => controller.abort());
+process.stdout.on('error', () => controller.abort());
+// The engine writes exactly one request then closes stdin. EOF after admission
+// is normal and must not cancel an in-flight model turn.
+async function readInput() {
+  const chunks = [];
+  let bytes = 0;
+  const admission = setTimeout(() => process.stdin.destroy(new BridgeError('TIMEOUT', 'no complete worker request within 10 seconds')), 10000);
+  try {
+    for await (const chunk of process.stdin) {
+      bytes += chunk.length;
+      if (bytes > MAX_FRAME_BYTES) throw new BridgeError('INVALID_REQUEST', 'worker request exceeds 8 MiB');
+      chunks.push(chunk);
+    }
+    const lines = Buffer.concat(chunks).toString('utf8').trim().split('\n');
+    if (lines.length !== 1 || !lines[0]) throw new BridgeError('INVALID_REQUEST', 'expected exactly one JSON line then EOF');
+    try { return JSON.parse(lines[0]); } catch {
+      throw new BridgeError('INVALID_REQUEST', 'worker request is not valid JSON');
+    }
+  } finally {
+    clearTimeout(admission);
+  }
+}
+
+const emit = value => process.stdout.write(JSON.stringify(value) + '\n');
+let warmInput;
+try {
+  if (process.argv.slice(2).some(arg => !['--doctor', '--prewarm'].includes(arg)) || process.argv.length > 3) {
+    throw new BridgeError('INVALID_REQUEST', 'worker accepts only optional --doctor or --prewarm');
+  }
+  warmInput = process.argv.includes('--prewarm') ? prewarmInput(controller) : undefined;
+  const request = warmInput ? await warmInput.admission : await readInput();
+  const result = await runWorker(request, {
+    emit, signal: controller.signal, doctor: process.argv.includes('--doctor'),
+    stderr: chunk => process.stderr.write(chunk), prewarm: warmInput,
+  });
+  process.exitCode = !result || ['ok', 'closed'].includes(result.status) ? 0 : result.status === 'cancelled' ? 143 : 1;
+} catch (error) {
+  emit({ protocol: 1, requestId: 'invalid-request', type: 'result', status: 'error', settled: true,
+    text: '', usage: null, costUsd: null, error: normalizedError(error) });
+  process.exitCode = 1;
+} finally {
+  warmInput?.stop();
+}

package/dist/workspaces.mjs

@@ -0,0 +1,42 @@
+// Only the desktop Host owns Workspace mutations. SDK workers must never open
+// a second writer on the desktop's workspace storage.
+const workerId = /^flywheel-[a-f0-9-]{36}$/;
+
+export async function reconcileWorkspaces(ctx, response) {
+  const registry = ctx.get?.('workspaceRegistry');
+  const persistence = ctx.get?.('sessionPersistence');
+  if (!registry || !persistence) return;
+  const project = response?.state?.project?.['workspace-cwd'];
+  if (project) await registry.create(project);
+  const groups = new Map(registry.list().map(workspace => [workspace.path, workspace]));
+  if (!groups.size) return;
+  // Public metadata listing, never a scan of project directories or session
+  // event bodies. attachSession independently validates the persisted header.
+  for (const snapshot of await persistence.list()) {
+    const header = snapshot.header;
+    if (!workerId.test(header.id)) continue;
+    const workspace = groups.get(header.cwd);
+    if (workspace && !workspace.sessionIds.includes(header.id)) {
+      await workspace.attachSession(header.id);
+    }
+  }
+}
+
+export function watchWorkspaces(ctx) {
+  // SDK profile/older compositions may omit Workspace entirely. Keep the
+  // controller available, and mount reconciliation when the public services exist.
+  ctx.inject?.(['workspaceRegistry', 'sessionPersistence'], (scope) => {
+    let busy = false;
+    const refresh = async () => {
+      if (busy) return;
+      busy = true;
+      try { await reconcileWorkspaces(scope); }
+      catch (error) { scope.logger.warn('Flywheel 工作区归属未同步：%s', error.message); }
+      finally { busy = false; }
+    };
+    const timer = setInterval(refresh, 30000);
+    timer.unref?.();
+    scope.on('dispose', () => clearInterval(timer));
+    return refresh();
+  });
+}

package/docs/README.md

@@ -31,7 +31,7 @@ execution separately.
 | --- | --- | --- |
 | Development setup, quality gates, and pull requests | [Contributing](en/contributing.md) | [贡献指南](zh-CN/contributing.md) |
 | Documentation ownership, bilingual updates, and review checklist | [Maintenance rules](en/contributing.md#keep-documentation-organized) | [文档维护规范](zh-CN/contributing.md#保持文档结构清晰) |
-| Build, verify, publish, and recover a six-package release | [Release runbook](en/releasing.md) | [发行手册](zh-CN/releasing.md) |
+| Build, verify, publish, and recover a complete single-package release | [Release runbook](en/releasing.md) | [发行手册](zh-CN/releasing.md) |
 | DSH package, host compatibility, and worker setup | [Plugin README](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/README.md) | [插件说明](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/README.zh-CN.md) |
 
 The [architecture specification](design.md) is the maintained design contract

package/docs/README.zh-CN.md

@@ -27,7 +27,7 @@
 | --- | --- | --- |
 | 开发环境、质量门禁和 PR 流程 | [贡献指南](zh-CN/contributing.md) | [Contributing](en/contributing.md) |
 | 文档归属、双语更新和审阅清单 | [文档维护规范](zh-CN/contributing.md#保持文档结构清晰) | [Maintenance rules](en/contributing.md#keep-documentation-organized) |
-| 六包构建、验证、发布和恢复 | [发行手册](zh-CN/releasing.md) | [Release runbook](en/releasing.md) |
+| 单包构建、验证、发布和恢复 | [发行手册](zh-CN/releasing.md) | [Release runbook](en/releasing.md) |
 | DSH 包、宿主兼容和 worker 接入 | [插件说明](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/README.zh-CN.md) | [Plugin README](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/README.md) |
 
 [架构规范](design.md)是当前维护的设计契约，以中文编写。[Worker 协议](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/PROTOCOL.md)、[schema 与模板](https://github.com/ckanner/flywheel/tree/main/templates)及[仓库约定](https://github.com/ckanner/flywheel/blob/main/AGENTS.md)定义实现接口；版本变化见 [CHANGELOG](../CHANGELOG.md)。

package/docs/design.md

@@ -628,6 +628,7 @@ Go 的 `make quality-gate` 执行 vet、gofmt 和 **逐函数 100% statement cov
 | P5 就绪队列与一次性 DSH 预热 | [实施计划](plans/2026-11-13-p5-ready-queue-prewarm.md) | [工程验证与收益边界](validation/2026-11-13-p5-ready-queue-prewarm.md) |
 | 历史影子评估（已退役） | [原 JEV 方案](plans/2026-11-10-jev-shadow.md) | [历史验收](validation/2026-11-10-jev-shadow.md) |
 | 0.30.2 发行与安装 | [发行流程](zh-CN/releasing.md) | [发行记录](validation/2026-11-11-release-0.30.2.md) |
+| 0.33.0 单包分发 | [发行流程](zh-CN/releasing.md) | [工程验证](validation/2026-11-14-single-package.md) |
 | 0.31.0 发行与安装 | [发行流程](zh-CN/releasing.md) | [发行记录](validation/2026-11-11-release-0.31.0.md) |
 
 提案保留当时的背景和分期，验收记录保留实际结果；现行行为以本文、schema 和当前使用指南为准。新增实现应修改对应章节，发布事实写入 changelog 和验收记录，不在文档开头或结尾追加另一套现行说明。
@@ -785,19 +786,21 @@ DSH 插件按公开 API 的兼容系列声明 `>=0.2.1-rc.5 <0.3.0-0`；DSH 使
 
 ### 13.1 npm 安装与发行
 
-正式分发以 npm 为入口：`npx -y @ckanner/flywheel@latest install` 显式协调同版本全局 CLI、worker、DSH 桌面插件与内嵌 skills。普通 `npm install` 不通过 postinstall 修改用户配置；安装器不要求源码 checkout 或本机 Go 编译器。四个平台包仍由 optionalDependencies 选择，插件是精确版本依赖，全部六包版本一致。安装不会替换用户的 DSH 桌面或代办模型账号登录。
+正式分发以 npm 为入口：`npx -y @ckanner/flywheel@latest install` 显式协调同版本全局 CLI、worker、DSH 桌面插件与内嵌 skills。普通 `npm install` 不通过 postinstall 修改用户配置；安装器不要求源码 checkout 或本机 Go 编译器。从 0.33 起只发布 `@ckanner/flywheel`：一个 tarball 内含 CLI、DSH Host／Client、worker 与四个平台 Go 二进制；skills 与模板继续内嵌在引擎中。`native/manifest.json` 固定版本、平台集合和各二进制摘要，启动器仅选择包内当前平台并核对完整性，不再下载或查找独立平台包。源码中的 `plugins/dsh` 仅为 private 构建／测试区。安装不会替换用户的 DSH 桌面或代办模型账号登录。
+
+桌面从拆包版本升级时，安装器先读取现有依赖，安装并确认新的完整包，再通过官方 DSH CLI 移除旧 `@ckanner/dsh-plugin-flywheel`，最后确认旧名不存在且新版本精确匹配。旧包移除失败时，仅在能确认旧包仍存在且替代包为本次新增的情况下回退；取消不启动新的回退子进程，局部状态在 JSON 报告中保留，重试先重新读取实际状态。自定义 file/git 来源的旧插件不自动迁移。升级前应退出 DSH；当前进程未重载不算新版已生效。全局配置、项目契约和历史调用账本不因包迁移而重写。
 
 npm shim 异步运行原生引擎，收到 TERM/INT/HUP 时转发给 Go 并等待退出；不能把仅 wrapper 退出当成子进程完成。worker 通过安装包公开入口解析绝对路径。桌面入口使用安装记录与绝对启动路径，避免依赖 GUI 恰好继承终端 PATH。用户显式配置优先，安装不覆盖已有 Flywheel 模型配置。
 
 skills 继续从同一 Go 二进制内嵌资源安装。每个受管快照保存内容与权限清单；升级前确认原内容未被用户修改，额外文件、未知标记或陌生目录保留并报冲突。先写完整 staging，再以 rename 切换并保留失败回滚；这是逐 skill 更新，不是全部目录的整体事务。旧文本标记只在目录与当前内嵌快照完全一致时迁移。`install-skills --json` 供安装器取得完整结果，部分失败不能报告整套成功。
 
-发布以精确 HEAD 标签与干净候选为依据。构建一次六包候选，Linux/macOS 安装测试消费同一组包；已存在版本必须核对 integrity。平台包与插件先发布、meta 最后发布，精确版本从 registry 安装验证后才推进 latest，防止倒退。源码 PR CI 通过、npm pack 成功、registry 安装通过与用户 Mac 实机验收是不同证据，分别记录。
+发布以精确 HEAD 标签与干净候选为依据。构建一次完整单包候选（candidate format 2），Linux/macOS 安装测试消费同一个 tarball；候选验证同时核对四个平台二进制、公开入口、MIT 许可和内置 adapter。已存在版本必须核对 integrity；先发 candidate 标签，精确版本从 registry 安装验证后才推进 latest，防止倒退。源码 PR CI 通过、npm pack 成功、registry 安装通过与用户 Mac 实机验收是不同证据，分别记录。
 
-历史 0.28.2 使用 DeepSeek API Key 默认，账号默认修复从 0.28.3 开始提供；这些版本差异保留在 changelog 和发行记录，升级仍须显式迁移已有配置，不重写已发布的包。DSH 插件精确依赖上游 `dsh-subagent-codex-pro@0.9.0`；该已审查源码候选以真实 npm tarball 锁定并 bundle 到插件，来源、许可证和摘要见 [vendor 记录](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/vendor/README.md)。Claude 0.4.0 维持可选 peer。旧发行失败与重试记录保留在 [npm 验证记录](validation/2026-11-01-npm-installation.md)；源码、候选、CI、registry 和 Mac 实机证据分别记录，不混为一个“测试通过”。
+历史 0.28.2 使用 DeepSeek API Key 默认，账号默认修复从 0.28.3 开始提供；这些版本差异保留在 changelog 和发行记录，升级仍须显式迁移已有配置，不重写已发布的包。DSH 插件精确依赖上游 `dsh-subagent-codex-pro@0.9.0`；该已审查源码候选以真实 npm tarball 锁定并 bundle 到完整包，来源、许可证和摘要见 [vendor 记录](https://github.com/ckanner/flywheel/blob/main/plugins/dsh/vendor/README.md)。Claude 0.4.0 维持可选 peer。旧发行失败与重试记录保留在 [npm 验证记录](validation/2026-11-01-npm-installation.md)；源码、候选、CI、registry 和 Mac 实机证据分别记录，不混为一个“测试通过”。
 
 CI、候选构建、双平台验证和发布统一固定为 Node 24.22.1／npm 12.2.1，预检只需同版 Node。发行协议测试通过隔离的本地 registry 调用真实 `npm view`，覆盖 latest、integrity、缺失字段与错误响应。存在的字段必须返回字符串，兼容用单元素数组包裹；多结果拒绝，缺失 latest 单独处理，缺失 integrity 不能当成版本不存在。只有结构化 E404 表示版本不存在，取消、认证或网络错误仍阻止发布。npm 11／12 的 `pack --json` 兼容保持严格包身份检查。
 
-GitHub Actions 的 publish job 使用固定 Node/npm 发行工具链，支持 OIDC trusted publishing 及已有 `NPM_TOKEN` 后备。无 token 时显式使用空 user npmrc，避免 setup-node 的认证占位配置；不在日志或 GitHub 环境文件中写入凭证。六个包各自的 npm trusted publisher 都必须对应 `ckanner/flywheel` 的 `publish.yml`，并分别允许直接 publish 与 dist-tag；GitHub 登录或 `id-token: write` 本身不授予 npm 包写权限。维护者配置和失败恢复见 [发行指南](zh-CN/releasing.md)。
+GitHub Actions 的 publish job 使用固定 Node/npm 工具链，仅通过 OIDC trusted publishing 认证；显式使用空 user npmrc 并清空认证占位值，不依赖存储 token 或浏览器逐包确认。只为完整包 `@ckanner/flywheel` 配置对应 `ckanner/flywheel`／`publish.yml` 的 npm Trusted Publisher，同时允许 publish 与 dist-tag。GitHub 登录或 `id-token: write` 本身不授予 npm 包写权限；新连接需实际 CI 发布来完成 npm 的验证。维护者配置和失败恢复见 [发行指南](zh-CN/releasing.md)。
 
 私有仓库的发行同样经过完整门禁。发布 job 在准备 npm 后，由官方 checkout 使用短暂的只读 GitHub 认证重新取得完整 refs，固定到已验证 source，再下载候选并检查精确 tag；后续不执行无凭证的远端 fetch。仓库可见性由 GitHub 事件显式传给 publisher，未知值拒绝发布。public 要求 npm provenance，private 显式关闭 npm 不支持的证明生成；这只记录 registry 的能力边界，不改变仓库可见性，也不取消本项目的 source／artifact integrity 校验。
 

package/docs/en/configuration.md

@@ -542,7 +542,7 @@ Main-task fresh and scoped calls both use outer worker protocol 3. Fresh selects
 
 | Variable | Purpose |
 |---|---|
-| `FLYWHEEL_DSH_WORKER` | Optional DSH worker override; the npm launcher normally resolves the matching dependency |
+| `FLYWHEEL_DSH_WORKER` | Optional DSH worker override; the npm launcher normally resolves the worker inside its own package |
 | `FLYWHEEL_DSH_BIN` | DSH command, otherwise `dsh` on PATH |
 | `FLYWHEEL_DSH_PROFILE` | SDK profile, default `sdk`; it must not be `desktop` |
 | `DSH_HOME` | Optional DSH configuration root, interpreted by DSH |

package/docs/en/contributing.md

@@ -100,7 +100,7 @@ FLYWHEEL_NPM_PACKAGES_DIR=dist-npm npm run test:install
 |---|---|
 | Go engine | `make quality-gate`: vet, formatting, tests, and coverage |
 | DSH plugin or worker | Plugin checks and the applicable Go-to-Node bridges |
-| npm installation or release | Root npm tests, a six-package candidate build, and installation of those tarballs |
+| npm installation or release | Root npm tests, a complete single-package candidate build, and installation of that tarball |
 | Documentation | Links, anchors, fences, runnable examples, translation consistency, and affected embedding/package contents |
 
 The Claude bridge needs the exact optional 0.4.0 machine API in the worker's
@@ -288,16 +288,15 @@ that limitation. Source merge and npm publication remain separate operations.
 
 ## Release changes
 
-Follow the [release guide](releasing.md). All six Flywheel packages share one exact
-version with exact internal dependencies and the pinned Codex Pro runtime. Build
+Follow the [release guide](releasing.md). Flywheel publishes one complete package containing all native platforms and the
+pinned Codex Pro runtime. The private DSH source harness is not published. Build
 once from final clean source and test those tarballs. Preserve the source commit,
 tree, snapshot hash, and package integrity values; the release tag must identify
 that source. Do not relabel a dirty candidate as a clean release or rebuild
 different bytes for a published version.
 
 Use the repository's release scripts for candidate checks, publication, registry
-verification, and promotion. Publish platform packages and the plugin before the
-meta package, test the exact registry version before moving `latest`, and verify
-all six tags and integrities. A partial publication resumes with the same
+verification, and promotion. Publish the complete candidate, test the exact registry version before moving
+`latest`, and verify the tag and integrity. A partial publication resumes with the same
 candidate. Manual publication requires its own explicit authorization and an
 accurate record of completed and unavailable checks.

package/docs/en/flow-console.md

@@ -3,7 +3,7 @@
 [Documentation](../README.md) · English · [简体中文](../zh-CN/flow-console.md)
 
 The DSH Flywheel view brings the current task, workflow stages, configuration, session
-interaction, and delivery into one place. Keep the CLI, platform packages, and DSH
+interaction, and delivery into one place. Keep the CLI, bundled engines, and DSH
 plugin at the same version. For installation, see [Getting started](getting-started.md).
 
 ## Find a task without entering paths

package/docs/en/getting-started.md

@@ -5,10 +5,17 @@
 Install Flywheel, connect the backends you intend to use, then run a small task.
 This guide follows the current repository. Check the installed version and the npm
 version you choose; a merged change does not update an existing installation.
-Keep the CLI, platform packages, and DSH plugin at one version.
+Keep the CLI, bundled engines, and DSH plugin at one version.
 
 For the complete path through task branches and PR review, see [Workflow](workflow.md).
 
+From 0.33, `@ckanner/flywheel` is one complete package: CLI, DSH view/workers,
+embedded skills and four platform engines. No separate platform package or first-run
+engine download is needed. When upgrading from 0.32.x, quit DSH before running the
+installer; it replaces the old desktop package registration and preserves your
+configuration and histories. Reload DSH after setup. Existing old npm versions
+remain available for historical installations.
+
 ## 1. Prepare the environment
 
 | Requirement | Purpose |
@@ -146,7 +153,7 @@ capabilities or merge full worker histories into the parent trajectory. See the
 
 Setup writes `~/.config/flywheel/npm-launcher` and an installation record containing
 absolute Node/CLI paths and the checked DSH entry. An explicit `flywheelBinary`
-overrides the managed launcher. Missing records can use legacy PATH lookup;
+overrides the managed launcher. Without a record, the installed package uses its bundled CLI;
 invalid records or modified launchers fail visibly.
 
 After moving Node/the npm prefix or installing missing tools, rerun