@jini-ai/agentic 0.1.2 → 0.3.6

package/dist/core/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/core/a2ui/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../src/core/a2ui/tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,CAAC;AAExE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,aAAa,EACvD,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,EAClC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,SAAS,MAAM,EAAE,GAC/C,UAAU,EAAE,CAuCd"}

package/dist/core/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/core/a2ui/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../../src/core/a2ui/tree.ts"],"names":[],"mappings":"AA8BA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAAkC,EAClC,MAAc,EACd,WAAgD;IAEhD,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,kGAAkG;IAClG,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IAGpC,MAAM,KAAK,GAAY,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IAElD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;QAC3B,IAAI,OAAO,IAAI,KAAK,EAAE,CAAC;YACrB,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC9B,SAAS;QACX,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,IAAI,gBAAgB,EAAE,CAAC;YACtC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;YACvE,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;QAC5B,IAAI,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACtB,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;YAC5C,SAAS;QACX,CAAC;QACD,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;YAC9C,SAAS;QACX,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QAC1B,8EAA8E;QAC9E,MAAM,QAAQ,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;QACxC,KAAK,IAAI,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YAC7D,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,QAAQ,CAAC,KAAK,CAAE,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/core/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/core/ag-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ag-ui.d.ts","sourceRoot":"","sources":["../../src/core/ag-ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE5E,wDAAwD;AACxD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;CAC5C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB;IACjC,wEAAwE;;IAExE,8EAA8E;;IAE9E,2EAA2E;;CAEnE,CAAC;AAEX,kEAAkE;AAClE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,aAAa,GAAG,QAAQ,CAM9D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,QAAQ,EAAE,CAEvF;AA+BD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpE,qBAAqB,CAKvB"}

package/dist/core/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/core/ag-ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ag-ui.js","sourceRoot":"","sources":["../../src/core/ag-ui.ts"],"names":[],"mappings":"AA4BA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,wEAAwE;IACxE,KAAK,EAAE,iBAAiB;IACxB,8EAA8E;IAC9E,IAAI,EAAE,gBAAgB;IACtB,2EAA2E;IAC3E,GAAG,EAAE,eAAe;CACZ,CAAC;AAUX;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,UAAyB;IAClD,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,EAAE;QACnB,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,UAAU,EAAE,UAAU,CAAC,WAAW;KACnC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,YAAsC;IAChE,OAAO,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,iBAAiB,CAAC,MAAe;IACxC,IAAI,OAA2B,CAAC;IAChC,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,6CAA6C,MAAM,EAAE,EAAE,CAAC,CAAC;IAC1F,CAAC;IACD,2FAA2F;IAC3F,oFAAoF;IACpF,OAAO,OAAO,IAAI,MAAM,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,UAAkB,EAClB,OAAqE;IAErE,MAAM,OAAO,GAAG,OAAO,CAAC,EAAE;QACxB,CAAC,CAAC,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,MAAM,CAAC;QACzF,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAC7C,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;AAC9D,CAAC"}

package/dist/core/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

package/dist/core/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/core/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,yGAAyG;AACzG,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACtG,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,SAAS,aAAa,EAAE,EACtC,EAAE,EAAE,MAAM,GACT,aAAa,GAAG,SAAS,CAE3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,aAAa,EACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,GAAG,IAAI,CAiCf;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,SAAS,aAAa,EAAE,EACtC,UAAU,EAAE,OAAO,GAClB,SAAS,aAAa,EAAE,CAE1B"}

package/dist/core/capability.js

