flowviant 0.125.20 → 0.125.21

package/bin/lib/websiteAccess.mjs

@@ -0,0 +1,68 @@
+/** Bounded website metadata only. Neither assistant prose nor page bodies are
+ * evidence of a loaded page. Browser integrations supply explicit observations
+ * through result metadata, never by embedding claims in a tool input. */
+import { scrubCut } from './uplinkScrub.mjs';
+import { REFERENCE_DIAGNOSTICS } from './publicReferenceProtocol.mjs';
+
+export function websiteUrl(value, scrub = s => s) {
+  if (typeof value !== 'string' || value.length > 8_192) return undefined;
+  try {
+    // Scrub before URL serialization can escape a known secret in its path.
+    const url = new URL(scrub(value));
+    if (!['http:', 'https:'].includes(url.protocol)) return undefined;
+    url.username = ''; url.password = ''; url.search = ''; url.hash = '';
+    return scrub(url.href).slice(0, 500);
+  } catch { return undefined; }
+}
+
+export function websiteRequest(name, input, scrub) {
+  const method = name === 'WebSearch' ? 'search' : name === 'WebFetch' ? 'fetch' :
+    name === 'WebsiteAccess' ? (['search', 'fetch', 'browser', 'tool', 'capability'].includes(input.method) ? input.method : 'tool') :
+    /^(?:mcp__|[^.]+\.)/.test(name ?? '') && websiteUrl(input?.url) ? 'tool' : null;
+  if (!method) return null;
+  const requestedUrl = websiteUrl(input?.url, scrub);
+  return {
+    method, tool: scrubCut(name === 'WebsiteAccess' ? input.tool ?? 'website' : name, 120, scrub),
+    ...(requestedUrl ? { requestedUrl } : {}), access: 'unknown',
+  };
+}
+
+/** Only fixed, recognized runtime errors can leave the machine. Never retain
+ * arbitrary tool output, even when is_error is set by the native runtime. */
+export function observeWebsite(e, meta, scrub) {
+  const w = e.website;
+  const output = scrubCut(meta.output ?? '', 16_384, scrub);
+  const lines = output.split('\n', 80);
+  const diagnostic = lines.find(line => Object.values(REFERENCE_DIAGNOSTICS).includes(line) || /^(?:Error: )?(?:MCP tool call requires approval, but approval policy is never|Tool (?:WebFetch|WebSearch) is not available|Browser executable not found|Browser sandbox unavailable|Request timed out|fetch failed|Network request failed|Not accessible via this tool)\.?$/i.test(line) || line.startsWith('flowviant: this turn is read-only, so '));
+  const failed = meta.isError === true || (Number.isSafeInteger(meta.exitCode) && meta.exitCode !== 0);
+  w.access = failed ? 'failed' : 'unknown';
+  if (failed && diagnostic) {
+    e.errorMessage = diagnostic.slice(0, 500);
+    if (diagnostic.length > 500) e.errorTruncated = true;
+    if (/^flowviant:/.test(diagnostic)) {
+      w.access = 'permission_denied'; w.permissionSource = 'flowviant';
+    } else if (/requires approval/.test(diagnostic)) {
+      w.access = 'permission_denied'; w.permissionSource = 'runtime';
+    } else if (/not available|not found|sandbox unavailable/i.test(diagnostic)) w.access = 'unavailable';
+  }
+  // Explicit daemon-owned integration result, not a tool-input or prose field.
+  // This is the emission seam used by the isolated browser/capture consumers.
+  const observed = meta.website;
+  if (meta.result) w.observedAt = new Date().toISOString();
+  if (meta.result && observed && typeof observed === 'object') {
+    if (['unknown', 'loaded', 'search_results', 'failed', 'unavailable', 'permission_denied', 'challenge', 'partial'].includes(observed.access)) w.access = observed.access;
+    const finalUrl = websiteUrl(observed.finalUrl, scrub);
+    if (finalUrl) w.finalUrl = finalUrl;
+    if (Number.isInteger(observed.httpStatus) && observed.httpStatus >= 100 && observed.httpStatus <= 599) w.httpStatus = observed.httpStatus;
+    if (['flowviant', 'runtime', 'unknown'].includes(observed.permissionSource)) w.permissionSource = observed.permissionSource;
+    if (['advertised', 'unavailable', 'unknown'].includes(observed.availability)) w.availability = observed.availability;
+    if (typeof observed.observedAt === 'string') w.observedAt = scrubCut(observed.observedAt, 40, scrub);
+  }
+  // Search completion is evidence of a search, never of opening its hits.
+  if (w.method === 'search' && w.access === 'unknown' && !failed && meta.result && meta.toolSuccess === true) w.access = 'search_results';
+  if (w.method === 'search' && w.access === 'loaded') w.access = 'unknown';
+  if (!meta.result) w.access = 'unknown';
+  e.outcome = !meta.result ? 'unknown' : ['failed', 'unavailable', 'permission_denied'].includes(w.access) ? 'failed' :
+    failed ? 'failed' : meta.toolSuccess === true || ['loaded', 'search_results', 'challenge', 'partial'].includes(w.access) ? 'success' : 'unknown';
+  if (e.outcome === 'failed') e.errorCategory = w.access === 'permission_denied' ? 'denied' : w.access === 'unavailable' ? 'unavailable_tool' : 'tool_error';
+}

