@loomweaver/ag-ui 0.7.2

package/README.md

@@ -0,0 +1,47 @@
+# @loomweaver/ag-ui
+
+Describes the workbench's own commands to an [AG-UI](https://docs.ag-ui.com) agent and runs what it
+asks for, so a weaver keeps no tool registry of its own.
+
+```ts
+import { commandTools } from '@loomweaver/ag-ui';
+
+const tools = commandTools(ctx);
+
+// when a run starts
+agent.runAgent({ tools: tools.list(), ...rest });
+
+// for every event the run produces
+const answer = await tools.receive(event);
+if (answer) messages.push(answer);
+```
+
+That is the whole integration. The actions the agent can reach are the ones the workbench already
+knows about, narrowed by everything that would refuse them — so an agent reaches what the user could
+have reached, and nothing more.
+
+## What it does not do
+
+- **No transport.** Opening a connection, choosing SSE or a socket, retrying and authenticating are
+  yours.
+- **No user interface.** Not a chat, not a message list, not a rendering of anything.
+- **No agent.** It never decides what to do; it carries what was decided.
+- **No shared state, reasoning display or subagent handling.** Those events pass by untouched.
+
+It is headless and framework-neutral: no Angular, no observables. You bring the stream and hand it
+one event at a time.
+
+## Stability
+
+**This package's stability follows AG-UI, not the platform.** It shares a version number with the
+other `@loomweaver/*` packages because they are released together, and that number says which platform
+release it was built against. It says nothing about the protocol, which is at `0.0.x` and still
+moving. A break there is answered by publishing at the next platform version.
+
+`@ag-ui/core` and `@loomweaver/plugin-sdk` are peer dependencies, so a weaver that also builds its own
+agent resolves one copy of each rather than two.
+
+## Documentation
+
+The full guide, including the hook that lets you confirm or decline a call before it runs, is at
+[docs/reference/agent-tools.md](https://github.com/yesbert/loomweaver/blob/main/docs/reference/agent-tools.md).

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@loomweaver/ag-ui",
+  "version": "0.7.2",
+  "description": "LoomWeaver AG-UI adapter: describes the workbench's own commands to an agent and runs what it asks for, so a weaver keeps no tool registry of its own. Headless — no transport, no UI, no agent.",
+  "keywords": [
+    "loomweaver",
+    "ag-ui",
+    "agent",
+    "agentic-ui",
+    "tool-calling",
+    "plugin-platform"
+  ],
+  "license": "Apache-2.0",
+  "author": "Norbert Rosenwinkel (https://loomweaver.dev)",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "peerDependencies": {
+    "@ag-ui/core": "0.0.x",
+    "@loomweaver/plugin-sdk": "0.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://loomweaver.dev",
+  "bugs": {
+    "url": "https://github.com/yesbert/loomweaver/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yesbert/loomweaver.git",
+    "directory": "platform/libs/integrations/ag-ui"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,4 @@
+export { commandTools, type CommandAccess, type CommandToolOptions, type CommandTools, type PendingToolCall, type ToolDecision, } from './lib/command-tools.js';
+export { toolFor, toolsFor } from './lib/tool-definitions.js';
+export { readArguments } from './lib/tool-arguments.js';
+export { resultFor } from './lib/tool-results.js';

package/src/index.js

@@ -0,0 +1,5 @@
+export { commandTools, } from './lib/command-tools.js';
+export { toolFor, toolsFor } from './lib/tool-definitions.js';
+export { readArguments } from './lib/tool-arguments.js';
+export { resultFor } from './lib/tool-results.js';
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../libs/integrations/ag-ui/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,GAMb,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC"}

package/src/lib/command-tools.d.ts

@@ -0,0 +1,70 @@
+import { type BaseEvent, type Tool, type ToolMessage } from '@ag-ui/core';
+import type { CommandArguments, PluginContext } from '@loomweaver/plugin-sdk';
+/**
+ * The slice of a plugin context this adapter touches: what may be run, and running it. Narrower than
+ * the whole context on purpose — it says exactly what an agent reaches through here, and a plugin
+ * hands its `ctx` straight in.
+ */
+export type CommandAccess = Pick<PluginContext, 'invocableCommands' | 'invokeCommand'>;
+/** One call an agent asked for, assembled from however many events carried it. */
+export interface PendingToolCall {
+    /** The protocol's id for this call — what the answer is addressed to. */
+    readonly toolCallId: string;
+    /** The command the agent named. */
+    readonly commandId: string;
+    /** What it wants to pass, already readable as data but not yet checked against the command. */
+    readonly args: CommandArguments;
+}
+/**
+ * What a weaver decides about a call before it runs. `run` lets it through to the workbench,
+ * `decline` answers the agent that it did not run and why, and `answer` serves the call without the
+ * workbench being involved.
+ *
+ * A decision can only narrow. Letting a call through does not make it reachable: the workbench
+ * refuses what it always refused, whatever was decided here.
+ */
+export type ToolDecision = {
+    readonly decision: 'run';
+} | {
+    readonly decision: 'decline';
+    readonly reason: string;
+} | {
+    readonly decision: 'answer';
+    readonly content: string;
+};
+/** What a weaver may supply when it wants a say before a call runs. */
+export interface CommandToolOptions {
+    before?(call: PendingToolCall): ToolDecision | Promise<ToolDecision>;
+}
+/**
+ * The workbench's own actions, offered to an agent and run on its behalf.
+ *
+ * Hand every event of a run to {@link receive} and send back whatever it answers. Ask {@link list}
+ * for the tools when a run begins rather than keeping the answer: what a plugin may reach changes as
+ * plugins load and the session changes, and a list kept from earlier promises actions that are no
+ * longer there.
+ */
+export interface CommandTools {
+    /** The tools reachable right now, from the workbench's own already-narrowed account. */
+    list(): readonly Tool[];
+    /**
+     * Takes one event of the run. Answers the message to send back where the event completed a call,
+     * and nothing otherwise. Events that are not part of a tool call are ignored.
+     */
+    receive(event: BaseEvent): Promise<ToolMessage | null>;
+    /**
+     * Closes a call the agent left open, answering it if there was one. A run that ends without its
+     * closing event is the case this exists for; {@link receive} already does it when the run reports
+     * that it finished.
+     */
+    flush(): Promise<ToolMessage | null>;
+}
+/**
+ * Connects a plugin context to an agent's tool calls.
+ *
+ * The commands the workbench offers become the tools, and a call comes back through the same seam
+ * every other trigger runs through — so an agent reaches what the user could have reached, and
+ * nothing more. Nothing here opens a connection, renders anything or decides what to do; a weaver
+ * brings the stream and this carries what it says.
+ */
+export declare function commandTools(ctx: CommandAccess, options?: CommandToolOptions): CommandTools;

package/src/lib/command-tools.js

@@ -0,0 +1,107 @@
+import { __awaiter } from "tslib";
+import { EventType } from '@ag-ui/core';
+import { readArguments } from './tool-arguments.js';
+import { toolsFor } from './tool-definitions.js';
+import { answerFor, refusalFor, resultFor } from './tool-results.js';
+/**
+ * Connects a plugin context to an agent's tool calls.
+ *
+ * The commands the workbench offers become the tools, and a call comes back through the same seam
+ * every other trigger runs through — so an agent reaches what the user could have reached, and
+ * nothing more. Nothing here opens a connection, renders anything or decides what to do; a weaver
+ * brings the stream and this carries what it says.
+ */
+export function commandTools(ctx, options = {}) {
+    const open = new Map();
+    let chunked = null;
+    const finish = (call) => __awaiter(this, void 0, void 0, function* () {
+        open.delete(call.toolCallId);
+        if (chunked === call.toolCallId) {
+            chunked = null;
+        }
+        const args = readArguments(call.json);
+        if (args === null) {
+            return refusalFor(call.toolCallId, 'its arguments did not arrive as readable JSON.');
+        }
+        const decision = yield decide(options, {
+            toolCallId: call.toolCallId,
+            commandId: call.commandId,
+            args,
+        });
+        if (decision.decision === 'decline') {
+            return refusalFor(call.toolCallId, decision.reason);
+        }
+        if (decision.decision === 'answer') {
+            return answerFor(call.toolCallId, decision.content);
+        }
+        return resultFor(call.toolCallId, yield ctx.invokeCommand(call.commandId, args));
+    });
+    const flush = () => __awaiter(this, void 0, void 0, function* () {
+        const pending = [...open.values()];
+        open.clear();
+        chunked = null;
+        return pending.length === 0 ? null : finish(pending[pending.length - 1]);
+    });
+    return {
+        list: () => toolsFor(ctx.invocableCommands()),
+        flush,
+        receive: (event) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const raw = event;
+            switch (event.type) {
+                case EventType.TOOL_CALL_START:
+                    open.set(String(raw['toolCallId']), {
+                        toolCallId: String(raw['toolCallId']),
+                        commandId: String(raw['toolCallName']),
+                        json: '',
+                    });
+                    return null;
+                case EventType.TOOL_CALL_ARGS: {
+                    const call = open.get(String(raw['toolCallId']));
+                    if (call) {
+                        call.json += String((_a = raw['delta']) !== null && _a !== void 0 ? _a : '');
+                    }
+                    return null;
+                }
+                case EventType.TOOL_CALL_END: {
+                    const call = open.get(String(raw['toolCallId']));
+                    return call ? finish(call) : null;
+                }
+                case EventType.TOOL_CALL_CHUNK:
+                    return receiveChunk(raw);
+                case EventType.RUN_FINISHED:
+                case EventType.RUN_ERROR:
+                    return flush();
+                default:
+                    return null;
+            }
+        }),
+    };
+    function receiveChunk(raw) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            const id = raw['toolCallId'];
+            if (typeof id === 'string' && id !== chunked) {
+                const previous = chunked === null ? null : open.get(chunked);
+                chunked = id;
+                open.set(id, {
+                    toolCallId: id,
+                    commandId: String((_a = raw['toolCallName']) !== null && _a !== void 0 ? _a : ''),
+                    json: String((_b = raw['delta']) !== null && _b !== void 0 ? _b : ''),
+                });
+                return previous ? finish(previous) : null;
+            }
+            const call = chunked === null ? undefined : open.get(chunked);
+            if (call) {
+                call.json += String((_c = raw['delta']) !== null && _c !== void 0 ? _c : '');
+            }
+            return null;
+        });
+    }
+}
+function decide(options, call) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return options.before ? options.before(call) : { decision: 'run' };
+    });
+}
+//# sourceMappingURL=command-tools.js.map

