@agwab/pi-workflow 0.2.1 → 0.4.0

package/dist/workflow-view.js

@@ -953,12 +953,14 @@ function statusForSummary(summary) {
         return "running";
     if (summary.blocked > 0)
         return "blocked";
-    if (summary.failed > 0 || summary.interrupted > 0)
+    if (summary.failed > 0)
         return "failed";
     if (summary.pending > 0)
         return "pending";
     if (summary.total > 0 && summary.completed === summary.total)
         return "completed";
+    if (summary.interrupted > 0)
+        return "interrupted";
     return "interrupted";
 }
 function taskElapsed(task) {

package/dist/workflow-web-source-extension.js

@@ -72,14 +72,26 @@ export function registerWorkflowWebSourceExtension(pi, config, providerExtension
         name: "workflow_web_fetch_source",
         description: "Fetch one or more URLs into the workflow web-source cache and return compact source cards with sourceRefs.",
         parameters: Type.Object({
-            url: Type.Optional(Type.String({ description: "Single URL to fetch into the workflow web-source cache." })),
-            urls: Type.Optional(Type.Array(Type.String(), { description: "Multiple URLs to fetch in one tool call. Prefer this over repeated fetch calls when caching several promising sources." })),
+            url: Type.Optional(Type.String({
+                description: "Single URL to fetch into the workflow web-source cache.",
+            })),
+            urls: Type.Optional(Type.Array(Type.String(), {
+                description: "Multiple URLs to fetch in one tool call. Prefer this over repeated fetch calls when caching several promising sources.",
+            })),
             sources: Type.Optional(Type.Array(Type.Object({
-                url: Type.String({ description: "URL to fetch into the workflow web-source cache." }),
+                url: Type.String({
+                    description: "URL to fetch into the workflow web-source cache.",
+                }),
                 title: Type.Optional(Type.String({ description: "Optional source title override." })),
-            }), { description: "Multiple URL/title objects to fetch in one tool call." })),
-            title: Type.Optional(Type.String({ description: "Optional source title override for single-url fetches." })),
-            titles: Type.Optional(Type.Array(Type.String(), { description: "Optional title overrides paired by index with urls." })),
+            }), {
+                description: "Multiple URL/title objects to fetch in one tool call.",
+            })),
+            title: Type.Optional(Type.String({
+                description: "Optional source title override for single-url fetches.",
+            })),
+            titles: Type.Optional(Type.Array(Type.String(), {
+                description: "Optional title overrides paired by index with urls.",
+            })),
         }),
         execute: async (toolCallId, params, signal, onUpdate, ctx) => {
             const batchRequested = fetchSourceBatchRequested(params);
@@ -101,8 +113,12 @@ export function registerWorkflowWebSourceExtension(pi, config, providerExtension
                         url: sanitizeUrlForModel(request.url),
                         status: typeof payload.status === "string" ? payload.status : "unknown",
                         ...(typeof payload.code === "string" ? { code: payload.code } : {}),
-                        ...(typeof payload.message === "string" ? { message: payload.message } : {}),
-                        ...(typeof card?.sourceRef === "string" ? { sourceRef: card.sourceRef } : {}),
+                        ...(typeof payload.message === "string"
+                            ? { message: payload.message }
+                            : {}),
+                        ...(typeof card?.sourceRef === "string"
+                            ? { sourceRef: card.sourceRef }
+                            : {}),
                         ...(card ? { cardIndex: cards.length - 1 } : {}),
                     });
                 }
@@ -159,10 +175,15 @@ export function registerWorkflowWebSourceExtension(pi, config, providerExtension
                 url: existing.redactedUrl,
                 visibleChars: budget.used,
             });
-            return toolResultFromJson({ status: "ok", tool: "workflow_web_fetch_source", card });
+            return toolResultFromJson({
+                status: "ok",
+                tool: "workflow_web_fetch_source",
+                card,
+            });
         }
         const fetchKey = sourceUrlCacheKey(fetchUrl);
