elanous 0.2.42 → 0.2.44

package/src/tool-runtime/elanous-linear-secretary-runtime.ts

@@ -0,0 +1,173 @@
+import { debug } from '../debug/log.js';
+import { fetchLinearIssueDescription, fetchLinearMissionIssueIdentity } from '../connectors/linear.js';
+import { DecisionLedger } from '../decisions/decision-ledger.js';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { getSecretAsync } from '../nexus/config/secrets/index.js';
+import { parseLinearSecretaryManifest, updateLinearSecretaryProgress, type LinearSecretaryCaptureInput } from '../intake-plane/linear-wish.js';
+import { submitIntakeWork, type SubmitIntakeWorkDeps } from '../intake-plane/submit-intake-work.js';
+import type { LLMToolSpec } from '../llm.js';
+import type { ToolRuntime, ToolRuntimeContext } from './types.js';
+
+export type ElanousLinearSecretaryArgs =
+  | { action: 'create'; request: string }
+  | { action: 'progress'; teamKey: 'DEMO'; parentIssueId: string; taskIssueId: string; state: 'started' | 'completed' | 'comment'; summary: string; absorbText?: string; captureArtifact?: LinearSecretaryCaptureInput; workaround?: string }
+  | { action: 'approval'; teamKey: 'DEMO'; parentIssueId: string; title: string; context: string };
+export interface ElanousLinearSecretaryResult extends Record<string, unknown> { ok: boolean; output: string }
+
+type CreateRunner = (request: string) => Promise<{ replyCard: string; parentIssueId: string; childIssueIds: string[] }>;
+const productionCreate: CreateRunner = async request =>
+  (await import('../intake-plane/linear-secretary-runtime.js')).runLinearSecretaryRequest(request);
+let createRunner = productionCreate;
+
+export function setElanousLinearSecretaryRunnerForTest(next?: CreateRunner): () => void {
+  if (createRunner !== productionCreate) throw new Error('Linear secretary runner already replaced');
+  createRunner = next ?? productionCreate;
+  const installed = createRunner;
+  return () => { if (createRunner === installed) createRunner = productionCreate; };
+}
+
+export interface ElanousLinearSecretaryRuntimeDeps {
+  create?: CreateRunner;
+  getApiKey?: () => Promise<string | undefined>;
+  fetch?: typeof fetch;
+  verifyParent?: typeof ensureDemoParent;
+  readChildManifest?: typeof readDemoChildManifest;
+  updateProgress?: typeof updateLinearSecretaryProgress;
+  intake?: SubmitIntakeWorkDeps;
+  ledger?: () => DecisionLedger;
+}
+
+async function ensureDemoParent(apiKey: string, parentIssueId: string, fetchFn: typeof fetch): Promise<void> {
+  const query = `query SecretaryDemoParent($id: String!) { issue(id: $id) { id team { key } } }`;
+  const response = await fetchFn('https://api.linear.app/graphql', { method: 'POST', headers: { Authorization: apiKey, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query, variables: { id: parentIssueId } }) });
+  if (!response.ok) throw new Error('Linear parent lookup failed');
+  const result = await response.json() as { errors?: unknown[]; data?: { issue?: { id?: string; team?: { key?: string } } | null } };
+  const issue = result.data?.issue;
+  if (result.errors?.length || !issue || issue.id !== parentIssueId || issue.team?.key !== 'DEMO') {
+    throw new Error('Linear secretary only accepts a parent issue in the DEMO team');
+  }
+}
+
+async function readDemoChildManifest(apiKey: string, parentIssueId: string, taskIssueId: string, fetchFn: typeof fetch) {
+  const identity = await fetchLinearMissionIssueIdentity({ apiKey, issueId: taskIssueId, fetch: fetchFn });
+  if (identity.teamKey !== 'DEMO' || identity.parentId !== parentIssueId) throw new Error('Linear secretary child is not listed in the DEMO parent manifest');
+  const description = await fetchLinearIssueDescription({ apiKey, issueId: taskIssueId, fetch: fetchFn });
+  const manifest = parseLinearSecretaryManifest(description, taskIssueId);
+  if (!manifest || manifest.parentIssueId !== parentIssueId) throw new Error('Linear secretary child is not listed in the DEMO parent manifest');
+  return manifest;
+}
+
+async function runProgress(args: Extract<ElanousLinearSecretaryArgs, { action: 'progress' }>, deps: ElanousLinearSecretaryRuntimeDeps) {
+  if (args.captureArtifact && (args.captureArtifact.externalShare !== true || args.captureArtifact.sensitivity !== 'public' ||
+      args.captureArtifact.linearIssueId !== args.parentIssueId || !args.captureArtifact.runId.trim() || !Number.isFinite(args.captureArtifact.createdAt))) {
+    return { ok: false, output: 'Linear 캡처는 현재 DEMO 부모에 대해 명시 승인된 공개 브라우저 증거여야 합니다.' };
+  }
+  const apiKey = await (deps.getApiKey?.() ?? getSecretAsync('connector.linear.apiKey'));
+  if (!apiKey?.trim()) throw new Error('Linear API key is missing; run elanous connector linear set-key');
+  const fetchFn = deps.fetch ?? globalThis.fetch;
+  await (deps.verifyParent ?? ensureDemoParent)(apiKey, args.parentIssueId, fetchFn);
+  const manifest = await (deps.readChildManifest ?? readDemoChildManifest)(apiKey, args.parentIssueId, args.taskIssueId, fetchFn);
+  const task = manifest.tasks.find(item => item.issueId === args.taskIssueId);
+  if (!task) throw new Error('Linear secretary child is not listed in the DEMO parent manifest');
+  const absorbed = args.absorbText?.trim() ? await (async text => {
+    const result = await submitIntakeWork({ text, track: 'absorb', origin: { kind: 'owner', ledgerSource: 'memo' } }, deps.intake);
+    return result.ok && result.track === 'absorb' ? { ok: true as const, ids: result.ids }
+      : { ok: false as const, reason: result.ok ? 'unexpected-intake-track' : result.reason };
+  })(args.absorbText.trim()) : undefined;
+  if (absorbed && (!absorbed.ok || !absorbed.ids.length)) throw new Error('흡수 근거를 intake 원장에 기록하지 못해 진행을 보류했습니다.');
+  const refs = absorbed?.ok ? absorbed.ids.map(id => `elanous:intake:${id}`) : [];
+  const summary = [args.summary.trim(), ...(refs.length ? [`흡수 근거: ${refs.join(' · ')}`] : [])].join('\n');
+  await (deps.updateProgress ?? updateLinearSecretaryProgress)({ apiKey, parentIssueId: args.parentIssueId, taskIssueId: task.issueId, taskTitle: task.title,
+    tasks: manifest.tasks, state: args.state, summary, ...(args.workaround ? { workaround: args.workaround } : {}),
+    ...(args.captureArtifact ? { captureArtifact: args.captureArtifact } : {}), fetch: fetchFn });
+  return { ok: true, output: `DEMO 하위 이슈 진행을 기록했습니다: ${task.issueId}`, parentIssueId: args.parentIssueId, taskIssueId: task.issueId, state: args.state,
+    ...(refs.length ? { evidenceRefs: refs } : {}) };
+}
+
+async function runApproval(args: Extract<ElanousLinearSecretaryArgs, { action: 'approval' }>, deps: ElanousLinearSecretaryRuntimeDeps) {
+  const apiKey = await (deps.getApiKey?.() ?? getSecretAsync('connector.linear.apiKey'));
+  if (!apiKey?.trim()) throw new Error('Linear API key is missing; run elanous connector linear set-key');
+  await (deps.verifyParent ?? ensureDemoParent)(apiKey, args.parentIssueId, deps.fetch ?? globalThis.fetch);
+  const refs = [args.parentIssueId];
+  const title = args.title.trim();
+  const context = args.context.trim();
+  if (!title || !context) throw new Error('Approval title and context are required');
+  const ledger = deps.ledger?.() ?? new DecisionLedger({ stateDir: elanousStateRoot() });
+  const ref = `linear-secretary-approval:${args.parentIssueId}`;
+  const entry = ledger.raiseOnce({ title, category: 'publish', scqa: { s: 'DEMO Linear 결과와 근거가 준비됐다.', c: context },
+    options: [{ key: 'a', label: '승인', consequence: '사람이 명시적으로 승인한 뒤 다음 동작을 진행한다' },
+      { key: 'b', label: '보류', consequence: '외부 공개를 멈춘다' }],
+    recommendation: { option: 'b', why: '승인 전에는 보류한다' }, raisedBy: { agent: 'OPT', track: 'OP' }, refs: [...refs, ref] }, ref);
+  // Local durable pending card only. No Telegram/card transport is invoked here.
+  const output = entry.status === 'open' ? `승인 대기 카드를 열었습니다: ${entry.id}` : `기존 승인 카드 ${entry.id}의 상태는 ${entry.status}입니다. 새 카드는 열지 않았습니다.`;
+  return { ok: true, output, decisionId: entry.id, status: entry.status };
+}
+
+export function createElanousLinearSecretaryRuntime(deps: ElanousLinearSecretaryRuntimeDeps = {}): ToolRuntime<ElanousLinearSecretaryArgs, ElanousLinearSecretaryResult> {
+return {
+  id: 'elanous_linear_secretary', surfaces: ['tui', 'mcp'],
+  spec: {
+    name: 'elanous_linear_secretary',
+    description: 'DEMO 팀 전용 grounded Linear secretary. create는 due date가 포함된 근거 기반 부모/하위 이슈를 만든다. progress는 intake 원문을 흡수한 ID와 명시 승인된 브라우저 캡처를 연결하고 하위 상태를 갱신한다. approval은 부모당 하나의 로컬 open 카드를 만든다. 같은 부모 재호출은 기존 카드 상태를 돌려주며 외부 발송은 없다.',
+    parameters: { type: 'object', properties: {
+      action: { type: 'string', enum: ['create', 'progress', 'approval'] },
+      request: { type: 'string', minLength: 1, description: 'create에 필수. 명시적 YYYY-MM-DD 날짜를 포함한다.' },
+      teamKey: { type: 'string', enum: ['DEMO'] }, parentIssueId: { type: 'string' }, taskIssueId: { type: 'string' },
+      state: { type: 'string', enum: ['started', 'completed', 'comment'] }, summary: { type: 'string' },
+      absorbText: { type: 'string', description: '흡수 원장에 실제 기록할 원문 또는 URL; 성공한 intake id만 진행 근거로 연결한다.' },
+      captureArtifact: { type: 'object', description: 'browser-runtime이 생성하고 Linear 공유가 명시 승인된 정확한 캡처 artifact',
+        properties: { path: { type: 'string' }, mimeType: { type: 'string', enum: ['image/png', 'image/jpeg', 'image/webp', 'image/gif'] },
+          runId: { type: 'string' }, linearIssueId: { type: 'string' }, externalShare: { type: 'boolean', enum: [true] },
+          sensitivity: { type: 'string', enum: ['public'] }, createdAt: { type: 'number' } },
+        required: ['path', 'mimeType', 'runId', 'linearIssueId', 'externalShare', 'sensitivity', 'createdAt'], additionalProperties: false },
+      workaround: { type: 'string' }, title: { type: 'string' }, context: { type: 'string' },
+    }, required: ['action'], additionalProperties: false },
+  } satisfies LLMToolSpec,
+  async run(args, _ctx): Promise<ElanousLinearSecretaryResult> {
+    try {
+      if (args?.action === 'create') {
+        const request = typeof args.request === 'string' ? args.request.trim() : '';
+        if (!request) return { ok: false, output: 'Linear 비서 요청 내용이 필요합니다.' };
+        const teamTokens = [...request.matchAll(/(?:^|\s)teamKey\s*=\s*([^\s]+)/gi)].map(match => match[1]);
+        const projectlessTokens = [...request.matchAll(/(?:^|\s)projectless\s*=\s*([^\s]+)/gi)].map(match => match[1]?.toLowerCase());
+        const declaredTeam = teamTokens[0];
+        if (teamTokens.length > 1 || (declaredTeam && declaredTeam.toUpperCase() !== 'DEMO') ||
+            projectlessTokens.length > 1 || projectlessTokens.some(token => token !== 'true') || (projectlessTokens.length === 1 && !declaredTeam)) {
+          return { ok: false, output: 'DEMO 팀만 지원합니다.' };
+        }
+        const normalizedRequest = request
+          .replace(/(^|\s)teamKey\s*=\s*[^\s]+/gi, '$1teamKey=DEMO')
+          .replace(/(^|\s)projectless\s*=\s*[^\s]+/gi, '$1projectless=true');
+        const scopedRequest = projectlessTokens.length === 1 ? normalizedRequest
+          : declaredTeam ? `projectless=true ${normalizedRequest}` : `projectless=true teamKey=DEMO ${request}`;
+        const result = await (deps.create ?? createRunner)(scopedRequest);
+        debug.log('tool.linear-secretary', 'created', { childCount: result.childIssueIds.length, teamKey: 'DEMO' });
+        return { ok: true, output: result.replyCard, parentIssueId: result.parentIssueId, childIssueIds: result.childIssueIds, teamKey: 'DEMO' };
+      }
+      if (args?.action === 'progress') {
+        if (args.teamKey !== 'DEMO' || !args.parentIssueId?.trim() || !args.taskIssueId?.trim() || !args.summary?.trim() || !args.state) return { ok: false, output: 'DEMO 진행 기록에는 팀·부모·하위 이슈·상태·요약이 필요합니다.' };
+        return await runProgress(args, deps);
+      }
+      if (args?.action === 'approval') {
+        if (args.teamKey !== 'DEMO' || !args.parentIssueId?.trim() || !args.title?.trim() || !args.context?.trim()) return { ok: false, output: 'DEMO 승인 카드에는 팀·부모 이슈·제목·맥락이 필요합니다.' };
+        return await runApproval(args, deps);
+      }
+      return { ok: false, output: '지원하지 않는 Linear secretary 작업입니다.' };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Linear 비서 실행 실패';
+      debug.log('tool.linear-secretary', 'failed', { action: args?.action ?? 'unknown', errorType: error instanceof Error ? 'Error' : 'unknown' });
+      const safeMessage = ['Linear secretary only accepts a parent issue in the DEMO team', 'Linear secretary child is not listed in the DEMO parent manifest',
+        'Linear API key is missing; run elanous connector linear set-key',
+        'Linear COO 프로젝트 설정이 없어 이슈 등록을 보류했습니다. 프로젝트를 지정해 주세요.',
+        '저장소 근거 검색 총 시간 제한(20초)을 초과했습니다.', '저장소 근거 검색 도구를 실행하지 못해 근거 확인을 완료하지 못했습니다.',
+        '저장소·문서·기억에서 확인된 근거가 없어 등록을 보류했습니다.', '요청에 마감일이 없어 등록을 보류했습니다. 요청에 YYYY-MM-DD 날짜를 넣어 주세요.',
+        '마감일이 없어 등록하지 않았습니다. 요청에 날짜를 넣어 주세요.', '흡수 근거를 intake 원장에 기록하지 못해 진행을 보류했습니다.']
+        .find(known => message.includes(known));
+      return { ok: false, output: safeMessage ?? 'Linear 비서 작업을 진행하지 못했습니다. 팀 키·이슈 ID·근거·권한을 확인해 주세요.' };
+    }
+  },
+};
+}
+
+export const elanousLinearSecretaryRuntime = createElanousLinearSecretaryRuntime();

