@adonis-agora/agent 0.54.0 → 0.56.0

package/dist/src/ag-ui/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/ag-ui/adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAuB,MAAM,4BAA4B,CAAC;AAevF,MAAM,WAAW,kBAAkB;IACjC,+FAA+F;IAC/F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAcD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,eAAe,CA+I7E"}

package/dist/src/ag-ui/adapter.js

@@ -0,0 +1,295 @@
+import { parseRunInput, planResume, readAnswersPayload, readApprovalPayload, readContext, readForwardedProps, readUserTurn, } from './input.js';
+import { agUiEvents, agUiSse } from './stream.js';
+import { AG_UI_CUSTOM } from './types.js';
+/** The surface an AG-UI resume decision is recorded as having come through. */
+const AG_UI_VIA = 'ag-ui';
+/** Input material the route could not use, as the events that say so. */
+function warningEvents(warnings) {
+    return warnings.map((message) => ({
+        type: 'CUSTOM',
+        name: AG_UI_CUSTOM.warning,
+        value: { message },
+    }));
+}
+/**
+ * Serve the agent over AG-UI 1.0 (https://docs.ag-ui.com/spec/1.0): the body of `POST <path>/ag-ui`
+ * is a `RunAgentInput`, the answer the run as AG-UI events. A run that stops to ask ends with the
+ * interrupt outcome and is continued by a later request carrying `resume`.
+ *
+ * ```ts
+ * import { agUiAdapter } from '@adonis-agora/agent/ag-ui'
+ *
+ * export default defineConfig({ adapters: [agUiAdapter()] })
+ * ```
+ *
+ * Authenticated and owner-scoped exactly as `chat`, `chat/:runId/stream` and the decision routes
+ * are: it goes through the gates the provider hands every adapter.
+ */
+export function agUiAdapter(options = {}) {
+    const path = (options.path ?? 'ag-ui').replace(/^\/+|\/+$/g, '');
+    const quietMs = options.quietMs;
+    return {
+        name: 'ag-ui',
+        mount(host) {
+            const { service } = host;
+            const staging = host.attachments;
+            host.post(path, async (ctx) => {
+                const input = parseRunInput(ctx.request.body());
+                if (typeof input === 'string') {
+                    return ctx.response.badRequest({ message: input, code: 'invalid_input' });
+                }
+                const forwarded = readForwardedProps(input.forwardedProps);
+                const agentName = forwarded.agent ?? host.defaultAgentName;
+                const actor = await host.resolveActor(ctx, agentName);
+                if (actor === null)
+                    return;
+                const warnings = [];
+                if (Array.isArray(input.tools) && input.tools.length > 0) {
+                    warnings.push('Frontend tools are not supported by this agent: the tools list was ignored.');
+                }
+                if (input.resume !== undefined && input.resume.length > 0) {
+                    const plan = planResume(input.resume);
+                    if (typeof plan === 'string') {
+                        return ctx.response.badRequest({ message: plan, code: 'invalid_resume' });
+                    }
+                    for (const id of plan.unrecognised) {
+                        warnings.push(`The resume entry ${id} answers an interrupt this agent did not raise.`);
+                    }
+                    const first = plan.decisions[0];
+                    // A list that answers nothing this agent asked continues nothing: an ordinary run.
+                    if (first !== undefined) {
+                        const streamRunId = first.address.stream;
+                        const owner = await service.runOwner(streamRunId);
+                        if (!(await host.assertOwner(ctx, actor, owner, 'run')))
+                            return;
+                        if (!(await service.hasStream(streamRunId))) {
+                            return ctx.response.conflict({
+                                code: 'run_not_active',
+                                message: 'The interrupted run is no longer waiting.',
+                            });
+                        }
+                        if (!(await settleResume(host, ctx, actor, plan.decisions))) {
+                            return;
+                        }
+                        await pipe(ctx, service, streamRunId, {
+                            threadId: input.threadId,
+                            runId: input.runId,
+                            streamRunId,
+                            skip: first.address.position,
+                            answered: plan.decisions.map((decision) => decision.address.toolCallId),
+                            ...(quietMs !== undefined ? { quietMs } : {}),
+                            preamble: warningEvents(warnings),
+                        });
+                        return;
+                    }
+                }
+                const turn = readUserTurn(input.messages);
+                if (turn === null) {
+                    return ctx.response.badRequest({
+                        message: 'messages carries no user message to answer',
+                        code: 'no_user_message',
+                    });
+                }
+                warnings.push(...turn.dropped);
+                // The consumer names the conversation. A thread it already has is continued (its owner
+                // checked, as on `chat`); one nobody has is created under that name.
+                const owner = await service.threadOwner(input.threadId);
+                if (owner !== null) {
+                    if (!(await host.assertOwner(ctx, actor, owner, 'thread')))
+                        return;
+                }
+                const refs = [];
+                for (const media of turn.media) {
+                    const label = `The ${media.kind} "${media.filename}" was not used`;
+                    if (staging === undefined) {
+                        warnings.push(`${label}: attachments are not enabled on this agent.`);
+                    }
+                    else if (refs.length >= staging.maxPerMessage) {
+                        warnings.push(`${label}: a message carries at most ${staging.maxPerMessage} attachments.`);
+                    }
+                    else if (!staging.allowedContentTypes.includes(media.contentType)) {
+                        warnings.push(`${label}: ${media.contentType} is not an accepted type.`);
+                    }
+                    else if (media.data.length > staging.maxBytes) {
+                        warnings.push(`${label}: it is larger than ${staging.maxBytes} bytes.`);
+                    }
+                    else {
+                        try {
+                            const staged = await staging.store.stage({
+                                data: media.data,
+                                filename: media.filename,
+                                contentType: media.contentType,
+                                sizeBytes: media.data.length,
+                                actor,
+                            });
+                            refs.push({ mediaId: staged.mediaId });
+                        }
+                        catch {
+                            warnings.push(`${label}: it could not be stored.`);
+                        }
+                    }
+                }
+                if (turn.text.trim().length === 0 && refs.length === 0) {
+                    return ctx.response.badRequest({
+                        message: 'the user message to answer is empty',
+                        code: 'no_user_message',
+                    });
+                }
+                const context = readContext(input.context);
+                const pageContext = forwarded.pageContext !== undefined || context !== undefined
+                    ? {
+                        ...forwarded.pageContext,
+                        ...(context !== undefined ? { agUiContext: context } : {}),
+                    }
+                    : undefined;
+                let started;
+                try {
+                    started = await service.chat({
+                        actor,
+                        message: turn.text,
+                        ...(owner !== null ? { threadId: input.threadId } : { newThreadId: input.threadId }),
+                        ...(forwarded.agent !== undefined ? { agentName: forwarded.agent } : {}),
+                        ...(forwarded.model !== undefined ? { model: forwarded.model } : {}),
+                        ...(forwarded.persona !== undefined ? { personaId: forwarded.persona } : {}),
+                        ...(pageContext !== undefined ? { pageContext } : {}),
+                        ...(refs.length > 0 ? { attachments: refs } : {}),
+                    });
+                }
+                catch (error) {
+                    if (host.refuseSend(ctx, error))
+                        return;
+                    throw error;
+                }
+                await pipe(ctx, service, started.runId, {
+                    threadId: input.threadId,
+                    runId: input.runId,
+                    streamRunId: started.runId,
+                    streamThreadId: started.threadId,
+                    ...(quietMs !== undefined ? { quietMs } : {}),
+                    preamble: warningEvents(warnings),
+                });
+            });
+        },
+    };
+}
+/**
+ * Deliver what a resume list decided, through the same calls the native decision routes make.
+ * Everything that can refuse — who may decide, an answer a question's rules reject, a payload that
+ * says nothing — is checked for EVERY entry before the first one is delivered, so a list with one
+ * bad entry settles nothing. Answers `false` after writing the refusal.
+ */
+async function settleResume(host, ctx, actor, decisions) {
+    const { service } = host;
+    const deliveries = [];
+    for (const { address, entry } of decisions) {
+        const { parked, toolCallId } = address;
+        const abandoned = entry.status === 'cancelled';
+        if (address.kind === 'approval') {
+            if (!(await host.mayDecide(ctx, actor, parked, toolCallId))) {
+                return false;
+            }
+            const decision = abandoned ? { approved: false } : readApprovalPayload(entry.payload);
+            if (decision === null) {
+                ctx.response.badRequest({
+                    code: 'invalid_resume',
+                    message: 'an approval is answered with { approved: boolean, reason?, remember? }',
+                });
+                return false;
+            }
+            deliveries.push(() => decision.approved
+                ? service.approve(parked, toolCallId, {
+                    executedByRef: actor.id,
+                    via: AG_UI_VIA,
+                    ...(decision.remember !== undefined ? { remember: decision.remember } : {}),
+                })
+                : service.reject(parked, toolCallId, decision.reason ?? (abandoned ? 'abandoned' : undefined), {
+                    executedByRef: actor.id,
+                    via: AG_UI_VIA,
+                }));
+            continue;
+        }
+        const owner = await service.runOwner(parked);
+        if (!(await host.assertOwner(ctx, actor, owner, 'run')))
+            return false;
+        if (abandoned) {
+            deliveries.push(() => service.skip({
+                runId: parked,
+                toolCallId,
+                answeredByRef: actor.id,
+                answeredVia: AG_UI_VIA,
+            }));
+            continue;
+        }
+        const answers = readAnswersPayload(entry.payload);
+        if (answers === null) {
+            ctx.response.badRequest({
+                code: 'invalid_resume',
+                message: 'a question set is answered with { answers: { <questionId>: string[] } }',
+            });
+            return false;
+        }
+        const problem = await service.answerProblem(toolCallId, answers);
+        if (problem !== null) {
+            ctx.response.badRequest({ code: 'invalid_resume', message: problem });
+            return false;
+        }
+        deliveries.push(() => service.answer({
+            runId: parked,
+            toolCallId,
+            answers,
+            answeredByRef: actor.id,
+            answeredVia: AG_UI_VIA,
+        }));
+    }
+    try {
+        for (const deliver of deliveries)
+            await deliver();
+    }
+    catch (error) {
+        host.conflictOnMismatch(ctx, error);
+        return false;
+    }
+    return true;
+}
+/**
+ * Pipe a run to the client as AG-UI 1.0 over SSE: one event per `data:` line, from `RUN_STARTED` to
+ * the run's terminal event. It ends when the run stops to ask — the library run stays parked, and
+ * the request that answers re-attaches to it.
+ */
+async function pipe(ctx, service, runId, options) {
+    const raw = ctx.response.response;
+    const headers = {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache, no-transform',
+        Connection: 'keep-alive',
+        'X-Accel-Buffering': 'no',
+        'X-Agent-Run-Id': runId,
+    };
+    const pending = ctx.response.getHeaders();
+    for (const [name, value] of Object.entries(pending)) {
+        if (value !== undefined && !(name in headers))
+            raw.setHeader(name, value);
+    }
+    raw.writeHead(200, headers);
+    let terminal = false;
+    try {
+        for await (const event of agUiEvents(service.subscribe(runId), options)) {
+            if (event.type === 'RUN_FINISHED' || event.type === 'RUN_ERROR')
+                terminal = true;
+            raw.write(agUiSse(event));
+        }
+    }
+    catch {
+        // The stream under the run broke. The status line is long gone, so the failure travels
+        // in-stream — and says nothing of what broke, which is the server's to know.
+        if (!terminal) {
+            raw.write(agUiSse({
+                type: 'RUN_ERROR',
+                message: 'The run could not be followed.',
+                code: 'run_failed',
+            }));
+        }
+    }
+    raw.end();
+}
+//# sourceMappingURL=adapter.js.map

