@tt-a1i/hive 2.1.1 → 2.1.4

package/dist/src/server/workflow-script-host-dispatcher.js

@@ -0,0 +1,42 @@
+import { planWorkflowDag } from './workflow-dag.js';
+export const dispatchWorkflowScriptHostCall = async (name, callArgs, handlers) => {
+    switch (name) {
+        case 'agent': {
+            const [prompt, opts] = callArgs;
+            return {
+                value: await handlers.agent(typeof prompt === 'string' ? prompt : String(prompt), (opts ?? {})),
+            };
+        }
+        case 'phase': {
+            const [title] = callArgs;
+            handlers.phase(typeof title === 'string' ? title : String(title ?? ''));
+            return {};
+        }
+        case 'log': {
+            const [message] = callArgs;
+            handlers.log(typeof message === 'string' ? message : String(message));
+            return {};
+        }
+        case 'workflow': {
+            const [scriptName, childArgs] = callArgs;
+            return {
+                value: await handlers.workflow(typeof scriptName === 'string' ? scriptName : String(scriptName), childArgs),
+            };
+        }
+        case 'catchPerItem': {
+            const [item] = callArgs;
+            return { value: handlers.catchPerItem(item) };
+        }
+        case 'cancelDagLayerAgents': {
+            const [layerId, reason] = callArgs;
+            handlers.cancelDagLayerAgents(layerId, reason);
+            return { skipPostActiveAssert: true };
+        }
+        case 'planDag': {
+            const [nodes] = callArgs;
+            return { value: planWorkflowDag(nodes) };
+        }
+        default:
+            throw new Error(`Unknown workflow host call: ${name}`);
+    }
+};

package/dist/src/server/workflow-script-loader.d.ts

