@jini-ai/agentic 0.1.0 → 0.1.1

package/dist/webmcp.d.ts

@@ -14,14 +14,91 @@
  * That detection is deliberately NOT here: it touches browser globals, and this package holds
  * none. Framework bindings own host access; this file owns only the shape translation, so when
  * the registration shape changes again there is exactly one place to change it.
+ *
+ * Re-verified 2026-07-28 against the primary spec source
+ * (https://webmachinelearning.github.io/webmcp/, `index.bs`). Four real gaps closed this pass,
+ * all additive — none change the confirmation gate below, which is Jini's own addition and has
+ * no spec counterpart:
+ *
+ * 1. **`signal`/`exposedTo`** — `ModelContextRegisterToolOptions`, the *second* positional
+ *    argument to `registerTool(tool, options)`. `signal` is the spec's ONLY unregistration
+ *    mechanism (there is no `unregisterTool()`); aborting it removes the tool and fires
+ *    `toolchange`. `exposedTo` scopes which cross-origin documents in the same tree may see the
+ *    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)`.
+ * 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
+ *    carry that judgment; a caller may override or add `untrustedContentHint` via `options.annotations`.
+ * 3. **Tool name validation** — the spec's `registerTool` algorithm rejects (with an
+ *    `InvalidStateError` `DOMException`) a name that is empty, over 128 code points, or contains
+ *    anything outside ASCII alphanumeric plus `_`, `-`, `.`. `capability.id` becomes `name`
+ *    verbatim, so a malformed manifest entry previously surfaced as a cryptic browser-side
+ *    rejection days later; {@link toWebMcpTool} now checks it at projection time and names the
+ *    offending capability.
+ * 4. **Schema-on-error** — WebMCP defines no input validation of its own (the spec's
+ *    `ToolExecuteCallback` is just `Promise<any> (object input)`), and this module's own doc used
+ *    to say so ("the caller is responsible for validating it... WebMCP does not"). That left a
+ *    wrong-schema call to fail deep inside whatever `execute` does, with no way for the caller to
+ *    self-correct in the same turn. `execute` now runs the manifest's own
+ *    {@link findCapabilityInputError} first and, on failure, throws the same
+ *    `"<id>: <reason>. Expected input: <schema>"` shape `page-executor.ts` already uses for
+ *    `page.*` — one discipline, not two.
  */
-import type { CapabilityDef, CapabilityInputSchema } from './capability.js';
+import { type CapabilityDef, type CapabilityInputSchema } from './capability.js';
 /** The registration object `registerTool` accepts. WebMCP names the schema field `inputSchema`. */
 export interface WebMcpToolRegistration {
     readonly name: string;
+    /**
+     * `ModelContextTool.title` — an optional human-readable label, distinct from `name` (the
+     * machine identifier) and `description` (what an agent reads to decide whether to call it). The
+     * spec recommends localizing it to the user's language; this projection makes no attempt at
+     * that; a caller wanting a localized title supplies it via `options.title`.
+     */
+    readonly title?: string;
     readonly description: string;
     readonly inputSchema: CapabilityInputSchema;
     readonly execute: (args: Record<string, unknown>) => Promise<unknown>;
+    /** `ModelContextTool.annotations` — behavior hints. See {@link WebMcpToolAnnotations}. */
+    readonly annotations?: WebMcpToolAnnotations;
+    /**
+     * The SECOND positional argument `registerTool(tool, options)` expects — the spec's
+     * `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)`.
+     */
+    readonly registerOptions?: WebMcpRegisterToolOptions;
+}
+/**
+ * `ToolAnnotations` — optional behavior hints a host UI or agent may use to decide how to treat a
+ * tool without calling it. Both default to `false` in the spec; this projection only ever sets
+ * `readOnlyHint` by default (from {@link CapabilityDef.risk}) and leaves `untrustedContentHint`
+ * unset unless a caller supplies one, since nothing in {@link CapabilityDef} implies it.
+ */
+export interface WebMcpToolAnnotations {
+    /** True when the tool never mutates state. Defaults from `capability.risk === 'read'`. */
+    readonly readOnlyHint?: boolean;
+    /** True when the tool's return value may contain content from outside the page's trust boundary. */
+    readonly untrustedContentHint?: boolean;
+}
+/**
+ * `ModelContextRegisterToolOptions` — the second positional argument to the real
+ * `registerTool(tool, options)`, per the spec IDL:
+ * `dictionary ModelContextRegisterToolOptions { AbortSignal signal; sequence<USVString> exposedTo; }`.
+ */
+export interface WebMcpRegisterToolOptions {
+    /**
+     * Aborting this unregisters the tool and rejects the in-flight `registerTool()` promise with the
+     * signal's abort reason — the spec's ONLY unregistration mechanism. There is no `unregisterTool()`
+     * in the current draft; a host that wants to drop a tool later must have registered it with a
+     * signal in the first place.
+     */
+    readonly signal?: AbortSignal;
+    /** Origins (besides same-origin, always allowed) that may see and call this tool from other documents in the same tree. */
+    readonly exposedTo?: readonly string[];
 }
 /** What a confirmation handler is asked to approve. */
 export interface WebMcpUserInteraction {
@@ -36,10 +113,34 @@ export interface WebMcpUserInteraction {
  * (https://webmachinelearning.github.io/webmcp/) does not define one, so there is nothing to
  * feature-detect and nothing standard to call. A host that wants a confirmed WebMCP tool supplies
  * this itself.
+ *
+ * Independently re-confirmed 2026-07-28: the reference polyfill `@mcp-b/webmcp-polyfill` (the
+ * `MCP-B`/`WebMCP-org` community project, not the W3C CG spec) DOES pass a second
+ * `client: { requestUserInteraction(callback) }` argument to `execute`, as one of its own
+ * non-standard "MCPB extensions". That is further evidence the idea is real and wanted, and
+ * further confirmation it is NOT part of the standardized `ToolExecuteCallback` — whose IDL is
+ * `Promise<any> (object input)`, one argument. This module's `execute` wrapper below takes one
+ * argument for exactly that reason; a second, ignored argument from a polyfill is harmless.
  */
 export type RequestUserInteraction = (interaction: WebMcpUserInteraction) => Promise<boolean>;
 export interface ToWebMcpToolOptions {
     readonly requestUserInteraction?: RequestUserInteraction;
+    /**
+     * `ModelContextTool.title`. Meaningful per-capability, so pass this through {@link toWebMcpTool}
+     * (one capability) rather than {@link toWebMcpTools} (a whole manifest) — the latter shares one
+     * `options` object across every capability in the batch, and a shared title would repeat
+     * verbatim across dissimilar tools.
+     */
+    readonly title?: string;
+    /**
+     * Overrides or extends the default `annotations` (`{ readOnlyHint: capability.risk === 'read' }`).
+     * Fields set here win over the default.
+     */
+    readonly annotations?: WebMcpToolAnnotations;
+    /** See {@link WebMcpRegisterToolOptions.signal}. Safe to share across a whole {@link toWebMcpTools} batch — one `AbortController` per registration session, aborted once on teardown. */
+    readonly signal?: AbortSignal;
+    /** See {@link WebMcpRegisterToolOptions.exposedTo}. Safe to share across a whole {@link toWebMcpTools} batch when every capability in it gets the same scoping. */
+    readonly exposedTo?: readonly string[];
 }
 /** Thrown in place of executing, when a call needed confirmation and did not get it. */
 export declare class WebMcpConfirmationRequiredError extends Error {
@@ -47,6 +148,17 @@ export declare class WebMcpConfirmationRequiredError extends Error {
     readonly reason: 'declined' | 'no-handler';
     constructor(capabilityId: string, reason: 'declined' | 'no-handler');
 }
+/** 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;
+/**
+ * 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
+ * defect caught before any registration is attempted, not a runtime refusal of a call.
+ */
+export declare class InvalidWebMcpToolNameError extends Error {
+    readonly capabilityId: string;
+    constructor(capabilityId: string);
+}
 /**
  * Projects one capability into a WebMCP registration.
  *
@@ -61,11 +173,13 @@ export declare class WebMcpConfirmationRequiredError 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; the caller is
- * responsible for validating it against `capability.inputSchema` — WebMCP does not.
- * @param options - Optional confirmation handler; required in practice for any capability
- * declaring `requiresConfirmation`.
+ * @param execute - Runs the capability. Receives the raw argument object, 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`.
  * @returns The registration object to hand to `registerTool`.
