@adonis-agora/agent 0.62.0 → 0.64.0

package/dist/src/channels/handler.d.ts

@@ -0,0 +1,190 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import { type TextActionProposalVocabulary } from '../action-proposal-text.js';
+import { AgentService } from '../agent-service.js';
+import type { AttachmentLimits } from '../attachment-limits.js';
+import type { ActionProposal } from '../spi/action-proposal-store.js';
+import type { ToolConfirmation } from '../tool-presentation.js';
+import type { Actor, PageContext } from '../types.js';
+import { type ChannelQuestionTexts } from './questions.js';
+import { type ChannelStore } from './store.js';
+import type { ChannelAdapter, InboundMedia, InboundMessage } from './types.js';
+/**
+ * What a channel turn needs from the agent — `AgentService` is one. The optional methods turn
+ * features on: proposals (buttons, outcomes), questions (`answer`), media (`stageAttachment`), and
+ * the Lucid default store (`lucidDatabase`).
+ */
+export interface ChannelTurnService extends Pick<AgentService, 'send' | 'subscribe' | 'skip' | 'cancel' | 'actionProposalReply'>, Partial<Pick<AgentService, 'decideActionProposal' | 'listActionProposals' | 'actionProposalVocabulary' | 'actionApprovalMode' | 'answer' | 'attachmentLimits' | 'stageAttachment' | 'lucidDatabase'>> {
+}
+/** A proposal the turn left pending, as the channel puts it to the person. */
+export interface ChannelProposal {
+    id: string;
+    toolName: string;
+    confirmation?: ToolConfirmation;
+}
+/** Why a media message could not be attached. */
+export type ChannelMediaRefusal = 'disabled' | 'type' | 'size' | 'failed';
+/**
+ * Everything the channel says on its own (not the model). English by default, Brazilian Portuguese
+ * ({@link ptBrChannelTexts}) when the agent's `actionProposalText` is `ptBrActionProposalText`;
+ * override any.
+ */
+export interface ChannelTexts {
+    /** The Confirm button's label. */
+    approve: string;
+    /** The Cancel button's label. */
+    reject: string;
+    /** What a proposal says above its buttons — default: its confirmation's bold title and detail. */
+    proposal(proposal: ChannelProposal): string;
+    /**
+     * How to answer a proposal by text, when there are no buttons. `approve`/`reject` are the reply
+     * commands, built from the configured `actionProposalText.vocabulary` — `#ID` included when more
+     * than one proposal is waiting.
+     */
+    instruction(commands: {
+        approve: string;
+        reject: string;
+    }): string;
+    /** An approval in blocking mode, which a text channel cannot settle. */
+    blockingApproval: string;
+    /** The turn failed. */
+    failed: string;
+    /** An approved action ran, and presented nothing the channel could show. */
+    actionSucceeded: string;
+    /** An approved action's execution failed. */
+    actionFailed: string;
+    /** A file that could not be attached — no attachment store, a type or size it refuses, a failed download. */
+    mediaRefused(reason: ChannelMediaRefusal, media: InboundMedia, limits: AttachmentLimits | null): string;
+    /** How questions (the `ask` tool, intakes) are worded. */
+    questions: ChannelQuestionTexts;
+    /** Answer a sender `actor()` maps to nobody. Omitted → say nothing. */
+    unknownSender?: string;
+}
+export declare const DEFAULT_CHANNEL_TEXTS: ChannelTexts;
+/**
+ * Brazilian Portuguese channel texts — the default when the agent's `actionProposalText` is
+ * `ptBrActionProposalText`, so the reply words and what the channel says agree.
+ */
+export declare const ptBrChannelTexts: ChannelTexts;
+/**
+ * The channel texts that speak the language of the agent's text-decision words: {@link
+ * ptBrChannelTexts} for `ptBrActionProposalText` (or any vocabulary whose `language` is Portuguese),
+ * else {@link DEFAULT_CHANNEL_TEXTS}.
+ */
+export declare function channelTextsFor(vocabulary?: TextActionProposalVocabulary | null): ChannelTexts;
+/**
+ * `texts` as `channels.handle` takes it: any part, `questions` too — over the texts in the language of
+ * the agent's `actionProposalText` (see {@link channelTextsFor}).
+ */
+export type ChannelTextsOverrides = Partial<Omit<ChannelTexts, 'questions'>> & {
+    questions?: Partial<ChannelQuestionTexts>;
+};
+export interface ChannelHandleOptions {
+    /**
+     * The account the sender is — from `message.from` (a phone number, a Telegram id). `null` → the
+     * message is not answered (or answered with `texts.unknownSender`). This IS the authentication of
+     * every message, so map only senders the channel itself vouches for.
+     */
+    actor(message: InboundMessage): Actor | null | Promise<Actor | null>;
+    /**
+     * The thread this conversation continues; `null`/`undefined` → a new one, reported to
+     * {@link onThreadCreated} so you can store it.
+     */
+    thread(actor: Actor, message: InboundMessage): string | null | undefined | Promise<string | null | undefined>;
+    /** A new thread was created for the conversation — remember it for {@link thread}. */
+    onThreadCreated?(threadId: string, actor: Actor, message: InboundMessage): void | Promise<void>;
+    /**
+     * The turn's page context. Default `{ kind: adapter.name }`. The handler adds `channel: { name,
+     * conversation }` to it — what a proposal's outcome is routed back by.
+     */
+    pageContext?: PageContext | ((message: InboundMessage) => PageContext);
+    /** The agent that answers. Default: the thread's, else the configured default. */
+    agentName?: string;
+    /** The agent service. Default: `AgentService` from the container. */
+    service?: ChannelTurnService;
+    /**
+     * Where the channel's short-lived state lives: message ids already taken, questions waiting for an
+     * answer, outcomes already relayed. Default: `lucidChannelStore()` over the agent store's database
+     * when the agent store is Lucid, else this process's memory.
+     */
+    store?: ChannelStore;
+    /** How long a message id is remembered. Default 24 h. */
+    dedupeTtlMs?: number;
+    /** Stop waiting for a turn after this long (and cancel it). Default 5 minutes. */
+    timeoutMs?: number;
+    /**
+     * After a proposal is approved, wait this long for it to execute and relay its outcome. `0` → do
+     * not wait (the decision reply is all the person gets; `channels.onSettled` can still relay it).
+     * Default 60 s.
+     */
+    outcomeTimeoutMs?: number;
+    /** How long a question waits for its answer before the agent proceeds without it. Default 30 min. */
+    questionTimeoutMs?: number;
+    /**
+     * What the channel says on its own. Omitted parts come from {@link channelTextsFor}: Brazilian
+     * Portuguese when the agent's `actionProposalText` is `ptBrActionProposalText`, else English.
+     */
+    texts?: ChannelTextsOverrides;
+    /** A message whose handling failed. Default: `console.error`. */
+    onError?(error: unknown, message: InboundMessage): void;
+}
+/** The route handler `channels.handle()` returns. */
+export interface ChannelRouteHandler {
+    (ctx: HttpContext): Promise<void>;
+    /** Resolves once every turn this handler started has been answered — for tests and shutdown. */
+    drain(): Promise<void>;
+}
+/** The button ids for a proposal: what {@link ChannelRouteHandler} maps back to its decision. */
+export declare function proposalButtonIds(proposalId: string): {
+    approve: string;
+    reject: string;
+};
+/** Where a turn's output goes back to — `pageContext.channel`, recorded with every proposal. */
+export interface ChannelAddress {
+    name: string;
+    conversation: string;
+}
+/**
+ * The webhook route for one channel. Each request is verified (`401` when it is not the provider's),
+ * parsed, deduplicated by the provider's message id, and acknowledged with `200` at once; the turn
+ * runs after the response, so a slow model never makes the provider retry. Then:
+ *
+ * - media are downloaded and attached (held to the attachment store's limits), or refused with a text;
+ * - the message is sent with text-only capabilities (components arrive as their `fallbackText`);
+ *   a text decision ("yes", "confirm #ID") is answered with its reply instead of starting a turn;
+ * - a press on a proposal's button decides that proposal (`via` = the adapter's name);
+ * - a question the turn asks is sent as text, one at a time, and the next messages answer it;
+ * - the reply is converted to the channel's markdown, split at its length limit, and sent;
+ * - a proposal the turn left pending is sent with Confirm/Cancel buttons — or, on a channel without
+ *   them, with a text instruction in the configured `actionProposalText` vocabulary;
+ * - an approved proposal's outcome is relayed once it executed (see `outcomeTimeoutMs`, and
+ *   `channels.onSettled` for one that runs later).
+ *
+ * Wants `actionApprovalMode: 'independent'`: a blocking approval holds the turn open until someone
+ * decides it in the app, so the channel sends what it has and `texts.blockingApproval`.
+ *
+ * Registers the adapter under its `name` for `channels.onSettled` — names must be unique.
+ */
+export declare function handleChannel(adapter: ChannelAdapter, options: ChannelHandleOptions): ChannelRouteHandler;
+/**
+ * `actionProposalWorker.onSettled` for text channels: relays an executed proposal's outcome to the
+ * conversation it was proposed in, through the adapter registered under the recorded channel name.
+ * Proposals from other surfaces are ignored. Safe next to the handler's own wait: an outcome is
+ * relayed once.
+ *
+ * ```ts
+ * // config/agent.ts
+ * actionProposalWorker: { onSettled: channels.onSettled }
+ * ```
+ */
+export declare function relayChannelOutcome(proposal: ActionProposal): Promise<void>;
+export declare const channels: {
+    /** See {@link handleChannel}. */
+    handle: typeof handleChannel;
+    /** See {@link relayChannelOutcome}. */
+    onSettled: typeof relayChannelOutcome;
+    /** Relay one proposal's outcome now; `true` when it was sent. */
+    deliverOutcome: (proposal: ActionProposal, service?: ChannelTurnService) => Promise<boolean>;
+    /** The adapter registered under `name` (by `channels.handle`), if any. */
+    adapter: (name: string) => ChannelAdapter | undefined;
+};
+//# sourceMappingURL=handler.d.ts.map

