@pellux/goodvibes-agent 1.2.0 → 1.3.0

package/src/tools/agent-research-runner.ts

@@ -0,0 +1,367 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+import type { CommandContext } from '../input/command-registry.ts';
+import { AgentResearchRunRegistry, type AgentResearchRunRecord } from '../agent/research-run-registry.ts';
+import { AgentResearchSourceRegistry, researchSourceReportLine, type AgentResearchSourceRecord } from '../agent/research-source-registry.ts';
+import type { AgentResearchToolArgs } from './agent-research-tool.ts';
+
+type ToolResult = { readonly success: true; readonly output: string } | { readonly success: false; readonly error: string };
+
+function error(message: string): { readonly success: false; readonly error: string } {
+  return { success: false, error: message };
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readNumber(value: unknown, fallback: number, max: 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(max, Math.trunc(parsed)));
+}
+
+function compactArgs(entries: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined && value !== ''));
+}
+
+function searchArgs(args: AgentResearchToolArgs): Record<string, unknown> {
+  const safeSearch = readString(args.safeSearch).toLowerCase() === 'strict' ? 'strict' : 'moderate';
+  return compactArgs({
+    query: args.query ?? args.target,
+    providerId: args.providerId,
+    maxResults: readNumber(args.maxResults, readNumber(args.limit, 5, 10), 10),
+    verbosity: 'evidence',
+    region: args.region,
+    safeSearch,
+    timeRange: args.timeRange,
+    includeEvidence: true,
+    evidenceTopN: readNumber(args.evidenceTopN, 3, 3),
+    evidenceExtract: args.evidenceExtract ?? 'readable',
+  });
+}
+
+function previewText(value: unknown, limit: number): string {
+  const text = typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : '';
+  if (text.length <= limit) return text;
+  return `${text.slice(0, Math.max(0, limit - 3)).trimEnd()}...`;
+}
+
+function quote(value: string): string {
+  return JSON.stringify(value);
+}
+
+function fallbackTitle(question: string): string {
+  const cleaned = question.trim().replace(/\s+/g, ' ');
+  if (!cleaned) return 'Deep research run';
+  return cleaned.length <= 72 ? cleaned : `${cleaned.slice(0, 71).trimEnd()}...`;
+}
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+function readRecordArray(value: unknown): readonly Record<string, unknown>[] {
+  return Array.isArray(value) ? value.map(readRecord).filter((entry): entry is Record<string, unknown> => Boolean(entry)) : [];
+}
+
+function hostname(value: string): string {
+  try {
+    return new URL(value).hostname.replace(/^www\./i, '');
+  } catch {
+    return '';
+  }
+}
+
+function sanitizeUrlForRoute(value: string): string {
+  try {
+    const url = new URL(value);
+    for (const key of [...url.searchParams.keys()]) {
+      if (/token|secret|password|authorization|credential|api[-_]?key/i.test(key)) url.searchParams.set(key, '<redacted>');
+    }
+    return url.toString();
+  } catch {
+    return value.replace(/([?&\s](?:token|secret|password|authorization|credential|api[-_]?key)=)[^\s&]+/gi, '$1<redacted>');
+  }
+}
+
+function candidateFromSearchResult(question: string, result: Record<string, unknown>, index: number): Record<string, unknown> {
+  const rawUrl = readString(result.url);
+  const url = sanitizeUrlForRoute(rawUrl);
+  const title = previewText(result.title, 120) || hostname(rawUrl) || `Search result ${index + 1}`;
+  const publisher = previewText(result.domain, 80) || hostname(rawUrl);
+  const evidenceRecords = readRecordArray(result.evidence);
+  const evidenceText = previewText(
+    evidenceRecords.map((entry) => readString(entry.content)).filter(Boolean).join('\n\n') || result.snippet,
+    420,
+  );
+  const summary = previewText(result.snippet, 260) || previewText(evidenceText, 260) || `Public web result for ${question}.`;
+  const captureArgs = compactArgs({
+    action: 'add_source',
+    question,
+    title,
+    url,
+    publisher,
+    summary,
+    evidence: evidenceText,
+    credibility: 'unreviewed',
+    tags: ['research', 'web-search'],
+    confirm: true,
+    explicitUserRequest: '...',
+  });
+  return {
+    rank: typeof result.rank === 'number' ? result.rank : index + 1,
+    title,
+    url,
+    ...(publisher ? { publisher } : {}),
+    summary,
+    ...(evidenceText ? { evidencePreview: evidenceText } : {}),
+    captureArgs,
+    captureRoute: [
+      'research action:"add_source"',
+      `question:${quote(question)}`,
+      `title:${quote(title)}`,
+      ...(url ? [`url:${quote(url)}`] : []),
+      ...(publisher ? [`publisher:${quote(publisher)}`] : []),
+      `summary:${quote(summary)}`,
+      ...(evidenceText ? [`evidence:${quote(evidenceText)}`] : []),
+      'credibility:"unreviewed"',
+      'tags:["research","web-search"]',
+      'confirm:true',
+      'explicitUserRequest:"..."',
+    ].join(' '),
+  };
+}
+
+function parseSearchPayload(outputValue: unknown): Record<string, unknown> | null {
+  if (typeof outputValue !== 'string') return readRecord(outputValue);
+  try {
+    return readRecord(JSON.parse(outputValue));
+  } catch {
+    return null;
+  }
+}
+
+function resolveSearchRun(args: AgentResearchToolArgs, shellPaths: CommandContext['workspace']['shellPaths'] | undefined): AgentResearchRunRecord | null {
+  if (!shellPaths) return null;
+  const lookup = readString(args.runId) || readString(args.id);
+  if (!lookup) return null;
+  return AgentResearchRunRegistry.fromShellPaths(shellPaths).get(lookup);
+}
+
+export async function runPublicSearch(
+  webSearchTool: Tool | undefined,
+  args: AgentResearchToolArgs,
+  shellPaths: CommandContext['workspace']['shellPaths'] | undefined,
+): Promise<ToolResult> {
+  const run = resolveSearchRun(args, shellPaths);
+  const query = readString(args.query) || readString(args.question) || run?.question || readString(args.target);
+  if ((readString(args.runId) || readString(args.id)) && !run && !readString(args.query) && !readString(args.question)) {
+    return error(`Unknown research run ${readString(args.runId) || readString(args.id)}. Use research action:"runs" to inspect run ids.`);
+  }
+  if (!query) return error('research action:"search" requires query or target.');
+  if (!webSearchTool) {
+    return error('Bounded public web search is unavailable because web_search is not registered. Use research action:"briefing" for the offline next-action queue or action:"plan" for the route plan.');
+  }
+  const webArgs = searchArgs({ ...args, query });
+  const webResult = await webSearchTool.execute(webArgs);
+  if (!webResult.success) return { success: false, error: readString(webResult.error) || 'web_search failed.' };
+  const payload = parseSearchPayload(webResult.output);
+  const results = readRecordArray(payload?.results);
+  const sourceCandidates = results
+    .filter((result) => readString(result.url))
+    .map((result, index) => candidateFromSearchResult(query, result, index));
+  return {
+    success: true,
+    output: JSON.stringify({
+      status: sourceCandidates.length > 0 ? 'source-candidates-ready' : 'no-source-candidates',
+      query,
+      providerId: readString(payload?.providerId),
+      providerLabel: readString(payload?.providerLabel),
+      resultCount: results.length,
+      sourceCandidateCount: sourceCandidates.length,
+      sourceCandidates,
+      nextRoutes: {
+        ...(run ? {
+          run: `research action:"run" runId:${quote(run.id)}`,
+          briefing: `research action:"briefing" target:${quote(run.id)}`,
+          startRun: `research action:"start_run" id:${quote(run.id)} confirm:true explicitUserRequest:"..."`,
+          checkpointAfterCapture: `research action:"checkpoint" id:${quote(run.id)} phase:"reading" progress:${Math.max(run.progress, 25)} note:"Captured candidate sources for review." sourceIds:["..."] confirm:true explicitUserRequest:"..."`,
+        } : {
+          createRun: `research action:"create_run" question:${quote(query)} plan:["Search bounded public web sources","Capture candidate sources","Review credibility","Save sourced report"] confirm:true explicitUserRequest:"..."`,
+        }),
+        sourceQueue: `research action:"sources" query:${quote(query)}`,
+        reviewedBundle: `research action:"bundle" query:${quote(query)} includeReportLines:true`,
+        saveReport: `research action:"report" question:${quote(query)} sources:[...] visualReport:true requireCitationCoverage:true confirm:true explicitUserRequest:"..."`,
+      },
+      ...(run ? { run: { id: run.id, title: run.title, status: run.status, phase: run.phase, progress: run.progress } } : {}),
+      searchArgs: webArgs,
+      policy: 'This route performs bounded read-only public web search only. It does not create or start a run, save sources, checkpoint progress, write a report, ingest Knowledge, or send messages. Use each returned route only after explicit user confirmation.',
+    }, null, 2),
+  };
+}
+
+function requireConfirmedRunner(args: AgentResearchToolArgs): string {
+  const explicitUserRequest = readString(args.explicitUserRequest);
+  if (!explicitUserRequest) throw new Error('research action:"runner" requires explicitUserRequest before it can create or checkpoint a visible research run.');
+  if (args.confirm !== true) throw new Error('research action:"runner" requires confirm:true before it can create or checkpoint a visible research run.');
+  return explicitUserRequest;
+}
+
+function researchSourceRoutes(source: AgentResearchSourceRecord): Record<string, unknown> {
+  return {
+    sourceId: source.id,
+    title: source.title,
+    status: source.status,
+    credibility: source.credibility,
+    score: source.score,
+    inspectRoute: `research action:"source" sourceId:${quote(source.id)}`,
+    reviewRoute: `research action:"review_source" id:${quote(source.id)} credibility:"high|medium|mixed|low" score:80 note:"..." confirm:true explicitUserRequest:"..."`,
+    reportLine: researchSourceReportLine(source),
+  };
+}
+
+function sourceFromCandidate(
+  registry: AgentResearchSourceRegistry,
+  question: string,
+  candidate: Record<string, unknown>,
+): { readonly source: AgentResearchSourceRecord; readonly created: boolean } | null {
+  const title = readString(candidate.title);
+  const summary = readString(candidate.summary);
+  const url = readString(candidate.url);
+  if (!title || !summary) return null;
+  const publisher = readString(candidate.publisher);
+  const evidence = readString(candidate.evidencePreview);
+  try {
+    return {
+      created: true,
+      source: registry.create({
+        question,
+        title,
+        ...(url ? { url } : {}),
+        ...(publisher ? { publisher } : {}),
+        summary,
+        ...(evidence ? { evidence } : {}),
+        credibility: 'unreviewed',
+        tags: ['research', 'web-search', 'runner'],
+        note: 'Captured by confirmed GoodVibes research runner.',
+        provenance: 'agent-research-runner',
+      }),
+    };
+  } catch (err) {
+    const existing = registry.get(url || title);
+    if (existing) return { created: false, source: existing };
+    throw err;
+  }
+}
+
+export async function runConfirmedResearchRunner(
+  webSearchTool: Tool | undefined,
+  args: AgentResearchToolArgs,
+  shellPaths: CommandContext['workspace']['shellPaths'] | undefined,
+): Promise<ToolResult> {
+  try {
+    const explicitUserRequest = requireConfirmedRunner(args);
+    if (!shellPaths) return error('Confirmed research runner is unavailable because this runtime did not provide shell paths.');
+    if (!webSearchTool) return error('Confirmed research runner requires the web_search tool for bounded source collection. Use research action:"plan" for offline routing.');
+    const runRegistry = AgentResearchRunRegistry.fromShellPaths(shellPaths);
+    const sourceRegistry = AgentResearchSourceRegistry.fromShellPaths(shellPaths);
+    const lookup = readString(args.runId) || readString(args.id);
+    const existingRun = lookup ? runRegistry.get(lookup) : null;
+    if (lookup && !existingRun) return error(`Unknown research run ${lookup}. Use research action:"runs" to inspect run ids.`);
+    const question = readString(args.query) || readString(args.question) || readString(args.target) || existingRun?.question || explicitUserRequest;
+    if (!question) return error('Confirmed research runner requires query, question, target, or an existing run with a question.');
+    let run = existingRun ?? runRegistry.create({
+      title: readString(args.title) || fallbackTitle(question),
+      question,
+      goal: readString(args.goal) || `Collect reviewed source candidates for: ${question}`,
+      plan: [
+        'Run bounded public web source collection.',
+        'Save candidate sources into the local research source queue.',
+        'Checkpoint the visible research run with source ids and next review steps.',
+        'Save a citation-covered report only after source review.',
+      ],
+      nextSteps: ['Run bounded source collection.', 'Review candidate sources.', 'Save a sourced report artifact.'],
+      note: `Confirmed runner authorized by user request: ${previewText(explicitUserRequest, 160)}`,
+      provenance: 'agent-research-runner',
+    });
+    if (run.status === 'planned') {
+      run = runRegistry.start(run.id, 'Confirmed research runner started bounded source collection.');
+    } else if (run.status === 'paused' || run.status === 'blocked') {
+      run = runRegistry.resume(run.id, 'Confirmed research runner resumed bounded source collection.');
+    } else if (run.status === 'completed' || run.status === 'failed' || run.status === 'cancelled') {
+      return error(`Cannot run confirmed research runner for ${run.status} research run ${run.id}. Create a follow-up run instead.`);
+    }
+
+    const webResult = await webSearchTool.execute(searchArgs({ ...args, query: run.question }));
+    if (!webResult.success) {
+      run = runRegistry.checkpoint(run.id, {
+        status: 'blocked',
+        phase: 'searching',
+        progress: Math.max(run.progress, 10),
+        note: `Confirmed research runner blocked during source collection: ${readString(webResult.error) || 'web_search failed.'}`,
+        nextSteps: ['Inspect runner readiness.', 'Retry bounded source collection after search is available.'],
+      });
+      return {
+        success: false,
+        error: `Confirmed research runner blocked for ${run.id}: ${readString(webResult.error) || 'web_search failed.'}`,
+      };
+    }
+
+    const payload = parseSearchPayload(webResult.output);
+    const results = readRecordArray(payload?.results);
+    const candidates = results
+      .filter((result) => readString(result.url))
+      .map((result, index) => candidateFromSearchResult(run.question, result, index));
+    const saved = candidates
+      .map((candidate) => sourceFromCandidate(sourceRegistry, run.question, candidate))
+      .filter((entry): entry is { readonly source: AgentResearchSourceRecord; readonly created: boolean } => entry !== null);
+    const sourceIds = saved.map((entry) => entry.source.id);
+    const createdCount = saved.filter((entry) => entry.created).length;
+    const duplicateCount = saved.length - createdCount;
+    run = runRegistry.checkpoint(run.id, {
+      status: 'running',
+      phase: 'reading',
+      progress: Math.max(run.progress, sourceIds.length > 0 ? 35 : 20),
+      note: `Confirmed research runner captured ${createdCount} new source candidate(s)${duplicateCount > 0 ? ` and reused ${duplicateCount} existing source(s)` : ''}.`,
+      nextSteps: sourceIds.length > 0
+        ? ['Review candidate source credibility.', 'Save a citation-covered report artifact after source review.']
+        : ['Try a more specific query or provider.', 'Capture sources manually if public search found none.'],
+      sourceIds,
+    });
+
+    return {
+      success: true,
+      output: JSON.stringify({
+        status: sourceIds.length > 0 ? 'source-collection-checkpointed' : 'no-source-candidates-checkpointed',
+        run: {
+          id: run.id,
+          title: run.title,
+          status: run.status,
+          phase: run.phase,
+          progress: run.progress,
+          sourceIds: run.sourceIds,
+          inspectRoute: `research action:"run" runId:${quote(run.id)}`,
+          checkpointRoute: `research action:"checkpoint" id:${quote(run.id)} phase:"reading" progress:${Math.max(run.progress, 35)} note:"..." sourceIds:["..."] confirm:true explicitUserRequest:"..."`,
+          cancelRoute: `research action:"cancel" id:${quote(run.id)} note:"..." confirm:true explicitUserRequest:"..."`,
+        },
+        query: run.question,
+        providerId: readString(payload?.providerId),
+        resultCount: results.length,
+        sourceCandidateCount: candidates.length,
+        savedSourceCount: createdCount,
+        reusedSourceCount: duplicateCount,
+        sources: saved.map((entry) => researchSourceRoutes(entry.source)),
+        nextRoutes: {
+          run: `research action:"run" runId:${quote(run.id)}`,
+          sources: `research action:"sources" query:${quote(run.question)} includeReportLines:true`,
+          reviewSource: 'research action:"review_source" id:"..." credibility:"high|medium|mixed|low" score:80 note:"..." confirm:true explicitUserRequest:"..."',
+          bundle: `research action:"bundle" query:${quote(run.question)} includeReportLines:true`,
+          saveReport: `research action:"report" question:${quote(run.question)} sources:[...] visualReport:true requireCitationCoverage:true confirm:true explicitUserRequest:"..."`,
+        },
+        policy: 'Confirmed research runner only creates/updates local visible research run state and local source queue records. It does not save a report, ingest Knowledge, send messages, or control a browser/PWA surface.',
+      }, null, 2),
+    };
+  } catch (err) {
+    return error(err instanceof Error ? err.message : String(err));
+  }
+}

