@jini-ai/agentic 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @jini-ai/agentic
 
+## 0.4.3
+
+### Patch Changes
+
+- Tovu clean-up release (2026-10-08): code Tovu moved into Jini, plus the Jini clean-up (see the commit log since 0.4.2).
+
 ## 0.4.2 — 2026-10-06
 
 - `@jini-ai/agentic/a2ui`: `A2UI_DISPLAY_ONLY_PROPERTY` (`"displayOnly"` on `createSurface.surfaceProperties`) plus `displayOnlySurfaceIdOf` and `a2uiSurfaceIdOf` readers.

package/dist/a2ui/agent-to-renderer.d.ts

@@ -0,0 +1,613 @@
+/**
+ * @module agent-to-renderer
+ *
+ * A2UI v1.0 agent→renderer envelope — mirrors `specification/v1_0/json/agent_to_renderer.json`
+ * (fetched from https://github.com/a2ui-project/a2ui, `main` branch, this session). Every
+ * required/optional field and every `additionalProperties: false` closure below was copied
+ * directly from that JSON Schema, not guessed. See `common-types.ts`'s module doc for the overall
+ * scope note (wire shape only; catalog membership is a separate runtime concern).
+ *
+ * The six message kinds, each keyed by version + exactly one message-type key
+ * (`createSurface` | `updateComponents` | `updateDataModel` | `deleteSurface` | `callFunction` +
+ * `functionCallId` | `actionResponse` + `actionId`):
+ * `CreateSurfaceMessage`, `UpdateComponentsMessage`, `UpdateDataModelMessage`,
+ * `DeleteSurfaceMessage`, `CallFunctionMessage`, `ActionResponseMessage`.
+ *
+ * `parseAgentToRendererMessage` is a hand-written dispatcher, not a plain `z.union(...)`: zod's
+ * union error for a 6-branch, all-`.strict()` union is an unreadable dump of all 6 branches'
+ * failures at once. Real renderers need to tell an agent *specifically* "you sent no version",
+ * "you sent two message-type keys", or "`updateComponents` is missing `surfaceId`" — so this
+ * dispatcher inspects the envelope's own shape first (which key is present) and only then
+ * validates against the one matching schema, matching what `renderer_to_agent.json`'s own error
+ * schema anticipates (`VALIDATION_FAILED` with a JSON-Pointer `path` into the offending field).
+ */
+import { z } from 'zod';
+/**
+ * A component's wire shape is only closed by its *catalog's* own per-type schema (e.g. `Text`
+ * requires `text`, forbids unknown extra keys via that type's own `unevaluatedProperties: false`)
+ * — a shape this module cannot know statically, since a renderer may be configured with any
+ * catalog. This schema validates only what every component, in every catalog, always carries:
+ * an `id` and a `component` type-name string. `catalog.ts`/`interpreter.ts` layer the closed,
+ * per-type check on top at runtime (component-type whitelisting against the active catalog).
+ */
+export declare const WireComponentSchema: z.ZodObject<{
+    id: z.ZodString;
+    component: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    id: z.ZodString;
+    component: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    id: z.ZodString;
+    component: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>;
+export type WireComponent = z.infer<typeof WireComponentSchema> & Record<string, unknown>;
+/** `agent_to_renderer.json#/$defs/ComponentsList` — "A list containing UI components for the surface." `minItems: 1`. */
+export declare const ComponentsListSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    component: z.ZodString;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    id: z.ZodString;
+    component: z.ZodString;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    id: z.ZodString;
+    component: z.ZodString;
+}, z.ZodTypeAny, "passthrough">>, "many">;
+export type ComponentsList = z.infer<typeof ComponentsListSchema>;
+export declare const CreateSurfaceMessageSchema: z.ZodObject<{
+    version: z.ZodLiteral<"v1.0">;
+    createSurface: z.ZodObject<{
+        surfaceId: z.ZodString;
+        catalogId: z.ZodString;
+        surfaceProperties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        sendDataModel: z.ZodOptional<z.ZodBoolean>;
+        components: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodString;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            id: z.ZodString;
+            component: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            id: z.ZodString;
+            component: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">>, "many">>;
+        dataModel: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strict", z.ZodTypeAny, {
+        surfaceId: string;
+        catalogId: string;
+        surfaceProperties?: Record<string, unknown> | undefined;
+        sendDataModel?: boolean | undefined;
+        components?: z.objectOutputType<{
+            id: z.ZodString;
+            component: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[] | undefined;
+        dataModel?: Record<string, unknown> | undefined;
+    }, {
+        surfaceId: string;
+        catalogId: string;
+        surfaceProperties?: Record<string, unknown> | undefined;
+        sendDataModel?: boolean | undefined;
+        components?: z.objectInputType<{
+            id: z.ZodString;
+            component: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[] | undefined;
+        dataModel?: Record<string, unknown> | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    version: "v1.0";
+    createSurface: {
+        surfaceId: string;
+        catalogId: string;
+        surfaceProperties?: Record<string, unknown> | undefined;
+        sendDataModel?: boolean | undefined;
+        components?: z.objectOutputType<{
+            id: z.ZodString;
+            component: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[] | undefined;
+        dataModel?: Record<string, unknown> | undefined;
+    };
+}, {
+    version: "v1.0";
+    createSurface: {
+        surfaceId: string;
+        catalogId: string;
+        surfaceProperties?: Record<string, unknown> | undefined;
+        sendDataModel?: boolean | undefined;
+        components?: z.objectInputType<{
+            id: z.ZodString;
+            component: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[] | undefined;
+        dataModel?: Record<string, unknown> | undefined;
+    };
+}>;
+export type CreateSurfaceMessage = z.infer<typeof CreateSurfaceMessageSchema>;
+export declare const UpdateComponentsMessageSchema: z.ZodObject<{
+    version: z.ZodLiteral<"v1.0">;
+    updateComponents: z.ZodObject<{
+        surfaceId: z.ZodString;
+        components: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            component: z.ZodString;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            id: z.ZodString;
+            component: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            id: z.ZodString;
+            component: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        surfaceId: string;
+        components: z.objectOutputType<{
+            id: z.ZodString;
+            component: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+    }, {
+        surfaceId: string;
+        components: z.objectInputType<{
+            id: z.ZodString;
+            component: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+    }>;
+}, "strict", z.ZodTypeAny, {
+    version: "v1.0";
+    updateComponents: {
+        surfaceId: string;
+        components: z.objectOutputType<{
+            id: z.ZodString;
+            component: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+    };
+}, {
+    version: "v1.0";
+    updateComponents: {
+        surfaceId: string;
+        components: z.objectInputType<{
+            id: z.ZodString;
+            component: z.ZodString;
+        }, z.ZodTypeAny, "passthrough">[];
+    };
+}>;
+export type UpdateComponentsMessage = z.infer<typeof UpdateComponentsMessageSchema>;
+/**
+ * `value` is required by the real schema (`"required": ["surfaceId", "value"]`, re-fetched and
+ * checked 2026-07-29) — but declaring it `z.unknown()` did not make it so. In Zod 3 a key whose
+ * schema accepts `undefined` is satisfied by the key being absent entirely, and `undefined`
+ * inhabits `unknown`; `z.unknown().isOptional()` is literally `true`. So `{updateDataModel:
+ * {surfaceId: "s1"}}` parsed clean, and `interpreter.ts` then wrote that missing value at the
+ * default `'/'` pointer — replacing the surface's whole data model with `undefined`, silently,
+ * with no error message and no way for the agent to learn it had happened.
+ *
+ * Presence is therefore asserted on the object rather than on the field: there is no Zod 3 schema
+ * for "any value, but it has to be there," because optionality is decided by the field's *type*.
+ * `'value' in body` rather than a `!== undefined` check, so every legal JSON value — `null`
+ * (the spec's own delete verb), `false`, `0`, `""` — is still accepted as content.
+ *
+ * The same limitation leaves `value` typed `value?: unknown` on the inferred type. That is
+ * unavoidable in Zod 3 for an `unknown`-typed key (`undefined extends unknown`), and is why this
+ * is enforced at runtime rather than trusted to the type.
+ */
+export declare const UpdateDataModelMessageSchema: z.ZodObject<{
+    version: z.ZodLiteral<"v1.0">;
+    updateDataModel: z.ZodEffects<z.ZodObject<{
+        surfaceId: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        value: z.ZodUnknown;
+    }, "strict", z.ZodTypeAny, {
+        surfaceId: string;
+        value?: unknown;
+        path?: string | undefined;
+    }, {
+        surfaceId: string;
+        value?: unknown;
+        path?: string | undefined;
+    }>, {
+        surfaceId: string;
+        value?: unknown;
+        path?: string | undefined;
+    }, {
+        surfaceId: string;
+        value?: unknown;
+        path?: string | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    version: "v1.0";
+    updateDataModel: {
+        surfaceId: string;
+        value?: unknown;
+        path?: string | undefined;
+    };
+}, {
+    version: "v1.0";
+    updateDataModel: {
+        surfaceId: string;
+        value?: unknown;
+        path?: string | undefined;
+    };
+}>;
+export type UpdateDataModelMessage = z.infer<typeof UpdateDataModelMessageSchema>;
+export declare const DeleteSurfaceMessageSchema: z.ZodObject<{
+    version: z.ZodLiteral<"v1.0">;
+    deleteSurface: z.ZodObject<{
+        surfaceId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        surfaceId: string;
+    }, {
+        surfaceId: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    version: "v1.0";
+    deleteSurface: {
+        surfaceId: string;
+    };
+}, {
+    version: "v1.0";
+    deleteSurface: {
+        surfaceId: string;
+    };
+}>;
+export type DeleteSurfaceMessage = z.infer<typeof DeleteSurfaceMessageSchema>;
+export declare const CallFunctionMessageSchema: z.ZodObject<{
+    version: z.ZodLiteral<"v1.0">;
+    functionCallId: z.ZodString;
+    wantResponse: z.ZodOptional<z.ZodBoolean>;
+    callFunction: z.ZodType<import("./common-types.js").FunctionCall, z.ZodTypeDef, import("./common-types.js").FunctionCall>;
+}, "strict", z.ZodTypeAny, {
+    version: "v1.0";
+    functionCallId: string;
+    callFunction: import("./common-types.js").FunctionCall;
+    wantResponse?: boolean | undefined;
+}, {
+    version: "v1.0";
+    functionCallId: string;
+    callFunction: import("./common-types.js").FunctionCall;
+    wantResponse?: boolean | undefined;
+}>;
+export type CallFunctionMessage = z.infer<typeof CallFunctionMessageSchema>;
+export declare const ActionResponseMessageSchema: z.ZodObject<{
+    version: z.ZodLiteral<"v1.0">;
+    actionId: z.ZodString;
+    actionResponse: z.ZodEffects<z.ZodUnion<[z.ZodObject<{
+        value: z.ZodUnknown;
+    }, "strict", z.ZodTypeAny, {
+        value?: unknown;
+    }, {
+        value?: unknown;
+    }>, z.ZodObject<{
+        error: z.ZodObject<{
+            code: z.ZodString;
+            message: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            code: string;
+            message: string;
+        }, {
+            code: string;
+            message: string;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        error: {
+            code: string;
+            message: string;
+        };
+    }, {
+        error: {
+            code: string;
+            message: string;
+        };
+    }>]>, {
+        value?: unknown;
+    } | {
+        error: {
+            code: string;
+            message: string;
+        };
+    }, {
+        value?: unknown;
+    } | {
+        error: {
+            code: string;
+            message: string;
+        };
+    }>;
+}, "strict", z.ZodTypeAny, {
+    version: "v1.0";
+    actionId: string;
+    actionResponse: {
+        value?: unknown;
+    } | {
+        error: {
+            code: string;
+            message: string;
+        };
+    };
+}, {
+    version: "v1.0";
+    actionId: string;
+    actionResponse: {
+        value?: unknown;
+    } | {
+        error: {
+            code: string;
+            message: string;
+        };
+    };
+}>;
+export type ActionResponseMessage = z.infer<typeof ActionResponseMessageSchema>;
+export type AgentToRendererMessage = CreateSurfaceMessage | UpdateComponentsMessage | UpdateDataModelMessage | DeleteSurfaceMessage | CallFunctionMessage | ActionResponseMessage;
+declare const MESSAGE_KEY_SCHEMAS: {
+    readonly createSurface: z.ZodObject<{
+        version: z.ZodLiteral<"v1.0">;
+        createSurface: z.ZodObject<{
+            surfaceId: z.ZodString;
+            catalogId: z.ZodString;
+            surfaceProperties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            sendDataModel: z.ZodOptional<z.ZodBoolean>;
+            components: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                component: z.ZodString;
+            }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+                id: z.ZodString;
+                component: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+                id: z.ZodString;
+                component: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">>, "many">>;
+            dataModel: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strict", z.ZodTypeAny, {
+            surfaceId: string;
+            catalogId: string;
+            surfaceProperties?: Record<string, unknown> | undefined;
+            sendDataModel?: boolean | undefined;
+            components?: z.objectOutputType<{
+                id: z.ZodString;
+                component: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">[] | undefined;
+            dataModel?: Record<string, unknown> | undefined;
+        }, {
+            surfaceId: string;
+            catalogId: string;
+            surfaceProperties?: Record<string, unknown> | undefined;
+            sendDataModel?: boolean | undefined;
+            components?: z.objectInputType<{
+                id: z.ZodString;
+                component: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">[] | undefined;
+            dataModel?: Record<string, unknown> | undefined;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        version: "v1.0";
+        createSurface: {
+            surfaceId: string;
+            catalogId: string;
+            surfaceProperties?: Record<string, unknown> | undefined;
+            sendDataModel?: boolean | undefined;
+            components?: z.objectOutputType<{
+                id: z.ZodString;
+                component: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">[] | undefined;
+            dataModel?: Record<string, unknown> | undefined;
+        };
+    }, {
+        version: "v1.0";
+        createSurface: {
+            surfaceId: string;
+            catalogId: string;
+            surfaceProperties?: Record<string, unknown> | undefined;
+            sendDataModel?: boolean | undefined;
+            components?: z.objectInputType<{
+                id: z.ZodString;
+                component: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">[] | undefined;
+            dataModel?: Record<string, unknown> | undefined;
+        };
+    }>;
+    readonly updateComponents: z.ZodObject<{
+        version: z.ZodLiteral<"v1.0">;
+        updateComponents: z.ZodObject<{
+            surfaceId: z.ZodString;
+            components: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                component: z.ZodString;
+            }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+                id: z.ZodString;
+                component: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+                id: z.ZodString;
+                component: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">>, "many">;
+        }, "strict", z.ZodTypeAny, {
+            surfaceId: string;
+            components: z.objectOutputType<{
+                id: z.ZodString;
+                component: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">[];
+        }, {
+            surfaceId: string;
+            components: z.objectInputType<{
+                id: z.ZodString;
+                component: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">[];
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        version: "v1.0";
+        updateComponents: {
+            surfaceId: string;
+            components: z.objectOutputType<{
+                id: z.ZodString;
+                component: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">[];
+        };
+    }, {
+        version: "v1.0";
+        updateComponents: {
+            surfaceId: string;
+            components: z.objectInputType<{
+                id: z.ZodString;
+                component: z.ZodString;
+            }, z.ZodTypeAny, "passthrough">[];
+        };
+    }>;
+    readonly updateDataModel: z.ZodObject<{
+        version: z.ZodLiteral<"v1.0">;
+        updateDataModel: z.ZodEffects<z.ZodObject<{
+            surfaceId: z.ZodString;
+            path: z.ZodOptional<z.ZodString>;
+            value: z.ZodUnknown;
+        }, "strict", z.ZodTypeAny, {
+            surfaceId: string;
+            value?: unknown;
+            path?: string | undefined;
+        }, {
+            surfaceId: string;
+            value?: unknown;
+            path?: string | undefined;
+        }>, {
+            surfaceId: string;
+            value?: unknown;
+            path?: string | undefined;
+        }, {
+            surfaceId: string;
+            value?: unknown;
+            path?: string | undefined;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        version: "v1.0";
+        updateDataModel: {
+            surfaceId: string;
+            value?: unknown;
+            path?: string | undefined;
+        };
+    }, {
+        version: "v1.0";
+        updateDataModel: {
+            surfaceId: string;
+            value?: unknown;
+            path?: string | undefined;
+        };
+    }>;
+    readonly deleteSurface: z.ZodObject<{
+        version: z.ZodLiteral<"v1.0">;
+        deleteSurface: z.ZodObject<{
+            surfaceId: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            surfaceId: string;
+        }, {
+            surfaceId: string;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        version: "v1.0";
+        deleteSurface: {
+            surfaceId: string;
+        };
+    }, {
+        version: "v1.0";
+        deleteSurface: {
+            surfaceId: string;
+        };
+    }>;
+    readonly callFunction: z.ZodObject<{
+        version: z.ZodLiteral<"v1.0">;
+        functionCallId: z.ZodString;
+        wantResponse: z.ZodOptional<z.ZodBoolean>;
+        callFunction: z.ZodType<import("./common-types.js").FunctionCall, z.ZodTypeDef, import("./common-types.js").FunctionCall>;
+    }, "strict", z.ZodTypeAny, {
+        version: "v1.0";
+        functionCallId: string;
+        callFunction: import("./common-types.js").FunctionCall;
+        wantResponse?: boolean | undefined;
+    }, {
+        version: "v1.0";
+        functionCallId: string;
+        callFunction: import("./common-types.js").FunctionCall;
+        wantResponse?: boolean | undefined;
+    }>;
+    readonly actionResponse: z.ZodObject<{
+        version: z.ZodLiteral<"v1.0">;
+        actionId: z.ZodString;
+        actionResponse: z.ZodEffects<z.ZodUnion<[z.ZodObject<{
+            value: z.ZodUnknown;
+        }, "strict", z.ZodTypeAny, {
+            value?: unknown;
+        }, {
+            value?: unknown;
+        }>, z.ZodObject<{
+            error: z.ZodObject<{
+                code: z.ZodString;
+                message: z.ZodString;
+            }, "strict", z.ZodTypeAny, {
+                code: string;
+                message: string;
+            }, {
+                code: string;
+                message: string;
+            }>;
+        }, "strict", z.ZodTypeAny, {
+            error: {
+                code: string;
+                message: string;
+            };
+        }, {
+            error: {
+                code: string;
+                message: string;
+            };
+        }>]>, {
+            value?: unknown;
+        } | {
+            error: {
+                code: string;
+                message: string;
+            };
+        }, {
+            value?: unknown;
+        } | {
+            error: {
+                code: string;
+                message: string;
+            };
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        version: "v1.0";
+        actionId: string;
+        actionResponse: {
+            value?: unknown;
+        } | {
+            error: {
+                code: string;
+                message: string;
+            };
+        };
+    }, {
+        version: "v1.0";
+        actionId: string;
+        actionResponse: {
+            value?: unknown;
+        } | {
+            error: {
+                code: string;
+                message: string;
+            };
+        };
+    }>;
+};
+type MessageKey = keyof typeof MESSAGE_KEY_SCHEMAS;
+/** Exported so `interpreter.ts` can look up "which of the *known* message-type keys is present" the same way this module's own dispatcher does, instead of guessing from raw object-key order (which could pick up an unrelated extra top-level key first). */
+export declare const AGENT_TO_RENDERER_MESSAGE_KEYS: MessageKey[];
+export interface ParseFailure {
+    readonly ok: false;
+    readonly code: 'MISSING_VERSION' | 'UNSUPPORTED_VERSION' | 'NO_MESSAGE_KEY' | 'AMBIGUOUS_MESSAGE' | 'VALIDATION_FAILED';
+    readonly message: string;
+    readonly path?: string;
+}
+export interface ParseSuccess {
+    readonly ok: true;
+    readonly message: AgentToRendererMessage;
+}
+/**
+ * Validates a raw (untrusted, possibly-malformed) value as one A2UI agent→renderer envelope.
+ * Never throws — every failure mode (missing `version`, an unrecognized/absent message-type key,
+ * two message-type keys at once, or a structurally invalid message body) returns a tagged
+ * `ParseFailure` instead, mirroring how a real renderer must degrade on the wire: reject the one
+ * bad message with a specific reason, not crash the whole connection.
+ */
+export declare function parseAgentToRendererMessage(raw: unknown): ParseSuccess | ParseFailure;
+export {};
+//# sourceMappingURL=agent-to-renderer.d.ts.map