-        const cachedFailure = fetchFailures.get(fetchKey) ?? await readDurableFetchFailure(config, fetchKey);
+        const cachedFailure = fetchFailures.get(fetchKey) ??
+            (await readDurableFetchFailure(config, fetchKey));
         if (cachedFailure) {
             fetchFailures.set(fetchKey, cachedFailure);
             await recordWorkflowWebSourceEvent(config, "fetch_negative_cache_hit", {
@@ -178,25 +199,43 @@ export function registerWorkflowWebSourceExtension(pi, config, providerExtension
             if (!source)
                 return result;
             sourceCache.set(source.sourceRef, source);
-            const card = buildWorkflowWebSourceCard({ source, policy, budget, duplicate: true });
+            const card = buildWorkflowWebSourceCard({
+                source,
+                policy,
+                budget,
+                duplicate: true,
+            });
             await recordWorkflowWebSourceEvent(config, "fetch_duplicate", {
                 sourceRef: source.sourceRef,
                 url: source.redactedUrl,
                 visibleChars: budget.used,
             });
-            return toolResultFromJson({ status: "ok", tool: "workflow_web_fetch_source", card });
+            return toolResultFromJson({
+                status: "ok",
+                tool: "workflow_web_fetch_source",
+                card,
+            });
         }
         const fetchPromise = withWorkflowWebFetchLock(config, fetchKey, signal, async () => {
             const lockedExisting = await findWorkflowWebSourceByUrl(config, fetchUrl);
             if (lockedExisting) {
                 sourceCache.set(lockedExisting.sourceRef, lockedExisting);
-                const card = buildWorkflowWebSourceCard({ source: lockedExisting, policy, budget, duplicate: true });
+                const card = buildWorkflowWebSourceCard({
+                    source: lockedExisting,
+                    policy,
+                    budget,
+                    duplicate: true,
+                });
                 await recordWorkflowWebSourceEvent(config, "fetch_duplicate", {
                     sourceRef: lockedExisting.sourceRef,
                     url: lockedExisting.redactedUrl,
                     visibleChars: budget.used,
                 });
-                return toolResultFromJson({ status: "ok", tool: "workflow_web_fetch_source", card });
+                return toolResultFromJson({
+                    status: "ok",
+                    tool: "workflow_web_fetch_source",
+                    card,
+                });
             }
             const lockedFailure = await readDurableFetchFailure(config, fetchKey);
             if (lockedFailure) {
@@ -221,7 +260,10 @@ export function registerWorkflowWebSourceExtension(pi, config, providerExtension
                     return await cachedFetchFailureResult(config, fetchFailures, fetchKey, {
                         code: "blocked_url",
                         message: "URL was blocked by workflow web-source security policy before content fetch.",
-                        extra: { reason: safeFetch.reason, url: sanitizeUrlForModel(safeFetch.url) },
+                        extra: {
+                            reason: safeFetch.reason,
+                            url: sanitizeUrlForModel(safeFetch.url),
+                        },
                         reason: safeFetch.reason,
                     });
                 }
@@ -311,10 +353,16 @@ export function registerWorkflowWebSourceExtension(pi, config, providerExtension
                 textChars: source.textChars,
                 visibleChars: budget.used,
             });
-            return toolResultFromJson({ status: "ok", tool: "workflow_web_fetch_source", card });
+            return toolResultFromJson({
+                status: "ok",
+                tool: "workflow_web_fetch_source",
+                card,
+            });
         }).catch(async (error) => {
             const message = error instanceof Error ? error.message : "workflow_web_fetch_failed";
-            const code = message === "fetch_lock_timeout" ? "fetch_lock_timeout" : "workflow_web_fetch_failed";
+            const code = message === "fetch_lock_timeout"
+                ? "fetch_lock_timeout"
+                : "workflow_web_fetch_failed";
             await recordWorkflowWebSourceEvent(config, "fetch_failed", {
                 url: sanitizeUrlForModel(fetchUrl),
                 code,
@@ -335,23 +383,47 @@ export function registerWorkflowWebSourceExtension(pi, config, providerExtension
         name: "workflow_web_source_read",
         description: "Read one or more narrow exact/fuzzy/term-matched snippets from a cached workflow web source by sourceRef.",
         parameters: Type.Object({
-            sourceRef: Type.String({ description: "Opaque sourceRef returned by workflow_web_fetch_source." }),
-            query: Type.Optional(Type.String({ description: "Exact or fuzzy text to locate in the cached source." })),
-            queries: Type.Optional(Type.Array(Type.String(), { description: "Multiple exact/fuzzy texts to locate in one cached source. Prefer this over repeated calls when reading several snippets from the same sourceRef." })),
-            exact: Type.Optional(Type.String({ description: "Exact text to locate in the cached source." })),
-            exactTexts: Type.Optional(Type.Array(Type.String(), { description: "Multiple exact texts to locate in one cached source." })),
-            claim: Type.Optional(Type.String({ description: "Claim to locate when the exact quote is not known. Use with terms for deterministic quote harvesting." })),
-            terms: Type.Optional(Type.Array(Type.String(), { description: "Important terms that should co-occur in the returned source window." })),
+            sourceRef: Type.String({
+                description: "Opaque sourceRef returned by workflow_web_fetch_source.",
+            }),
+            query: Type.Optional(Type.String({
+                description: "Exact or fuzzy text to locate in the cached source.",
+            })),
+            queries: Type.Optional(Type.Array(Type.String(), {
+                description: "Multiple exact/fuzzy texts to locate in one cached source. Prefer this over repeated calls when reading several snippets from the same sourceRef.",
+            })),
+            exact: Type.Optional(Type.String({
+                description: "Exact text to locate in the cached source.",
+            })),
+            exactTexts: Type.Optional(Type.Array(Type.String(), {
+                description: "Multiple exact texts to locate in one cached source.",
+            })),
+            claim: Type.Optional(Type.String({
+                description: "Claim to locate when the exact quote is not known. Use with terms for deterministic quote harvesting.",
+            })),
+            terms: Type.Optional(Type.Array(Type.String(), {
+                description: "Important terms that should co-occur in the returned source window.",
+            })),
             reads: Type.Optional(Type.Array(Type.Object({
                 query: Type.Optional(Type.String({ description: "Exact or fuzzy text to locate." })),
                 exact: Type.Optional(Type.String({ description: "Exact text to locate." })),
                 exactText: Type.Optional(Type.String({ description: "Exact text to locate." })),
                 text: Type.Optional(Type.String({ description: "Text to locate." })),
-                claim: Type.Optional(Type.String({ description: "Claim to locate when exact quote is unknown." })),
-                terms: Type.Optional(Type.Array(Type.String(), { description: "Important terms for deterministic quote harvesting." })),
-                maxChars: Type.Optional(Type.Number({ description: "Maximum visible snippet characters for this read." })),
-            }), { description: "Mixed batch reads for one sourceRef; each item can use query or claim+terms." })),
-            maxChars: Type.Optional(Type.Number({ description: "Maximum visible snippet characters per query." })),
+                claim: Type.Optional(Type.String({
+                    description: "Claim to locate when exact quote is unknown.",
+                })),
+                terms: Type.Optional(Type.Array(Type.String(), {
+                    description: "Important terms for deterministic quote harvesting.",
+                })),
+                maxChars: Type.Optional(Type.Number({
+                    description: "Maximum visible snippet characters for this read.",
+                })),
+            }), {
+                description: "Mixed batch reads for one sourceRef; each item can use query or claim+terms.",
+            })),
+            maxChars: Type.Optional(Type.Number({
+                description: "Maximum visible snippet characters per query.",
+            })),
         }),
         execute: async (_toolCallId, params) => {
             const sourceRef = stringParam(params, "sourceRef") ?? stringParam(params, "source_ref");
@@ -361,7 +433,9 @@ export function registerWorkflowWebSourceExtension(pi, config, providerExtension
             }
             const source = await readCachedWorkflowWebSource(sourceRef);
             if (!source) {
-                await recordWorkflowWebSourceEvent(config, "source_read_missing", { sourceRef });
+                await recordWorkflowWebSourceEvent(config, "source_read_missing", {
+                    sourceRef,
+                });
                 return errorToolResult("source_not_found", "No cached workflow web source exists for sourceRef.", {
                     sourceRef,
                 });
@@ -391,6 +465,7 @@ export function registerWorkflowWebSourceExtension(pi, config, providerExtension
                     missingTerms: read.missingTerms,
                     coverageRatio: read.coverageRatio,
                     candidateOnly: read.candidateOnly,
+                    truncated: read.truncated,
                     quote: status === "budget_exhausted" ? undefined : read.quote,
                     startOffset: read.startOffset,
                     endOffset: read.endOffset,
@@ -420,25 +495,33 @@ export function registerWorkflowWebSourceExtension(pi, config, providerExtension
                     missingTerms: result.missingTerms,
                     coverageRatio: result.coverageRatio,
                     candidateOnly: result.candidateOnly,
+                    truncated: result.truncated,
                     quote: result.status === "budget_exhausted" ? undefined : result.quote,
                     startOffset: result.startOffset,
                     endOffset: result.endOffset,
-                    budget: budgetSnapshot(result.status === "budget_exhausted"),
+                    budget: budgetSnapshot(result.status === "budget_exhausted" ||
+                        result.status === "truncated"),
                     next: result.status === "budget_exhausted"
                         ? "Visible web-source budget is exhausted for this task; cite the sourceRef as an evidence gap or use a smaller query in a fresh task."
-                        : undefined,
+                        : result.status === "truncated"
+                            ? "The matched web-source snippet was truncated by the visible budget or maxChars; use a smaller exact query or a fresh task if the full quote is required."
+                            : undefined,
                 });
             }
+            const hasBudgetExhaustedRead = results.some((result) => result.status === "budget_exhausted");
+            const hasTruncatedRead = results.some((result) => result.status === "truncated");
             return toolResultFromJson({
                 status: responseStatus,
                 tool: "workflow_web_source_read",
                 sourceRef,
                 url: source.redactedUrl,
                 results,
-                budget: budgetSnapshot(results.some((result) => result.status === "budget_exhausted")),
-                next: responseStatus === "budget_exhausted"
+                budget: budgetSnapshot(hasBudgetExhaustedRead || hasTruncatedRead),
+                next: hasBudgetExhaustedRead
                     ? "Visible web-source budget is exhausted for this task; cite missing quotes as evidence gaps or use smaller query batches in a fresh task."
-                    : undefined,
+                    : hasTruncatedRead
+                        ? "One or more matched web-source snippets were truncated by the visible budget or maxChars; use smaller exact queries or a fresh task if full quotes are required."
+                        : undefined,
             });
         },
     });
@@ -525,8 +608,8 @@ async function cachedFetchFailureResult(config, cache, key, failure) {
     }
     return errorToolResult(failure.code, failure.message, failure.extra);
 }
-const FETCH_LOCK_STALE_MS = 60_000;
-const FETCH_LOCK_WAIT_MS = 75_000;
+const FETCH_LOCK_STALE_MS = 4 * 60_000;
+const FETCH_LOCK_WAIT_MS = 5 * 60_000;
 async function withWorkflowWebFetchLock(config, key, signal, fn) {
     const release = await acquireWorkflowWebFetchLock(config, key, signal);
     try {
@@ -544,10 +627,11 @@ async function acquireWorkflowWebFetchLock(config, key, signal) {
         if (signal?.aborted)
             throw new Error("aborted");
         try {
+            const ownerId = `${process.pid}:${Date.now()}:${Math.random().toString(36).slice(2)}`;
             await mkdir(lockDir);
-            await writeFile(resolve(lockDir, "owner.json"), `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString(), key }, null, 2)}\n`, "utf8");
+            await writeFile(resolve(lockDir, "owner.json"), `${JSON.stringify({ ownerId, pid: process.pid, createdAt: new Date().toISOString(), key }, null, 2)}\n`, "utf8");
             return async () => {
-                await rm(lockDir, { recursive: true, force: true });
+                await releaseWorkflowWebFetchLock(lockDir, ownerId);
             };
         }
         catch (error) {
@@ -561,6 +645,17 @@ async function acquireWorkflowWebFetchLock(config, key, signal) {
         }
     }
 }
+async function releaseWorkflowWebFetchLock(lockDir, ownerId) {
+    try {
+        const current = await readFetchLockOwner(lockDir);
+        if (current?.ownerId !== ownerId)
+            return;
+        await rm(lockDir, { recursive: true, force: true });
+    }
+    catch {
+        // Missing or unreadable lock will be retried by the caller.
+    }
+}
 async function removeStaleFetchLock(lockDir) {
     try {
         const current = await stat(lockDir);
@@ -572,6 +667,17 @@ async function removeStaleFetchLock(lockDir) {
         // Missing or unreadable lock will be retried by the caller.
     }
 }
+async function readFetchLockOwner(lockDir) {
+    try {
+        const parsed = JSON.parse(await readFile(resolve(lockDir, "owner.json"), "utf8"));
+        return isRecord(parsed) && typeof parsed.ownerId === "string"
+            ? { ownerId: parsed.ownerId }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function readDurableFetchFailure(config, key) {
     try {
         const parsed = JSON.parse(await readFile(fetchFailurePath(config, key), "utf8"));
@@ -596,7 +702,9 @@ function normalizeFetchFailure(value) {
         message: value.message,
         extra,
         ...(typeof value.reason === "string" ? { reason: value.reason } : {}),
-        ...(typeof value.createdAt === "string" ? { createdAt: value.createdAt } : {}),
+        ...(typeof value.createdAt === "string"
+            ? { createdAt: value.createdAt }
+            : {}),
     };
 }
 function fetchLockPath(config, key) {
@@ -621,7 +729,9 @@ function shouldCacheFetchFailure(reason) {
         reason === "unsupported_content_type");
 }
 function shouldCacheFetchFailureInMemory(reason) {
-    return reason === "empty_source" || reason === "dns_resolution_failed" || reason.includes("ENOTFOUND");
+    return (reason === "empty_source" ||
+        reason === "dns_resolution_failed" ||
+        reason.includes("ENOTFOUND"));
 }
 const WORKFLOW_WEB_FETCH_TIMEOUT_MS = 30_000;
 const WORKFLOW_WEB_FETCH_MAX_CHARS = 1_000_000;
@@ -636,12 +746,20 @@ async function safeFetchWorkflowWebText(url, security, signal) {
             return response;
         if (response.status >= 300 && response.status < 400) {
             if (!response.location)
-                return { ok: false, reason: "redirect_without_location", url: checked.normalizedUrl };
+                return {
+                    ok: false,
+                    reason: "redirect_without_location",
+                    url: checked.normalizedUrl,
+                };
             current = new URL(response.location, checked.normalizedUrl).href;
             continue;
         }
         if (response.status < 200 || response.status >= 300) {
-            return { ok: false, reason: `http_${response.status}`, url: checked.normalizedUrl };
+            return {
+                ok: false,
+                reason: `http_${response.status}`,
+                url: checked.normalizedUrl,
+            };
         }
         const extracted = extractWorkflowWebResponseText(response.text, response.contentType);
         return {
@@ -675,13 +793,17 @@ function safeFetchOnce(url, security, signal) {
                 lookupPublicAddress(hostname, security)
                     .then((address) => {
                     if (isLookupAllOptions(options)) {
-                        callback(null, [{ address: address.address, family: address.family }]);
+                        callback(null, [
+                            { address: address.address, family: address.family },
+                        ]);
                         return;
                     }
                     callback(null, address.address, address.family);
                 })
                     .catch((error) => {
-                    const reason = error instanceof Error ? error.message : "dns_resolution_failed";
+                    const reason = error instanceof Error
+                        ? error.message
+                        : "dns_resolution_failed";
                     callback(new Error(reason), "", 4);
                 });
             },
@@ -693,7 +815,10 @@ function safeFetchOnce(url, security, signal) {
                 ? res.headers["content-type"][0]
                 : res.headers["content-type"];
             const status = res.statusCode ?? 0;
-            if (status >= 200 && status < 300 && contentType && !isWorkflowWebTextContentType(contentType)) {
+            if (status >= 200 &&
+                status < 300 &&
+                contentType &&
+                !isWorkflowWebTextContentType(contentType)) {
                 res.resume();
                 settle({ ok: false, reason: "unsupported_content_type", url });
                 return;
@@ -772,7 +897,10 @@ async function validateResolvedHost(url, security) {
         return { ok: false, reason: "invalid_url", url };
     }
     try {
-        const addresses = await lookup(parsed.hostname, { all: true, verbatim: true });
+        const addresses = await lookup(parsed.hostname, {
+            all: true,
+            verbatim: true,
+        });
         for (const address of addresses) {
             const reason = privateIpReason(address.address);
             if (reason)
@@ -800,7 +928,8 @@ function privateIpReason(address) {
     }
     if (isIP(lower) === 4) {
         const parts = lower.split(".").map((part) => Number(part));
-        if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255))
+        if (parts.length !== 4 ||
+            parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255))
             return "private_host_blocked";
         const [a, b, c, d] = parts;
         if (a === 0 || a === 10 || a === 127 || a >= 224)
@@ -961,7 +1090,9 @@ function fetchSourceRequestsFromParams(params) {
     const titles = Array.isArray(params.titles) ? params.titles : [];
     if (Array.isArray(params.sources)) {
         for (const source of params.sources) {
-            if (!isRecord(source) || typeof source.url !== "string" || !source.url.trim())
+            if (!isRecord(source) ||
+                typeof source.url !== "string" ||
+                !source.url.trim())
                 continue;
             requests.push({
                 url: source.url.trim(),
@@ -978,7 +1109,9 @@ function fetchSourceRequestsFromParams(params) {
             const title = titles[index];
             requests.push({
                 url: url.trim(),
-                ...(typeof title === "string" && title.trim() ? { title: title.trim() } : {}),
+                ...(typeof title === "string" && title.trim()
+                    ? { title: title.trim() }
+                    : {}),
             });
         }
     }
@@ -1086,12 +1219,18 @@ function dedupeSourceReadRequests(requests) {
     return deduped;
 }
 function sourceReadBatchRequested(params) {
-    return ((isRecord(params) && Array.isArray(params.reads) && params.reads.length > 0) ||
+    return ((isRecord(params) &&
+        Array.isArray(params.reads) &&
+        params.reads.length > 0) ||
         stringArrayParam(params, "queries").length > 0 ||
         stringArrayParam(params, "exactTexts").length > 0 ||
         stringArrayParam(params, "texts").length > 0);
 }
 function sourceReadResponseStatus(read) {
+    if (read.status === "truncated" && !read.quote)
+        return "budget_exhausted";
+    if (read.status === "truncated")
+        return "truncated";
     if (read.status === "matched" && !read.quote)
         return "budget_exhausted";
     if (read.status === "matched" && read.candidateOnly)
@@ -1105,6 +1244,8 @@ function aggregateSourceReadStatus(statuses) {
         return "ok";
     if (statuses.every((status) => status === "candidate"))
         return "candidate";
+    if (statuses.every((status) => status === "truncated"))
+        return "truncated";
     if (statuses.every((status) => status === "not_found"))
         return "not_found";
     if (statuses.every((status) => status === "budget_exhausted"))
@@ -1140,7 +1281,8 @@ function isWorkflowWebTextContentType(contentType) {
     return /^(text\/|application\/(json|xml|xhtml\+xml|ld\+json)|[^;]+\+json\b|[^;]+\+xml\b)/i.test(contentType.trim());
 }
 function extractWorkflowWebResponseText(text, contentType) {
-    const looksHtml = /html/i.test(contentType ?? "") || /<html[\s>]|<body[\s>]|<title[\s>]/i.test(text);
+    const looksHtml = /html/i.test(contentType ?? "") ||
+        /<html[\s>]|<body[\s>]|<title[\s>]/i.test(text);
     if (!looksHtml) {
         return { text, title: titleFromPlainText(text) };
     }

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

@@ -67,7 +67,7 @@ export interface WorkflowWebSourceReadRequest {
     maxChars?: number;
 }
 export interface WorkflowWebSourceReadResult {
-    status: "matched" | "not_found";
+    status: "matched" | "truncated" | "not_found";
     matchType?: "exact" | "normalized" | "terms";
     quote?: string;
     startOffset?: number;
@@ -77,6 +77,7 @@ export interface WorkflowWebSourceReadResult {
     missingTerms?: string[];
     coverageRatio?: number;
     candidateOnly?: boolean;
+    truncated?: boolean;
 }
 export interface WorkflowWebSourceCard {
     sourceRef: string;