dsh-plugin-t-expert 0.1.0

package/lib/squads.js

@@ -0,0 +1,231 @@
+/**
+ * T专家 小队数据层：读写 `teams.json`，并把改动编译成引擎配置。
+ *
+ * 职责边界：本文件只管**小队定义**（有哪些队、谁在里面、别名、启停），
+ * 编译交给既有的 `team-profiles.py`（它已内置成员名撞键预检、别名校验、人格注入）。
+ * 这样 UI 编辑器不需要复制一份校验逻辑，生成器仍是唯一权威。
+ */
+import { readFileSync, writeFileSync, statSync, existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+
+/** profile key 只允许小写 ASCII + 数字 + 连字符（引擎按它生成命令别名）。 */
+const KEY_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+function text(value) {
+  return typeof value === "string" ? value : "";
+}
+
+function fail(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  error.details = details;
+  return error;
+}
+
+/** members 允许两种写法：slug 字符串，或 {slug|name, role} 对象（兼容手写）。 */
+function memberSlug(member) {
+  if (typeof member === "string") return member.trim();
+  if (member !== null && typeof member === "object") {
+    for (const key of ["slug", "name", "role"]) {
+      if (typeof member[key] === "string" && member[key].trim() !== "") return member[key].trim();
+    }
+  }
+  return "";
+}
+
+export function createSquadService({ teamsFile, catalog, python = "python3" }) {
+  const dataDir = dirname(teamsFile);
+  const generator = join(dataDir, "team-profiles.py");
+  let lastBuild = { at: 0, ok: true, output: "" };
+
+  function readSpec() {
+    try {
+      const spec = JSON.parse(readFileSync(teamsFile, "utf8"));
+      return spec !== null && typeof spec === "object" ? spec : {};
+    } catch (error) {
+      throw fail("tTeam/squads-unreadable", `读不到小队定义 ${teamsFile}：${String(error)}`);
+    }
+  }
+
+  function revisionOf() {
+    try {
+      const stat = statSync(teamsFile);
+      const hash = createHash("sha256").update(readFileSync(teamsFile)).digest("hex").slice(0, 12);
+      return `${stat.mtimeMs.toString(36)}-${hash}`;
+    } catch {
+      return "missing";
+    }
+  }
+
+  /** 名册快照（成员选择器用）：slug / 中英文名 / 分区 / 是否已启用。 */
+  async function roster() {
+    let experts = [];
+    let enabled = new Set();
+    try {
+      // 名册服务的 snapshot() 是异步的（它要读 settings），必须 await。
+      const snapshot = await catalog?.snapshot?.();
+      experts = snapshot?.experts ?? [];
+      enabled = new Set(snapshot?.enabled ?? []);
+    } catch {
+      /* 名册不可用时只给小队本身 */
+    }
+    const bySlug = new Map(experts.map((expert) => [expert.slug, expert]));
+    return {
+      experts: experts.map((expert) => ({
+        slug: expert.slug,
+        name: expert.name,
+        nameZh: expert.nameZh ?? expert.name,
+        division: expert.division,
+        divisionZh: expert.divisionZh ?? expert.division,
+        enabled: enabled.has(expert.slug),
+        conflict: expert.conflict === true,
+      })),
+      bySlug,
+    };
+  }
+
+  function describeMembers(members, bySlug) {
+    return (Array.isArray(members) ? members : []).map((member) => {
+      const slug = memberSlug(member);
+      const expert = bySlug.get(slug);
+      return {
+        slug,
+        role: typeof member === "object" && member !== null && typeof member.role === "string" ? member.role : "",
+        name: expert?.name ?? slug,
+        nameZh: expert?.nameZh ?? expert?.name ?? slug,
+        division: expert?.division ?? "",
+        divisionZh: expert?.divisionZh ?? expert?.division ?? "",
+        known: expert !== undefined,
+      };
+    });
+  }
+
+  async function list() {
+    const spec = readSpec();
+    const { bySlug, experts } = await roster();
+    const rawProfiles = spec.profiles !== null && typeof spec.profiles === "object" ? spec.profiles : {};
+    const squads = Object.entries(rawProfiles).map(([key, profile]) => {
+      const source = profile !== null && typeof profile === "object" ? profile : {};
+      return {
+        key,
+        description: text(source.description),
+        aliases: Array.isArray(source.aliases) ? source.aliases.filter((alias) => typeof alias === "string") : [],
+        taskPlanning: source.taskPlanning === "seed" ? "seed" : "captain",
+        // 缺省视为启用（老定义没有这个字段）
+        enabled: source.enabled !== false,
+        members: describeMembers(source.members, bySlug),
+      };
+    });
+    return {
+      revision: revisionOf(),
+      teamsFile,
+      squads,
+      experts,
+      engine: spec.engine ?? {},
+      defaults: spec.defaults ?? {},
+      lastBuild,
+    };
+  }
+
+  /** 校验（生成器之外的第一道闸门，错误信息面向面板）。 */
+  function validate(squads) {
+    if (!Array.isArray(squads) || squads.length === 0) {
+      throw fail("tTeam/squads-invalid", "至少要保留一个小队。");
+    }
+    const seenKeys = new Set();
+    const seenAliases = new Map();
+    squads.forEach((squad, index) => {
+      const label = `第 ${index + 1} 个小队`;
+      const key = text(squad?.key).trim();
+      if (!KEY_RE.test(key)) {
+        throw fail("tTeam/squads-invalid", `${label} 的 key「${key}」不合法：只能用小写字母、数字和连字符（例如 t-team-writing）。`);
+      }
+      if (seenKeys.has(key)) throw fail("tTeam/squads-invalid", `小队 key 重复：${key}`);
+      seenKeys.add(key);
+      const members = Array.isArray(squad?.members) ? squad.members.map(memberSlug).filter((slug) => slug !== "") : [];
+      if (members.length === 0) throw fail("tTeam/squads-invalid", `「${key}」没有成员：至少要选一位专家。`);
+      for (const alias of Array.isArray(squad?.aliases) ? squad.aliases : []) {
+        const value = text(alias).trim();
+        if (value === "") continue;
+        const owner = seenAliases.get(value);
+        if (owner !== undefined && owner !== key) {
+          throw fail("tTeam/squads-invalid", `别名「${value}」被 ${owner} 和 ${key} 同时占用，会让 /t 无法判断用哪个小队。`);
+        }
+        seenAliases.set(value, key);
+      }
+    });
+  }
+
+  /** 把 UI 传来的小队列表写回 teams.json（保留 engine/defaults 等顶层字段）。 */
+  function serialize(spec, squads) {
+    const previous = spec.profiles !== null && typeof spec.profiles === "object" ? spec.profiles : {};
+    const profiles = {};
+    for (const squad of squads) {
+      const key = text(squad.key).trim();
+      const members = (Array.isArray(squad.members) ? squad.members : [])
+        .map(memberSlug)
+        .filter((slug) => slug !== "");
+      // 保留面板没建模的字段（personaMode / personaBudget 等），只覆盖面板负责的那几项。
+      const merged = {
+        ...(previous[key] !== null && typeof previous[key] === "object" ? previous[key] : {}),
+        description: text(squad.description),
+        aliases: (Array.isArray(squad.aliases) ? squad.aliases : [])
+          .map((alias) => text(alias).trim())
+          .filter((alias) => alias !== ""),
+        taskPlanning: squad.taskPlanning === "seed" ? "seed" : "captain",
+        members,
+      };
+      if (squad.enabled === false) merged.enabled = false;
+      else delete merged.enabled;
+      profiles[key] = merged;
+    }
+    return { ...spec, profiles };
+  }
+
+  /** 跑生成器：编译 t-team.config.json + teams.resolved.json（失败即回滚 teams.json）。 */
+  function build() {
+    if (!existsSync(generator)) {
+      lastBuild = { at: Date.now(), ok: false, output: `找不到生成器 ${generator}` };
+      return lastBuild;
+    }
+    try {
+      const output = execFileSync(python, [generator, "--teams", teamsFile], {
+        cwd: dataDir,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 60_000,
+      });
+      lastBuild = { at: Date.now(), ok: true, output: output.trim().split("\n").slice(-6).join("\n") };
+    } catch (error) {
+      const output = [error?.stdout, error?.stderr].map((part) => text(part).trim()).filter((part) => part !== "").join("\n");
+      lastBuild = { at: Date.now(), ok: false, output: output === "" ? String(error) : output };
+    }
+    return lastBuild;
+  }
+
+  async function save(squads, expectedRevision) {
+    validate(squads);
+    const current = revisionOf();
+    if (typeof expectedRevision === "string" && expectedRevision !== "" && expectedRevision !== current) {
+      throw fail("tTeam/squads-conflict", "小队定义已在别处改动，请刷新后重试。", {
+        expectedRevision,
+        actualRevision: current,
+      });
+    }
+    const previousText = readFileSync(teamsFile, "utf8");
+    const nextSpec = serialize(readSpec(), squads);
+    writeFileSync(teamsFile, `${JSON.stringify(nextSpec, null, 2)}\n`);
+    const built = build();
+    if (!built.ok) {
+      writeFileSync(teamsFile, previousText); // 回滚，别把坏定义留在盘上
+      throw fail("tTeam/squads-build-failed", `配置生成失败，已回滚 teams.json：\n${built.output}`, {
+        actualRevision: revisionOf(),
+      });
+    }
+    return await list();
+  }
+
+  return { list, save, validate, revision: revisionOf, generator, dataDir };
+}

package/lib/teams/capabilities.js

@@ -0,0 +1,106 @@
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { readTeamSync, readRetiredMemberIdsSync } from "./state.js";
+import { MEMBER_TOOL_NAMES, TEAM_TOOL_NAMES } from "./tool-names.js";
+export const TEAM_ACTIVATION_PROMPT = 'T Team （T专家 团队） provides multi-agent team collaboration. Apply these rules when the user requests it (including /t-team) or when continuing an existing team. Mentioning, quoting, discussing, or declining T Team alone is not a request to start work.';
+export const TEAM_MEMBER_PROMPT = 'You are an T Team member. Follow your assigned member persona and task contract. Use t_team_claim_task, t_team_update_task, t_team_send_message and t_team_status for your own work. Include the current attempt_id in updates; report completion or failure to the captain. Do not create, approve, edit or resume a team. If your durable membership is unavailable, report that to the parent instead of creating a replacement.';
+function stateRoot(agent, config) {
+    return join(agent.session.header.cwd ?? process.cwd(), config.stateDir);
+}
+/** Synchronous startup/HMR hydration must finish before the first assembly. */
+function currentTeam(agent, config) {
+    const root = stateRoot(agent, config);
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    let found;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name === 'archive')
+            continue;
+        const team = readTeamSync(root, entry.name);
+        if (team === undefined || (team.captainSessionId !== agent.id
+            && !team.members.some(member => member.id === agent.id)))
+            continue;
+        if (found !== undefined)
+            throw new Error('ambiguous T Team membership');
+        found = team;
+    }
+    return found;
+}
+/** Call once, after all business definitions have registered. Never per member. */
+export function installTeamCapabilities(ctx, config) {
+    const states = new WeakMap();
+    const active = new Set();
+    let mounted = true;
+    // Snapshot policy once: profiles, team state, and tool results must never
+    // rewrite this prefix or control whether core instructions are available.
+    const captainPrompt = `${TEAM_ACTIVATION_PROMPT}\n\n${config.captainPrompt()}`;
+    function attach(agent) {
+        const prior = states.get(agent);
+        if (prior !== undefined)
+            return prior;
+        if (!mounted)
+            throw new Error('T Team capability provider is disposed');
+        // Determine a member's role before its first request and retain it for the
+        // lifetime of this scope. Team creation/archive must never rewrite the
+        // captain's system/tools prefix, even after a long ordinary conversation.
+        let member = config.isPendingMember(agent);
+        try {
+            member ||= readRetiredMemberIdsSync(stateRoot(agent, config)).has(agent.id);
+            const team = currentTeam(agent, config);
+            member ||= team !== undefined && team.captainSessionId !== agent.id;
+        }
+        catch (error) {
+            // Unrelated damaged state must not disable ordinary conversation.
+            // Business tools still validate durable team state before acting.
+            ctx.logger.warn(`t-team: capability hydration failed: ${String(error)}`);
+        }
+        const state = { member, dispose: () => undefined };
+        let revoke;
+        let disposed = false;
+        let releaseLifetime;
+        state.dispose = () => {
+            if (disposed)
+                return;
+            disposed = true;
+            revoke?.();
+            releaseLifetime?.();
+            states.delete(agent);
+            active.delete(state);
+        };
+        states.set(agent, state);
+        active.add(state);
+        try {
+            if (member)
+                revoke = agent.ctx.tools.restrict({
+                    deny: TEAM_TOOL_NAMES.filter(name => !MEMBER_TOOL_NAMES.includes(name)),
+                });
+            releaseLifetime = agent.ctx.effect(() => state.dispose, 't-team: capability lifetime');
+            return state;
+        }
+        catch (error) {
+            state.dispose();
+            throw error;
+        }
+    }
+    ctx.systemPrompt.section({
+        name: 't-team:usage', order: config.order ?? 117,
+        text: ({ agent }) => {
+            return agent !== undefined && states.get(agent)?.member ? TEAM_MEMBER_PROMPT : captainPrompt;
+        },
+    });
+    ctx.on('agent/session-start', ({ agent }) => { attach(agent); });
+    ctx.effect(() => () => {
+        mounted = false;
+        for (const state of [...active])
+            state.dispose();
+    }, 't-team: capability scopes');
+    for (const agent of ctx.agents.list())
+        attach(agent);
+}

