@agwab/pi-workflow 0.1.0 → 0.1.2

package/README.md

@@ -12,7 +12,9 @@
 
 `pi-workflow` lets Pi run named, repeatable multi-step workflows: research, code review, spec conformance checks, impact review, and project-specific team routines.
 
-You choose a workflow and describe the task in natural language. `pi-workflow` coordinates the steps, passes results between them, and records the run so it can be inspected or resumed.
+Built on [`@agwab/pi-subagent`](https://github.com/AgwaB/pi-subagent), it coordinates Pi subagent workers across workflow steps, passes results between them, and records the run so it can be inspected or resumed.
+
+You choose a workflow and describe the task in natural language.
 
 ## Installation
 
@@ -169,7 +171,7 @@ Parallel execution is a graph shape, not a stage type: model parallel branches a
 
 Dynamic workflows are the advanced form of adaptive orchestration. A JSON `type: "dynamic"` stage points at trusted bundle-local `.mjs` controller code; that controller can add official workflow tasks, call helpers, or run nested workflows while preserving replayable run state. See [`docs/usage.md`](./docs/usage.md) for approval, detach, helper retry, nested workflow, and cache details.
 
-Workflow `fetch_content` calls use a run-scoped file cache by default under `.pi/workflows/<run-id>/source-cache/fetch-content/`. Set `PI_WORKFLOW_FETCH_CONTENT_CACHE=0` to opt out.
+New workflows should prefer `workflow_web_search`, `workflow_web_fetch_source`, and `workflow_web_source_read`: search returns compact candidates, fetch returns a source card with an opaque `sourceRef`, and source-read retrieves narrow evidence snippets. Preserve `sourceRef` through workflow outputs; use `urls: [...]` or `sources: [...]` to batch several source fetches, use `queries: [...]` or `reads: [...]` to batch several snippets from one sourceRef, and use `claim` + distinctive `terms` to get candidate quote windows with match metadata when the exact quote is unknown. Normalized web sources are cached under `.pi/workflows/<run-id>/web-source-cache/` without exposing cache paths to agents; same-URL fetches and deterministic terminal failures are coordinated across parallel workers. Legacy `fetch_content` calls still use `.pi/workflows/<run-id>/source-cache/fetch-content/`; set `PI_WORKFLOW_FETCH_CONTENT_CACHE=0` to opt out of that legacy cache.
 
 ## Predefined workflows
 
@@ -214,5 +216,14 @@ Open a task detail view with its artifact output.
 
 ## More
 
-- [`docs/usage.md`](./docs/usage.md) — command reference, workflow resolution, run artifacts, authoring rules, and release checks.
+- [`docs/usage.md`](./docs/usage.md) — command reference, workflow resolution, run artifacts, and authoring rules.
 - [`workflows/README.md`](./workflows/README.md) — bundled workflow notes.
+
+## Runtime dependencies
+
+`pi-workflow` bundles the runtime pieces it needs:
+
+- [`@agwab/pi-subagent`](https://github.com/AgwaB/pi-subagent) launches and tracks the Pi subagent workers used by workflow tasks.
+- [`pi-web-access`](https://github.com/nicobailon/pi-web-access) provides web tools such as `web_search`, `fetch_content`, `get_search_content`, and `code_search` when a workflow or agent requests them.
+
+The web provider is just a tool provider. You can replace or narrow it with your own extension if it exposes compatible tool names, arguments, and results. Be careful when changing providers: if the tool result shape, reference/evidence formatting, or field names differ, workflow specs, prompts, and control/output schemas that depend on those fields may need to change too. The stage graph and normal workflow run record format do not need to change for a compatible web-tool implementation swap.

package/agents/researcher.md

@@ -1,7 +1,7 @@
 ---
 name: researcher
 description: Read-only source-backed research agent.
-tools: read, grep, find, ls, web_search, fetch_content
+tools: read, grep, find, ls, workflow_web_search, workflow_web_fetch_source, workflow_web_source_read, web_search, fetch_content
 readOnly: true
 ---
 
@@ -28,12 +28,22 @@ evidence beyond the repository's immediate code.
 
 - Use `read`, `grep`, `find`, and `ls` for local files, vendored docs,
   package metadata, and downloaded/reference material already on disk.
-- Use `web_search` to discover candidate sources across papers, docs,
-  articles, issues, and community discussions.
-- Use `fetch_content` to extract ordinary URLs.
-- Full cached search-content hydration is intentionally unavailable in
-  autonomous workflows; if source extraction is insufficient, report the
-  evidence gap instead of broad raw document retrieval.
+- Prefer `workflow_web_search` to discover candidate sources across papers,
+  docs, articles, issues, and community discussions.
+- Prefer `workflow_web_fetch_source` to cache URLs and return compact source
+  cards, then use `workflow_web_source_read` for exact evidence snippets. Preserve
+  `sourceRef` values in structured outputs. When several source cards are needed,
+  batch fetches with `urls: [...]` or `sources: [...]`; when several snippets are
+  needed from one `sourceRef`, batch them with `queries: [...]` or `reads: [...]`
+  instead of making repeated source-read calls. If the exact quote text is not
+  known, pass `claim` plus 2-6 distinctive `terms` so the tool can harvest a
+  candidate source window before trying another source. Treat term/claim matches
+  as candidate evidence; preserve `matchType`, `matchedTerms`, `missingTerms`,
+  `coverageRatio`, and `candidateOnly` when citing them.
+- Do not read workflow web-source cache files directly; use source refs and
+  `workflow_web_source_read` instead.
+- Legacy `web_search` and `fetch_content` may be available during migration;
+  use them only when normalized workflow web tools are unavailable.
 - If network access, credentials, provider quota, or the web extension is
   unavailable, report that limitation instead of guessing.
 

package/dist/artifact-graph-runtime.js

@@ -665,6 +665,7 @@ export function formatArtifactGraphSourceContext(sources, requiredReads) {
     return [
         "# Workflow Artifact Inputs",
         "Use workflow_artifact to list/read upstream workflow artifacts. Inline controlProjection fields are authoritative for the projected data they contain; use artifact reads for declared requiredReads, missing fields, or debug detail.",
+        "Projected reads must include a JSON path when using maxItems or maxChars, for example {\"action\":\"read\",\"source\":\"plan\",\"artifact\":\"control\",\"path\":\"$.factSlots\",\"maxItems\":8,\"maxChars\":2000}. For a whole artifact read, omit maxItems/maxChars.",
         requiredReads.length > 0
             ? [
                 "Required reads before final output:",

package/dist/compiler.js

@@ -2,7 +2,7 @@ import { readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { loadAgentByName } from "./agents.js";
 import { DYNAMIC_OUTPUT_PROFILES } from "./dynamic-profiles.js";
-import { classifyToolCapability, effectiveToolClassification, providersForSelectedTools, resolveToolSelection, TOOL_NAME_PATTERN, toolNameForSpec, } from "./tool-metadata.js";
+import { classifyToolCapability, effectiveToolClassification, providersForSelectedTools, resolveToolSelection, TOOL_NAME_PATTERN, toolAllowedByAuthorityCeiling, toolNameForSpec, } from "./tool-metadata.js";
 import { WorkflowValidationError, WORKFLOW_RUN_TYPE, } from "./types.js";
 const DELEGATION_TOOLS = new Set([
     "skill_test_subagent",
@@ -207,7 +207,7 @@ function validateToolSubset(requestedTools, agent, issues, path) {
     }
     const allowed = new Set(agent.tools);
     for (const tool of requestedTools) {
-        if (!allowed.has(tool)) {
+        if (!toolAllowedByAuthorityCeiling(tool, allowed)) {
             issues.push({
                 path,
                 message: `tool "${tool}" expands agent ${agent.displayName}; allowed tools: ${agent.tools.join(", ")}`,

package/dist/dynamic-generated-task-runtime.js

@@ -5,7 +5,7 @@ import { isDynamicOutputProfile, } from "./dynamic-profiles.js";
 import { readOrRebuildDynamicState } from "./dynamic-state.js";
 import { sanitizeTaskId } from "./engine-run-graph.js";
 import { fromProjectPath, isTerminalTaskStatus, readJson } from "./store.js";
-import { classifyToolCapability, effectiveToolClassification, providersForSelectedTools, } from "./tool-metadata.js";
+import { classifyToolCapability, effectiveToolClassification, providersForSelectedTools, toolAllowedByAuthorityCeiling, } from "./tool-metadata.js";
 const DYNAMIC_OUTPUT_MAX_DIGEST_CHARS = 1000;
 const DYNAMIC_DELEGATION_TOOLS = new Set([
     "skill_test_subagent",
@@ -57,7 +57,8 @@ export async function buildDynamicGeneratedCompiledTask(input) {
         throw new Error(`dynamic agent ${requestedAgent} does not declare a tools authority ceiling`);
     }
     if (tools && agentDefinition.tools) {
-        const missing = tools.filter((tool) => !agentDefinition.tools?.includes(tool));
+        const allowed = new Set(agentDefinition.tools);
+        const missing = tools.filter((tool) => !toolAllowedByAuthorityCeiling(tool, allowed));
         if (missing.length > 0) {
             throw new Error(`dynamic agent requested tools not declared by ${requestedAgent}: ${missing.join(", ")}`);
         }
@@ -571,7 +572,7 @@ function appendDynamicOutputInstructions(prompt, outputProfile, maxDigestChars =
         `The control.digest string must be at most ${maxDigestChars} characters; prefer one short sentence.`,
         "Use schema `dynamic-task-result-v1` unless the dynamic controller asks for a more specific control schema.",
         refsMinItems !== undefined && refsMinItems > 0
-            ? `The <refs> JSON array must include at least ${refsMinItems} item${refsMinItems === 1 ? "" : "s"}. Include URLs or local file paths used by the analysis. Verify external URLs with fetch_content before including them; do not include stale, guessed, or unreachable URLs.`
+            ? `The <refs> JSON array must include at least ${refsMinItems} item${refsMinItems === 1 ? "" : "s"}. Include URLs or local file paths used by the analysis. Verify external URLs with available workflow web fetch/source-read tools before including them; do not include stale, guessed, or unreachable URLs.`
             : undefined,
         dynamicOutputProfileInstructions(outputProfile),
     ]

package/dist/dynamic-runtime-bundle.js

@@ -7,8 +7,9 @@ const DIRECT_DYNAMIC_RUNTIME_TOOLS = [
     "grep",
     "find",
     "ls",
-    "web_search",
-    "fetch_content",
+    "workflow_web_search",
+    "workflow_web_fetch_source",
+    "workflow_web_source_read",
 ];
 export async function ensureDirectDynamicRuntimeBundle(cwd) {
     const bundleDir = join(cwd, ".pi", "workflow-runtime", DIRECT_DYNAMIC_RUNTIME_VERSION);

package/dist/extension.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { closeSync, openSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { discoverAgents } from "./agents.js";
@@ -15,6 +15,7 @@ import { listWorkflows, resolveWorkflowRef } from "./workflow-specs.js";
 import { WorkflowValidationError, } from "./types.js";
 const UNFINISHED_RUN_NOTICE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 const UNFINISHED_RUN_NOTICE_MAX_RUNS = 5;
+const UNFINISHED_RUN_NOTICE_DEDUPE_MS = 6 * 60 * 60 * 1000;
 const RUN_FEEDBACK_POLL_MS = 2_000;
 const runFeedbackTimers = new Map();
 export const WORKFLOW_LIST_TOOL = "workflow_list";
@@ -470,6 +471,9 @@ export async function notifyUnfinishedRuns(cwd, notify, nowMs = Date.now()) {
     }
     if (unfinished.length === 0)
         return;
+    const noticeKey = unfinishedNoticeKey(unfinished);
+    if (await shouldSuppressUnfinishedNotice(cwd, noticeKey, nowMs))
+        return;
     const lines = unfinished
         .slice(0, UNFINISHED_RUN_NOTICE_MAX_RUNS)
         .map((run) => {
@@ -488,6 +492,41 @@ export async function notifyUnfinishedRuns(cwd, notify, nowMs = Date.now()) {
         ...lines,
     ].join("\n"), "warning");
 }
+function unfinishedNoticeKey(runs) {
+    return runs
+        .map((run) => `${run.runId}:${run.status}:${run.updatedAt ?? ""}`)
+        .sort()
+        .join("|");
+}
+async function shouldSuppressUnfinishedNotice(cwd, noticeKey, nowMs) {
+    if (!noticeKey)
+        return true;
+    const dir = join(cwd, ".pi", "workflows");
+    const file = join(dir, "unfinished-notices.json");
+    let state = {};
+    try {
+        state = JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        state = {};
+    }
+    const notices = state.notices ?? {};
+    const previousMs = Date.parse(notices[noticeKey]?.lastNotifiedAt ?? "");
+    if (Number.isFinite(previousMs) &&
+        nowMs - previousMs < UNFINISHED_RUN_NOTICE_DEDUPE_MS) {
+        return true;
+    }
+    const cutoff = nowMs - UNFINISHED_RUN_NOTICE_MAX_AGE_MS;
+    for (const [key, item] of Object.entries(notices)) {
+        const itemMs = Date.parse(item.lastNotifiedAt ?? "");
+        if (!Number.isFinite(itemMs) || itemMs < cutoff)
+            delete notices[key];
+    }
+    notices[noticeKey] = { lastNotifiedAt: new Date(nowMs).toISOString() };
+    await mkdir(dir, { recursive: true });
+    await writeFile(file, `${JSON.stringify({ notices }, null, 2)}\n`, "utf8");
+    return false;
+}
 async function handleWorkflowCommand(args, ctx, api) {
     const tokens = splitArgs(args);
     try {

package/dist/subagent-backend.js

@@ -6,6 +6,8 @@ import { fromProjectPath, isTerminalTaskStatus, nowIso, toProjectPath, writeRunR
 import { applyTaskResultArtifact, isTaskTimedOut, markTaskTimedOut, } from "./result.js";
 import { readWorkflowArtifactReadLedger } from "./workflow-artifact-tool.js";
 import { writeWorkflowFetchCacheExtensionWrapper } from "./workflow-fetch-cache-extension.js";
+import { writeWorkflowWebSourceExtensionWrapper } from "./workflow-web-source-extension.js";
+import { isWorkflowWebSourceTool } from "./workflow-web-source.js";
 import { buildWorkflowOutputRetryInstructions, parseWorkflowOutputForBundle, writeWorkflowTaskArtifactBundle, } from "./workflow-output-artifacts.js";
 const DEFAULT_SUBAGENT_RUNS_ROOT = ".pi/workflow-subagents";
 const EXTRA_SUBAGENT_EXTENSIONS_ENV = "PI_WORKFLOW_SUBAGENT_EXTRA_EXTENSIONS";
@@ -18,6 +20,7 @@ const MODULE_DIR = dirname(MODULE_PATH);
 const BUNDLED_PI_WEB_ACCESS_EXTENSION = bundledNodeModulePath("pi-web-access", "index.ts");
 const BUNDLED_PI_WEB_ACCESS_STORAGE = bundledNodeModulePath("pi-web-access", "storage.ts");
 const WORKFLOW_FETCH_CACHE_EXTENSION_IMPORT = resolve(MODULE_DIR, `workflow-fetch-cache-extension${extname(MODULE_PATH)}`);
+const WORKFLOW_WEB_SOURCE_EXTENSION_IMPORT = resolve(MODULE_DIR, `workflow-web-source-extension${extname(MODULE_PATH)}`);
 const TOOL_PROVIDER_EXTENSIONS = {
     web_search: [BUNDLED_PI_WEB_ACCESS_EXTENSION],
     code_search: [BUNDLED_PI_WEB_ACCESS_EXTENSION],
@@ -847,36 +850,85 @@ function captureToolCallsEnabled() {
     return typeof value === "string" && /^(1|true|yes|on)$/i.test(value.trim());
 }
 async function workflowTaskExtensions(cwd, run, task, compiledTask) {
-    const baseExtensions = uniqueStrings([
-        ...providerExtensionsForTools(compiledTask.runtime.tools, compiledTask.runtime.toolProviders),
+    const tools = compiledTask.runtime.tools;
+    let extensions = uniqueStrings([
+        ...providerExtensionsForTools(tools, compiledTask.runtime.toolProviders),
         ...extraSubagentExtensionsFromEnv(),
     ]);
-    if (!shouldUseFetchContentCache(compiledTask.runtime.tools)) {
-        return baseExtensions;
-    }
     const taskDir = dirname(fromProjectPath(cwd, task.files.result));
-    const wrapperPath = join(taskDir, "workflow-fetch-cache-extension.ts");
-    await writeWorkflowFetchCacheExtensionWrapper({
-        wrapperPath,
-        importPath: WORKFLOW_FETCH_CACHE_EXTENSION_IMPORT,
-        webAccessExtensionPath: BUNDLED_PI_WEB_ACCESS_EXTENSION,
-        webAccessStoragePath: BUNDLED_PI_WEB_ACCESS_STORAGE,
-        config: {
-            runId: run.runId,
-            taskId: task.taskId,
-            cacheDir: resolve(cwd, ".pi", "workflows", run.runId, "source-cache", "fetch-content"),
-        },
-    });
-    return uniqueStrings([
-        ...baseExtensions.filter((extension) => resolve(extension) !== BUNDLED_PI_WEB_ACCESS_EXTENSION),
-        wrapperPath,
-    ]);
+    if (shouldUseFetchContentCache(tools)) {
+        const wrapperPath = join(taskDir, "workflow-fetch-cache-extension.ts");
+        await writeWorkflowFetchCacheExtensionWrapper({
+            wrapperPath,
+            importPath: WORKFLOW_FETCH_CACHE_EXTENSION_IMPORT,
+            webAccessExtensionPath: BUNDLED_PI_WEB_ACCESS_EXTENSION,
+            webAccessStoragePath: BUNDLED_PI_WEB_ACCESS_STORAGE,
+            config: {
+                runId: run.runId,
+                taskId: task.taskId,
+                cacheDir: resolve(cwd, ".pi", "workflows", run.runId, "source-cache", "fetch-content"),
+            },
+        });
+        extensions = uniqueStrings([
+            ...extensions.filter((extension) => resolve(extension) !== BUNDLED_PI_WEB_ACCESS_EXTENSION),
+            wrapperPath,
+        ]);
+    }
+    if (shouldUseWorkflowWebSource(tools)) {
+        const providerExtensionPath = workflowWebSourceProviderExtension(tools, compiledTask.runtime.toolProviders);
+        const wrapperPath = join(taskDir, "workflow-web-source-extension.ts");
+        await writeWorkflowWebSourceExtensionWrapper({
+            wrapperPath,
+            importPath: WORKFLOW_WEB_SOURCE_EXTENSION_IMPORT,
+            providerExtensionPath,
+            config: {
+                schema: "workflow-web-source-launch-config-v1",
+                runId: run.runId,
+                taskId: task.taskId,
+                cwd,
+                cacheDir: resolve(cwd, ".pi", "workflows", run.runId, "web-source-cache"),
+                provider: {
+                    kind: providerExtensionPath === BUNDLED_PI_WEB_ACCESS_EXTENSION
+                        ? "pi-web-access"
+                        : "extension",
+                    extensionPath: providerExtensionPath,
+                },
+                securityPolicy: {
+                    allowPrivateHosts: false,
+                    cacheRawProviderPayloads: false,
+                },
+            },
+        });
+        const capturedProviderExtensions = new Set(workflowWebSourceProviderExtensions(tools, compiledTask.runtime.toolProviders));
+        extensions = uniqueStrings([
+            ...extensions.filter((extension) => !capturedProviderExtensions.has(extension)),
+            wrapperPath,
+        ]);
+    }
+    return extensions;
 }
 function shouldUseFetchContentCache(tools) {
     if (!(tools ?? []).includes("fetch_content"))
         return false;
     return !isExplicitlyDisabled(fetchContentCacheEnvValue());
 }
+function shouldUseWorkflowWebSource(tools) {
+    return (tools ?? []).some((tool) => isWorkflowWebSourceTool(tool));
+}
+function workflowWebSourceProviderExtension(tools, toolProviders) {
+    return (workflowWebSourceProviderExtensions(tools, toolProviders)[0] ??
+        BUNDLED_PI_WEB_ACCESS_EXTENSION);
+}
+function workflowWebSourceProviderExtensions(tools, toolProviders) {
+    const providers = new Set();
+    for (const tool of tools ?? []) {
+        if (!isWorkflowWebSourceTool(tool))
+            continue;
+        for (const provider of toolProviders?.[tool]?.extensions ?? [])
+            providers.add(provider);
+    }
+    return [...providers];
+}
 function fetchContentCacheEnvValue() {
     return (process.env[FETCH_CONTENT_CACHE_ENV] ?? process.env[LEGACY_FETCH_CACHE_ENV]);
 }
@@ -1068,7 +1120,7 @@ function buildSystemPrompt(task) {
                 : []),
             ...(workflowRefsUrlValidation
                 ? [
-                    "External URLs in <refs> are validated before completion. Use fetch_content to verify each URL you cite; replace stale or unreachable URLs with working canonical URLs or omit them.",
+                    "External URLs in <refs> are validated before completion. Use available workflow web tools to fetch/cache the URL and read exact evidence before citing it; replace stale or unreachable URLs with working canonical URLs or omit them.",
                 ]
                 : []),
         ]
@@ -1082,11 +1134,14 @@ function buildSystemPrompt(task) {
             ? `Only these tools are enabled for this workflow task: ${enabledTools.join(", ")}.`
             : "No tools are enabled for this workflow task.",
         "If the agent definition below mentions tools that are not in this enabled list, ignore those mentions; unavailable tools cannot be called in this workflow run.",
-        !enabledTools.includes("get_search_content") &&
-            (enabledTools.includes("web_search") ||
-                enabledTools.includes("fetch_content"))
-            ? "Full cached search-content hydration is unavailable here. Use web_search/fetch_content results and report evidence gaps instead of broad raw document retrieval."
-            : undefined,
+        enabledTools.includes("workflow_web_fetch_source") ||
+            enabledTools.includes("workflow_web_source_read")
+            ? "Workflow web-source tools return compact source cards. Preserve sourceRef values in structured outputs. Use workflow_web_source_read for exact evidence snippets; when several snippets are needed from the same sourceRef, batch them with queries:[...] or reads:[...] instead of making repeated calls. If the exact quote is unknown, pass claim plus 2-6 distinctive terms to harvest a candidate source window and preserve its match metadata. Do not read workflow cache files directly."
+            : !enabledTools.includes("get_search_content") &&
+                (enabledTools.includes("web_search") ||
+                    enabledTools.includes("fetch_content"))
+                ? "Full cached search-content hydration is unavailable here. Use web_search/fetch_content results and report evidence gaps instead of broad raw document retrieval."
+                : undefined,
     ].filter((line) => typeof line === "string");
     return [
         `You are Pi workflow subagent '${task.agent}'.`,

package/dist/tool-metadata.d.ts

@@ -33,3 +33,4 @@ export declare function effectiveToolClassification(tool: string, toolProviders:
 export declare function classifyToolCapability(tools: string[] | undefined, toolProviders: Record<string, CompiledToolProvider> | undefined, readOnlyDeclared: boolean, options?: ClassifyToolCapabilityOptions): TaskCapability;
 export declare function buildAvailableToolView(tools?: readonly string[], toolProviders?: Record<string, CompiledToolProvider>): AvailableToolViewItem[];
 export declare function validateToolAuthority(tools: readonly string[] | undefined, options?: ToolAuthorityValidationOptions): string[];
+export declare function toolAllowedByAuthorityCeiling(tool: string, allowed: ReadonlySet<string>): boolean;

package/dist/tool-metadata.js

@@ -16,6 +16,9 @@ const BUILTIN_TOOL_METADATA = {
     code_search: { classification: "read-only" },
     fetch_content: { classification: "read-only" },
     get_search_content: { classification: "read-only" },
+    workflow_web_search: { classification: "read-only" },
+    workflow_web_fetch_source: { classification: "read-only" },
+    workflow_web_source_read: { classification: "read-only" },
     scrapling_fetch: { classification: "read-only" },
     edit: { classification: "write-capable" },
     write: { classification: "write-capable" },
@@ -26,6 +29,11 @@ const NON_DOWNGRADABLE_TOOL_FLOORS = {
     write: "write-capable",
     bash: "mutation-capable",
 };
+const TOOL_AUTHORITY_COMPAT_ALIASES = {
+    workflow_web_search: ["web_search"],
+    workflow_web_fetch_source: ["fetch_content"],
+    workflow_web_source_read: ["fetch_content", "get_search_content"],
+};
 export function toolNameForSpec(tool) {
     if (typeof tool === "string")
         return tool;
@@ -168,7 +176,7 @@ export function validateToolAuthority(tools, options = {}) {
         ? new Set(options.allowedTools)
         : undefined;
     for (const tool of tools) {
-        if (allowed && !allowed.has(tool)) {
+        if (allowed && !toolAllowedByAuthorityCeiling(tool, allowed)) {
             errors.push(`tool "${tool}" is outside the allowed tool ceiling`);
             continue;
         }
@@ -179,6 +187,10 @@ export function validateToolAuthority(tools, options = {}) {
     }
     return errors;
 }
+export function toolAllowedByAuthorityCeiling(tool, allowed) {
+    return (allowed.has(tool) ||
+        (TOOL_AUTHORITY_COMPAT_ALIASES[tool] ?? []).some((alias) => allowed.has(alias)));
+}
 function maxClassification(...values) {
     let best;
     for (const value of values) {

package/dist/workflow-artifact-extension.js

@@ -32,7 +32,7 @@ const workflowArtifactParameters = {
         },
         path: {
             type: "string",
-            description: "Optional simple JSON path for projected reads, for example $.claims or $.claimIndex.items. Supported only for JSON artifacts.",
+            description: "Optional simple JSON path for projected reads, for example $.claims or $.claimIndex.items. Required when maxItems or maxChars is provided. Supported only for JSON artifacts.",
         },
         maxItems: {
             type: "integer",
@@ -42,7 +42,7 @@ const workflowArtifactParameters = {
         maxChars: {
             type: "integer",
             minimum: 0,
-            description: "Optional character limit for the projected JSON value after maxItems is applied.",
+            description: "Optional character limit for the projected JSON value after maxItems is applied. Requires path; omit maxChars for whole-artifact reads.",
         },
     },
     required: ["action"],
@@ -56,6 +56,7 @@ export function registerWorkflowArtifactTool(pi, config) {
         promptGuidelines: [
             "Use workflow_artifact to inspect upstream workflow artifacts when the workflow prompt lists available sources or required reads.",
             "Call workflow_artifact with action=list to see visible source names before reading an artifact if unsure.",
+            "When using maxItems or maxChars, include a JSON path such as $.claims; for whole-artifact reads, omit maxItems/maxChars.",
             "Do not use repository read for workflow artifacts; workflow_artifact records required-read evidence.",
         ],
         parameters: workflowArtifactParameters,

package/dist/workflow-artifact-tool.js

@@ -23,7 +23,24 @@ const WORKFLOW_ARTIFACT_KIND_SET = new Set(WORKFLOW_ARTIFACT_KINDS);
 const DEFAULT_MAX_BYTES = 50 * 1024;
 const DEFAULT_MAX_LINES = 2000;
 const SOURCE_NAME_PATTERN = /^[A-Za-z0-9_.:-]+$/;
-const SIMPLE_JSON_PATH_PATTERN = /^(\$|\$(\.[A-Za-z0-9_-]+)+)$/;
+const SIMPLE_JSON_PATH_PATTERN = /^(\$|\$(\.[A-Za-z0-9_-]+(\[(\*|\d+|\d*:\d*)\])?)+)$/;
+const JSON_PATH_SEGMENT_ALIASES = {
+    axes: "researchAxes",
+    claimVerdicts: "claimVerdictLedger",
+    factSlot: "factSlots",
+    gaps: "remainingGaps",
+    primarySources: "sourcePolicy",
+    priorities: "verificationPriorities",
+    questions: "researchQuestions",
+    requiredSources: "sourcePolicy",
+    scope: "researchScope",
+    slots: "factSlots",
+    sourceQualityRules: "sourcePolicy",
+    sourceRequirements: "sourcePolicy",
+    verification: "verificationPriorities",
+    verificationPriority: "verificationPriorities",
+    verdicts: "claimVerdictLedger",
+};
 export async function loadWorkflowSourceManifest(manifestPath, options = {}) {
     const absoluteManifestPath = resolve(manifestPath);
     const runDir = resolve(options.runDir ?? inferRunDirFromManifestPath(absoluteManifestPath));
@@ -192,17 +209,28 @@ export async function readWorkflowArtifact(manifest, sourceName, artifact, optio
 }
 async function readProjectedWorkflowArtifact(options) {
     const parsed = JSON.parse(await readFile(options.artifactPath, "utf8"));
-    const resolved = readSimpleJsonPath(parsed, options.path);
+    let effectivePath = options.path;
+    let resolved;
+    for (const candidatePath of projectionPathCandidates(options.path, options.source, options.artifact)) {
+        resolved = readSimpleJsonPath(parsed, candidatePath);
+        if (resolved !== undefined) {
+            effectivePath = candidatePath;
+            break;
+        }
+    }
     if (resolved === undefined) {
         throw new Error(`workflow_artifact path did not resolve: ${options.path}`);
     }
-    const sliced = applyProjectionItemLimit(resolved, options);
+    const sliced = applyProjectionItemLimit(resolved, {
+        ...options,
+        path: effectivePath,
+    });
     const serialized = JSON.stringify(sliced.value, null, 2);
     const preview = options.maxChars !== undefined && serialized.length > options.maxChars
         ? serialized.slice(0, options.maxChars)
         : serialized;
     const projection = {
-        path: options.path,
+        path: effectivePath,
         valueType: jsonValueType(resolved),
         ...(options.maxItems === undefined ? {} : { maxItems: options.maxItems }),
         ...(options.maxChars === undefined ? {} : { maxChars: options.maxChars }),
@@ -234,6 +262,58 @@ async function readProjectedWorkflowArtifact(options) {
         projection,
     };
 }
+function projectionPathCandidates(path, source, artifact) {
+    const candidates = [];
+    const seen = new Set();
+    const queue = [path];
+    for (let index = 0; index < queue.length && index < 32; index += 1) {
+        const candidate = queue[index];
+        if (seen.has(candidate))
+            continue;
+        seen.add(candidate);
+        candidates.push(candidate);
+        for (const next of [
+            stripArraySelector(candidate),
+            stripSourcePathPrefix(candidate, source),
+            stripArtifactPathPrefix(candidate, artifact),
+            applyJsonPathSegmentAliases(candidate),
+        ]) {
+            if (next !== candidate && !seen.has(next))
+                queue.push(next);
+        }
+    }
+    return candidates;
+}
+function stripArraySelector(path) {
+    return path.replace(/\[(\*|\d+|\d*:\d*)\]/gu, "");
+}
+function stripSourcePathPrefix(path, source) {
+    const sourcePrefix = `$.${source}.`;
+    if (!path.startsWith(sourcePrefix))
+        return path;
+    return `$.${path.slice(sourcePrefix.length)}`;
+}
+function stripArtifactPathPrefix(path, artifact) {
+    const artifactPath = `$.${artifact}`;
+    if (path === artifactPath)
+        return "$";
+    const artifactPrefix = `${artifactPath}.`;
+    if (!path.startsWith(artifactPrefix))
+        return path;
+    return `$.${path.slice(artifactPrefix.length)}`;
+}
+function applyJsonPathSegmentAliases(path) {
+    if (path === "$")
+        return path;
+    const segments = path
+        .slice(2)
+        .split(".")
+        .map((segment) => segment.replace(/\[(\*|\d+|\d*:\d*)\]$/u, ""));
+    const aliased = segments.map((segment) => JSON_PATH_SEGMENT_ALIASES[segment] ?? segment);
+    if (aliased.every((segment, index) => segment === segments[index]))
+        return path;
+    return `$.${aliased.join(".")}`;
+}
 function applyProjectionItemLimit(value, options) {
     if (options.maxItems === undefined)
         return { value };

package/dist/workflow-web-source-extension.d.ts

@@ -0,0 +1,43 @@
+import { type WorkflowWebSecurityPolicy, type WorkflowWebSourceCacheConfig, type WorkflowWebSourcePolicy } from "./workflow-web-source.js";
+export declare const WORKFLOW_WEB_SOURCE_LAUNCH_CONFIG_SCHEMA: "workflow-web-source-launch-config-v1";
+export interface WorkflowWebProviderLaunchConfig {
+    kind: "pi-web-access" | "extension" | "none";
+    extensionPath?: string;
+}
+export interface WorkflowWebSourceLaunchConfig extends WorkflowWebSourceCacheConfig {
+    schema: typeof WORKFLOW_WEB_SOURCE_LAUNCH_CONFIG_SCHEMA;
+    workflowName?: string;
+    stageId?: string;
+    taskKey?: string;
+    cwd: string;
+    provider: WorkflowWebProviderLaunchConfig;
+    webSourcePolicy?: Partial<WorkflowWebSourcePolicy>;
+    securityPolicy?: Partial<WorkflowWebSecurityPolicy>;
+    exposeLegacyTools?: boolean;
+}
+export interface WorkflowWebSourceExtensionWrapperOptions {
+    wrapperPath: string;
+    importPath: string;
+    providerExtensionPath?: string;
+    config: WorkflowWebSourceLaunchConfig;
+}
+type ToolResult = {
+    content?: Array<Record<string, unknown>>;
+    details?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+type ToolSpec = {
+    name?: string;
+    execute?: (toolCallId: string, params: unknown, signal?: AbortSignal, onUpdate?: unknown, ctx?: unknown) => Promise<ToolResult>;
+    [key: string]: unknown;
+};
+type PiLike = Record<string | symbol, unknown> & {
+    registerTool(tool: ToolSpec): void;
+    appendEntry?(type: string, data: unknown): void;
+};
+type ProviderExtension = (pi: PiLike) => void;
+export declare function registerWorkflowWebSourceExtension(pi: PiLike, config: WorkflowWebSourceLaunchConfig, providerExtension?: ProviderExtension): void;
+export declare function buildWorkflowWebSourceExtensionWrapper(options: Omit<WorkflowWebSourceExtensionWrapperOptions, "wrapperPath">): string;
+export declare function writeWorkflowWebSourceExtensionWrapper(options: WorkflowWebSourceExtensionWrapperOptions): Promise<string>;
+export declare function workflowWebSourceModuleImportPath(modulePath: string): string;
+export {};