package/bin/lib/websiteTrace.mjs

@@ -0,0 +1,36 @@
+import { createToolLog } from './workToolLog.mjs';
+import { createHash } from 'node:crypto';
+
+/** Reuse the turn collector for agent research too. Trace entries are snapshots:
+ * later results must not mutate a request already queued or sent. */
+export function createWebsiteTrace(cwd, trace, attributed) {
+  const { pushToolEvent } = createToolLog(cwd);
+  const inventory = new Map();
+  const emit = (event, owner) => {
+    const send = id => trace.tool(event, id);
+    if (owner && attributed) attributed(owner, send); else send(owner);
+  };
+  return (name, input, meta = {}) => {
+    const e = pushToolEvent(name, input, meta);
+    if (!e?.website) return false;
+    const event = structuredClone(e);
+    if (event.id) {
+      // The trace scopes/caps ids. Hash the complete native identity first so
+      // long child prefixes cannot hide the call id at that boundary.
+      const id = createHash('sha256').update(JSON.stringify([meta.agentId ?? null, event.id])).digest('hex');
+      event.id = trace.agentId(`web:${id}`);
+    }
+    // Startup inventory belongs beside a reference attempt, not in every
+    // coding turn. An actual unavailable/denied capability result still emits
+    // immediately, even if no request can follow it.
+    if (event.website.method === 'capability' && !event.website.requestedUrl && event.website.access === 'unknown') {
+      inventory.set(event.website.tool, { event, owner: meta.agentId });
+      if (inventory.size > 12) inventory.delete(inventory.keys().next().value);
+      return true;
+    }
+    for (const pending of inventory.values()) emit(pending.event, pending.owner);
+    inventory.clear();
+    emit(event, meta.agentId);
+    return true;
+  };
+}

package/bin/lib/work.mjs

