@agwab/pi-workflow 0.1.1 → 0.2.0

package/docs/usage.md

@@ -187,20 +187,22 @@ A run prints a `workflow_*` id. Use that id for follow-up commands:
 
 The runtime task is not optional. `/workflow run <workflow>` and `/workflow dynamic` without task text fail before launch.
 
-### Run-scoped `fetch_content` cache
+### Run-scoped web-source cache
 
-Workflow tasks that use `fetch_content` share a run-scoped file cache by default. The cache is stored under the workflow run directory, for example:
+Prefer normalized workflow web tools in new workflows:
 
-```text
-.pi/workflows/<run-id>/source-cache/fetch-content/
-```
+- `workflow_web_search` returns compact candidate cards.
+- `workflow_web_fetch_source` caches one or more URLs and returns compact source cards with `sourceRef` values; pass `urls: [...]` or `sources: [{ url, title }]` to batch several fetches in one tool call.
+- `workflow_web_source_read` reads narrow exact/fuzzy/term-matched evidence snippets by `sourceRef`; pass `queries: [...]` or `reads: [...]` to batch several snippets from the same source in one tool call, or `claim` + distinctive `terms` when the exact quote is unknown. Term/claim reads return candidate metadata (`matchedTerms`, `missingTerms`, `coverageRatio`) rather than a proof verdict.
 
-The cache is only reused within the same workflow run, including resume/retry of that run. It is not reused across separate runs by default. Cache events are appended to that cache directory's `events.jsonl` with `hit`, `miss`, `write`, and `skip` records for telemetry and audit. To disable the cache for a run, set:
+The normalized cache is stored under the workflow run directory:
 
-```bash
-PI_WORKFLOW_FETCH_CONTENT_CACHE=0
+```text
+.pi/workflows/<run-id>/web-source-cache/
 ```
 
+Do not instruct agents to read that directory directly; source cards intentionally expose only opaque refs and short previews. The cache also writes an append-only index ledger plus same-URL fetch locks/negative-cache files so duplicate lookup and deterministic terminal failures can recover across parallel worker processes. Custom extension `fetch_content` providers are treated as trusted fetchers and are disabled under the default private-host policy; use the default safe fetch path or opt into trusted private-host behavior only for controlled providers. Legacy workflow tasks that still use `fetch_content` keep the older run-scoped file cache under `.pi/workflows/<run-id>/source-cache/fetch-content/`. Set `PI_WORKFLOW_FETCH_CONTENT_CACHE=0` to disable that legacy fetch cache for a run.
+
 Benchmark note: cache-enabled runs are a distinct cohort from older uncached runs. Do not compare wall-clock numbers directly unless the task set, model, and cache policy are controlled and recorded.
 
 ## Bundled workflows
@@ -209,7 +211,7 @@ Benchmark note: cache-enabled runs are a distinct cohort from older uncached run
 
 | Workflow | Required agents | Mode | Use when |
 |---|---|---|---|
-| `deep-research` | `researcher` | plan + foreach questions + normalize + foreach verifier + audit support + full audit reduce + deterministic executive render | Use when you need a grounded answer or summary based on source material. |
+| `deep-research` | `researcher` | plan + foreach questions + normalize-input packet support + normalize + foreach verifier + audit support + final-audit packet support + compact final synthesis reduce + deterministic ledger-backed executive render | Use when you need a grounded answer or summary based on source material. |
 | `deep-review` | `scout` | triage + foreach review lenses + dedup support + foreach devil's advocate + verdict-partition support + reduce | Use when you want code or design reviewed carefully from multiple angles. |
 | `spec-review` | `scout` | extract spec + map implementation + inspect tests -> reduce candidates -> foreach verifier -> reduce report | Use when you want to check whether requirements, an API spec, or a contract are reflected in the implementation and tests. |
 | `impact-review` | `scout` | scope/implementation/validation maps -> impact lenses -> consistency/regression/ship-readiness joins -> final synthesis | Use before merging or releasing a change to check affected areas, risks, missing tests, and missing docs. |
@@ -534,7 +536,7 @@ Authoring checklist:
 Workflow `tools` are still the child-worker allowlist. Entries can be strings:
 
 ```json