package/dist/src/ag-ui/adapter.js.map

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

package/dist/src/ag-ui/encoder.d.ts

@@ -0,0 +1,107 @@
+import type { StreamFrame } from '../spi/token-stream-sink.js';
+import { type AgUiEvent } from './types.js';
+export interface AgUiEncoderOptions {
+    /** The ids the consumer sent on `RunAgentInput`: every boundary event echoes them. */
+    threadId: string;
+    runId: string;
+    /** The library run whose stream is being projected (it mints interrupt ids and the `agora.run` event). */
+    streamRunId: string;
+    /** The library's thread id, when it differs from what the consumer calls the thread. */
+    streamThreadId?: string;
+    /**
+     * Frames of the library run's stream that an earlier AG-UI run already delivered (a resume). They
+     * are fed to the encoder like any other — it has to know what they opened — but produce no events.
+     */
+    skip?: number;
+    /**
+     * Tool calls a resuming request just answered. The run has not necessarily said so yet — a parked
+     * run takes a moment to wake — so without this the encoder would read them as still waiting and
+     * report the interrupt again before the answer had any effect.
+     */
+    answered?: readonly string[];
+    /** Model id for the usage entry when the step frames carry none. */
+    model?: string;
+}
+/**
+ * Projects one library run's stream ({@link StreamFrame}s, in buffer order) onto AG-UI 1.0 events.
+ *
+ * A pure state machine: the same frames always give the same events, which is what lets a resuming
+ * request — served by any replica — replay the run's buffer, skip what the interrupted AG-UI run
+ * already delivered, and continue. It writes nothing itself; {@link agUiEvents} drives it and
+ * decides when the run has stopped to ask.
+ *
+ * What maps where:
+ *  - `text` → `TEXT_MESSAGE_*` (one message per stretch of text);
+ *  - `reasoning` → a reasoning span with one reasoning message;
+ *  - `step-start`/`step-finish` → `STEP_STARTED`/`STEP_FINISHED`, the step's usage folded into the
+ *    run's `usage`;
+ *  - `tool-input-*` → `TOOL_CALL_START`/`ARGS`/`END`; `tool-output*` → `TOOL_CALL_RESULT`;
+ *  - an approval or a question set the run parks on → an `Interrupt` on the closing `RUN_FINISHED`;
+ *  - `cancelled` → the cancelled outcome; an error frame → `RUN_ERROR`;
+ *  - generative UI, title, queue and the native approval/elicitation frames → `CUSTOM` events named
+ *    in {@link AG_UI_CUSTOM}, for what AG-UI has no event for.
+ *
+ * Not mapped: sub-agent attribution (`subagentRunId`) — a delegated agent's frames are projected
+ * flat, as the protocol allows of a producer that does not attribute.
+ */
+export declare class AgUiEncoder {
+    private readonly options;
+    private position;
+    private started;
+    private closed;
+    private cancelled;
+    private crossed;
+    private messageSeq;
+    private stepSeq;
+    private openText;
+    private openReasoning;
+    /** The last text message of the current step: a tool call attaches to it. */
+    private stepMessage;
+    private readonly openSteps;
+    private readonly calls;
+    private readonly pending;
+    private readonly usage;
+    constructor(options: AgUiEncoderOptions);
+    /** How many frames of the library stream this encoder has consumed. */
+    get consumed(): number;
+    /** The run is waiting on at least one approval or question set nobody has settled yet. */
+    get waiting(): boolean;
+    /**
+     * Is anything still in flight that is NOT waiting on a person — a tool call announced and neither
+     * answered nor parked? While there is, more frames are coming without anyone's help.
+     */
+    get busy(): boolean;
+    /** `RUN_STARTED`, and the library's own ids for the run. Call once, before the first frame. */
+    start(): AgUiEvent[];
+    /** The AG-UI events the next frame of the library stream stands for (possibly none). */
+    encode(frame: StreamFrame): AgUiEvent[];
+    /**
+     * The replayed frames are behind us: from here on events are written. The AG-UI run that delivered
+     * them closed everything it had open before it finished, so this run starts with nothing open, and
+     * what the resuming request answered is no longer waiting.
+     */
+    private crossBoundary;
+    private get replaying();
+    private project;
+    private event;
+    /**
+     * The events that end the AG-UI run: whatever is still open is closed first, then `RUN_FINISHED`
+     * with how it ended — interrupted when the run is waiting on someone, cancelled when it was
+     * stopped, success otherwise. Nothing after a `RUN_ERROR`. `ended` says the library run's stream
+     * itself ended, rather than this reader having stopped following it.
+     */
+    finish(ended?: boolean): AgUiEvent[];
+    private interrupts;
+    private custom;
+    private nextMessageId;
+    private textDelta;
+    private reasoningDelta;
+    private closeText;
+    private closeReasoning;
+    private closeStreams;
+    private callStart;
+    private result;
+    private addUsage;
+    private usageEntries;
+}
+//# sourceMappingURL=encoder.d.ts.map