package/src/tool-runtime/graph-mcp-runtimes.ts

@@ -0,0 +1,240 @@
+// External graph control uses the same wizard, editor run API, and runner as the local UI.
+// The MCP HTTP boundary filters mutating tools by token scope before dispatch.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { LLMToolSpec } from '../llm.js';
+import { debug } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { generateGraphFromPrompt } from '../graph-wizard/generate.js';
+import { handleGraphsCreate } from '../nexus/api/graphs-api.js';
+import { handleGraphRunGet, handleGraphRunStart } from '../graph-runner/graph-run-api.js';
+import { proposeGrowth } from '../graph-runner/graph-grow.js';
+import { runGraph, type GraphRunState } from '../graph-runner/runner.js';
+import { parseGraphTemplateYaml } from '../self-implement/graph-yaml.js';
+import type { ToolRuntime, ToolRuntimeContext } from './types.js';
+
+const GRAPH_ID = /^[a-z0-9-]+$/;
+const RUN_ID = /^ed-[a-z0-9]+-[a-f0-9]{6}$/;
+type Args = Record<string, unknown>;
+type Result = { output: string; [key: string]: unknown };
+export interface GraphMcpDeps {
+  root?: string;
+  mineDir?: string;
+  recipesFile?: string;
+  generate?: typeof generateGraphFromPrompt;
+  growth?: typeof proposeGrowth;
+  run?: typeof runGraph;
+}
+let testDeps: GraphMcpDeps = {};
+export function setGraphMcpDepsForTest(deps: GraphMcpDeps | undefined): void { testDeps = deps ?? {}; }
+const rootOf = () => testDeps.root ?? effectiveInstanceRoot();
+
+function value(args: Args, key: string): string | null {
+  const item = args[key];
+  return typeof item === 'string' && item.trim() ? item.trim() : null;
+}
+
+function error(tool: string, reason: string): Result {
+  return { output: `${tool}: ${reason}`, error: reason };
+}
+
+function observe(tool: string, action: string, ctx: ToolRuntimeContext, fields: Record<string, unknown>): void {
+  debug.log('mcp.graph', action, { tool, caller: ctx.mcpClient ?? 'unknown', ...fields });
+}
+
+function spec(name: string, description: string, properties: Record<string, unknown>, required: string[]): LLMToolSpec {
+  return { name, description, parameters: { type: 'object', properties, required } };
+}
+
+const composeSpec = spec('graph_compose', 'Preview a validated graph from one research goal. Does not save or run it.',
+  { goal: { type: 'string' } }, ['goal']);
+const startSpec = spec('graph_run_start', 'Start an existing saved graph, or save and start a graph_compose result. Requires a write-scoped MCP token.',
+  { graphId: { type: 'string' }, compose: { type: 'object', description: 'graph_compose result: id, yaml, optional validated steps.' },
+    reason: { type: 'string' } }, ['reason']);
+const statusSpec = spec('graph_run_status', 'Read bounded node states, outputs, and source IDs for a graph run.',
+  { graphId: { type: 'string' }, runId: { type: 'string' } }, ['graphId', 'runId']);
+const nodeSpec = spec('graph_node_op', 'Operate on a saved run: retry from a failed node, or add a validated growth node as a new linked run. Requires a write-scoped MCP token.',
+  { graphId: { type: 'string' }, runId: { type: 'string' }, op: { type: 'string', enum: ['retry', 'add-node'] },
+    nodeId: { type: 'string' }, outcome: { type: 'string' }, reason: { type: 'string' } },
+  ['graphId', 'runId', 'op', 'nodeId', 'reason']);
+
+function storedRun(graphId: string, runId: string, root: string): GraphRunState | null {
+  if (!GRAPH_ID.test(graphId) || !RUN_ID.test(runId)) return null;
+  try {
+    const state = JSON.parse(readFileSync(join(root, 'graph-runs', graphId, `${runId}.json`), 'utf8')) as GraphRunState;
+    return state.graphId === graphId && state.runId === runId ? state : null;
+  } catch { return null; }
+}
+
+async function compose(args: Args, ctx: ToolRuntimeContext): Promise<Result> {
+  const goal = value(args, 'goal');
+  if (!goal) return error('graph_compose', 'goal is required');
+  try {
+    const result = await (testDeps.generate ?? generateGraphFromPrompt)({ prompt: goal, kind: 'harness' });
+    observe('graph_compose', result.ok ? 'composed' : 'rejected', ctx, { graphId: result.id, reason: result.summary });
+    return { output: result.summary, ...result, compose: result.ok
+      ? { id: result.id, yaml: result.yaml, ...(result.steps ? { steps: result.steps } : {}) } : null };
+  } catch (cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    observe('graph_compose', 'failed', ctx, { reason });
+    return error('graph_compose', reason);
+  }
+}
+
+async function start(args: Args, ctx: ToolRuntimeContext): Promise<Result> {
+  const reason = value(args, 'reason');
+  const supplied = args.compose;
+  const candidate = supplied && typeof supplied === 'object' && !Array.isArray(supplied)
+    ? supplied as Record<string, unknown> : null;
+  const graphId = candidate ? value(candidate, 'id') : value(args, 'graphId');
+  if (!reason || !graphId || !GRAPH_ID.test(graphId)) return error('graph_run_start', 'valid graphId and reason are required');
+  if (candidate) {
+    if (typeof candidate.yaml !== 'string') return error('graph_run_start', 'compose.yaml is required');
+    const created = await handleGraphsCreate(new Request('http://localhost/v1/graphs', {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ id: graphId, yaml: candidate.yaml, ...(candidate.steps ? { steps: candidate.steps } : {}) }),
+    }), { ...(testDeps.mineDir ? { mineDir: testDeps.mineDir } : {}) });
+    if (!created.ok) {
+      const detail = await created.text();
+      observe('graph_run_start', 'refused', ctx, { graphId, reason, status: created.status });
+      return error('graph_run_start', `save refused (${created.status}): ${detail.slice(0, 300)}`);
+    }
+  }
+  const response = handleGraphRunStart(graphId, {
+    ...(testDeps.mineDir ? { mineDir: testDeps.mineDir } : {}),
+    root: rootOf(),
+    ...(testDeps.recipesFile ? { recipesFile: testDeps.recipesFile } : {}),
+  });
+  const body = await response.json() as Record<string, unknown>;
+  observe('graph_run_start', response.ok ? 'started' : 'refused', ctx,
+    { graphId, runId: body.runId ?? null, reason, status: response.status });
+  return { output: response.ok ? `Started ${graphId} run ${body.runId}` : `Start refused: ${JSON.stringify(body)}`,
+    ...body, status: response.status };
+}
+
+async function status(args: Args, ctx: ToolRuntimeContext): Promise<Result> {
+  const graphId = value(args, 'graphId');
+  const runId = value(args, 'runId');
+  if (!graphId || !runId || !GRAPH_ID.test(graphId) || !RUN_ID.test(runId)) return error('graph_run_status', 'invalid graphId or runId');
+  const response = handleGraphRunGet(graphId, runId, { root: rootOf() });
+  const body = await response.json() as Record<string, unknown>;
+  if (!response.ok) {
+    const reason = typeof body.reason === 'string' ? body.reason
+      : typeof body.error === 'string' ? body.error : `request failed (${response.status})`;
+    observe('graph_run_status', 'refused', ctx, { graphId, runId, status: response.status, error: reason });
+    return error('graph_run_status', reason);
+  }
+  const state = storedRun(graphId, runId, rootOf());
+  let truncated = false;
+  const clip = (text: string, max: number) => {
+    if (text.length > max) truncated = true;
+    return text.slice(0, max);
+  };
+  const allNodes = state?.nodes.map(node => {
+    const record = node.output && typeof node.output === 'object' && !Array.isArray(node.output)
+      ? node.output as Record<string, unknown> : null;
+    const sourceIds = [record?.sourceIds, record?.refs, record?.citations]
+      .flatMap(item => Array.isArray(item) ? item.filter((id): id is string => typeof id === 'string') : [])
+      .slice(0, 30);
+    const encodedOutput = node.output === undefined ? undefined : JSON.stringify(node.output);
+    if (sourceIds.length > 10) truncated = true;
+    return { nodeId: clip(node.nodeId, 160), ok: node.ok, exit: node.exit, executed: node.executed,
+      ...(node.error ? { error: clip(node.error, 300) } : {}),
+      sourceIds: sourceIds.slice(0, 10).map(id => clip(id, 120)),
+      ...(encodedOutput === undefined ? {} : { output: clip(encodedOutput, 800) }) };
+  }) ?? [];
+  const rawPath = Array.isArray(body.path) ? body.path : [];
+  const errorText = typeof body.error === 'string' ? body.error : undefined;
+  let nodes = [...allNodes].sort((a, b) => Number(b.ok === false) - Number(a.ok === false)).slice(0, 30);
+  let path = rawPath.slice(0, 100).map(nodeId => clip(String(nodeId), 160));
+  if (allNodes.length > nodes.length || rawPath.length > path.length) truncated = true;
+  const statusValue = clip(String(body.status ?? 'unknown'), 40);
+  const graphIdValue = clip(graphId, 120);
+  const runIdValue = clip(runId, 120);
+  const startedAt = typeof body.startedAt === 'string' ? clip(body.startedAt, 100) : undefined;
+  const finishedAt = typeof body.finishedAt === 'string' ? clip(body.finishedAt, 100) : undefined;
+  const boundedError = errorText ? clip(errorText, 1000) : undefined;
+  const serialize = () => JSON.stringify({
+    graphId: graphIdValue, runId: runIdValue, status: statusValue,
+    ...(startedAt ? { startedAt } : {}), ...(finishedAt ? { finishedAt } : {}),
+    ...(boundedError ? { error: boundedError } : {}), path, nodes, truncated,
+  });
+  let encoded = serialize();
+  while (Buffer.byteLength(encoded, 'utf8') > 24000 && nodes.length > 0) {
+    nodes = nodes.slice(0, -1);
+    truncated = true;
+    encoded = serialize();
+  }
+  while (Buffer.byteLength(encoded, 'utf8') > 24000 && path.length > 0) {
+    path = path.slice(0, -1);
+    truncated = true;
+    encoded = serialize();
+  }
+  if (Buffer.byteLength(encoded, 'utf8') > 24000) {
+    truncated = true;
+    path = [];
+    nodes = [];
+    encoded = serialize();
+  }
+  observe('graph_run_status', 'read', ctx, { graphId, runId, status: body.status ?? response.status });
+  return { output: encoded, ...JSON.parse(encoded) as Record<string, unknown> };
+}
+
+async function nodeOp(args: Args, ctx: ToolRuntimeContext): Promise<Result> {
+  const graphId = value(args, 'graphId');
+  const runId = value(args, 'runId');
+  const op = value(args, 'op');
+  const nodeId = value(args, 'nodeId');
+  const reason = value(args, 'reason');
+  if (!graphId || !runId || !GRAPH_ID.test(graphId) || !RUN_ID.test(runId) || !nodeId || !reason
+    || !['retry', 'add-node'].includes(op ?? '')) return error('graph_node_op', 'invalid graphId, runId, op, nodeId, or reason');
+  if (op === 'add-node' && !value(args, 'outcome'))
+    return error('graph_node_op', 'add-node requires the observed node outcome');
+  const root = rootOf();
+  const state = storedRun(graphId, runId, root);
+  if (!state || state.status !== 'failed' || !state.path.includes(nodeId))
+    return error('graph_node_op', 'a failed run and node on its saved path are required');
+  const graphFile = join(root, 'graph-run-work', graphId, runId, 'graph.yaml');
+  if (op === 'retry') {
+    try {
+      // Runner enforces the saved source hash, approval boundary, and failed-path limit.
+      const next = await (testDeps.run ?? runGraph)(graphFile, { resumeRunId: runId, fromNodeId: nodeId, deps: { root } });
+      observe('graph_node_op', op, ctx, { graphId, runId, nodeId, reason, status: next.status });
+      return { output: `${op}: ${next.status}`, graphId, runId, status: next.status, path: next.path };
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause);
+      observe('graph_node_op', 'refused', ctx, { graphId, runId, nodeId, op, reason, error: message });
+      return error('graph_node_op', message);
+    }
+  }
+  try {
+    const parsed = parseGraphTemplateYaml(readFileSync(graphFile, 'utf8'), graphFile);
+    if (!parsed.template || parsed.errors.length) return error('graph_node_op', 'saved graph is invalid');
+    const nodeOutput = [...state.nodes].reverse().find(node => node.nodeId === nodeId)?.output;
+    const outcome = value(args, 'outcome')!;
+    const growth = await (testDeps.growth ?? proposeGrowth)({ graph: parsed.template, nodeId, outcome, runId, output: nodeOutput },
+      undefined, () => 'unknown', { root });
+    if (!growth.ok) {
+      observe('graph_node_op', 'refused', ctx, { graphId, runId, nodeId, op, reason, detail: growth.reason });
+      return error('graph_node_op', growth.reason);
+    }
+    const returnTo = growth.growth.edges.find(edge => edge.from === growth.growth.node.nodeId)?.to;
+    if (!returnTo) return error('graph_node_op', 'growth has no return node');
+    const next = await (testDeps.run ?? runGraph)(graphFile, { variant: { goal: `mcp_${runId}`,
+      plan: { growth: { node: growth.growth.node, from: nodeId, outcome,
+        returnTo } } }, input: { source: 'mcp', parentRunId: runId, reason }, deps: { root } });
+    observe('graph_node_op', 'add-node', ctx, { graphId, runId: next.runId, parentRunId: runId, nodeId, reason, status: next.status });
+    return { output: `add-node: ${next.status}`, graphId, runId: next.runId, parentRunId: runId, status: next.status };
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    observe('graph_node_op', 'refused', ctx, { graphId, runId, nodeId, op, reason, error: message });
+    return error('graph_node_op', message);
+  }
+}
+
+export const GRAPH_MCP_RUNTIMES: ToolRuntime<Args, Result>[] = [
+  { id: 'graph_compose', spec: composeSpec, surfaces: ['mcp'], run: compose },
+  { id: 'graph_run_start', spec: startSpec, surfaces: ['mcp'], run: start },
+  { id: 'graph_run_status', spec: statusSpec, surfaces: ['mcp'], run: status },
+  { id: 'graph_node_op', spec: nodeSpec, surfaces: ['mcp'], run: nodeOp },
+];

