@jini-ai/agentic 0.4.4 → 0.4.5

package/dist/core/gen-ui/encoder.js

@@ -1,3 +1,13 @@
+/** `stage_start` / `stage_end` share one shape; `iteration` is omitted entirely (not set to `undefined`) when absent. */
+function encodeStage(payload, base) {
+    return {
+        ...base,
+        kind: 'run.lifecycle',
+        status: payload.type === 'stage_start' ? 'pipeline_stage_started' : 'pipeline_stage_completed',
+        stageId: payload.stageId,
+        ...(payload.iteration !== undefined ? { iteration: payload.iteration } : {}),
+    };
+}
 /**
  * Creates a fresh `GenUiEncoder` with its own, empty tool-call correlation map.
  * @complexity `encode` is O(1) per call (one `Map` get/set/delete); memory is O(k) in the number
@@ -10,6 +20,24 @@ export function createGenUiEncoder({ clock }, _optional = {}) {
         const ts = ctx.now ? ctx.now({}) : clock.nowMs();
         return ctx.seq !== undefined ? { runId: ctx.runId, ts, seq: ctx.seq } : { runId: ctx.runId, ts };
     }
+    /** Resolves a `tool_result` against (and removes) its correlated `tool_use`. */
+    function encodeToolResult(payload, base) {
+        const pending = pendingToolCalls.get(payload.toolUseId);
+        pendingToolCalls.delete(payload.toolUseId);
+        return {
+            ...base,
+            kind: 'tool_call',
+            // A tool_result with no matching prior tool_use (never observed, or already resolved/
+            // cleared — e.g. after a run-ending 'end' event, see below) falls back to an 'unknown'
+            // name and null args rather than throwing: the result itself is still real and worth
+            // relaying even when its originating call wasn't captured.
+            toolName: pending?.toolName ?? 'unknown',
+            args: pending?.args ?? null,
+            callId: payload.toolUseId,
+            status: payload.isError ? 'failed' : 'completed',
+            result: payload.content,
+        };
+    }
     function encodeAgentPayload(payload, ctx) {
         const base = baseFields(ctx);
         switch (payload.type) {
@@ -21,42 +49,14 @@ export function createGenUiEncoder({ clock }, _optional = {}) {
                 // and there is no protocol-level guarantee ids are never reused within one run.
                 pendingToolCalls.set(payload.id, { toolName: payload.name, args: payload.input });
                 return { ...base, kind: 'tool_call', toolName: payload.name, args: payload.input, callId: payload.id, status: 'started' };
-            case 'tool_result': {
-                const pending = pendingToolCalls.get(payload.toolUseId);
-                pendingToolCalls.delete(payload.toolUseId);
-                return {
-                    ...base,
-                    kind: 'tool_call',
-                    // A tool_result with no matching prior tool_use (never observed, or already resolved/
-                    // cleared — e.g. after a run-ending 'end' event, see below) falls back to an 'unknown'
-                    // name and null args rather than throwing: the result itself is still real and worth
-                    // relaying even when its originating call wasn't captured.
-                    toolName: pending?.toolName ?? 'unknown',
-                    args: pending?.args ?? null,
-                    callId: payload.toolUseId,
-                    status: payload.isError ? 'failed' : 'completed',
-                    result: payload.content,
-                };
-            }
+            case 'tool_result':
+                return encodeToolResult(payload, base);
             // Generalization (see archived provenance ledger): pipeline_stage_started/completed generalized into a
             // named-stage boundary any multi-step driver can emit, flowing through the same 'agent'
             // channel as tool_use/tool_result.
             case 'stage_start':
-                return {
-                    ...base,
-                    kind: 'run.lifecycle',
-                    status: 'pipeline_stage_started',
-                    stageId: payload.stageId,
-                    ...(payload.iteration !== undefined ? { iteration: payload.iteration } : {}),
-                };
             case 'stage_end':
-                return {
-                    ...base,
-                    kind: 'run.lifecycle',
-                    status: 'pipeline_stage_completed',
-                    stageId: payload.stageId,
-                    ...(payload.iteration !== undefined ? { iteration: payload.iteration } : {}),
-                };
+                return encodeStage(payload, base);
             // Generalization (see archived provenance ledger): genui_surface_request/response generalized into a
             // generic human-in-the-loop ask/answer pair.
             case 'surface_request':

package/dist/core/guards.js

@@ -81,6 +81,13 @@ export function findFieldReadRefusal({ field }, _optional = {}) {
     const type = field.type?.toLowerCase();
     if (type !== undefined && DENIED_TYPES.has(type))
         return 'denied-type';
+    if (hasDeniedAutocomplete({ field }))
+        return 'denied-autocomplete';
+    if (hasSuspiciousFieldName({ field }))
+        return 'suspicious-name';
+    return null;
+}
+function hasDeniedAutocomplete({ field }, _optional = {}) {
     const autocomplete = field.autocomplete?.toLowerCase();
     if (autocomplete !== undefined) {
         // The real grammar is space-separated tokens, but a comma-joined value
@@ -90,10 +97,13 @@ export function findFieldReadRefusal({ field }, _optional = {}) {
         // worked as a plain text input while looking unguarded.
         for (const token of autocomplete.split(/[\s,]+/)) {
             if (DENIED_AUTOCOMPLETE.has(token))
-                return 'denied-autocomplete';
+                return true;
         }
     }
-    if (SUSPICIOUS_NAME.test(squashSeparators(field.name ?? ''))
+    return false;
+}
+function hasSuspiciousFieldName({ field }, _optional = {}) {
+    return (SUSPICIOUS_NAME.test(squashSeparators(field.name ?? ''))
         || SUSPICIOUS_NAME.test(squashSeparators(field.id ?? ''))
         // `name`/`id` are the *machine* names; a form builder or CMS that emits `name="field_47"`
         // next to a visible "Card number" label left the guard nothing to judge until this existed.
@@ -102,10 +112,7 @@ export function findFieldReadRefusal({ field }, _optional = {}) {
         // deletes the separators, so a join would let two innocuous labels form a trigger word across
         // their boundary ("Address" + "Snapshot" -> "addresssnapshot", which contains "ssn"). This
         // guard is deliberately over-inclusive, but not at the cost of matching text no page wrote.
-        || (field.accessibleLabels ?? []).some((label) => SUSPICIOUS_NAME.test(squashSeparators(label)))) {
-        return 'suspicious-name';
-    }
-    return null;
+        || (field.accessibleLabels ?? []).some((label) => SUSPICIOUS_NAME.test(squashSeparators(label))));
 }
 /**
  * Why an automated fill must be refused for this field, or `null` when it is safe to write.

package/dist/core/mcp-ui-apps.js

@@ -194,14 +194,10 @@ export function isJsonRpcMessage(required, _optional = {}) {
     const { value } = required;
     if (!isRecord(value) || value['jsonrpc'] !== '2.0')
         return false;
-    if ('id' in value && typeof value['id'] !== 'number' && typeof value['id'] !== 'string')
+    if (!hasValidJsonRpcId({ value }))
         return false;
     if ('method' in value) {
-        // Request or notification: `id` present or not, but never a response's members alongside.
-        return typeof value['method'] === 'string'
-            && hasValidParams(value)
-            && !('result' in value)
-            && !('error' in value);
+        return isJsonRpcCallShape({ value });
     }
     // Response: correlated by `id`, carrying exactly one of `result` / `error`.
     if (!('id' in value))
@@ -212,6 +208,16 @@ export function isJsonRpcMessage(required, _optional = {}) {
         return false;
     return hasResult || isJsonRpcErrorObject(value['error']);
 }
+function hasValidJsonRpcId({ value }, _optional = {}) {
+    return !('id' in value) || typeof value['id'] === 'number' || typeof value['id'] === 'string';
+}
+function isJsonRpcCallShape({ value }, _optional = {}) {
+    // Request or notification: `id` present or not, but never a response's members alongside.
+    return typeof value['method'] === 'string'
+        && hasValidParams(value)
+        && !('result' in value)
+        && !('error' in value);
+}
 /** Whether a validated message expects a response (as opposed to being a notification). */
 export function isJsonRpcRequest(required, _optional = {}) {
     const { message } = required;

package/dist/core/page-executor.js

@@ -11,7 +11,7 @@
  * Nothing here touches the DOM. That is what makes the interesting half testable without a
  * browser: "does it refuse to type into a password box" is a unit test, not an integration test.
  */
-import { findCapabilityInputError, } from './capability.js';
+import { findCapability, findCapabilityInputError, } from './capability.js';
 import { AGENT_ELEMENT_ROLES, isValidElementHandle, } from './element-handles.js';
 import { describeFieldReadRefusal, describeFieldRefusal, findFieldFillRefusal, findFieldReadRefusal, normalizeAgentLabel, } from './guards.js';
 import { PAGE_CAPABILITIES } from './page-capabilities.js';
@@ -69,19 +69,28 @@ export function projectElementState({ raw }, _optional = {}) {
     // what the option is called; withholding the label too would blind a caller to the page's own
     // ontology for no reduction in what actually leaks.
     const refusal = raw.field !== undefined ? findFieldReadRefusal({ field: raw.field }) : null;
+    const withheldText = findWithheldText({ raw, refusal });
+    const base = {
+        text: withheldText === undefined ? text.text : '',
+        textTruncated: withheldText === undefined ? text.truncated : false,
+        ...(withheldText !== undefined ? { textWithheld: withheldText } : {}),
+        ...projectOptionalState({ raw, refusal }),
+    };
+    return projectFieldValue({ raw, refusal, base });
+}
+function findWithheldText({ raw, refusal }, _optional = {}) {
     // The one element whose `text` is NOT page-authored chrome: an editable region, whose contents
     // are the user's data and whose driver has no `value` to report them as. It is gated by exactly
     // the rules `value` is gated by below, including the "arrived with nothing to check it against"
     // one — an unverifiable secret is withheld, not trusted.
-    const withheldText = raw.textIsValue !== true
+    return raw.textIsValue !== true
         ? undefined
         : raw.field === undefined
             ? 'this element reported contents without the attributes needed to check them for secrets'
             : refusal !== null ? describeFieldReadRefusal({ refusal }) : undefined;
-    const base = {
-        text: withheldText === undefined ? text.text : '',
-        textTruncated: withheldText === undefined ? text.truncated : false,
-        ...(withheldText !== undefined ? { textWithheld: withheldText } : {}),
+}
+function projectOptionalState({ raw, refusal }, _optional = {}) {
+    return {
         ...(raw.checked !== undefined && refusal === null ? { checked: raw.checked } : {}),
         ...(raw.disabled !== undefined ? { disabled: raw.disabled } : {}),
         ...(raw.visible !== undefined ? { visible: raw.visible } : {}),
@@ -91,6 +100,8 @@ export function projectElementState({ raw }, _optional = {}) {
             ? { options: raw.options.map((option) => normalizeAgentLabel({ raw: option }).text) }
             : {}),
     };
+}
+function projectFieldValue({ raw, refusal, base }, _optional = {}) {
     if (raw.value === undefined)
         return base;
     if (raw.field === undefined) {
@@ -176,66 +187,10 @@ async function summarizePage(driver) {
  * purpose: a caller must be told why, not handed a silent no-op it will retry forever.
  */
 export async function executePageCapability({ driver, capabilityId, input }, _optional = {}) {
-    const capability = PAGE_CAPABILITIES.find((entry) => entry.id === capabilityId);
-    if (capability === undefined)
-        throw new Error(`unknown page capability: ${capabilityId}`);
-    const inputError = findCapabilityInputError({ capability, input });
-    if (inputError !== null) {
-        // The schema rides along with the refusal rather than making a caller spend a second
-        // round trip on describe_tool to learn what it already tried to guess — ai-control-plane.md
-        // §29.4's "schema-on-error" requirement, empirically forced by a real run: page.fill was
-        // called with `handle` instead of the argument's old name, `element`, twice before the caller
-        // gave up and looked the schema up separately. One JSON-Schema object, embedded once, turned
-        // that into a same-turn self-correction for every page.* verb this gate guards, not just the
-        // one that got measured — self-correction is why that mismatch was survivable at all, given
-        // every verb here needs a handle from `page.find_elements`, whose own response has always
-        // called this same value `handle` (`AgentElementDescriptor.handle`). The argument itself was
-        // later renamed from `element` to `handle` to match, closing the gap this comment describes
-        // rather than merely papering over it turn by turn.
-        throw new Error(`${capabilityId}: ${inputError}. Expected input: ${JSON.stringify(capability.inputSchema)}`);
-    }
+    validatePageCapability({ capabilityId, input });
     switch (capabilityId) {
-        case 'page.find_elements': {
-            const role = input['role'];
-            // The schema's enum check has already run; this narrows the type for the driver.
-            const filter = {
-                ...(isAgentElementRole(role) ? { role } : {}),
-                ...(typeof input['query'] === 'string' ? { query: input['query'] } : {}),
-            };
-            const [found, rawPages] = await Promise.all([driver.findElements({}, filter), driver.listPages({})]);
-            const withState = input['withState'] === true;
-            const observing = withState && driver.describeState !== undefined;
-            const elements = await Promise.all(found.map(async (element, index) => {
-                const label = normalizeAgentLabel({ raw: element.label });
-                const base = {
-                    handle: element.handle,
-                    role: element.role,
-                    label: label.text,
-                    labelTruncated: label.truncated,
-                    page: element.page,
-                };
-                if (!observing || index >= MAX_STATEFUL_ELEMENTS)
-                    return base;
-                const state = await observeElement(driver, element.handle);
-                return state === undefined ? base : { ...base, state };
-            }));
-            // `label` is page-authored the same way an element's is — bounded here for the same reason
-            // `page.navigate`'s refusal message bounds it below, rather than trusting a host to have kept
-            // every `data-agent-page` label short and clean.
-            const pages = rawPages.map((page) => ({
-                id: page.id,
-                label: normalizeAgentLabel({ raw: page.label }).text,
-            }));
-            return {
-                elements,
-                pages,
-                untrustedFields: observing
-                    ? ['elements[].label', 'elements[].state.text', 'elements[].state.value', 'pages[].label']
-                    : ['elements[].label', 'pages[].label'],
-                ...(withState && !observing ? { stateUnavailable: true } : {}),
-                ...(observing && found.length > MAX_STATEFUL_ELEMENTS ? { stateTruncated: true } : {}),
-            };
-        }
+        case 'page.find_elements':
+            return findPageElements({ driver, input });
         case 'page.highlight': {
             const handle = requireHandle(input, 'handle');
             const durationMs = clampHighlightDuration(input['durationMs']);
@@ -252,30 +207,15 @@ export async function executePageCapability({ driver, capabilityId, input }, _op
             const observation = await observeWrite(driver, handle, () => driver.click({ handle }));
             return { clicked: handle, ...observation };
         }
-        case 'page.fill': {
-            const handle = requireHandle(input, 'handle');
-            // Declared required and typed `string` in the manifest, and `findCapabilityInputError`
-            // enforced both above — re-checking here would be an unreachable branch, not a safeguard.
-            const text = input['text'];
-            // Ask the page what this field actually is before writing to it. A handle proves the page
-            // published the element; it says nothing about whether it holds a password.
-            const field = await driver.describeField({ handle });
-            if (field === null)
-                throw new Error(`"${handle}" is not a fillable field`);
-            const refusal = findFieldFillRefusal({ field });
-            if (refusal !== null) {
-                throw new Error(`refusing to fill "${handle}": ${describeFieldRefusal({ refusal })}`);
-            }
-            const observation = await observeWrite(driver, handle, () => driver.fill({ handle, text }));
-            return { filled: handle, ...observation };
-        }
+        case 'page.fill':
+            return fillPageField({ driver, input });
         case 'page.select_option': {
             const handle = requireHandle(input, 'handle');
             // Required and string-typed by the manifest, already enforced above. See page.fill.
             const option = input['option'];
             // Optional and boolean-typed by the manifest; absent means "select it", same as before this
             // argument existed.
-            const selected = input['selected'] === false ? false : true;
+            const selected = input['selected'] !== false;
             // No field guard: a dropdown's options are authored by the page, so choosing one reveals
             // nothing the page had not already published, and none of the credential field types this
             // surface refuses can be a `<select>`.
@@ -284,37 +224,117 @@ export async function executePageCapability({ driver, capabilityId, input }, _op
             // "the handle this call acted on" for every verb in this switch (`clicked`, `filled`, …).
             return { selected: handle, option, optionSelected: selected, ...observation };
         }
-        case 'page.navigate': {
-            // Required and string-typed by the manifest, already enforced above. See page.fill.
-            const page = input['page'];
-            const pages = await driver.listPages({});
-            if (!pages.some((candidate) => candidate.id === page)) {
-                // Every other piece of page-authored (or, here, caller-authored-but-page-shaped) text
-                // this system hands to a model goes through normalizeAgentLabel first — bounded, control-
-                // and bidi-stripped. This refusal was the one path that skipped it: the raw `page`
-                // argument, and the `pages` this host actually publishes (itself read verbatim off
-                // `data-agent-page` attributes with no length bound), were interpolated straight into the
-                // thrown message. A 5000+-char bidi payload survived verbatim as a result. The lookup
-                // above still runs on the raw values — only the text that reaches the message is bounded.
-                //
-                // `id (label)`, not just the id: a refusal is the one moment a caller that guessed wrong
-                // is looking straight at the real menu, so it is worth spending the label here even though
-                // `page.find_elements` already carries the same information — a caller that jumped
-                // straight to `page.navigate` without calling that first still lands on the right id.
-                const safePage = normalizeAgentLabel({ raw: page }).text;
-                const safePages = pages.map((candidate) => `${normalizeAgentLabel({ raw: candidate.id }).text} (${normalizeAgentLabel({ raw: candidate.label }).text})`);
-                throw new Error(`"${safePage}" is not a published page. Available: ${safePages.length > 0 ? safePages.join(', ') : '(none)'}`);
-            }
-            const before = await summarizePage(driver);
-            await driver.navigate({ page });
-            if (driver.settle !== undefined)
-                await driver.settle({});
-            const after = await summarizePage(driver);
-            return { navigatedTo: page, before, after };
-        }
+        case 'page.navigate':
+            return navigatePage({ driver, input });
         /* c8 ignore next 2 -- unreachable: the id was matched against PAGE_CAPABILITIES above. */
         default:
             throw new Error(`unhandled page capability: ${capabilityId}`);
     }
 }
+function validatePageCapability({ capabilityId, input }, _optional = {}) {
+    const capability = findCapability({ capabilities: PAGE_CAPABILITIES, id: capabilityId });
+    if (capability === undefined)
+        throw new Error(`unknown page capability: ${capabilityId}`);
+    const inputError = findCapabilityInputError({ capability, input });
+    if (inputError !== null) {
+        // The schema rides along with the refusal rather than making a caller spend a second
+        // round trip on describe_tool to learn what it already tried to guess — ai-control-plane.md
+        // §29.4's "schema-on-error" requirement, empirically forced by a real run: page.fill was
+        // called with `handle` instead of the argument's old name, `element`, twice before the caller
+        // gave up and looked the schema up separately. One JSON-Schema object, embedded once, turned
+        // that into a same-turn self-correction for every page.* verb this gate guards, not just the
+        // one that got measured — self-correction is why that mismatch was survivable at all, given
+        // every verb here needs a handle from `page.find_elements`, whose own response has always
+        // called this same value `handle` (`AgentElementDescriptor.handle`). The argument itself was
+        // later renamed from `element` to `handle` to match, closing the gap this comment describes
+        // rather than merely papering over it turn by turn.
+        throw new Error(`${capabilityId}: ${inputError}. Expected input: ${JSON.stringify(capability.inputSchema)}`);
+    }
+}
+async function findPageElements({ driver, input }, _optional = {}) {
+    const role = input['role'];
+    // The schema's enum check has already run; this narrows the type for the driver.
+    const filter = {
+        ...(isAgentElementRole(role) ? { role } : {}),
+        ...(typeof input['query'] === 'string' ? { query: input['query'] } : {}),
+    };
+    const [found, rawPages] = await Promise.all([driver.findElements({}, filter), driver.listPages({})]);
+    const withState = input['withState'] === true;
+    const observing = withState && driver.describeState !== undefined;
+    const elements = await Promise.all(found.map(async (element, index) => {
+        const label = normalizeAgentLabel({ raw: element.label });
+        const base = {
+            handle: element.handle,
+            role: element.role,
+            label: label.text,
+            labelTruncated: label.truncated,
+            page: element.page,
+        };
+        if (!observing || index >= MAX_STATEFUL_ELEMENTS)
+            return base;
+        const state = await observeElement(driver, element.handle);
+        return state === undefined ? base : { ...base, state };
+    }));
+    // `label` is page-authored the same way an element's is — bounded here for the same reason
+    // `page.navigate`'s refusal message bounds it below, rather than trusting a host to have kept
+    // every `data-agent-page` label short and clean.
+    const pages = rawPages.map((page) => ({
+        id: page.id,
+        label: normalizeAgentLabel({ raw: page.label }).text,
+    }));
+    return {
+        elements,
+        pages,
+        untrustedFields: observing
+            ? ['elements[].label', 'elements[].state.text', 'elements[].state.value', 'pages[].label']
+            : ['elements[].label', 'pages[].label'],
+        ...(withState && !observing ? { stateUnavailable: true } : {}),
+        ...(observing && found.length > MAX_STATEFUL_ELEMENTS ? { stateTruncated: true } : {}),
+    };
+}
+async function fillPageField({ driver, input }, _optional = {}) {
+    const handle = requireHandle(input, 'handle');
+    // Declared required and typed `string` in the manifest, and `findCapabilityInputError`
+    // enforced both above — re-checking here would be an unreachable branch, not a safeguard.
+    const text = input['text'];
+    // Ask the page what this field actually is before writing to it. A handle proves the page
+    // published the element; it says nothing about whether it holds a password.
+    const field = await driver.describeField({ handle });
+    if (field === null)
+        throw new Error(`"${handle}" is not a fillable field`);
+    const refusal = findFieldFillRefusal({ field });
+    if (refusal !== null) {
+        throw new Error(`refusing to fill "${handle}": ${describeFieldRefusal({ refusal })}`);
+    }
+    const observation = await observeWrite(driver, handle, () => driver.fill({ handle, text }));
+    return { filled: handle, ...observation };
+}
+async function navigatePage({ driver, input }, _optional = {}) {
+    // Required and string-typed by the manifest, already enforced above. See page.fill.
+    const page = input['page'];
+    const pages = await driver.listPages({});
+    if (!pages.some((candidate) => candidate.id === page)) {
+        // Every other piece of page-authored (or, here, caller-authored-but-page-shaped) text
+        // this system hands to a model goes through normalizeAgentLabel first — bounded, control-
+        // and bidi-stripped. This refusal was the one path that skipped it: the raw `page`
+        // argument, and the `pages` this host actually publishes (itself read verbatim off
+        // `data-agent-page` attributes with no length bound), were interpolated straight into the
+        // thrown message. A 5000+-char bidi payload survived verbatim as a result. The lookup
+        // above still runs on the raw values — only the text that reaches the message is bounded.
+        //
+        // `id (label)`, not just the id: a refusal is the one moment a caller that guessed wrong
+        // is looking straight at the real menu, so it is worth spending the label here even though
+        // `page.find_elements` already carries the same information — a caller that jumped
+        // straight to `page.navigate` without calling that first still lands on the right id.
+        const safePage = normalizeAgentLabel({ raw: page }).text;
+        const safePages = pages.map((candidate) => `${normalizeAgentLabel({ raw: candidate.id }).text} (${normalizeAgentLabel({ raw: candidate.label }).text})`);
+        throw new Error(`"${safePage}" is not a published page. Available: ${safePages.length > 0 ? safePages.join(', ') : '(none)'}`);
+    }
+    const before = await summarizePage(driver);
+    await driver.navigate({ page });
+    if (driver.settle !== undefined)
+        await driver.settle({});
+    const after = await summarizePage(driver);
+    return { navigatedTo: page, before, after };
+}
 //# sourceMappingURL=page-executor.js.map

package/dist/core/site-guide/site-guide.js

@@ -62,83 +62,101 @@ export function createSiteGuide(ports, options = {}) {
     if (builtIns.length > 256 || new Set(builtIns.map(topic => topic.id)).size !== builtIns.length)
         throw new SiteGuideInputError({ message: 'Built-in topics must have unique ids and contain at most 256 cards' });
     return { async run(input, _options = {}) {
-            if (input.operation !== 'overview' && input.operation !== 'explain')
-                throw new SiteGuideInputError({ message: 'operation must be overview or explain' });
-            if (input.operation === 'overview' && input.topic !== undefined)
-                throw new SiteGuideInputError({ message: 'topic is only accepted with operation explain' });
-            if (input.operation === 'explain' && (typeof input.topic !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(input.topic))) {
-                throw new SiteGuideInputError({ message: 'explain requires a topic id from overview' });
-            }
-            let contributions = [];
-            let enrichment = 'ok';
-            if (ports.loadContributions) {
-                try {
-                    const loaded = await boundedRead(() => ports.loadContributions({ caller: input.caller }), timeoutMs);
-                    if (loaded.items.reduce((count, item) => count + item.topics.length, 0) > 256)
-                        throw new SiteGuideInputError({ message: 'Too many contributed topics' });
-                    contributions = loaded.items;
-                    if (loaded.refusals.length)
-                        enrichment = 'partial';
-                }
-                catch {
-                    enrichment = 'unavailable';
-                }
-            }
-            const combined = combineTopics(builtIns, contributions);
-            if (combined.conflicts)
-                enrichment = 'partial';
-            const decisions = new Map();
-            const allowed = (permission) => {
-                let decision = decisions.get(permission);
-                if (!decision) {
-                    // Failed authorization is denial, never an excuse to expose a card or run its read.
-                    decision = boundedRead(() => ports.authorize({ caller: input.caller, permission }), timeoutMs).catch(() => false);
-                    decisions.set(permission, decision);
-                }
-                return decision;
-            };
-            const permitted = async (permissions) => (await Promise.all(permissions.map(allowed))).every(Boolean);
-            const views = [];
-            for (const entry of combined.topics) {
-                if (input.operation === 'explain' && entry.topic.id !== input.topic)
-                    continue;
-                if (!await permitted(entry.topic.permissions))
-                    continue;
-                const view = { id: entry.topic.id, title: entry.topic.title, summary: entry.topic.summary, source: entry.source };
-                if (input.operation === 'explain') {
-                    const pointers = [];
-                    for (const { permissions, ...pointer } of entry.topic.pointers)
-                        if (await permitted(permissions))
-                            pointers.push(pointer);
-                    const workflows = [];
-                    for (const { permissions, ...workflow } of entry.topic.workflows)
-                        if (await permitted(permissions))
-                            workflows.push(workflow);
-                    views.push({ ...view, explanation: entry.topic.explanation, pointers, workflows });
-                }
-                else
-                    views.push(view);
-            }
+            assertGuideInput(input);
+            const loaded = await loadContributions({ ports, caller: input.caller, timeoutMs });
+            const combined = combineTopics(builtIns, loaded.contributions);
+            const enrichment = combined.conflicts ? 'partial' : loaded.enrichment;
+            const gate = createPermissionGate({ ports, caller: input.caller, timeoutMs });
+            const views = await buildViews({ topics: combined.topics, input, permitted: gate.permitted });
             if (input.operation === 'explain' && views.length === 0)
                 throw new SiteGuideInputError({ message: 'Topic unavailable. Call site_guide with operation overview for topics you may read.' });
-            let facts = {};
-            const topicIds = views.map(view => view.id);
             // Overview is discovery only; read fresh domain facts when a visible topic is explained.
-            if (input.operation === 'explain') {
-                try {
-                    const read = await boundedRead(() => ports.facts.read({ caller: input.caller, topics: topicIds }), timeoutMs);
-                    // A facts adapter returning an unrelated section cannot disclose it through this tool.
-                    facts = Object.fromEntries(topicIds.map(id => [id, read[id] ?? { status: 'unavailable' }]));
-                }
-                catch {
-                    facts = Object.fromEntries(topicIds.map(id => [id, { status: 'unavailable' }]));
-                }
-            }
+            const facts = input.operation === 'explain' ? await readFacts({ ports, caller: input.caller, topicIds: views.map(view => view.id), timeoutMs }) : {};
+            return { operation: input.operation, topics: views, facts, callerPermissions: await gate.granted(), enrichment };
+        } };
+}
+/** Refuses unknown operations, a topic on overview, and explain without a well-formed topic id. */
+function assertGuideInput(input) {
+    if (input.operation !== 'overview' && input.operation !== 'explain')
+        throw new SiteGuideInputError({ message: 'operation must be overview or explain' });
+    if (input.operation === 'overview' && input.topic !== undefined)
+        throw new SiteGuideInputError({ message: 'topic is only accepted with operation explain' });
+    if (input.operation === 'explain' && (typeof input.topic !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(input.topic))) {
+        throw new SiteGuideInputError({ message: 'explain requires a topic id from overview' });
+    }
+}
+/** Reads plugin contributions within the deadline; any failure or over-limit result degrades to none. */
+async function loadContributions({ ports, caller, timeoutMs }) {
+    if (!ports.loadContributions)
+        return { contributions: [], enrichment: 'ok' };
+    try {
+        const loaded = await boundedRead(() => ports.loadContributions({ caller }), timeoutMs);
+        if (loaded.items.reduce((count, item) => count + item.topics.length, 0) > 256)
+            throw new SiteGuideInputError({ message: 'Too many contributed topics' });
+        return { contributions: loaded.items, enrichment: loaded.refusals.length ? 'partial' : 'ok' };
+    }
+    catch {
+        return { contributions: [], enrichment: 'unavailable' };
+    }
+}
+/** Per-request authorization cache: each permission is asked at most once, in first-use order. */
+function createPermissionGate({ ports, caller, timeoutMs }) {
+    const decisions = new Map();
+    const allowed = (permission) => {
+        let decision = decisions.get(permission);
+        if (!decision) {
+            // Failed authorization is denial, never an excuse to expose a card or run its read.
+            decision = boundedRead(() => ports.authorize({ caller, permission }), timeoutMs).catch(() => false);
+            decisions.set(permission, decision);
+        }
+        return decision;
+    };
+    return {
+        permitted: async (permissions) => (await Promise.all(permissions.map(allowed))).every(Boolean),
+        granted: async () => {
             const callerPermissions = [];
             for (const [permission, decision] of decisions)
                 if (await decision)
                     callerPermissions.push(permission);
-            return { operation: input.operation, topics: views, facts, callerPermissions, enrichment };
-        } };
+            return callerPermissions;
+        },
+    };
+}
+/** Visible cards in topic order; explain narrows to the requested id and adds its permitted details. */
+async function buildViews({ topics, input, permitted }) {
+    const views = [];
+    for (const entry of topics) {
+        if (input.operation === 'explain' && entry.topic.id !== input.topic)
+            continue;
+        if (!await permitted(entry.topic.permissions))
+            continue;
+        const view = { id: entry.topic.id, title: entry.topic.title, summary: entry.topic.summary, source: entry.source };
+        views.push(input.operation === 'explain' ? await explainView({ view, topic: entry.topic, permitted }) : view);
+    }
+    return views;
+}
+async function explainView({ view, topic, permitted }) {
+    const pointers = await withoutForbidden({ items: topic.pointers, permitted });
+    const workflows = await withoutForbidden({ items: topic.workflows, permitted });
+    return { ...view, explanation: topic.explanation, pointers, workflows };
+}
+/** Keeps items whose permissions are all granted, asked one item at a time, minus their gates. */
+async function withoutForbidden({ items, permitted }) {
+    const kept = [];
+    for (const { permissions, ...item } of items)
+        if (await permitted(permissions))
+            kept.push(item);
+    return kept;
+}
+/** One bulk facts read for the visible topics; failure marks each of them unavailable. */
+async function readFacts({ ports, caller, topicIds, timeoutMs }) {
+    try {
+        const read = await boundedRead(() => ports.facts.read({ caller, topics: topicIds }), timeoutMs);
+        // A facts adapter returning an unrelated section cannot disclose it through this tool.
+        return Object.fromEntries(topicIds.map(id => [id, read[id] ?? { status: 'unavailable' }]));
+    }
+    catch {
+        return Object.fromEntries(topicIds.map(id => [id, { status: 'unavailable' }]));
+    }
 }
 //# sourceMappingURL=site-guide.js.map