@steerable/agent-shell-web 0.6.27 → 0.6.29

package/src/components/chat/executed-actions-model.ts

@@ -8,6 +8,8 @@
  * result_count / status / bytes / truncated 这些小字段原样保留。
  */
 
+import { findAgentForProfile } from './orchestration-children-model';
+
 interface WebToolResultData {
   result_count?: unknown;
   status?: unknown;
@@ -121,6 +123,473 @@ export interface ExecutedActionLike {
   sandbox?: { backend?: string; enforcement: string };
 }
 
+export interface DelegateSubagentView {
+  profile: string | null;
+  task: string | null;
+}
+
+const BUILTIN_DELEGATE_LABELS: Record<string, string> = {
+  explore: '探索',
+  research: '调研',
+  coder: '编程',
+  'general-purpose': '通用',
+};
+
+const BUILTIN_DELEGATE_COLORS: Record<string, string> = {
+  explore: '#0ea5e9',
+  research: '#2563eb',
+  coder: '#16a34a',
+  'general-purpose': '#7c3aed',
+};
+
+export interface TurnParticipant {
+  key: string;
+  name: string;
+  color: string;
+}
+
+type AgentRef = { id: string; slug: string | null; name: string; color?: string | null };
+
+function participantFromProfile(
+  profile: string,
+  agents: ReadonlyArray<AgentRef>,
+): TurnParticipant {
+  const match = findAgentForProfile(profile, agents);
+  return {
+    key: match?.id ?? profile,
+    name: match?.name ?? BUILTIN_DELEGATE_LABELS[profile] ?? profile,
+    color: match?.color || BUILTIN_DELEGATE_COLORS[profile] || '#7c3aed',
+  };
+}
+
+/**
+ * 本回合顶栏要画的智能体。用户 `@提及` 了谁就画谁（含父代理若未点名则
+ * 仍放最前）；没有提及才回落到实际 `delegate_subagent` / 子代理生命周期，
+ * 避免内置画像「探索」顶替用户点名的智能助手、日程规划。
+ */
+export function collectTurnParticipants(
+  parent: { id: string; name: string; color?: string | null } | null,
+  input: {
+    agents?: ReadonlyArray<AgentRef>;
+    children?: ReadonlyArray<{ profile?: string }>;
+    actions?: ReadonlyArray<{ tool: string; arguments?: unknown }>;
+    mentionedAgentIds?: string[];
+  },
+): TurnParticipant[] {
+  const agents = input.agents ?? [];
+  const out: TurnParticipant[] = [];
+  const seen = new Set<string>();
+  const push = (item: TurnParticipant) => {
+    if (seen.has(item.key)) return;
+    seen.add(item.key);
+    out.push(item);
+  };
+  const pushAgent = (agent: AgentRef) => {
+    push({
+      key: agent.id,
+      name: agent.name,
+      color: agent.color || '#7c3aed',
+    });
+  };
+  const mentioned = (input.mentionedAgentIds ?? []).filter((id) => id.length > 0);
+  if (mentioned.length > 0) {
+    if (parent && !mentioned.includes(parent.id)) {
+      push({
+        key: parent.id,
+        name: parent.name,
+        color: parent.color || '#7c3aed',
+      });
+    }
+    for (const id of mentioned) {
+      const agent = agents.find((item) => item.id === id);
+      if (agent) pushAgent(agent);
+    }
+    return out;
+  }
+  if (parent) {
+    push({
+      key: parent.id,
+      name: parent.name,
+      color: parent.color || '#7c3aed',
+    });
+  }
+  for (const child of input.children ?? []) {
+    if (child.profile) push(participantFromProfile(child.profile, agents));
+  }
+  for (const action of input.actions ?? []) {
+    if (action.tool !== 'delegate_subagent') continue;
+    const { profile } = parseDelegateSubagent(action.arguments);
+    if (profile) push(participantFromProfile(profile, agents));
+  }
+  return out;
+}
+
+const MENTION_TOKEN = /(?<=^|\s)@([^\s@]+)/g;
+
+function mentionedIdsFromMetadata(raw: unknown): string[] {
+  if (typeof raw !== 'string' || !raw) return [];
+  try {
+    const meta = JSON.parse(raw) as { mentionedAgentIds?: unknown };
+    if (!Array.isArray(meta.mentionedAgentIds)) return [];
+    return meta.mentionedAgentIds.filter(
+      (item): item is string => typeof item === 'string' && item.length > 0,
+    );
+  } catch {
+    return [];
+  }
+}
+
+/** 上一轮用户消息里点名的智能体：优先 metadata，否则按正文 `@名` 扫描。 */
+export function extractMentionedAgentIds(
+  user: { content?: string; messageMetadata?: string | null } | null | undefined,
+  agents: ReadonlyArray<AgentRef>,
+): string[] {
+  if (!user) return [];
+  const fromMeta = mentionedIdsFromMetadata(user.messageMetadata);
+  if (fromMeta.length > 0) {
+    const known = new Set(agents.map((agent) => agent.id));
+    return fromMeta.filter((id) => known.has(id));
+  }
+  const content = user.content ?? '';
+  const seen = new Set<string>();
+  const ids: string[] = [];
+  for (const match of content.matchAll(MENTION_TOKEN)) {
+    const name = match[1];
+    const agent = agents.find((item) => item.name === name || item.slug === name);
+    if (!agent || seen.has(agent.id)) continue;
+    seen.add(agent.id);
+    ids.push(agent.id);
+  }
+  return ids;
+}
+
+/**
+ * `delegate_subagent` 的参数投影：画像名 + 自包含任务正文。
+ */
+export function parseDelegateSubagent(args: unknown): DelegateSubagentView {
+  if (!args || typeof args !== 'object') return { profile: null, task: null };
+  const obj = args as Record<string, unknown>;
+  const profile =
+    typeof obj.subagent_type === 'string' && obj.subagent_type.trim()
+      ? obj.subagent_type.trim()
+      : null;
+  const task =
+    typeof obj.task === 'string' && obj.task.trim() ? obj.task.trim() : null;
+  return { profile, task };
+}
+
+/**
+ * 把 `subagent_type` 映射成卡片上的显示名：先匹配会话智能体，再退回内置画像中文名，再退回画像原文。
+ */
+export function delegateSubagentDisplayName(
+  profile: string | null,
+  agents: ReadonlyArray<{ id: string; slug: string | null; name: string }>,
+): string {
+  if (!profile) return '子代理';
+  const match = findAgentForProfile(profile, agents);
+  if (match) return match.name;
+  return BUILTIN_DELEGATE_LABELS[profile] ?? profile;
+}
+
+/** 任务正文作行摘要；没有任务时返回 null，调用方不再回落 JSON。 */
+export function summarizeDelegateSubagent(args: unknown): string | null {
+  const { task } = parseDelegateSubagent(args);
+  if (!task) return null;
+  return clip(task);
+}
+
+function clip(text: string, max = 60): string {
+  return text.length > max ? `${text.slice(0, max - 3)}…` : text;
+}
+
+function asObject(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function stringField(obj: Record<string, unknown> | null, key: string): string | null {
+  if (!obj) return null;
+  const value = obj[key];
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+const ENVELOPE_KEYS = new Set([
+  'success',
+  'error',
+  'message',
+  'data',
+  'needsFollowup',
+  'terminal',
+  'nextAction',
+]);
+
+/** Sidecar `ToolResult` plus JSON 字符串；`fields` 是 data 与顶层业务字段的合并。 */
+export interface ToolEnvelope {
+  success: boolean | null;
+  error: string | null;
+  message: string | null;
+  fields: Record<string, unknown>;
+}
+
+function parseJsonValue(value: unknown): unknown {
+  if (typeof value !== 'string') return value;
+  const trimmed = value.trim();
+  if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) return value;
+  try {
+    return JSON.parse(trimmed) as unknown;
+  } catch {
+    return value;
+  }
+}
+
+export function parseToolEnvelope(result: unknown): ToolEnvelope {
+  const parsed = parseJsonValue(result);
+  const obj = asObject(parsed);
+  if (!obj) {
+    return {
+      success: null,
+      error: null,
+      message: typeof parsed === 'string' && parsed.trim() ? parsed.trim() : null,
+      fields: {},
+    };
+  }
+  const data = asObject(obj.data);
+  const fields: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (!ENVELOPE_KEYS.has(key) && value !== undefined) fields[key] = value;
+  }
+  if (data) {
+    for (const [key, value] of Object.entries(data)) {
+      if (key === 'durationMs' || value === undefined) continue;
+      fields[key] = value;
+    }
+  }
+  const dataText = typeof obj.data === 'string' && obj.data.trim() ? obj.data.trim() : null;
+  return {
+    success: typeof obj.success === 'boolean' ? obj.success : null,
+    error: stringField(obj, 'error'),
+    message: stringField(obj, 'message') ?? dataText,
+    fields,
+  };
+}
+
+const DELEGATE_STATUS_ZH: Record<string, string> = {
+  budget_exhausted: '额度耗尽',
+  failed: '失败',
+  cancelled: '已取消',
+};
+
+/** 把 sidecar 的英文失败句收成行头/错误栏可读的中文。 */
+export function humanizeDelegateError(error: string | null): string | null {
+  if (!error) return null;
+  if (error.includes('orchestration_budget_exceeded')) return '编排额度已用尽';
+  const ended = error.match(/sub-agent ended with status:\s*(\S+)/i);
+  if (ended) {
+    const status = ended[1].replace(/[.,;]+$/, '');
+    return `子代理因${DELEGATE_STATUS_ZH[status] ?? status}结束`;
+  }
+  if (error.includes('budget_exhausted')) return '子代理因额度耗尽结束';
+  return error;
+}
+
+export interface TaskSnapshotView {
+  taskId: string | null;
+  status: string | null;
+  task: string | null;
+  answer: string | null;
+  error: string | null;
+  worktreeLabel: string | null;
+  hint: string | null;
+}
+
+function worktreeLabel(obj: Record<string, unknown>): string | null {
+  const path = stringField(obj, 'worktreePath');
+  if (path) return path;
+  const wt = asObject(obj.worktree);
+  if (!wt) return null;
+  const wtPath = stringField(wt, 'path');
+  const branch = stringField(wt, 'branch');
+  if (wtPath && branch) return `${wtPath} · ${branch}`;
+  return wtPath ?? branch;
+}
+
+function snapshotFromRecord(obj: Record<string, unknown>): TaskSnapshotView {
+  return {
+    taskId: stringField(obj, 'taskId'),
+    status: stringField(obj, 'status'),
+    task: stringField(obj, 'task'),
+    answer: stringField(obj, 'answer') ?? stringField(obj, 'answerPreview'),
+    error: stringField(obj, 'error'),
+    worktreeLabel: worktreeLabel(obj),
+    hint: stringField(obj, 'hint'),
+  };
+}
+
+function snapshotUseful(view: TaskSnapshotView): boolean {
+  return Boolean(
+    view.taskId || view.status || view.task || view.answer || view.worktreeLabel || view.hint,
+  );
+}
+
+/** `task_*` 工具结果：兼容扁平返回和 CoreLoop `{success, data:{task}}`。 */
+export function parseTaskToolOutput(result: unknown): {
+  items: TaskSnapshotView[];
+  hint: string | null;
+  error: string | null;
+} {
+  const env = parseToolEnvelope(result);
+  const nested = asObject(env.fields.task);
+  const items: TaskSnapshotView[] = [];
+  if (Array.isArray(env.fields.tasks)) {
+    for (const row of env.fields.tasks) {
+      const obj = asObject(row);
+      if (!obj) continue;
+      const view = snapshotFromRecord(obj);
+      if (snapshotUseful(view)) items.push(view);
+    }
+  } else if (nested) {
+    const view = snapshotFromRecord(nested);
+    if (snapshotUseful(view)) items.push(view);
+  } else {
+    const view = snapshotFromRecord(env.fields);
+    if (snapshotUseful(view)) items.push(view);
+  }
+  return {
+    items,
+    hint: stringField(env.fields, 'hint'),
+    error: env.error,
+  };
+}
+
+/** 右侧过程栏的打开目标。终态卡用 `task` 当标题。 */
+export interface InspectTaskInput {
+  id: string;
+  chatId: string;
+  title?: string;
+  task?: string;
+  /** 子代理过程：按它自己的 durable record 读，而不是任务表。 */
+  recordId?: string;
+  /** 目标仍在运行——面板据此轮询并显示「正在推理」。 */
+  live?: boolean;
+}
+
+export function inspectTaskTitle(input: InspectTaskInput): string {
+  return input.title ?? input.task ?? '后台任务';
+}
+
+/** 工具行能打开右侧「后台推理」时抽出 taskId 和标题。 */
+export function inspectableTaskFromAction(
+  tool: string,
+  args: unknown,
+  result?: unknown,
+): { id: string; title: string } | null {
+  if (!isTaskFamilyTool(tool)) return null;
+  const parsed = parseTaskToolOutput(result);
+  const argId = stringField(asObject(args), 'taskId');
+  const id = parsed.items[0]?.taskId ?? argId;
+  if (!id) return null;
+  const title =
+    parseTaskRun(args).task
+    ?? parsed.items[0]?.task
+    ?? parsed.items[0]?.hint
+    ?? '后台任务';
+  return { id, title };
+}
+
+export interface TaskRunView {
+  task: string | null;
+  worktree: boolean;
+  worktreeName: string | null;
+  dependsOn: string[];
+}
+
+/** `task_run` 的参数投影。 */
+export function parseTaskRun(args: unknown): TaskRunView {
+  const obj = asObject(args);
+  const dependsOn = Array.isArray(obj?.dependsOn)
+    ? obj.dependsOn.filter((item): item is string => typeof item === 'string' && item.length > 0)
+    : [];
+  return {
+    task: stringField(obj, 'task'),
+    worktree: obj?.worktree === true,
+    worktreeName: stringField(obj, 'worktreeName'),
+    dependsOn,
+  };
+}
+
+export function shortTaskId(id: string): string {
+  return id.slice(0, 8);
+}
+
+export const TASK_FAMILY_TOOLS = [
+  'task_run',
+  'task_send',
+  'task_status',
+  'task_result',
+] as const;
+
+export type TaskFamilyTool = (typeof TASK_FAMILY_TOOLS)[number];
+
+export function isTaskFamilyTool(tool: string): tool is TaskFamilyTool {
+  return (TASK_FAMILY_TOOLS as readonly string[]).includes(tool);
+}
+
+/** 行头标题：不露出 `task_run` 这类工具原名。 */
+export function taskToolLabel(tool: string, args: unknown): string | null {
+  switch (tool) {
+    case 'task_run':
+      return parseTaskRun(args).worktree ? '后台任务 · 隔离' : '后台任务';
+    case 'task_send':
+      return '转达任务';
+    case 'task_status':
+      return '查询任务';
+    case 'task_result':
+      return '收取结果';
+    default:
+      return null;
+  }
+}
+
+function taskRunStatus(result: unknown): string | null {
+  const env = parseToolEnvelope(result);
+  const direct = stringField(env.fields, 'status');
+  if (direct) return direct;
+  const nested = asObject(env.fields.task);
+  return nested ? stringField(nested, 'status') : null;
+}
+
+/** `task_*` 家族的行摘要。 */
+export function summarizeTaskAction(
+  tool: string,
+  args: unknown,
+  result?: unknown,
+): string | null {
+  if (tool === 'task_run') {
+    const parsed = parseTaskRun(args);
+    if (!parsed.task) return null;
+    const head = clip(parsed.task);
+    if (taskRunStatus(result) === 'blocked') return `${head} · 等待依赖`;
+    if (parsed.worktree) return `${head} · 隔离工作区`;
+    return head;
+  }
+  if (tool === 'task_send') {
+    const message = stringField(asObject(args), 'message');
+    return message ? clip(message) : null;
+  }
+  if (tool === 'task_status') {
+    const id = stringField(asObject(args), 'taskId');
+    if (id) return shortTaskId(id);
+    const total = asObject(result)?.total;
+    return typeof total === 'number' ? `${total} 个任务` : '本会话';
+  }
+  if (tool === 'task_result') {
+    const id = stringField(asObject(args), 'taskId');
+    return id ? shortTaskId(id) : null;
+  }
+  return null;
+}
+
 /** Flatten a run_code action into the outer program plus inner tool rows. */
 export function expandRunCodeActions<T extends ExecutedActionLike>(actions: T[]): T[] {
   const out: T[] = [];

package/src/components/chat/next-steps-tags.ts

@@ -0,0 +1,28 @@
+/**
+ * 助手回复里的自定义 `[next_steps]...[/next_steps]` 标签：
+ * 给追问建议当判断来源，气泡里只显示标签内的正文，不显示标签本身。
+ */
+
+const COMPLETE_BLOCK_RE = /\[next_steps\]([\s\S]*?)\[\/next_steps\]/gi;
+const OPEN_TAG = 'next_steps]';
+const CLOSE_TAG = '/next_steps]';
+
+function isIncompleteTagSuffix(suffix: string): boolean {
+  const body = suffix.slice(1).toLowerCase();
+  if (!body) return false;
+  return OPEN_TAG.startsWith(body) || CLOSE_TAG.startsWith(body);
+}
+
+function stripIncompleteTrailingTag(text: string): string {
+  const idx = text.lastIndexOf('[');
+  if (idx < 0) return text;
+  const suffix = text.slice(idx);
+  return isIncompleteTagSuffix(suffix) ? text.slice(0, idx) : text;
+}
+
+/** 去掉自定义标签，保留里面的建议正文。 */
+export function stripNextStepsTags(text: string): string {
+  let out = (text ?? '').replace(COMPLETE_BLOCK_RE, '$1');
+  out = out.replace(/\[\/?next_steps\]/gi, '');
+  return stripIncompleteTrailingTag(out);
+}

package/src/components/chat/orchestration-children-model.ts

@@ -22,6 +22,80 @@ export interface ChildInfo {
   profile?: string;
   /** running | completed | failed | cancelled | interrupted */
   status: string;
+  /** 子代理自己的 durable record；右侧过程面板据此回看它的推理与工具。 */
+  recordId?: string;
+}
+
+/**
+ * 把一次 `delegate_subagent` 调用对上它的子代理。
+ *
+ * 工具行只有画像名与任务正文，子代理的 record 在生命周期事件里；`task` 就是
+ * 这次调用的 `task` 参数，所以两者精确相等。同一画像被派了多份活时按顺序
+ * 消费，`taken` 记下已配对的 childId。
+ *
+ * @param call 这次委派的画像名与任务正文。
+ * @param children 本回合累积的子代理列表。
+ * @param taken 已被前面的行配对掉的 childId。
+ * @returns 命中的子代理，或 undefined（历史回合没有事件、六件套子代理等）。
+ */
+export function matchChildForDelegation(
+  call: { profile: string | null; task: string | null },
+  children: ReadonlyArray<ChildInfo>,
+  taken: ReadonlySet<string> = new Set(),
+): ChildInfo | undefined {
+  return children.find((child) => {
+    if (taken.has(child.childId)) return false;
+    if (call.task && child.task && child.task.trim() !== call.task.trim()) return false;
+    if (!call.task && child.task) return false;
+    if (call.profile && child.profile && child.profile !== call.profile) return false;
+    return true;
+  });
+}
+
+/**
+ * 画像名的派生规则，与宿主 `local-backend/subagent-profiles.ts` 的
+ * `profileNameForAgent` 一致（两包不能互相 import：那边带 fs / sqlite）。
+ *
+ * 没有 slug 的自建智能体（中文名 slugify 后为空）会拿到
+ * `agent-<id 前 16 位字母数字>` 这种派生名——只按 slug/id 反查就映射不回来，
+ * 行头只能显示这串 id。所以这里把宿主的整条链都列成候选。
+ */
+function profileNameCandidates(agent: {
+  id: string;
+  slug: string | null;
+  name: string;
+}): string[] {
+  const candidates = [agent.id];
+  const slug = agent.slug?.trim() ?? '';
+  if (slug) candidates.push(slug);
+  if (/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/.test(slug)) return candidates;
+  const fromName = agent.name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+  const alnumId = agent.id.replace(/[^a-zA-Z0-9]/g, '');
+  const derived = fromName || (alnumId ? `agent-${alnumId.slice(0, 16)}` : 'agent');
+  candidates.push(derived);
+  // 同名画像在花名册里会加 id 后缀去重（`buildMentionDelegateRoster`）。
+  if (alnumId) candidates.push(`${derived}-${alnumId.slice(0, 8)}`);
+  return candidates;
+}
+
+/**
+ * 把画像名（slug / 派生名 / lineage id）映射回智能体记录，调用方据此取显示名
+ * 与颜色。没有匹配（编排六件套的子代理、已删除的智能体）时返回 undefined，
+ * 由调用方退回画像原文。
+ *
+ * @param profileOrId `child_spawned.profile`、`subagent_type`，或六件套的 lineage childId。
+ * @param agents 当前会话可见的智能体列表。
+ */
+export function findAgentForProfile<
+  T extends { id: string; slug: string | null; name: string },
+>(profileOrId: string, agents: ReadonlyArray<T>): T | undefined {
+  return agents.find((agent) =>
+    profileNameCandidates(agent).includes(profileOrId),
+  );
 }
 
 const STATUS_MAP: Record<string, OrchestrationTaskStatus> = {
@@ -58,6 +132,14 @@ export function childrenToCardModel(children: ChildInfo[]): {
   };
 }
 
+/**
+ * 子代理看板只在「不止一个孩子」时有用。单次 `delegate_subagent` 已经
+ * 出现在工具行「委派 ·」，再画「编排计划 · 1 个子任务」是同一件事。
+ */
+export function shouldShowOrchestrationBoard(children: ChildInfo[]): boolean {
+  return children.length >= 2;
+}
+
 /**
  * Fold the accumulated raw sidecar `agent.child` lifecycle events (as
  * forwarded by the backend's `orchestration_child` SSE payload) back into a
@@ -81,6 +163,9 @@ export function foldOrchestrationChildEvents(
         childId,
         task: typeof ev.task === 'string' ? ev.task : undefined,
         depth: typeof ev.depth === 'number' ? ev.depth : undefined,
+        profile: typeof ev.profile === 'string' ? ev.profile : undefined,
+        // 子代理自己的 durable record：委派行靠它跳转右侧过程栏。
+        recordId: typeof ev.recordId === 'string' ? ev.recordId : undefined,
         status: 'running',
       });
       continue;
@@ -102,3 +187,38 @@ export function foldOrchestrationChildEvents(
   }
   return list;
 }
+
+/**
+ * 从助手消息 `messageMetadata.orchestrationChildEvents` 水合子代理卡片。
+ * 刷新后没有 live SSE，只能靠落库事件经 `foldOrchestrationChildEvents` 重建。
+ */
+export function extractPersistedOrchestrationChildren(
+  messages:
+    | ReadonlyArray<{
+        id: string;
+        role?: string;
+        messageMetadata?: string | null;
+      }>
+    | undefined,
+): Record<string, ChildInfo[]> {
+  const seeded: Record<string, ChildInfo[]> = {};
+  if (!messages || messages.length === 0) return seeded;
+  for (const message of messages) {
+    if (message.role !== 'assistant' || !message.messageMetadata) continue;
+    try {
+      const metadata = JSON.parse(message.messageMetadata) as {
+        orchestrationChildEvents?: unknown;
+      };
+      if (!Array.isArray(metadata.orchestrationChildEvents)) continue;
+      const events = metadata.orchestrationChildEvents.filter(
+        (item): item is Record<string, unknown> =>
+          Boolean(item) && typeof item === 'object' && !Array.isArray(item),
+      );
+      const list = foldOrchestrationChildEvents(events);
+      if (list.length > 0) seeded[message.id] = list;
+    } catch {
+      // Ignore malformed legacy metadata.
+    }
+  }
+  return seeded;
+}