package/src/tool-runtime/index.ts

@@ -62,11 +62,14 @@ import { skillExecRuntime } from './skill-exec-runtime.js';
 import { elanousObsidianSearchRuntime } from './elanous-obsidian-search-runtime.js';
 import { elanousObsidianInfoRuntime } from './elanous-obsidian-info-runtime.js';
 import { ELANOUS_ASANA_RUNTIMES } from './elanous-asana-runtimes.js';
+import { elanousLinearSecretaryRuntime } from './elanous-linear-secretary-runtime.js';
+import { elanousLinearIssueRuntime } from './elanous-linear-issue-runtime.js';
 import { elanousFsListRuntime } from './elanous-fs-list-runtime.js';
 import { elanousFsReadRuntime } from './elanous-fs-read-runtime.js';
 import { elanousShowroomBroadcastRuntime } from './elanous-showroom-broadcast-runtime.js';
 import { elanousAutopilotLaunchRuntime } from './elanous-autopilot-launch-runtime.js';
 import { elanousTaskSubmitRuntime } from './elanous-task-submit-runtime.js';
+import { GRAPH_MCP_RUNTIMES } from './graph-mcp-runtimes.js';
 import { persistentGroundingRuntime } from './persistent-grounding-runtime.js';
 import { goalAuthorRuntime } from './goal-author-runtime.js';
 import { bootstrapMcpProxyRuntimes } from './mcp-proxy-bootstrap.js';
