glirastes 0.4.0 → 0.5.0

package/dist/browser/ui-action-bus.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Framework-neutral UI action dispatch. React (`glirastes/react`), the chat
+ * embed and plain browser code (`glirastes/browser`) share this bus, so a
+ * generated navigation, filter or client action reaches the handler the app
+ * registered, whatever framework it uses.
+ */
+export interface UiAction {
+    type: string;
+    actionId?: string;
+    [key: string]: unknown;
+}
+export type UiActionHandler = (action: UiAction) => void | Promise<void>;
+export declare class UiActionBus {
+    private handlersByType;
+    private handlersById;
+    subscribeByType(type: string, handler: UiActionHandler): () => void;
+    subscribeById(actionId: string, handler: UiActionHandler): () => void;
+    /**
+     * Client actions that have a handler right now. The chat sends them with
+     * each request, so a generated client-action tool can refuse an action the
+     * open page does not take instead of reporting it as done.
+     */
+    registeredActionIds(): string[];
+    dispatch(action: UiAction): Promise<void>;
+}
+export declare function getDefaultUiActionBus(): UiActionBus;

package/dist/browser/ui-action-bus.js

@@ -0,0 +1,66 @@
+function addHandler(map, key, handler) {
+    const handlers = map.get(key) ?? new Set();
+    handlers.add(handler);
+    map.set(key, handlers);
+    return () => {
+        const current = map.get(key);
+        if (!current)
+            return;
+        current.delete(handler);
+        if (current.size === 0)
+            map.delete(key);
+    };
+}
+export class UiActionBus {
+    handlersByType = new Map();
+    handlersById = new Map();
+    subscribeByType(type, handler) {
+        return addHandler(this.handlersByType, type, handler);
+    }
+    subscribeById(actionId, handler) {
+        return addHandler(this.handlersById, actionId, handler);
+    }
+    /**
+     * Client actions that have a handler right now. The chat sends them with
+     * each request, so a generated client-action tool can refuse an action the
+     * open page does not take instead of reporting it as done.
+     */
+    registeredActionIds() {
+        return Array.from(this.handlersById.keys());
+    }
+    async dispatch(action) {
+        const typeHandlers = this.handlersByType.get(action.type);
+        const idHandlers = action.actionId
+            ? this.handlersById.get(action.actionId)
+            : undefined;
+        const allHandlers = new Set([
+            ...(typeHandlers ? Array.from(typeHandlers) : []),
+            ...(idHandlers ? Array.from(idHandlers) : []),
+        ]);
+        for (const handler of allHandlers) {
+            await handler(action);
+        }
+    }
+}
+const DEFAULT_BUS = Symbol.for('glirastes.uiActionBus');
+/**
+ * The page-wide bus that the chat dispatches generated UI actions to. Kept on
+ * `globalThis` so two bundled copies of the SDK still share one bus.
+ */
+function isUiActionBus(value) {
+    const candidate = value;
+    return typeof candidate?.dispatch === 'function'
+        && typeof candidate.subscribeById === 'function'
+        && typeof candidate.subscribeByType === 'function';
+}
+export function getDefaultUiActionBus() {
+    const scope = globalThis;
+    const existing = scope[DEFAULT_BUS];
+    // A bus of another bundled SDK copy is a different class: check the shape, not instanceof.
+    if (isUiActionBus(existing))
+        return existing;
+    const bus = new UiActionBus();
+    scope[DEFAULT_BUS] = bus;
+    return bus;
+}
+//# sourceMappingURL=ui-action-bus.js.map

