@pellux/goodvibes-agent 1.1.7 → 1.2.0

package/src/tools/agent-harness-research-queue.ts

@@ -0,0 +1,250 @@
+import type { CommandContext } from '../input/command-registry.ts';
+import {
+  AgentResearchSourceRegistry,
+  researchSourceReportLine,
+  type AgentResearchSourceRecord,
+  type AgentResearchSourceStatus,
+} from '../agent/research-source-registry.ts';
+import { previewHarnessText } from './agent-harness-text.ts';
+
+interface AgentHarnessResearchQueueArgs {
+  readonly sourceId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+interface ResearchQueueItem {
+  readonly source: AgentResearchSourceRecord;
+  readonly priority: number;
+  readonly next: string;
+  readonly modelRoute: string;
+  readonly inspectRoute: string;
+  readonly bundleRoute?: string;
+  readonly reviewRoute?: string;
+  readonly rejectRoute?: string;
+  readonly reportRoute?: string;
+  readonly ingestRoute?: string;
+}
+
+export type ResearchSourceResolution =
+  | { readonly status: 'found'; readonly source: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
+  | { readonly status: 'missing_lookup'; readonly usage: string };
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readLimit(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
+  return Math.max(1, Math.min(200, Math.trunc(parsed)));
+}
+
+function routeString(value: string): string {
+  return JSON.stringify(value);
+}
+
+function statusPriority(status: AgentResearchSourceStatus): number {
+  if (status === 'candidate') return 86;
+  if (status === 'reviewed') return 72;
+  if (status === 'used') return 42;
+  return 20;
+}
+
+function nextForSource(source: AgentResearchSourceRecord): string {
+  if (source.status === 'candidate') return 'Review credibility, score, and notes before citing or ingesting this source.';
+  if (source.status === 'reviewed') return 'Use this source in a report, attach it to a document, or explicitly ingest it into Agent Knowledge if it should become durable.';
+  if (source.status === 'used') return 'Inspect the saved report or promote the report artifact into Agent Knowledge only after review.';
+  return 'Leave rejected unless new evidence changes the source assessment.';
+}
+
+function buildQueueItem(source: AgentResearchSourceRecord): ResearchQueueItem {
+  const reviewRoute = source.status === 'candidate' || source.status === 'rejected'
+    ? `research action:"review_source" id="${source.id}" confirm:true explicitUserRequest="..."`
+    : '';
+  const rejectRoute = source.status !== 'rejected'
+    ? `research action:"reject_source" id="${source.id}" confirm:true explicitUserRequest="..."`
+    : '';
+  const reportRoute = source.status === 'reviewed' || source.status === 'used'
+    ? 'research action:"report" confirm:true explicitUserRequest:"..."'
+    : '';
+  const bundleRoute = source.status === 'reviewed' || source.status === 'used'
+    ? `research action:"bundle" query:${routeString(source.id)} limit:10`
+    : '';
+  const ingestRoute = source.status === 'reviewed' || source.status === 'used'
+    ? 'agent_knowledge_ingest sourceKind="url" confirm=true explicitUserRequest="..."'
+    : '';
+  return {
+    source,
+    priority: Math.max(statusPriority(source.status), source.score),
+    next: nextForSource(source),
+    modelRoute: 'research action:"source"',
+    inspectRoute: `research action:"source" sourceId="${source.id}"`,
+    ...(bundleRoute ? { bundleRoute } : {}),
+    ...(reviewRoute ? { reviewRoute } : {}),
+    ...(rejectRoute ? { rejectRoute } : {}),
+    ...(reportRoute ? { reportRoute } : {}),
+    ...(ingestRoute ? { ingestRoute } : {}),
+  };
+}
+
+function sourceSearchText(item: ResearchQueueItem): string {
+  const source = item.source;
+  return [
+    source.id,
+    source.question,
+    source.title,
+    source.url ?? '',
+    source.publisher ?? '',
+    source.summary,
+    source.evidence ?? '',
+    source.credibility,
+    source.status,
+    source.note ?? '',
+    source.tags.join('\n'),
+    item.inspectRoute,
+    item.bundleRoute ?? '',
+    item.reviewRoute ?? '',
+    item.reportRoute ?? '',
+    item.ingestRoute ?? '',
+  ].join('\n').toLowerCase();
+}
+
+function queueItems(context: CommandContext): readonly ResearchQueueItem[] {
+  const shellPaths = context.workspace?.shellPaths;
+  if (!shellPaths) return [];
+  return AgentResearchSourceRegistry.fromShellPaths(shellPaths)
+    .list()
+    .map(buildQueueItem)
+    .sort((left, right) => right.priority - left.priority || right.source.updatedAt.localeCompare(left.source.updatedAt));
+}
+
+function describeSourceItem(item: ResearchQueueItem, includeParameters: boolean, lookup?: Record<string, unknown>): Record<string, unknown> {
+  const source = item.source;
+  return {
+    sourceId: source.id,
+    title: source.title,
+    question: previewHarnessText(source.question, includeParameters ? 180 : 96),
+    status: source.status,
+    credibility: source.credibility,
+    score: source.score,
+    priority: item.priority,
+    summary: previewHarnessText(source.summary, includeParameters ? 220 : 96),
+    ...(source.url ? { url: source.url } : {}),
+    ...(source.publisher ? { publisher: source.publisher } : {}),
+    tags: source.tags,
+    next: previewHarnessText(item.next, includeParameters ? 180 : 96),
+    modelRoute: item.modelRoute,
+    inspectRoute: item.inspectRoute,
+    ...(item.bundleRoute ? { bundleRoute: item.bundleRoute } : {}),
+    ...(item.reviewRoute ? { reviewRoute: item.reviewRoute } : {}),
+    ...(item.rejectRoute ? { rejectRoute: item.rejectRoute } : {}),
+    ...(item.reportRoute ? { reportRoute: item.reportRoute } : {}),
+    ...(item.ingestRoute ? { ingestRoute: item.ingestRoute } : {}),
+    reportSourceLine: researchSourceReportLine(source),
+    ...(lookup ? { lookup } : {}),
+    ...(includeParameters ? {
+      evidence: source.evidence ?? null,
+      note: source.note ?? null,
+      createdAt: source.createdAt,
+      updatedAt: source.updatedAt,
+      reviewedAt: source.reviewedAt ?? null,
+      rejectedAt: source.rejectedAt ?? null,
+      usedAt: source.usedAt ?? null,
+      policy: 'Research queue rows are local project state only. Report save, Knowledge ingest, external sends, and deletion stay on explicit separate routes.',
+    } : {}),
+  };
+}
+
+function nextActions(items: readonly ResearchQueueItem[]): readonly string[] {
+  return items
+    .filter((item) => item.source.status === 'candidate' || item.source.status === 'reviewed')
+    .slice(0, 5)
+    .map((item) => `${item.source.title}: ${item.next}`);
+}
+
+export function researchQueueCatalogStatus(context: CommandContext): Record<string, unknown> {
+  const items = queueItems(context);
+  return {
+    modes: ['research_queue', 'research_source'],
+    sources: items.length,
+    candidates: items.filter((item) => item.source.status === 'candidate').length,
+    reviewed: items.filter((item) => item.source.status === 'reviewed').length,
+    rejected: items.filter((item) => item.source.status === 'rejected').length,
+    used: items.filter((item) => item.source.status === 'used').length,
+    readOnly: true,
+  };
+}
+
+export function researchQueueSummary(context: CommandContext, args: AgentHarnessResearchQueueArgs): Record<string, unknown> {
+  const includeParameters = args.includeParameters === true;
+  const query = readString(args.query).toLowerCase();
+  const limit = readLimit(args.limit, 100);
+  const items = queueItems(context);
+  const filtered = items.filter((item) => !query || sourceSearchText(item).includes(query));
+  const bundleItems = filtered.filter((item) => item.source.status === 'reviewed' || item.source.status === 'used');
+  return {
+    summary: {
+      sources: items.length,
+      candidates: items.filter((item) => item.source.status === 'candidate').length,
+      reviewed: items.filter((item) => item.source.status === 'reviewed').length,
+      rejected: items.filter((item) => item.source.status === 'rejected').length,
+      used: items.filter((item) => item.source.status === 'used').length,
+    },
+    sources: filtered.slice(0, limit).map((item) => describeSourceItem(item, includeParameters)),
+    bundle: {
+      sources: bundleItems.length,
+      route: query
+        ? `research action:"bundle" query:${routeString(query)} limit:${Math.min(limit, 20)}`
+        : `research action:"bundle" limit:${Math.min(limit, 20)}`,
+      reportRoute: 'research action:"report" requireCitationCoverage:true confirm:true explicitUserRequest:"..."',
+      next: 'Use bundle route to assemble reviewed/used sources into citation-ready report input before saving a report artifact.',
+    },
+    returned: Math.min(filtered.length, limit),
+    total: items.length,
+    nextActions: nextActions(items),
+    policy: 'Research queue is read-only in the harness. Source capture/review writes use confirmed research source actions; report artifacts and Knowledge ingest remain explicit separate steps.',
+  };
+}
+
+export function describeResearchSource(context: CommandContext, args: AgentHarnessResearchQueueArgs): ResearchSourceResolution {
+  const sourceId = readString(args.sourceId);
+  const target = readString(args.target);
+  const query = readString(args.query);
+  const input = sourceId || target || query;
+  if (!input) {
+    return {
+      status: 'missing_lookup',
+      usage: 'research_source requires sourceId, target, or query. Use research action:"sources" to inspect source ids.',
+    };
+  }
+  const normalized = input.toLowerCase();
+  const items = queueItems(context);
+  const exact = items.find((item) => item.source.id === input);
+  if (exact) return { status: 'found', source: describeSourceItem(exact, true, { source: sourceId ? 'sourceId' : target ? 'target' : 'query', input, resolvedBy: 'id' }) };
+  const insensitive = items.find((item) => item.source.id.toLowerCase() === normalized);
+  if (insensitive) return { status: 'found', source: describeSourceItem(insensitive, true, { source: sourceId ? 'sourceId' : target ? 'target' : 'query', input, resolvedBy: 'case-insensitive-id' }) };
+  const matches = items.filter((item) => sourceSearchText(item).includes(normalized));
+  if (matches.length === 1) return { status: 'found', source: describeSourceItem(matches[0]!, true, { source: sourceId ? 'sourceId' : target ? 'target' : 'query', input, resolvedBy: 'search' }) };
+  if (matches.length > 1) {
+    return {
+      status: 'ambiguous',
+      input,
+      candidates: matches.slice(0, 8).map((item) => ({
+        sourceId: item.source.id,
+        title: item.source.title,
+        status: item.source.status,
+        credibility: item.source.credibility,
+        score: item.source.score,
+        modelRoute: item.modelRoute,
+      })),
+    };
+  }
+  return {
+    status: 'missing_lookup',
+    usage: `Unknown research source ${input}. Use research action:"sources" to inspect source ids.`,
+  };
+}

package/src/tools/agent-harness-research-runs.ts

@@ -0,0 +1,295 @@
+import type { CommandContext } from '../input/command-registry.ts';
+import {
+  AgentResearchRunRegistry,
+  researchRunLogTail,
+  researchRunReportLine,
+  type AgentResearchRunRecord,
+  type AgentResearchRunStatus,
+} from '../agent/research-run-registry.ts';
+import { browserControlPosture } from './agent-harness-browser-control.ts';
+import { previewHarnessText } from './agent-harness-text.ts';
+
+interface AgentHarnessResearchRunArgs {
+  readonly runId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+interface ResearchRunItem {
+  readonly run: AgentResearchRunRecord;
+  readonly priority: number;
+  readonly next: string;
+  readonly modelRoute: string;
+  readonly inspectRoute: string;
+  readonly checkpointRoute?: string;
+  readonly pauseRoute?: string;
+  readonly resumeRoute?: string;
+  readonly cancelRoute?: string;
+  readonly completeRoute?: string;
+  readonly reportRoute?: string;
+}
+
+export type ResearchRunResolution =
+  | { readonly status: 'found'; readonly run: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
+  | { readonly status: 'missing_lookup'; readonly usage: string };
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readLimit(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
+  return Math.max(1, Math.min(200, Math.trunc(parsed)));
+}
+
+function statusPriority(status: AgentResearchRunStatus): number {
+  if (status === 'running') return 96;
+  if (status === 'blocked') return 90;
+  if (status === 'paused') return 82;
+  if (status === 'planned') return 76;
+  if (status === 'failed') return 64;
+  if (status === 'cancelled') return 30;
+  return 42;
+}
+
+function isMutable(status: AgentResearchRunStatus): boolean {
+  return status !== 'cancelled' && status !== 'completed' && status !== 'failed';
+}
+
+function nextForRun(run: AgentResearchRunRecord): string {
+  if (run.status === 'planned') return 'Start the run or add an initial checkpoint before doing more research.';
+  if (run.status === 'running') return 'Checkpoint source ids, progress, and next steps before switching tasks or saving a report.';
+  if (run.status === 'paused') return 'Resume only when the user wants this research to continue.';
+  if (run.status === 'blocked') return 'Resolve the blocker or cancel with a clear note.';
+  if (run.status === 'failed') return 'Inspect the failure note, then create a new run or recover manually.';
+  if (run.status === 'completed') return 'Inspect the saved report artifact or explicitly promote reviewed artifacts to Agent Knowledge.';
+  return 'Leave cancelled unless the user asks to create a replacement run.';
+}
+
+function buildRunItem(run: AgentResearchRunRecord): ResearchRunItem {
+  const mutable = isMutable(run.status);
+  const checkpointRoute = mutable
+    ? `research action:"checkpoint" id="${run.id}" confirm:true explicitUserRequest="..."`
+    : '';
+  const pauseRoute = run.status === 'running' || run.status === 'blocked'
+    ? `research action:"pause" id="${run.id}" confirm:true explicitUserRequest="..."`
+    : '';
+  const resumeRoute = run.status === 'paused' || run.status === 'planned' || run.status === 'blocked'
+    ? `research action:"resume" id="${run.id}" confirm:true explicitUserRequest="..."`
+    : '';
+  const cancelRoute = mutable
+    ? `research action:"cancel" id="${run.id}" note="..." confirm:true explicitUserRequest="..."`
+    : '';
+  const completeRoute = mutable
+    ? `research action:"complete" id="${run.id}" reportArtifactId="..." confirm:true explicitUserRequest="..."`
+    : '';
+  return {
+    run,
+    priority: statusPriority(run.status) + Math.min(20, Math.round(run.progress / 5)),
+    next: nextForRun(run),
+    modelRoute: 'research action:"run"',
+    inspectRoute: `research action:"run" runId="${run.id}"`,
+    ...(checkpointRoute ? { checkpointRoute } : {}),
+    ...(pauseRoute ? { pauseRoute } : {}),
+    ...(resumeRoute ? { resumeRoute } : {}),
+    ...(cancelRoute ? { cancelRoute } : {}),
+    ...(completeRoute ? { completeRoute } : {}),
+    reportRoute: 'research action:"report" confirm:true explicitUserRequest:"..."',
+  };
+}
+
+function runSearchText(item: ResearchRunItem): string {
+  const run = item.run;
+  return [
+    run.id,
+    run.title,
+    run.question,
+    run.goal,
+    run.status,
+    run.phase,
+    run.note ?? '',
+    run.error ?? '',
+    run.reportArtifactId ?? '',
+    researchRunLogTail(run, 5).join('\n'),
+    run.plan.join('\n'),
+    run.nextSteps.join('\n'),
+    run.sourceIds.join('\n'),
+    item.inspectRoute,
+    item.checkpointRoute ?? '',
+    item.pauseRoute ?? '',
+    item.resumeRoute ?? '',
+    item.cancelRoute ?? '',
+    item.completeRoute ?? '',
+  ].join('\n').toLowerCase();
+}
+
+function runItems(context: CommandContext): readonly ResearchRunItem[] {
+  const shellPaths = context.workspace?.shellPaths;
+  if (!shellPaths) return [];
+  return AgentResearchRunRegistry.fromShellPaths(shellPaths)
+    .list()
+    .map(buildRunItem)
+    .sort((left, right) => right.priority - left.priority || right.run.updatedAt.localeCompare(left.run.updatedAt));
+}
+
+function describeRunItem(item: ResearchRunItem, includeParameters: boolean, lookup?: Record<string, unknown>): Record<string, unknown> {
+  const run = item.run;
+  return {
+    runId: run.id,
+    title: run.title,
+    question: previewHarnessText(run.question, includeParameters ? 180 : 96),
+    goal: previewHarnessText(run.goal, includeParameters ? 180 : 96),
+    status: run.status,
+    phase: run.phase,
+    progress: run.progress,
+    priority: item.priority,
+    sources: run.sourceIds.length,
+    checkpoints: run.checkpoints.length,
+    logTail: researchRunLogTail(run, includeParameters ? 5 : 3),
+    ...(run.reportArtifactId ? { reportArtifactId: run.reportArtifactId } : {}),
+    next: previewHarnessText(item.next, includeParameters ? 180 : 96),
+    modelRoute: item.modelRoute,
+    inspectRoute: item.inspectRoute,
+    ...(item.checkpointRoute ? { checkpointRoute: item.checkpointRoute } : {}),
+    ...(item.pauseRoute ? { pauseRoute: item.pauseRoute } : {}),
+    ...(item.resumeRoute ? { resumeRoute: item.resumeRoute } : {}),
+    ...(item.cancelRoute ? { cancelRoute: item.cancelRoute } : {}),
+    ...(item.completeRoute ? { completeRoute: item.completeRoute } : {}),
+    ...(item.reportRoute ? { reportRoute: item.reportRoute } : {}),
+    runLine: researchRunReportLine(run),
+    ...(lookup ? { lookup } : {}),
+    ...(includeParameters ? {
+      plan: run.plan,
+      nextSteps: run.nextSteps,
+      sourceIds: run.sourceIds,
+      note: run.note ?? null,
+      error: run.error ?? null,
+      createdAt: run.createdAt,
+      updatedAt: run.updatedAt,
+      startedAt: run.startedAt ?? null,
+      pausedAt: run.pausedAt ?? null,
+      cancelledAt: run.cancelledAt ?? null,
+      completedAt: run.completedAt ?? null,
+      failedAt: run.failedAt ?? null,
+      checkpoints: run.checkpoints.slice(-10),
+      policy: 'Research run rows are local visible state only. Web research, source review, report saves, Knowledge ingest, and external sends stay on explicit separate routes.',
+    } : {}),
+  };
+}
+
+function researchRunnerPosture(context: CommandContext, includeParameters: boolean): Record<string, unknown> {
+  const browser = browserControlPosture(context);
+  return {
+    browserBackedResearch: {
+      status: browser.status,
+      configured: browser.configured,
+      needsReview: browser.needsReview,
+      recommendedRoute: browser.recommendedRoute,
+      setupRoute: browser.setupRoute,
+      fallbackRoutes: browser.fallbackRoutes,
+      workflows: browser.workflows.map((workflow) => ({
+        id: workflow.id,
+        label: workflow.label,
+        status: workflow.status,
+        next: previewHarnessText(workflow.next, includeParameters ? 180 : 96),
+        inspectRoute: workflow.inspectRoute,
+        safety: previewHarnessText(workflow.safety, includeParameters ? 180 : 96),
+      })),
+    },
+    sourceQueueRoute: 'research action:"sources"',
+    sourceReviewRoute: 'research action:"review_source" confirm:true explicitUserRequest:"..."',
+    reportRoute: 'research action:"report" confirm:true explicitUserRequest:"..."',
+    knowledgePromotionRoute: 'agent_knowledge_ingest sourceKind:"artifact" artifactId:"..." confirm:true explicitUserRequest:"..."',
+    policy: 'Use browser-backed research only when browser/desktop control is ready or reviewed. Public web research can use web/fetch routes; report saving and Knowledge promotion remain separate confirmed effects.',
+  };
+}
+
+function nextActions(items: readonly ResearchRunItem[]): readonly string[] {
+  return items
+    .filter((item) => item.run.status === 'planned' || item.run.status === 'running' || item.run.status === 'paused' || item.run.status === 'blocked')
+    .slice(0, 5)
+    .map((item) => `${item.run.title}: ${item.next}`);
+}
+
+export function researchRunsCatalogStatus(context: CommandContext): Record<string, unknown> {
+  const items = runItems(context);
+  return {
+    modes: ['research_runs', 'research_run'],
+    runs: items.length,
+    planned: items.filter((item) => item.run.status === 'planned').length,
+    running: items.filter((item) => item.run.status === 'running').length,
+    paused: items.filter((item) => item.run.status === 'paused').length,
+    blocked: items.filter((item) => item.run.status === 'blocked').length,
+    terminal: items.filter((item) => !isMutable(item.run.status)).length,
+    cancellable: items.filter((item) => isMutable(item.run.status)).length,
+    readOnly: true,
+  };
+}
+
+export function researchRunsSummary(context: CommandContext, args: AgentHarnessResearchRunArgs): Record<string, unknown> {
+  const includeParameters = args.includeParameters === true;
+  const query = readString(args.query).toLowerCase();
+  const limit = readLimit(args.limit, 100);
+  const items = runItems(context);
+  const filtered = items.filter((item) => !query || runSearchText(item).includes(query));
+  return {
+    summary: {
+      runs: items.length,
+      planned: items.filter((item) => item.run.status === 'planned').length,
+      running: items.filter((item) => item.run.status === 'running').length,
+      paused: items.filter((item) => item.run.status === 'paused').length,
+      blocked: items.filter((item) => item.run.status === 'blocked').length,
+      terminal: items.filter((item) => !isMutable(item.run.status)).length,
+      cancellable: items.filter((item) => isMutable(item.run.status)).length,
+    },
+    runs: filtered.slice(0, limit).map((item) => describeRunItem(item, includeParameters)),
+    runnerPosture: researchRunnerPosture(context, includeParameters),
+    returned: Math.min(filtered.length, limit),
+    total: items.length,
+    nextActions: nextActions(items),
+    policy: 'Research runs are read-only in the harness. Run-state writes use confirmed research lifecycle actions; sources, reports, Knowledge, and delivery stay on separate explicit routes.',
+  };
+}
+
+export function describeResearchRun(context: CommandContext, args: AgentHarnessResearchRunArgs): ResearchRunResolution {
+  const runId = readString(args.runId);
+  const target = readString(args.target);
+  const query = readString(args.query);
+  const input = runId || target || query;
+  if (!input) {
+    return {
+      status: 'missing_lookup',
+      usage: 'research_run requires runId, target, or query. Use research action:"runs" to inspect run ids.',
+    };
+  }
+  const normalized = input.toLowerCase();
+  const items = runItems(context);
+  const exact = items.find((item) => item.run.id === input);
+  if (exact) return { status: 'found', run: describeRunItem(exact, true, { source: runId ? 'runId' : target ? 'target' : 'query', input, resolvedBy: 'id' }) };
+  const insensitive = items.find((item) => item.run.id.toLowerCase() === normalized);
+  if (insensitive) return { status: 'found', run: describeRunItem(insensitive, true, { source: runId ? 'runId' : target ? 'target' : 'query', input, resolvedBy: 'case-insensitive-id' }) };
+  const matches = items.filter((item) => runSearchText(item).includes(normalized));
+  if (matches.length === 1) return { status: 'found', run: describeRunItem(matches[0]!, true, { source: runId ? 'runId' : target ? 'target' : 'query', input, resolvedBy: 'search' }) };
+  if (matches.length > 1) {
+    return {
+      status: 'ambiguous',
+      input,
+      candidates: matches.slice(0, 8).map((item) => ({
+        runId: item.run.id,
+        title: item.run.title,
+        status: item.run.status,
+        phase: item.run.phase,
+        progress: item.run.progress,
+        modelRoute: item.modelRoute,
+      })),
+    };
+  }
+  return {
+    status: 'missing_lookup',
+    usage: `Unknown research run ${input}. Use research action:"runs" to inspect run ids.`,
+  };
+}