@@ -167,11 +170,14 @@ export function registerAllDefaultToolRuntimes(opts: RegisterAllDefaultToolRunti
   registerToolRuntime(elanousObsidianSearchRuntime);
   registerToolRuntime(elanousObsidianInfoRuntime);
   for (const rt of ELANOUS_ASANA_RUNTIMES) registerToolRuntime(rt);
+  registerToolRuntime(elanousLinearSecretaryRuntime);
+  registerToolRuntime(elanousLinearIssueRuntime);
   registerToolRuntime(elanousFsListRuntime);
   registerToolRuntime(elanousFsReadRuntime);
   registerToolRuntime(elanousShowroomBroadcastRuntime);
   registerToolRuntime(elanousAutopilotLaunchRuntime);
   registerToolRuntime(elanousTaskSubmitRuntime);
+  for (const rt of GRAPH_MCP_RUNTIMES) registerToolRuntime(rt);
   for (const rt of SELF_COGNITION_RUNTIMES) registerToolRuntime(rt);
   for (const rt of ELANOUS_CONTROL_RUNTIMES) registerToolRuntime(rt);
   // External MCP proxies already declare surfaces `['mcp','tui']`, but the

package/src/tool-runtime/types.ts

@@ -52,6 +52,8 @@ export interface ToolRuntimeContext {
   /** MCP only — the connected client's `clientInfo.name` from `initialize`
    *  (e.g. `claude-code`, `codex-mcp-client`). Unset on other surfaces. */
   mcpClient?: string;
+  /** Optional caller-supplied MCP join key. Correlation only; never an authorization input. */
+  runId?: string;
   /** Cancellation — forwarded to underlying dispatcher when
    *  supported (e.g. streaming fetch, long-running agent calls). */
   signal?: AbortSignal;
@@ -66,6 +68,9 @@ export interface ToolRuntimeContext {
     dispatch: (name: string, args: Record<string, unknown>) => Promise<unknown>;
     workingDirectory: string;
   };
+  /** TUI-only opt-in for inheriting the parent's policy-filtered catalog when
+   *  the general-purpose agent definition omits its own tool allowlist. */
+  inheritGeneralPurposeToolCatalog?: boolean;
   /** M5 (PLAN-rich-dev-feedback-multi-surface · 2026-05-13) —
    *  optional progress emitter. Runtimes that produce streaming
    *  side effects (bash stdout tail, search hit streaming, edit

package/src/tui/entry.ts

@@ -99,6 +99,9 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
   let sidetabChordTimer: ReturnType<typeof setTimeout> | null = null;
   let sidetabRemoteFrame: string | null = null;
   let sidetabRows: import('./sidetab/list.js').SidetabRow[] = [];
+  let herdrSidetabRows: import('./sidetab/list.js').SidetabRow[] = [];
+  let herdrSidetabRefreshPending = false;
+  let herdrSidetabPortal: import('./sidetab/herdr-portal.js').HerdrSidetabPortal | null = null;
   let sidetabApi: typeof import('./sidetab/list.js') | null = null;
   // ⚠️ `as` 단언은 «null 로 좁혀지는» 흐름 분석을 푸는 것 — 값은 클로저(ensureSidetabAttachments) 안에서만 바뀐다.
   let sidetabAttachments: import('./sidetab/attach.js').SidetabAttachmentController | null = null as import('./sidetab/attach.js').SidetabAttachmentController | null;
@@ -357,6 +360,8 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
 
   const ensureSidetabAttachments = async (): Promise<void> => {
     if (sidetabAttachments) return;
+    const herdrPortalModule = await import('./sidetab/herdr-portal.js');
+    herdrSidetabPortal ??= herdrPortalModule.createHerdrSidetabPortal();
     const installer = await import('../agent-mission/tool-install.js') as unknown as {
       detectAgentCli?: (agent: 'codex' | 'claude') => Promise<{
         agent: 'codex' | 'claude'; installed: boolean; version: string | null;
@@ -364,6 +369,8 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
       }>;
     };
     sidetabAttachments = (await import('./sidetab/attach.js')).createSidetabAttachmentController({
+      herdrPortal: herdrSidetabPortal,
+      logEvent: (category, event, data) => debug.log(category, event, data),
       drawBase: () => {
         paintingCoordinatorFrame = true;
         try { render(); } finally { paintingCoordinatorFrame = false; }
@@ -403,9 +410,11 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
     sidetabSelected = next.selected;
     sidetabMode = 'list';
     if (sidetabOpen && sidetabRefreshTimer === null) {
+      void refreshHerdrSidetabRows();
       sidetabRefreshTimer = setInterval(() => {
         if (!sidetabOpen || !sidetabApi) return;
         refreshSidetabRows();
+        void refreshHerdrSidetabRows();
         render();
       }, 1000);
     } else if (!sidetabOpen && sidetabRefreshTimer !== null) {
@@ -417,12 +426,24 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
   const refreshSidetabRows = (): void => {
     if (!sidetabApi) return;
     const selectedId = sidetabRows[sidetabSelected]?.id;
-    sidetabRows = sidetabApi.loadSidetabRows(sidetabAll);
+    sidetabRows = [...sidetabApi.loadSidetabRows(sidetabAll), ...herdrSidetabRows];
     const preservedIndex = selectedId ? sidetabRows.findIndex((row) => row.id === selectedId) : -1;
     sidetabSelected = preservedIndex >= 0
       ? preservedIndex
       : Math.min(sidetabSelected, Math.max(0, sidetabRows.length - 1));
   };
+  const refreshHerdrSidetabRows = async (): Promise<void> => {
+    if (herdrSidetabRefreshPending) return;
+    herdrSidetabRefreshPending = true;
+    try {
+      const portal = await import('./sidetab/herdr-portal.js');
+      herdrSidetabPortal ??= portal.createHerdrSidetabPortal();
+      await herdrSidetabPortal.refreshRows();
+      herdrSidetabRows = [...herdrSidetabPortal.rows()];
+      refreshSidetabRows();
+    } catch { /* Herdr is optional; TUI rows remain available. */ }
+    finally { herdrSidetabRefreshPending = false; }
+  };
   const switchSidetabSession = async (requestedSessionId?: string): Promise<void> => {
     const selected = sidetabRows[sidetabSelected];
     const targetId = requestedSessionId ?? (selected?.kind === 'tui' ? selected.sessionId : undefined);
@@ -590,10 +611,21 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
             firstResponseSeen = true;
             dashboardRuntime.endTurnStartSegments(turnSessionId, 'stream-open');
           }