package/src/tools/agent-research-tool.ts

@@ -1,11 +1,11 @@
 import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
 import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
 import type { CommandContext, CommandRegistry } from '../input/command-registry.ts';
-import { AgentResearchRunRegistry, type AgentResearchRunRecord } from '../agent/research-run-registry.ts';
 import { createAgentArtifactsTool } from './agent-artifacts-tool.ts';
 import { createAgentHarnessTool } from './agent-harness-tool.ts';
 import { createAgentResearchReportTool } from './agent-research-report-tool.ts';
 import { createAgentResearchRunsTool } from './agent-research-runs-tool.ts';
+import { runConfirmedResearchRunner, runPublicSearch } from './agent-research-runner.ts';
 import { createAgentResearchSourcesTool } from './agent-research-sources-tool.ts';
 
 type AgentResearchAction =
@@ -36,7 +36,7 @@ type AgentResearchAction =
   | 'delete_source'
   | 'report';
 
-interface AgentResearchToolArgs {
+export interface AgentResearchToolArgs {
   readonly action?: unknown;
   readonly mode?: unknown;
   readonly id?: unknown;
@@ -111,12 +111,6 @@ function readString(value: unknown): string {
   return typeof value === 'string' ? value.trim() : '';
 }
 
-function readNumber(value: unknown, fallback: number, max: 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(max, Math.trunc(parsed)));
-}
-
 function normalizeResearchAction(value: unknown): AgentResearchAction | null {
   const action = readString(value).toLowerCase().replace(/-/g, '_');
   if (!action) return null;
@@ -279,22 +273,6 @@ function bundleArgs(args: AgentResearchToolArgs): Record<string, unknown> {
   });
 }
 
