@jini-ai/agentic 0.3.7 → 0.4.0

package/dist/core/page-executor.js

@@ -34,7 +34,7 @@ export const MAX_HIGHLIGHT_MS = 15_000;
 export const MAX_STATEFUL_ELEMENTS = 50;
 function requireHandle(input, key) {
     const value = input[key];
-    if (typeof value !== 'string' || !isValidElementHandle(value)) {
+    if (typeof value !== 'string' || !isValidElementHandle({ handle: value })) {
         throw new Error(`"${key}" must be a published element handle from page.find_elements — `
             + 'lowercase words joined by single hyphens, never a CSS selector');
     }
@@ -56,8 +56,8 @@ function isAgentElementRole(value) {
  * guard does — a secrecy rule re-derived by each driver is a secrecy rule that will eventually be
  * derived wrong. A value arriving with no descriptor to check is withheld rather than trusted.
  */
-export function projectElementState(raw) {
-    const text = normalizeAgentLabel(raw.text);
+export function projectElementState({ raw }, _optional = {}) {
+    const text = normalizeAgentLabel({ raw: raw.text });
     // Computed once, up front, so `checked` is gated by the exact same refusal as `value` below
     // rather than being copied through unconditionally. A checkbox/radio's `checked` is a second
     // secrecy channel, not a formatting detail: for a field like `health_disclosure_password`,
@@ -68,7 +68,7 @@ export function projectElementState(raw) {
     // it, exactly like a `<select>`'s `options` below. The secret is which option is checked, not
     // 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(raw.field) : null;
+    const refusal = raw.field !== undefined ? findFieldReadRefusal({ field: raw.field }) : null;
     // 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"
@@ -77,7 +77,7 @@ export function projectElementState(raw) {
         ? undefined
         : raw.field === undefined
             ? 'this element reported contents without the attributes needed to check them for secrets'
-            : refusal !== null ? describeFieldReadRefusal(refusal) : undefined;
+            : refusal !== null ? describeFieldReadRefusal({ refusal }) : undefined;
     const base = {
         text: withheldText === undefined ? text.text : '',
         textTruncated: withheldText === undefined ? text.truncated : false,
@@ -88,7 +88,7 @@ export function projectElementState(raw) {
         // Bounded like every other page-authored string, but never withheld: the options a dropdown
         // offers are part of the UI's shape, not the user's data.
         ...(raw.options !== undefined
-            ? { options: raw.options.map((option) => normalizeAgentLabel(option).text) }
+            ? { options: raw.options.map((option) => normalizeAgentLabel({ raw: option }).text) }
             : {}),
     };
     if (raw.value === undefined)
@@ -100,8 +100,8 @@ export function projectElementState(raw) {
         };
     }
     if (refusal !== null)
-        return { ...base, valueWithheld: describeFieldReadRefusal(refusal) };
-    const value = normalizeAgentLabel(raw.value);
+        return { ...base, valueWithheld: describeFieldReadRefusal({ refusal }) };
+    const value = normalizeAgentLabel({ raw: raw.value });
     return { ...base, value: value.text, valueTruncated: value.truncated };
 }
 /**
@@ -133,17 +133,17 @@ function sameElementState(a, b) {
  * not report state.
  */
 async function observeElement(driver, handle) {
-    if (driver.describeState === undefined || !isValidElementHandle(handle))
+    if (driver.describeState === undefined || !isValidElementHandle({ handle }))
         return undefined;
-    const raw = await driver.describeState(handle);
-    return raw === null ? undefined : projectElementState(raw);
+    const raw = await driver.describeState({ handle });
+    return raw === null ? undefined : projectElementState({ raw });
 }
 /** Runs a write between two readings of its target, waiting for the surface to settle in between. */
 async function observeWrite(driver, handle, write) {
     const before = await observeElement(driver, handle);
     await write();
     if (driver.settle !== undefined)
-        await driver.settle();
+        await driver.settle({});
     const after = await observeElement(driver, handle);
     return {
         ...(before !== undefined ? { before } : {}),
@@ -158,7 +158,7 @@ async function observeWrite(driver, handle, write) {
  * surface that publishes nothing has no page id to report, and says so rather than guessing.
  */
 async function summarizePage(driver) {
-    const elements = await driver.findElements({});
+    const elements = await driver.findElements({}, {});
     return {
         page: elements.find((element) => element.page !== undefined)?.page,
         elementCount: elements.length,
@@ -175,11 +175,11 @@ async function summarizePage(driver) {
  * a field no automated caller may fill, or the page is not published. Refusals are errors on
  * purpose: a caller must be told why, not handed a silent no-op it will retry forever.
  */
-export async function executePageCapability(driver, capabilityId, input) {
+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);
+    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
@@ -202,11 +202,11 @@ export async function executePageCapability(driver, capabilityId, input) {
                 ...(isAgentElementRole(role) ? { role } : {}),
                 ...(typeof input['query'] === 'string' ? { query: input['query'] } : {}),
             };
-            const [found, rawPages] = await Promise.all([driver.findElements(filter), driver.listPages()]);
+            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(element.label);
+                const label = normalizeAgentLabel({ raw: element.label });
                 const base = {
                     handle: element.handle,
                     role: element.role,
@@ -224,7 +224,7 @@ export async function executePageCapability(driver, capabilityId, input) {
             // every `data-agent-page` label short and clean.
             const pages = rawPages.map((page) => ({
                 id: page.id,
-                label: normalizeAgentLabel(page.label).text,
+                label: normalizeAgentLabel({ raw: page.label }).text,
             }));
             return {
                 elements,
@@ -239,17 +239,17 @@ export async function executePageCapability(driver, capabilityId, input) {
         case 'page.highlight': {
             const handle = requireHandle(input, 'handle');
             const durationMs = clampHighlightDuration(input['durationMs']);
-            await driver.highlight(handle, durationMs);
+            await driver.highlight({ handle, durationMs });
             return { highlighted: handle, durationMs };
         }
         case 'page.scroll_to': {
             const handle = requireHandle(input, 'handle');
-            await driver.scrollTo(handle);
+            await driver.scrollTo({ handle });
             return { scrolledTo: handle };
         }
         case 'page.click': {
             const handle = requireHandle(input, 'handle');
-            const observation = await observeWrite(driver, handle, () => driver.click(handle));
+            const observation = await observeWrite(driver, handle, () => driver.click({ handle }));
             return { clicked: handle, ...observation };
         }
         case 'page.fill': {
@@ -259,14 +259,14 @@ export async function executePageCapability(driver, capabilityId, input) {
             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);
+            const field = await driver.describeField({ handle });
             if (field === null)
                 throw new Error(`"${handle}" is not a fillable field`);
-            const refusal = findFieldFillRefusal(field);
+            const refusal = findFieldFillRefusal({ field });
             if (refusal !== null) {
-                throw new Error(`refusing to fill "${handle}": ${describeFieldRefusal(refusal)}`);
+                throw new Error(`refusing to fill "${handle}": ${describeFieldRefusal({ refusal })}`);
             }
-            const observation = await observeWrite(driver, handle, () => driver.fill(handle, text));
+            const observation = await observeWrite(driver, handle, () => driver.fill({ handle, text }));
             return { filled: handle, ...observation };
         }
         case 'page.select_option': {
@@ -279,7 +279,7 @@ export async function executePageCapability(driver, capabilityId, input) {
             // 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>`.
-            const observation = await observeWrite(driver, handle, () => driver.selectOption(handle, option, selected));
+            const observation = await observeWrite(driver, handle, () => driver.selectOption({ handle, option }, { selected }));
             // `optionSelected` names the boolean rather than reusing `selected`, which already means
             // "the handle this call acted on" for every verb in this switch (`clicked`, `filled`, …).
             return { selected: handle, option, optionSelected: selected, ...observation };
@@ -287,7 +287,7 @@ export async function executePageCapability(driver, capabilityId, input) {
         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();
+            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-
@@ -301,14 +301,14 @@ export async function executePageCapability(driver, capabilityId, input) {
                 // 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(page).text;
-                const safePages = pages.map((candidate) => `${normalizeAgentLabel(candidate.id).text} (${normalizeAgentLabel(candidate.label).text})`);
+                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);
+            await driver.navigate({ page });
             if (driver.settle !== undefined)
-                await driver.settle();
+                await driver.settle({});
             const after = await summarizePage(driver);
             return { navigatedTo: page, before, after };
         }

package/dist/core/webmcp.d.ts

@@ -27,7 +27,7 @@
  *    tool. Neither belongs on the `ModelContextTool` dict itself, so they are not fields of
  *    {@link WebMcpToolRegistration} — they ride along on its optional `registerOptions`, computed
  *    from {@link ToWebMcpToolOptions}, so a caller has exactly one object to destructure:
- *    `modelContext.registerTool(reg, reg.registerOptions)`.
+ *    `modelContext.registerTool({ tool: reg }, reg.registerOptions)`.
  * 2. **`title`/`annotations`** — real `ModelContextTool` dict fields (`USVString title`,
  *    `ToolAnnotations annotations`), now on {@link WebMcpToolRegistration}. `annotations.readOnlyHint`
  *    defaults from {@link CapabilityDef.risk} (`'read'` → `true`) since Jini's manifests already
@@ -68,7 +68,7 @@ export interface WebMcpToolRegistration {
      * `ModelContextRegisterToolOptions`, not part of the `ModelContextTool` dict this object
      * otherwise models. Present only when `options.signal` or `options.exposedTo` was supplied.
      * Bundled here rather than returned as a second value so `toWebMcpTool`'s output stays a single
-     * object a caller can pass straight through: `modelContext.registerTool(reg, reg.registerOptions)`.
+     * object a caller can pass straight through: `modelContext.registerTool({ tool: reg }, reg.registerOptions)`.
      */
     readonly registerOptions?: WebMcpRegisterToolOptions;
 }
@@ -146,10 +146,15 @@ export interface ToWebMcpToolOptions {
 export declare class WebMcpConfirmationRequiredError extends Error {
     readonly capabilityId: string;
     readonly reason: 'declined' | 'no-handler';
-    constructor(capabilityId: string, reason: 'declined' | 'no-handler');
+    constructor({ capabilityId, reason }: {
+        capabilityId: string;
+        reason: 'declined' | 'no-handler';
+    }, _optional?: Record<string, never>);
 }
 /** Whether `name` satisfies the spec's tool-name rule. Exported so a caller can pre-check a manifest without registering anything. */
-export declare function isValidWebMcpToolName(name: string): boolean;
+export declare function isValidWebMcpToolName({ name }: {
+    name: string;
+}, _optional?: Record<string, never>): boolean;
 /**
  * Thrown synchronously by {@link toWebMcpTool} for a capability whose `id` cannot legally become a
  * WebMCP tool name. Distinct from {@link WebMcpConfirmationRequiredError}: this is a manifest
@@ -157,7 +162,9 @@ export declare function isValidWebMcpToolName(name: string): boolean;
  */
 export declare class InvalidWebMcpToolNameError extends Error {
     readonly capabilityId: string;
-    constructor(capabilityId: string);
+    constructor({ capabilityId }: {
+        capabilityId: string;
+    }, _optional?: Record<string, never>);
 }
 /**
  * Projects one capability into a WebMCP registration.
@@ -173,7 +180,7 @@ export declare class InvalidWebMcpToolNameError extends Error {
  * capability reaching the page with nothing in front of it — not the authorization gap.
  *
  * @param capability - The capability to expose.
- * @param execute - Runs the capability. Receives the raw argument object, already checked against
+ * @param execute - Runs the capability. Receives `{ id, args }`, with args already checked against
  * `capability.inputSchema` — a caller-supplied value that fails validation never reaches this.
  * @param options - Optional confirmation handler, title/annotations, and registration options
  * (`signal`/`exposedTo`); required in practice for any capability declaring `requiresConfirmation`.
@@ -183,7 +190,13 @@ export declare class InvalidWebMcpToolNameError extends Error {
  * @throws {@link WebMcpConfirmationRequiredError} from `execute`, when confirmation is required
  * and is either declined or unobtainable.
  */
-export declare function toWebMcpTool(capability: CapabilityDef, execute: (id: string, args: Record<string, unknown>) => Promise<unknown>, options?: ToWebMcpToolOptions): WebMcpToolRegistration;
+export declare function toWebMcpTool({ capability, execute }: {
+    capability: CapabilityDef;
+    execute: (required: {
+        id: string;
+        args: Record<string, unknown>;
+    }) => Promise<unknown>;
+}, options?: ToWebMcpToolOptions): WebMcpToolRegistration;
 /**
  * Projects a whole manifest.
  *
@@ -198,5 +211,11 @@ export declare function toWebMcpTool(capability: CapabilityDef, execute: (id: st
  * @throws {@link InvalidWebMcpToolNameError} synchronously, for the first capability whose `id`
  * cannot be a WebMCP tool name.
  */
-export declare function toWebMcpTools(capabilities: readonly CapabilityDef[], execute: (id: string, args: Record<string, unknown>) => Promise<unknown>, options?: ToWebMcpToolOptions): readonly WebMcpToolRegistration[];
+export declare function toWebMcpTools({ capabilities, execute }: {
+    capabilities: readonly CapabilityDef[];
+    execute: (required: {
+        id: string;
+        args: Record<string, unknown>;
+    }) => Promise<unknown>;
+}, options?: ToWebMcpToolOptions): readonly WebMcpToolRegistration[];
 //# sourceMappingURL=webmcp.d.ts.map

package/dist/core/webmcp.js

@@ -27,7 +27,7 @@
  *    tool. Neither belongs on the `ModelContextTool` dict itself, so they are not fields of
  *    {@link WebMcpToolRegistration} — they ride along on its optional `registerOptions`, computed
  *    from {@link ToWebMcpToolOptions}, so a caller has exactly one object to destructure:
- *    `modelContext.registerTool(reg, reg.registerOptions)`.
+ *    `modelContext.registerTool({ tool: reg }, reg.registerOptions)`.
  * 2. **`title`/`annotations`** — real `ModelContextTool` dict fields (`USVString title`,
  *    `ToolAnnotations annotations`), now on {@link WebMcpToolRegistration}. `annotations.readOnlyHint`
  *    defaults from {@link CapabilityDef.risk} (`'read'` → `true`) since Jini's manifests already
@@ -52,7 +52,7 @@ import { findCapabilityInputError } from './capability.js';
 export class WebMcpConfirmationRequiredError extends Error {
     capabilityId;
     reason;
-    constructor(capabilityId, reason) {
+    constructor({ capabilityId, reason }, _optional = {}) {
         super(reason === 'declined'
             ? `WebMCP: "${capabilityId}" was declined by the user`
             : `WebMCP: "${capabilityId}" requires confirmation, but no requestUserInteraction handler was supplied`);
@@ -69,7 +69,7 @@ export class WebMcpConfirmationRequiredError extends Error {
  */
 const WEBMCP_TOOL_NAME_PATTERN = /^[A-Za-z0-9_.-]{1,128}$/;
 /** Whether `name` satisfies the spec's tool-name rule. Exported so a caller can pre-check a manifest without registering anything. */
-export function isValidWebMcpToolName(name) {
+export function isValidWebMcpToolName({ name }, _optional = {}) {
     return WEBMCP_TOOL_NAME_PATTERN.test(name);
 }
 /**
@@ -79,7 +79,7 @@ export function isValidWebMcpToolName(name) {
  */
 export class InvalidWebMcpToolNameError extends Error {
     capabilityId;
-    constructor(capabilityId) {
+    constructor({ capabilityId }, _optional = {}) {
         super(`WebMCP: capability id "${capabilityId}" is not a valid tool name — the spec requires 1-128 `
             + 'ASCII alphanumeric characters plus "_", "-", "." '
             + '(https://webmachinelearning.github.io/webmcp/#dom-modelcontext-registertool)');
@@ -101,7 +101,7 @@ export class InvalidWebMcpToolNameError extends Error {
  * capability reaching the page with nothing in front of it — not the authorization gap.
  *
  * @param capability - The capability to expose.
- * @param execute - Runs the capability. Receives the raw argument object, already checked against
+ * @param execute - Runs the capability. Receives `{ id, args }`, with args already checked against
  * `capability.inputSchema` — a caller-supplied value that fails validation never reaches this.
  * @param options - Optional confirmation handler, title/annotations, and registration options
  * (`signal`/`exposedTo`); required in practice for any capability declaring `requiresConfirmation`.
@@ -111,9 +111,9 @@ export class InvalidWebMcpToolNameError extends Error {
  * @throws {@link WebMcpConfirmationRequiredError} from `execute`, when confirmation is required
  * and is either declined or unobtainable.
  */
-export function toWebMcpTool(capability, execute, options = {}) {
-    if (!isValidWebMcpToolName(capability.id)) {
-        throw new InvalidWebMcpToolNameError(capability.id);
+export function toWebMcpTool({ capability, execute }, options = {}) {
+    if (!isValidWebMcpToolName({ name: capability.id })) {
+        throw new InvalidWebMcpToolNameError({ capabilityId: capability.id });
     }
     const { title, annotations, signal, exposedTo } = options;
     const resolvedAnnotations = {
@@ -133,21 +133,21 @@ export function toWebMcpTool(capability, execute, options = {}) {
             // Schema-on-error, matching page-executor.ts's discipline for page.* — WebMCP defines no
             // input validation of its own, so a wrong-schema call would otherwise reach `execute` (or a
             // confirmation prompt for one) with bad arguments instead of a same-turn correctable error.
-            const inputError = findCapabilityInputError(capability, input);
+            const inputError = findCapabilityInputError({ capability, input });
             if (inputError !== null) {
                 throw new Error(`${capability.id}: ${inputError}. Expected input: ${JSON.stringify(capability.inputSchema)}`);
             }
             if (capability.requiresConfirmation === true) {
                 const { requestUserInteraction } = options;
                 if (!requestUserInteraction) {
-                    throw new WebMcpConfirmationRequiredError(capability.id, 'no-handler');
+                    throw new WebMcpConfirmationRequiredError({ capabilityId: capability.id, reason: 'no-handler' });
                 }
                 const approved = await requestUserInteraction({ capability, args: input });
                 if (approved !== true) {
-                    throw new WebMcpConfirmationRequiredError(capability.id, 'declined');
+                    throw new WebMcpConfirmationRequiredError({ capabilityId: capability.id, reason: 'declined' });
                 }
             }
-            return execute(capability.id, input);
+            return execute({ id: capability.id, args: input });
         },
         annotations: resolvedAnnotations,
         ...(registerOptions !== undefined ? { registerOptions } : {}),
@@ -167,7 +167,7 @@ export function toWebMcpTool(capability, execute, options = {}) {
  * @throws {@link InvalidWebMcpToolNameError} synchronously, for the first capability whose `id`
  * cannot be a WebMCP tool name.
  */
-export function toWebMcpTools(capabilities, execute, options = {}) {
-    return capabilities.map((capability) => toWebMcpTool(capability, execute, options));
+export function toWebMcpTools({ capabilities, execute }, options = {}) {
+    return capabilities.map((capability) => toWebMcpTool({ capability, execute }, options));
 }
 //# sourceMappingURL=webmcp.js.map

package/dist/index.d.ts

@@ -2,6 +2,36 @@
  * Compatibility root — re-exports `./core` unchanged so existing `from '@jini-ai/agentic'`
  * imports keep resolving. New code should prefer the explicit `@jini-ai/agentic/core` import;
  * see `core/README.md` for why this package is split the way it is.
+
+ * Archived provenance rationale:
+ * ## The DOM split (why this package has two entry points)
+ *
+ * Everything under `src/` except `src/dom/` compiles under `tsconfig.json`, which extends the repo's
+ * `tsconfig.base.json` unmodified (`lib: ["ES2023"]`, no `DOM`) and **excludes `src/dom` entirely**.
+ * `src/dom/` compiles separately under `tsconfig.dom.json`, the only config in this package with
+ * `DOM`/`DOM.Iterable` in `lib`.
+ *
+ * This is a compile-time guarantee, not a convention: a `document`/`window` reference anywhere
+ * outside `src/dom/**` fails `tsc -p tsconfig.json` with "Cannot find name 'document'" (verified
+ * during the 2026-07-26 extraction — see the extraction's report for the exact command and error
+ * text). That is what proves the policy layer (`page-executor.ts`'s guards, refusals, and
+ * allowlist-enforcement) cannot quietly reach into a live page; only `src/dom/dom-page-driver.ts`,
+ * the one `PageDriver` implementation that legitimately needs a DOM, may.
+ *
+ * Two `package.json` exports follow the same split:
+ *
+ * - `.` (`dist/index.d.ts`/`dist/index.js`, built by `tsconfig.json`) — the DOM-free vocabulary,
+ *   policy gate, and protocol projections. What `@jini/chat-core`, `@jini/daemon` (structurally, see
+ *   below), and (once §5 of the plan lands) `@jini/ui` depend on.
+ * - `./dom` (`dist/dom/index.d.ts`/`dist/dom/index.js`, built by `tsconfig.dom.json`) — the browser
+ *   `PageDriver`. What `@jini/chat-react` depends on.
+ *
+ * `scripts/check-engine-boundaries.ts` R2 normally allows only bare `@jini/<name>` imports (one
+ * entry point per package), with a single named exception for `@jini/core/internal`. This extraction
+ * added a second, identically-gated exception for the exact literal `@jini/agentic/dom` — not a
+ * pattern — because `@jini/chat-react` genuinely needs the DOM half and there is no third package for
+ * it to live in without recreating the sprawl this plan exists to reduce (23 packages vs. a locked
+ * 14). See that script's own module doc for the up-to-date rule list.
  */
 export * from './core/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -2,6 +2,36 @@
  * Compatibility root — re-exports `./core` unchanged so existing `from '@jini-ai/agentic'`
  * imports keep resolving. New code should prefer the explicit `@jini-ai/agentic/core` import;
  * see `core/README.md` for why this package is split the way it is.
+
+ * Archived provenance rationale:
+ * ## The DOM split (why this package has two entry points)
+ *
+ * Everything under `src/` except `src/dom/` compiles under `tsconfig.json`, which extends the repo's
+ * `tsconfig.base.json` unmodified (`lib: ["ES2023"]`, no `DOM`) and **excludes `src/dom` entirely**.
+ * `src/dom/` compiles separately under `tsconfig.dom.json`, the only config in this package with
+ * `DOM`/`DOM.Iterable` in `lib`.
+ *
+ * This is a compile-time guarantee, not a convention: a `document`/`window` reference anywhere
+ * outside `src/dom/**` fails `tsc -p tsconfig.json` with "Cannot find name 'document'" (verified
+ * during the 2026-07-26 extraction — see the extraction's report for the exact command and error
+ * text). That is what proves the policy layer (`page-executor.ts`'s guards, refusals, and
+ * allowlist-enforcement) cannot quietly reach into a live page; only `src/dom/dom-page-driver.ts`,
+ * the one `PageDriver` implementation that legitimately needs a DOM, may.
+ *
+ * Two `package.json` exports follow the same split:
+ *
+ * - `.` (`dist/index.d.ts`/`dist/index.js`, built by `tsconfig.json`) — the DOM-free vocabulary,
+ *   policy gate, and protocol projections. What `@jini/chat-core`, `@jini/daemon` (structurally, see
+ *   below), and (once §5 of the plan lands) `@jini/ui` depend on.
+ * - `./dom` (`dist/dom/index.d.ts`/`dist/dom/index.js`, built by `tsconfig.dom.json`) — the browser
+ *   `PageDriver`. What `@jini/chat-react` depends on.
+ *
+ * `scripts/check-engine-boundaries.ts` R2 normally allows only bare `@jini/<name>` imports (one
+ * entry point per package), with a single named exception for `@jini/core/internal`. This extraction
+ * added a second, identically-gated exception for the exact literal `@jini/agentic/dom` — not a
+ * pattern — because `@jini/chat-react` genuinely needs the DOM half and there is no third package for
+ * it to live in without recreating the sprawl this plan exists to reduce (23 packages vs. a locked
+ * 14). See that script's own module doc for the up-to-date rule list.
  */
 export * from './core/index.js';
 //# sourceMappingURL=index.js.map

package/dist/skills/install/archive.d.ts

@@ -0,0 +1,8 @@
+import type { ArchiveReaderPort } from "./ports.js";
+import { type SkillUploadFile } from "./validation.js";
+/** Read bounded archive content only; paths are validated before opening any entry stream. */
+export declare function readSkillArchive({ base64, archiveReader }: {
+    base64: string;
+    archiveReader: ArchiveReaderPort;
+}, _optional?: Record<string, never>): Promise<SkillUploadFile[]>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/skills/install/archive.js

@@ -0,0 +1,47 @@
+import { decodeSkillBase64, MAX_SKILL_BYTES, MAX_SKILL_FILES, MAX_SKILL_FILE_BYTES, SkillInputError, validateSkillPath } from "./validation.js";
+/** Read bounded archive content only; paths are validated before opening any entry stream. */
+export async function readSkillArchive({ base64, archiveReader }, _optional = {}) {
+    try {
+        const reader = await archiveReader.open({ bytes: decodeSkillBase64({ value: base64 }) });
+        const files = [];
+        let total = 0;
+        let count = 0;
+        try {
+            for await (const entry of reader.entries) {
+                if (++count > MAX_SKILL_FILES)
+                    throw new SkillInputError({ message: "A skill archive may contain at most 256 entries." });
+                validateSkillPath({ filePath: entry.path.replace(/\/$/, "") });
+                if (entry.kind !== "file" && entry.kind !== "directory")
+                    throw new SkillInputError({ message: "Skill archives may contain only regular files and directories." });
+                if (entry.kind === "directory")
+                    continue;
+                if (!Number.isSafeInteger(entry.size) || entry.size < 0 || entry.size > MAX_SKILL_FILE_BYTES)
+                    throw new SkillInputError({ message: "Skill archive file exceeds 1 MiB." });
+                const chunks = [];
+                let size = 0;
+                {
+                    for await (const chunk of entry.read({})) {
+                        size += chunk.length;
+                        total += chunk.length;
+                        if (size > MAX_SKILL_FILE_BYTES || total > MAX_SKILL_BYTES)
+                            throw new SkillInputError({ message: "Skill archive exceeds its decompressed size limit." });
+                        chunks.push(Buffer.from(chunk));
+                    }
+                }
+                if (size !== entry.size)
+                    throw new SkillInputError({ message: "Skill archive file size does not match its metadata." });
+                files.push({ path: entry.path, contentBase64: Buffer.concat(chunks).toString("base64") });
+            }
+            return files;
+        }
+        finally {
+            reader.close({});
+        }
+    }
+    catch (error) {
+        if (error instanceof SkillInputError)
+            throw error;
+        throw new SkillInputError({ message: "Could not read skill ZIP. Use a valid ZIP with regular files only." });
+    }
+}
+//# sourceMappingURL=archive.js.map

package/dist/skills/install/fetch-adapter.d.ts

@@ -0,0 +1,6 @@
+import type { SkillFetchPort } from './ports.js';
+/** Wrap an explicitly supplied native fetch without adding transport defaults or changing responses. */
+export declare function createSkillFetchAdapter(required: {
+    fetch: typeof fetch;
+}, _optional?: Record<string, never>): SkillFetchPort;
+//# sourceMappingURL=fetch-adapter.d.ts.map

package/dist/skills/install/fetch-adapter.js

@@ -0,0 +1,6 @@
+/** Wrap an explicitly supplied native fetch without adding transport defaults or changing responses. */
+export function createSkillFetchAdapter(required, _optional = {}) {
+    const fetchImpl = required.fetch;
+    return ({ url }, optional = {}) => fetchImpl(url, optional);
+}
+//# sourceMappingURL=fetch-adapter.js.map

package/dist/skills/install/github.d.ts

@@ -0,0 +1,21 @@
+/** Commit-pinned public GitHub import with one request/body deadline, byte caps and refused redirects. */
+import { type SkillUploadFile } from "./validation.js";
+import type { SkillFetchPort } from "./ports.js";
+export interface GitHubSkillSource {
+    readonly githubUrl: string;
+    readonly commit: string;
+}
+/** Restricts every request to api.github.com, disallows redirects, pins one immutable commit.
+ * @complexity O(files + downloaded bytes), at most 256 file requests and 8 MiB decoded content.
+ */
+export declare function fetchGitHubSkill({ githubUrl, fetch: fetchImpl }: {
+    githubUrl: string;
+    fetch: SkillFetchPort;
+}, _optional?: Record<string, never>): Promise<{
+    files: SkillUploadFile[];
+    source: {
+        githubUrl: string;
+        commit: string;
+    };
+}>;
+//# sourceMappingURL=github.d.ts.map

package/dist/skills/install/github.js

@@ -0,0 +1,92 @@
+/** Commit-pinned public GitHub import with one request/body deadline, byte caps and refused redirects. */
+import { MAX_SKILL_BYTES, MAX_SKILL_FILES, MAX_SKILL_FILE_BYTES, decodeSkillBase64, SkillInputError } from "./validation.js";
+/** Restricts every request to api.github.com, disallows redirects, pins one immutable commit.
+ * @complexity O(files + downloaded bytes), at most 256 file requests and 8 MiB decoded content.
+ */
+export async function fetchGitHubSkill({ githubUrl, fetch: fetchImpl }, _optional = {}) {
+    let url;
+    try {
+        url = new URL(githubUrl);
+    }
+    catch {
+        throw new SkillInputError({ message: "Use an HTTPS GitHub repository URL, optionally ending in /tree/ref/skill-folder." });
+    }
+    let parts;
+    try {
+        parts = url.pathname.replace(/\/$/, "").split("/").slice(1).map(p => decodeURIComponent(p));
+    }
+    catch {
+        throw new SkillInputError({ message: "Use an HTTPS GitHub repository URL, optionally ending in /tree/ref/skill-folder." });
+    }
+    if (url.protocol !== "https:" || url.hostname !== "github.com" || url.port || url.username || url.password || url.search || url.hash || parts.length < 2 || (parts.length > 2 && (parts[2] !== "tree" || parts.length < 4)) || parts.some(p => !/^[a-zA-Z0-9_.-]+$/.test(p) || p === "." || p === ".."))
+        throw new SkillInputError({ message: "Use an HTTPS GitHub repository URL, optionally ending in /tree/ref/skill-folder." });
+    const owner = parts[0];
+    const repo = parts[1].replace(/\.git$/, "");
+    if (!repo)
+        throw new SkillInputError({ message: "Use an HTTPS GitHub repository URL, optionally ending in /tree/ref/skill-folder." });
+    const base = `https://api.github.com/repos/${owner}/${repo}`;
+    // One deadline for the whole fetch, including streaming response bodies.
+    const signal = AbortSignal.timeout(30_000);
+    async function json(endpoint) {
+        const response = await fetchImpl({ url: endpoint }, { redirect: "error", signal, headers: { Accept: "application/vnd.github+json" } });
+        if (!response.ok)
+            throw new SkillInputError({ message: `GitHub could not fetch this skill (HTTP ${response.status}). Use a public repository URL.` });
+        if (!response.body)
+            throw new SkillInputError({ message: "GitHub returned an empty response." });
+        const reader = response.body.getReader();
+        let bytes = 0;
+        const chunks = [];
+        try {
+            for (;;) {
+                const part = await reader.read();
+                if (part.done)
+                    break;
+                bytes += part.value.length;
+                if (bytes > MAX_SKILL_BYTES * 2)
+                    throw new SkillInputError({ message: "GitHub skill response exceeds its size limit." });
+                chunks.push(part.value);
+            }
+        }
+        finally {
+            await reader.cancel();
+        }
+        const result = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        if (!result || typeof result !== "object" || Array.isArray(result))
+            throw new SkillInputError({ message: "GitHub returned an invalid skill response." });
+        return result;
+    }
+    const commit = (await json(`${base}/commits/${encodeURIComponent(parts[3] ?? "HEAD")}`)).sha;
+    if (typeof commit !== "string" || !/^[a-f0-9]{40}$/.test(commit))
+        throw new SkillInputError({ message: "GitHub returned an invalid commit." });
+    const tree = await json(`${base}/git/trees/${commit}?recursive=1`);
+    if (tree.truncated || !Array.isArray(tree.tree))
+        throw new SkillInputError({ message: "GitHub repository tree is incomplete. Choose a smaller skill repository." });
+    const prefix = parts.length > 4 ? parts.slice(4).join("/") + "/" : "";
+    const files = [];
+    let total = 0;
+    let actualBytes = 0;
+    for (const row of tree.tree) {
+        if (typeof row.path !== "string" || !row.path.startsWith(prefix))
+            continue;
+        const relative = row.path.slice(prefix.length);
+        if (!/^(SKILL\.md|README\.md|LICENSE|(?:references|scripts|assets)\/.*)$/.test(relative) || row.type === "tree")
+            continue;
+        if (row.type !== "blob" || !["100644", "100755"].includes(String(row.mode)))
+            throw new SkillInputError({ message: "GitHub skills may contain only regular files." });
+        if (typeof row.size !== "number" || row.size < 0 || row.size > MAX_SKILL_FILE_BYTES || typeof row.sha !== "string" || !/^[a-f0-9]{40}$/.test(row.sha))
+            throw new SkillInputError({ message: "GitHub skill file exceeds its size limit or has invalid metadata." });
+        total += row.size;
+        if (total > MAX_SKILL_BYTES || files.length >= MAX_SKILL_FILES)
+            throw new SkillInputError({ message: "GitHub skill exceeds 8 MiB or 256 files." });
+        const blob = await json(`${base}/git/blobs/${row.sha}`);
+        if (blob.encoding !== "base64" || typeof blob.content !== "string")
+            throw new SkillInputError({ message: "GitHub returned an invalid skill file." });
+        const contentBase64 = blob.content.replace(/\s/g, "");
+        actualBytes += decodeSkillBase64({ value: contentBase64 }, { maxBytes: MAX_SKILL_FILE_BYTES }).length;
+        if (actualBytes > MAX_SKILL_BYTES)
+            throw new SkillInputError({ message: "GitHub skill exceeds 8 MiB or 256 files." });
+        files.push({ path: relative, contentBase64 });
+    }
+    return { files, source: { githubUrl, commit } };
+}
+//# sourceMappingURL=github.js.map