-          // The first model token is visible before the final JSONL frame. Keep only
-          // a bounded tail until session history becomes the canonical display.
-          streamingReply = replace ? delta.slice(-32_768) : (streamingReply + delta).slice(-32_768);
-          activity = streamReplyLines(streamingReply, process.stdout.columns || 80);
+          // The first model token is visible while the turn runs. Once the core
+          // replaces that provisional answer, let the persisted final message
+          // become canonical instead of showing the same answer in both layers.
+          if (replace) {
+            streamingReply = '';
+            activity = [];
+            if (streamRenderTimer !== null) clearTimeout(streamRenderTimer);
+            streamRenderTimer = null;
+            streamRenderAt = performance.now();
+            render();
+            return;
+          } else {
+            streamingReply = (streamingReply + delta).slice(-32_768);
+            activity = streamReplyLines(streamingReply, process.stdout.columns || 80);
+          }
           const now = performance.now();
           if (streamRenderAt === 0 || now - streamRenderAt >= 33) {
             streamRenderAt = now;
@@ -636,7 +668,6 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
         activity = [];
         streamingReply = '';
         busy = false;
-        reportTuiTurn('idle');
         turnAbort = null;
         scroll = 0;
         settle();
@@ -659,17 +690,28 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
         }
         const switchAfterTurn = pendingSidetabSwitch;
         pendingSidetabSwitch = null;
