@adonis-agora/agent/dist/src/genui/actions.d.ts

Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.

/**
 * UI actions: what a drawn component hands back to the agent — a sandbox's `agent.send(…)`, an
 * A2UI button's `action` event, an app component's own button. Every kind becomes the same thing:
 * the next user turn, whose text says what was done and carries the values.
 *
 * Framework-free and isomorphic: the browser builds one before sending, the server reads and checks
 * one that arrives over a protocol (A2UI, AG-UI's `forwardedProps`).
 */
import type { StandardSchemaV1 } from '@standard-schema/spec';
import { type GenuiIssue, type JsonSchema } from './schema.js';
/** Where an action came from. */
export type UiActionSource = 'sandbox' | 'a2ui' | 'component';
export interface UiAction {
    source: UiActionSource;
    /** What was done (`send` for a plain `agent.send`, an A2UI event's `name`, a button's own name). */
    name: string;
    /** The values that go with it — JSON. */
    context: Record<string, unknown>;
    /** What the user says by doing it ("Split it three ways"). Shown as their message. */
    text?: string;
    /** The `ui` frame id (or A2UI surface id) the action came from. */
    surfaceId?: string;
    /** The tree node (or A2UI component id) that raised it. */
    componentId?: string;
    /** The view's title, for the model's benefit. */
    title?: string;
    /** ISO 8601, when the user acted. */
    timestamp?: string;
}
/** Largest action accepted by default, as JSON, in bytes. */
export declare const UI_ACTION_MAX_BYTES = 8192;
/** Bytes of `value` as JSON, or `undefined` when it is not JSON (a cycle, a function, a bigint). */
export declare function jsonByteLength(value: unknown): number | undefined;
export interface ReadUiActionOptions {
    /** Default {@link UI_ACTION_MAX_BYTES}. */
    maxBytes?: number;
    /** The source to stamp when the raw value names none. Default `component`. */
    source?: UiActionSource;
}
/**
 * A UI action from untrusted input, checked: a plain object with a short `name` and a JSON
 * `context`, no larger than `maxBytes`. Answers the problem as a string when it is refused.
 */
export declare function readUiAction(raw: unknown, options?: ReadUiActionOptions): UiAction | string;
/**
 * The action a sandbox's `agent.send(payload)` stands for: `payload.text` is what the user says,
 * `payload.action` (optional) names it, and every other field is a value.
 */
export declare function sandboxAction(payload: unknown, frame?: {
    surfaceId?: string;
    componentId?: string;
    title?: string;
}): UiAction;
/**
 * Check an action's `context` against a schema (Zod, Valibot, ArkType — any Standard Schema — or a
 * JSON Schema). Answers the parsed context, or the issues.
 */
export declare function validateUiActionContext(action: UiAction, schema: StandardSchemaV1 | JsonSchema): Promise<{
    ok: true;
    context: Record<string, unknown>;
} | {
    ok: false;
    issues: GenuiIssue[];
}>;
/**
 * The user message an action becomes: what the user said (or a sentence naming the action), then
 * where it came from and its values as a JSON block — the model reads both.
 */
export declare function uiActionText(action: UiAction): string;
/** A user message {@link uiActionText} wrote, read back: what a transcript shows instead of its text. */
export interface UiActionMessage {
    /** What the user said (the action's `text`, or the sentence naming it). */
    text: string;
    /** The action's name. */
    name: string;
    source: UiActionSource;
    /** The view's title, when the action named one. */
    title?: string;
    /** The values the model read. */
    context: Record<string, unknown>;
}
/**
 * The inverse of {@link uiActionText}: a user message that is a UI action, as its parts — or `null`
 * for any other message. The message itself stays what it was (the model reads it whole); this is
 * for drawing it: the user's sentence as a chip, the values out of sight.
 */
export declare function readUiActionText(message: string): UiActionMessage | null;
/**
 * One line for a UI action — what a chip says: the user's sentence, then up to `maxValues` of its
 * plain values (`"Recalculate · people: 4, tip: 15"`). Nested values are left out (the model has
 * them; a chip has no room).
 */
export declare function uiActionSummary(action: Pick<UiActionMessage, 'text' | 'context'> | Pick<UiAction, 'name' | 'text' | 'context'>, options?: {
    maxValues?: number;
}): string;
//# sourceMappingURL=actions.d.ts.map