package/dist/src/channels/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/channels/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAGL,KAAK,4BAA4B,EAClC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,YAAY,EAA0B,MAAM,qBAAqB,CAAC;AAC3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAGtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGtD,OAAO,EACL,KAAK,oBAAoB,EAK1B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,KAAK,YAAY,EAA2C,MAAM,YAAY,CAAC;AACxF,OAAO,KAAK,EACV,cAAc,EAEd,YAAY,EACZ,cAAc,EAEf,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,MAAM,WAAW,kBACf,SAAQ,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,qBAAqB,CAAC,EAC1F,OAAO,CACL,IAAI,CACF,YAAY,EACV,sBAAsB,GACtB,qBAAqB,GACrB,0BAA0B,GAC1B,oBAAoB,GACpB,QAAQ,GACR,kBAAkB,GAClB,iBAAiB,GACjB,eAAe,CAClB,CACF;CAAG;AAER,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACjC;AAED,iDAAiD;AACjD,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE1E;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,kGAAkG;IAClG,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAAC;IAC5C;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC;IACnE,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,CAAC;IACzB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,eAAe,EAAE,MAAM,CAAC;IACxB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,6GAA6G;IAC7G,YAAY,CACV,MAAM,EAAE,mBAAmB,EAC3B,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,gBAAgB,GAAG,IAAI,GAC9B,MAAM,CAAC;IACV,0DAA0D;IAC1D,SAAS,EAAE,oBAAoB,CAAC;IAChC,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAQD,eAAO,MAAM,qBAAqB,EAAE,YAuBnC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAwB9B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,CAAC,EAAE,4BAA4B,GAAG,IAAI,GAAG,YAAY,CAM9F;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC,GAAG;IAC7E,SAAS,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC3C,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IACrE;;;OAGG;IACH,MAAM,CACJ,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,cAAc,GACtB,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAClE,sFAAsF;IACtF,eAAe,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChG;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,GAAG,CAAC,CAAC,OAAO,EAAE,cAAc,KAAK,WAAW,CAAC,CAAC;IACvE,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qGAAqG;IACrG,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,KAAK,CAAC,EAAE,qBAAqB,CAAC;IAC9B,iEAAiE;IACjE,OAAO,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;CACzD;AAED,qDAAqD;AACrD,MAAM,WAAW,mBAAmB;IAClC,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,gGAAgG;IAChG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAWD,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAGzF;AAED,gGAAgG;AAChG,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAgHD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,oBAAoB,GAC5B,mBAAmB,CA+erB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjF;AAED,eAAO,MAAM,QAAQ;IACnB,iCAAiC;IACjC,MAAM;IACN,uCAAuC;IACvC,SAAS;IACT,iEAAiE;IACjE,cAAc,aAAa,cAAc,YAAY,kBAAkB;IAEvE,0EAA0E;IAC1E,OAAO,SAAS,MAAM,KAAG,cAAc,GAAG,SAAS;CACpD,CAAC"}