package/dist/browser/ui-action-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-action-bus.js","sourceRoot":"","sources":["../../src/browser/ui-action-bus.ts"],"names":[],"mappings":"AAcA,SAAS,UAAU,CACjB,GAAsC,EACtC,GAAW,EACX,OAAwB;IAExB,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,EAAmB,CAAC;IAC5D,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACtB,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAEvB,OAAO,GAAG,EAAE;QACV,MAAM,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACxB,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1C,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,WAAW;IACd,cAAc,GAAG,IAAI,GAAG,EAAgC,CAAC;IACzD,YAAY,GAAG,IAAI,GAAG,EAAgC,CAAC;IAE/D,eAAe,CAAC,IAAY,EAAE,OAAwB;QACpD,OAAO,UAAU,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC;IAED,aAAa,CAAC,QAAgB,EAAE,OAAwB;QACtD,OAAO,UAAU,CAAC,IAAI,CAAC,YAAY,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC1D,CAAC;IAED;;;;OAIG;IACH,mBAAmB;QACjB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,MAAgB;QAC7B,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1D,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ;YAChC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC;YACxC,CAAC,CAAC,SAAS,CAAC;QAEd,MAAM,WAAW,GAAG,IAAI,GAAG,CAAkB;YAC3C,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9C,CAAC,CAAC;QAEH,KAAK,MAAM,OAAO,IAAI,WAAW,EAAE,CAAC;YAClC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;CACF;AAED,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAExD;;;GAGG;AACH,SAAS,aAAa,CAAC,KAAc;IACnC,MAAM,SAAS,GAAG,KAAgD,CAAC;IACnE,OAAO,OAAO,SAAS,EAAE,QAAQ,KAAK,UAAU;WAC3C,OAAO,SAAS,CAAC,aAAa,KAAK,UAAU;WAC7C,OAAO,SAAS,CAAC,eAAe,KAAK,UAAU,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,qBAAqB;IACnC,MAAM,KAAK,GAAG,UAAqC,CAAC;IACpD,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;IACpC,2FAA2F;IAC3F,IAAI,aAAa,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC7C,MAAM,GAAG,GAAG,IAAI,WAAW,EAAE,CAAC;IAC9B,KAAK,CAAC,WAAW,CAAC,GAAG,GAAG,CAAC;IACzB,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/cjs/browser/client-actions.d.ts

@@ -0,0 +1,26 @@
+import { type UiActionBus } from './ui-action-bus.js';
+/** Any schema with `safeParse`, e.g. a Zod object; it types and validates the payload. */
+export interface PayloadContract<T> {
+    safeParse(value: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error?: unknown;
+    };
+}
+export interface ClientActionOptions {
+    bus?: UiActionBus;
+}
+/**
+ * Registers a client action the chat may run (`ui.<actionId>`). The literal
+ * id and the contract are read by `glirastes tools refresh`; at runtime the
+ * contract validates the payload before the handler runs.
+ */
+export declare function registerAiClientAction<T = Record<string, unknown>>(actionId: string, handler: (payload: T) => void | Promise<void>, contract?: PayloadContract<T>, options?: ClientActionOptions): () => void;
+/**
+ * Hands the UI actions of a successful tool result to the bus. Only actions
+ * of generated Glirastes tools (`glirastes.*`) are dispatched; app-specific
+ * uiActions stay with the app's own result handler. Returns the count.
+ */
+export declare function dispatchToolResultUiActions(result: unknown, bus?: UiActionBus): Promise<number>;

