@agwab/pi-workflow 0.1.1 → 0.2.0

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/types.d.ts

@@ -1,3 +1,4 @@
+import type { WorkflowRuntimeThinkingResolution } from "./workflow-runtime.js";
 export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh"];
 export declare const FAST_MODES: readonly ["inherit", "off"];
 export declare const APPROVAL_MODES: readonly ["non-interactive", "on-request"];
@@ -249,6 +250,7 @@ export interface PermissionPreview {
 export interface CompiledTaskRuntime {
     model?: string;
     thinking?: ThinkingLevel;
+    thinkingResolution?: WorkflowRuntimeThinkingResolution;
     fast?: FastMode;
     approvalMode: ApprovalMode;
     tools?: string[];
@@ -505,6 +507,7 @@ export interface WorkflowTaskRunRecord {
     runtime: {
         model?: string;
         thinking?: ThinkingLevel;
+        thinkingResolution?: WorkflowRuntimeThinkingResolution;
         fast?: FastMode;
         approvalMode: ApprovalMode;
         maxRuntimeMs?: number;

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-progress-health.d.ts

@@ -0,0 +1,37 @@
+import type { TaskRunStatus, WorkflowRunRecord, WorkflowTaskRunRecord } from "./types.js";
+export type WorkflowHealthState = "completed" | "pending" | "active" | "long-tail" | "stalled" | "likely-stuck" | "needs-action";
+export type WorkflowHealthTone = "success" | "accent" | "warning" | "error" | "dim";
+export type WorkflowDurationClass = "short" | "medium" | "long";
+export type WorkflowHealthSuggestion = "wait" | "inspect" | "resume" | "review";
+export interface WorkflowHealthTaskSummary {
+    taskId?: string;
+    displayName?: string;
+    stageId?: string;
+    status?: TaskRunStatus;
+    elapsedMs?: number;
+}
+export interface WorkflowProgressHealth {
+    state: WorkflowHealthState;
+    label: string;
+    summary: string;
+    tone: WorkflowHealthTone;
+    suggestion: WorkflowHealthSuggestion;
+    reason: string;
+    durationClass?: WorkflowDurationClass;
+    currentTask?: WorkflowHealthTaskSummary;
+    lastActivityAt?: string;
+    lastActivityAgeMs?: number;
+    heartbeatAt?: string;
+    heartbeatAgeMs?: number;
+}
+type TaskHealthInput = Pick<WorkflowTaskRunRecord, "taskId" | "specId" | "displayName" | "status" | "statusDetail" | "stageId" | "kind" | "startedAt" | "lastMessage" | "runtime" | "backendHandle" | "pid">;
+type RunHealthInput = Pick<WorkflowRunRecord, "status" | "taskSummary" | "createdAt" | "updatedAt"> & {
+    tasks?: TaskHealthInput[];
+};
+export interface WorkflowHealthOptions {
+    nowMs?: number;
+}
+export declare function diagnoseWorkflowRunHealth(run: RunHealthInput, options?: WorkflowHealthOptions): WorkflowProgressHealth;
+export declare function diagnoseWorkflowTaskHealth(task: TaskHealthInput, run?: Pick<WorkflowRunRecord, "updatedAt">, options?: WorkflowHealthOptions): WorkflowProgressHealth;
+export declare function classifyWorkflowTaskDuration(task: Pick<WorkflowTaskRunRecord, "stageId" | "displayName" | "specId" | "kind" | "statusDetail" | "runtime">): WorkflowDurationClass;
+export {};