@jini-ai/agentic 0.4.1 → 0.4.3

package/dist/a2ui/tree.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @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' | 'truncated';
+export interface RenderNode {
+    readonly id: string;
+    readonly depth: number;
+    readonly status: RenderNodeStatus;
+}
+/**
+ * Ceiling on how many nodes one flattening may produce.
+ *
+ * The cycle check bounds *repetition along one path*; it does not bound the tree's size, and a
+ * component map is an adjacency list, so a valid acyclic message can name the same child twice per
+ * level and double the output at every step. Measured before this cap existed: 24 components —
+ * a few hundred bytes of wire data — expanded to 16,777,215 render nodes in ~15 seconds. Nothing
+ * crashed; the renderer was simply consumed.
+ *
+ * Far above any real UI (the largest component tree a catalog of 18 types could sensibly produce
+ * is orders of magnitude smaller), so this is a fail-safe, not a design budget.
+ */
+export declare const MAX_RENDER_NODES = 50000;
+/**
+ * @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). A `truncated` node is the
+ * third such marker and always the last entry: the tree exceeded {@link MAX_RENDER_NODES} and the
+ * rest was not walked.
+ *
+ * The walk is iterative — an explicit stack rather than recursion — because the component map is
+ * agent-authored: a straight chain of components is a legal, acyclic message, and a recursive walk
+ * died on one with `RangeError: Maximum call stack size exceeded` somewhere past 6,000 links.
+ * Degrading sanely on hostile input is this module's whole purpose, and "deep" belongs on that
+ * list next to "missing" and "circular".
+ *
+ * The ancestor set is maintained by push/pop along the current path rather than copied per node,
+ * which is both what makes the iterative form equivalent (an ancestor set IS the path from the
+ * root) and what removes the old walk's quadratic set-copying cost.
+ */
+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.js

@@ -0,0 +1,74 @@
+/**
+ * Ceiling on how many nodes one flattening may produce.
+ *
+ * The cycle check bounds *repetition along one path*; it does not bound the tree's size, and a
+ * component map is an adjacency list, so a valid acyclic message can name the same child twice per
+ * level and double the output at every step. Measured before this cap existed: 24 components —
+ * a few hundred bytes of wire data — expanded to 16,777,215 render nodes in ~15 seconds. Nothing
+ * crashed; the renderer was simply consumed.
+ *
+ * Far above any real UI (the largest component tree a catalog of 18 types could sensibly produce
+ * is orders of magnitude smaller), so this is a fail-safe, not a design budget.
+ */
+export const MAX_RENDER_NODES = 50_000;
+/**
+ * @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). A `truncated` node is the
+ * third such marker and always the last entry: the tree exceeded {@link MAX_RENDER_NODES} and the
+ * rest was not walked.
+ *
+ * The walk is iterative — an explicit stack rather than recursion — because the component map is
+ * agent-authored: a straight chain of components is a legal, acyclic message, and a recursive walk
+ * died on one with `RangeError: Maximum call stack size exceeded` somewhere past 6,000 links.
+ * Degrading sanely on hostile input is this module's whole purpose, and "deep" belongs on that
+ * list next to "missing" and "circular".
+ *
+ * The ancestor set is maintained by push/pop along the current path rather than copied per node,
+ * which is both what makes the iterative form equivalent (an ancestor set IS the path from the
+ * root) and what removes the old walk's quadratic set-copying cost.
+ */
+export function flattenRenderTree(components, rootId, getChildIds) {
+    const output = [];
+    /** Ids on the path from the root to the node being visited — the recursive walk's `ancestors`. */
+    const ancestors = new Set();
+    const stack = [{ id: rootId, depth: 0 }];
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if ('leave' in frame) {
+            ancestors.delete(frame.leave);
+            continue;
+        }
+        if (output.length >= MAX_RENDER_NODES) {
+            output.push({ id: frame.id, depth: frame.depth, status: 'truncated' });
+            return output;
+        }
+        const { id, depth } = frame;
+        if (ancestors.has(id)) {
+            output.push({ id, depth, status: 'cycle' });
+            continue;
+        }
+        const component = components.get(id);
+        if (!component) {
+            output.push({ id, depth, status: 'missing' });
+            continue;
+        }
+        output.push({ id, depth, status: 'ok' });
+        ancestors.add(id);
+        stack.push({ leave: id });
+        // Pushed in reverse so the first child is popped first, preserving pre-order.
+        const childIds = getChildIds(component);
+        for (let index = childIds.length - 1; index >= 0; index -= 1) {
+            stack.push({ id: childIds[index], depth: depth + 1 });
+        }
+    }
+    return output;
+}
+//# sourceMappingURL=tree.js.map

