@jini-ai/agentic 0.3.6 → 0.4.0

package/dist/core/capability.js

@@ -17,7 +17,7 @@
  * @param id - Capability id to resolve.
  * @returns The definition, or `undefined` when the id is not in the manifest.
  */
-export function findCapability(capabilities, id) {
+export function findCapability({ capabilities, id }, _optional = {}) {
     return capabilities.find((capability) => capability.id === id);
 }
 /**
@@ -33,7 +33,7 @@ export function findCapability(capabilities, id) {
  * @param input - Raw caller-supplied arguments.
  * @returns An error message, or `null` when the input is acceptable.
  */
-export function findCapabilityInputError(capability, input) {
+export function findCapabilityInputError({ capability, input }, _optional = {}) {
     const { properties, required, additionalProperties } = capability.inputSchema;
     for (const name of required ?? []) {
         if (input[name] === undefined)
@@ -73,7 +73,7 @@ export function findCapabilityInputError(capability, input) {
  * @param hasSession - Whether a live frontend session is attached.
  * @returns Only the capabilities that can actually be satisfied right now.
  */
-export function availableCapabilities(capabilities, hasSession) {
+export function availableCapabilities({ capabilities, hasSession }, _optional = {}) {
     return hasSession ? capabilities : capabilities.filter((c) => c.surface === 'server');
 }
 //# sourceMappingURL=capability.js.map

package/dist/core/dom/dom-page-driver.d.ts

@@ -4,15 +4,17 @@ export interface DomPageDriverPage {
     /** Shown to a caller by `page.find_elements`/`page.navigate`'s refusal message — see
      *  `PageSummary.label` for why this exists at all. */
     readonly label: string;
-    readonly navigate: () => void;
+    readonly navigate: (required: Record<string, never>) => void;
 }
-export interface DomPageDriverOptions {
+export interface DomPageDriverRequired {
     /** The subtree to expose. Never pass `document`. */
     readonly root: ParentNode & {
         querySelector: Element['querySelector'];
     };
     /** Page ids this driver may navigate to, each with its label and how to get there. */
     readonly pages: Readonly<Record<string, DomPageDriverPage>>;
+}
+export interface DomPageDriverOptions {
     /**
      * The id of the page currently shown, reported on every element.
      *
@@ -30,7 +32,9 @@ export interface DomPageDriverOptions {
  * @param options - The subtree, the navigable pages, and the current page id.
  * @returns A driver ready to hand to `executePageCapability`.
  */
-export declare function createDomPageDriver(options: DomPageDriverOptions): PageDriver;
+export declare function createDomPageDriver({ root, pages }: DomPageDriverRequired, options?: DomPageDriverOptions): PageDriver;
 /** Reads the current page's `data-agent-page`, for hosts that tag the body. */
-export declare function currentAgentPage(root: ParentNode): string | undefined;
+export declare function currentAgentPage({ root }: {
+    root: ParentNode;
+}, _optional?: Record<string, never>): string | undefined;
 //# sourceMappingURL=dom-page-driver.d.ts.map

package/dist/core/dom/dom-page-driver.js

@@ -1,4 +1,4 @@
-import { AGENT_ELEMENT_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, AGENT_ELEMENT_ROLES, resolveHandleSelector, } from '../element-handles.js';
+import { AGENT_ELEMENT_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_PRIVATE_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, AGENT_ELEMENT_ROLES, resolveHandleSelector, } from '../element-handles.js';
 import { normalizeAgentLabel } from '../guards.js';
 /**
  * A {@link PageDriver} over a real DOM subtree.
@@ -178,10 +178,30 @@ function disabledOf(control) {
         ? control.matches(':disabled')
         : undefined;
 }
+const PRIVATE_SELECTOR = `[${AGENT_PRIVATE_ATTRIBUTE}]`;
+/** Whether `node` is inside (or is) a `[data-agent-private]` subtree. @complexity O(depth). */
+function isPrivate(node) {
+    return node.closest(PRIVATE_SELECTOR) !== null;
+}
+/**
+ * `element`'s text content with every `[data-agent-private]` subtree left out — the only text
+ * this driver ever reports, so a secret shown inside a published card never rides out on the
+ * card's own text. @complexity O(subtree size).
+ */
+function publicTextOf(element) {
+    if (element.querySelector(PRIVATE_SELECTOR) === null) {
+        /* c8 ignore next -- `Node.textContent` is typed nullable for the abstract node; on an Element it is always a string, so the `?? ''` satisfies the type and is not a reachable path. */
+        return element.textContent ?? '';
+    }
+    const copy = element.cloneNode(true);
+    for (const hidden of Array.from(copy.querySelectorAll(PRIVATE_SELECTOR)))
+        hidden.remove();
+    /* c8 ignore next -- as above. */
+    return copy.textContent ?? '';
+}
 function describe(element, page) {
     const role = element.getAttribute(AGENT_ROLE_ATTRIBUTE);
-    /* c8 ignore next -- `Node.textContent` is typed nullable for the abstract node; on an Element it is always a string, so the `?? ''` satisfies the type and is not a reachable path. */
-    const text = element.textContent ?? '';
+    const text = publicTextOf(element);
     // Live text is a fine fallback label for an ordinary element — it is the page's own ontology,
     // rendered openly. For an editable region it is not: a contenteditable's content is the *user's
     // data*, so falling back to it published the contents of a rich-text field to every
@@ -208,8 +228,7 @@ function describe(element, page) {
  * @param options - The subtree, the navigable pages, and the current page id.
  * @returns A driver ready to hand to `executePageCapability`.
  */
-export function createDomPageDriver(options) {
-    const { root, pages } = options;
+export function createDomPageDriver({ root, pages }, options = {}) {
     /**
      * The page a specific element belongs to — its own nearest `[data-agent-page]` ancestor, not a
      * single document-wide guess.
@@ -237,7 +256,8 @@ export function createDomPageDriver(options) {
      * publishes the same handle twice makes `find`'s single-match resolution ambiguous — surfaced
      * here so both callers below can refuse rather than silently pick one.
      */
-    const findAll = (handle) => Array.from(root.querySelectorAll(resolveHandleSelector(handle)));
+    const findAll = (handle) => Array.from(root.querySelectorAll(resolveHandleSelector({ handle })))
+        .filter((element) => !isPrivate(element));
     /**
      * More than one element answers to the same handle — a page-authoring bug (duplicate
      * `data-agent-element`), not something a caller passing that handle can resolve on its own.
@@ -284,14 +304,16 @@ export function createDomPageDriver(options) {
         // `<li><label><input>` this descent exists for. Filtering to descendants whose nearest
         // published ancestor is still `element` itself excludes exactly that case while leaving
         // ordinary wrapper descent untouched.
-        const owned = (node) => node.closest(`[${AGENT_ELEMENT_ATTRIBUTE}]`) === element;
+        const owned = (node) => node.closest(`[${AGENT_ELEMENT_ATTRIBUTE}]`) === element
+            && !isPrivate(node);
         const candidate = Array.from(element.querySelectorAll('input, textarea, select, button, a, summary'))
             .find(owned);
         return candidate ?? element;
     };
     return {
-        async findElements(filter) {
+        async findElements(_required, filter = {}) {
             const found = Array.from(root.querySelectorAll(`[${AGENT_ELEMENT_ATTRIBUTE}]`))
+                .filter((element) => !isPrivate(element))
                 .map((element) => describe(element, pageOf(element)))
                 .filter((element) => element.handle.length > 0);
             const query = filter.query?.toLowerCase();
@@ -304,16 +326,16 @@ export function createDomPageDriver(options) {
                     || element.label.toLowerCase().includes(query);
             });
         },
-        async listPages() {
+        async listPages(_required, _optional = {}) {
             // `Object.entries`, same own-enumerable-keys-only guarantee `Object.keys` gives `navigate`'s
             // own `hasOwnProperty` check above — no risk of a `pages.label`/`pages.navigate`-shaped
             // prototype entry leaking in as a fake page id.
             return Object.entries(pages).map(([id, page]) => ({ id, label: page.label }));
         },
-        async describeField(handle) {
+        async describeField({ handle }, _optional = {}) {
             return fieldDescriptorOf(controlOf(find(handle)));
         },
-        async describeState(handle) {
+        async describeState({ handle }, _optional = {}) {
             // Unlike every other method here, a handle that no longer resolves is an answer rather than
             // an error: an element that a click removed is exactly what the caller is asking about. A
             // handle resolving to *more than one* element is a different situation entirely — not an
@@ -348,8 +370,7 @@ export function createDomPageDriver(options) {
             const value = field !== null
                 ? control.value
                 : dropdown?.value;
-            /* c8 ignore next -- as in `describe`: an Element's textContent is always a string. */
-            const text = element.textContent ?? '';
+            const text = publicTextOf(element);
             return {
                 text,
                 // A contenteditable region has no `.value`; its content IS its value, so `text` is the
@@ -380,7 +401,7 @@ export function createDomPageDriver(options) {
          * would hang for the whole life of a backgrounded tab; without the frames every write would
          * report its own target unchanged, because the read would beat the render.
          */
-        async settle() {
+        async settle(_required, _optional = {}) {
             await new Promise((resolve) => {
                 let timer;
                 // No re-entry guard: whichever side loses the race calls this again, and both of its
@@ -400,7 +421,7 @@ export function createDomPageDriver(options) {
                     raf(() => raf(finish));
             });
         },
-        async highlight(handle, durationMs) {
+        async highlight({ handle, durationMs }, _optional = {}) {
             const element = find(handle);
             // Same refusal as `click()`, for the same reason: an SVG (or other non-HTMLElement) target
             // has no `.style` to draw an outline on, so silently returning here drew nothing while
@@ -426,16 +447,16 @@ export function createDomPageDriver(options) {
             }, durationMs);
             highlights.set(handle, { timer, restore });
         },
-        async scrollTo(handle) {
+        async scrollTo({ handle }, _optional = {}) {
             find(handle).scrollIntoView({ behavior: 'smooth', block: 'center' });
         },
-        async click(handle) {
+        async click({ handle }, _optional = {}) {
             const control = controlOf(find(handle));
             if (!(control instanceof HTMLElement))
                 throw new Error(`"${handle}" is not clickable`);
             control.click();
         },
-        async fill(handle, text) {
+        async fill({ handle, text }, _optional = {}) {
             const control = controlOf(find(handle));
             if (isEditableRegion(control)) {
                 // A contenteditable region has no `value`; its content *is* its children, and a real
@@ -461,7 +482,7 @@ export function createDomPageDriver(options) {
             control.dispatchEvent(new Event('input', { bubbles: true }));
             control.dispatchEvent(new Event('change', { bubbles: true }));
         },
-        async selectOption(handle, option, selected = true) {
+        async selectOption({ handle, option }, { selected = true } = {}) {
             const control = controlOf(find(handle));
             if (!(control instanceof HTMLSelectElement)) {
                 throw new Error(`"${handle}" is not a dropdown`);
@@ -496,8 +517,8 @@ export function createDomPageDriver(options) {
                 // the same shape of problem regardless of which side authored it. `handle` needs no
                 // treatment: it is already validated ASCII, length-capped by isValidElementHandle before
                 // this driver is ever called.
-                const safeOption = normalizeAgentLabel(option).text;
-                const available = options.map((entry) => normalizeAgentLabel(entry.text.trim()).text)
+                const safeOption = normalizeAgentLabel({ raw: option }).text;
+                const available = options.map((entry) => normalizeAgentLabel({ raw: entry.text.trim() }).text)
                     .filter((text) => text.length > 0);
                 throw new Error(`"${safeOption}" is not an option of "${handle}". Available: ${available.length > 0 ? available.join(', ') : '(none)'}`);
             }
@@ -513,7 +534,7 @@ export function createDomPageDriver(options) {
                 // ignoring this would tell the caller a deselect happened when nothing changed, and clearing
                 // the control would invent a third state (no selection) that a native <select> cannot hold.
                 throw new Error(`"${handle}" is a single-select; its choice cannot be removed, only replaced — `
-                    + `select a different option instead of deselecting "${normalizeAgentLabel(option).text}"`);
+                    + `select a different option instead of deselecting "${normalizeAgentLabel({ raw: option }).text}"`);
             }
             else {
                 // Same prototype-setter dance as `fill`, for the same reason: React tracks the previous
@@ -527,7 +548,7 @@ export function createDomPageDriver(options) {
             control.dispatchEvent(new Event('input', { bubbles: true }));
             control.dispatchEvent(new Event('change', { bubbles: true }));
         },
-        async navigate(page) {
+        async navigate({ page }, _optional = {}) {
             // `hasOwnProperty`, not `pages[page]`: a plain object literal inherits everything
             // `Object.prototype` contributes, so a bare lookup answered `navigate("constructor")` with
             // the `Object` constructor — a function the host never published, which this then called,
@@ -542,8 +563,8 @@ export function createDomPageDriver(options) {
             // the executor entirely, hands `page` in unsanitized, so the same bound-and-strip treatment
             // applies here too rather than assuming the only caller is the one that already checked.
             if (!published)
-                throw new Error(`"${normalizeAgentLabel(page).text}" is not a published page`);
-            pages[page].navigate();
+                throw new Error(`"${normalizeAgentLabel({ raw: page }).text}" is not a published page`);
+            pages[page].navigate({});
         },
     };
 }
@@ -594,7 +615,7 @@ function fillEditableRegion(control, text) {
     control.dispatchEvent(new Event('input', { bubbles: true }));
 }
 /** Reads the current page's `data-agent-page`, for hosts that tag the body. */
-export function currentAgentPage(root) {
+export function currentAgentPage({ root }, _optional = {}) {
     const tagged = root.querySelector(`[${AGENT_PAGE_ATTRIBUTE}]`);
     return tagged?.getAttribute(AGENT_PAGE_ATTRIBUTE) ?? undefined;
 }

package/dist/core/dom/index.d.ts

@@ -3,15 +3,15 @@
  *
  * The one `PageDriver` (see `@jini-ai/agentic`'s `page-driver.ts`) that reads and writes a real DOM
  * subtree. Split into its own entry point, compiled under its own `DOM`-lib `tsconfig.dom.json`,
- * so the rest of this package can stay provably DOM-free — see source-map.md's "The DOM split".
+ * so the rest of this package can stay provably DOM-free — see archived provenance ledger's "The DOM split".
  *
  * `@jini-ai/chat-react` is this package's one in-repo consumer today.
  */
-export { createDomPageDriver, currentAgentPage, type DomPageDriverOptions, type DomPageDriverPage, } from './dom-page-driver.js';
+export { createDomPageDriver, currentAgentPage, type DomPageDriverRequired, type DomPageDriverOptions, type DomPageDriverPage, } from './dom-page-driver.js';
 /**
  * WebMCP feature detection — moved 2026-07-26 from `@jini-ai/ui`'s `agent-tools/model-context.ts`
  * (plan §8 step 6). See `model-context.ts`'s module doc for why it lives here rather than
  * alongside `../webmcp.ts`'s DOM-free projection.
  */
-export { getAgentModelContext, type AgentModelContextLike, type AgentModelContextToolRegistration, } from './model-context.js';
+export { getAgentModelContext, type AgentModelContextLike, type ModelContextHostPort, type AgentModelContextRegisterToolOptions, type AgentModelContextToolRegistration, } from './model-context.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/dom/index.js

@@ -3,7 +3,7 @@
  *
  * The one `PageDriver` (see `@jini-ai/agentic`'s `page-driver.ts`) that reads and writes a real DOM
  * subtree. Split into its own entry point, compiled under its own `DOM`-lib `tsconfig.dom.json`,
- * so the rest of this package can stay provably DOM-free — see source-map.md's "The DOM split".
+ * so the rest of this package can stay provably DOM-free — see archived provenance ledger's "The DOM split".
  *
  * `@jini-ai/chat-react` is this package's one in-repo consumer today.
  */

package/dist/core/dom/model-context.d.ts

@@ -1,8 +1,8 @@
 /**
  * @module dom/model-context
  *
- * Feature-detected access to the browser's (draft) WebMCP surface —
- * `document.modelContext`, falling back to the deprecated `navigator.modelContext`
+ * Host-injected access to the browser's (draft) WebMCP surface —
+ * the host supplies `document.modelContext`, followed by the deprecated `navigator.modelContext`
  * alias (the spec moved the getter from Navigator to Document in 2026;
  * see the polyfill ecosystem's own back-compat posture). No `@mcp-b/*` or
  * other WebMCP package dependency: this module only needs the shape, the
@@ -11,11 +11,11 @@
  * bridges already use.
  * A page that wants `document.modelContext` to actually exist in a browser
  * without native support must load a real polyfill itself (e.g.
- * `@mcp-b/webmcp-polyfill`) — this module only ever reads what's there.
+ * `@mcp-b/webmcp-polyfill`) — this module adapts only the candidates the host supplies.
  *
  * Moved 2026-07-26 from `@jini-ai/ui/src/features/agent-tools/model-context.ts` (plan §4/§8 step 6).
  * Lives under `src/dom/`, not alongside `../webmcp.ts`'s pure `CapabilityDef` → WebMCP-tool
- * projection, because it reads `document`/`navigator` — `webmcp.ts`'s own module doc is explicit
+ * projection, because it adapts the native browser API — `webmcp.ts`'s own module doc is explicit
  * that "that detection is deliberately NOT here: it touches browser globals, and this package
  * holds none," which is exactly the DOM-free guarantee `src/dom/` exists to carve an exception
  * for. See `dom/index.ts`'s re-export of this module.
@@ -56,14 +56,24 @@ export interface AgentModelContextLike {
      * ModelContextRegisterToolOptions options = {})` — it is **async**. Callers must not assume it
      * has taken effect synchronously, and must not let a rejection escape.
      */
-    registerTool(tool: AgentModelContextToolRegistration, options?: AgentModelContextRegisterToolOptions): Promise<void>;
+    registerTool(required: {
+        tool: AgentModelContextToolRegistration;
+    }, options?: AgentModelContextRegisterToolOptions): Promise<void>;
     /**
      * NOT in the spec — the draft's only unregistration mechanism is aborting the `signal` passed to
      * `registerTool`. Kept optional purely so a polyfill that happens to expose one can be used;
      * never rely on its presence, and always pass a `signal` as the real cleanup path.
      */
-    unregisterTool?(name: string): void;
+    unregisterTool?(required: {
+        name: string;
+    }, _optional?: Record<string, never>): void;
 }
-/** Returns the page's WebMCP surface if one is installed (native or polyfilled), or `undefined`. */
-export declare function getAgentModelContext(): AgentModelContextLike | undefined;
+/** Ordered host candidates: modern document first, then any deprecated navigator alias. */
+export interface ModelContextHostPort {
+    candidates(required: Record<string, never>): readonly unknown[];
+}
+/** Adapts the first installed native surface to Jini's argument-object port. */
+export declare function getAgentModelContext({ host }: {
+    host: ModelContextHostPort;
+}, _optional?: Record<string, never>): AgentModelContextLike | undefined;
 //# sourceMappingURL=model-context.d.ts.map

package/dist/core/dom/model-context.js

@@ -1,8 +1,8 @@
 /**
  * @module dom/model-context
  *
- * Feature-detected access to the browser's (draft) WebMCP surface —
- * `document.modelContext`, falling back to the deprecated `navigator.modelContext`
+ * Host-injected access to the browser's (draft) WebMCP surface —
+ * the host supplies `document.modelContext`, followed by the deprecated `navigator.modelContext`
  * alias (the spec moved the getter from Navigator to Document in 2026;
  * see the polyfill ecosystem's own back-compat posture). No `@mcp-b/*` or
  * other WebMCP package dependency: this module only needs the shape, the
@@ -11,11 +11,11 @@
  * bridges already use.
  * A page that wants `document.modelContext` to actually exist in a browser
  * without native support must load a real polyfill itself (e.g.
- * `@mcp-b/webmcp-polyfill`) — this module only ever reads what's there.
+ * `@mcp-b/webmcp-polyfill`) — this module adapts only the candidates the host supplies.
  *
  * Moved 2026-07-26 from `@jini-ai/ui/src/features/agent-tools/model-context.ts` (plan §4/§8 step 6).
  * Lives under `src/dom/`, not alongside `../webmcp.ts`'s pure `CapabilityDef` → WebMCP-tool
- * projection, because it reads `document`/`navigator` — `webmcp.ts`'s own module doc is explicit
+ * projection, because it adapts the native browser API — `webmcp.ts`'s own module doc is explicit
  * that "that detection is deliberately NOT here: it touches browser globals, and this package
  * holds none," which is exactly the DOM-free guarantee `src/dom/` exists to carve an exception
  * for. See `dom/index.ts`'s re-export of this module.
@@ -28,17 +28,14 @@
  * fixture: a raw (non-`toWebMcpTool`) registration carrying a `title` failed TypeScript's
  * excess-property check against the un-widened type here.
  */
-function isModelContext(value) {
-    return typeof value === 'object' && value !== null && typeof value.registerTool === 'function';
-}
-/** Returns the page's WebMCP surface if one is installed (native or polyfilled), or `undefined`. */
-export function getAgentModelContext() {
-    const doc = globalThis.document;
-    if (isModelContext(doc?.modelContext))
-        return doc.modelContext;
-    const nav = globalThis.navigator;
-    if (isModelContext(nav?.modelContext))
-        return nav.modelContext;
+import { adaptNativeModelContext } from './native-model-context.js';
+/** Adapts the first installed native surface to Jini's argument-object port. */
+export function getAgentModelContext({ host }, _optional = {}) {
+    for (const value of host.candidates({})) {
+        const context = adaptNativeModelContext({ value });
+        if (context)
+            return context;
+    }
     return undefined;
 }
 //# sourceMappingURL=model-context.js.map

package/dist/core/dom/native-model-context.d.ts

@@ -0,0 +1,6 @@
+import type { AgentModelContextLike } from './model-context.js';
+/** Preserve native receiver binding and stable port identity across feature detection. */
+export declare function adaptNativeModelContext({ value }: {
+    value: unknown;
+}): AgentModelContextLike | undefined;
+//# sourceMappingURL=native-model-context.d.ts.map

package/dist/core/dom/native-model-context.js

@@ -0,0 +1,19 @@
+const adapters = new WeakMap();
+/** Preserve native receiver binding and stable port identity across feature detection. */
+export function adaptNativeModelContext({ value }) {
+    if (typeof value !== 'object' || value === null || typeof value.registerTool !== 'function')
+        return undefined;
+    const existing = adapters.get(value);
+    if (existing)
+        return existing;
+    const native = value;
+    const adapter = {
+        registerTool: ({ tool }, options) => native.registerTool(tool, options),
+        ...(typeof native.unregisterTool === 'function'
+            ? { unregisterTool: ({ name }) => native.unregisterTool(name) }
+            : {}),
+    };
+    adapters.set(value, adapter);
+    return adapter;
+}
+//# sourceMappingURL=native-model-context.js.map

package/dist/core/element-handles.d.ts

@@ -13,6 +13,12 @@ export declare const AGENT_ELEMENT_ATTRIBUTE = "data-agent-element";
 export declare const AGENT_ROLE_ATTRIBUTE = "data-agent-role";
 export declare const AGENT_LABEL_ATTRIBUTE = "data-agent-label";
 export declare const AGENT_PAGE_ATTRIBUTE = "data-agent-page";
+/**
+ * Marks a subtree the page driver must treat as absent: nothing inside it is published, adopted
+ * as a wrapper's control, or counted in any ancestor's text. For a secret the page shows a human
+ * (a revealed key), since a published ancestor's state otherwise reports its whole text content.
+ */
+export declare const AGENT_PRIVATE_ATTRIBUTE = "data-agent-private";
 /** What verb applies to a tagged element. Mirrors the convention documented in the sample markup. */
 export type AgentElementRole = 'button' | 'checkbox' | 'field' | 'form' | 'list' | 'status' | 'region' | 'link';
 export declare const AGENT_ELEMENT_ROLES: readonly AgentElementRole[];
@@ -22,7 +28,9 @@ export declare const AGENT_ELEMENT_ROLES: readonly AgentElementRole[];
  * @param handle - Candidate handle, typically caller-supplied.
  * @returns True when it is safe to interpolate into an attribute selector.
  */
-export declare function isValidElementHandle(handle: string): boolean;
+export declare function isValidElementHandle({ handle }: {
+    handle: string;
+}, _optional?: Record<string, never>): boolean;
 /**
  * Builds the one selector shape this system will ever resolve.
  *
@@ -30,7 +38,9 @@ export declare function isValidElementHandle(handle: string): boolean;
  * @returns The attribute selector for that handle.
  * @throws If the handle is not valid — never fall back to treating it as a raw selector.
  */
-export declare function resolveHandleSelector(handle: string): string;
+export declare function resolveHandleSelector({ handle }: {
+    handle: string;
+}, _optional?: Record<string, never>): string;
 /** A tagged element as described back to a caller. `label` is page-authored, so it is untrusted. */
 export interface AgentElementDescriptor {
     readonly handle: string;

package/dist/core/element-handles.js

@@ -2,6 +2,12 @@ export const AGENT_ELEMENT_ATTRIBUTE = 'data-agent-element';
 export const AGENT_ROLE_ATTRIBUTE = 'data-agent-role';
 export const AGENT_LABEL_ATTRIBUTE = 'data-agent-label';
 export const AGENT_PAGE_ATTRIBUTE = 'data-agent-page';
+/**
+ * Marks a subtree the page driver must treat as absent: nothing inside it is published, adopted
+ * as a wrapper's control, or counted in any ancestor's text. For a secret the page shows a human
+ * (a revealed key), since a published ancestor's state otherwise reports its whole text content.
+ */
+export const AGENT_PRIVATE_ATTRIBUTE = 'data-agent-private';
 export const AGENT_ELEMENT_ROLES = [
     'button', 'checkbox', 'field', 'form', 'list', 'status', 'region', 'link',
 ];
@@ -19,7 +25,7 @@ const MAX_HANDLE_LENGTH = 128;
  * @param handle - Candidate handle, typically caller-supplied.
  * @returns True when it is safe to interpolate into an attribute selector.
  */
-export function isValidElementHandle(handle) {
+export function isValidElementHandle({ handle }, _optional = {}) {
     return handle.length > 0 && handle.length <= MAX_HANDLE_LENGTH && HANDLE_PATTERN.test(handle);
 }
 /**
@@ -29,8 +35,8 @@ export function isValidElementHandle(handle) {
  * @returns The attribute selector for that handle.
  * @throws If the handle is not valid — never fall back to treating it as a raw selector.
  */
-export function resolveHandleSelector(handle) {
-    if (!isValidElementHandle(handle)) {
+export function resolveHandleSelector({ handle }, _optional = {}) {
+    if (!isValidElementHandle({ handle })) {
         throw new Error(`invalid element handle "${handle.slice(0, MAX_HANDLE_LENGTH)}": `
             + 'handles are lowercase words joined by single hyphens, and are never CSS selectors');
     }

package/dist/core/gen-ui/encoder.d.ts

@@ -1,18 +1,20 @@
+import type { Clock } from "@jini-ai/core/primitives";
 /**
- * @module agui/encoder
+ * @module gen-ui/encoder
  *
- * Encodes `@jini-ai/protocol`'s `RunProtocolEvent` stream into AG-UI wire events (see
+ * Encodes `@jini-ai/protocol`'s `RunProtocolEvent` stream into custom gen-ui wire events (see
  * `./events.ts`'s module doc). Rewritten from scratch against `@jini-ai/protocol`'s actual
  * current shape — the ported adapter's original encoder targeted a different, product-specific
  * event union with no direct correspondence to `RunProtocolEvent`/`RunAgentPayload`; only the
  * *shape* of the job (a big per-event-kind switch, unrecognized events silently dropped) carried
- * over. See `source-map.md` for the full old→new field-mapping table and the generalization
+ * over. See `archived provenance ledger` for the full old→new field-mapping table and the generalization
  * writeup for the six event kinds that had no generic equivalent before this task.
  *
  * Folded in 2026-07-26 from the standalone `@jini-ai/agui` package (plan §3a) into this `src/gen-ui/`
  * subdirectory — kept out of the flat `ag-ui.ts` namespace because that file is a different
  * projection ({@link CapabilityDef} → an AG-UI *frontend tool*); this one turns a run's event
- * stream into AG-UI *wire* events. Same protocol, two unrelated halves of it.
+ * stream into Jini's own gen-ui *wire* events. These are separate protocols; the old package name
+ * did not make this custom event vocabulary compatible with external AG-UI.
  */
 import type { RunProtocolEvent } from '@jini-ai/protocol';
 import type { GenUiEvent } from './events.js';
@@ -20,12 +22,12 @@ export interface GenUiEncodeContext {
     /** The run this event belongs to — stamped onto every produced `GenUiEvent`. */
     readonly runId: string;
     /** Passed through onto the produced event's `seq`, when the caller tracks one (e.g. an SSE `Last-Event-ID`-shaped cursor). Omitted entirely (not set to `undefined`) when absent, matching the original adapter's own base-field construction. */
-    readonly seq?: number;
-    /** Injectable clock for the produced event's `ts`. Defaults to `Date.now`. Test-only hook. */
-    readonly now?: () => number;
+    readonly seq?: number | undefined;
+    /** Optional clock override for this event; the factory's required clock supplies the default. */
+    readonly now?: ((required: Record<string, never>) => number) | undefined;
 }
 /**
- * A stateful AG-UI encoder for one run's event stream. Stateful because `tool_use`/`tool_result`
+ * A stateful gen-ui encoder for one run's event stream. Stateful because `tool_use`/`tool_result`
  * correlation requires remembering each in-flight tool call's name/args between the two protocol
  * events that describe its start and end — a pure per-event function cannot do this alone. Create
  * one instance per run (e.g. one per `RunLifecycle.stream(runId, ...)` subscription); do not share
@@ -34,11 +36,17 @@ export interface GenUiEncodeContext {
  */
 export interface GenUiEncoder {
     /**
-     * Encodes one `RunProtocolEvent` into an `GenUiEvent`, or `null` if this event has no AG-UI
+     * Encodes one `RunProtocolEvent` into a `GenUiEvent`, or `null` if this event has no gen-ui
      * equivalent (an unrecognized/not-yet-generalized event kind — silently dropped by the relay,
      * matching the original adapter's own default behavior).
      */
-    encode(event: RunProtocolEvent, ctx: GenUiEncodeContext): GenUiEvent | null;
+    encode(required: {
+        event: RunProtocolEvent;
+        runId: string;
+    }, optional?: {
+        seq?: number | undefined;
+        now?: ((required: Record<string, never>) => number) | undefined;
+    }): GenUiEvent | null;
 }
 /**
  * Creates a fresh `GenUiEncoder` with its own, empty tool-call correlation map.
@@ -46,5 +54,7 @@ export interface GenUiEncoder {
  * of currently in-flight (not yet resolved) tool calls for the run this instance encodes.
  * @overallScore 100/100
  */
-export declare function createGenUiEncoder(): GenUiEncoder;
+export declare function createGenUiEncoder({ clock }: {
+    clock: Clock;
+}, _optional?: Record<string, never>): GenUiEncoder;
 //# sourceMappingURL=encoder.d.ts.map

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

@@ -4,10 +4,10 @@
  * of currently in-flight (not yet resolved) tool calls for the run this instance encodes.
  * @overallScore 100/100
  */
-export function createGenUiEncoder() {
+export function createGenUiEncoder({ clock }, _optional = {}) {
     const pendingToolCalls = new Map();
     function baseFields(ctx) {
-        const ts = ctx.now ? ctx.now() : Date.now();
+        const ts = ctx.now ? ctx.now({}) : clock.nowMs();
         return ctx.seq !== undefined ? { runId: ctx.runId, ts, seq: ctx.seq } : { runId: ctx.runId, ts };
     }
     function encodeAgentPayload(payload, ctx) {
@@ -38,7 +38,7 @@ export function createGenUiEncoder() {
                     result: payload.content,
                 };
             }
-            // Generalization (see source-map.md): pipeline_stage_started/completed generalized into a
+            // 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':
@@ -57,19 +57,20 @@ export function createGenUiEncoder() {
                     stageId: payload.stageId,
                     ...(payload.iteration !== undefined ? { iteration: payload.iteration } : {}),
                 };
-            // Generalization (see source-map.md): genui_surface_request/response generalized into a
+            // Generalization (see archived provenance ledger): genui_surface_request/response generalized into a
             // generic human-in-the-loop ask/answer pair.
             case 'surface_request':
                 return { ...base, kind: 'ui.surface_requested', surfaceId: payload.surfaceId, surfaceKind: payload.surfaceKind, payload: payload.payload };
             case 'surface_response':
                 return { ...base, kind: 'ui.surface_responded', surfaceId: payload.surfaceId, value: payload.value, respondedBy: payload.respondedBy };
             // 'status' / 'thinking_start' / 'thinking_delta' / 'tool_input_delta' / 'usage' / 'raw':
-            // no AG-UI equivalent — silently dropped, matching the original adapter's default behavior.
+            // no gen-ui equivalent — silently dropped, matching the original adapter's default behavior.
             default:
                 return null;
         }
     }
-    function encode(event, ctx) {
+    function encode({ event, runId }, { seq, now } = {}) {
+        const ctx = { runId, seq, now };
         switch (event.kind) {
             case 'start':
                 return { ...baseFields(ctx), kind: 'run.lifecycle', status: 'started' };
@@ -86,7 +87,7 @@ export function createGenUiEncoder() {
             }
             case 'agent':
                 return encodeAgentPayload(event.payload, ctx);
-            // 'stdout' / 'stderr' / 'error': no AG-UI equivalent — silently dropped, matching the
+            // 'stdout' / 'stderr' / 'error': no gen-ui equivalent — silently dropped, matching the
             // original adapter's default behavior for unrecognized event kinds.
             default:
                 return null;