@jini-ai/agentic 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Open Design contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ag-ui.d.ts","sourceRoot":"","sources":["../src/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;AAED;;;;;;;;;;;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/ag-ui.js

@@ -0,0 +1,56 @@
+/**
+ * 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);
+}
+/**
+ * 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 : JSON.stringify(outcome.output ?? null)
+        : JSON.stringify({ error: outcome.error });
+    return { id: messageId, role: 'tool', content, toolCallId };
+}
+//# sourceMappingURL=ag-ui.js.map

package/dist/ag-ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ag-ui.js","sourceRoot":"","sources":["../src/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;;;;;;;;;;;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,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;QAC9F,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/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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.d.ts","sourceRoot":"","sources":["../../src/agui/encoder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAmB,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kPAAkP;IAClP,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,8FAA8F;IAC9F,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAOD;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,iBAAiB,GAAG,SAAS,GAAG,IAAI,CAAC;CAC3E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,CAqG/C"}

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/encoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.js","sourceRoot":"","sources":["../../src/agui/encoder.ts"],"names":[],"mappings":"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"}

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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/agui/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,WAAW,GACX,cAAc,GACd,sBAAsB,GACtB,sBAAsB,GACtB,eAAe,CAAC;AAEpB,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,qBAAsB,SAAQ,aAAa;IAC1D,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,yBAA0B,SAAQ,aAAa;IAC9D,IAAI,EAAE,sBAAsB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,QAAQ,GAAG,cAAc,GAAG,cAAc,CAAC;IACjE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,yBAA0B,SAAQ,aAAa;IAC9D,IAAI,EAAE,sBAAsB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;CAClD;AAED,MAAM,WAAW,qBAAsB,SAAQ,aAAa;IAC1D,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,SAAS,GAAG,wBAAwB,GAAG,0BAA0B,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC;IACjH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,SAAS,GACjB,qBAAqB,GACrB,iBAAiB,GACjB,oBAAoB,GACpB,yBAAyB,GACzB,yBAAyB,GACzB,qBAAqB,CAAC"}

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/agui/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/agui/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}