@@ -20,8 +20,8 @@ export interface LoadedWorkflow {
     meta: WorkflowMeta;
     scriptPath: string;
     scriptHash: string;
-    /** Transpiled `async function __wf(...) {…}` — the runner executes it in a
-     *  locked-down VM context and calls it with the Hive DSL bridge functions. */
+    /** Transpiled `async function __wf(dsl) {…}` — the runner executes it in a
+     *  locked-down VM context and calls it with the Hive DSL bridge object. */
     compiledFunctionSource: string;
 }
 interface ExtractedMeta {

package/dist/src/server/workflow-script-loader.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
-const DSL_PARAMS = 'agent, parallel, pipeline, phase, log, workflow, args';
+const DSL_BINDINGS = 'agent, parallel, pipeline, phase, log, workflow, dag, args';
 const DANGEROUS_WORKFLOW_IDENTIFIERS = new Set([
     'AsyncFunction',
     'Bun',
@@ -254,7 +254,7 @@ export const loadWorkflowScriptSource = async (source, scriptPath) => {
     }
     const { meta, body } = extractMeta(source);
     assertWorkflowScriptIsSandboxable(body);
-    const wrapped = `async function __wf(${DSL_PARAMS}) {\n${body}\n}`;
+    const wrapped = `async function __wf(dsl) {\nconst { ${DSL_BINDINGS} } = dsl\n${body}\n}`;
     // Lazy-load esbuild: its native binary breaks under jsdom/worker contexts
     // used by the web test suite, so importing it at module-load time would
     // crash any test file that transitively pulls in the runtime store. The

package/dist/src/server/workflow-script-worker.d.ts

@@ -0,0 +1,14 @@
+import { Worker } from 'node:worker_threads';
+import { type WorkflowScriptHostHandlers } from './workflow-script-host-dispatcher.js';
+export type WorkflowScriptWorker = Worker;
+export type WorkflowScriptWorkerSource = string | URL;
+export interface RunWorkflowScriptWorkerInput<AgentOptions> {
+    args: unknown;
+    compiledFunctionSource: string;
+    handlers: WorkflowScriptHostHandlers<AgentOptions>;
+    onWorkerCreated?: (worker: WorkflowScriptWorker) => void;
+    onWorkerSettled?: (worker: WorkflowScriptWorker) => void;
+    scriptPath: string;
+    workerSource: WorkflowScriptWorkerSource;
+}
+export declare const runWorkflowScriptWorker: <AgentOptions>({ args, compiledFunctionSource, handlers, onWorkerCreated, onWorkerSettled, scriptPath, workerSource, }: RunWorkflowScriptWorkerInput<AgentOptions>) => Promise<unknown>;

package/dist/src/server/workflow-script-worker.js

@@ -0,0 +1,81 @@
+import { Worker } from 'node:worker_threads';
+import { dispatchWorkflowScriptHostCall, } from './workflow-script-host-dispatcher.js';
+const errorToMessage = (error) => error instanceof Error ? error.message : String(error);
+export const runWorkflowScriptWorker = ({ args, compiledFunctionSource, handlers, onWorkerCreated, onWorkerSettled, scriptPath, workerSource, }) => new Promise((resolve, reject) => {
+    const worker = new Worker(workerSource, {
+        ...(typeof workerSource === 'string' ? { eval: true } : {}),
+        workerData: {
+            args,
+            compiledFunctionSource,
+            scriptPath,
+        },
+    });
+    onWorkerCreated?.(worker);
+    let settled = false;
+    const activeHostCalls = new Set();
+    const settle = (fn, input) => {
+        if (settled)
+            return;
+        settled = true;
+        onWorkerSettled?.(worker);
+        void (async () => {
+            if (input.waitForHostCalls) {
+                await Promise.allSettled(activeHostCalls);
+            }
+            fn();
+            void worker.terminate().catch(() => { });
+        })();
+    };
+    const respond = (id, response) => {
+        try {
+            worker.postMessage({ type: 'hostResponse', id, ...response });
+        }
+        catch {
+            /* worker already terminated */
+        }
+    };
+    worker.on('message', (message) => {
+        const record = message;
+        if (!record)
+            return;
+        if (record.type === 'done') {
+            settle(() => {
+                if (record.ok)
+                    resolve(record.value);
+                else
+                    reject(new Error(record.error || 'Hive workflow script failed'));
+            }, { waitForHostCalls: record.ok === true });
+            return;
+        }
+        if (record.type !== 'hostCall' || typeof record.id !== 'string')
+            return;
+        const callId = record.id;
+        if (settled) {
+            respond(callId, { ok: false, error: 'Stopped by user' });
+            return;
+        }
+        const hostCall = (async () => {
+            try {
+                handlers.assertRunActive();
+                const callArgs = Array.isArray(record.args) ? record.args : [];
+                const result = await dispatchWorkflowScriptHostCall(record.name, callArgs, handlers);
+                if (!result.skipPostActiveAssert)
+                    handlers.assertRunActive();
+                respond(callId, { ok: true, value: result.value });
+            }
+            catch (error) {
+                respond(callId, { ok: false, error: errorToMessage(error) });
+            }
+        })();
+        activeHostCalls.add(hostCall);
+        void hostCall.finally(() => activeHostCalls.delete(hostCall));
+    });
+    worker.on('error', (error) => settle(() => reject(error), { waitForHostCalls: false }));
+    worker.on('exit', (code) => {
+        if (settled)
+            return;
+        settled = true;
+        onWorkerSettled?.(worker);
+        reject(new Error(`Hive workflow VM worker exited before completion (code ${code})`));
+    });
+});

package/dist/src/server/workflow-vm-worker-source.d.ts

@@ -0,0 +1 @@
+export declare const WORKFLOW_VM_WORKER_URL: URL;

package/dist/src/server/workflow-vm-worker-source.js

@@ -0,0 +1 @@
+export const WORKFLOW_VM_WORKER_URL = new URL('./workflow-vm-worker.cjs', import.meta.url);

package/dist/src/server/workflow-vm-worker.cjs

@@ -0,0 +1,238 @@
+const { AsyncLocalStorage } = require('node:async_hooks')
+const { parentPort, workerData } = require('node:worker_threads')
+const { Script, createContext } = require('node:vm')
+
+const BRIDGE_FACTORY = new Script(`"use strict";
+((hostCall) => {
+  const stringify = JSON.stringify;
+  const parse = JSON.parse;
+  const promiseResolve = Promise.resolve.bind(Promise);
+  const promiseThen = Promise.prototype.then;
+  return (...args) =>
+    promiseThen.call(promiseResolve(hostCall(stringify(args))), (payloadJson) => {
+      const payload = parse(payloadJson);
+      if (!payload.ok) throw new Error(payload.error || 'Hive workflow host call failed');
+      return payload.hasValue ? payload.value : undefined;
+    });
+})`)
+
+const FLOW_FACTORY = new Script(`"use strict";
+((agentBase, catchPerItem, cancelDagLayerAgents, planDag, dagLayerContext) => {
+  const promiseAll = Promise.all.bind(Promise);
+  const promiseResolve = Promise.resolve.bind(Promise);
+  const promiseThen = Promise.prototype.then;
+  const promiseCatch = Promise.prototype.catch;
+  let dagLayerCounter = 0;
+  const agent = (prompt, opts) => {
+    const activeDagLayerId = dagLayerContext.getStore();
+    if (!activeDagLayerId) return agentBase(prompt, opts);
+    const nextOpts = opts && typeof opts === 'object' ? { ...opts } : {};
+    nextOpts.__hiveDagLayerId = activeDagLayerId;
+    return agentBase(prompt, nextOpts);
+  };
+  const normalizeDagNodes = (spec) => {
+    const rawNodes = Array.isArray(spec)
+      ? spec
+      : spec && Array.isArray(spec.nodes)
+        ? spec.nodes
+        : null;
+    if (!rawNodes) throw new Error('dag(): expected an array of nodes or { nodes }');
+    return rawNodes.map((node, index) => {
+      if (!node || typeof node !== 'object') {
+        throw new Error('dag(): node #' + (index + 1) + ' must be an object');
+      }
+      const id = typeof node.id === 'string' ? node.id.trim() : '';
+      if (!id) throw new Error('dag(): node #' + (index + 1) + ' requires a non-empty string id');
+      const rawDeps = node.needs ?? node.dependsOn ?? node.after ?? [];
+      const deps = Array.isArray(rawDeps) ? rawDeps.map((dep) => String(dep).trim()) : [String(rawDeps).trim()];
+      for (const dep of deps) {
+        if (!dep) throw new Error('dag(' + id + '): dependency ids must be non-empty strings');
+      }
+      if (typeof node.run !== 'function') {
+        throw new Error('dag(' + id + '): node.run must be a function');
+      }
+      return { deps, id, run: node.run };
+    });
+  };
+  const runDagNode = (node, results) => {
+    if (typeof node.run !== 'function') {
+      throw new Error('dag(' + node.id + '): node.run must be a function');
+    }
+    const deps = Object.create(null);
+    for (const dep of node.deps) deps[dep] = results[dep];
+    return node.run(deps, results);
+  };
+  const runDagNodeInLayer = (layerId, node, results) =>
+    dagLayerContext.run(layerId, () => runDagNode(node, results));
+  const parallel = (thunks) =>
+    promiseAll(Array.from(thunks).map((thunk) =>
+      promiseCatch.call(promiseThen.call(promiseResolve(), () => thunk()), (err) => catchPerItem(err))
+    ));
+  const pipeline = (items, ...stages) =>
+    promiseAll(Array.from(items).map((item, index) => {
+      let chain = promiseResolve(item);
+      for (const stage of stages) {
+        chain = promiseThen.call(chain, (prev) => stage(prev, item, index));
+      }
+      return promiseCatch.call(chain, (err) => catchPerItem(err));
+    }));
+  const dag = async (spec) => {
+    const nodes = normalizeDagNodes(spec);
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const plan = await planDag(nodes.map((node) => ({ id: node.id, deps: node.deps })));
+    const order = [];
+    const results = Object.create(null);
+    for (const layer of plan.layers) {
+      const layerId = 'dag-layer-' + (++dagLayerCounter);
+      let values;
+      let cancelError;
+      try {
+        values = await promiseAll(layer.map((id) =>
+          promiseThen.call(promiseResolve(), () =>
+            runDagNodeInLayer(layerId, byId.get(id), results)
+          )
+        ));
+      } catch (error) {
+        const message = error && typeof error.message === 'string' ? error.message : String(error);
+        try {
+          await cancelDagLayerAgents(layerId, 'DAG node failed: ' + message);
+        } catch (cancelFailure) {
+          cancelError = cancelFailure;
+        }
+        if (cancelError) {
+          const cancelMessage =
+            cancelError && typeof cancelError.message === 'string'
+              ? cancelError.message
+              : String(cancelError);
+          throw new Error(message + '; failed to cancel DAG sibling agents: ' + cancelMessage);
+        }
+        throw error;
+      }
+      for (let index = 0; index < layer.length; index += 1) {
+        const node = byId.get(layer[index]);
+        const value = values[index];
+        results[node.id] = value === undefined ? null : value;
+        order.push(node.id);
+      }
+    }
+    return { order, results };
+  };
+  return { agent, dag, parallel, pipeline };
+})`)
+
+const JSON_PARSE = new Script('JSON.parse')
+const DAG_LAYER_CONTEXT = new AsyncLocalStorage()
+
+const encodeSuccess = (value) => {
+  const payload = { ok: true, hasValue: value !== undefined }
+  if (value !== undefined) payload.value = value
+  return JSON.stringify(payload)
+}
+
+const encodeFailure = (error) =>
+  JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })
+
+const createSafeHostCall = (fn) =>
+  new Proxy(
+    (serializedArgs) => {
+      let args
+      try {
+        const parsed = JSON.parse(serializedArgs)
+        args = Array.isArray(parsed) ? parsed : []
+      } catch (error) {
+        return encodeFailure(error)
+      }
+      try {
+        return Promise.resolve(fn(args)).then(encodeSuccess, encodeFailure)
+      } catch (error) {
+        return encodeFailure(error)
+      }
+    },
+    {
+      get: () => undefined,
+      getOwnPropertyDescriptor: () => undefined,
+      getPrototypeOf: () => null,
+      has: () => false,
+      ownKeys: () => [],
+      set: () => false,
+    }
+  )
+
+let nextCallId = 0
+const pending = new Map()
+
+parentPort.on('message', (message) => {
+  if (!message || message.type !== 'hostResponse') return
+  const entry = pending.get(message.id)
+  if (!entry) return
+  pending.delete(message.id)
+  if (message.ok) entry.resolve(message.value)
+  else entry.reject(new Error(message.error || 'Hive workflow host call failed'))
+})
+
+const callHost = (name, args) =>
+  new Promise((resolve, reject) => {
+    const id = String(++nextCallId)
+    pending.set(id, { resolve, reject })
+    parentPort.postMessage({ type: 'hostCall', id, name, args })
+  })
+
+const cloneIntoVm = (context, value) => {
+  if (value === undefined) return undefined
+  const serialized = JSON.stringify(value)
+  if (serialized === undefined) return undefined
+  return JSON_PARSE.runInContext(context)(serialized)
+}
+
+const cloneOutOfVm = (value) => {
+  if (value === undefined) return undefined
+  const serialized = JSON.stringify(value)
+  return serialized === undefined ? undefined : JSON.parse(serialized)
+}
+
+;(async () => {
+  try {
+    const context = createContext(Object.create(null), {
+      codeGeneration: { strings: false, wasm: false },
+    })
+    const bridgeFactory = BRIDGE_FACTORY.runInContext(context, { timeout: 1000 })
+    const bridge = (name) => bridgeFactory(createSafeHostCall((args) => callHost(name, args)))
+    const vmAgentBase = bridge('agent')
+    const vmPhase = bridge('phase')
+    const vmLog = bridge('log')
+    const vmWorkflow = bridge('workflow')
+    const vmCatchPerItem = bridge('catchPerItem')
+    const vmCancelDagLayerAgents = bridge('cancelDagLayerAgents')
+    const vmPlanDag = bridge('planDag')
+    const {
+      agent: vmAgent,
+      dag,
+      parallel,
+      pipeline,
+    } = FLOW_FACTORY.runInContext(context, {
+      timeout: 1000,
+    })(vmAgentBase, vmCatchPerItem, vmCancelDagLayerAgents, vmPlanDag, DAG_LAYER_CONTEXT)
+    const fn = new Script(`"use strict";\n${workerData.compiledFunctionSource}\n; __wf`, {
+      filename: workerData.scriptPath,
+    }).runInContext(context, { timeout: 1000 })
+    const value = cloneOutOfVm(
+      await fn({
+        agent: vmAgent,
+        parallel,
+        pipeline,
+        phase: vmPhase,
+        log: vmLog,
+        workflow: vmWorkflow,
+        dag,
+        args: cloneIntoVm(context, workerData.args),
+      })
+    )
+    parentPort.postMessage({ type: 'done', ok: true, value })
+  } catch (error) {
+    parentPort.postMessage({
+      type: 'done',
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    })
+  }
+})()

package/dist/src/server/workspace-ui-language.d.ts

@@ -0,0 +1,7 @@
+import { type UiLanguage } from '../shared/ui-language.js';
+import type { SettingsStore } from './settings-store.js';
+export type { UiLanguage };
+export declare const workspaceUiLanguageKey: (workspaceId: string) => string;
+export declare const readWorkspaceUiLanguage: (value: string | null | undefined) => UiLanguage | null;
+export declare const resolveWorkspaceUiLanguage: (settings: Pick<SettingsStore, "getAppState">, workspaceId: string, requestedLanguage?: unknown) => UiLanguage;
+export declare const writeWorkspaceUiLanguage: (settings: Pick<SettingsStore, "setAppState">, workspaceId: string, language: UiLanguage) => void;

package/dist/src/server/workspace-ui-language.js

@@ -0,0 +1,9 @@
+import { DEFAULT_UI_LANGUAGE, isUiLanguage } from '../shared/ui-language.js';
+export const workspaceUiLanguageKey = (workspaceId) => `workspace.${workspaceId}.ui_language`;
+export const readWorkspaceUiLanguage = (value) => isUiLanguage(value) ? value : null;
+export const resolveWorkspaceUiLanguage = (settings, workspaceId, requestedLanguage) => readWorkspaceUiLanguage(typeof requestedLanguage === 'string' ? requestedLanguage : null) ??
+    readWorkspaceUiLanguage(settings.getAppState(workspaceUiLanguageKey(workspaceId))?.value) ??
+    DEFAULT_UI_LANGUAGE;
+export const writeWorkspaceUiLanguage = (settings, workspaceId, language) => {
+    settings.setAppState(workspaceUiLanguageKey(workspaceId), language);
+};

package/dist/src/shared/scenario-presets.d.ts

@@ -1,4 +1,5 @@
 import type { WorkerRole } from './types.js';
+import type { UiLanguage } from './ui-language.js';
 /**
  * Scenario team presets — the data behind "one-click team assembly".
  *
@@ -17,7 +18,10 @@ export interface ScenarioWorkerSpec {
      * (startup prompt + every dispatch). Built-in roles omit this and fall back
      * to their default description from `role-templates.ts`.
      */
-    descriptionOverride?: string;
+    descriptionOverride?: {
+        en: string;
+        zh: string;
+    };
 }
 export interface ScenarioPreset {
     id: ScenarioId;
@@ -30,3 +34,4 @@ export interface ScenarioPreset {
 }
 export declare const SCENARIO_PRESETS: ScenarioPreset[];
 export declare const getScenarioPreset: (id: string) => ScenarioPreset | undefined;
+export declare const getScenarioWorkerDescription: (spec: ScenarioWorkerSpec, language: UiLanguage) => string | undefined;

package/dist/src/shared/scenario-presets.js

@@ -1,34 +1,66 @@
-const RESEARCHER_DESCRIPTION = [
+const RESEARCHER_DESCRIPTION_EN = [
     'You are a Researcher. Collect facts, data, and sources for the assigned topic.',
-    '工作方式 / How to work:',
-    '- Break the topic into key questions first, then investigate each one. / 先拆出要回答的关键问题，再逐项调查。',
-    '- Prefer primary sources and real project files; attach a source or file path to every conclusion. / 优先一手来源和项目内真实文件；每个结论都附上来源或文件路径。',
-    '- Separate facts, inferences, and unknowns; never present guesses as facts. / 区分事实、推断和未知，不把猜测写成结论。',
-    'Delivery / 交付说明: include findings by topic, source list, and unresolved questions.',
+    'How to work:',
+    '- Break the topic into key questions first, then investigate each one.',
+    '- Prefer primary sources and real project files; attach a source or file path to every conclusion.',
+    '- Separate facts, inferences, and unknowns; never present guesses as facts.',
+    'Delivery: include findings by topic, source list, and unresolved questions.',
 ].join('\n');
-const FACTCHECKER_DESCRIPTION = [
+const RESEARCHER_DESCRIPTION_ZH = [
+    '你是 Researcher，负责为指定主题收集事实、数据和来源。',
+    '工作方式：',
+    '- 先拆出要回答的关键问题，再逐项调查。',
+    '- 优先一手来源和项目内真实文件；每个结论都附上来源或文件路径。',
+    '- 区分事实、推断和未知，不把猜测写成结论。',
+    '交付说明：按主题列出发现、来源清单和未解决问题。',
+].join('\n');
+const FACTCHECKER_DESCRIPTION_EN = [
     'You are a Fact-checker. Verify research claims and evidence strength without expanding the scope by default.',
-    '工作方式 / How to work:',
-    '- Check every claim against its source and mark supported, uncertain, or unsupported. / 逐条核对结论与其来源，标注支持、存疑或不支持。',
-    '- Cross-check critical claims with a second source, command, or direct file read. / 对关键结论做交叉验证。',
-    '- When a claim is wrong, provide the corrected wording and evidence. / 发现错误时给出纠正后的表述和依据。',
-    'Delivery / 交付说明: group by confidence and list refuted or uncertain claims first.',
+    'How to work:',
+    '- Check every claim against its source and mark supported, uncertain, or unsupported.',
+    '- Cross-check critical claims with a second source, command, or direct file read.',
+    '- When a claim is wrong, provide the corrected wording and evidence.',
+    'Delivery: group by confidence and list refuted or uncertain claims first.',
+].join('\n');
+const FACTCHECKER_DESCRIPTION_ZH = [
+    '你是 Fact-checker，负责验证研究结论和证据强度，默认不扩范围。',
+    '工作方式：',
+    '- 逐条核对结论与其来源，标注支持、存疑或不支持。',
+    '- 对关键结论用第二来源、命令或直接读文件做交叉验证。',
+    '- 发现错误时给出纠正后的表述和依据。',
+    '交付说明：按可信度分组，先列被推翻或存疑的结论。',
 ].join('\n');
-const DRAFTER_DESCRIPTION = [
+const DRAFTER_DESCRIPTION_EN = [
     'You are a Drafter. Turn goals and source material into a clear first-draft document.',
-    '工作方式 / How to work:',
-    '- Confirm audience, purpose, and scope before outlining and writing. / 先确认读者、目的和范围，再列提纲，后成文。',
-    '- Use real project code and files as the source of truth; do not invent behavior or APIs. / 以项目内真实代码和文件为准，不编造行为或接口。',
-    '- Mark missing material and points that need confirmation. / 标注待确认和缺素材的位置。',
-    'Delivery / 交付说明: include document path, structure overview, and confirmation checklist.',
+    'How to work:',
+    '- Confirm audience, purpose, and scope before outlining and writing.',
+    '- Use real project code and files as the source of truth; do not invent behavior or APIs.',
+    '- Mark missing material and points that need confirmation.',
+    'Delivery: include document path, structure overview, and confirmation checklist.',
 ].join('\n');
-const DOC_REVIEWER_DESCRIPTION = [
+const DRAFTER_DESCRIPTION_ZH = [
+    '你是 Drafter，负责把目标和素材写成清晰的第一版文档。',
+    '工作方式：',
+    '- 先确认读者、目的和范围，再列提纲，后成文。',
+    '- 以项目内真实代码和文件为准，不编造行为或接口。',
+    '- 标注待确认和缺素材的位置。',
+    '交付说明：包含文档路径、结构概览和确认清单。',
+].join('\n');
+const DOC_REVIEWER_DESCRIPTION_EN = [
     'You are a Document Reviewer. Check a draft for accuracy and readability; do not rewrite the whole document by default.',
-    '工作方式 / How to work:',
-    '- Verify technical details against real code and files first. / 先对照项目真实代码和文件核对技术细节。',
-    '- Check structure, terminology consistency, and whether readers can follow the document. / 检查结构、术语一致性，以及读者能否按文档完成操作。',
-    '- List issues by severity with concrete edits or rewrite examples. / 问题按严重度列出，给出具体修改建议或改写示例。',
-    'Delivery / 交付说明: list factual errors first, then structure and wording issues.',
+    'How to work:',
+    '- Verify technical details against real code and files first.',
+    '- Check structure, terminology consistency, and whether readers can follow the document.',
+    '- List issues by severity with concrete edits or rewrite examples.',
+    'Delivery: list factual errors first, then structure and wording issues.',
+].join('\n');
+const DOC_REVIEWER_DESCRIPTION_ZH = [
+    '你是 Document Reviewer，负责检查草稿的准确性和可读性；默认不要整篇重写。',
+    '工作方式：',
+    '- 先对照项目真实代码和文件核对技术细节。',
+    '- 检查结构、术语一致性，以及读者能否按文档完成操作。',
+    '- 问题按严重度列出，给出具体修改建议或改写示例。',
+    '交付说明：先列事实错误，再列结构和表达问题。',
 ].join('\n');
 export const SCENARIO_PRESETS = [
     {
@@ -46,8 +78,16 @@ export const SCENARIO_PRESETS = [
     {
         id: 'research_factcheck',
         workers: [
-            { nameStem: 'researcher', role: 'custom', descriptionOverride: RESEARCHER_DESCRIPTION },
-            { nameStem: 'factchecker', role: 'custom', descriptionOverride: FACTCHECKER_DESCRIPTION },
+            {
+                nameStem: 'researcher',
+                role: 'custom',
+                descriptionOverride: { en: RESEARCHER_DESCRIPTION_EN, zh: RESEARCHER_DESCRIPTION_ZH },
+            },
+            {
+                nameStem: 'factchecker',
+                role: 'custom',
+                descriptionOverride: { en: FACTCHECKER_DESCRIPTION_EN, zh: FACTCHECKER_DESCRIPTION_ZH },
+            },
         ],
         goalTemplate: {
             en: 'Research <topic>: have the Researcher gather evidence and the Factchecker verify it; list questions, trusted sources, and the decision this research should support.',
@@ -57,8 +97,19 @@ export const SCENARIO_PRESETS = [
     {
         id: 'docs_pipeline',
         workers: [
-            { nameStem: 'drafter', role: 'custom', descriptionOverride: DRAFTER_DESCRIPTION },
-            { nameStem: 'doc-reviewer', role: 'custom', descriptionOverride: DOC_REVIEWER_DESCRIPTION },
+            {
+                nameStem: 'drafter',
+                role: 'custom',
+                descriptionOverride: { en: DRAFTER_DESCRIPTION_EN, zh: DRAFTER_DESCRIPTION_ZH },
+            },
+            {
+                nameStem: 'doc-reviewer',
+                role: 'custom',
+                descriptionOverride: {
+                    en: DOC_REVIEWER_DESCRIPTION_EN,
+                    zh: DOC_REVIEWER_DESCRIPTION_ZH,
+                },
+            },
         ],
         goalTemplate: {
             en: 'Write <doc>: have the Drafter write and the Doc Reviewer review; state the audience, scope, required sections, and code or files it should describe.',
@@ -67,3 +118,4 @@ export const SCENARIO_PRESETS = [
     },
 ];
 export const getScenarioPreset = (id) => SCENARIO_PRESETS.find((preset) => preset.id === id);
+export const getScenarioWorkerDescription = (spec, language) => spec.descriptionOverride?.[language];

package/dist/src/shared/types.d.ts

@@ -2,7 +2,8 @@ export declare const agentStatuses: readonly ["idle", "working", "stopped"];
 export type AgentStatus = (typeof agentStatuses)[number];
 export type WorkerRole = 'coder' | 'reviewer' | 'tester' | 'sentinel' | 'custom';
 /** How a worker came to exist: spawned by a workflow run or by the orchestrator
- *  (via `team spawn`). Absent/null for user-added persistent workers. */
+ *  (via `team spawn`). Absent/null for user-added workers. `ephemeral`
+ *  controls lifecycle; `spawnedBy` controls ownership/routing behavior. */
 export type WorkerSpawnSource = 'workflow' | 'orchestrator';
 export interface WorkspaceSummary {
     id: string;
@@ -38,13 +39,16 @@ export interface TeamListItem {
      * — in that case the UI falls back to the role-letter avatar.
      */
     commandPresetId?: string;
-    /** Lifecycle marker — true for workers spawned by `team spawn` or by the
-     *  workflow runner (auto-dismissed after their dispatch). Drives the team
-     *  panel's visual distinction so workflow-spawned agents read as the live
-     *  workflow fleet, not as members of the user's persistent team (M10). */
+    /** Lifecycle marker — true for one-shot workers spawned by `team spawn
+     *  --ephemeral` or by the workflow runner (auto-dismissed after their
+     *  dispatch). Drives the team panel's visual distinction so workflow-spawned
+     *  agents read as the live workflow fleet, not as members of the user's
+     *  persistent team (M10). */
     ephemeral?: boolean;
-    /** When `ephemeral`, identifies the creator: 'orchestrator' (via `team spawn`)
-     *  or 'workflow' (via the workflow runner's `agent()` call). */
+    /** Identifies the creator: 'orchestrator' (via `team spawn`) or 'workflow'
+     *  (via the workflow runner's `agent()` call). Persistent `team spawn`
+     *  workers carry this too, so `team send` can wake them instead of parking
+     *  the first dispatch. */
     spawnedBy?: 'orchestrator' | 'workflow';
 }
 /**

package/dist/src/shared/ui-language.d.ts

@@ -0,0 +1,4 @@
+export type UiLanguage = 'en' | 'zh';
+export declare const DEFAULT_UI_LANGUAGE: UiLanguage;
+export declare const isUiLanguage: (value: unknown) => value is UiLanguage;
+export declare const normalizeUiLanguage: (value: unknown, fallback?: UiLanguage) => UiLanguage;

package/dist/src/shared/ui-language.js

@@ -0,0 +1,3 @@
+export const DEFAULT_UI_LANGUAGE = 'en';
+export const isUiLanguage = (value) => value === 'en' || value === 'zh';
+export const normalizeUiLanguage = (value, fallback = DEFAULT_UI_LANGUAGE) => (isUiLanguage(value) ? value : fallback);