package/dist/ag-ui.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @module ag-ui
+ *
+ * Projection: {@link CapabilityDef} → an AG-UI frontend tool.
+ *
+ * AG-UI (the Agent-User Interaction Protocol) streams typed events between an agent backend and
+ * a frontend. The relevant half here is its **frontend tool calls**: the frontend passes its
+ * tools in `RunAgentInput.tools`, the agent emits a tool call, the frontend executes it, and the
+ * frontend returns a `role: "tool"` message referencing the call id. That is the same handoff
+ * Jini's capabilities describe, which is why this projection is a rename rather than a redesign.
+ *
+ * One shape difference this file exists to absorb: **AG-UI names the JSON Schema field
+ * `parameters`**, where WebMCP and MCP both name it `inputSchema`. Anything reading a manifest
+ * through the wrong name silently sends a tool with no arguments.
+ *
+ * Transport is not here — AG-UI runs over SSE or WebSocket, and this package opens no
+ * connections. This is the vocabulary translation only.
+ */
+import type { CapabilityDef, CapabilityInputSchema } from './capability.js';
+/** An AG-UI tool as passed in `RunAgentInput.tools`. */
+export interface AgUiTool {
+    readonly name: string;
+    readonly description: string;
+    /** JSON Schema. Note the field name: AG-UI says `parameters`, not `inputSchema`. */
+    readonly parameters: CapabilityInputSchema;
+}
+/**
+ * The tool-call event names AG-UI emits, agent → frontend.
+ *
+ * Arguments stream: `TOOL_CALL_ARGS` carries a `delta` fragment and may arrive many times for
+ * one call, so a consumer must accumulate by `toolCallId` and only execute after
+ * `TOOL_CALL_END`. Acting on a partial argument object is the obvious failure here.
+ */
+export declare const AG_UI_TOOL_CALL_EVENTS: {
+    /** Fields: `toolCallId`, `toolCallName`, optional `parentMessageId`. */
+    readonly start: "TOOL_CALL_START";
+    /** Fields: `toolCallId`, `delta` — a JSON fragment, not a complete object. */
+    readonly args: "TOOL_CALL_ARGS";
+    /** Fields: `toolCallId`. Arguments are complete only once this arrives. */
+    readonly end: "TOOL_CALL_END";
+};
+/** The message a frontend returns after executing a tool call. */
+export interface AgUiToolResultMessage {
+    readonly id: string;
+    readonly role: 'tool';
+    readonly content: string;
+    readonly toolCallId: string;
+}
+/**
+ * Projects one capability into an AG-UI tool.
+ *
+ * @param capability - The capability to expose.
+ * @returns The tool entry for `RunAgentInput.tools`.
+ */
+export declare function toAgUiTool(capability: CapabilityDef): AgUiTool;
+/**
+ * Projects a whole manifest.
+ *
+ * @param capabilities - Capabilities to expose, already filtered by whatever policy applies.
+ * @returns One tool per capability, in manifest order.
+ */
+export declare function toAgUiTools(capabilities: readonly CapabilityDef[]): readonly AgUiTool[];
+/**
+ * Builds the result message for a completed frontend tool call.
+ *
+ * AG-UI carries the result as a string, so structured output is JSON-encoded. Errors are
+ * returned through this same channel rather than thrown — the agent needs to see the refusal
+ * (a fill guard saying no, an unavailable capability) as a result it can reason about.
+ *
+ * @param messageId - Id for the result message itself.
+ * @param toolCallId - The `toolCallId` from `TOOL_CALL_START`.
+ * @param outcome - What happened.
+ * @returns The `role: "tool"` message to send back.
+ */
+export declare function createAgUiToolResult(messageId: string, toolCallId: string, outcome: {
+    ok: true;
+    output: unknown;
+} | {
+    ok: false;
+    error: string;
+}): AgUiToolResultMessage;
+//# sourceMappingURL=ag-ui.d.ts.map

