@jini-ai/agentic 0.3.7 → 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

@@ -228,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.
@@ -257,7 +256,7 @@ 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
@@ -312,7 +311,7 @@ export function createDomPageDriver(options) {
         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)))
@@ -327,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
@@ -402,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
@@ -422,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
@@ -448,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
@@ -483,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`);
@@ -518,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)'}`);
             }
@@ -535,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
@@ -549,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,
@@ -564,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({});
         },
     };
 }
@@ -616,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

@@ -28,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.
  *
@@ -36,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

@@ -25,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);
 }
 /**
@@ -35,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;

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

@@ -1,11 +1,12 @@
 /**
- * @module agui/events
+ * @module gen-ui/events
  *
- * The AG-UI wire event shapes `./encoder.ts` produces. AG-UI (Agent-User Interaction
- * Protocol) is CopilotKit's open, external wire protocol for streaming an agent's run over SSE to
- * a UI client — see https://github.com/ag-ui-protocol/ag-ui. This module is a near-verbatim port
+ * The custom gen-ui wire event shapes `./encoder.ts` produces. AG-UI (Agent-User Interaction
+ * Protocol) is CopilotKit's separate, external wire protocol for streaming an agent's run over SSE to
+ * a UI client — see https://github.com/ag-ui-protocol/ag-ui. These six `kind` values belong to
+ * Jini's own protocol, not the external AG-UI event vocabulary. This module is a near-verbatim port
  * of a 312-line adapter that encoded a product's own run-event stream into this shape; the types
- * themselves are unchanged in kind, only de-branded (see `source-map.md` for the full
+ * themselves are unchanged in kind, only de-branded (see `archived provenance ledger` for the full
  * field-mapping table and provenance).
  *
  * Folded in 2026-07-26 from the standalone `@jini-ai/agui` package (plan §3a) into this `src/gen-ui/`

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

@@ -1,11 +1,12 @@
 /**
- * @module agui/events
+ * @module gen-ui/events
  *
- * The AG-UI wire event shapes `./encoder.ts` produces. AG-UI (Agent-User Interaction
- * Protocol) is CopilotKit's open, external wire protocol for streaming an agent's run over SSE to
- * a UI client — see https://github.com/ag-ui-protocol/ag-ui. This module is a near-verbatim port
+ * The custom gen-ui wire event shapes `./encoder.ts` produces. AG-UI (Agent-User Interaction
+ * Protocol) is CopilotKit's separate, external wire protocol for streaming an agent's run over SSE to
+ * a UI client — see https://github.com/ag-ui-protocol/ag-ui. These six `kind` values belong to
+ * Jini's own protocol, not the external AG-UI event vocabulary. This module is a near-verbatim port
  * of a 312-line adapter that encoded a product's own run-event stream into this shape; the types
- * themselves are unchanged in kind, only de-branded (see `source-map.md` for the full
+ * themselves are unchanged in kind, only de-branded (see `archived provenance ledger` for the full
  * field-mapping table and provenance).
  *
  * Folded in 2026-07-26 from the standalone `@jini-ai/agui` package (plan §3a) into this `src/gen-ui/`

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

@@ -8,7 +8,7 @@
  * **This is not AG-UI**, despite what this directory was called until 2026-07-27. The real
  * Agent-User Interaction Protocol uses a 33-member `SCREAMING_SNAKE` event enum and shares zero
  * event names with these six; `../ag-ui.ts` is the genuine AG-UI projection and lives at `src/`
- * root, apart from this. See `source-map.md` for how the two came to be confused.
+ * root, apart from this. See `archived provenance ledger` for how the two came to be confused.
  *
  * Nothing here opens a connection or touches a browser global. Transport (SSE, WebSocket) belongs
  * to a host — `@jini-ai/http-kit`'s run-stream route is the shipped consumer.

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

@@ -8,7 +8,7 @@
  * **This is not AG-UI**, despite what this directory was called until 2026-07-27. The real
  * Agent-User Interaction Protocol uses a 33-member `SCREAMING_SNAKE` event enum and shares zero
  * event names with these six; `../ag-ui.ts` is the genuine AG-UI projection and lives at `src/`
- * root, apart from this. See `source-map.md` for how the two came to be confused.
+ * root, apart from this. See `archived provenance ledger` for how the two came to be confused.
  *
  * Nothing here opens a connection or touches a browser global. Transport (SSE, WebSocket) belongs
  * to a host — `@jini-ai/http-kit`'s run-stream route is the shipped consumer.