package/dist/src/ag-ui/encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.d.ts","sourceRoot":"","sources":["../../../src/ag-ui/encoder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAI/D,OAAO,EAGL,KAAK,SAAS,EAGf,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,kBAAkB;IACjC,sFAAsF;IACtF,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,0GAA0G;IAC1G,WAAW,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA0DD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,WAAW;IAiBV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhBpC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,aAAa,CAAqB;IAC1C,6EAA6E;IAC7E,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAE3D,YAA6B,OAAO,EAAE,kBAAkB,EAAI;IAE5D,uEAAuE;IACvE,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,0FAA0F;IAC1F,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;OAGG;IACH,IAAI,IAAI,IAAI,OAAO,CAKlB;IAED,+FAA+F;IAC/F,KAAK,IAAI,SAAS,EAAE,CAmBnB;IAED,wFAAwF;IACxF,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,EAAE,CAgBtC;IAED;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAarB,OAAO,KAAK,SAAS,GAEpB;IAED,OAAO,CAAC,OAAO;IA+Ef,OAAO,CAAC,KAAK;IAgHb;;;;;OAKG;IACH,MAAM,CAAC,KAAK,UAAQ,GAAG,SAAS,EAAE,CA+BjC;IAED,OAAO,CAAC,UAAU;IAalB,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,SAAS;IAYjB,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,MAAM;IA0Bd,OAAO,CAAC,QAAQ;IAsBhB,OAAO,CAAC,YAAY;CAGrB"}