package/dist/ag-ui.js

@@ -0,0 +1,85 @@
+/**
+ * The tool-call event names AG-UI emits, agent → frontend.
+ *
+ * Arguments stream: `TOOL_CALL_ARGS` carries a `delta` fragment and may arrive many times for
+ * one call, so a consumer must accumulate by `toolCallId` and only execute after
+ * `TOOL_CALL_END`. Acting on a partial argument object is the obvious failure here.
+ */
+export const AG_UI_TOOL_CALL_EVENTS = {
+    /** Fields: `toolCallId`, `toolCallName`, optional `parentMessageId`. */
+    start: 'TOOL_CALL_START',
+    /** Fields: `toolCallId`, `delta` — a JSON fragment, not a complete object. */
+    args: 'TOOL_CALL_ARGS',
+    /** Fields: `toolCallId`. Arguments are complete only once this arrives. */
+    end: 'TOOL_CALL_END',
+};
+/**
+ * Projects one capability into an AG-UI tool.
+ *
+ * @param capability - The capability to expose.
+ * @returns The tool entry for `RunAgentInput.tools`.
+ */
+export function toAgUiTool(capability) {
+    return {
+        name: capability.id,
+        description: capability.description,
+        parameters: capability.inputSchema,
+    };
+}
+/**
+ * Projects a whole manifest.
+ *
+ * @param capabilities - Capabilities to expose, already filtered by whatever policy applies.
+ * @returns One tool per capability, in manifest order.
+ */
+export function toAgUiTools(capabilities) {
+    return capabilities.map(toAgUiTool);
+}
+/**
+ * JSON, or a description of why there is none — always a string, which `JSON.stringify` alone is
+ * not.
+ *
+ * `output` is `unknown`: whatever a host's capability actually returned. `JSON.stringify` is not
+ * total over that domain, in two different ways, and `content` is declared `string`:
+ *
+ * - it **throws** for a BigInt or a circular structure — landing on the transport, where the
+ *   agent never learns its tool call produced anything at all;
+ * - it **returns `undefined`** (not a string) for a function or a symbol, so `content` was
+ *   genuinely `undefined` despite its type, and whatever serialized the message downstream
+ *   dropped the field or wrote `undefined` into the wire.
+ *
+ * Both become a result the agent can read, because that is this channel's whole premise: a
+ * failure it can see and reason about beats one that disappears.
+ */
+function encodeToolContent(output) {
+    let encoded;
+    try {
+        encoded = JSON.stringify(output ?? null);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return JSON.stringify({ error: `tool output could not be encoded as JSON: ${detail}` });
+    }
+    // `undefined` here means "not representable in JSON" (a function, a symbol), which is what
+    // `null` means in every other JSON position — an array element, an object property.
+    return encoded ?? 'null';
+}
+/**
+ * Builds the result message for a completed frontend tool call.
+ *
+ * AG-UI carries the result as a string, so structured output is JSON-encoded. Errors are
+ * returned through this same channel rather than thrown — the agent needs to see the refusal
+ * (a fill guard saying no, an unavailable capability) as a result it can reason about.
+ *
+ * @param messageId - Id for the result message itself.
+ * @param toolCallId - The `toolCallId` from `TOOL_CALL_START`.
+ * @param outcome - What happened.
+ * @returns The `role: "tool"` message to send back.
+ */
+export function createAgUiToolResult(messageId, toolCallId, outcome) {
+    const content = outcome.ok
+        ? typeof outcome.output === 'string' ? outcome.output : encodeToolContent(outcome.output)
+        : JSON.stringify({ error: outcome.error });
+    return { id: messageId, role: 'tool', content, toolCallId };
+}
+//# sourceMappingURL=ag-ui.js.map