package/dist/cjs/browser/client-actions.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAiClientAction = registerAiClientAction;
+exports.dispatchToolResultUiActions = dispatchToolResultUiActions;
+const ui_action_bus_js_1 = require("./ui-action-bus.js");
+/**
+ * Registers a client action the chat may run (`ui.<actionId>`). The literal
+ * id and the contract are read by `glirastes tools refresh`; at runtime the
+ * contract validates the payload before the handler runs.
+ */
+function registerAiClientAction(actionId, handler, contract, options = {}) {
+    const bus = options.bus ?? (0, ui_action_bus_js_1.getDefaultUiActionBus)();
+    return bus.subscribeById(actionId, async (action) => {
+        const payload = action.payload ?? {};
+        if (!contract) {
+            await handler(payload);
+            return;
+        }
+        const parsed = contract.safeParse(payload);
+        if (!parsed.success)
+            throw new Error(`Invalid payload for UI action ${actionId}`);
+        await handler(parsed.data);
+    });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Hands the UI actions of a successful tool result to the bus. Only actions
+ * of generated Glirastes tools (`glirastes.*`) are dispatched; app-specific
+ * uiActions stay with the app's own result handler. Returns the count.
+ */
+async function dispatchToolResultUiActions(result, bus = (0, ui_action_bus_js_1.getDefaultUiActionBus)()) {
+    if (!isRecord(result) || result.success !== true)
+        return 0;
+    const actions = Array.isArray(result.uiAction) ? result.uiAction : [result.uiAction];
+    let dispatched = 0;
+    for (const action of actions) {
+        if (!isRecord(action) || typeof action.type !== 'string' || !action.type.startsWith('glirastes.'))
+            continue;
+        await bus.dispatch(action);
+        dispatched += 1;
+    }
+    return dispatched;
+}

package/dist/cjs/browser/index.d.ts

@@ -0,0 +1,4 @@
+export { getDefaultUiActionBus, UiActionBus, type UiAction, type UiActionHandler, } from './ui-action-bus.js';
+export { buildNavigationHref, GLIRASTES_NAVIGATE_ACTION_ID, isSafeAppHref, registerNavigationBridge, type NavigationBridgeOptions, type QueryValue, } from './navigation.js';
+export { dispatchToolResultUiActions, registerAiClientAction, type ClientActionOptions, type PayloadContract, } from './client-actions.js';
+export { defineQueryFilters, type QueryFilterScalar, type QueryFilterSpec, type QueryFiltersDefinition, type QueryFilterValues, } from './query-filters.js';

package/dist/cjs/browser/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineQueryFilters = exports.registerAiClientAction = exports.dispatchToolResultUiActions = exports.registerNavigationBridge = exports.isSafeAppHref = exports.GLIRASTES_NAVIGATE_ACTION_ID = exports.buildNavigationHref = exports.UiActionBus = exports.getDefaultUiActionBus = void 0;
+var ui_action_bus_js_1 = require("./ui-action-bus.js");
+Object.defineProperty(exports, "getDefaultUiActionBus", { enumerable: true, get: function () { return ui_action_bus_js_1.getDefaultUiActionBus; } });
+Object.defineProperty(exports, "UiActionBus", { enumerable: true, get: function () { return ui_action_bus_js_1.UiActionBus; } });
+var navigation_js_1 = require("./navigation.js");
+Object.defineProperty(exports, "buildNavigationHref", { enumerable: true, get: function () { return navigation_js_1.buildNavigationHref; } });
+Object.defineProperty(exports, "GLIRASTES_NAVIGATE_ACTION_ID", { enumerable: true, get: function () { return navigation_js_1.GLIRASTES_NAVIGATE_ACTION_ID; } });
+Object.defineProperty(exports, "isSafeAppHref", { enumerable: true, get: function () { return navigation_js_1.isSafeAppHref; } });
+Object.defineProperty(exports, "registerNavigationBridge", { enumerable: true, get: function () { return navigation_js_1.registerNavigationBridge; } });
+var client_actions_js_1 = require("./client-actions.js");
+Object.defineProperty(exports, "dispatchToolResultUiActions", { enumerable: true, get: function () { return client_actions_js_1.dispatchToolResultUiActions; } });
+Object.defineProperty(exports, "registerAiClientAction", { enumerable: true, get: function () { return client_actions_js_1.registerAiClientAction; } });
+var query_filters_js_1 = require("./query-filters.js");
+Object.defineProperty(exports, "defineQueryFilters", { enumerable: true, get: function () { return query_filters_js_1.defineQueryFilters; } });

package/dist/cjs/browser/navigation.d.ts

@@ -0,0 +1,32 @@
+import { type UiActionBus } from './ui-action-bus.js';
+/** Action id of every generated navigation and filter tool (`ui.navigate`, `ui.filter.<view>`). */
+export declare const GLIRASTES_NAVIGATE_ACTION_ID = "glirastes.navigate";
+export type QueryValue = string | number | boolean | null | undefined | ReadonlyArray<string | number | boolean>;
+/**
+ * An app-internal path: one leading slash, no scheme, no protocol-relative
+ * `//host`, no backslash, no control characters and no dot segment in the
+ * path (`/a/..//host` resolves to the protocol-relative `//host`).
+ */
+export declare function isSafeAppHref(href: unknown): href is string;
+/**
+ * Builds the href a navigation or filter tool pushes. `destination` uses the
+ * route spelling of the tool (`/tasks/:id`); query values keep key order,
+ * arrays are joined with commas (nuqs `parseAsArrayOf`) or repeated
+ * (`searchParams.getAll`).
+ */
+export declare function buildNavigationHref(input: {
+    destination: string;
+    params?: Readonly<Record<string, string>>;
+    query?: Readonly<Record<string, QueryValue>>;
+    arrayFormats?: Readonly<Record<string, 'comma' | 'repeat'>>;
+}): string;
+export interface NavigationBridgeOptions {
+    /** The router's push, e.g. Next.js `router.push` or vue-router `router.push`. */
+    push: (href: string) => unknown;
+    bus?: UiActionBus;
+}
+/**
+ * Executes `ui.navigate` and `ui.filter.<view>` results with the app's own
+ * router. Returns the unsubscribe function.
+ */
+export declare function registerNavigationBridge(options: NavigationBridgeOptions): () => void;

package/dist/cjs/browser/navigation.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GLIRASTES_NAVIGATE_ACTION_ID = void 0;
+exports.isSafeAppHref = isSafeAppHref;
+exports.buildNavigationHref = buildNavigationHref;
+exports.registerNavigationBridge = registerNavigationBridge;
+const ui_action_bus_js_1 = require("./ui-action-bus.js");
+/** Action id of every generated navigation and filter tool (`ui.navigate`, `ui.filter.<view>`). */
+exports.GLIRASTES_NAVIGATE_ACTION_ID = 'glirastes.navigate';
+/** `.` and `..` path segments, also percent-encoded; URL parsing resolves them. */
+const DOT_SEGMENT = /^(?:\.|%2e){1,2}$/i;
+/**
+ * An app-internal path: one leading slash, no scheme, no protocol-relative
+ * `//host`, no backslash, no control characters and no dot segment in the
+ * path (`/a/..//host` resolves to the protocol-relative `//host`).
+ */
+function isSafeAppHref(href) {
+    return typeof href === 'string'
+        && href.length > 0
+        && href.length <= 2_048
+        && href.startsWith('/')
+        && !href.startsWith('//')
+        && !href.includes('\\')
+        && !/[\u0000-\u001f\u007f]/.test(href)
+        && !href.split(/[?#]/, 1)[0].split('/').some((segment) => DOT_SEGMENT.test(segment));
+}
+/**
+ * Builds the href a navigation or filter tool pushes. `destination` uses the
+ * route spelling of the tool (`/tasks/:id`); query values keep key order,
+ * arrays are joined with commas (nuqs `parseAsArrayOf`) or repeated
+ * (`searchParams.getAll`).
+ */
+function buildNavigationHref(input) {
+    const path = input.destination.split('/').map((segment) => {
+        if (!segment.startsWith(':'))
+            return segment;
+        const name = segment.slice(1);
+        const value = input.params?.[name];
+        if (typeof value !== 'string' || value.length === 0) {
+            throw new Error(`Missing route parameter ${name}`);
+        }
+        // `.` and `..` would move the path instead of naming one segment.
+        if (value === '.' || value === '..')
+            throw new Error(`Invalid route parameter ${name}`);
+        return encodeURIComponent(value);
+    }).join('/');
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(input.query ?? {})) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        if (Array.isArray(value)) {
+            if (value.length === 0)
+                continue;
+            if (input.arrayFormats?.[key] === 'repeat') {
+                for (const item of value)
+                    search.append(key, String(item));
+            }
+            else {
+                search.append(key, value.map(String).join(','));
+            }
+            continue;
+        }
+        search.append(key, String(value));
+    }
+    const query = search.toString();
+    return query ? `${path}?${query}` : path;
+}
+function hrefOf(action) {
+    const payload = action.payload;
+    return payload && typeof payload === 'object' ? payload.href : undefined;
+}
+/**
+ * Executes `ui.navigate` and `ui.filter.<view>` results with the app's own
+ * router. Returns the unsubscribe function.
+ */
+function registerNavigationBridge(options) {
+    const bus = options.bus ?? (0, ui_action_bus_js_1.getDefaultUiActionBus)();
+    return bus.subscribeById(exports.GLIRASTES_NAVIGATE_ACTION_ID, async (action) => {
+        const href = hrefOf(action);
+        if (!isSafeAppHref(href))
+            throw new Error('Unsafe navigation target');
+        await options.push(href);
+    });
+}

package/dist/cjs/browser/query-filters.d.ts

@@ -0,0 +1,30 @@
+export type QueryFilterScalar = 'string' | 'integer' | 'number' | 'boolean' | readonly [string, ...string[]];
+export type QueryFilterSpec = QueryFilterScalar | {
+    readonly arrayOf: QueryFilterScalar;
+    readonly format?: 'comma' | 'repeat';
+};
+type ScalarValue<S> = S extends 'integer' | 'number' ? number : S extends 'boolean' ? boolean : S extends readonly (infer L)[] ? L : string;
+type FilterValue<S> = S extends {
+    readonly arrayOf: infer V;
+} ? Array<ScalarValue<V>> : ScalarValue<S>;
+export type QueryFilterValues<F extends Record<string, QueryFilterSpec>> = {
+    [K in keyof F]?: FilterValue<F[K]>;
+};
+export interface QueryFiltersDefinition<F extends Record<string, QueryFilterSpec>> {
+    readonly path: string;
+    readonly filters: F;
+    /** Typed filter values from a query string; values outside the domain are dropped. */
+    read(search: string | URLSearchParams): QueryFilterValues<F>;
+    /** The href `ui.filter.<view>` pushes for these values. */
+    href(values: QueryFilterValues<F>, params?: Readonly<Record<string, string>>): string;
+}
+/**
+ * Declares the URL filters of a view for apps without a framework source
+ * (SPAs, Vue). `glirastes tools refresh` reads the literal definition and
+ * generates `ui.filter.<view>`; the app uses `read` to apply the URL.
+ */
+export declare function defineQueryFilters<const F extends Record<string, QueryFilterSpec>>(definition: {
+    path: string;
+    filters: F;
+}): QueryFiltersDefinition<F>;
+export {};

package/dist/cjs/browser/query-filters.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineQueryFilters = defineQueryFilters;
+const navigation_js_1 = require("./navigation.js");
+const NAME = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
+const KINDS = new Set(['string', 'integer', 'number', 'boolean']);
+function scalarOf(spec) {
+    return typeof spec === 'object' && !Array.isArray(spec) && 'arrayOf' in spec ? spec.arrayOf : spec;
+}
+function assertScalar(key, scalar) {
+    if (Array.isArray(scalar)) {
+        if (scalar.length === 0 || scalar.some((value) => typeof value !== 'string' || value.length === 0)) {
+            throw new Error(`Filter ${key} needs at least one non-empty value`);
+        }
+        return;
+    }
+    if (typeof scalar !== 'string' || !KINDS.has(scalar)) {
+        throw new Error(`Filter ${key} must be string, integer, number, boolean or a list of values`);
+    }
+}
+function parseScalar(scalar, raw) {
+    if (Array.isArray(scalar))
+        return scalar.includes(raw) ? raw : undefined;
+    switch (scalar) {
+        case 'integer':
+            return /^-?\d+$/.test(raw) ? Number.parseInt(raw, 10) : undefined;
+        case 'number': {
+            const value = Number(raw);
+            return raw.trim() !== '' && Number.isFinite(value) ? value : undefined;
+        }
+        case 'boolean':
+            return raw === 'true' ? true : raw === 'false' ? false : undefined;
+        default:
+            return raw;
+    }
+}
+/**
+ * Declares the URL filters of a view for apps without a framework source
+ * (SPAs, Vue). `glirastes tools refresh` reads the literal definition and
+ * generates `ui.filter.<view>`; the app uses `read` to apply the URL.
+ */
+function defineQueryFilters(definition) {
+    if (typeof definition.path !== 'string' || !definition.path.startsWith('/') || definition.path.startsWith('//')) {
+        throw new Error('defineQueryFilters needs an app path starting with /');
+    }
+    for (const [key, spec] of Object.entries(definition.filters)) {
+        if (!NAME.test(key))
+            throw new Error(`Filter key ${JSON.stringify(key)} is not a plain name`);
+        assertScalar(key, scalarOf(spec));
+    }
+    const arrayFormats = {};
+    for (const [key, spec] of Object.entries(definition.filters)) {
+        if (typeof spec === 'object' && !Array.isArray(spec) && 'arrayOf' in spec)
+            arrayFormats[key] = spec.format ?? 'comma';
+    }
+    return {
+        path: definition.path,
+        filters: definition.filters,
+        read(search) {
+            const params = typeof search === 'string' ? new URLSearchParams(search) : search;
+            const values = {};
+            for (const [key, spec] of Object.entries(definition.filters)) {
+                const scalar = scalarOf(spec);
+                if (arrayFormats[key]) {
+                    const raw = arrayFormats[key] === 'repeat' ? params.getAll(key) : (params.get(key)?.split(',') ?? []);
+                    const parsed = raw.map((value) => parseScalar(scalar, value)).filter((value) => value !== undefined);
+                    if (parsed.length > 0)
+                        values[key] = parsed;
+                    continue;
+                }
+                const raw = params.get(key);
+                const parsed = raw === null ? undefined : parseScalar(scalar, raw);
+                if (parsed !== undefined)
+                    values[key] = parsed;
+            }
+            return values;
+        },
+        href(values, params) {
+            return (0, navigation_js_1.buildNavigationHref)({
+                destination: definition.path,
+                ...(params ? { params } : {}),
+                query: values,
+                arrayFormats,
+            });
+        },
+    };
+}

package/dist/cjs/browser/ui-action-bus.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Framework-neutral UI action dispatch. React (`glirastes/react`), the chat
+ * embed and plain browser code (`glirastes/browser`) share this bus, so a
+ * generated navigation, filter or client action reaches the handler the app
+ * registered, whatever framework it uses.
+ */
+export interface UiAction {
+    type: string;
+    actionId?: string;
+    [key: string]: unknown;
+}
+export type UiActionHandler = (action: UiAction) => void | Promise<void>;
+export declare class UiActionBus {
+    private handlersByType;
+    private handlersById;
+    subscribeByType(type: string, handler: UiActionHandler): () => void;
+    subscribeById(actionId: string, handler: UiActionHandler): () => void;
+    /**
+     * Client actions that have a handler right now. The chat sends them with
+     * each request, so a generated client-action tool can refuse an action the
+     * open page does not take instead of reporting it as done.
+     */
+    registeredActionIds(): string[];
+    dispatch(action: UiAction): Promise<void>;
+}
+export declare function getDefaultUiActionBus(): UiActionBus;

package/dist/cjs/browser/ui-action-bus.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UiActionBus = void 0;
+exports.getDefaultUiActionBus = getDefaultUiActionBus;
+function addHandler(map, key, handler) {
+    const handlers = map.get(key) ?? new Set();
+    handlers.add(handler);
+    map.set(key, handlers);
+    return () => {
+        const current = map.get(key);
+        if (!current)
+            return;
+        current.delete(handler);
+        if (current.size === 0)
+            map.delete(key);
+    };
+}
+class UiActionBus {
+    handlersByType = new Map();
+    handlersById = new Map();
+    subscribeByType(type, handler) {
+        return addHandler(this.handlersByType, type, handler);
+    }
+    subscribeById(actionId, handler) {
+        return addHandler(this.handlersById, actionId, handler);
+    }
+    /**
+     * Client actions that have a handler right now. The chat sends them with
+     * each request, so a generated client-action tool can refuse an action the
+     * open page does not take instead of reporting it as done.
+     */
+    registeredActionIds() {
+        return Array.from(this.handlersById.keys());
+    }
+    async dispatch(action) {
+        const typeHandlers = this.handlersByType.get(action.type);
+        const idHandlers = action.actionId
+            ? this.handlersById.get(action.actionId)
+            : undefined;
+        const allHandlers = new Set([
+            ...(typeHandlers ? Array.from(typeHandlers) : []),
+            ...(idHandlers ? Array.from(idHandlers) : []),
+        ]);
+        for (const handler of allHandlers) {
+            await handler(action);
+        }
+    }
+}
+exports.UiActionBus = UiActionBus;
+const DEFAULT_BUS = Symbol.for('glirastes.uiActionBus');
+/**
+ * The page-wide bus that the chat dispatches generated UI actions to. Kept on
+ * `globalThis` so two bundled copies of the SDK still share one bus.
+ */
+function isUiActionBus(value) {
+    const candidate = value;
+    return typeof candidate?.dispatch === 'function'
+        && typeof candidate.subscribeById === 'function'
+        && typeof candidate.subscribeByType === 'function';
+}
+function getDefaultUiActionBus() {
+    const scope = globalThis;
+    const existing = scope[DEFAULT_BUS];
+    // A bus of another bundled SDK copy is a different class: check the shape, not instanceof.
+    if (isUiActionBus(existing))
+        return existing;
+    const bus = new UiActionBus();
+    scope[DEFAULT_BUS] = bus;
+    return bus;
+}

package/dist/cjs/codegen/execution-inventory.d.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+export declare const FoundationExecutionInventorySchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    targetAppKey: z.ZodString;
+    executions: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        toolId: z.ZodUUID;
+        definitionId: z.ZodString;
+        stableKey: z.ZodString;
+        sourceFingerprint: z.ZodString;
+        inputSchemaDigest: z.ZodString;
+        outputSchemaDigest: z.ZodString;
+        executionKind: z.ZodLiteral<"endpoint">;
+        sourceKind: z.ZodOptional<z.ZodEnum<{
+            openapi: "openapi";
+            "next-app": "next-app";
+            nest: "nest";
+        }>>;
+        sourceFile: z.ZodString;
+        method: z.ZodEnum<{
+            GET: "GET";
+            HEAD: "HEAD";
+            POST: "POST";
+            PATCH: "PATCH";
+            PUT: "PUT";
+            DELETE: "DELETE";
+        }>;
+        path: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        toolId: z.ZodUUID;
+        definitionId: z.ZodString;
+        stableKey: z.ZodString;
+        sourceFingerprint: z.ZodString;
+        inputSchemaDigest: z.ZodString;
+        outputSchemaDigest: z.ZodString;
+        executionKind: z.ZodLiteral<"ui">;
+        actionBindingRef: z.ZodString;
+        actionId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "executionKind">>;
+}, z.core.$strict>;
+export type FoundationExecutionInventory = z.infer<typeof FoundationExecutionInventorySchema>;
+export type DiscoveredFoundationExecution = FoundationExecutionInventory['executions'][number] & {
+    sourceLocator: {
+        sourceFile: string;
+        exportName: string;
+    } | {
+        actionBindingRef: string;
+        sourceFile?: string;
+    };
+};
+export interface FoundationExecutionDiscovery {
+    schemaVersion: 2;
+    targetAppKey: string;
+    inventoryDigest: string;
+    executions: DiscoveredFoundationExecution[];
+    findings: Array<{
+        code: string;
+        subjectRef: string;
+    }>;
+}
+export declare function discoverFoundationExecutions(options: {
+    rootDir: string;
+    inventory: unknown;
+}): Promise<FoundationExecutionDiscovery>;