@xemahq/kernel-contracts 0.2.3 → 0.3.1

package/dist/agent-workspace/awp-spec.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://xema.dev/schemas/awp-spec.v1.json",
-  "emittedAt": "2026-06-07T09:05:01.778Z",
+  "emittedAt": "2026-06-07T10:41:18.819Z",
   "spec": {
     "id": "awp/v1",
     "version": "1.2.0",

package/dist/widget/index.d.ts

@@ -0,0 +1,5 @@
+export * from './lib/chat-widget-kind';
+export * from './lib/chat-widget-payloads';
+export * from './lib/chat-widget-envelope';
+export * from './lib/widget-contribution';
+//# sourceMappingURL=index.d.ts.map

package/dist/widget/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/widget/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC"}

package/dist/widget/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./lib/chat-widget-kind"), exports);
+__exportStar(require("./lib/chat-widget-payloads"), exports);
+__exportStar(require("./lib/chat-widget-envelope"), exports);
+__exportStar(require("./lib/widget-contribution"), exports);
+//# sourceMappingURL=index.js.map

package/dist/widget/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/widget/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,6DAA2C;AAC3C,6DAA2C;AAC3C,4DAA0C"}

package/dist/widget/lib/chat-widget-envelope.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export interface ChatWidgetEnvelope {
+    readonly kind: string;
+    readonly version: number;
+    readonly payload: unknown;
+}
+export declare const ChatWidgetEnvelopeSchema: z.ZodType<ChatWidgetEnvelope>;
+export declare enum ChatWidgetFallbackReason {
+    UnknownKind = "unknown-kind",
+    InvalidPayload = "invalid-payload",
+    UnsupportedVersion = "unsupported-version"
+}
+//# sourceMappingURL=chat-widget-envelope.d.ts.map

package/dist/widget/lib/chat-widget-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-widget-envelope.d.ts","sourceRoot":"","sources":["../../../src/widget/lib/chat-widget-envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAkBxB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAGD,eAAO,MAAM,wBAAwB,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAIjE,CAAC;AAOH,oBAAY,wBAAwB;IAClC,WAAW,iBAAiB;IAC5B,cAAc,oBAAoB;IAClC,kBAAkB,wBAAwB;CAC3C"}

package/dist/widget/lib/chat-widget-envelope.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatWidgetFallbackReason = exports.ChatWidgetEnvelopeSchema = void 0;
+const zod_1 = require("zod");
+exports.ChatWidgetEnvelopeSchema = zod_1.z.object({
+    kind: zod_1.z.string().min(1),
+    version: zod_1.z.number().int().positive(),
+    payload: zod_1.z.unknown(),
+});
+var ChatWidgetFallbackReason;
+(function (ChatWidgetFallbackReason) {
+    ChatWidgetFallbackReason["UnknownKind"] = "unknown-kind";
+    ChatWidgetFallbackReason["InvalidPayload"] = "invalid-payload";
+    ChatWidgetFallbackReason["UnsupportedVersion"] = "unsupported-version";
+})(ChatWidgetFallbackReason || (exports.ChatWidgetFallbackReason = ChatWidgetFallbackReason = {}));
+//# sourceMappingURL=chat-widget-envelope.js.map

package/dist/widget/lib/chat-widget-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-widget-envelope.js","sourceRoot":"","sources":["../../../src/widget/lib/chat-widget-envelope.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAyBX,QAAA,wBAAwB,GAAkC,OAAC,CAAC,MAAM,CAAC;IAC9E,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACpC,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE;CACrB,CAAC,CAAC;AAOH,IAAY,wBAIX;AAJD,WAAY,wBAAwB;IAClC,wDAA4B,CAAA;IAC5B,8DAAkC,CAAA;IAClC,sEAA0C,CAAA;AAC5C,CAAC,EAJW,wBAAwB,wCAAxB,wBAAwB,QAInC"}

package/dist/widget/lib/chat-widget-kind.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export declare enum ChatWidgetKind {
+    Plan = "plan",
+    Diff = "diff",
+    Approval = "approval",
+    Table = "table",
+    Chart = "chart",
+    FileEdit = "file-edit"
+}
+export declare const ChatWidgetKindSchema: z.ZodEnum<typeof ChatWidgetKind>;
+export declare enum ChatChartKind {
+    Bar = "bar",
+    Line = "line"
+}
+export declare const ChatChartKindSchema: z.ZodEnum<typeof ChatChartKind>;
+//# sourceMappingURL=chat-widget-kind.d.ts.map

package/dist/widget/lib/chat-widget-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-widget-kind.d.ts","sourceRoot":"","sources":["../../../src/widget/lib/chat-widget-kind.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB,oBAAY,cAAc;IAExB,IAAI,SAAS;IAEb,IAAI,SAAS;IAEb,QAAQ,aAAa;IAErB,KAAK,UAAU;IAEf,KAAK,UAAU;IAEf,QAAQ,cAAc;CACvB;AAGD,eAAO,MAAM,oBAAoB,kCAA+B,CAAC;AAMjE,oBAAY,aAAa;IACvB,GAAG,QAAQ;IACX,IAAI,SAAS;CACd;AAED,eAAO,MAAM,mBAAmB,iCAA8B,CAAC"}

package/dist/widget/lib/chat-widget-kind.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatChartKindSchema = exports.ChatChartKind = exports.ChatWidgetKindSchema = exports.ChatWidgetKind = void 0;
+const zod_1 = require("zod");
+var ChatWidgetKind;
+(function (ChatWidgetKind) {
+    ChatWidgetKind["Plan"] = "plan";
+    ChatWidgetKind["Diff"] = "diff";
+    ChatWidgetKind["Approval"] = "approval";
+    ChatWidgetKind["Table"] = "table";
+    ChatWidgetKind["Chart"] = "chart";
+    ChatWidgetKind["FileEdit"] = "file-edit";
+})(ChatWidgetKind || (exports.ChatWidgetKind = ChatWidgetKind = {}));
+exports.ChatWidgetKindSchema = zod_1.z.nativeEnum(ChatWidgetKind);
+var ChatChartKind;
+(function (ChatChartKind) {
+    ChatChartKind["Bar"] = "bar";
+    ChatChartKind["Line"] = "line";
+})(ChatChartKind || (exports.ChatChartKind = ChatChartKind = {}));
+exports.ChatChartKindSchema = zod_1.z.nativeEnum(ChatChartKind);
+//# sourceMappingURL=chat-widget-kind.js.map

package/dist/widget/lib/chat-widget-kind.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-widget-kind.js","sourceRoot":"","sources":["../../../src/widget/lib/chat-widget-kind.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAuBxB,IAAY,cAaX;AAbD,WAAY,cAAc;IAExB,+BAAa,CAAA;IAEb,+BAAa,CAAA;IAEb,uCAAqB,CAAA;IAErB,iCAAe,CAAA;IAEf,iCAAe,CAAA;IAEf,wCAAsB,CAAA;AACxB,CAAC,EAbW,cAAc,8BAAd,cAAc,QAazB;AAGY,QAAA,oBAAoB,GAAG,OAAC,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AAMjE,IAAY,aAGX;AAHD,WAAY,aAAa;IACvB,4BAAW,CAAA;IACX,8BAAa,CAAA;AACf,CAAC,EAHW,aAAa,6BAAb,aAAa,QAGxB;AAEY,QAAA,mBAAmB,GAAG,OAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC"}

package/dist/widget/lib/chat-widget-payloads.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { ChatWidgetKind } from './chat-widget-kind';
+export declare enum WidgetTodoState {
+    Todo = "todo",
+    Active = "active",
+    Done = "done"
+}
+export declare const WidgetTodoStateSchema: z.ZodEnum<typeof WidgetTodoState>;
+export declare const PlanWidgetItemSchema: z.ZodObject<{
+    label: z.ZodString;
+    state: z.ZodEnum<typeof WidgetTodoState>;
+}, z.core.$strip>;
+export declare const PlanWidgetPayloadSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    items: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        state: z.ZodEnum<typeof WidgetTodoState>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PlanWidgetPayload = z.infer<typeof PlanWidgetPayloadSchema>;
+export declare const DiffWidgetPayloadSchema: z.ZodObject<{
+    path: z.ZodString;
+    add: z.ZodNumber;
+    del: z.ZodNumber;
+    hunks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type DiffWidgetPayload = z.infer<typeof DiffWidgetPayloadSchema>;
+export declare const FileEditWidgetPayloadSchema: z.ZodObject<{
+    path: z.ZodString;
+    summary: z.ZodOptional<z.ZodString>;
+    add: z.ZodNumber;
+    del: z.ZodNumber;
+}, z.core.$strip>;
+export type FileEditWidgetPayload = z.infer<typeof FileEditWidgetPayloadSchema>;
+export declare const ApprovalWidgetPayloadSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    accent: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ApprovalWidgetPayload = z.infer<typeof ApprovalWidgetPayloadSchema>;
+export declare const TableWidgetColumnSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>;
+export declare const TableWidgetPayloadSchema: z.ZodObject<{
+    columns: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+}, z.core.$strip>;
+export type TableWidgetPayload = z.infer<typeof TableWidgetPayloadSchema>;
+export declare const ChartWidgetSeriesSchema: z.ZodObject<{
+    label: z.ZodString;
+    points: z.ZodArray<z.ZodObject<{
+        x: z.ZodString;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ChartWidgetPayloadSchema: z.ZodObject<{
+    kind: z.ZodEnum<typeof import("./chat-widget-kind").ChatChartKind>;
+    series: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        points: z.ZodArray<z.ZodObject<{
+            x: z.ZodString;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ChartWidgetPayload = z.infer<typeof ChartWidgetPayloadSchema>;
+export declare const FIRST_PARTY_WIDGET_PAYLOAD_SCHEMAS: Readonly<Record<ChatWidgetKind, z.ZodTypeAny>>;
+export declare const FIRST_PARTY_WIDGET_VERSIONS: Readonly<Record<ChatWidgetKind, number>>;
+//# sourceMappingURL=chat-widget-payloads.d.ts.map

package/dist/widget/lib/chat-widget-payloads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-widget-payloads.d.ts","sourceRoot":"","sources":["../../../src/widget/lib/chat-widget-payloads.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAuB,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAkBzE,oBAAY,eAAe;IACzB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AACD,eAAO,MAAM,qBAAqB,mCAAgC,CAAC;AAGnE,eAAO,MAAM,oBAAoB;;;iBAG/B,CAAC;AAGH,eAAO,MAAM,uBAAuB;;;;;;iBAGlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAMxE,eAAO,MAAM,uBAAuB;;;;;iBAKlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAGxE,eAAO,MAAM,2BAA2B;;;;;iBAKtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAOhF,eAAO,MAAM,2BAA2B;;;iBAGtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAGhF,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAC;AAGH,eAAO,MAAM,wBAAwB;;;;;;iBAGnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAG1E,eAAO,MAAM,uBAAuB;;;;;;iBAGlC,CAAC;AAGH,eAAO,MAAM,wBAAwB;;;;;;;;;iBAGnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAQ1E,eAAO,MAAM,kCAAkC,EAAE,QAAQ,CACvD,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,UAAU,CAAC,CAQrC,CAAC;AAOF,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAChD,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAQ/B,CAAC"}

package/dist/widget/lib/chat-widget-payloads.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIRST_PARTY_WIDGET_VERSIONS = exports.FIRST_PARTY_WIDGET_PAYLOAD_SCHEMAS = exports.ChartWidgetPayloadSchema = exports.ChartWidgetSeriesSchema = exports.TableWidgetPayloadSchema = exports.TableWidgetColumnSchema = exports.ApprovalWidgetPayloadSchema = exports.FileEditWidgetPayloadSchema = exports.DiffWidgetPayloadSchema = exports.PlanWidgetPayloadSchema = exports.PlanWidgetItemSchema = exports.WidgetTodoStateSchema = exports.WidgetTodoState = void 0;
+const zod_1 = require("zod");
+const chat_widget_kind_1 = require("./chat-widget-kind");
+var WidgetTodoState;
+(function (WidgetTodoState) {
+    WidgetTodoState["Todo"] = "todo";
+    WidgetTodoState["Active"] = "active";
+    WidgetTodoState["Done"] = "done";
+})(WidgetTodoState || (exports.WidgetTodoState = WidgetTodoState = {}));
+exports.WidgetTodoStateSchema = zod_1.z.nativeEnum(WidgetTodoState);
+exports.PlanWidgetItemSchema = zod_1.z.object({
+    label: zod_1.z.string().min(1),
+    state: exports.WidgetTodoStateSchema,
+});
+exports.PlanWidgetPayloadSchema = zod_1.z.object({
+    title: zod_1.z.string().optional(),
+    items: zod_1.z.array(exports.PlanWidgetItemSchema),
+});
+exports.DiffWidgetPayloadSchema = zod_1.z.object({
+    path: zod_1.z.string().min(1),
+    add: zod_1.z.number(),
+    del: zod_1.z.number(),
+    hunks: zod_1.z.array(zod_1.z.string()).optional(),
+});
+exports.FileEditWidgetPayloadSchema = zod_1.z.object({
+    path: zod_1.z.string().min(1),
+    summary: zod_1.z.string().optional(),
+    add: zod_1.z.number(),
+    del: zod_1.z.number(),
+});
+exports.ApprovalWidgetPayloadSchema = zod_1.z.object({
+    sessionId: zod_1.z.string().min(1),
+    accent: zod_1.z.string().optional(),
+});
+exports.TableWidgetColumnSchema = zod_1.z.object({
+    key: zod_1.z.string().min(1),
+    label: zod_1.z.string().min(1),
+});
+exports.TableWidgetPayloadSchema = zod_1.z.object({
+    columns: zod_1.z.array(exports.TableWidgetColumnSchema),
+    rows: zod_1.z.array(zod_1.z.record(zod_1.z.string(), zod_1.z.union([zod_1.z.string(), zod_1.z.number()]))),
+});
+exports.ChartWidgetSeriesSchema = zod_1.z.object({
+    label: zod_1.z.string().min(1),
+    points: zod_1.z.array(zod_1.z.object({ x: zod_1.z.string(), y: zod_1.z.number() })),
+});
+exports.ChartWidgetPayloadSchema = zod_1.z.object({
+    kind: chat_widget_kind_1.ChatChartKindSchema,
+    series: zod_1.z.array(exports.ChartWidgetSeriesSchema),
+});
+exports.FIRST_PARTY_WIDGET_PAYLOAD_SCHEMAS = {
+    [chat_widget_kind_1.ChatWidgetKind.Plan]: exports.PlanWidgetPayloadSchema,
+    [chat_widget_kind_1.ChatWidgetKind.Diff]: exports.DiffWidgetPayloadSchema,
+    [chat_widget_kind_1.ChatWidgetKind.Approval]: exports.ApprovalWidgetPayloadSchema,
+    [chat_widget_kind_1.ChatWidgetKind.Table]: exports.TableWidgetPayloadSchema,
+    [chat_widget_kind_1.ChatWidgetKind.Chart]: exports.ChartWidgetPayloadSchema,
+    [chat_widget_kind_1.ChatWidgetKind.FileEdit]: exports.FileEditWidgetPayloadSchema,
+};
+exports.FIRST_PARTY_WIDGET_VERSIONS = {
+    [chat_widget_kind_1.ChatWidgetKind.Plan]: 1,
+    [chat_widget_kind_1.ChatWidgetKind.Diff]: 1,
+    [chat_widget_kind_1.ChatWidgetKind.Approval]: 1,
+    [chat_widget_kind_1.ChatWidgetKind.Table]: 1,
+    [chat_widget_kind_1.ChatWidgetKind.Chart]: 1,
+    [chat_widget_kind_1.ChatWidgetKind.FileEdit]: 1,
+};
+//# sourceMappingURL=chat-widget-payloads.js.map

package/dist/widget/lib/chat-widget-payloads.js.map

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

package/dist/widget/lib/widget-contribution.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+export interface WidgetContributionManifest {
+    readonly kind: string;
+    readonly version: number;
+    readonly displayName: string;
+    readonly summary: string;
+    readonly payloadSchema: Record<string, unknown>;
+}
+export declare const WidgetContributionManifestSchema: z.ZodType<WidgetContributionManifest>;
+export interface WidgetKindCatalogueEntry {
+    readonly kind: string;
+    readonly version: number;
+    readonly displayName: string;
+    readonly summary: string;
+    readonly payloadSchema: Record<string, unknown>;
+    readonly source: WidgetKindSource;
+    readonly biomeId?: string;
+}
+export declare enum WidgetKindSource {
+    FirstParty = "first-party",
+    Biome = "biome"
+}
+export declare const WidgetKindSourceSchema: z.ZodEnum<typeof WidgetKindSource>;
+//# sourceMappingURL=widget-contribution.d.ts.map

package/dist/widget/lib/widget-contribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-contribution.d.ts","sourceRoot":"","sources":["../../../src/widget/lib/widget-contribution.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyBxB,MAAM,WAAW,0BAA0B;IAMzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjD;AAUD,eAAO,MAAM,gCAAgC,EAAE,CAAC,CAAC,OAAO,CAAC,0BAA0B,CActC,CAAC;AAY9C,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAElC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAGD,oBAAY,gBAAgB;IAC1B,UAAU,gBAAgB;IAC1B,KAAK,UAAU;CAChB;AAED,eAAO,MAAM,sBAAsB,oCAAiC,CAAC"}

package/dist/widget/lib/widget-contribution.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WidgetKindSourceSchema = exports.WidgetKindSource = exports.WidgetContributionManifestSchema = void 0;
+const zod_1 = require("zod");
+const WIDGET_KIND_SLUG_REGEX = /^[a-z][a-z0-9-]*$/;
+exports.WidgetContributionManifestSchema = zod_1.z.object({
+    kind: zod_1.z
+        .string()
+        .min(1)
+        .max(100)
+        .regex(WIDGET_KIND_SLUG_REGEX, 'Widget kind slug must be lowercase letters, digits, and hyphens (start with a letter).'),
+    version: zod_1.z.number().int().positive(),
+    displayName: zod_1.z.string().min(1).max(200),
+    summary: zod_1.z.string().min(1).max(1000),
+    payloadSchema: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+});
+var WidgetKindSource;
+(function (WidgetKindSource) {
+    WidgetKindSource["FirstParty"] = "first-party";
+    WidgetKindSource["Biome"] = "biome";
+})(WidgetKindSource || (exports.WidgetKindSource = WidgetKindSource = {}));
+exports.WidgetKindSourceSchema = zod_1.z.nativeEnum(WidgetKindSource);
+//# sourceMappingURL=widget-contribution.js.map

package/dist/widget/lib/widget-contribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-contribution.js","sourceRoot":"","sources":["../../../src/widget/lib/widget-contribution.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AA0CxB,MAAM,sBAAsB,GAAG,mBAAmB,CAAC;AAQtC,QAAA,gCAAgC,GAC3C,OAAC,CAAC,MAAM,CAAC;IACP,IAAI,EAAE,OAAC;SACJ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,GAAG,CAAC;SACR,KAAK,CACJ,sBAAsB,EACtB,wFAAwF,CACzF;IACH,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACpC,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACvC,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;IACpC,aAAa,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC;CACjD,CAA0C,CAAC;AAwB9C,IAAY,gBAGX;AAHD,WAAY,gBAAgB;IAC1B,8CAA0B,CAAA;IAC1B,mCAAe,CAAA;AACjB,CAAC,EAHW,gBAAgB,gCAAhB,gBAAgB,QAG3B;AAEY,QAAA,sBAAsB,GAAG,OAAC,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/kernel-contracts",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "Consolidated Xema OS kernel wire contracts — pure types + zod schemas for the 32 kernel protocol surfaces. One package, one npm scope, wildcard per-surface subpath exports. No framework/runtime deps.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/src/widget/index.ts

@@ -0,0 +1,4 @@
+export * from './lib/chat-widget-kind';
+export * from './lib/chat-widget-payloads';
+export * from './lib/chat-widget-envelope';
+export * from './lib/widget-contribution';

package/src/widget/lib/chat-widget-envelope.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+
+/**
+ * `ChatWidgetEnvelope` — a single widget instance recorded on an assistant
+ * message's `metadata.widgets[]` and rendered by the host-web ChatWidget
+ * registry (HANDOFF §3.2).
+ *
+ * `kind` is a first-party {@link ChatWidgetKind} value OR a namespaced biome
+ * string (`<biomeId>:<kind>`). `version` is the monotonic schema version for
+ * THIS kind — the FE renders the registered renderer when `version <=
+ * supportedVersion`, else a safe fallback card. `payload` is the kind-specific
+ * payload (validated by the producer against the kind's schema; the FE
+ * re-validates before render so a malformed payload renders the fallback rather
+ * than being dropped).
+ *
+ * This is the kernel-canonical mirror of the FE `ChatWidgetEnvelope` interface
+ * — keep the shapes value-identical.
+ */
+export interface ChatWidgetEnvelope {
+  readonly kind: string;
+  readonly version: number;
+  readonly payload: unknown;
+}
+
+/** Zod validator for {@link ChatWidgetEnvelope}. */
+export const ChatWidgetEnvelopeSchema: z.ZodType<ChatWidgetEnvelope> = z.object({
+  kind: z.string().min(1),
+  version: z.number().int().positive(),
+  payload: z.unknown(),
+});
+
+/**
+ * Why a widget fell back to the safe card — populated on the FE resolved
+ * decision so the Studio debugger can see WHY. Mirror of the FE
+ * `ChatWidgetFallbackReason`. Closed set.
+ */
+export enum ChatWidgetFallbackReason {
+  UnknownKind = 'unknown-kind',
+  InvalidPayload = 'invalid-payload',
+  UnsupportedVersion = 'unsupported-version',
+}

package/src/widget/lib/chat-widget-kind.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+
+/**
+ * `ChatWidgetKind` — the closed first-party set of rich in-chat widget kinds an
+ * agent may render through the generic `render_widget` tool (see the Xema OS
+ * ChatWidget feature). Each kind is a GENERIC, domain-agnostic presentation
+ * primitive — chosen to cover the broadest possible range of "structured thing
+ * the agent wants to show the user" without baking in any vertical semantics.
+ *
+ * ── Value-identity invariant ────────────────────────────────────────────────
+ * This enum is the kernel-canonical mirror of the host-web FE model
+ * (`submodules/xema-host-web/src/views/project/sessions/thin/chat-widget-model.ts`,
+ * `ChatWidgetKind`). The two MUST stay value-identical: the FE consumes this
+ * contract via the frontend-bridge sync, and the registry resolves a payload to
+ * a renderer by matching `kind`. Adding a generic kind = add the enum member in
+ * BOTH places (the "2-file rule") plus a payload schema below.
+ *
+ * ── Closed first-party set vs. open biome set ───────────────────────────────
+ * A biome contributes its OWN widget kind as a namespaced string
+ * (`<biomeId>:<kind>`) through a `widget-kind` contribution — it never extends
+ * this enum. This mirrors the closed-enum + open-namespaced-string pattern used
+ * by the FE registry's `registerChatWidget`.
+ */
+export enum ChatWidgetKind {
+  /** A checklist / plan (todo items with status). The agent's "here's the plan". */
+  Plan = 'plan',
+  /** A single-file unified diff (path + hunks). "Here's the change I propose." */
+  Diff = 'diff',
+  /** A suspended capability call awaiting human approval, keyed by approval id. */
+  Approval = 'approval',
+  /** A generic columns + rows table. The universal "show me structured records". */
+  Table = 'table',
+  /** A compact bar/line chart over labelled series. "Visualise these numbers." */
+  Chart = 'chart',
+  /** A header-only file-change summary (path + add/del counts), no hunks. */
+  FileEdit = 'file-edit',
+}
+
+/** Zod mirror of {@link ChatWidgetKind} for wire-boundary validation. */
+export const ChatWidgetKindSchema = z.nativeEnum(ChatWidgetKind);
+
+/**
+ * The chart shapes the first-party `chart` widget can draw. Closed set — kept
+ * value-identical with the FE's `ChatChartKind`.
+ */
+export enum ChatChartKind {
+  Bar = 'bar',
+  Line = 'line',
+}
+
+export const ChatChartKindSchema = z.nativeEnum(ChatChartKind);

package/src/widget/lib/chat-widget-payloads.ts

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+
+import { ChatChartKindSchema, ChatWidgetKind } from './chat-widget-kind';
+
+/**
+ * Per-kind payload contracts for the first-party {@link ChatWidgetKind} set.
+ *
+ * These schemas are the WIRE contract the `render_widget` tool validates against
+ * before a widget envelope is recorded onto an assistant message's
+ * `metadata.widgets[]`. They are kept STRUCTURALLY value-identical with the FE
+ * narrowing validators in
+ * `submodules/xema-host-web/src/views/project/sessions/thin/chat-widget-builtins.tsx`
+ * — the FE re-validates client-side (so a future/unknown payload still routes to
+ * the safe fallback card), but the runtime fails fast on a bad payload so a
+ * malformed widget never reaches the transcript.
+ *
+ * Zero runtime deps beyond zod (kernel-leaf invariant).
+ */
+
+/** Mirror of the FE `TodoState` (session-kit). Closed set. */
+export enum WidgetTodoState {
+  Todo = 'todo',
+  Active = 'active',
+  Done = 'done',
+}
+export const WidgetTodoStateSchema = z.nativeEnum(WidgetTodoState);
+
+/** A single plan/checklist item. Mirrors session-kit `TodoItem`. */
+export const PlanWidgetItemSchema = z.object({
+  label: z.string().min(1),
+  state: WidgetTodoStateSchema,
+});
+
+/** `plan` payload — a titled checklist of todo items. */
+export const PlanWidgetPayloadSchema = z.object({
+  title: z.string().optional(),
+  items: z.array(PlanWidgetItemSchema),
+});
+export type PlanWidgetPayload = z.infer<typeof PlanWidgetPayloadSchema>;
+
+/**
+ * `diff` payload — a single-file unified diff. `hunks` are raw diff lines whose
+ * first character is the marker (`+`/`-`/space). Mirrors session-kit `DiffFile`.
+ */
+export const DiffWidgetPayloadSchema = z.object({
+  path: z.string().min(1),
+  add: z.number(),
+  del: z.number(),
+  hunks: z.array(z.string()).optional(),
+});
+export type DiffWidgetPayload = z.infer<typeof DiffWidgetPayloadSchema>;
+
+/** `file-edit` payload — a header-only file change summary (no hunks). */
+export const FileEditWidgetPayloadSchema = z.object({
+  path: z.string().min(1),
+  summary: z.string().optional(),
+  add: z.number(),
+  del: z.number(),
+});
+export type FileEditWidgetPayload = z.infer<typeof FileEditWidgetPayloadSchema>;
+
+/**
+ * `approval` payload — the suspended capability call awaiting approval, keyed by
+ * the session it belongs to. The FE mounts the same Pillar-3 inline approval
+ * card from this id.
+ */
+export const ApprovalWidgetPayloadSchema = z.object({
+  sessionId: z.string().min(1),
+  accent: z.string().optional(),
+});
+export type ApprovalWidgetPayload = z.infer<typeof ApprovalWidgetPayloadSchema>;
+
+/** A `table` column descriptor. */
+export const TableWidgetColumnSchema = z.object({
+  key: z.string().min(1),
+  label: z.string().min(1),
+});
+
+/** `table` payload — generic columns + rows. Cells are strings or numbers. */
+export const TableWidgetPayloadSchema = z.object({
+  columns: z.array(TableWidgetColumnSchema),
+  rows: z.array(z.record(z.string(), z.union([z.string(), z.number()]))),
+});
+export type TableWidgetPayload = z.infer<typeof TableWidgetPayloadSchema>;
+
+/** A single chart series (one bar/line group). */
+export const ChartWidgetSeriesSchema = z.object({
+  label: z.string().min(1),
+  points: z.array(z.object({ x: z.string(), y: z.number() })),
+});
+
+/** `chart` payload — a compact bar/line chart over labelled series. */
+export const ChartWidgetPayloadSchema = z.object({
+  kind: ChatChartKindSchema,
+  series: z.array(ChartWidgetSeriesSchema),
+});
+export type ChartWidgetPayload = z.infer<typeof ChartWidgetPayloadSchema>;
+
+/**
+ * The closed registry of first-party kind → payload schema. The single source
+ * of truth the `render_widget` tool & runtime use to validate a first-party
+ * widget payload by `kind`. Adding a generic kind = one enum member + one schema
+ * here + the FE mirror (the "2-file rule").
+ */
+export const FIRST_PARTY_WIDGET_PAYLOAD_SCHEMAS: Readonly<
+  Record<ChatWidgetKind, z.ZodTypeAny>
+> = {
+  [ChatWidgetKind.Plan]: PlanWidgetPayloadSchema,
+  [ChatWidgetKind.Diff]: DiffWidgetPayloadSchema,
+  [ChatWidgetKind.Approval]: ApprovalWidgetPayloadSchema,
+  [ChatWidgetKind.Table]: TableWidgetPayloadSchema,
+  [ChatWidgetKind.Chart]: ChartWidgetPayloadSchema,
+  [ChatWidgetKind.FileEdit]: FileEditWidgetPayloadSchema,
+};
+
+/**
+ * The current schema version for each first-party kind. Bumped when a kind's
+ * payload schema changes shape; the FE renders the registered renderer only
+ * when `envelope.version <= supportedVersion`, else the safe fallback.
+ */
+export const FIRST_PARTY_WIDGET_VERSIONS: Readonly<
+  Record<ChatWidgetKind, number>
+> = {
+  [ChatWidgetKind.Plan]: 1,
+  [ChatWidgetKind.Diff]: 1,
+  [ChatWidgetKind.Approval]: 1,
+  [ChatWidgetKind.Table]: 1,
+  [ChatWidgetKind.Chart]: 1,
+  [ChatWidgetKind.FileEdit]: 1,
+};

package/src/widget/lib/widget-contribution.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+
+/**
+ * Manifest shape carried by every `ContributionKind.WidgetKind` envelope.
+ *
+ * One contribution = one widget kind. The shape mirrors
+ * `CapabilityContributionManifest` (see `../capability/lib/capability-contribution.ts`)
+ * so the generic `BootstrapContributionsService<TKind, TManifest>` template and
+ * the codemod can ingest it the same way every other contribution kind is
+ * ingested. Provenance (`biomeId`, `biomeVersion`) is stamped by the bootstrap
+ * pipeline from the discovering biome's manifest — authors do NOT declare it
+ * inline.
+ *
+ * A biome contributes a widget kind so its frontend biome can register a
+ * renderer for it via `registerChatWidget('<biomeId>:<kind>', …)`. The
+ * `kind` here is the BARE, biome-local kind slug; the catalogue namespaces it
+ * to `<biomeId>:<kind>` at ingest so it can never shadow a first-party kind.
+ *
+ * Validation is fail-fast: a contribution that violates any constraint is
+ * rejected at boot. `payloadSchema` is an opaque JSON Schema passed through
+ * verbatim (the catalogue surfaces it to the FE and to authoring tools; it is
+ * NOT a kernel-validated shape — validating it as JSON Schema here would be
+ * either partial or pull in a JSON-Schema validator, violating the kernel-leaf
+ * invariant).
+ */
+export interface WidgetContributionManifest {
+  /**
+   * Biome-local kind slug (lowercase, hyphenated). Namespaced to
+   * `<biomeId>:<kind>` by the catalogue — a biome can never claim a bare
+   * first-party kind.
+   */
+  readonly kind: string;
+  /** Monotonic schema version for this kind's payload. */
+  readonly version: number;
+  /** Human-readable display name surfaced in the catalogue (≤ 200 chars). */
+  readonly displayName: string;
+  /** One-line summary of WHAT the widget shows + WHEN to use it (≤ 1000 chars). */
+  readonly summary: string;
+  /** JSON Schema for the widget payload — passed through verbatim. */
+  readonly payloadSchema: Record<string, unknown>;
+}
+
+const WIDGET_KIND_SLUG_REGEX = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Zod validator for {@link WidgetContributionManifest}. The bootstrap template
+ * and the catalogue's `POST /widget-kinds/register` route BOTH route every
+ * candidate manifest through this before persisting, so a malformed
+ * contribution fails at the boundary instead of at render time.
+ */
+export const WidgetContributionManifestSchema: z.ZodType<WidgetContributionManifest> =
+  z.object({
+    kind: z
+      .string()
+      .min(1)
+      .max(100)
+      .regex(
+        WIDGET_KIND_SLUG_REGEX,
+        'Widget kind slug must be lowercase letters, digits, and hyphens (start with a letter).',
+      ),
+    version: z.number().int().positive(),
+    displayName: z.string().min(1).max(200),
+    summary: z.string().min(1).max(1000),
+    payloadSchema: z.record(z.string(), z.unknown()),
+  }) as z.ZodType<WidgetContributionManifest>;
+
+/**
+ * A resolved widget-kind catalogue entry — what `GET /widget-kinds` returns. It
+ * unifies the closed first-party set and the open biome-contributed set behind
+ * ONE shape the FE consumes to know which kinds exist (and to register
+ * biome-contributed kinds into the open FE registry).
+ *
+ * `source` discriminates provenance; `kind` is the FULLY-NAMESPACED slug the FE
+ * registry keys by (a first-party kind is its bare enum value; a biome kind is
+ * `<biomeId>:<kind>`).
+ */
+export interface WidgetKindCatalogueEntry {
+  readonly kind: string;
+  readonly version: number;
+  readonly displayName: string;
+  readonly summary: string;
+  readonly payloadSchema: Record<string, unknown>;
+  readonly source: WidgetKindSource;
+  /** Present only for biome-contributed kinds. */
+  readonly biomeId?: string;
+}
+
+/** Provenance of a catalogue entry. Closed set. */
+export enum WidgetKindSource {
+  FirstParty = 'first-party',
+  Biome = 'biome',
+}
+
+export const WidgetKindSourceSchema = z.nativeEnum(WidgetKindSource);