@jini-ai/agentic 0.1.0 → 0.1.1

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

@@ -0,0 +1,318 @@
+/**
+ * @module renderer-to-agent
+ *
+ * A2UI v1.0 renderer→agent envelope — mirrors `specification/v1_0/json/renderer_to_agent.json`
+ * (fetched from https://github.com/a2ui-project/a2ui, `main` branch, this session). Three message
+ * kinds, each envelope carrying `version` plus **exactly one** of `action` | `functionResponse` |
+ * `error` (`minProperties: 2, maxProperties: 2` in the real schema — enforced below via `.refine`,
+ * since zod's object schema has no direct min/max-properties primitive).
+ */
+import { z } from 'zod';
+/** `renderer_to_agent.json#/properties/action` — "Reports a user-initiated action from a component." */
+export declare const ActionMessagePayloadSchema: z.ZodObject<{
+    name: z.ZodString;
+    surfaceId: z.ZodString;
+    sourceComponentId: z.ZodString;
+    /** ISO 8601 timestamp — validated as a non-empty string, not parsed as a `Date`: the real schema only declares `format: "date-time"` (an annotation, not a structural constraint zod enforces by default). */
+    timestamp: z.ZodString;
+    context: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    wantResponse: z.ZodOptional<z.ZodBoolean>;
+    actionId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    surfaceId: string;
+    context: Record<string, unknown>;
+    sourceComponentId: string;
+    timestamp: string;
+    wantResponse?: boolean | undefined;
+    actionId?: string | undefined;
+}, {
+    name: string;
+    surfaceId: string;
+    context: Record<string, unknown>;
+    sourceComponentId: string;
+    timestamp: string;
+    wantResponse?: boolean | undefined;
+    actionId?: string | undefined;
+}>;
+export type ActionMessagePayload = z.infer<typeof ActionMessagePayloadSchema>;
+/** `renderer_to_agent.json#/properties/functionResponse`. */
+export declare const FunctionResponsePayloadSchema: z.ZodObject<{
+    functionCallId: z.ZodString;
+    call: z.ZodString;
+    value: z.ZodUnknown;
+}, "strip", z.ZodTypeAny, {
+    call: string;
+    functionCallId: string;
+    value?: unknown;
+}, {
+    call: string;
+    functionCallId: string;
+    value?: unknown;
+}>;
+export type FunctionResponsePayload = z.infer<typeof FunctionResponsePayloadSchema>;
+/**
+ * `renderer_to_agent.json#/properties/error` — two mutually-exclusive shapes: a `VALIDATION_FAILED`
+ * error (always carries `surfaceId` + a JSON-Pointer `path`), or a generic error (any other `code`,
+ * carrying exactly one of `surfaceId` XOR `functionCallId`).
+ */
+export declare const ValidationFailedErrorSchema: z.ZodObject<{
+    code: z.ZodLiteral<"VALIDATION_FAILED">;
+    surfaceId: z.ZodString;
+    path: z.ZodString;
+    message: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    surfaceId: string;
+    code: "VALIDATION_FAILED";
+    path: string;
+    message: string;
+}, {
+    surfaceId: string;
+    code: "VALIDATION_FAILED";
+    path: string;
+    message: string;
+}>;
+export type ValidationFailedError = z.infer<typeof ValidationFailedErrorSchema>;
+export declare const GenericErrorSchema: z.ZodEffects<z.ZodObject<{
+    code: z.ZodEffects<z.ZodString, string, string>;
+    message: z.ZodString;
+    surfaceId: z.ZodOptional<z.ZodString>;
+    functionCallId: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    code: z.ZodEffects<z.ZodString, string, string>;
+    message: z.ZodString;
+    surfaceId: z.ZodOptional<z.ZodString>;
+    functionCallId: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    code: z.ZodEffects<z.ZodString, string, string>;
+    message: z.ZodString;
+    surfaceId: z.ZodOptional<z.ZodString>;
+    functionCallId: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{
+    code: z.ZodEffects<z.ZodString, string, string>;
+    message: z.ZodString;
+    surfaceId: z.ZodOptional<z.ZodString>;
+    functionCallId: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    code: z.ZodEffects<z.ZodString, string, string>;
+    message: z.ZodString;
+    surfaceId: z.ZodOptional<z.ZodString>;
+    functionCallId: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export type GenericError = z.infer<typeof GenericErrorSchema>;
+export declare const ErrorPayloadSchema: z.ZodUnion<[z.ZodObject<{
+    code: z.ZodLiteral<"VALIDATION_FAILED">;
+    surfaceId: z.ZodString;
+    path: z.ZodString;
+    message: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    surfaceId: string;
+    code: "VALIDATION_FAILED";
+    path: string;
+    message: string;
+}, {
+    surfaceId: string;
+    code: "VALIDATION_FAILED";
+    path: string;
+    message: string;
+}>, z.ZodEffects<z.ZodObject<{
+    code: z.ZodEffects<z.ZodString, string, string>;
+    message: z.ZodString;
+    surfaceId: z.ZodOptional<z.ZodString>;
+    functionCallId: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    code: z.ZodEffects<z.ZodString, string, string>;
+    message: z.ZodString;
+    surfaceId: z.ZodOptional<z.ZodString>;
+    functionCallId: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    code: z.ZodEffects<z.ZodString, string, string>;
+    message: z.ZodString;
+    surfaceId: z.ZodOptional<z.ZodString>;
+    functionCallId: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{
+    code: z.ZodEffects<z.ZodString, string, string>;
+    message: z.ZodString;
+    surfaceId: z.ZodOptional<z.ZodString>;
+    functionCallId: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    code: z.ZodEffects<z.ZodString, string, string>;
+    message: z.ZodString;
+    surfaceId: z.ZodOptional<z.ZodString>;
+    functionCallId: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>]>;
+export type ErrorPayload = z.infer<typeof ErrorPayloadSchema>;
+export declare const ActionMessageSchema: z.ZodObject<{
+    version: z.ZodLiteral<"v1.0">;
+    action: z.ZodObject<{
+        name: z.ZodString;
+        surfaceId: z.ZodString;
+        sourceComponentId: z.ZodString;
+        /** ISO 8601 timestamp — validated as a non-empty string, not parsed as a `Date`: the real schema only declares `format: "date-time"` (an annotation, not a structural constraint zod enforces by default). */
+        timestamp: z.ZodString;
+        context: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        wantResponse: z.ZodOptional<z.ZodBoolean>;
+        actionId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        surfaceId: string;
+        context: Record<string, unknown>;
+        sourceComponentId: string;
+        timestamp: string;
+        wantResponse?: boolean | undefined;
+        actionId?: string | undefined;
+    }, {
+        name: string;
+        surfaceId: string;
+        context: Record<string, unknown>;
+        sourceComponentId: string;
+        timestamp: string;
+        wantResponse?: boolean | undefined;
+        actionId?: string | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    version: "v1.0";
+    action: {
+        name: string;
+        surfaceId: string;
+        context: Record<string, unknown>;
+        sourceComponentId: string;
+        timestamp: string;
+        wantResponse?: boolean | undefined;
+        actionId?: string | undefined;
+    };
+}, {
+    version: "v1.0";
+    action: {
+        name: string;
+        surfaceId: string;
+        context: Record<string, unknown>;
+        sourceComponentId: string;
+        timestamp: string;
+        wantResponse?: boolean | undefined;
+        actionId?: string | undefined;
+    };
+}>;
+export type ActionMessage = z.infer<typeof ActionMessageSchema>;
+export declare const FunctionResponseMessageSchema: z.ZodObject<{
+    version: z.ZodLiteral<"v1.0">;
+    functionResponse: z.ZodObject<{
+        functionCallId: z.ZodString;
+        call: z.ZodString;
+        value: z.ZodUnknown;
+    }, "strip", z.ZodTypeAny, {
+        call: string;
+        functionCallId: string;
+        value?: unknown;
+    }, {
+        call: string;
+        functionCallId: string;
+        value?: unknown;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    version: "v1.0";
+    functionResponse: {
+        call: string;
+        functionCallId: string;
+        value?: unknown;
+    };
+}, {
+    version: "v1.0";
+    functionResponse: {
+        call: string;
+        functionCallId: string;
+        value?: unknown;
+    };
+}>;
+export type FunctionResponseMessage = z.infer<typeof FunctionResponseMessageSchema>;
+export declare const ErrorMessageSchema: z.ZodObject<{
+    version: z.ZodLiteral<"v1.0">;
+    error: z.ZodUnion<[z.ZodObject<{
+        code: z.ZodLiteral<"VALIDATION_FAILED">;
+        surfaceId: z.ZodString;
+        path: z.ZodString;
+        message: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        surfaceId: string;
+        code: "VALIDATION_FAILED";
+        path: string;
+        message: string;
+    }, {
+        surfaceId: string;
+        code: "VALIDATION_FAILED";
+        path: string;
+        message: string;
+    }>, z.ZodEffects<z.ZodObject<{
+        code: z.ZodEffects<z.ZodString, string, string>;
+        message: z.ZodString;
+        surfaceId: z.ZodOptional<z.ZodString>;
+        functionCallId: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        code: z.ZodEffects<z.ZodString, string, string>;
+        message: z.ZodString;
+        surfaceId: z.ZodOptional<z.ZodString>;
+        functionCallId: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        code: z.ZodEffects<z.ZodString, string, string>;
+        message: z.ZodString;
+        surfaceId: z.ZodOptional<z.ZodString>;
+        functionCallId: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{
+        code: z.ZodEffects<z.ZodString, string, string>;
+        message: z.ZodString;
+        surfaceId: z.ZodOptional<z.ZodString>;
+        functionCallId: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        code: z.ZodEffects<z.ZodString, string, string>;
+        message: z.ZodString;
+        surfaceId: z.ZodOptional<z.ZodString>;
+        functionCallId: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>]>;
+}, "strict", z.ZodTypeAny, {
+    error: {
+        surfaceId: string;
+        code: "VALIDATION_FAILED";
+        path: string;
+        message: string;
+    } | z.objectOutputType<{
+        code: z.ZodEffects<z.ZodString, string, string>;
+        message: z.ZodString;
+        surfaceId: z.ZodOptional<z.ZodString>;
+        functionCallId: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">;
+    version: "v1.0";
+}, {
+    error: {
+        surfaceId: string;
+        code: "VALIDATION_FAILED";
+        path: string;
+        message: string;
+    } | z.objectInputType<{
+        code: z.ZodEffects<z.ZodString, string, string>;
+        message: z.ZodString;
+        surfaceId: z.ZodOptional<z.ZodString>;
+        functionCallId: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">;
+    version: "v1.0";
+}>;
+export type ErrorMessage = z.infer<typeof ErrorMessageSchema>;
+export type RendererToAgentMessage = ActionMessage | FunctionResponseMessage | ErrorMessage;
+export declare function buildActionMessage(payload: ActionMessagePayload): ActionMessage;
+export declare function buildFunctionResponseMessage(payload: FunctionResponsePayload): FunctionResponseMessage;
+export declare function buildValidationFailedMessage(surfaceId: string, path: string, message: string): ErrorMessage;
+export declare function buildGenericErrorMessage(code: string, message: string, target: {
+    surfaceId: string;
+} | {
+    functionCallId: string;
+}): ErrorMessage;
+export interface RendererParseFailure {
+    readonly ok: false;
+    readonly reason: string;
+}
+export interface RendererParseSuccess {
+    readonly ok: true;
+    readonly message: RendererToAgentMessage;
+}
+/** Same "inspect the shape, validate the one matching branch" dispatcher as `parseAgentToRendererMessage` — see that function's doc for why this beats a plain `z.union`. Used by tests and by anything on the agent side of this fixture that needs to validate what the browser sent. */
+export declare function parseRendererToAgentMessage(raw: unknown): RendererParseSuccess | RendererParseFailure;
+//# sourceMappingURL=renderer-to-agent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"renderer-to-agent.d.ts","sourceRoot":"","sources":["../../src/a2ui/renderer-to-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,wGAAwG;AACxG,eAAO,MAAM,0BAA0B;;;;IAIrC,8MAA8M;;;;;;;;;;;;;;;;;;;;;EAK9M,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,6DAA6D;AAC7D,eAAO,MAAM,6BAA6B;;;;;;;;;;;;EAIxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;EAO7B,CAAC;AACZ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;gCAQwF,CAAC;AACxH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kCAA6D,CAAC;AAC7F,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,mBAAmB;;;;;;QA7C9B,8MAA8M;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+CrM,CAAC;AACZ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE/B,CAAC;AACZ,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEpB,CAAC;AACZ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,MAAM,MAAM,sBAAsB,GAAG,aAAa,GAAG,uBAAuB,GAAG,YAAY,CAAC;AAE5F,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAE/E;AACD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,uBAAuB,GAAG,uBAAuB,CAEtG;AACD,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,CAE3G;AACD,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,MAAM,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,GACzD,YAAY,CAEd;AAID,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AACD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;CAC1C;AAED,2RAA2R;AAC3R,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,OAAO,GAAG,oBAAoB,GAAG,oBAAoB,CAqBrG"}

package/dist/a2ui/renderer-to-agent.js

@@ -0,0 +1,98 @@
+/**
+ * @module renderer-to-agent
+ *
+ * A2UI v1.0 renderer→agent envelope — mirrors `specification/v1_0/json/renderer_to_agent.json`
+ * (fetched from https://github.com/a2ui-project/a2ui, `main` branch, this session). Three message
+ * kinds, each envelope carrying `version` plus **exactly one** of `action` | `functionResponse` |
+ * `error` (`minProperties: 2, maxProperties: 2` in the real schema — enforced below via `.refine`,
+ * since zod's object schema has no direct min/max-properties primitive).
+ */
+import { z } from 'zod';
+import { CallIdSchema } from './common-types.js';
+const PROTOCOL_VERSION = 'v1.0';
+/** `renderer_to_agent.json#/properties/action` — "Reports a user-initiated action from a component." */
+export const ActionMessagePayloadSchema = z.object({
+    name: z.string(),
+    surfaceId: z.string(),
+    sourceComponentId: z.string(),
+    /** ISO 8601 timestamp — validated as a non-empty string, not parsed as a `Date`: the real schema only declares `format: "date-time"` (an annotation, not a structural constraint zod enforces by default). */
+    timestamp: z.string(),
+    context: z.record(z.string(), z.unknown()),
+    wantResponse: z.boolean().optional(),
+    actionId: z.string().optional(),
+});
+/** `renderer_to_agent.json#/properties/functionResponse`. */
+export const FunctionResponsePayloadSchema = z.object({
+    functionCallId: CallIdSchema,
+    call: z.string(),
+    value: z.unknown(),
+});
+/**
+ * `renderer_to_agent.json#/properties/error` — two mutually-exclusive shapes: a `VALIDATION_FAILED`
+ * error (always carries `surfaceId` + a JSON-Pointer `path`), or a generic error (any other `code`,
+ * carrying exactly one of `surfaceId` XOR `functionCallId`).
+ */
+export const ValidationFailedErrorSchema = z
+    .object({
+    code: z.literal('VALIDATION_FAILED'),
+    surfaceId: z.string(),
+    path: z.string(),
+    message: z.string(),
+})
+    .strict();
+export const GenericErrorSchema = z
+    .object({
+    code: z.string().refine((c) => c !== 'VALIDATION_FAILED', 'code must not be VALIDATION_FAILED here'),
+    message: z.string(),
+    surfaceId: z.string().optional(),
+    functionCallId: CallIdSchema.optional(),
+})
+    .passthrough()
+    .refine((v) => ('surfaceId' in v) !== ('functionCallId' in v), 'exactly one of surfaceId/functionCallId is required');
+export const ErrorPayloadSchema = z.union([ValidationFailedErrorSchema, GenericErrorSchema]);
+export const ActionMessageSchema = z
+    .object({ version: z.literal(PROTOCOL_VERSION), action: ActionMessagePayloadSchema })
+    .strict();
+export const FunctionResponseMessageSchema = z
+    .object({ version: z.literal(PROTOCOL_VERSION), functionResponse: FunctionResponsePayloadSchema })
+    .strict();
+export const ErrorMessageSchema = z
+    .object({ version: z.literal(PROTOCOL_VERSION), error: ErrorPayloadSchema })
+    .strict();
+export function buildActionMessage(payload) {
+    return { version: PROTOCOL_VERSION, action: payload };
+}
+export function buildFunctionResponseMessage(payload) {
+    return { version: PROTOCOL_VERSION, functionResponse: payload };
+}
+export function buildValidationFailedMessage(surfaceId, path, message) {
+    return { version: PROTOCOL_VERSION, error: { code: 'VALIDATION_FAILED', surfaceId, path, message } };
+}
+export function buildGenericErrorMessage(code, message, target) {
+    return { version: PROTOCOL_VERSION, error: { code, message, ...target } };
+}
+const MESSAGE_KEYS = ['action', 'functionResponse', 'error'];
+/** Same "inspect the shape, validate the one matching branch" dispatcher as `parseAgentToRendererMessage` — see that function's doc for why this beats a plain `z.union`. Used by tests and by anything on the agent side of this fixture that needs to validate what the browser sent. */
+export function parseRendererToAgentMessage(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return { ok: false, reason: 'envelope must be a JSON object' };
+    }
+    const obj = raw;
+    if (obj.version !== PROTOCOL_VERSION) {
+        return { ok: false, reason: `envelope declares version ${JSON.stringify(obj.version)}, expected "${PROTOCOL_VERSION}"` };
+    }
+    const presentKeys = MESSAGE_KEYS.filter((key) => key in obj);
+    if (presentKeys.length !== 1) {
+        return { ok: false, reason: `expected exactly one of ${MESSAGE_KEYS.join(', ')}, found ${presentKeys.length}` };
+    }
+    const key = presentKeys[0];
+    const schema = key === 'action' ? ActionMessageSchema : key === 'functionResponse' ? FunctionResponseMessageSchema : ErrorMessageSchema;
+    const result = schema.safeParse(obj);
+    if (!result.success) {
+        // Same zod guarantee as `parseAgentToRendererMessage` relies on: `success: false` implies a
+        // non-empty `issues` array — see that function's comment for why this is asserted, not branched.
+        return { ok: false, reason: result.error.issues[0].message };
+    }
+    return { ok: true, message: result.data };
+}
+//# sourceMappingURL=renderer-to-agent.js.map

package/dist/a2ui/renderer-to-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer-to-agent.js","sourceRoot":"","sources":["../../src/a2ui/renderer-to-agent.ts"],"names":[],"mappings":"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"}

package/dist/a2ui/resolve.d.ts

@@ -0,0 +1,28 @@
+import type { Catalog } from './catalog.js';
+export type ResolveSide = 'renderer' | 'agent';
+/** Set while resolving one item of a `ChildList` template (`common_types.json`'s "Collection Scope"): relative (no leading `/`) `DataBinding` paths resolve under `${basePath}/${index}/...` instead of the data-model root. */
+export interface ItemScope {
+    readonly basePath: string;
+    readonly index: number;
+}
+export interface ResolveContext {
+    readonly dataModel: unknown;
+    readonly catalog: Catalog;
+    /** Which side is *evaluating* this binding — the renderer resolving a component's own props (`'renderer'`), or something acting on the agent's behalf. A2UI's spec doesn't explicitly name a case where the agent-side evaluates a `Dynamic*` binding (that's a renderer-only concept — the agent only ever sends `callFunction` for direct RPC), but `callableFromOf` is checked against this side regardless, so a future agent-side evaluator (e.g. resolving `action.event.context` bindings before dispatch — which today happens on the renderer, see `interpreter.ts`'s `buildAction`) is covered by the same boundary without a second resolver. */
+    readonly side: ResolveSide;
+    readonly itemScope?: ItemScope;
+}
+export type ResolveFailureReason = 'PATH_NOT_FOUND' | 'FUNCTION_NOT_REGISTERED' | 'FUNCTION_NOT_CALLABLE_FROM_SIDE' | 'FUNCTION_NOT_IMPLEMENTED' | 'INDEX_OUTSIDE_LIST_CONTEXT' | 'RELATIVE_PATH_OUTSIDE_LIST_CONTEXT';
+export interface ResolveFailure {
+    readonly ok: false;
+    readonly reason: ResolveFailureReason;
+    readonly detail: string;
+}
+export interface ResolveOk {
+    readonly ok: true;
+    readonly value: unknown;
+}
+export type ResolveResult = ResolveOk | ResolveFailure;
+/** Resolves any `Dynamic*` value (`DynamicString`/`DynamicNumber`/`DynamicBoolean`/`DynamicStringList`/`DynamicValue` all share this one shape: literal | `DataBinding` | `FunctionCall`). */
+export declare function resolveDynamicValue(value: unknown, ctx: ResolveContext): ResolveResult;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/a2ui/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/a2ui/resolve.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAI5C,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC;AAE/C,gOAAgO;AAChO,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,4nBAA4nB;IAC5nB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED,MAAM,MAAM,oBAAoB,GAC5B,gBAAgB,GAChB,yBAAyB,GACzB,iCAAiC,GACjC,0BAA0B,GAC1B,4BAA4B,GAC5B,oCAAoC,CAAC;AAEzC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AACD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AACD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,cAAc,CAAC;AAgGvD,8LAA8L;AAC9L,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,GAAG,aAAa,CAItF"}

package/dist/a2ui/resolve.js

@@ -0,0 +1,118 @@
+/**
+ * @module resolve
+ *
+ * Resolves A2UI's `Dynamic*` binding types (literal | `DataBinding` | `FunctionCall`) against a
+ * surface's data model. This is the piece the task brief called out as GenUI/AG-UI having no
+ * equivalent of: AG-UI's `state_update` event is "some path changed, some value" with no binding
+ * *resolution* step — A2UI's `Dynamic*` types are unresolved references a renderer must actively
+ * walk the data model to answer.
+ *
+ * **Never throws.** Every failure mode (a path that doesn't resolve, a function that isn't
+ * registered, a function that crosses a `callableFrom` boundary it isn't allowed to cross, `@index`
+ * used outside a list-template context) returns a tagged `ResolveFailure` instead — this is the
+ * direct answer to this task's adversarial question "a binding whose path doesn't resolve — does
+ * it crash or degrade sanely?": it degrades sanely, always, by construction (no code path in this
+ * module can throw on bad *input data*; only a genuine programming error, e.g. calling this module
+ * incorrectly, would).
+ */
+import { getAtPointer, joinPointer, parsePointerTokens } from './json-pointer.js';
+import { callableFromOf, isFunctionRegistered } from './catalog.js';
+function isDataBinding(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && 'path' in value && Object.keys(value).length === 1;
+}
+function isFunctionCall(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) && 'call' in value && typeof value.call === 'string';
+}
+function resolveBindingPath(path, ctx) {
+    // A relative path is still RFC 6901 syntax, so its `~0`/`~1` escapes must be decoded into real
+    // token text before `joinPointer` re-escapes them. Splitting the raw string on `/` instead would
+    // hand `joinPointer` already-escaped text and double-escape it, making a relative `a~1b` resolve
+    // the literal key `a~1b` while the equivalent absolute pointer correctly resolves `a/b`.
+    const absolute = path.startsWith('/')
+        ? path
+        : ctx.itemScope
+            ? joinPointer(ctx.itemScope.basePath, String(ctx.itemScope.index), ...parsePointerTokens(`/${path}`))
+            : null;
+    if (absolute === null) {
+        return { ok: false, reason: 'RELATIVE_PATH_OUTSIDE_LIST_CONTEXT', detail: `relative path "${path}" used outside a list-template item context` };
+    }
+    const result = getAtPointer(ctx.dataModel, absolute);
+    if (!result.found) {
+        return { ok: false, reason: 'PATH_NOT_FOUND', detail: `no value at "${absolute}" in the current data model` };
+    }
+    return { ok: true, value: result.value };
+}
+function resolveFunctionCall(call, ctx) {
+    if (call.call === '@index') {
+        if (!ctx.itemScope) {
+            return { ok: false, reason: 'INDEX_OUTSIDE_LIST_CONTEXT', detail: '@index used outside a list-template item context' };
+        }
+        const offsetArg = call.args?.offset;
+        const offsetResult = offsetArg === undefined ? { ok: true, value: 0 } : resolveDynamicValue(offsetArg, ctx);
+        if (!offsetResult.ok)
+            return offsetResult;
+        const offset = typeof offsetResult.value === 'number' ? offsetResult.value : 0;
+        return { ok: true, value: ctx.itemScope.index + offset };
+    }
+    if (!isFunctionRegistered(ctx.catalog, call.call)) {
+        return { ok: false, reason: 'FUNCTION_NOT_REGISTERED', detail: `function "${call.call}" is not registered in catalog "${ctx.catalog.catalogId}"` };
+    }
+    const callableFrom = callableFromOf(ctx.catalog, call.call);
+    const allowed = callableFrom === 'rendererOrAgent' || (callableFrom === 'rendererOnly' && ctx.side === 'renderer') || (callableFrom === 'agentOnly' && ctx.side === 'agent');
+    if (!allowed) {
+        return {
+            ok: false,
+            reason: 'FUNCTION_NOT_CALLABLE_FROM_SIDE',
+            detail: `function "${call.call}" has callableFrom="${callableFrom}", not callable from the "${ctx.side}" side`,
+        };
+    }
+    const spec = ctx.catalog.functions.get(call.call);
+    if (!spec?.impl) {
+        return { ok: false, reason: 'FUNCTION_NOT_IMPLEMENTED', detail: `function "${call.call}" is registered but this renderer has no implementation for it` };
+    }
+    const resolvedArgs = {};
+    for (const [key, argValue] of Object.entries(call.args ?? {})) {
+        const argResult = resolveArgValue(argValue, ctx);
+        if (!argResult.ok)
+            return argResult;
+        resolvedArgs[key] = argResult.value;
+    }
+    return { ok: true, value: spec.impl(resolvedArgs) };
+}
+/**
+ * Resolves one `FunctionCall` arg value, recursing into arrays element-by-element. Real
+ * basic-catalog functions commonly type an arg as an *array* of `Dynamic*` values (e.g. `and`/`or`'s
+ * `values: DynamicBoolean[]`, confirmed against `specification/v1_0/catalogs/basic/catalog.json`'s
+ * own function definitions and the spec repo's `button_checks.json` conformance fixture, both
+ * fetched this session) — `common_types.json`'s generic `DynamicValue` schema's own `array` branch
+ * has no `items` sub-schema (it does not itself promise recursive binding resolution), so this
+ * per-element recursion is a deliberate generalization by this port, not a literal requirement of
+ * that one generic type — done because without it, an array-of-`DynamicBoolean` arg's own nested
+ * `DataBinding`/`FunctionCall` entries would pass through unresolved (as raw, non-boolean objects)
+ * to a function's `impl`, silently producing wrong results instead of a clean failure or a correct
+ * answer. `resolveDynamicValue` itself is left alone (a literal-array `DynamicValue` at the top
+ * level — e.g. a `DynamicStringList`'s literal-array branch — still passes through as-is, matching
+ * the generic type's own contract); only this arg-resolution path recurses.
+ */
+function resolveArgValue(argValue, ctx) {
+    if (Array.isArray(argValue)) {
+        const resolvedItems = [];
+        for (const item of argValue) {
+            const itemResult = resolveArgValue(item, ctx);
+            if (!itemResult.ok)
+                return itemResult;
+            resolvedItems.push(itemResult.value);
+        }
+        return { ok: true, value: resolvedItems };
+    }
+    return resolveDynamicValue(argValue, ctx);
+}
+/** Resolves any `Dynamic*` value (`DynamicString`/`DynamicNumber`/`DynamicBoolean`/`DynamicStringList`/`DynamicValue` all share this one shape: literal | `DataBinding` | `FunctionCall`). */
+export function resolveDynamicValue(value, ctx) {
+    if (isDataBinding(value))
+        return resolveBindingPath(value.path, ctx);
+    if (isFunctionCall(value))
+        return resolveFunctionCall(value, ctx);
+    return { ok: true, value };
+}
+//# sourceMappingURL=resolve.js.map

package/dist/a2ui/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/a2ui/resolve.ts"],"names":[],"mappings":"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"}

package/dist/a2ui/tree.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module tree
+ *
+ * Flattens the component adjacency list (`id -> ComponentInstance`, each instance's `children`
+ * being an array of other ids) into an ordered, depth-first render list — the two adversarial
+ * cases this exists to answer sanely: **a child id that doesn't exist** in the map, and **a
+ * circular reference** (A -> B -> A). Neither may crash or infinite-loop a renderer; both must
+ * degrade to a visible, inert placeholder node instead.
+ *
+ * Scope: only the *static array* form of `ChildList` (`common_types.json#/$defs/ChildList`'s
+ * first `oneOf` branch) is walked here. The *template* form (`{componentId, path}`, generating N
+ * children from a data-model list) is accepted by the wire schema (`ChildListSchema`) but not
+ * expanded by this port — see `../source-map.md` for why (a distinct, substantially larger
+ * rendering feature: item-scoped relative-path resolution, `@index`, per-item React keys for one
+ * shared component definition rendered N times). A `getChildIds` callback that always returns
+ * `[]` for a template-shaped `children` value is a safe, honest way to consume this module without
+ * pretending template lists render.
+ */
+export interface ComponentLike {
+    readonly id: string;
+}
+export type RenderNodeStatus = 'ok' | 'missing' | 'cycle';
+export interface RenderNode {
+    readonly id: string;
+    readonly depth: number;
+    readonly status: RenderNodeStatus;
+}
+/**
+ * @param components The full component map (id -> instance).
+ * @param rootId The id to start walking from (typically `'root'`, but not assumed — a surface
+ * with no `root` component yet is the caller's concern, not this function's; see
+ * `interpreter.ts`'s `getRoot()`).
+ * @param getChildIds Given a present component, returns its child ids in render order (`[]` for
+ * a leaf, or a template-shaped `ChildList` this port doesn't expand — see module doc).
+ * @returns A depth-first, pre-order flattening. A `missing` node is a leaf in the output (its own
+ * children are never visited — there is nothing to look up). A `cycle` node is also a leaf: the
+ * id is emitted once more so a renderer can show *where* the cycle closes, but its children are
+ * not walked again (that walk already happened higher up the same path).
+ */
+export declare function flattenRenderTree<C extends ComponentLike>(components: ReadonlyMap<string, C>, rootId: string, getChildIds: (component: C) => readonly string[]): RenderNode[];
+//# sourceMappingURL=tree.d.ts.map

package/dist/a2ui/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/a2ui/tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC;AAE1D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,aAAa,EACvD,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,EAClC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,SAAS,MAAM,EAAE,GAC/C,UAAU,EAAE,CAuBd"}