package/dist/agui/encoder.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module agui/encoder
+ *
+ * Encodes `@jini/protocol`'s `RunProtocolEvent` stream into AG-UI wire events (see
+ * `./events.ts`'s module doc). Rewritten from scratch against `@jini/protocol`'s actual
+ * current shape — the ported adapter's original encoder targeted a different, product-specific
+ * event union with no direct correspondence to `RunProtocolEvent`/`RunAgentPayload`; only the
+ * *shape* of the job (a big per-event-kind switch, unrecognized events silently dropped) carried
+ * over. See `source-map.md` for the full old→new field-mapping table and the generalization
+ * writeup for the six event kinds that had no generic equivalent before this task.
+ *
+ * Folded in 2026-07-26 from the standalone `@jini/agui` package (plan §3a) into this `src/agui/`
+ * subdirectory — kept out of the flat `ag-ui.ts` namespace because that file is a different
+ * projection ({@link CapabilityDef} → an AG-UI *frontend tool*); this one turns a run's event
+ * stream into AG-UI *wire* events. Same protocol, two unrelated halves of it.
+ */
+import type { RunProtocolEvent } from '@jini/protocol';
+import type { AGUIEvent } from './events.js';
+export interface AguiEncodeContext {
+    /** The run this event belongs to — stamped onto every produced `AGUIEvent`. */
+    readonly runId: string;
+    /** Passed through onto the produced event's `seq`, when the caller tracks one (e.g. an SSE `Last-Event-ID`-shaped cursor). Omitted entirely (not set to `undefined`) when absent, matching the original adapter's own base-field construction. */
+    readonly seq?: number;
+    /** Injectable clock for the produced event's `ts`. Defaults to `Date.now`. Test-only hook. */
+    readonly now?: () => number;
+}
+/**
+ * A stateful AG-UI encoder for one run's event stream. Stateful because `tool_use`/`tool_result`
+ * correlation requires remembering each in-flight tool call's name/args between the two protocol
+ * events that describe its start and end — a pure per-event function cannot do this alone. Create
+ * one instance per run (e.g. one per `RunLifecycle.stream(runId, ...)` subscription); do not share
+ * an instance across multiple runs, since the correlation map has no per-run partitioning of its
+ * own (`ctx.runId` is only used to stamp the produced event, not to scope the map).
+ */
+export interface AguiEncoder {
+    /**
+     * Encodes one `RunProtocolEvent` into an `AGUIEvent`, or `null` if this event has no AG-UI
+     * equivalent (an unrecognized/not-yet-generalized event kind — silently dropped by the relay,
+     * matching the original adapter's own default behavior).
+     */
+    encode(event: RunProtocolEvent, ctx: AguiEncodeContext): AGUIEvent | null;
+}
+/**
+ * Creates a fresh `AguiEncoder` with its own, empty tool-call correlation map.
+ * @complexity `encode` is O(1) per call (one `Map` get/set/delete); memory is O(k) in the number
+ * of currently in-flight (not yet resolved) tool calls for the run this instance encodes.
+ * @overallScore 100/100
+ */
+export declare function createAguiEncoder(): AguiEncoder;
+//# sourceMappingURL=encoder.d.ts.map

package/dist/agui/encoder.js