@@ -428,6 +428,7 @@ export function createWorkManager({
     publishAgentBranch, stopAgentPublishing,
     admit,
     workChildren,
+    groupKillChildren,
     agentPublished,
     agentRemoteAt,
     fetchAgentFiles,

package/bin/lib/workAgentTools.mjs

@@ -31,7 +31,7 @@ import { ORCHESTRATOR_SERVER } from './orchestratorProtocol.mjs';
  *  agent calls them: a multi-repository card's add_repository, and an
  *  orchestrated card's routing. Never a project server's, whatever the base
  *  `.mcp.json` names. */
-export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositories', orchestrator: ORCHESTRATOR_SERVER });
+export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositories', orchestrator: ORCHESTRATOR_SERVER, uiReview: 'card_ui_review' });
 
 /**
  * The card turn's tools, prepared, and what it is told of them.
@@ -44,7 +44,7 @@ export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositorie
  * from here), the note, the mount's part of the CLI's `mcpEnv` and whether it
  * needs one, and the keys the runner takes the mount as.
  */
-export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources = [], repositoryTool = null, orchestratorConfig = null, orchestrated = false, codexHome = null, env = process.env, machineServers = machineMcpServers }) {
+export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources = [], repositoryTool = null, orchestratorConfig = null, uiReviewConfig = null, orchestrated = false, codexHome = null, env = process.env, machineServers = machineMcpServers }) {
   // A turn reads the base ref afresh. Changes the agent has made to its
   // own worktree cannot silently change the next turn's tools.
   const source = sources.find((r) => r.wt === wt);
@@ -56,6 +56,7 @@ export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources =
   const projectTools = prepareAgentTools(snapshot, rt, env, wt, { codexHome, fenced: posture !== 'build', turnServers: {
     ...(repositoryTool ? { [CARD_TURN_SERVERS.repositories]: repositoryTool.config } : {}),
     ...(orchestratorConfig ? { [CARD_TURN_SERVERS.orchestrator]: orchestratorConfig } : {}),
+    ...(posture === 'build' && uiReviewConfig ? { [CARD_TURN_SERVERS.uiReview]: uiReviewConfig } : {}),
   } });
   try {
     const mountsProjectMcp = TURN_PROFILES[posture]?.projectMcp === true && runnerToolCapabilities(rt).mcp;

package/bin/lib/workAgentTurnExecution.mjs

@@ -1,5 +1,6 @@
 import { reportLocalCleanup } from './localCleanupReport.mjs';
 import { createManagedLocalCleanup } from './managedLocalCleanup.mjs';
+import { createCaptureRetention } from './referenceCaptures.mjs';
 import { imageRevisionInstructions } from './artifactIteration.mjs';
 import { agentChildScope } from './agentQueueContext.mjs';
 import { measureTestFindings } from './testFindings.mjs';
@@ -45,6 +46,7 @@ import { scrub as envScrub } from './uplinkScrub.mjs';
 import { canRun, runtimeById } from './runtimes.mjs';
 import { toolEventOf, CLAUDE_TOOL_PROSE_KINDS, scrubNativeText } from './runtimeEvents.mjs';
 import { makeTraceRelay } from './trace.mjs';
+import { createWebsiteTrace } from './websiteTrace.mjs';
 import { prepareCardTools } from './workAgentTools.mjs';
 import { runTurnResumingOnce } from './resumeLost.mjs';
 import { runAgentWithInternalWaits } from './agentInternalWait.mjs';
@@ -64,6 +66,8 @@ import { knownCodexModels } from './runtimeOfferings.mjs';
 import { codexSubagentsSafe } from './runtimeCodex.mjs';
 import { measuredRuntimeVersion } from './runtimeDetection.mjs';
 import { createIntermediateArtifacts } from './intermediateArtifacts.mjs';
+import { createUiReview } from './uiReview.mjs';
+import { withUiReview, appendUiReviewEvidence } from './uiReviewTurn.mjs';
 
 export function createAgentTurnExecution({
   admit,
@@ -83,6 +87,7 @@ export function createAgentTurnExecution({
   runReviewEntry,
   runMergeCheck,
   workChildren,
+  groupKillChildren,
   agentChildren,
   postAgentTrace,
   postAgentActivity,
@@ -92,6 +97,7 @@ export function createAgentTurnExecution({
   makeLiveMessages = createLiveMessages,
   runTurnImpl = runTurn,
   exportModel,
+  makeUiReview = createUiReview,
 }) {
   const reportDelivery = createDeliveryReporter();
   /** How long the final flush may hold the settle. Bounded because the settle
@@ -359,6 +365,9 @@ export function createAgentTurnExecution({
      * CLAUDE_TOOL_PROSE_KINDS.
      */
     const doubledKinds = runtimeById(rt)?.parse ? null : CLAUDE_TOOL_PROSE_KINDS;
+    const websiteTrace = createWebsiteTrace(wt, trace, (id, emit) => {
+      if (orchestrator) orchestrator.attributed(id, emit); else emit(id);
+    });
 
     /**
      * WHICH BRAIN THIS CONTAINER WAS PINNED TO — the same `brainFor` the tab
@@ -392,7 +401,14 @@ export function createAgentTurnExecution({
     const spawnedChildren = new Set();
     /** The CLI, unless a person already asked to stop this turn (Interrupt
      *  now): then nothing starts — no fresh retry, no continuation. */
-    const runCli = (args) => (run.interrupted ? Promise.resolve('') : runTurnImpl(args));
+    let uiReview = null;
+    let uiReviewNote = '';
+    let uiReviewEvidence = '';
+    const runCli = (args) => {
+      if (run.interrupted) return Promise.resolve('');
+      args = withUiReview(args, uiReviewNote, uiReview?.env);
+      return runTurnImpl(args);
+    };
     /**
      * WHAT THIS TURN SPENT, AS THE CLI COUNTED IT (2026-09-19).
      *
@@ -440,6 +456,18 @@ export function createAgentTurnExecution({
     let orchestrator = null;
     let intermediateDelivery = null;
     try {
+      if (posture === 'build' && job.kind !== 'merge_resolve') {
+        try {
+          uiReview = await makeUiReview({ wt, signal: setupController.signal, onChild: ch => {
+            workChildren.set(ch, agentId); groupKillChildren?.add(ch);
+            return () => { workChildren.delete(ch); groupKillChildren?.delete(ch); };
+          } });
+          uiReviewNote = uiReview.instructions;
+        } catch (error) {
+          uiReviewNote = `Local UI self-review is unavailable: ${envScrub(error.message)}. Report browser, image and interaction checks as unrun with this reason when relevant; do not install tools or weaken isolation.`;
+          uiReviewEvidence = uiReviewNote;
+        }
+      }
       if (orchestrating) {
         orchestrator = await createOrchestrator({ turnId, runtime: rt, trace, admit,
           assignmentContext: () => agentChildScope(job),
@@ -450,7 +478,7 @@ export function createAgentTurnExecution({
           notify: message => liveInput ? run.live?.inject(message) === true : false,
           taken: id => run.live?.onTaken(id) });
       }
-      const tools = prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources: repositoryRun?.sources ?? [], repositoryTool: repositoryRun?.tool ?? null, orchestratorConfig: orchestrator?.config ?? null, orchestrated: Boolean(orchestrator), codexHome: agentResume.codexHome });
+      const tools = prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources: repositoryRun?.sources ?? [], repositoryTool: repositoryRun?.tool ?? null, orchestratorConfig: orchestrator?.config ?? null, uiReviewConfig: uiReview?.config, orchestrated: Boolean(orchestrator), codexHome: agentResume.codexHome });
       projectTools = tools.projectTools;
       localCleanup?.begin(turnId);
       const { toolsNote } = tools;
@@ -468,6 +496,9 @@ export function createAgentTurnExecution({
         })) } : {}),
         // The kickoff and the system prompt, composed by the agent lane's
         // shape (workAgentTurnShape.mjs) from what this run measured.
+        signal: setupController.signal,
+        onReferenceCapture: createCaptureRetention({ report: (files, { placeDir }) => artifacts.report({ placeDir, before: new Map(), agentId, turnId, requireStored: true, referenceCapture: true,
+          includeNames: new Set(files.map(f => f.name)), requiredOutputs: files.map(({ name, sha256 }) => ({ name, sha256 })) }) }),
         researchHandoff: job.researchHandoff,
         resultInputs: job.resultInputs,
         intermediateFiles,
@@ -583,6 +614,7 @@ export function createAgentTurnExecution({
         // the builder itself (bounded window BEFORE its caps; see
         // toolEventOf). A tool it does not know pushes nothing.
         onToolEvent: (name, input, meta) => {
+          if (websiteTrace(name, input, meta)) return;
           if (meta?.agentId) {
             if (!meta.result) {
               const event = toolEventOf(name, input, wt, envScrub);
@@ -698,6 +730,14 @@ export function createAgentTurnExecution({
       // answer is scrubbed; then it can leave the machine's secret set.
       out = envScrub(out);
       if (lastAnswer) lastAnswer = envScrub(lastAnswer);
+      // The builder has finished its fix/recheck loop. Close only resources
+      // owned by its review tool, then bind evidence to the final source
+      // before the existing artifact upload and delivery settlement.
+      try { await uiReview?.close(); }
+      finally {
+        try { uiReviewEvidence = uiReview?.finalize() ?? uiReviewEvidence; }
+        catch (error) { uiReviewEvidence = `Local UI review final source/evidence measurement unavailable: ${envScrub(error.message)}. Earlier checks do not establish the final source.`; }
+      }
       await run.live?.stop();
       await orchestrator?.close(run.interrupted);
       await brief?.stop();
@@ -804,6 +844,7 @@ export function createAgentTurnExecution({
       wt,
       modelExports: intermediateDelivery?.modelExports,
     });
+    appendUiReviewEvidence(body, uiReviewEvidence);
     if (body.outcome === 'delivered') intermediateDelivery?.commit();
     // This place's writer lock is still held. Measure the exited children
     // and their groups before releasing any file requirements. Dirty repository files are unrelated to managed scratch eligibility.

package/bin/lib/workAgentTurns.mjs

@@ -53,6 +53,7 @@ export function createWorkAgentTurns({
   stopAgentPublishing = () => {},
   admit,
   workChildren,
+  groupKillChildren,
   agentPublished,
   agentRemoteAt,
   /** The turn's files, fetched into its worktree (workAttachments.mjs, 0.112.0). */
@@ -138,6 +139,7 @@ export function createWorkAgentTurns({
     runMergeCheck,
     exportModel,
     workChildren,
+    groupKillChildren,
     agentChildren,
     postAgentTrace,
     postAgentActivity,

package/bin/lib/workToolLog.mjs

@@ -9,6 +9,7 @@
  */
 import { toolEventOf } from './runtimeEvents.mjs';
 import { scrubCut, scrub as envScrub } from './uplinkScrub.mjs';
+import { observeWebsite } from './websiteAccess.mjs';
 
 /**
  * THE TURN'S TOOL LOG — the structured relay behind the transcript's
@@ -47,7 +48,15 @@ export function createToolLog(cwd) {
     e.outcome = !meta.result ? 'unknown' : failed ? 'failed' :
       meta.runtime === 'codex' && code === undefined ? 'unknown' : 'success';
     if (code !== undefined) e.exitCode = code;
-    if (failed) {
+    if (e.website) {
+      observeWebsite(e, meta, envScrub);
+      if (e.errorTruncated) toolLog.state = 'partial';
+    }
+    if (e.outcome === 'failed') {
+      if (e.website) {
+        if (!toolLog.firstFailure) { toolLog.firstFailure = structuredClone(e); toolLog.recovery = []; }
+        return;
+      }
       const output = scrubCut(meta.output ?? '', 16_384);
       const guardAt = output.indexOf('flowviant: this turn is read-only, so ');
       const guard = guardAt >= 0 ? output.slice(guardAt).split('\n', 1)[0] : undefined;
@@ -67,8 +76,19 @@ export function createToolLog(cwd) {
   };
   const pushToolEvent = (name, input, meta = {}) => {
     const id = typeof meta.id === 'string' && meta.id && meta.id.length <= 160 ? meta.id : undefined;
-    const existing = id && correlated.get(id);
+    const key = id && JSON.stringify([meta.agentId ?? null, id]);
+    const existing = key && correlated.get(key);
     if (existing) {
+      // Codex may only name the web action/URL on completion. Enrich that
+      // same native request instead of keeping its provisional search label.
+      if (existing.website && name) {
+        const request = toolEventOf(name, input, cwd, envScrub)?.website;
+        if (request) {
+          existing.website.method = request.method;
+          existing.website.tool = request.tool;
+          if (request.requestedUrl) existing.website.requestedUrl = request.requestedUrl;
+        }
+      }
       if (meta.result) observe(existing, meta);
       refresh();
       return existing;
@@ -87,7 +107,7 @@ export function createToolLog(cwd) {
     if (typeof meta.agentId === 'string' && meta.agentId) e.agentId = scrubCut(meta.agentId, 160);
     if (e.agentId && typeof meta.agentTitle === 'string' && meta.agentTitle) e.agentTitle = scrubCut(meta.agentTitle, 120);
     if (e.t !== 'plan') {
-      if (id) { e.id = scrubCut(id, 160); correlated.set(id, e); }
+      if (id) { e.id = scrubCut(id, 160); correlated.set(key, e); }
       if (name === 'Read') for (const key of ['offset', 'limit']) {
         if (Number.isSafeInteger(input?.[key]) && input[key] >= 0) e[key] = input[key];
       }
@@ -115,6 +135,7 @@ export function createToolLog(cwd) {
         last.errorCategory === e.errorCategory &&
         last.offset === e.offset && last.limit === e.limit &&
         last.t === e.t &&
+        !e.website && !last.website &&
         last.p === e.p &&
         last.q === e.q &&
         last.c === e.c;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.125.20",
+  "version": "0.125.21",
   "description": "Run your own coding CLIs as build agents for Flowviant \u2014 Claude Code, Codex or Antigravity, on your own credentials. Holds your sessions, keeps a worktree per tab, and ships branches on your word.",
   "type": "module",
   "bin": {