@agwab/pi-workflow 0.2.0 → 0.3.0

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,
             });
         },
     });
@@ -596,7 +679,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 +706,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 +723,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 +770,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 +792,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 +874,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 +905,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 +1067,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 +1086,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 +1196,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 +1221,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 +1258,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;

package/dist/workflow-web-source.js

@@ -526,19 +526,32 @@ function snippetForTerms(options) {
             return right.score - left.score;
         return right.matchedTerms.length - left.matchedTerms.length;
     })[0];
-    const raw = redactInlineSecrets(options.text.slice(best.start, best.end));
-    const consumed = consumeWorkflowWebVisibleBudget(options.budget, raw, options.maxChars);
+    const consumed = consumeAnchoredSnippet({
+        text: options.text,
+        anchorStart: best.anchorStart,
+        anchorEnd: best.anchorEnd,
+        maxChars: options.maxChars,
+        budget: options.budget,
+    });
+    const returnedWindowNorm = normalizeForSearch(options.text.slice(consumed.sourceStart, consumed.sourceEnd)).normalized;
+    const matchedTerms = needles
+        .filter((term) => returnedWindowNorm.includes(term.normalized))
+        .map((term) => term.raw);
+    const missingTerms = needles
+        .filter((term) => !returnedWindowNorm.includes(term.normalized))
+        .map((term) => term.raw);
     return {
-        status: "matched",
+        status: consumed.status,
         matchType: "terms",
-        quote: consumed.text,
-        startOffset: best.start,
-        endOffset: best.end,
-        visibleChars: consumed.text.length,
-        matchedTerms: best.matchedTerms,
-        missingTerms: best.missingTerms,
-        coverageRatio: best.matchedTerms.length / Math.max(1, needles.length),
+        quote: consumed.quote || undefined,
+        startOffset: consumed.sourceStart,
+        endOffset: consumed.sourceEnd,
+        visibleChars: consumed.visibleChars,
+        matchedTerms,
+        missingTerms,
+        coverageRatio: matchedTerms.length / Math.max(1, needles.length),
         candidateOnly: true,
+        truncated: consumed.truncated || undefined,
     };
 }
 function scoreTermWindow(text, matchStart, matchEnd, maxChars, terms) {
@@ -559,6 +572,8 @@ function scoreTermWindow(text, matchStart, matchEnd, maxChars, terms) {
     return {
         start,
         end,
+        anchorStart: matchStart,
+        anchorEnd: matchEnd,
         matchedTerms,
         missingTerms,
         score: matchedTerms.length * 1_000 + occurrenceScore,
@@ -631,20 +646,70 @@ const SOURCE_READ_STOPWORDS = new Set([
     "without",
 ]);
 function snippetForMatch(options) {
-    const matchLength = Math.max(0, options.end - options.start);
-    const slack = Math.max(0, options.maxChars - matchLength);
-    const before = Math.floor(slack / 2);
-    const snippetStart = Math.max(0, options.start - before);
-    const snippetEnd = Math.min(options.text.length, snippetStart + options.maxChars);
-    const raw = redactInlineSecrets(options.text.slice(snippetStart, snippetEnd));
-    const consumed = consumeWorkflowWebVisibleBudget(options.budget, raw, options.maxChars);
+    const consumed = consumeAnchoredSnippet({
+        text: options.text,
+        anchorStart: options.start,
+        anchorEnd: options.end,
+        maxChars: options.maxChars,
+        budget: options.budget,
+    });
     return {
-        status: "matched",
+        status: consumed.status,
         matchType: options.matchType,
-        quote: consumed.text,
+        quote: consumed.quote || undefined,
         startOffset: options.start,
         endOffset: options.end,
+        visibleChars: consumed.visibleChars,
+        truncated: consumed.truncated || undefined,
+    };
+}
+function consumeAnchoredSnippet(options) {
+    const maxChars = Math.max(0, Math.floor(options.maxChars));
+    const remainingBefore = Math.max(0, options.budget.limit - options.budget.used);
+    const visibleLimit = Math.max(0, Math.min(maxChars, remainingBefore));
+    const anchorStart = Math.max(0, Math.min(options.text.length, Math.floor(options.anchorStart)));
+    const anchorEnd = Math.max(anchorStart, Math.min(options.text.length, Math.floor(options.anchorEnd)));
+    const anchorLength = Math.max(0, anchorEnd - anchorStart);
+    if (visibleLimit <= 0) {
+        return {
+            status: "truncated",
+            quote: "",
+            visibleChars: 0,
+            sourceStart: anchorStart,
+            sourceEnd: anchorStart,
+            truncated: true,
+        };
+    }
+    let sourceStart;
+    let sourceEnd;
+    let status = "matched";
+    if (anchorLength > visibleLimit) {
+        sourceStart = anchorStart;
+        sourceEnd = Math.min(options.text.length, sourceStart + visibleLimit);
+        status = "truncated";
+    }
+    else {
+        const slack = Math.max(0, visibleLimit - anchorLength);
+        sourceStart = Math.max(0, anchorStart - Math.floor(slack / 2));
+        sourceEnd = Math.min(options.text.length, sourceStart + visibleLimit);
+        if (sourceEnd < anchorEnd) {
+            sourceEnd = anchorEnd;
+            sourceStart = Math.max(0, sourceEnd - visibleLimit);
+        }
+        else if (sourceEnd === options.text.length) {
+            sourceStart = Math.max(0, sourceEnd - visibleLimit);
+        }
+    }
+    const raw = redactInlineSecrets(options.text.slice(sourceStart, sourceEnd));
+    const consumed = consumeWorkflowWebVisibleBudget(options.budget, raw, visibleLimit);
+    const truncated = status === "truncated" || consumed.truncated;
+    return {
+        status,
+        quote: consumed.text,
         visibleChars: consumed.text.length,
+        sourceStart,
+        sourceEnd,
+        truncated,
     };
 }
 function normalizeForSearch(text) {

package/docs/usage.md

@@ -187,6 +187,17 @@ 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.
 
+### Opt-in fast mode
+
+For lower-latency runs, pass `--thinking low` explicitly:
+
+```text
+/workflow run --thinking low deep-research "Research this repository and summarize the architecture tradeoffs."
+/workflow dynamic --thinking low "Research this repository and summarize the architecture tradeoffs."
+```
+
+This is an opt-in fast mode. Package defaults remain conservative until a separate holdout evaluation provides enough evidence to change them. Current evidence is limited but encouraging for explicit fast runs: the 2026-07-02 `deep-research` combined gate on P1/P2/P3-style prompts resolved non-support tasks to `low`, completed selected valid runs in about 15-17 minutes, passed the strict gate 9/9, and had zero source-ref join failures across those 9 runs. Treat this as a speed option, not proof that every workflow should default to `low`.
+
 ### Run-scoped web-source cache
 
 Prefer normalized workflow web tools in new workflows:

package/node_modules/@agwab/pi-subagent/README.md

@@ -38,7 +38,6 @@ Run this check in a sandboxed worker and report the artifact paths.
 Start a background audit and let me inspect it in /subagent panel.
 ```
 
-
 ## What it does
 
 Tool: `subagent`
@@ -121,9 +120,11 @@ Existing run:
 { "action": "status", "runId": "run_..." }
 ```
 
+Recent runs can be addressed by `runId` even when they were launched from another cwd; legacy records still resolve from the explicit or current cwd.
+
 ### Panel
 
-Inspect runs, attempts, artifacts, and log tails in a live TUI.
+Inspect runs, attempts, artifacts, and log tails in a live TUI. The panel defaults to the current Pi session, can switch to current cwd or all indexed runs, and includes status filters plus a scrollable detail pane. It shows active and recent terminal runs by default, with in-panel `m` to show more, and counts stale/malformed run pointers without exposing raw session ids.
 
 Open the run monitor:
 
@@ -147,4 +148,3 @@ const status = await getSubagentStatus({ runId: run.runId });
 ## Detailed docs
 
 - [`docs/usage.md`](./docs/usage.md) — full argument reference, code API, `action` behavior, backend selection, sandbox/worktree behavior, artifacts, and validation notes.
-

package/node_modules/@agwab/pi-subagent/api.mjs

@@ -9,4 +9,5 @@ export const getSubagentLogs = api.getSubagentLogs;
 export const waitForSubagent = api.waitForSubagent;
 export const interruptSubagent = api.interruptSubagent;
 export const reconcileSubagentRun = api.reconcileSubagentRun;
+export const recordSubagentChildEvent = api.recordSubagentChildEvent;
 export const SubagentValidationError = api.SubagentValidationError;