dsh-archify-projects 0.0.0-stage → 0.1.0

package/lib/host/runner.js

@@ -0,0 +1,913 @@
+/**
+ * Agent 编排：一次运行 = 一个 DSH 会话 + 一段结构化提示词 + 产物/概念回收。
+ *
+ * 走的是宿主已经有的东西，不新造轮子：
+ *   - 会话由 `ctx.sessionController.create({ cwd, agentPreset })` 起（复用 DSH 的
+ *     模型/日志/审批），preset 就是 `cordis.patch.yml` 里那个受限组合；
+ *   - 提示词经 `ctx.sessionController.prompt(...)` 进 agent 收件箱；
+ *   - 结束靠 `agent.whenIdle()`，产物靠「标记优先 + 目录兜底」回收。
+ *
+ * 两种会话：
+ *   - 出图：可写工作目录，跑 archify；
+ *   - 提问：只读（read / glob / grep / skill），上下文只有这张图 + 概念表 + 代码库。
+ */
+import { readFile, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { buildAskPrompt, buildRunPrompt, parseArtifactMarkers, } from '../shared/prompt.js';
+import { allDiagrams, DIAGRAM_KINDS, findDiagram, usageTotalOf, } from '../shared/types.js';
+import { projectDir, workspaceRoot } from './config.js';
+import { serviceOf, } from './context.js';
+import { allowedToolNames, readonlyToolNames, tightenAgent, tightenReadOnlyAgent, } from './policy.js';
+import { ensureProjectWorkspace } from './workspace.js';
+/** 生成可读的运行 id（不追求全局唯一，台账里可区分即可）。 */
+export function newRunId(now = new Date()) {
+    const stamp = now
+        .toISOString()
+        .replace(/[-:.TZ]/g, '')
+        .slice(0, 14);
+    const rand = Math.random().toString(36).slice(2, 6);
+    return `run_${stamp}_${rand}`;
+}
+/** 生成请求 id（prompt 的幂等标识）。 */
+function newRequestId() {
+    return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+/** 跑一次运行。 */
+export class Runner {
+    deps;
+    busy = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** 该项目是否已有任务在跑。 */
+    isBusy(projectId) {
+        return this.busy.has(projectId);
+    }
+    /** 等某个项目当前的运行结束（没有在跑就返回 undefined）。 */
+    whenSettled(projectId) {
+        return this.busy.get(projectId);
+    }
+    /**
+     * 起一次出图运行。
+     *
+     * `diagramIds` 里默认图用 `structure` / `domain`，自定义图用 `dgm_xxx`。
+     * 临时图不参与「更新图册」，只会在被显式创建/重画时进来。
+     */
+    async start(project, kind, diagramIds) {
+        if (this.isBusy(project.id)) {
+            throw new RunnerBusy(project.id);
+        }
+        const { store, config } = this.deps;
+        const diagrams = diagramIds
+            .map((id) => findDiagram(project, id))
+            .filter((d) => d !== undefined);
+        if (diagrams.length === 0)
+            throw new RunnerUnavailable('没有可运行的图');
+        const runId = newRunId();
+        const startedAt = new Date().toISOString();
+        const workspaceDir = await ensureProjectWorkspace(config, project.id);
+        const skillDir = await this.deps.skillDir();
+        const prompt = buildRunPrompt({
+            projectName: project.name,
+            repoPath: project.repoPath,
+            workspaceDir,
+            git: project.git,
+            diagrams: diagrams.map(toPromptDiagram),
+            concepts: project.concepts,
+            stamp: stampOf(new Date()),
+            archifySkillPath: skillDir,
+            previous: previousBranches(diagrams),
+        });
+        const sessionId = await this.openSession(workspaceDir, prompt, 'draw');
+        const record = {
+            id: runId,
+            kind,
+            status: 'running',
+            sessionId,
+            startedAt,
+            finishedAt: null,
+            error: null,
+            note: null,
+            diagramIds: diagrams.map((d) => d.id),
+            todos: [],
+            usage: null,
+        };
+        await store.patch(project.id, (current) => ({
+            ...current,
+            updatedAt: startedAt,
+            lastRun: record,
+            runs: pushRun(current.runs, record, config.keepRuns),
+            ...markStatuses(current, diagrams.map((d) => d.id), 'running'),
+        }));
+        const tracked = this.follow(project.id, runId, diagrams.map((d) => d.id)).finally(() => {
+            this.busy.delete(project.id);
+        });
+        this.busy.set(project.id, tracked);
+        return { runId, sessionId, kind };
+    }
+    /**
+     * 对一张图提问（只读会话）。
+     *
+     * 上下文只有三样：这张图的 prompt + 产物摘要、项目概念表、代码库根目录。
+     * 工具面是 read / glob / grep / skill(archify) —— 没有 shell、没有写工具。
+     */
+    async ask(project, diagramId, question) {
+        if (this.isBusy(project.id)) {
+            throw new RunnerBusy(project.id);
+        }
+        const { store, config } = this.deps;
+        const diagram = findDiagram(project, diagramId);
+        if (diagram === undefined)
+            throw new RunnerUnavailable('图不存在');
+        const workspaceDir = await ensureProjectWorkspace(config, project.id);
+        const candidate = await readCandidate(config, project, diagram);
+        const prompt = buildAskPrompt({
+            projectName: project.name,
+            repoPath: project.repoPath,
+            diagram: toPromptDiagram(diagram),
+            concepts: project.concepts,
+            candidate,
+            question,
+        });
+        const qaId = `qa_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+        const createdAt = new Date().toISOString();
+        const pending = {
+            id: qaId,
+            diagramId: diagram.id,
+            question,
+            answer: '',
+            at: createdAt,
+            applied: false,
+            status: 'running',
+            todos: [],
+            usage: null,
+        };
+        await store.patch(project.id, (current) => ({
+            ...current,
+            updatedAt: createdAt,
+            qa: [...current.qa, pending],
+        }));
+        const run = (async () => {
+            const { ctx } = this.deps;
+            const sessionId = await this.openSession(workspaceDir, prompt, 'ask');
+            const agent = agentOf(ctx, sessionId);
+            let stop = () => { };
+            let text = '';
+            let usage = null;
+            try {
+                if (agent !== undefined) {
+                    stop = this.watchQaTodos(project.id, qaId, agent);
+                    await withTimeout(agent.whenIdle(), config.askTimeoutMs);
+                    text = readFinalText(agent);
+                    usage = usageOf(ctx, agent);
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                const failed = await this.finishQa(project.id, qaId, {
+                    answer: `（提问失败：${message}）`,
+                    status: 'failed',
+                    usage,
+                });
+                return { sessionId, entry: failed };
+            }
+            finally {
+                stop();
+            }
+            const entry = await this.finishQa(project.id, qaId, {
+                answer: text.length > 0 ? text : '（这次提问没有拿到回答：会话结束时没有 assistant 文本）',
+                status: 'done',
+                usage,
+            });
+            return { sessionId, entry };
+        })();
+        const tracked = run
+            .then(() => undefined)
+            .catch(() => undefined)
+            .finally(() => {
+            this.busy.delete(project.id);
+        });
+        this.busy.set(project.id, tracked);
+        return run;
+    }
+    /**
+     * 建会话并投递提示词。
+     *
+     * 优先 `sessionController`（宿主的标准会话命令面）；没有这个服务时退回
+     * `agents.createSession` + `agent.followup`。两条路都用同一个 preset，
+     * 限制不会因为走哪条路而消失。
+     */
+    async openSession(workspaceDir, prompt, mode) {
+        const { ctx, config } = this.deps;
+        const allow = mode === 'ask' ? readonlyToolNames() : allowedToolNames();
+        const presetId = mode === 'ask' ? config.askPresetId : config.presetId;
+        const controller = serviceOf(ctx, 'sessionController');
+        if (controller !== undefined) {
+            const created = await controller.create({ cwd: workspaceDir, agentPreset: presetId });
+            // 会话刚建好、还没开 turn：这时候收口工具面最干净
+            this.tighten(created.sessionId, allow, mode);
+            if (typeof controller.prompt === 'function') {
+                await controller.prompt({
+                    requestId: newRequestId(),
+                    sessionId: created.sessionId,
+                    mode: 'queue',
+                    content: [{ type: 'text', text: prompt }],
+                }, new AbortController().signal);
+            }
+            return created.sessionId;
+        }
+        const agents = serviceOf(ctx, 'agents');
+        if (agents === undefined) {
+            throw new RunnerUnavailable('宿主没有 sessionController 也没有 agents 服务，无法起 agent 会话');
+        }
+        const created = await agents.createSession({
+            cwd: workspaceDir,
+            agentPreset: presetId,
+            reusable: () => false,
+        });
+        const agent = created.agent;
+        this.tighten(agent.id ?? null, allow, mode);
+        agent.followup({
+            id: newRequestId(),
+            content: [{ type: 'text', text: prompt }],
+            source: { kind: 'user' },
+        });
+        const sessionId = agent.id ?? null;
+        if (sessionId === null)
+            throw new RunnerUnavailable('用 agents.createSession 起的会话没有 id');
+        return sessionId;
+    }
+    /** 对该会话的 agent 作用域装工具白名单与守卫。 */
+    tighten(sessionId, allow, mode) {
+        const { ctx } = this.deps;
+        const warn = (message) => {
+            try {
+                ctx.logger.warn(`[dsh-archify-projects] ${message}`);
+            }
+            catch {
+                // 日志器不可用不影响运行
+            }
+        };
+        if (sessionId === null) {
+            warn('会话没有 id：跳过工具收口');
+            return;
+        }
+        const agent = agentOf(ctx, sessionId);
+        if (agent?.ctx === undefined) {
+            warn('拿不到 agent 作用域：工具白名单未生效（守卫同样未生效）');
+            return;
+        }
+        if (mode === 'ask') {
+            tightenReadOnlyAgent(agent.ctx, warn);
+            return;
+        }
+        tightenAgent(agent.ctx, allow, warn);
+    }
+    /** 问答会话期间盯 todo，写到 qa 条目上，页面才能看到进度。 */
+    watchQaTodos(projectId, qaId, agent) {
+        const { ctx, store } = this.deps;
+        let stopped = false;
+        let last = '';
+        const tick = async () => {
+            if (stopped)
+                return;
+            const todos = todosOf(ctx, agent);
+            if (todos === null)
+                return;
+            const signature = todos.map((todo) => `${todo.status}:${todo.content}`).join('|');
+            if (signature === last)
+                return;
+            last = signature;
+            await store
+                .patch(projectId, (current) => ({
+                ...current,
+                qa: current.qa.map((entry) => (entry.id === qaId ? { ...entry, todos } : entry)),
+            }))
+                .catch(() => undefined);
+        };
+        void tick();
+        const timer = setInterval(() => void tick(), 3000);
+        return () => {
+            stopped = true;
+            clearInterval(timer);
+        };
+    }
+    /** 收尾一条提问：写回答、状态与用量，并把用量并进项目累计。 */
+    async finishQa(projectId, qaId, outcome) {
+        const { store } = this.deps;
+        const now = new Date().toISOString();
+        let saved;
+        await store.patch(projectId, (current) => ({
+            ...current,
+            updatedAt: now,
+            usageTotal: current.usageTotal + usageTotalOf(outcome.usage),
+            qa: current.qa.map((entry) => {
+                if (entry.id !== qaId)
+                    return entry;
+                saved = {
+                    ...entry,
+                    at: now,
+                    answer: outcome.answer,
+                    status: outcome.status,
+                    usage: outcome.usage,
+                };
+                return saved;
+            }),
+        }));
+        return (saved ?? {
+            id: qaId,
+            diagramId: '',
+            question: '',
+            answer: outcome.answer,
+            at: now,
+            applied: false,
+            status: outcome.status,
+            todos: [],
+            usage: outcome.usage,
+        });
+    }
+    /**
+     * 运行期间盯 todo：每 3 秒读一次 `todos` projection 写进台账。
+     *
+     * 页面靠这份快照显示「正在：<当前步骤>」；读不到（宿主没挂 projection 或 agent
+     * 还没写 todo）就什么都不做，不制造假进度。
+     */
+    watchTodos(projectId, runId, agent) {
+        const { ctx, store } = this.deps;
+        let stopped = false;
+        let last = '';
+        const tick = async () => {
+            if (stopped)
+                return;
+            const todos = todosOf(ctx, agent);
+            if (todos === null)
+                return;
+            const signature = todos.map((todo) => `${todo.status}:${todo.content}`).join('|');
+            if (signature === last)
+                return;
+            last = signature;
+            await store
+                .patch(projectId, (current) => patchRunTodos(current, runId, todos))
+                .catch(() => undefined);
+        };
+        void tick();
+        const timer = setInterval(() => void tick(), 3000);
+        return () => {
+            stopped = true;
+            clearInterval(timer);
+        };
+    }
+    /** 后台等待结束并回收产物/概念。 */
+    follow(projectId, runId, diagramIds) {
+        const run = async () => {
+            const { ctx, store, config } = this.deps;
+            const project = await store.get(projectId);
+            if (project === undefined)
+                return;
+            const sessionId = project.lastRun?.sessionId ?? null;
+            if (sessionId === null) {
+                await this.fail(projectId, runId, '会话没有 id，无法跟踪运行');
+                return;
+            }
+            const agent = agentOf(ctx, sessionId);
+            const stop = agent === undefined ? () => { } : this.watchTodos(projectId, runId, agent);
+            try {
+                if (agent === undefined)
+                    throw new RunnerUnavailable('会话已不在运行中，无法等待结果');
+                await withTimeout(agent.whenIdle(), config.runTimeoutMs);
+                const text = readFinalText(agent);
+                const markers = parseArtifactMarkers(text);
+                const found = await this.collectArtifacts(projectId, markers, diagramIds);
+                const concepts = await readConcepts(config, projectId);
+                await this.succeed(projectId, runId, found, diagramIds, concepts, usageOf(ctx, agent));
+            }
+            catch (err) {
+                await this.fail(projectId, runId, err instanceof Error ? err.message : String(err), usageOf(ctx, agent));
+            }
+            finally {
+                stop();
+            }
+        };
+        return run();
+    }
+    /** 回收产物：标记优先，找不到就扫 `.archify/` 最新目录。 */
+    async collectArtifacts(projectId, markers, diagramIds) {
+        const found = new Map();
+        for (const id of diagramIds) {
+            const marked = markers.get(id.toLowerCase()) ?? markers.get(legacyMarkerId(id).toLowerCase());
+            if (marked !== undefined && (await isFile(marked))) {
+                found.set(id, path.resolve(marked));
+            }
+        }
+        if (found.size === diagramIds.length)
+            return found;
+        const fallback = await discoverArtifacts(this.deps.config, projectId, diagramIds);
+        for (const id of diagramIds) {
+            if (found.has(id))
+                continue;
+            const candidate = fallback.get(id);
+            if (candidate !== undefined)
+                found.set(id, candidate);
+        }
+        return found;
+    }
+    async succeed(projectId, runId, found, diagramIds, concepts, usage) {
+        const { store, config } = this.deps;
+        const now = new Date().toISOString();
+        const root = workspaceRoot(config);
+        await store.patch(projectId, (current) => {
+            let next = { ...current, concepts: mergeConcepts(current.concepts, concepts) };
+            for (const id of diagramIds) {
+                const diagram = findDiagram(next, id);
+                if (diagram === undefined)
+                    continue;
+                const html = found.get(id);
+                const updated = html === undefined
+                    ? failedDiagram(diagram, '没有找到这次运行的产物文件')
+                    : readyDiagram(diagram, html, root, next, now);
+                next = { ...next, ...replaceDiagram(next, diagram, updated) };
+            }
+            const lastRun = withUsage(finishRun(next, runId, now, found.size === diagramIds.length
+                ? { status: 'succeeded', error: null }
+                : { status: 'failed', error: '部分图谱没有产出' }), usage);
+            return {
+                ...next,
+                updatedAt: now,
+                usageTotal: next.usageTotal + usageTotalOf(usage),
+                lastRun,
+                runs: pushRun(next.runs, lastRun, config.keepRuns),
+            };
+        });
+    }
+    async fail(projectId, runId, message, usage = null) {
+        const { store, config } = this.deps;
+        const now = new Date().toISOString();
+        // 失败路径也要先看盘：agent 常常已经把自检通过的 HTML 落进 `.archify/`，
+        // 报错只是「等不到最终回复」（会话被宿主机重启掐断、超时、连接断）。
+        const salvaged = await discoverArtifacts(config, projectId, (await store.get(projectId))?.custom.map((d) => d.id) ?? []).catch(() => new Map());
+        const concepts = await readConcepts(config, projectId).catch(() => []);
+        const root = workspaceRoot(config);
+        await store.patch(projectId, (current) => {
+            let next = { ...current, concepts: mergeConcepts(current.concepts, concepts) };
+            for (const diagram of allDiagrams(current)) {
+                if (diagram.status !== 'running' && diagram.status !== 'queued')
+                    continue;
+                const html = salvaged.get(diagram.id) ?? salvaged.get(legacyMarkerId(diagram.id));
+                next = {
+                    ...next,
+                    ...replaceDiagram(next, diagram, html === undefined
+                        ? failedDiagram(diagram, message)
+                        : readyDiagram(diagram, html, root, next, now)),
+                };
+            }
+            const lastRun = withUsage(finishRun(next, runId, now, { status: 'failed', error: message }), usage);
+            return {
+                ...next,
+                updatedAt: now,
+                usageTotal: next.usageTotal + usageTotalOf(usage),
+                lastRun,
+                runs: pushRun(next.runs, lastRun, config.keepRuns),
+            };
+        });
+    }
+}
+/** 正在跑时又点了一次。 */
+export class RunnerBusy extends Error {
+    projectId;
+    constructor(projectId) {
+        super('这个项目已有任务在运行，等它结束再试');
+        this.name = 'RunnerBusy';
+        this.projectId = projectId;
+    }
+}
+/** 宿主缺少必要的 agent 服务。 */
+export class RunnerUnavailable extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RunnerUnavailable';
+    }
+}
+/** 把一条运行写进历史（同 id 覆盖，否则追加），并裁剪到上限。 */
+export function pushRun(runs, record, keep) {
+    const withoutSame = runs.filter((run) => run.id !== record.id);
+    const next = [...withoutSame, record];
+    return next.length <= keep ? next : next.slice(next.length - keep);
+}
+/** 结束一条运行：补齐 status / finishedAt / error，其余字段沿用启动时的记录。 */
+function finishRun(project, runId, now, outcome) {
+    const base = project.runs.find((run) => run.id === runId) ??
+        project.lastRun ?? {
+        id: runId,
+        kind: 'create',
+        sessionId: null,
+        startedAt: now,
+        finishedAt: null,
+        error: null,
+        note: null,
+        diagramIds: [],
+        todos: [],
+        usage: null,
+    };
+    return { ...base, status: outcome.status, finishedAt: now, error: outcome.error };
+}
+function stampOf(date) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return (`${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}` +
+        `-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`);
+}
+function toPromptDiagram(diagram) {
+    return {
+        id: diagram.id,
+        kind: diagram.kind,
+        title: diagram.title,
+        prompt: diagram.prompt,
+        persistence: diagram.persistence,
+        conceptIds: diagram.conceptIds,
+        renderer: diagram.renderer,
+        pathScope: diagram.pathScope,
+    };
+}
+function previousBranches(diagrams) {
+    const out = {};
+    for (const diagram of diagrams)
+        out[diagram.id] = diagram.branch;
+    return out;
+}
+/** 旧版本标记（structure/domain）与默认图 id 是同一个，这里只是留个可读入口。 */
+function legacyMarkerId(id) {
+    return id;
+}
+function agentOf(ctx, sessionId) {
+    if (sessionId === null)
+        return undefined;
+    return serviceOf(ctx, 'agents')?.get(sessionId);
+}
+/** 把图替换回项目，同时保持 record/数组两条路径。 */
+function replaceDiagram(project, current, next) {
+    if (DIAGRAM_KINDS.includes(current.kind)) {
+        return { diagrams: { ...project.diagrams, [current.kind]: next } };
+    }
+    return { custom: project.custom.map((d) => (d.id === current.id ? next : d)) };
+}
+function markStatuses(project, ids, status) {
+    let next = project;
+    for (const id of ids) {
+        const diagram = findDiagram(next, id);
+        if (diagram === undefined)
+            continue;
+        next = { ...next, ...replaceDiagram(next, diagram, { ...diagram, status, error: null }) };
+    }
+    return { diagrams: next.diagrams, custom: next.custom };
+}
+/** 产物就绪：保留图的元信息，只换产物字段。 */
+export function readyDiagram(diagram, htmlPath, root, project, now) {
+    const specPath = path.join(path.dirname(htmlPath), 'candidate.json');
+    return {
+        ...diagram,
+        status: 'ready',
+        htmlPath: relativeTo(root, htmlPath),
+        specPath: relativeTo(root, specPath),
+        generatedAt: now,
+        branch: project.git.branch,
+        tree: project.git.tree,
+        error: null,
+    };
+}
+function failedDiagram(diagram, message) {
+    return {
+        ...diagram,
+        status: 'failed',
+        htmlPath: null,
+        specPath: null,
+        generatedAt: null,
+        branch: null,
+        tree: null,
+        error: message,
+    };
+}
+/** 相对路径统一用 posix 分隔符，URL 拼接才稳。 */
+function relativeTo(root, target) {
+    return path.relative(root, target).split(path.sep).join('/');
+}
+async function isFile(target) {
+    try {
+        return (await stat(target)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** 从 agent 会话里取最后一条 assistant 文本。 */
+function readFinalText(agent) {
+    const session = agent.session;
+    if (session === undefined || typeof session.deriveMessages !== 'function')
+        return '';
+    let messages;
+    try {
+        messages = session.deriveMessages();
+    }
+    catch {
+        return '';
+    }
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const message = messages[i];
+        if (message?.role !== 'assistant' || !Array.isArray(message.content))
+            continue;
+        const text = message.content
+            .map((block) => {
+            const b = block;
+            return b.type === 'text' && typeof b.text === 'string' ? b.text : '';
+        })
+            .join('\n')
+            .trim();
+        if (text.length > 0)
+            return text;
+    }
+    return '';
+}
+/** 读 agent 写下的概念表（工作目录根的 concepts.json）。 */
+export async function readConcepts(config, projectId) {
+    const file = path.join(projectDir(config, projectId), 'concepts.json');
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    const list = Array.isArray(parsed) ? parsed : (parsed.concepts ?? []);
+    if (!Array.isArray(list))
+        return [];
+    const now = new Date().toISOString();
+    const out = [];
+    for (const item of list) {
+        if (typeof item !== 'object' || item === null)
+            continue;
+        const raw = item;
+        const id = typeof raw.id === 'string' ? raw.id : null;
+        const name = typeof raw.name === 'string' ? raw.name : null;
+        if (id === null || name === null)
+            continue;
+        out.push({
+            id,
+            name,
+            summary: typeof raw.summary === 'string' ? raw.summary : '',
+            evidence: Array.isArray(raw.evidence)
+                ? raw.evidence.filter((v) => typeof v === 'string')
+                : [],
+            tags: Array.isArray(raw.tags)
+                ? raw.tags.filter((v) => typeof v === 'string')
+                : [],
+            updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt : now,
+        });
+    }
+    return out;
+}
+/** 合并概念：同 id 覆盖，其余保留；按出现顺序去重。 */
+export function mergeConcepts(existing, incoming) {
+    if (incoming.length === 0)
+        return existing;
+    const byId = new Map();
+    for (const concept of existing)
+        byId.set(concept.id, concept);
+    for (const concept of incoming)
+        byId.set(concept.id, concept);
+    return [...byId.values()];
+}
+/** 读一次 todos projection；没有服务或没写过 todo 时返回 null。 */
+export function todosOf(ctx, agent) {
+    const session = agent.session;
+    if (session === undefined || session === null)
+        return null;
+    const projections = serviceOf(ctx, 'sessionProjections');
+    if (projections === undefined)
+        return null;
+    let values;
+    try {
+        values = projections.snapshot(session, ['todos']).values;
+    }
+    catch {
+        return null;
+    }
+    const raw = values?.todos;
+    if (!Array.isArray(raw))
+        return null;
+    const out = [];
+    for (const item of raw) {
+        if (typeof item !== 'object' || item === null)
+            continue;
+        const value = item;
+        if (typeof value.content !== 'string' || value.content.length === 0)
+            continue;
+        const status = value.status === 'in_progress' || value.status === 'completed' ? value.status : 'pending';
+        out.push({ content: value.content, status });
+    }
+    return out;
+}
+/** 读一次 tokenUsage projection；没有就返回 null。 */
+export function usageOf(ctx, agent) {
+    if (agent === undefined)
+        return null;
+    const session = agent.session;
+    if (session === undefined || session === null)
+        return null;
+    const projections = serviceOf(ctx, 'sessionProjections');
+    if (projections === undefined)
+        return null;
+    let values;
+    try {
+        values = projections.snapshot(session, ['tokenUsage']).values;
+    }
+    catch {
+        return null;
+    }
+    const raw = values?.tokenUsage;
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const source = raw;
+    const num = (key) => {
+        const n = Number(source[key]);
+        return Number.isFinite(n) && n > 0 ? n : 0;
+    };
+    const usage = {
+        uncachedInput: num('uncachedInputTokens'),
+        output: num('outputTokens'),
+        cacheRead: num('cacheReadTokens'),
+        cacheWrite: num('cacheWriteTokens'),
+    };
+    // 全 0 = 这次调用没真正发生（比如首轮就报错），别记成一条「用量 0」
+    return usageTotalOf(usage) === 0 ? null : usage;
+}
+/** 把 todo 写进某条运行记录（lastRun 与 runs[] 同步改）。 */
+export function patchRunTodos(project, runId, todos) {
+    const stamp = (run) => (run.id === runId ? { ...run, todos } : run);
+    return {
+        ...project,
+        lastRun: project.lastRun === null ? null : stamp(project.lastRun),
+        runs: project.runs.map(stamp),
+    };
+}
+/** 给运行记录补上用量。 */
+function withUsage(run, usage) {
+    return { ...run, usage };
+}
+/** 读这张图的 candidate.json（截断），给问答会话当上下文。 */
+async function readCandidate(config, project, diagram) {
+    void project;
+    if (diagram.specPath === null)
+        return null;
+    const file = path.join(workspaceRoot(config), diagram.specPath);
+    try {
+        const text = await readFile(file, 'utf8');
+        return text.length > 6000 ? `${text.slice(0, 6000)}\n…（已截断）` : text;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 开库对账。宿主每次启动跑一次，做两件事：
+ *
+ * 1. **认领磁盘上的产物**：记录说不 ready、`.archify/` 下却已经有自检通过的 html
+ *    （agent 跑到一半宿主被重启 / 页面被关的典型现场），把它认回来当 ready。
+ * 2. **收尸悬挂的运行**：上一次运行的 `running` 会原样留在台账里（进程被 kill 时
+ *    没有机会写 finishedAt）。不收拾就会永远「生成中」，按钮全禁用，用户只能手改 JSON。
+ */
+export async function reconcileArtifacts(store, config) {
+    const adopted = [];
+    const root = workspaceRoot(config);
+    let projects = [];
+    try {
+        projects = await store.list();
+    }
+    catch {
+        return adopted;
+    }
+    for (const project of projects) {
+        const diagrams = allDiagrams(project);
+        const strayRuns = project.runs.filter((run) => run.status === 'running');
+        const missing = diagrams.filter((diagram) => diagram.status !== 'ready');
+        if (missing.length === 0 && strayRuns.length === 0)
+            continue;
+        const found = await discoverArtifacts(config, project.id, diagrams.map((d) => d.id)).catch(() => new Map());
+        const strayDiagrams = diagrams.filter((diagram) => diagram.status === 'queued' || diagram.status === 'running');
+        if (found.size === 0 && strayRuns.length === 0 && strayDiagrams.length === 0)
+            continue;
+        const now = new Date().toISOString();
+        await store.patch(project.id, (current) => {
+            let next = current;
+            for (const diagram of allDiagrams(current)) {
+                const html = found.get(diagram.id);
+                if (html !== undefined) {
+                    next = {
+                        ...next,
+                        ...replaceDiagram(next, diagram, readyDiagram(diagram, html, root, next, now)),
+                    };
+                    continue;
+                }
+                if (diagram.status !== 'queued' && diagram.status !== 'running')
+                    continue;
+                next = {
+                    ...next,
+                    ...replaceDiagram(next, diagram, failedDiagram(diagram, '上一次运行随宿主退出而中断，点「重新生成」重跑')),
+                };
+            }
+            const runs = current.runs.map((run) => run.status === 'running'
+                ? { ...run, status: 'failed', finishedAt: now, error: '宿主重启，本次运行中断' }
+                : run);
+            const lastRun = current.lastRun !== null && current.lastRun.status === 'running'
+                ? {
+                    ...current.lastRun,
+                    status: 'failed',
+                    finishedAt: now,
+                    error: '宿主重启，本次运行中断',
+                }
+                : current.lastRun;
+            return { ...next, updatedAt: now, runs, lastRun };
+        });
+        if (found.size > 0)
+            adopted.push(`${project.name}: 认领 ${found.size} 张图`);
+        if (strayRuns.length > 0)
+            adopted.push(`${project.name}: 收尸 ${strayRuns.length} 条悬挂运行`);
+    }
+    return adopted;
+}
+/**
+ * 目录兜底：扫 `<项目目录>/.archify/` 下的子目录，按目录名里的图 id / 旧 kind 关键词归类。
+ *
+ * 只在标记缺失时用。目录名必须以图 id 开头（prompt 里约定的），否则按旧版
+ * `structure-` / `domain-` 前缀兜底。
+ */
+export async function discoverArtifacts(config, projectId, diagramIds) {
+    const result = new Map();
+    const archifyRoot = path.join(projectDir(config, projectId), '.archify');
+    let dirs;
+    try {
+        dirs = await readdir(archifyRoot, { withFileTypes: true }).then((entries) => entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort()
+            .reverse());
+    }
+    catch {
+        return result;
+    }
+    for (const dir of dirs) {
+        const id = diagramIdOfDirName(dir, diagramIds);
+        if (id === null || result.has(id))
+            continue;
+        const html = await firstHtmlIn(path.join(archifyRoot, dir));
+        if (html !== null)
+            result.set(id, html);
+    }
+    return result;
+}
+function diagramIdOfDirName(dir, diagramIds) {
+    const lower = dir.toLowerCase();
+    for (const id of diagramIds) {
+        if (lower.startsWith(`${id.toLowerCase()}-`))
+            return id;
+    }
+    if (lower.startsWith('domain'))
+        return 'domain';
+    if (lower.startsWith('structure') || lower.startsWith('architecture'))
+        return 'structure';
+    return null;
+}
+async function firstHtmlIn(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        const html = entries.find((e) => e.isFile() && e.name.endsWith('.html'));
+        return html === undefined ? null : path.join(dir, html.name);
+    }
+    catch {
+        return null;
+    }
+}
+/** 超时包装。 */
+export function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`等待 agent 结束超时（${ms} ms）`));
+        }, ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err instanceof Error ? err : new Error(String(err)));
+        });
+    });
+}
+/** 供测试使用：把树状态签名摆出来，别在测试里手抄格式。 */
+export function treeOf(tree) {
+    return tree === null ? 'none' : `${tree.staged}:${tree.unstaged}:${tree.untracked}`;
+}
+//# sourceMappingURL=runner.js.map