-{ "tools": ["read", "grep", "fetch_content"] }
+{ "tools": ["read", "grep", "workflow_web_search", "workflow_web_fetch_source", "workflow_web_source_read"] }
 ```
 
 or object specs for custom/local providers:
@@ -548,7 +550,7 @@ or object specs for custom/local providers:
       "extensions": ["packages/pi-scrapling-access"],
       "classification": "read-only",
       "optional": true,
-      "fallbackTools": ["fetch_content"]
+      "fallbackTools": ["workflow_web_fetch_source"]
     }
   ]
 }
@@ -569,10 +571,22 @@ Scope order is agent frontmatter fallback < `defaults.tools` < stage `tools`: th
 
 ## Web tools
 
-Workflows that use `web_search`, `fetch_content`, `get_search_content`, or
-`code_search` use the bundled `pi-web-access` dependency packaged with
-pi-workflow. The worker launcher injects that bundled extension automatically
-for those tools. Object-form custom tool `extensions` are merged with this
-built-in mapping and deduplicated for the subagent launch. Web calls can still
-fail when network access, provider credentials, browser state, or quota are
-unavailable; research workflows should report those limits instead of guessing.
+New workflows should use `workflow_web_search`, `workflow_web_fetch_source`, and
+`workflow_web_source_read`. These tools route through a workflow web-source
+adapter, return compact model-visible cards/snippets, and preserve full source
+text in a run-scoped cache when safe. Fetch accepts `urls: [...]` and
+`sources: [{ url, title }]` so agents can cache several source cards in one call.
+Source-read accepts `queries: [...]` and `reads: [...]` so agents can retrieve
+several snippets from one `sourceRef` in a single call, and accepts `claim` +
+distinctive `terms` for deterministic quote
+candidate harvesting when the exact quote is unknown. Term/claim matches are
+candidate evidence and include matched/missing term metadata; they are not a
+verdict by themselves. The bundled `pi-web-access` adapter remains
+available as the default compatibility provider for this release scope.
+
+Legacy workflows that use `web_search`, `fetch_content`, `get_search_content`, or
+`code_search` still use the bundled `pi-web-access` dependency packaged with
+pi-workflow. Object-form custom tool `extensions` are merged with built-in
+mappings and deduplicated for the subagent launch. Web calls can still fail when
+network access, provider credentials, browser state, or quota are unavailable;
+research workflows should report those limits instead of guessing.

package/node_modules/@agwab/pi-subagent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agwab/pi-subagent",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Minimal subagent runtime for Pi.",
   "type": "module",
   "private": false,

package/node_modules/@agwab/pi-subagent/src/api.ts

@@ -1,26 +1,45 @@
 import { resolve } from "node:path";
 import { loadAgentByName, type AgentDefinition } from "./agents.ts";
 import type { ResultEnvelope } from "./artifacts/index.ts";
-import type { ExecutionMode, ResolveInput, ResolvedBackend } from "./core/constants.ts";
+import type {
+	ExecutionMode,
+	ResolveInput,
+	ResolvedBackend,
+} from "./core/constants.ts";
 import { resolveBackend } from "./core/resolver.ts";
 import { validateResolveInput } from "./core/validation.ts";
-import { startAsyncParallelSubagentRuns, startAsyncSubagentRun } from "./orchestrate/async.ts";
-import { interruptRun, type InterruptRunOptions, type InterruptRunResult } from "./orchestrate/interrupt.ts";
-import { reconcileSubagentRun as reconcileRun, type ReconcileSubagentRunOptions as ReconcileRunOptions, type ReconcileSubagentRunResult } from "./orchestrate/reconcile.ts";
-import { runParallelSubagentTasks, runSubagentTask, type ParallelRunResult } from "./orchestrate/run.ts";
 import {
-  getRunLogs,
-  getRunStatus,
-  waitForRun,
-  type RunLogsSnapshot,
-  type RunStatusRef,
-  type RunStatusSnapshot,
-  type WaitForRunOptions,
-  type WaitForRunResult,
+	startAsyncParallelSubagentRuns,
+	startAsyncSubagentRun,
+} from "./orchestrate/async.ts";
+import {
+	interruptRun,
+	type InterruptRunOptions,
+	type InterruptRunResult,
+} from "./orchestrate/interrupt.ts";
+import {
+	reconcileSubagentRun as reconcileRun,
+	type ReconcileSubagentRunOptions as ReconcileRunOptions,
+	type ReconcileSubagentRunResult,
+} from "./orchestrate/reconcile.ts";
+import {
+	runParallelSubagentTasks,
+	runSubagentTask,
+	type ParallelRunResult,
+} from "./orchestrate/run.ts";
+import {
+	getRunLogs,
+	getRunStatus,
+	waitForRun,
+	type RunLogsSnapshot,
+	type RunStatusRef,
+	type RunStatusSnapshot,
+	type WaitForRunOptions,
+	type WaitForRunResult,
 } from "./orchestrate/status.ts";
 
 export interface RunSubagentOptions extends ResolveInput {
-  signal?: AbortSignal;
+	signal?: AbortSignal;
 }
 
 export type RunSubagentResult = ResultEnvelope | ParallelRunResult;
@@ -32,159 +51,253 @@ export type InterruptSubagentOptions = InterruptRunOptions;
 export type ReconcileSubagentOptions = ReconcileRunOptions;
 
 export class SubagentValidationError extends Error {
-  readonly failureKind = "validation" as const;
-  readonly backend?: ResolvedBackend;
-
-  constructor(message: string, backend?: ResolvedBackend) {
-    super(message);
-    this.name = "SubagentValidationError";
-    this.backend = backend;
-  }
+	readonly failureKind = "validation" as const;
+	readonly backend?: ResolvedBackend;
+
+	constructor(message: string, backend?: ResolvedBackend) {
+		super(message);
+		this.name = "SubagentValidationError";
+		this.backend = backend;
+	}
 }
 
-const AGENT_REQUEST_KEYS = ["agent", "task", "roleContext", "agentScope", "confirmProjectAgents"] as const;
+const AGENT_REQUEST_KEYS = [
+	"agent",
+	"task",
+	"roleContext",
+	"agentScope",
+	"confirmProjectAgents",
+] as const;
 
 interface AgentRequest {
-  agent: string;
-  cwd?: string;
-  agentScope?: ResolveInput["agentScope"];
-  confirmProjectAgents?: boolean;
+	agent: string;
+	cwd?: string;
+	agentScope?: ResolveInput["agentScope"];
+	confirmProjectAgents?: boolean;
 }
 
 function executionMode(input: ResolveInput): ExecutionMode {
-  if (input.mode !== undefined) return input.mode;
-  if (input.tasks !== undefined) return "parallel";
-  return "single";
+	if (input.mode !== undefined) return input.mode;
+	if (input.tasks !== undefined) return "parallel";
+	return "single";
 }
 
 function hasRunnableSingleInput(input: ResolveInput): boolean {
-  return AGENT_REQUEST_KEYS.some((key) => input[key] !== undefined);
+	return AGENT_REQUEST_KEYS.some((key) => input[key] !== undefined);
 }
 
 function agentRequests(input: ResolveInput): AgentRequest[] {
-  if (input.tasks !== undefined) {
-    return input.tasks
-      .filter((task): task is typeof task & { agent: string } => typeof task.agent === "string" && task.agent.length > 0)
-      .map((task) => ({
-        agent: task.agent,
-        cwd: task.cwd,
-        agentScope: task.agentScope ?? input.agentScope,
-        confirmProjectAgents: task.confirmProjectAgents ?? input.confirmProjectAgents ?? false,
-      }));
-  }
-  return typeof input.agent === "string" && input.agent.length > 0
-    ? [{ agent: input.agent, cwd: input.cwd, agentScope: input.agentScope, confirmProjectAgents: input.confirmProjectAgents ?? false }]
-    : [];
+	if (input.tasks !== undefined) {
+		return input.tasks
+			.filter(
+				(task): task is typeof task & { agent: string } =>
+					typeof task.agent === "string" && task.agent.length > 0,
+			)
+			.map((task) => ({
+				agent: task.agent,
+				cwd: task.cwd,
+				agentScope: task.agentScope ?? input.agentScope,
+				confirmProjectAgents:
+					task.confirmProjectAgents ?? input.confirmProjectAgents ?? false,
+			}));
+	}
+	return typeof input.agent === "string" && input.agent.length > 0
+		? [
+				{
+					agent: input.agent,
+					cwd: input.cwd,
+					agentScope: input.agentScope,
+					confirmProjectAgents: input.confirmProjectAgents ?? false,
+				},
+			]
+		: [];
 }
 
-async function assertProjectAgentApproval(input: ResolveInput, cwd: string): Promise<void> {
-  const projectAgents: AgentDefinition[] = [];
-  for (const request of agentRequests(input)) {
-    if (request.confirmProjectAgents === false || request.agentScope === "global") continue;
-    const requestCwd = resolve(cwd, request.cwd ?? ".");
-    const agent = await loadAgentByName(request.agent, requestCwd, request.agentScope);
-    if (agent?.source === "project" && !projectAgents.some((candidate) => candidate.sourcePath === agent.sourcePath)) {
-      projectAgents.push(agent);
-    }
-  }
-  if (projectAgents.length === 0) return;
-
-  const names = projectAgents.map((agent) => agent.displayName).join(", ");
-  const sources = projectAgents.map((agent) => agent.sourcePath).join("\n");
-  throw new SubagentValidationError(
-    `Project-local subagent definitions require explicit opt-in from code API callers. Set confirmProjectAgents:false only for trusted repositories. Agents: ${names}\nSources:\n${sources}`,
-  );
+async function assertProjectAgentApproval(
+	input: ResolveInput,
+	cwd: string,
+): Promise<void> {
+	const projectAgents: AgentDefinition[] = [];
+	for (const request of agentRequests(input)) {
+		if (
+			request.confirmProjectAgents === false ||
+			request.agentScope === "global"
+		)
+			continue;
+		const requestCwd = resolve(cwd, request.cwd ?? ".");
+		const agent = await loadAgentByName(
+			request.agent,
+			requestCwd,
+			request.agentScope,
+		);
+		if (
+			agent?.source === "project" &&
+			!projectAgents.some(
+				(candidate) => candidate.sourcePath === agent.sourcePath,
+			)
+		) {
+			projectAgents.push(agent);
+		}
+	}
+	if (projectAgents.length === 0) return;
+
+	const names = projectAgents.map((agent) => agent.displayName).join(", ");
+	const sources = projectAgents.map((agent) => agent.sourcePath).join("\n");
+	throw new SubagentValidationError(
+		`Project-local subagent definitions require explicit opt-in from code API callers. Set confirmProjectAgents:false only for trusted repositories. Agents: ${names}\nSources:\n${sources}`,
+	);
 }
 
-function validateRunnableInput(input: ResolveInput, backend: ResolvedBackend): void {
-  const mode = executionMode(input);
-  if (mode === "parallel") {
-    if (input.tasks === undefined || input.tasks.length === 0) {
-      throw new SubagentValidationError("parallel mode requires a non-empty tasks array.", backend);
-    }
-    return;
-  }
-
-  if (!hasRunnableSingleInput(input)) {
-    throw new SubagentValidationError(`${backend} execution requires agent/task input.`, backend);
-  }
-  if (input.task === undefined) {
-    throw new SubagentValidationError(`${backend} agent/task execution requires a non-empty task.`, backend);
-  }
+function validateRunnableInput(
+	input: ResolveInput,
+	backend: ResolvedBackend,
+): void {
+	const mode = executionMode(input);
+	if (mode === "parallel") {
+		if (input.tasks === undefined || input.tasks.length === 0) {
+			throw new SubagentValidationError(
+				"parallel mode requires a non-empty tasks array.",
+				backend,
+			);
+		}
+		return;
+	}
+
+	if (!hasRunnableSingleInput(input)) {
+		throw new SubagentValidationError(
+			`${backend} execution requires agent/task input.`,
+			backend,
+		);
+	}
+	if (input.task === undefined) {
+		throw new SubagentValidationError(
+			`${backend} agent/task execution requires a non-empty task.`,
+			backend,
+		);
+	}
 }
 
-function validateRunOptions(options: RunSubagentOptions): { input: ResolveInput; cwd: string; backend: ResolvedBackend; signal?: AbortSignal } {
-  const { signal, ...rawInput } = options;
-  const validation = validateResolveInput(rawInput);
-  if (!validation.ok) {
-    throw new SubagentValidationError(validation.failure.error, validation.failure.backend);
-  }
-
-  const resolved = resolveBackend(validation.input);
-  if (resolved.status === "failed") {
-    throw new SubagentValidationError(resolved.error, resolved.backend);
-  }
-
-  validateRunnableInput(validation.input, resolved.backend);
-  const cwd = resolve(validation.input.cwd ?? process.cwd());
-  return { input: validation.input, cwd, backend: resolved.backend, signal };
+function validateRunOptions(options: RunSubagentOptions): {
+	input: ResolveInput;
+	cwd: string;
+	backend: ResolvedBackend;
+	signal?: AbortSignal;
+} {
+	const { signal, ...rawInput } = options;
+	const validation = validateResolveInput(rawInput);
+	if (!validation.ok) {
+		throw new SubagentValidationError(
+			validation.failure.error,
+			validation.failure.backend,
+		);
+	}
+
+	const resolved = resolveBackend(validation.input);
+	if (resolved.status === "failed") {
+		throw new SubagentValidationError(resolved.error, resolved.backend);
+	}
+
+	validateRunnableInput(validation.input, resolved.backend);
+	const cwd = resolve(validation.input.cwd ?? process.cwd());
+	return { input: validation.input, cwd, backend: resolved.backend, signal };
 }
 
-export async function runSubagent(options: RunSubagentOptions): Promise<RunSubagentResult> {
-  const { input, cwd, backend, signal } = validateRunOptions(options);
-  await assertProjectAgentApproval(input, cwd);
-
-  try {
-    const mode = executionMode(input);
-    const asyncRequested = input.async === true || input.onComplete === "detach" || input.onComplete === "notify";
-    if (mode === "parallel") {
-      return asyncRequested ? await startAsyncParallelSubagentRuns(input, cwd, signal) : await runParallelSubagentTasks(input, cwd, signal);
-    }
-
-    if (asyncRequested) {
-      return await startAsyncSubagentRun({ input, cwd, backend, signal });
-    }
-
-    return await runSubagentTask({ input, cwd, signal });
-  } catch (error) {
-    if (typeof error === "object" && error !== null && (error as { failureKind?: unknown }).failureKind === "validation") {
-      throw new SubagentValidationError(error instanceof Error ? error.message : String(error));
-    }
-    throw error;
-  }
+export async function runSubagent(
+	options: RunSubagentOptions,
+): Promise<RunSubagentResult> {
+	const { input, cwd, backend, signal } = validateRunOptions(options);
+	await assertProjectAgentApproval(input, cwd);
+
+	try {
+		const mode = executionMode(input);
+		const asyncRequested =
+			input.async === true ||
+			input.onComplete === "detach" ||
+			input.onComplete === "notify";
+		if (mode === "parallel") {
+			return asyncRequested
+				? await startAsyncParallelSubagentRuns(input, cwd, signal)
+				: await runParallelSubagentTasks(input, cwd, signal);
+		}
+
+		if (asyncRequested) {
+			return await startAsyncSubagentRun({ input, cwd, backend, signal });
+		}
+
+		return await runSubagentTask({ input, cwd, signal });
+	} catch (error) {
+		if (
+			typeof error === "object" &&
+			error !== null &&
+			(error as { failureKind?: unknown }).failureKind === "validation"
+		) {
+			throw new SubagentValidationError(
+				error instanceof Error ? error.message : String(error),
+			);
+		}
+		throw error;
+	}
 }
 
-export async function getSubagentStatus(options: GetSubagentStatusOptions): Promise<RunStatusSnapshot | null> {
-  return await getRunStatus(options);
+export async function getSubagentStatus(
+	options: GetSubagentStatusOptions,
+): Promise<RunStatusSnapshot | null> {
+	return await getRunStatus(options);
 }
 
-export async function getSubagentLogs(options: GetSubagentLogsOptions): Promise<RunLogsSnapshot | null> {
-  return await getRunLogs(options);
+export async function getSubagentLogs(
+	options: GetSubagentLogsOptions,
+): Promise<RunLogsSnapshot | null> {
+	return await getRunLogs(options);
 }
 
-export async function waitForSubagent(options: WaitForSubagentOptions): Promise<WaitForRunResult> {
-  return await waitForRun(options);
+export async function waitForSubagent(
+	options: WaitForSubagentOptions,
+): Promise<WaitForRunResult> {
+	return await waitForRun(options);
 }
 
-export async function interruptSubagent(options: InterruptSubagentOptions): Promise<InterruptRunResult> {
-  return await interruptRun(options);
+export async function interruptSubagent(
+	options: InterruptSubagentOptions,
+): Promise<InterruptRunResult> {
+	return await interruptRun(options);
 }
 
-export async function reconcileSubagentRun(options: ReconcileSubagentOptions): Promise<ReconcileSubagentRunResult> {
-  return await reconcileRun(options);
+export async function reconcileSubagentRun(
+	options: ReconcileSubagentOptions,
+): Promise<ReconcileSubagentRunResult> {
+	return await reconcileRun(options);
 }
 
 export type {
-  ArtifactRef,
-  CompletionMetadata,
-  ResultEnvelope,
-  ResultSandbox,
-  ResultTmuxMetadata,
-  ResultWorkspace,
-  WorktreeCleanupStatus,
+	ArtifactRef,
+	CompletionMetadata,
+	ResultEnvelope,
+	ResultMetadata,
+	ResultSandbox,
+	ResultSessionDisposition,
+	ResultSessionMetadata,
+	ResultSessionReason,
+	ResultTmuxMetadata,
+	ResultWorkspace,
+	WorktreeCleanupStatus,
 } from "./artifacts/index.ts";
-export type { AsyncDependency, Backend, ExecutionMode, FailureKind, ResolvedBackend, Status } from "./core/constants.ts";
+export type {
+	AsyncDependency,
+	Backend,
+	ExecutionMode,
+	FailureKind,
+	ResolvedBackend,
+	Status,
+} from "./core/constants.ts";
 export type { InterruptRunResult } from "./orchestrate/interrupt.ts";
 export type { ReconcileSubagentRunResult } from "./orchestrate/reconcile.ts";
 export type { ParallelRunResult } from "./orchestrate/run.ts";
-export type { RunLogRef, RunLogsSnapshot, RunStatusRef, RunStatusSnapshot, RunTaskStatusSnapshot, WaitForRunResult } from "./orchestrate/status.ts";
+export type {
+	RunLogRef,
+	RunLogsSnapshot,
+	RunStatusRef,
+	RunStatusSnapshot,
+	RunTaskStatusSnapshot,
+	WaitForRunResult,
+} from "./orchestrate/status.ts";