-        if (switchAfterTurn) await switchSidetabSession(switchAfterTurn);
-        render();
+        try {
+          if (switchAfterTurn) await switchSidetabSession(switchAfterTurn);
+        } finally {
+          try {
+            render();
+          } finally {
+            // Publish idle only after the canonical history has replaced the stream preview
+            // on screen. External PTY observers use this edge as their capture boundary.
+            reportTuiTurn('idle');
+          }
+        }
       });
   };
 
   if (sidetabOpen) {
     sidetabApi = await import('./sidetab/list.js');
     sidetabRows = sidetabApi.loadSidetabRows(sidetabAll);
+    void refreshHerdrSidetabRows();
     sidetabRefreshTimer = setInterval(() => {
       if (!sidetabApi || !sidetabOpen) return;
       refreshSidetabRows();
+      void refreshHerdrSidetabRows();
       render();
     }, 1_000);
   }
@@ -731,6 +773,7 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
         detach: () => { if (sidetabAttachments?.hasRemoteView()) sidetabAttachments.showMain(); else if (sidetabAttachments?.hasModal()) { sidetabAttachments.handleKey({ name: '\\', ctrl: true, shift: false, raw: '' }); sidetabAttachments.handleKey({ name: 'd', ctrl: false, shift: false, raw: 'd' }); } render(); return { ok: true, action: 'detach' }; },
         spawn: async (character) => { await ensureSidetabAttachments(); const ok = sidetabAttachments!.spawn(character); refreshSidetabRows(); render(); return { ok, action: 'new', character }; },
         runMission: async (agent, mission) => { await ensureSidetabAttachments(); const result = await sidetabAttachments!.runMission(agent, mission); refreshSidetabRows(); render(); return result; },
+        runMissionPair: async (agent, mission, parallelMission) => { await ensureSidetabAttachments(); const result = await sidetabAttachments!.runMissionPair(agent, mission, parallelMission); refreshSidetabRows(); render(); return result; },
         kill: async (row) => { await ensureSidetabAttachments(); const ok = sidetabAttachments!.kill(row); refreshSidetabRows(); render(); return { ok, action: 'kill', target: row.id }; },
       }));
       const gate = wakeup.gate;