@@ -0,0 +1,97 @@
+/**
+ * Creates a fresh `AguiEncoder` with its own, empty tool-call correlation map.
+ * @complexity `encode` is O(1) per call (one `Map` get/set/delete); memory is O(k) in the number
+ * of currently in-flight (not yet resolved) tool calls for the run this instance encodes.
+ * @overallScore 100/100
+ */
+export function createAguiEncoder() {
+    const pendingToolCalls = new Map();
+    function baseFields(ctx) {
+        const ts = ctx.now ? ctx.now() : Date.now();
+        return ctx.seq !== undefined ? { runId: ctx.runId, ts, seq: ctx.seq } : { runId: ctx.runId, ts };
+    }
+    function encodeAgentPayload(payload, ctx) {
+        const base = baseFields(ctx);
+        switch (payload.type) {
+            case 'text_delta':
+                return { ...base, kind: 'agent.message', text: payload.delta };
+            case 'tool_use':
+                // Overwrites any prior entry under the same id (a duplicate tool_use for one id) — the
+                // most recent call's name/args are what a matching tool_result should be attributed to,
+                // and there is no protocol-level guarantee ids are never reused within one run.
+                pendingToolCalls.set(payload.id, { toolName: payload.name, args: payload.input });
+                return { ...base, kind: 'tool_call', toolName: payload.name, args: payload.input, callId: payload.id, status: 'started' };
+            case 'tool_result': {
+                const pending = pendingToolCalls.get(payload.toolUseId);
+                pendingToolCalls.delete(payload.toolUseId);
+                return {
+                    ...base,
+                    kind: 'tool_call',
+                    // A tool_result with no matching prior tool_use (never observed, or already resolved/
+                    // cleared — e.g. after a run-ending 'end' event, see below) falls back to an 'unknown'
+                    // name and null args rather than throwing: the result itself is still real and worth
+                    // relaying even when its originating call wasn't captured.
+                    toolName: pending?.toolName ?? 'unknown',
+                    args: pending?.args ?? null,
+                    callId: payload.toolUseId,
+                    status: payload.isError ? 'failed' : 'completed',
+                    result: payload.content,
+                };
+            }
+            // Generalization (see source-map.md): pipeline_stage_started/completed generalized into a
+            // named-stage boundary any multi-step driver can emit, flowing through the same 'agent'
+            // channel as tool_use/tool_result.
+            case 'stage_start':
+                return {
+                    ...base,
+                    kind: 'run.lifecycle',
+                    status: 'pipeline_stage_started',
+                    stageId: payload.stageId,
+                    ...(payload.iteration !== undefined ? { iteration: payload.iteration } : {}),
+                };
+            case 'stage_end':
+                return {
+                    ...base,
+                    kind: 'run.lifecycle',
+                    status: 'pipeline_stage_completed',
+                    stageId: payload.stageId,
+                    ...(payload.iteration !== undefined ? { iteration: payload.iteration } : {}),
+                };
+            // Generalization (see source-map.md): genui_surface_request/response generalized into a
+            // generic human-in-the-loop ask/answer pair.
+            case 'surface_request':
+                return { ...base, kind: 'ui.surface_requested', surfaceId: payload.surfaceId, surfaceKind: payload.surfaceKind, payload: payload.payload };
+            case 'surface_response':
+                return { ...base, kind: 'ui.surface_responded', surfaceId: payload.surfaceId, value: payload.value, respondedBy: payload.respondedBy };
+            // 'status' / 'thinking_start' / 'thinking_delta' / 'tool_input_delta' / 'usage' / 'raw':
+            // no AG-UI equivalent — silently dropped, matching the original adapter's default behavior.
+            default:
+                return null;
+        }
+    }
+    function encode(event, ctx) {
+        switch (event.kind) {
+            case 'start':
+                return { ...baseFields(ctx), kind: 'run.lifecycle', status: 'started' };
+            case 'end': {
+                const status = event.payload.status === 'failed' ? 'failed' : event.payload.status === 'canceled' ? 'cancelled' : 'completed';
+                // A run can legitimately end while a tool_use is still in flight (its tool_result never
+                // arrived, or arrived after 'end' and was already rejected by RunLifecycle — see
+                // run-lifecycle.ts's "cannot emit on terminal run" guard). Clearing here means any such
+                // stale entries never leak past this run's own lifetime, and a same-id tool_result that
+                // somehow still reaches this encoder afterward correctly falls back to 'unknown' rather
+                // than resolving against a call from a run that has already ended.
+                pendingToolCalls.clear();
+                return { ...baseFields(ctx), kind: 'run.lifecycle', status };
+            }
+            case 'agent':
+                return encodeAgentPayload(event.payload, ctx);
+            // 'stdout' / 'stderr' / 'error': no AG-UI equivalent — silently dropped, matching the
+            // original adapter's default behavior for unrecognized event kinds.
+            default:
+                return null;
+        }
+    }
+    return { encode };
+}
+//# sourceMappingURL=encoder.js.map