@@ -0,0 +1,79 @@
+/**
+ * @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.
+ */
+/**
+ * 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 function findCapability(capabilities, id) {
+    return capabilities.find((capability) => capability.id === id);
+}
+/**
+ * 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 function findCapabilityInputError(capability, input) {
+    const { properties, required, additionalProperties } = capability.inputSchema;
+    for (const name of required ?? []) {
+        if (input[name] === undefined)
+            return `"${name}" is required`;
+    }
+    if (additionalProperties === false) {
+        // `key in properties` walks the whole prototype chain, so a key that happens to be inherited
+        // from Object.prototype (`__proto__`, `constructor`, `toString`, `valueOf`, …) reads as
+        // "known" regardless of whether the schema actually lists it — `'constructor' in {}` is
+        // true even on an empty object. `JSON.parse('{"__proto__":...}')` creates a real own data
+        // property (not the accessor), so this was a live way for such a key to escape the
+        // "unknown argument" refusal entirely. hasOwnProperty ignores the prototype chain, so only
+        // keys the schema actually declares count as known.
+        const unknown = Object.keys(input)
+            .filter((key) => !Object.prototype.hasOwnProperty.call(properties, key));
+        if (unknown.length > 0) {
+            return `unknown ${unknown.length === 1 ? 'argument' : 'arguments'}: ${unknown.sort().join(', ')}`;
+        }
+    }
+    for (const [name, schema] of Object.entries(properties)) {
+        const value = input[name];
+        if (value === undefined)
+            continue;
+        const actual = Array.isArray(value) ? 'array' : typeof value;
+        if (actual !== schema.type)
+            return `"${name}" must be a ${schema.type}, received ${actual}`;
+        if (schema.enum !== undefined && !schema.enum.includes(value)) {
+            return `"${name}" must be one of: ${schema.enum.join(', ')}`;
+        }
+    }
+    return 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 function availableCapabilities(capabilities, hasSession) {
+    return hasSession ? capabilities : capabilities.filter((c) => c.surface === 'server');
+}
+//# sourceMappingURL=capability.js.map

package/dist/core/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../src/core/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwCH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,YAAsC,EACtC,EAAU;IAEV,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,wBAAwB,CACtC,UAAyB,EACzB,KAA8B;IAE9B,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,oBAAoB,EAAE,GAAG,UAAU,CAAC,WAAW,CAAC;IAE9E,KAAK,MAAM,IAAI,IAAI,QAAQ,IAAI,EAAE,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,SAAS;YAAE,OAAO,IAAI,IAAI,eAAe,CAAC;IAChE,CAAC;IAED,IAAI,oBAAoB,KAAK,KAAK,EAAE,CAAC;QACnC,6FAA6F;QAC7F,wFAAwF;QACxF,wFAAwF;QACxF,0FAA0F;QAC1F,mFAAmF;QACnF,2FAA2F;QAC3F,oDAAoD;QACpD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;aAC/B,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC;QAC3E,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,WAAW,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpG,CAAC;IACH,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACxD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC;QAC7D,IAAI,MAAM,KAAK,MAAM,CAAC,IAAI;YAAE,OAAO,IAAI,IAAI,eAAe,MAAM,CAAC,IAAI,cAAc,MAAM,EAAE,CAAC;QAC5F,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAe,CAAC,EAAE,CAAC;YACxE,OAAO,IAAI,IAAI,qBAAqB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/D,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,YAAsC,EACtC,UAAmB;IAEnB,OAAO,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC;AACxF,CAAC"}

package/dist/core/dom/dom-page-driver.d.ts

@@ -0,0 +1,36 @@
+import type { PageDriver } from '../page-driver.js';
+/** One page a host allows navigation to: its human label, and how to actually get there. */
+export interface DomPageDriverPage {
+    /** Shown to a caller by `page.find_elements`/`page.navigate`'s refusal message — see
+     *  `PageSummary.label` for why this exists at all. */
+    readonly label: string;
+    readonly navigate: () => void;
+}
+export interface DomPageDriverOptions {
+    /** The subtree to expose. Never pass `document`. */
+    readonly root: ParentNode & {
+        querySelector: Element['querySelector'];
+    };
+    /** Page ids this driver may navigate to, each with its label and how to get there. */
+    readonly pages: Readonly<Record<string, DomPageDriverPage>>;
+    /**
+     * The id of the page currently shown, reported on every element.
+     *
+     * Omit it in a single-page app that swaps views: the driver then reads `data-agent-page` from
+     * the live DOM on every call, so navigating actually changes what elements report. A value
+     * captured here is fixed for the driver's whole lifetime, which is right only for a surface that
+     * never changes view — and silently wrong for one that does, since the driver outlives any one
+     * view (it is bound to the connection, not the render).
+     */
+    readonly currentPage?: string | undefined;
+}
+/**
+ * Builds a driver over `root`.
+ *
+ * @param options - The subtree, the navigable pages, and the current page id.
+ * @returns A driver ready to hand to `executePageCapability`.
+ */
+export declare function createDomPageDriver(options: DomPageDriverOptions): PageDriver;
+/** Reads the current page's `data-agent-page`, for hosts that tag the body. */
+export declare function currentAgentPage(root: ParentNode): string | undefined;
+//# sourceMappingURL=dom-page-driver.d.ts.map

package/dist/core/dom/dom-page-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-page-driver.d.ts","sourceRoot":"","sources":["../../../src/core/dom/dom-page-driver.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAsB,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAgNxE,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC;0DACsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG;QAAE,aAAa,EAAE,OAAO,CAAC,eAAe,CAAC,CAAA;KAAE,CAAC;IACxE,sFAAsF;IACtF,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC5D;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,UAAU,CA2V7E;AAgDD,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAGrE"}