package/lib/teams/command.js

@@ -0,0 +1,143 @@
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { parseProfileInvocation, resolveProfileTaskPlanning } from "./profiles.js";
+export const T_TEAM_COMMAND = 't';
+const PROFILE_COMMAND_PREFIX = `${T_TEAM_COMMAND}-`;
+const GESTURE = /^\/t(?=$|[\t\n\r ])/u;
+/**
+ * Convert a configured profile key into a stable, closed-namespace command
+ * suffix. Only lowercase ASCII letters, digits and dashes are representable;
+ * this deliberately prevents accidental command aliases for ambiguous profile
+ * names such as `foo bar`, `foo_bar`, or non-ASCII keys.
+ */
+export function profileCommandName(profileName) {
+    const normalized = profileName.trim().toLowerCase();
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(normalized))
+        return undefined;
+    return `${PROFILE_COMMAND_PREFIX}${normalized}`;
+}
+/** Resolve a profile command only when it maps uniquely to a live profile. */
+function profileForCommand(commandName, profiles) {
+    const matches = Object.keys(profiles).filter((profileName) => profileCommandName(profileName) === commandName);
+    return matches.length === 1 ? matches[0] : undefined;
+}
+/** Parse either the generic command or one generated profile alias. */
+function parseCommandText(text, profiles) {
+    const trimmed = text.trimStart();
+    if (GESTURE.test(trimmed))
+        return parseProfileInvocation(trimmed.slice(T_TEAM_COMMAND.length + 1).trim());
+    if (!trimmed.startsWith(`/${PROFILE_COMMAND_PREFIX}`))
+        return undefined;
+    const tokenEnd = trimmed.search(/[\t\n\r ]/u);
+    const commandName = trimmed.slice(1, tokenEnd === -1 ? undefined : tokenEnd);
+    const profile = profileForCommand(commandName, profiles);
+    if (profile === undefined)
+        return undefined;
+    return { profile, goal: (tokenEnd === -1 ? '' : trimmed.slice(tokenEnd)).trim() };
+}
+export function invokedTTeamInvocation(messages, getProfiles = () => ({})) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message === undefined || message.source.kind !== 'user')
+            continue;
+        for (const block of message.content) {
+            if (block.type !== 'text')
+                continue;
+            const invocation = parseCommandText(block.text, getProfiles());
+            if (invocation !== undefined)
+                return invocation;
+        }
+    }
+    return undefined;
+}
+export function invokedTTeamGoal(messages) {
+    return invokedTTeamInvocation(messages)?.goal;
+}
+export function buildActivationDirective(goal, profile, taskPlanning = 'seed') {
+    const lines = [
+        'The user invoked a T Team slash command. Follow the T Team protocol already in your system instructions. Inspect existing team state with t_team_status when needed.',
+        'Respect the current team state. Continue an existing plan or team without recreating it. Only when no current team exists, call t_team_create with approval="required". Build the complete staged roster and DAG, then stop and ask the user to review the Web plan. Do not approve or start it in this same turn.',
+    ];
+    if (profile !== undefined) {
+        lines.push(`Use profile="${profile}" when creating a new team.`);
+        if (taskPlanning === 'captain') {
+            lines.push('This profile supplies the roster and guardrails. After create, do not recreate members.', 'Derive the smallest useful task graph from the goal while the team is staged; do not ask the user whether to split, merge, serialize, or parallelize.', 'Independent supplemental work must become separate ready tasks so idle members can run in parallel. Add dependencies only for genuine prerequisites and later synthesis.');
+        }
+        else {
+            lines.push('Do not recreate the same members or seed tasks manually.');
+        }
+    }
+    lines.push(goal === '' ? 'The goal was not given — ask the user what the team should accomplish.' : `Goal: ${goal}`);
+    return lines.join('\n');
+}
+export function registerTTeamCommand(ctx, getProfiles = () => ({})) {
+    ctx.effect(() => {
+        const dispose = [];
+        dispose.push(ctx.commands.register({
+            name: T_TEAM_COMMAND,
+            description: 'run a goal with a multi-agent team (you become the captain)',
+            input: { hint: '[--profile <name>] <goal>' },
+            handler(invocation) {
+                let parsed;
+                try {
+                    parsed = parseProfileInvocation(invocation.rawInput.trim());
+                }
+                catch (error) {
+                    return { kind: 'error', text: String(error) };
+                }
+                if (parsed.profile !== undefined && !Object.keys(getProfiles()).some(key => key.trim() === parsed.profile))
+                    return { kind: 'error', text: `未知的 T专家 小队「${parsed.profile}」` };
+                if (parsed.profile === undefined && parsed.goal === '')
+                    return { kind: 'error', text: `Usage: /${T_TEAM_COMMAND} [--profile <name>] <goal>` };
+                invocation.agent.followup(createUserMessage({ content: [{ type: 'text', text: `/${T_TEAM_COMMAND}${invocation.rawInput}` }], source: { kind: 'user' } }));
+                return { kind: 'success', text: `T专家 小队已激活${parsed.profile === undefined ? '' : `（${parsed.profile}）`} —— 队长会先组装团队。` };
+            },
+        }));
+        for (const profileName of Object.keys(getProfiles())) {
+            const commandName = profileCommandName(profileName);
+            if (commandName === undefined)
+                continue;
+            dispose.push(ctx.commands.register({
+                name: commandName,
+                description: `run a goal with the T Team ${profileName} profile`,
+                input: { hint: '<goal>' },
+                handler(invocation) {
+                    const profile = profileForCommand(commandName, getProfiles());
+                    if (profile === undefined)
+                        return { kind: 'error', text: `T Team profile command "/${commandName}" is unavailable` };
+                    invocation.agent.followup(createUserMessage({ content: [{ type: 'text', text: `/${commandName}${invocation.rawInput}` }], source: { kind: 'user' } }));
+                    return { kind: 'success', text: `T专家 小队已激活（${profile}）—— 队长会先组装团队。` };
+                },
+            }));
+        }
+        return () => {
+            for (const unregister of dispose.reverse())
+                unregister();
+        };
+    }, 't-team: slash commands');
+}
+export function installTTeamGestureBoundary(ctx, getProfiles = () => ({})) {
+    ctx.on('agent/pre-step', async ({ messages, signal }, next) => {
+        const decision = await next();
+        if (decision.kind === 'reject')
+            return decision;
+        let invocation;
+        try {
+            invocation = invokedTTeamInvocation(messages, getProfiles);
+        }
+        catch (error) {
+            return { kind: 'enter', messages: [...decision.messages, createUserMessage({ content: [{ type: 'text', text: `T专家 小队解析失败：${String(error)}` }], source: { kind: 't-team-command' } })] };
+        }
+        if (invocation === undefined)
+            return decision;
+        signal.throwIfAborted();
+        const profiles = getProfiles();
+        const matched = invocation.profile === undefined
+            ? undefined
+            : Object.entries(profiles).find(([key]) => key.trim() === invocation.profile);
+        const known = invocation.profile === undefined || matched !== undefined;
+        const text = !known
+            ? `T专家 小队「${invocation.profile}」不存在。可用小队：${Object.keys(profiles).join('、') || '（无）'}。不要创建团队。`
+            : buildActivationDirective(invocation.goal, invocation.profile, resolveProfileTaskPlanning(matched?.[1]));
+        return { kind: 'enter', messages: [...decision.messages, createUserMessage({ content: [{ type: 'text', text }], source: { kind: 't-team-command', ...invocation.goal === '' ? {} : { goal: invocation.goal }, ...invocation.profile === undefined ? {} : { profile: invocation.profile } } })] };
+    });
+}