-function searchArgs(args: AgentResearchToolArgs): Record<string, unknown> {
-  const safeSearch = readString(args.safeSearch).toLowerCase() === 'strict' ? 'strict' : 'moderate';
-  return compactArgs({
-    query: args.query ?? args.target,
-    providerId: args.providerId,
-    maxResults: readNumber(args.maxResults, readNumber(args.limit, 5, 10), 10),
-    verbosity: 'evidence',
-    region: args.region,
-    safeSearch,
-    timeRange: args.timeRange,
-    includeEvidence: true,
-    evidenceTopN: readNumber(args.evidenceTopN, 3, 3),
-    evidenceExtract: args.evidenceExtract ?? 'readable',
-  });
-}
-
 function reportsArgs(args: AgentResearchToolArgs): Record<string, unknown> {
   return compactArgs({
     mode: 'list',
@@ -313,160 +291,6 @@ function reportArtifactArgs(args: AgentResearchToolArgs): Record<string, unknown
   });
 }
 
-function previewText(value: unknown, limit: number): string {
-  const text = typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : '';
-  if (text.length <= limit) return text;
-  return `${text.slice(0, Math.max(0, limit - 3)).trimEnd()}...`;
-}
-
-function quote(value: string): string {
-  return JSON.stringify(value);
-}
-
-function readRecord(value: unknown): Record<string, unknown> | null {
-  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
-}
-
-function readRecordArray(value: unknown): readonly Record<string, unknown>[] {
-  return Array.isArray(value) ? value.map(readRecord).filter((entry): entry is Record<string, unknown> => Boolean(entry)) : [];
-}
-
-function hostname(value: string): string {
-  try {
-    return new URL(value).hostname.replace(/^www\./i, '');
-  } catch {
-    return '';
-  }
-}
-
-function sanitizeUrlForRoute(value: string): string {
-  try {
-    const url = new URL(value);
-    for (const key of [...url.searchParams.keys()]) {
-      if (/token|secret|password|authorization|credential|api[-_]?key/i.test(key)) url.searchParams.set(key, '<redacted>');
-    }
-    return url.toString();
-  } catch {
-    return value.replace(/([?&\s](?:token|secret|password|authorization|credential|api[-_]?key)=)[^\s&]+/gi, '$1<redacted>');
-  }
-}
-
-function candidateFromSearchResult(question: string, result: Record<string, unknown>, index: number): Record<string, unknown> {
-  const rawUrl = readString(result.url);
-  const url = sanitizeUrlForRoute(rawUrl);
-  const title = previewText(result.title, 120) || hostname(rawUrl) || `Search result ${index + 1}`;
-  const publisher = previewText(result.domain, 80) || hostname(rawUrl);
-  const evidenceRecords = readRecordArray(result.evidence);
-  const evidenceText = previewText(
-    evidenceRecords.map((entry) => readString(entry.content)).filter(Boolean).join('\n\n') || result.snippet,
-    420,
-  );
-  const summary = previewText(result.snippet, 260) || previewText(evidenceText, 260) || `Public web result for ${question}.`;
-  const captureArgs = compactArgs({
-    action: 'add_source',
-    question,
-    title,
-    url,
-    publisher,
-    summary,
-    evidence: evidenceText,
-    credibility: 'unreviewed',
-    tags: ['research', 'web-search'],
-    confirm: true,
-    explicitUserRequest: '...',
-  });
-  return {
-    rank: typeof result.rank === 'number' ? result.rank : index + 1,
-    title,
-    url,
-    ...(publisher ? { publisher } : {}),
-    summary,
-    ...(evidenceText ? { evidencePreview: evidenceText } : {}),
-    captureArgs,
-    captureRoute: [
-      'research action:"add_source"',
-      `question:${quote(question)}`,
-      `title:${quote(title)}`,
-      ...(url ? [`url:${quote(url)}`] : []),
-      ...(publisher ? [`publisher:${quote(publisher)}`] : []),
-      `summary:${quote(summary)}`,
-      ...(evidenceText ? [`evidence:${quote(evidenceText)}`] : []),
-      'credibility:"unreviewed"',
-      'tags:["research","web-search"]',
-      'confirm:true',
-      'explicitUserRequest:"..."',
-    ].join(' '),
-  };
-}
-
-function parseSearchPayload(outputValue: unknown): Record<string, unknown> | null {
-  if (typeof outputValue !== 'string') return readRecord(outputValue);
-  try {
-    return readRecord(JSON.parse(outputValue));
-  } catch {
-    return null;
-  }
-}
-
-function resolveSearchRun(args: AgentResearchToolArgs, shellPaths: CommandContext['workspace']['shellPaths'] | undefined): AgentResearchRunRecord | null {
-  if (!shellPaths) return null;
-  const lookup = readString(args.runId) || readString(args.id);
-  if (!lookup) return null;
-  return AgentResearchRunRegistry.fromShellPaths(shellPaths).get(lookup);
-}
-
-async function runPublicSearch(
-  webSearchTool: Tool | undefined,
-  args: AgentResearchToolArgs,
-  shellPaths: CommandContext['workspace']['shellPaths'] | undefined,
-): Promise<{ readonly success: true; readonly output: string } | { readonly success: false; readonly error: string }> {
-  const run = resolveSearchRun(args, shellPaths);
-  const query = readString(args.query) || readString(args.question) || run?.question || readString(args.target);
-  if ((readString(args.runId) || readString(args.id)) && !run && !readString(args.query) && !readString(args.question)) {
-    return error(`Unknown research run ${readString(args.runId) || readString(args.id)}. Use research action:"runs" to inspect run ids.`);
-  }
-  if (!query) return error('research action:"search" requires query or target.');
-  if (!webSearchTool) {
-    return error('Bounded public web search is unavailable because web_search is not registered. Use research action:"briefing" for the offline next-action queue or action:"plan" for the route plan.');
-  }
-  const webArgs = searchArgs({ ...args, query });
-  const webResult = await webSearchTool.execute(webArgs);
-  if (!webResult.success) return { success: false, error: readString(webResult.error) || 'web_search failed.' };
-  const payload = parseSearchPayload(webResult.output);
-  const results = readRecordArray(payload?.results);
-  const sourceCandidates = results
-    .filter((result) => readString(result.url))
-    .map((result, index) => candidateFromSearchResult(query, result, index));
-  return {
-    success: true,
-    output: JSON.stringify({
-      status: sourceCandidates.length > 0 ? 'source-candidates-ready' : 'no-source-candidates',
-      query,
-      providerId: readString(payload?.providerId),
-      providerLabel: readString(payload?.providerLabel),
-      resultCount: results.length,
-      sourceCandidateCount: sourceCandidates.length,
-      sourceCandidates,
-      nextRoutes: {
-        ...(run ? {
-          run: `research action:"run" runId:${quote(run.id)}`,
-          briefing: `research action:"briefing" target:${quote(run.id)}`,
-          startRun: `research action:"start_run" id:${quote(run.id)} confirm:true explicitUserRequest:"..."`,
-          checkpointAfterCapture: `research action:"checkpoint" id:${quote(run.id)} phase:"reading" progress:${Math.max(run.progress, 25)} note:"Captured candidate sources for review." sourceIds:["..."] confirm:true explicitUserRequest:"..."`,
-        } : {
-          createRun: `research action:"create_run" question:${quote(query)} plan:["Search bounded public web sources","Capture candidate sources","Review credibility","Save sourced report"] confirm:true explicitUserRequest:"..."`,
-        }),
-        sourceQueue: `research action:"sources" query:${quote(query)}`,
-        reviewedBundle: `research action:"bundle" query:${quote(query)} includeReportLines:true`,
-        saveReport: `research action:"report" question:${quote(query)} sources:[...] visualReport:true requireCitationCoverage:true confirm:true explicitUserRequest:"..."`,
-      },
-      ...(run ? { run: { id: run.id, title: run.title, status: run.status, phase: run.phase, progress: run.progress } } : {}),
-      searchArgs: webArgs,
-      policy: 'This route performs bounded read-only public web search only. It does not create or start a run, save sources, checkpoint progress, write a report, ingest Knowledge, or send messages. Use each returned route only after explicit user confirmation.',
-    }, null, 2),
-  };
-}
-
 function addSourceArgs(args: AgentResearchToolArgs): Record<string, unknown> {
   return compactArgs({
     mode: 'add',
@@ -648,7 +472,11 @@ export function createAgentResearchTool(deps: AgentResearchToolDeps): Tool {
 
       if (action === 'briefing') return harnessTool.execute(briefingArgs(args));
       if (action === 'plan') return harnessTool.execute(planArgs(args));
-      if (action === 'runner') return harnessTool.execute(runnerArgs(args));
+      if (action === 'runner') {
+        return args.confirm === true
+          ? runConfirmedResearchRunner(webSearchTool, args, shellPaths)
+          : harnessTool.execute(runnerArgs(args));
+      }
       if (action === 'runs') return harnessTool.execute(runsArgs(args));
       if (action === 'run') return harnessTool.execute(runArgs(args));
       if (action === 'sources') return harnessTool.execute(sourcesArgs(args));

package/src/tools/agent-route-planner-candidates-surfaces.ts

@@ -119,7 +119,7 @@ if (browserControlLike(lower)) {
         'workspace action:"open" surfaceId:"connected-browser-cockpit" confirm:true explicitUserRequest:"..."',
         'host action:"services" query:"web" includeParameters:true',
       ],
-      policy: 'Browser/PWA readiness is read-only. Opening the connected browser cockpit is a visible confirmed handoff; browser-native Agent workspace receipts remain unpublished until the connected host provides them.',
+      policy: 'Browser/PWA readiness is read-only. Opening the connected browser cockpit is a visible confirmed handoff; browser-native Agent workspace routes count as ready only from certified SDK/daemon browser/PWA route and first-run receipt read models.',
     });
   }
 

package/src/version.ts

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 // The prebuild script updates the fallback value before compilation.
 // Uses import.meta.dir (Bun) to locate package.json relative to this file,
 // which is correct regardless of the process working directory.
-let _version = '1.2.0';
+let _version = '1.3.0';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8')) as {
     readonly version?: unknown;