package/dist/agui/events.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @module agui/events
+ *
+ * The AG-UI wire event shapes `./encoder.ts` produces. AG-UI (Agent-User Interaction
+ * Protocol) is CopilotKit's open, external wire protocol for streaming an agent's run over SSE to
+ * a UI client — see https://github.com/ag-ui-protocol/ag-ui. This module is a near-verbatim port
+ * of a 312-line adapter that encoded a product's own run-event stream into this shape; the types
+ * themselves are unchanged in kind, only de-branded (see `source-map.md` for the full
+ * field-mapping table and provenance).
+ *
+ * Folded in 2026-07-26 from the standalone `@jini/agui` package (plan §3a) into this `src/agui/`
+ * subdirectory — see `./encoder.ts` for why it is kept apart from the flat `ag-ui.ts`.
+ */
+export type AGUIEventKind = 'agent.message' | 'tool_call' | 'state_update' | 'ui.surface_requested' | 'ui.surface_responded' | 'run.lifecycle';
+export interface AGUIEventBase {
+    kind: AGUIEventKind;
+    runId: string;
+    seq?: number;
+    ts: number;
+}
+export interface AGUIAgentMessageEvent extends AGUIEventBase {
+    kind: 'agent.message';
+    text: string;
+    done?: boolean;
+}
+export interface AGUIToolCallEvent extends AGUIEventBase {
+    kind: 'tool_call';
+    toolName: string;
+    args: unknown;
+    callId?: string;
+    status?: 'started' | 'completed' | 'failed';
+    result?: unknown;
+}
+export interface AGUIStateUpdateEvent extends AGUIEventBase {
+    kind: 'state_update';
+    path: string;
+    value: unknown;
+}
+export interface AGUISurfaceRequestedEvent extends AGUIEventBase {
+    kind: 'ui.surface_requested';
+    surfaceId: string;
+    surfaceKind: 'form' | 'choice' | 'confirmation' | 'oauth-prompt';
+    payload: unknown;
+}
+export interface AGUISurfaceRespondedEvent extends AGUIEventBase {
+    kind: 'ui.surface_responded';
+    surfaceId: string;
+    value: unknown;
+    respondedBy: 'user' | 'agent' | 'auto' | 'cache';
+}
+export interface AGUIRunLifecycleEvent extends AGUIEventBase {
+    kind: 'run.lifecycle';
+    status: 'started' | 'pipeline_stage_started' | 'pipeline_stage_completed' | 'completed' | 'cancelled' | 'failed';
+    stageId?: string;
+    iteration?: number;
+    message?: string;
+}
+export type AGUIEvent = AGUIAgentMessageEvent | AGUIToolCallEvent | AGUIStateUpdateEvent | AGUISurfaceRequestedEvent | AGUISurfaceRespondedEvent | AGUIRunLifecycleEvent;
+//# sourceMappingURL=events.d.ts.map

package/dist/agui/events.js

@@ -0,0 +1,15 @@
+/**
+ * @module agui/events
+ *
+ * The AG-UI wire event shapes `./encoder.ts` produces. AG-UI (Agent-User Interaction
+ * Protocol) is CopilotKit's open, external wire protocol for streaming an agent's run over SSE to
+ * a UI client — see https://github.com/ag-ui-protocol/ag-ui. This module is a near-verbatim port
+ * of a 312-line adapter that encoded a product's own run-event stream into this shape; the types
+ * themselves are unchanged in kind, only de-branded (see `source-map.md` for the full
+ * field-mapping table and provenance).
+ *
+ * Folded in 2026-07-26 from the standalone `@jini/agui` package (plan §3a) into this `src/agui/`
+ * subdirectory — see `./encoder.ts` for why it is kept apart from the flat `ag-ui.ts`.
+ */
+export {};
+//# sourceMappingURL=events.js.map

