@dudousxd/nestjs-agent-core 0.25.0 → 0.27.0

package/README.md

@@ -19,7 +19,9 @@ import type { ModelProvider, AgentStore, ToolSpec, RolesPolicy } from '@dudousxd
 ## Key types
 
 - `ToolSpec` — `{ name, kind: 'read' | 'action' | 'agent', description, inputSchema, roles?, ability?, targetAgent?, detached?, terminal? }`. (`ToolKind` has three further members — `'ask'`, `'skill'` and `'memory'` — which no `ToolSpec` carries: they belong to the built-in tools the loop serves itself rather than from a handler. `ask` settles against a person, `skill` against the turn's journaled catalog, `remember` against the turn's journaled memory digest.) `inputSchema` is a [Standard Schema](https://standardschema.dev) (Zod, Valibot, ArkType); the loop validates via `~standard.validate`, throwing `ToolInputInvalidError` on failure.
-- `AiToolCtx.emitUi(component, props, { id?, version? })` — **a tool pushes generative UI.** The `ui` frame streams live (inline, durable, and from a dispatched tool step's worker) and the component is persisted on the assistant message through the optional `AgentStore.setMessageUi`, once per step, after the step's tools settle. `id` defaults to `<toolCallId>:ui:<n>`, so a retried call replaces what it pushed. The pushes ride the tool step's journaled result (`wrapToolStepOutput` / `unwrapToolStepOutput`; the wrapper is only used when something was pushed), so a replay neither re-streams nor re-persists them. `ToolSpec.terminal` ends the turn after a successful call, settled in `persist:toolcall` like `detached`.
+- `AiToolCtx.emitUi(component, props, { id?, version? })` — **a tool pushes generative UI.** The `ui` frame streams live (inline, durable, and from a dispatched tool step's worker) and the component is persisted on the assistant message through the optional `AgentStore.setMessageUi`, once per step, after the step's tools settle. `id` defaults to `<toolCallId>:ui:<n>`, so a retried call replaces what it pushed. The pushes ride the tool step's journaled result (`wrapToolStepOutput` / `unwrapToolStepOutput`; the wrapper is only used when something was pushed), so a replay neither re-streams nor re-persists them. `ToolSpec.terminal` ends the turn after a successful call, settled in `persist:toolcall` like `detached`. `emitUi` is always present: where there is no conversation (the MCP server, a bare `registry.invoke`) it is `createNoopEmitUi()`, which pushes nothing and still resolves to an id.
+- `ToolHandler.describe?({ actor, threadId?, agentName? })` — **a per-turn description.** Called when the turn's tool list is built, after every gate; what it returns replaces the spec's `description` / `inputSchema` in what the model sees (`registry.definitionsFor(actor, policy, allowList, { threadId, agentName })`). The registry still validates calls against the registered schema, so a tool whose input varies per turn registers a permissive one and validates in `execute`.
+- `@dudousxd/nestjs-agent-core/genui` (+ `/genui/builtins`) — **the generative-UI catalog**, an isomorphic entry (no server-only import; a spec holds that line) a browser imports too: `defineComponent` / `defineCatalog` (Standard Schema or JSON Schema props), validation, `catalogToModelText`, `componentToText` fallbacks, tree helpers, and `genuiTools(catalog, { mode, terminal, showTool, resolveCatalog, … })` — the tools that push components, with an optional per-request catalog resolver consulted on every call and every turn's description. NestJS apps use `AgentGenuiModule` (`@dudousxd/nestjs-agent/genui`) instead of calling `genuiTools` themselves.
 - `AgentDefinition` — a named agent (`systemPrompt` string | `PromptBuilder`, `tools`, `delegatesTo`, `personas`, …) for multi-agent setups. `delegatesTo` holds `AgentDelegation` entries: a bare target name for the delegation that waits, `{ agent, detached: true }` for one that does not.
 - `detachedStarted` / `detachedDelivered` / `settleUnsettledDelegation` / `AgentLoopHooks.startAgent` / `AgentRunInput.deliverTo` — **delegation that does not block the chat.** An `agent`-kind call whose spec says `detached` is STARTED rather than awaited (`hooks.startAgent`, which the durable runner maps to `ctx.startChild` and the inline one to a loop nobody awaits), and the turn ends with a `DetachedDelegationReceipt` as the call's result instead of an answer. The started run carries a `deliverTo` address — the delegating thread and the call that started it — and posts its answer there as a message of its own, stamped with its own `runId` and `agentName`, so a client renders "the research agent finished" rather than the assistant's next reply. Whether a call detaches is settled INSIDE `persist:toolcall` alongside its kind and target, never from a live registry lookup, so a replay reads the branch back rather than re-deciding it; the loop writes the same checkpoint names either way, and only the runner's own positions (`spawn:` versus the awaited child's `signal:child:`) differ. A detached run streams into its OWN sink and its `action` tools park on its OWN run, so its approval reaches the pending-approvals surface instead of an inline card in whatever turn happens to be open. `settleUnsettledDelegation` is the runner's half: a run that crashed or was stopped posts a message saying so, because "started" is the one state a reader can neither wait on nor act on. `AgentRunInput.parentRunId` / `RecordRunStartInput.parentRunId` record the edge, so a delegation is not a run row with nothing pointing at it.
 - `RolesPolicy.can(actor, tool): boolean | Promise<boolean>` — the tool authorization seam

package/dist/catalog-CrzetM3_.d.cts

@@ -0,0 +1,147 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+
+/** A JSON Schema document (draft-07 / 2020-12 subset). Plain data, so a catalog can be stored and shipped. */
+type JsonSchema = Record<string, unknown>;
+/** One problem with a value, addressed by its path from the root of the value. */
+interface GenuiIssue {
+    path: (string | number)[];
+    message: string;
+}
+type GenuiValidation<T = unknown> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    issues: GenuiIssue[];
+};
+/**
+ * Validates a value against a JSON Schema. The package ships {@link builtinJsonSchemaValidator} (a
+ * dependency-free subset that covers what component props use); pass {@link ajvValidator} to a
+ * catalog for full JSON Schema.
+ */
+interface JsonSchemaValidator {
+    validate(schema: JsonSchema, value: unknown): GenuiIssue[];
+}
+/** A component's props schema: any Standard Schema (Zod, Valibot, ArkType) or a JSON Schema object. */
+type PropsSchema = StandardSchemaV1 | JsonSchema;
+declare function isStandardSchema(schema: unknown): schema is StandardSchemaV1;
+/**
+ * The JSON Schema a props schema presents to a model: the schema itself for a JSON Schema, the
+ * Standard JSON Schema converter's output for a Standard Schema that has one (Zod 4, Valibot,
+ * ArkType). `undefined` when neither is available (e.g. Zod 3) — the model then gets the
+ * component's description only.
+ */
+declare function toJsonSchema(schema: PropsSchema): JsonSchema | undefined;
+/** Validate against either kind of props schema. A Standard Schema's own (possibly transformed) output wins. */
+declare function validateProps(schema: PropsSchema, value: unknown, validator: JsonSchemaValidator): Promise<GenuiValidation>;
+/**
+ * {@link validateProps} without waiting: the verdict when it is available synchronously (always
+ * for JSON Schema, and for every Standard Schema whose `validate` does not return a promise — Zod,
+ * Valibot and ArkType all answer synchronously for synchronous schemas), `undefined` otherwise. What
+ * a renderer uses to decide on its first paint instead of flashing a placeholder.
+ */
+declare function validatePropsSync(schema: PropsSchema, value: unknown, validator: JsonSchemaValidator): GenuiValidation | undefined;
+/** `a.b[0].c: message; …` — what a model is handed back when its props were refused. */
+declare function formatIssues(issues: readonly GenuiIssue[]): string;
+/**
+ * Structural type of an Ajv instance, so the package never imports Ajv: `new Ajv({ allErrors: true })`
+ * satisfies it.
+ */
+interface AjvLike {
+    compile(schema: object): ((data: unknown) => boolean | Promise<unknown>) & {
+        errors?: {
+            instancePath?: string;
+            message?: string;
+        }[] | null;
+    };
+}
+/**
+ * Full JSON Schema validation through the app's own Ajv instance. Compiled validators are cached
+ * per schema object.
+ */
+declare function ajvValidator(ajv: AjvLike): JsonSchemaValidator;
+/**
+ * A dependency-free JSON Schema validator for the keywords component props actually use: `type`
+ * (incl. `integer`, `null`, type arrays), `enum`, `const`, `properties`, `required`,
+ * `additionalProperties`, `items`, `minItems`/`maxItems`, `minLength`/`maxLength`/`pattern`,
+ * `minimum`/`maximum`, `anyOf`/`oneOf`/`allOf`, `not`, and local `$ref`s (`#`, `#/$defs/…`,
+ * `#/definitions/…`). Unknown keywords (e.g. `format`) are ignored. Use {@link ajvValidator} when
+ * you need the rest.
+ */
+declare const builtinJsonSchemaValidator: JsonSchemaValidator;
+
+/**
+ * One component a server may push into a conversation. Data only — how it LOOKS is each app's own
+ * renderer, looked up by {@link name}. The same definition serves the model (description + props
+ * schema), the server (validation), text-only channels ({@link fallbackText}) and the client
+ * (validation before rendering).
+ */
+interface ComponentDefinition<P = Record<string, unknown>> {
+    /** Registry key, e.g. `DataTable`. What a `ui` frame's `component` names. */
+    name: string;
+    /** Human label: "Data table". */
+    title: string;
+    /** Shown to the model: what the component is for and when to use it. */
+    description: string;
+    /** The props schema: a Standard Schema (Zod, Valibot, ArkType) or a JSON Schema object. */
+    props: PropsSchema;
+    /**
+     * The component takes nested elements (a layout: `Stack`, `Card`). Only meaningful in tree mode,
+     * where a node's `children` are validated against the catalog too.
+     */
+    children?: boolean;
+    /**
+     * Plain text / Slack mrkdwn rendering of these props, for a channel that cannot draw the
+     * component. Absent → {@link componentToText} prints the props as JSON.
+     */
+    fallbackText?: (props: P) => string;
+    /**
+     * Pushed by the server (e.g. an approval card), never offered to the model. Excluded from
+     * {@link catalogToModelText} and from the tool factories.
+     */
+    internal?: boolean;
+    /**
+     * Schema version of {@link props}. Stamped on every `ui` frame the component is pushed with, so a
+     * client can keep rendering messages persisted under an older shape.
+     */
+    version?: number;
+}
+/** Component names: an identifier a registry key, a tool name and a snake_case slug can all be derived from. */
+declare const COMPONENT_NAME: RegExp;
+/** Declare a component. Validates the name and returns the definition unchanged (typed). */
+declare function defineComponent<P = Record<string, unknown>>(definition: ComponentDefinition<P>): ComponentDefinition<P>;
+interface CatalogOptions {
+    /** How JSON Schema props are checked. Default: {@link builtinJsonSchemaValidator}; pass `ajvValidator(new Ajv())` for full JSON Schema. */
+    jsonSchemaValidator?: JsonSchemaValidator;
+}
+/** An immutable set of component definitions, looked up by name. */
+interface Catalog {
+    readonly components: readonly ComponentDefinition<any>[];
+    readonly validator: JsonSchemaValidator;
+    get(name: string): ComponentDefinition<any> | undefined;
+    has(name: string): boolean;
+    /** The components a model may be offered (every non-`internal` one). */
+    modelComponents(): ComponentDefinition<any>[];
+    /** Validate `props` for `component`. An unknown component is a validation failure, not a throw. */
+    validate(component: string, props: unknown): Promise<GenuiValidation<Record<string, unknown>>>;
+    /**
+     * {@link validate} without waiting — `undefined` only when the component's Standard Schema
+     * validates asynchronously. An unknown component is a failure, as in `validate`.
+     */
+    validateSync(component: string, props: unknown): GenuiValidation<Record<string, unknown>> | undefined;
+    /** The component's props as JSON Schema, when it can be derived (see {@link toJsonSchema}). */
+    jsonSchemaFor(component: string): JsonSchema | undefined;
+    /** A new catalog with these components added (a later definition replaces an earlier one of the same name). */
+    extend(components: readonly ComponentDefinition<any>[]): Catalog;
+}
+/**
+ * Collect component definitions into a {@link Catalog}. Names must be unique; to override a
+ * definition (e.g. a builtin), use {@link Catalog.extend}.
+ */
+declare function defineCatalog(components: readonly ComponentDefinition<any>[], options?: CatalogOptions): Catalog;
+/** `DataTable` → `data_table`, `KPICards` → `kpi_cards`. */
+declare function toSnakeCase(name: string): string;
+/** The per-component tool name: `ui__show_data_table` with the default prefix. */
+declare function toolNameFor(component: string, prefix?: string): string;
+
+export { type AjvLike as A, type ComponentDefinition as C, type GenuiValidation as G, type JsonSchema as J, type PropsSchema as P, type Catalog as a, type GenuiIssue as b, COMPONENT_NAME as c, type CatalogOptions as d, type JsonSchemaValidator as e, ajvValidator as f, builtinJsonSchemaValidator as g, defineCatalog as h, defineComponent as i, formatIssues as j, isStandardSchema as k, toSnakeCase as l, toolNameFor as m, validatePropsSync as n, toJsonSchema as t, validateProps as v };

package/dist/catalog-CrzetM3_.d.ts

@@ -0,0 +1,147 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+
+/** A JSON Schema document (draft-07 / 2020-12 subset). Plain data, so a catalog can be stored and shipped. */
+type JsonSchema = Record<string, unknown>;
+/** One problem with a value, addressed by its path from the root of the value. */
+interface GenuiIssue {
+    path: (string | number)[];
+    message: string;
+}
+type GenuiValidation<T = unknown> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    issues: GenuiIssue[];
+};
+/**
+ * Validates a value against a JSON Schema. The package ships {@link builtinJsonSchemaValidator} (a
+ * dependency-free subset that covers what component props use); pass {@link ajvValidator} to a
+ * catalog for full JSON Schema.
+ */
+interface JsonSchemaValidator {
+    validate(schema: JsonSchema, value: unknown): GenuiIssue[];
+}
+/** A component's props schema: any Standard Schema (Zod, Valibot, ArkType) or a JSON Schema object. */
+type PropsSchema = StandardSchemaV1 | JsonSchema;
+declare function isStandardSchema(schema: unknown): schema is StandardSchemaV1;
+/**
+ * The JSON Schema a props schema presents to a model: the schema itself for a JSON Schema, the
+ * Standard JSON Schema converter's output for a Standard Schema that has one (Zod 4, Valibot,
+ * ArkType). `undefined` when neither is available (e.g. Zod 3) — the model then gets the
+ * component's description only.
+ */
+declare function toJsonSchema(schema: PropsSchema): JsonSchema | undefined;
+/** Validate against either kind of props schema. A Standard Schema's own (possibly transformed) output wins. */
+declare function validateProps(schema: PropsSchema, value: unknown, validator: JsonSchemaValidator): Promise<GenuiValidation>;
+/**
+ * {@link validateProps} without waiting: the verdict when it is available synchronously (always
+ * for JSON Schema, and for every Standard Schema whose `validate` does not return a promise — Zod,
+ * Valibot and ArkType all answer synchronously for synchronous schemas), `undefined` otherwise. What
+ * a renderer uses to decide on its first paint instead of flashing a placeholder.
+ */
+declare function validatePropsSync(schema: PropsSchema, value: unknown, validator: JsonSchemaValidator): GenuiValidation | undefined;
+/** `a.b[0].c: message; …` — what a model is handed back when its props were refused. */
+declare function formatIssues(issues: readonly GenuiIssue[]): string;
+/**
+ * Structural type of an Ajv instance, so the package never imports Ajv: `new Ajv({ allErrors: true })`
+ * satisfies it.
+ */
+interface AjvLike {
+    compile(schema: object): ((data: unknown) => boolean | Promise<unknown>) & {
+        errors?: {
+            instancePath?: string;
+            message?: string;
+        }[] | null;
+    };
+}
+/**
+ * Full JSON Schema validation through the app's own Ajv instance. Compiled validators are cached
+ * per schema object.
+ */
+declare function ajvValidator(ajv: AjvLike): JsonSchemaValidator;
+/**
+ * A dependency-free JSON Schema validator for the keywords component props actually use: `type`
+ * (incl. `integer`, `null`, type arrays), `enum`, `const`, `properties`, `required`,
+ * `additionalProperties`, `items`, `minItems`/`maxItems`, `minLength`/`maxLength`/`pattern`,
+ * `minimum`/`maximum`, `anyOf`/`oneOf`/`allOf`, `not`, and local `$ref`s (`#`, `#/$defs/…`,
+ * `#/definitions/…`). Unknown keywords (e.g. `format`) are ignored. Use {@link ajvValidator} when
+ * you need the rest.
+ */
+declare const builtinJsonSchemaValidator: JsonSchemaValidator;
+
+/**
+ * One component a server may push into a conversation. Data only — how it LOOKS is each app's own
+ * renderer, looked up by {@link name}. The same definition serves the model (description + props
+ * schema), the server (validation), text-only channels ({@link fallbackText}) and the client
+ * (validation before rendering).
+ */
+interface ComponentDefinition<P = Record<string, unknown>> {
+    /** Registry key, e.g. `DataTable`. What a `ui` frame's `component` names. */
+    name: string;
+    /** Human label: "Data table". */
+    title: string;
+    /** Shown to the model: what the component is for and when to use it. */
+    description: string;
+    /** The props schema: a Standard Schema (Zod, Valibot, ArkType) or a JSON Schema object. */
+    props: PropsSchema;
+    /**
+     * The component takes nested elements (a layout: `Stack`, `Card`). Only meaningful in tree mode,
+     * where a node's `children` are validated against the catalog too.
+     */
+    children?: boolean;
+    /**
+     * Plain text / Slack mrkdwn rendering of these props, for a channel that cannot draw the
+     * component. Absent → {@link componentToText} prints the props as JSON.
+     */
+    fallbackText?: (props: P) => string;
+    /**
+     * Pushed by the server (e.g. an approval card), never offered to the model. Excluded from
+     * {@link catalogToModelText} and from the tool factories.
+     */
+    internal?: boolean;
+    /**
+     * Schema version of {@link props}. Stamped on every `ui` frame the component is pushed with, so a
+     * client can keep rendering messages persisted under an older shape.
+     */
+    version?: number;
+}
+/** Component names: an identifier a registry key, a tool name and a snake_case slug can all be derived from. */
+declare const COMPONENT_NAME: RegExp;
+/** Declare a component. Validates the name and returns the definition unchanged (typed). */
+declare function defineComponent<P = Record<string, unknown>>(definition: ComponentDefinition<P>): ComponentDefinition<P>;
+interface CatalogOptions {
+    /** How JSON Schema props are checked. Default: {@link builtinJsonSchemaValidator}; pass `ajvValidator(new Ajv())` for full JSON Schema. */
+    jsonSchemaValidator?: JsonSchemaValidator;
+}
+/** An immutable set of component definitions, looked up by name. */
+interface Catalog {
+    readonly components: readonly ComponentDefinition<any>[];
+    readonly validator: JsonSchemaValidator;
+    get(name: string): ComponentDefinition<any> | undefined;
+    has(name: string): boolean;
+    /** The components a model may be offered (every non-`internal` one). */
+    modelComponents(): ComponentDefinition<any>[];
+    /** Validate `props` for `component`. An unknown component is a validation failure, not a throw. */
+    validate(component: string, props: unknown): Promise<GenuiValidation<Record<string, unknown>>>;
+    /**
+     * {@link validate} without waiting — `undefined` only when the component's Standard Schema
+     * validates asynchronously. An unknown component is a failure, as in `validate`.
+     */
+    validateSync(component: string, props: unknown): GenuiValidation<Record<string, unknown>> | undefined;
+    /** The component's props as JSON Schema, when it can be derived (see {@link toJsonSchema}). */
+    jsonSchemaFor(component: string): JsonSchema | undefined;
+    /** A new catalog with these components added (a later definition replaces an earlier one of the same name). */
+    extend(components: readonly ComponentDefinition<any>[]): Catalog;
+}
+/**
+ * Collect component definitions into a {@link Catalog}. Names must be unique; to override a
+ * definition (e.g. a builtin), use {@link Catalog.extend}.
+ */
+declare function defineCatalog(components: readonly ComponentDefinition<any>[], options?: CatalogOptions): Catalog;
+/** `DataTable` → `data_table`, `KPICards` → `kpi_cards`. */
+declare function toSnakeCase(name: string): string;
+/** The per-component tool name: `ui__show_data_table` with the default prefix. */
+declare function toolNameFor(component: string, prefix?: string): string;
+
+export { type AjvLike as A, type ComponentDefinition as C, type GenuiValidation as G, type JsonSchema as J, type PropsSchema as P, type Catalog as a, type GenuiIssue as b, COMPONENT_NAME as c, type CatalogOptions as d, type JsonSchemaValidator as e, ajvValidator as f, builtinJsonSchemaValidator as g, defineCatalog as h, defineComponent as i, formatIssues as j, isStandardSchema as k, toSnakeCase as l, toolNameFor as m, validatePropsSync as n, toJsonSchema as t, validateProps as v };