+ * @throws {@link InvalidWebMcpToolNameError} synchronously, if `capability.id` cannot be a WebMCP
+ * tool name.
  * @throws {@link WebMcpConfirmationRequiredError} from `execute`, when confirmation is required
  * and is either declined or unobtainable.
  */
@@ -73,9 +187,16 @@ export declare function toWebMcpTool(capability: CapabilityDef, execute: (id: st
 /**
  * Projects a whole manifest.
  *
+ * `options` is shared across every capability — safe for `requestUserInteraction`, `signal`, and
+ * `exposedTo`, which are naturally uniform for one registration session; do not pass `title`
+ * through this one, since it would repeat verbatim across every tool in the manifest (see
+ * {@link ToWebMcpToolOptions.title}).
+ *
  * @param capabilities - Capabilities to expose, already filtered by whatever policy applies.
  * @param execute - Shared dispatcher, keyed by capability id.
  * @returns One registration per capability, in manifest order.
+ * @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[];
 //# sourceMappingURL=webmcp.d.ts.map

package/dist/webmcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webmcp.d.ts","sourceRoot":"","sources":["../src/webmcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE5E,mGAAmG;AACnG,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvE;AAED,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,WAAW,EAAE,qBAAqB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE9F,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;CAC1D;AAED,wFAAwF;AACxF,qBAAa,+BAAgC,SAAQ,KAAK;IAC5C,QAAQ,CAAC,YAAY,EAAE,MAAM;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,YAAY;gBAAhE,YAAY,EAAE,MAAM,EAAW,MAAM,EAAE,UAAU,GAAG,YAAY;CAQtF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,aAAa,EACzB,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,EACxE,OAAO,GAAE,mBAAwB,GAChC,sBAAsB,CAoBxB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,SAAS,aAAa,EAAE,EACtC,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,EACxE,OAAO,GAAE,mBAAwB,GAChC,SAAS,sBAAsB,EAAE,CAEnC"}
+{"version":3,"file":"webmcp.d.ts","sourceRoot":"","sources":["../src/webmcp.ts"],"names":[],"mappings":"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"}

package/dist/webmcp.js

@@ -1,3 +1,53 @@
+/**
+ * @module webmcp
+ *
+ * Projection: {@link CapabilityDef} → a WebMCP tool registration.
+ *
+ * WebMCP (`document.modelContext.registerTool`) is the browser API by which a *page* offers
+ * tools to an agent running inside the browser. It is a W3C Community Group draft, not a
+ * standards-track spec, and it moves: the API relocated from `navigator.modelContext` to
+ * `document.modelContext` on 2026-07-21, Chrome 150 deprecated the `navigator` location while
+ * still serving it during the origin trial (Chrome 149–156), Edge ships it behind a flag, and
+ * Firefox and Safari have made no commitment. Feature detection must therefore check `document`
+ * first and fall back to `navigator`.
+ *
+ * That detection is deliberately NOT here: it touches browser globals, and this package holds
+ * none. Framework bindings own host access; this file owns only the shape translation, so when
+ * the registration shape changes again there is exactly one place to change it.
+ *
+ * Re-verified 2026-07-28 against the primary spec source
+ * (https://webmachinelearning.github.io/webmcp/, `index.bs`). Four real gaps closed this pass,
+ * all additive — none change the confirmation gate below, which is Jini's own addition and has
+ * no spec counterpart:
+ *
+ * 1. **`signal`/`exposedTo`** — `ModelContextRegisterToolOptions`, the *second* positional
+ *    argument to `registerTool(tool, options)`. `signal` is the spec's ONLY unregistration
+ *    mechanism (there is no `unregisterTool()`); aborting it removes the tool and fires
+ *    `toolchange`. `exposedTo` scopes which cross-origin documents in the same tree may see the
+ *    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)`.
+ * 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
+ *    carry that judgment; a caller may override or add `untrustedContentHint` via `options.annotations`.
+ * 3. **Tool name validation** — the spec's `registerTool` algorithm rejects (with an
+ *    `InvalidStateError` `DOMException`) a name that is empty, over 128 code points, or contains
+ *    anything outside ASCII alphanumeric plus `_`, `-`, `.`. `capability.id` becomes `name`
+ *    verbatim, so a malformed manifest entry previously surfaced as a cryptic browser-side
+ *    rejection days later; {@link toWebMcpTool} now checks it at projection time and names the
+ *    offending capability.
+ * 4. **Schema-on-error** — WebMCP defines no input validation of its own (the spec's
+ *    `ToolExecuteCallback` is just `Promise<any> (object input)`), and this module's own doc used
+ *    to say so ("the caller is responsible for validating it... WebMCP does not"). That left a
+ *    wrong-schema call to fail deep inside whatever `execute` does, with no way for the caller to
+ *    self-correct in the same turn. `execute` now runs the manifest's own
+ *    {@link findCapabilityInputError} first and, on failure, throws the same
+ *    `"<id>: <reason>. Expected input: <schema>"` shape `page-executor.ts` already uses for
+ *    `page.*` — one discipline, not two.
+ */
+import { findCapabilityInputError } from './capability.js';
 /** Thrown in place of executing, when a call needed confirmation and did not get it. */
 export class WebMcpConfirmationRequiredError extends Error {
     capabilityId;
@@ -11,6 +61,32 @@ export class WebMcpConfirmationRequiredError extends Error {
         this.name = 'WebMcpConfirmationRequiredError';
     }
 }
+/**
+ * The spec's tool-name rule, verbatim: "The tool definition's name's length must be between 1 and
+ * 128, inclusive, and only consist of ASCII alphanumeric code points, U+005F LOW LINE (_), U+002D
+ * HYPHEN-MINUS (-), and U+002E FULL STOP (.)." A name outside this is rejected by `registerTool`
+ * with an `InvalidStateError` `DOMException` — this projection checks it earlier, at manifest time.
+ */
+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) {
+    return WEBMCP_TOOL_NAME_PATTERN.test(name);
+}
+/**
+ * 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
+ * defect caught before any registration is attempted, not a runtime refusal of a call.
+ */
+export class InvalidWebMcpToolNameError extends Error {
+    capabilityId;
+    constructor(capabilityId) {
+        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)');
+        this.capabilityId = capabilityId;
+        this.name = 'InvalidWebMcpToolNameError';
+    }
+}
 /**
  * Projects one capability into a WebMCP registration.
  *
@@ -25,21 +101,42 @@ export class WebMcpConfirmationRequiredError 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; the caller is
- * responsible for validating it against `capability.inputSchema` — WebMCP does not.
- * @param options - Optional confirmation handler; required in practice for any capability
- * declaring `requiresConfirmation`.
+ * @param execute - Runs the capability. Receives the raw argument object, 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`.
  * @returns The registration object to hand to `registerTool`.
+ * @throws {@link InvalidWebMcpToolNameError} synchronously, if `capability.id` cannot be a WebMCP
+ * tool name.
  * @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);
+    }
+    const { title, annotations, signal, exposedTo } = options;
+    const resolvedAnnotations = {
+        readOnlyHint: capability.risk === 'read',
+        ...annotations,
+    };
+    const registerOptions = signal !== undefined || exposedTo !== undefined
+        ? { ...(signal !== undefined ? { signal } : {}), ...(exposedTo !== undefined ? { exposedTo } : {}) }
+        : undefined;
     return {
         name: capability.id,
+        ...(title !== undefined ? { title } : {}),
         description: capability.description,
         inputSchema: capability.inputSchema,
         execute: async (args) => {
             const input = args ?? {};
+            // 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);
+            if (inputError !== null) {
+                throw new Error(`${capability.id}: ${inputError}. Expected input: ${JSON.stringify(capability.inputSchema)}`);
+            }
             if (capability.requiresConfirmation === true) {
                 const { requestUserInteraction } = options;
                 if (!requestUserInteraction) {
@@ -52,14 +149,23 @@ export function toWebMcpTool(capability, execute, options = {}) {
             }
             return execute(capability.id, input);
         },
+        annotations: resolvedAnnotations,
+        ...(registerOptions !== undefined ? { registerOptions } : {}),
     };
 }
 /**
  * Projects a whole manifest.
  *
+ * `options` is shared across every capability — safe for `requestUserInteraction`, `signal`, and
+ * `exposedTo`, which are naturally uniform for one registration session; do not pass `title`
+ * through this one, since it would repeat verbatim across every tool in the manifest (see
+ * {@link ToWebMcpToolOptions.title}).
+ *
  * @param capabilities - Capabilities to expose, already filtered by whatever policy applies.
  * @param execute - Shared dispatcher, keyed by capability id.
  * @returns One registration per capability, in manifest order.
+ * @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));

package/dist/webmcp.js.map

@@ -1 +1 @@
-{"version":3,"file":"webmcp.js","sourceRoot":"","sources":["../src/webmcp.ts"],"names":[],"mappings":"AAgDA,wFAAwF;AACxF,MAAM,OAAO,+BAAgC,SAAQ,KAAK;IACnC;IAA+B;IAApD,YAAqB,YAAoB,EAAW,MAAiC;QACnF,KAAK,CACH,MAAM,KAAK,UAAU;YACnB,CAAC,CAAC,YAAY,YAAY,4BAA4B;YACtD,CAAC,CAAC,YAAY,YAAY,6EAA6E,CAC1G,CAAC;QALiB,iBAAY,GAAZ,YAAY,CAAQ;QAAW,WAAM,GAAN,MAAM,CAA2B;QAMnF,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAC;IAChD,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY,CAC1B,UAAyB,EACzB,OAAwE,EACxE,UAA+B,EAAE;IAEjC,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,EAAE;QACnB,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACtB,MAAM,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC;YACzB,IAAI,UAAU,CAAC,oBAAoB,KAAK,IAAI,EAAE,CAAC;gBAC7C,MAAM,EAAE,sBAAsB,EAAE,GAAG,OAAO,CAAC;gBAC3C,IAAI,CAAC,sBAAsB,EAAE,CAAC;oBAC5B,MAAM,IAAI,+BAA+B,CAAC,UAAU,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;gBACzE,CAAC;gBACD,MAAM,QAAQ,GAAG,MAAM,sBAAsB,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;gBAC3E,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;oBACtB,MAAM,IAAI,+BAA+B,CAAC,UAAU,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;gBACvE,CAAC;YACH,CAAC;YACD,OAAO,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QACvC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,YAAsC,EACtC,OAAwE,EACxE,UAA+B,EAAE;IAEjC,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AACtF,CAAC"}
+{"version":3,"file":"webmcp.js","sourceRoot":"","sources":["../src/webmcp.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/agentic",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -14,18 +14,26 @@
     "admission": "admitted",
     "entries": {
       ".": "universal",
-      "./dom": "browser"
+      "./dom": "browser",
+      "./a2ui": "universal"
     }
   },
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./dom": {
       "types": "./dist/dom/index.d.ts",
-      "import": "./dist/dom/index.js"
+      "import": "./dist/dom/index.js",
+      "default": "./dist/dom/index.js"
+    },
+    "./a2ui": {
+      "types": "./dist/a2ui/index.d.ts",
+      "import": "./dist/a2ui/index.js",
+      "default": "./dist/a2ui/index.js"
     }
   },
   "files": [
@@ -41,7 +49,8 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@jini-ai/protocol": "0.1.0"
+    "zod": "^3.25.76",
+    "@jini-ai/protocol": "0.1.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^2.1.9",