package/dist/capability.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @module capability
+ *
+ * The vocabulary every agent-drivable surface shares: what an outside caller may ask a
+ * frontend to do, described as pure data with no transport, DOM, or framework attached.
+ *
+ * One noun, deliberately: **capability**. The chat pane's first draft used `tool` in its
+ * type names and `capability` in its ids, which forked the vocabulary across four files.
+ * `tool` stays reserved for the engine's own `ToolRegistry`/`ToolExecutor` nouns; anything
+ * an outside caller asks a *frontend* to do is a capability. Transports may of course
+ * present capabilities as MCP tools — that is a projection, not a rename.
+ */
+/** How much damage a capability can do. `requiresConfirmation` is the enforcement; this is the label. */
+export type CapabilityRisk = 'read' | 'write';
+/**
+ * Whether a capability means anything without a live UI session attached.
+ *
+ * - `session` — needs a connected frontend. "Highlight this field" is meaningless with no
+ *   tab open, and must fail closed with a distinct error rather than hanging on a timeout.
+ * - `server` — a product outcome the backend can satisfy headlessly. Sending a chat message
+ *   is the same outcome whether a tab is open or not.
+ *
+ * This decides *availability*, so a caller can be told "no eligible frontend is connected"
+ * instead of waiting for a timeout that will never resolve.
+ */
+export type CapabilitySurface = 'session' | 'server';
+export interface CapabilityInputSchema {
+    readonly type: 'object';
+    readonly properties: Record<string, {
+        type: string;
+        description?: string;
+        enum?: readonly string[];
+    }>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean;
+}
+export interface CapabilityDef {
+    readonly id: string;
+    readonly description: string;
+    readonly inputSchema: CapabilityInputSchema;
+    readonly risk: CapabilityRisk;
+    readonly surface: CapabilitySurface;
+    /**
+     * Destructive or otherwise irreversible — the caller must acknowledge before it runs. A host
+     * with a real confirmation gate (`@jini-ai/daemon`'s `ToolExecutor` has a resumable one) should
+     * enforce it there; surfaces without one enforce it in-band by requiring `confirm: true`, so
+     * no transport can execute it by accident.
+     */
+    readonly requiresConfirmation?: boolean;
+}
+/**
+ * Looks a capability up by id.
+ *
+ * @param capabilities - The manifest to search.
+ * @param id - Capability id to resolve.
+ * @returns The definition, or `undefined` when the id is not in the manifest.
+ */
+export declare function findCapability(capabilities: readonly CapabilityDef[], id: string): CapabilityDef | undefined;
+/**
+ * Checks caller input against a capability's declared schema.
+ *
+ * Manifests advertise `additionalProperties: false` and a `required` list, but nothing was
+ * enforcing either — handlers read the fields they knew about and ignored the rest, so a
+ * misnamed argument silently became a missing one. This closes that for any surface that calls
+ * it. Intentionally a shallow check, not a JSON Schema engine: these schemas are flat by
+ * construction, and a real validator is a dependency this package will not take.
+ *
+ * @param capability - The capability being invoked.
+ * @param input - Raw caller-supplied arguments.
+ * @returns An error message, or `null` when the input is acceptable.
+ */
+export declare function findCapabilityInputError(capability: CapabilityDef, input: Record<string, unknown>): string | null;
+/**
+ * The capabilities a caller may use given what is currently connected.
+ *
+ * @param capabilities - The full manifest.
+ * @param hasSession - Whether a live frontend session is attached.
+ * @returns Only the capabilities that can actually be satisfied right now.
+ */
+export declare function availableCapabilities(capabilities: readonly CapabilityDef[], hasSession: boolean): readonly CapabilityDef[];
+//# sourceMappingURL=capability.d.ts.map