package/lib/teams/event-types.js

@@ -0,0 +1,12 @@
+/**
+ * T Team session event types — pure types only, zero imports.
+ *
+ * This file intentionally imports nothing: both the host program (the
+ * emitter in `events.ts`) and the browser program (the Conversation Node
+ * definition) must be able to load these types and the `SessionEventMap`
+ * declaration merge without pulling in host-side `Context` augmentations
+ * (dsh-session's index declares `Context.sessions: SessionStore`, which
+ * collides with the browser runtime's `ISessions` under the same name).
+ * @module t-team/event-types
+ */
+export {};

package/lib/teams/events.js

@@ -0,0 +1,60 @@
+/**
+ * Durable T Team session events and their emitter.
+ *
+ * Every team-state mutation appends one event to the captain's Session, so
+ * the web client's Conversation Node mechanism can fold the tree view from
+ * the session log deterministically (same mechanism as `tool-workflow`'s
+ * `tool-workflow/*` record events). Events append to the captain's session
+ * even when a member agent performed the mutation, so the captain's
+ * conversation stream stays the single authoritative monitor surface.
+ *
+ * Types and the `SessionEventMap` merge live in `event-types.ts` (zero
+ * imports) so the browser program can load them without host augmentations.
+ * @module t-team/events
+ */
+import * as dshSession from '@deepseek-ai/dsh-session';
+/** Event types already reported as unsupported, to avoid repetitive logs. */
+const skippedEventTypes = new Set();
+/**
+ * Append one T Team event to a Session, containing failures (a broken
+ * durable record must never break team tool execution).
+ * @param ctx - the plugin context (for logging).
+ * @param session - the session to record into (the captain's, normally).
+ * @param type - the event type.
+ * @param data - the event payload.
+ */
+export function appendTeamEvent(ctx, session, type, data) {
+    // Out-of-repo events are not in the harness's generated vocabulary today.
+    // Mutating that ReadonlySet would make readability depend on which plugins
+    // happen to be loaded. Until Session.append exposes the official
+    // `ignorable: true` writer surface, omit these informational records unless
+    // the running harness already recognizes them. Disk state remains the
+    // authoritative source for the activity panel.
+    const known = dshSession.KNOWN_SESSION_EVENT_TYPES;
+    if (known?.has(type) !== true) {
+        if (!skippedEventTypes.has(type)) {
+            skippedEventTypes.add(type);
+            ctx.logger.debug(`t-team: session event "${type}" omitted because this harness does not recognize it`);
+        }
+        return;
+    }
+    try {
+        session.append(type, data);
+    }
+    catch (error) {
+        ctx.logger.warn(`t-team: session record failed after ${type}: ${String(error)}`);
+    }
+}
+/**
+ * Resolve the captain's live Session for event recording. The captain agent
+ * may be offline (its team outlives the session), in which case the caller's
+ * own session is used as the fallback record target.
+ * @param ctx - the plugin context (injects `agents`).
+ * @param captainSessionId - the captain's durable session id.
+ * @param fallback - the calling agent's session, used when the captain is not live.
+ * @returns the session to record into.
+ */
+export function captainSessionOf(ctx, captainSessionId, fallback) {
+    const captain = ctx.agents.get(captainSessionId);
+    return captain?.session ?? fallback;
+}