package/src/lib/command-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-tools.js","sourceRoot":"","sources":["../../../../../../libs/integrations/ag-ui/src/lib/command-tools.ts"],"names":[],"mappings":"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"}

package/src/lib/tool-arguments.d.ts

@@ -0,0 +1,13 @@
+import type { CommandArguments } from '@loomweaver/plugin-sdk';
+/**
+ * Reads the JSON an agent streamed for one call into arguments the workbench can be handed, or
+ * `null` where it cannot be read as such.
+ *
+ * This checks only that the values can *cross*, not that they are the ones the command declared.
+ * That second check belongs to the workbench and happens there, so a call that survives this one may
+ * still be refused for naming an argument the command does not take.
+ *
+ * An empty stream of deltas reads as a call with no arguments, which is what an agent sends for a
+ * command that declares none.
+ */
+export declare function readArguments(json: string): CommandArguments | null;

package/src/lib/tool-arguments.js

@@ -0,0 +1,49 @@
+/**
+ * Reads the JSON an agent streamed for one call into arguments the workbench can be handed, or
+ * `null` where it cannot be read as such.
+ *
+ * This checks only that the values can *cross*, not that they are the ones the command declared.
+ * That second check belongs to the workbench and happens there, so a call that survives this one may
+ * still be refused for naming an argument the command does not take.
+ *
+ * An empty stream of deltas reads as a call with no arguments, which is what an agent sends for a
+ * command that declares none.
+ */
+export function readArguments(json) {
+    const text = json.trim();
+    if (text.length === 0) {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (_a) {
+        return null;
+    }
+    if (!isRecord(parsed)) {
+        return null;
+    }
+    const args = {};
+    for (const [name, value] of Object.entries(parsed)) {
+        if (isScalar(value)) {
+            args[name] = value;
+            continue;
+        }
+        if (Array.isArray(value) && value.every(isScalar)) {
+            args[name] = value;
+            continue;
+        }
+        return null;
+    }
+    return args;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isScalar(value) {
+    return (typeof value === 'string' ||
+        typeof value === 'boolean' ||
+        (typeof value === 'number' && Number.isFinite(value)));
+}
+//# sourceMappingURL=tool-arguments.js.map

package/src/lib/tool-arguments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-arguments.js","sourceRoot":"","sources":["../../../../../../libs/integrations/ag-ui/src/lib/tool-arguments.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IACzB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,WAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAA6D,EAAE,CAAC;IAC1E,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACpB,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YACnB,SAAS;QACX,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClD,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YACnB,SAAS;QACX,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,SAAS;QAC1B,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CACtD,CAAC;AACJ,CAAC"}

package/src/lib/tool-definitions.d.ts

@@ -0,0 +1,15 @@
+import type { Tool } from '@ag-ui/core';
+import type { InvocableCommand } from '@loomweaver/plugin-sdk';
+/**
+ * Describes one command the workbench offers as a tool an agent can call. The id becomes the tool
+ * name, so a call names the same identity the workbench knows it by, and nothing has to be looked up
+ * in a table on the way back.
+ *
+ * A command with no description of its own gets one derived from its title. The protocol requires a
+ * description and an agent chooses between tools by reading it, so an empty string would make the
+ * tool unpickable; the title is a poor explanation but it is not nothing, and the workbench warns the
+ * author in dev mode when a command is opened without one.
+ */
+export declare function toolFor(command: InvocableCommand): Tool;
+/** Describes every command in the list, in the order the workbench gave them. */
+export declare function toolsFor(commands: readonly InvocableCommand[]): readonly Tool[];

package/src/lib/tool-definitions.js

@@ -0,0 +1,50 @@
+const SCALAR_TYPE = {
+    text: 'string',
+    number: 'number',
+    boolean: 'boolean',
+    choice: 'string',
+};
+/**
+ * Describes one command the workbench offers as a tool an agent can call. The id becomes the tool
+ * name, so a call names the same identity the workbench knows it by, and nothing has to be looked up
+ * in a table on the way back.
+ *
+ * A command with no description of its own gets one derived from its title. The protocol requires a
+ * description and an agent chooses between tools by reading it, so an empty string would make the
+ * tool unpickable; the title is a poor explanation but it is not nothing, and the workbench warns the
+ * author in dev mode when a command is opened without one.
+ */
+export function toolFor(command) {
+    var _a;
+    return {
+        name: command.id,
+        description: (_a = command.description) !== null && _a !== void 0 ? _a : command.title,
+        parameters: parametersFor(command.arguments),
+    };
+}
+/** Describes every command in the list, in the order the workbench gave them. */
+export function toolsFor(commands) {
+    return commands.map(toolFor);
+}
+function parametersFor(args) {
+    const declared = args !== null && args !== void 0 ? args : [];
+    const properties = {};
+    for (const argument of declared) {
+        properties[argument.name] = propertyFor(argument);
+    }
+    return {
+        type: 'object',
+        properties,
+        required: declared
+            .filter((argument) => argument.required === true)
+            .map((argument) => argument.name),
+    };
+}
+function propertyFor(argument) {
+    var _a;
+    const scalar = Object.assign({ type: (_a = SCALAR_TYPE[argument.kind]) !== null && _a !== void 0 ? _a : 'string' }, (argument.kind === 'choice' ? { enum: argument.choices } : {}));
+    return argument.list === true
+        ? { type: 'array', description: argument.description, items: scalar }
+        : Object.assign(Object.assign({}, scalar), { description: argument.description });
+}
+//# sourceMappingURL=tool-definitions.js.map

package/src/lib/tool-definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-definitions.js","sourceRoot":"","sources":["../../../../../../libs/integrations/ag-ui/src/lib/tool-definitions.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,GAAqC;IACpD,IAAI,EAAE,QAAQ;IACd,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;CACjB,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,OAAO,CAAC,OAAyB;;IAC/C,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,EAAE;QAChB,WAAW,EAAE,MAAA,OAAO,CAAC,WAAW,mCAAI,OAAO,CAAC,KAAK;QACjD,UAAU,EAAE,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC;KAC7C,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,QAAQ,CAAC,QAAqC;IAC5D,OAAO,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,aAAa,CACpB,IAA4C;IAE5C,MAAM,QAAQ,GAAG,IAAI,aAAJ,IAAI,cAAJ,IAAI,GAAI,EAAE,CAAC;IAC5B,MAAM,UAAU,GAAuC,EAAE,CAAC;IAC1D,KAAK,MAAM,QAAQ,IAAI,QAAQ,EAAE,CAAC;QAChC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACpD,CAAC;IACD,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,UAAU;QACV,QAAQ,EAAE,QAAQ;aACf,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,KAAK,IAAI,CAAC;aAChD,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC;KACpC,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,QAAyB;;IAC5C,MAAM,MAAM,mBACV,IAAI,EAAE,MAAA,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,mCAAI,QAAQ,IACzC,CAAC,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAClE,CAAC;IACF,OAAO,QAAQ,CAAC,IAAI,KAAK,IAAI;QAC3B,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE;QACrE,CAAC,iCAAM,MAAM,KAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,GAAE,CAAC;AACvD,CAAC"}

package/src/lib/tool-results.d.ts

@@ -0,0 +1,18 @@
+import type { ToolMessage } from '@ag-ui/core';
+import type { CommandOutcome } from '@loomweaver/plugin-sdk';
+/**
+ * Turns what the workbench answered into the message that goes back to the agent.
+ *
+ * A refusal and a failure both land in `error`, because the protocol has one field for "this did not
+ * give you an answer" and its own reason for having it: without it, a tool that failed cannot be told
+ * from one that succeeded. The wording keeps the distinction the workbench preserved, so an agent
+ * reading it can tell "it did not run" from "it ran and broke" and choose differently.
+ *
+ * A command that declares no answer reports plainly that it ran. An empty string would read to an
+ * agent like a tool that returned nothing useful, and the usual response to that is to try again.
+ */
+export declare function resultFor(toolCallId: string, outcome: CommandOutcome): ToolMessage;
+/** The message that answers a call the adapter could not put to the workbench at all. */
+export declare function refusalFor(toolCallId: string, reason: string): ToolMessage;
+/** The message that answers a call something in front of the workbench answered itself. */
+export declare function answerFor(toolCallId: string, content: string): ToolMessage;

package/src/lib/tool-results.js

@@ -0,0 +1,40 @@
+const RAN = 'The command ran.';
+/**
+ * Turns what the workbench answered into the message that goes back to the agent.
+ *
+ * A refusal and a failure both land in `error`, because the protocol has one field for "this did not
+ * give you an answer" and its own reason for having it: without it, a tool that failed cannot be told
+ * from one that succeeded. The wording keeps the distinction the workbench preserved, so an agent
+ * reading it can tell "it did not run" from "it ran and broke" and choose differently.
+ *
+ * A command that declares no answer reports plainly that it ran. An empty string would read to an
+ * agent like a tool that returned nothing useful, and the usual response to that is to try again.
+ */
+export function resultFor(toolCallId, outcome) {
+    if (outcome.outcome === 'answered') {
+        return message(toolCallId, contentOf(outcome.value));
+    }
+    if (outcome.outcome === 'refused') {
+        return message(toolCallId, '', `The command did not run: ${outcome.message}`);
+    }
+    return message(toolCallId, '', `The command ran and failed: ${outcome.message}`);
+}
+/** The message that answers a call the adapter could not put to the workbench at all. */
+export function refusalFor(toolCallId, reason) {
+    return message(toolCallId, '', `The command did not run: ${reason}`);
+}
+/** The message that answers a call something in front of the workbench answered itself. */
+export function answerFor(toolCallId, content) {
+    return message(toolCallId, content);
+}
+function contentOf(value) {
+    if (value === undefined) {
+        return RAN;
+    }
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+function message(toolCallId, content, error) {
+    return Object.assign({ id: `tool-${toolCallId}`, role: 'tool', toolCallId,
+        content }, (error === undefined ? {} : { error }));
+}
+//# sourceMappingURL=tool-results.js.map

package/src/lib/tool-results.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-results.js","sourceRoot":"","sources":["../../../../../../libs/integrations/ag-ui/src/lib/tool-results.ts"],"names":[],"mappings":"AAGA,MAAM,GAAG,GAAG,kBAAkB,CAAC;AAE/B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CACvB,UAAkB,EAClB,OAAuB;IAEvB,IAAI,OAAO,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACnC,OAAO,OAAO,CAAC,UAAU,EAAE,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,OAAO,OAAO,CACZ,UAAU,EACV,EAAE,EACF,4BAA4B,OAAO,CAAC,OAAO,EAAE,CAC9C,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,UAAU,EAAE,EAAE,EAAE,+BAA+B,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;AACnF,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,UAAU,CAAC,UAAkB,EAAE,MAAc;IAC3D,OAAO,OAAO,CAAC,UAAU,EAAE,EAAE,EAAE,4BAA4B,MAAM,EAAE,CAAC,CAAC;AACvE,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,SAAS,CAAC,UAAkB,EAAE,OAAe;IAC3D,OAAO,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,SAAS,OAAO,CACd,UAAkB,EAClB,OAAe,EACf,KAAc;IAEd,uBACE,EAAE,EAAE,QAAQ,UAAU,EAAE,EACxB,IAAI,EAAE,MAAM,EACZ,UAAU;QACV,OAAO,IACJ,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EACzC;AACJ,CAAC"}