@dudousxd/nestjs-agent 1.28.0 → 1.29.0

package/dist/index.d.cts

@@ -7,8 +7,8 @@ export * from '@dudousxd/nestjs-agent-core';
 export { FunctionalToolDefinition } from '@dudousxd/nestjs-agent-core';
 import { A2uiOptions } from '@dudousxd/nestjs-agent-core/a2ui';
 import { Request, Response } from 'express';
-import { A as AgentService, a as ActionProposalService } from './index-C-Zo8rTL.cjs';
-export { b as A2uiAdapterOptions, c as A2uiRunHandler, d as AttachmentLimits, C as ChatParams, e as ChatSendMode, f as ChatSendResult, D as DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, g as DEFAULT_MAX_ATTACHMENT_BYTES, M as MAX_ATTACHMENTS_PER_MESSAGE, N as NO_USER_MESSAGE_CODE, Q as QueuedSend, T as ThreadDefaultAgentReader, h as ThreadModelReader, i as a2uiAdapter, j as attachmentLimits } from './index-C-Zo8rTL.cjs';
+import { A as AgentService, a as ActionProposalService } from './index-D9EM7ivO.cjs';
+export { b as A2uiAdapterOptions, c as A2uiRunHandler, d as AttachmentLimits, C as ChatParams, e as ChatSendMode, f as ChatSendResult, D as DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, g as DEFAULT_MAX_ATTACHMENT_BYTES, M as MAX_ATTACHMENTS_PER_MESSAGE, N as NO_USER_MESSAGE_CODE, Q as QueuedSend, T as ThreadDefaultAgentReader, h as ThreadModelReader, i as a2uiAdapter, j as attachmentLimits } from './index-D9EM7ivO.cjs';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 import '@dudousxd/nestjs-agent-core/genui';
@@ -33,6 +33,11 @@ interface AgUiAdapterOptions {
      * any client of AG-UI's A2UI binding — draws it. `true` maps the library builtins onto A2UI's
      * basic catalog; pass {@link A2uiOptions} for the app's own mappings or catalog. Inbound,
      * `forwardedProps.a2uiAction.userAction` is always read: the action becomes the user's turn.
+     *
+     * The basic catalog goes under the id the client advertises — `forwardedProps
+     * .a2uiClientCapabilities`, or the "A2UI catalog capabilities" context entry CopilotKit sends —
+     * and, when it advertises none, under the id AG-UI's A2UI binding uses
+     * (`A2UI_LEGACY_BASIC_CATALOG_ID`: CopilotKit 1.77, `@ag-ui/a2ui-middleware`).
      */
     a2ui?: boolean | A2uiOptions;
 }
@@ -73,6 +78,8 @@ declare class AgUiRunHandler {
     private decideProposals;
     /** Answer with a complete list of events, no run behind them. */
     private writeEvents;
+    /** A2UI for this request's client: the basic catalog under the id it advertises. Off when off. */
+    private a2uiFor;
     /**
      * 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,

package/dist/index.d.ts

@@ -7,8 +7,8 @@ export * from '@dudousxd/nestjs-agent-core';
 export { FunctionalToolDefinition } from '@dudousxd/nestjs-agent-core';
 import { A2uiOptions } from '@dudousxd/nestjs-agent-core/a2ui';
 import { Request, Response } from 'express';
-import { A as AgentService, a as ActionProposalService } from './index-CBO7egb7.js';
-export { b as A2uiAdapterOptions, c as A2uiRunHandler, d as AttachmentLimits, C as ChatParams, e as ChatSendMode, f as ChatSendResult, D as DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, g as DEFAULT_MAX_ATTACHMENT_BYTES, M as MAX_ATTACHMENTS_PER_MESSAGE, N as NO_USER_MESSAGE_CODE, Q as QueuedSend, T as ThreadDefaultAgentReader, h as ThreadModelReader, i as a2uiAdapter, j as attachmentLimits } from './index-CBO7egb7.js';
+import { A as AgentService, a as ActionProposalService } from './index-APh8WN3z.js';
+export { b as A2uiAdapterOptions, c as A2uiRunHandler, d as AttachmentLimits, C as ChatParams, e as ChatSendMode, f as ChatSendResult, D as DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, g as DEFAULT_MAX_ATTACHMENT_BYTES, M as MAX_ATTACHMENTS_PER_MESSAGE, N as NO_USER_MESSAGE_CODE, Q as QueuedSend, T as ThreadDefaultAgentReader, h as ThreadModelReader, i as a2uiAdapter, j as attachmentLimits } from './index-APh8WN3z.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 import '@dudousxd/nestjs-agent-core/genui';
@@ -33,6 +33,11 @@ interface AgUiAdapterOptions {
      * any client of AG-UI's A2UI binding — draws it. `true` maps the library builtins onto A2UI's
      * basic catalog; pass {@link A2uiOptions} for the app's own mappings or catalog. Inbound,
      * `forwardedProps.a2uiAction.userAction` is always read: the action becomes the user's turn.
+     *
+     * The basic catalog goes under the id the client advertises — `forwardedProps
+     * .a2uiClientCapabilities`, or the "A2UI catalog capabilities" context entry CopilotKit sends —
+     * and, when it advertises none, under the id AG-UI's A2UI binding uses
+     * (`A2UI_LEGACY_BASIC_CATALOG_ID`: CopilotKit 1.77, `@ag-ui/a2ui-middleware`).
      */
     a2ui?: boolean | A2uiOptions;
 }
@@ -73,6 +78,8 @@ declare class AgUiRunHandler {
     private decideProposals;
     /** Answer with a complete list of events, no run behind them. */
     private writeEvents;
+    /** A2UI for this request's client: the basic catalog under the id it advertises. Off when off. */
+    private a2uiFor;
     /**
      * 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,

package/dist/index.js

@@ -6520,6 +6520,7 @@ AgentModule = _ts_decorate27([
 
 // src/ag-ui/ag-ui.adapter.ts
 import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER15, AGENT_ATTACHMENT_STAGING as AGENT_ATTACHMENT_STAGING5, AGENT_OPTIONS as AGENT_OPTIONS11 } from "@dudousxd/nestjs-agent-core";
+import { A2UI_LEGACY_BASIC_CATALOG_ID, negotiateA2uiCatalog, readAgUiA2uiCatalogIds } from "@dudousxd/nestjs-agent-core/a2ui";
 import { AG_UI_CUSTOM, actionProposalDecisionEvents, agUiEvents, agUiFramesFromNdjson, agUiSse, parseRunInput, planResume, readAnswersPayload, readApprovalPayload, readContext, readForwardedProps, readUserTurn } from "@dudousxd/nestjs-agent-core/ag-ui";
 import { uiActionText } from "@dudousxd/nestjs-agent-core/genui";
 import { BadRequestException as BadRequestException8, Body as Body7, Controller as Controller15, ForbiddenException as ForbiddenException4, HttpCode as HttpCode2, Inject as Inject26, Optional as Optional11, Post as Post8, Req as Req14, Res as Res3 } from "@nestjs/common";
@@ -6633,6 +6634,7 @@ var AgUiRunHandler = class {
           skip: first.address.position,
           answered: plan.decisions.map((decision) => decision.address.toolCallId),
           ...quiet,
+          ...this.a2uiFor(input),
           preamble: warningEvents(warnings)
         });
         return;
@@ -6721,6 +6723,7 @@ var AgUiRunHandler = class {
       streamRunId: started.runId,
       streamThreadId: started.threadId,
       ...quiet,
+      ...this.a2uiFor(input),
       preamble: warningEvents(warnings)
     });
   }
@@ -6867,6 +6870,13 @@ var AgUiRunHandler = class {
     for (const event of events) res.write(agUiSse(event));
     res.end();
   }
+  /** A2UI for this request's client: the basic catalog under the id it advertises. Off when off. */
+  a2uiFor(input) {
+    if (this.a2ui === void 0) return {};
+    return {
+      a2ui: negotiateA2uiCatalog(this.a2ui, readAgUiA2uiCatalogIds(input), A2UI_LEGACY_BASIC_CATALOG_ID)
+    };
+  }
   /**
   * 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,
@@ -6886,12 +6896,8 @@ var AgUiRunHandler = class {
     };
     try {
       const frames = agUiFramesFromNdjson(this.agent.subscribe(runId));
-      const a2ui = this.a2ui !== void 0 ? {
-        a2ui: this.a2ui
-      } : {};
       for await (const event of agUiEvents(frames, {
         ...options,
-        ...a2ui,
         cursor
       })) {
         if (event.type === "RUN_FINISHED" || event.type === "RUN_ERROR") terminal = true;
@@ -6975,10 +6981,10 @@ __name(withCatalog, "withCatalog");
 
 // src/a2ui/a2ui.adapter.ts
 import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER16 } from "@dudousxd/nestjs-agent-core";
-import { A2UI_APPROVE_ACTION, A2UI_REJECT_ACTION, A2uiProjector, readA2uiAction } from "@dudousxd/nestjs-agent-core/a2ui";
+import { A2UI_APPROVE_ACTION, A2UI_REJECT_ACTION, A2uiProjector, a2uiThreadReplay, negotiateA2uiCatalog as negotiateA2uiCatalog2, readA2uiAction, readA2uiClientCapabilities } from "@dudousxd/nestjs-agent-core/a2ui";
 import { agUiEvents as agUiEvents2, agUiFramesFromNdjson as agUiFramesFromNdjson2, decodeInterruptId } from "@dudousxd/nestjs-agent-core/ag-ui";
 import { uiActionText as uiActionText2, validateUiCapabilities as validateUiCapabilities2 } from "@dudousxd/nestjs-agent-core/genui";
-import { BadRequestException as BadRequestException9, Body as Body8, Controller as Controller16, ForbiddenException as ForbiddenException5, HttpCode as HttpCode3, Inject as Inject27, Optional as Optional12, Post as Post9, Req as Req15, Res as Res4 } from "@nestjs/common";
+import { BadRequestException as BadRequestException9, Body as Body8, Controller as Controller16, ForbiddenException as ForbiddenException5, Get as Get13, HttpCode as HttpCode3, Inject as Inject27, Optional as Optional12, Param as Param7, Post as Post9, Query as Query7, Req as Req15, Res as Res4 } from "@nestjs/common";
 function _ts_decorate29(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
@@ -7018,6 +7024,28 @@ function invalid2(code, message) {
   });
 }
 __name(invalid2, "invalid");
+function bodyField(body, key) {
+  if (body[key] !== void 0) return body[key];
+  return isRecord(body.metadata) ? body.metadata[key] : void 0;
+}
+__name(bodyField, "bodyField");
+function readDataModel(raw, maxBytes) {
+  if (raw === void 0) return void 0;
+  if (!isRecord(raw) || !isRecord(raw.surfaces)) {
+    return "a2uiClientDataModel carries { version, surfaces }";
+  }
+  let size;
+  try {
+    size = new TextEncoder().encode(JSON.stringify(raw.surfaces)).length;
+  } catch {
+    return "a2uiClientDataModel must be JSON";
+  }
+  if (size > maxBytes) {
+    return `a2uiClientDataModel may be at most ${maxBytes} bytes (this one is ${size})`;
+  }
+  return Object.keys(raw.surfaces).length > 0 ? raw.surfaces : void 0;
+}
+__name(readDataModel, "readDataModel");
 var A2uiRunHandler = class {
   static {
     __name(this, "A2uiRunHandler");
@@ -7027,17 +7055,43 @@ var A2uiRunHandler = class {
   projection;
   quietMs;
   maxActionBytes;
-  constructor(agent, actorResolver, projection, quietMs, maxActionBytes) {
+  maxDataModelBytes;
+  constructor(agent, actorResolver, projection, quietMs, maxActionBytes, maxDataModelBytes = void 0) {
     this.agent = agent;
     this.actorResolver = actorResolver;
     this.projection = projection;
     this.quietMs = quietMs;
     this.maxActionBytes = maxActionBytes;
+    this.maxDataModelBytes = maxDataModelBytes;
+  }
+  /**
+  * `GET <path>/a2ui/threads/:threadId`: a stored thread as `{ threadId, entries }`
+  * (`a2uiThreadReplay`) — what a client draws again after a reload. Owner-scoped; a thread nobody
+  * has answers `{ entries: [] }`. `?catalog=<id>` names the client's basic catalog id.
+  */
+  async replay(req, threadId, catalog) {
+    const actor = await this.actorResolver.resolve(req);
+    const owner = await this.agent.threadOwner(threadId);
+    if (owner === null) return {
+      threadId,
+      entries: []
+    };
+    const thread = await this.agent.getThread(actor, threadId);
+    const supported = typeof catalog === "string" ? [
+      catalog
+    ] : Array.isArray(catalog) ? catalog.filter((id) => typeof id === "string") : void 0;
+    return {
+      threadId,
+      entries: a2uiThreadReplay(thread?.messages ?? [], negotiateA2uiCatalog2(this.projection, supported))
+    };
   }
   async handle(req, res, raw) {
     const body = isRecord(raw) ? raw : {};
     const agentName = typeof body.agent === "string" && body.agent.length > 0 ? body.agent : void 0;
     const actor = await this.actorResolver.resolve(req);
+    const projection = negotiateA2uiCatalog2(this.projection, readA2uiClientCapabilities(bodyField(body, "a2uiClientCapabilities")));
+    const dataModel = readDataModel(bodyField(body, "a2uiClientDataModel"), this.maxDataModelBytes ?? 32768);
+    if (typeof dataModel === "string") throw invalid2("invalid_data_model", dataModel);
     let action;
     if (body.action !== void 0) {
       const read = isRecord(body.action) ? readA2uiAction(body.action, {
@@ -7065,7 +7119,7 @@ var A2uiRunHandler = class {
         this.writeHead(res, {
           "X-Agent-Thread-Id": address.threadId
         });
-        const projector = new A2uiProjector(this.projection);
+        const projector = new A2uiProjector(projection);
         const messageId = `proposal-${address.proposalId}`;
         for (const event of [
           {
@@ -7100,7 +7154,8 @@ var A2uiRunHandler = class {
         skip: address.position,
         answered: [
           address.toolCallId
-        ]
+        ],
+        projection
       });
       return;
     }
@@ -7135,10 +7190,16 @@ var A2uiRunHandler = class {
       } : {},
       ...uiCapabilities !== void 0 ? {
         uiCapabilities
+      } : {},
+      ...dataModel !== void 0 ? {
+        pageContext: {
+          a2uiDataModel: dataModel
+        }
       } : {}
     });
     await this.stream(res, started.runId, {
-      threadId: started.threadId
+      threadId: started.threadId,
+      projection
     });
   }
   /** Open the JSON Lines response. */
@@ -7159,7 +7220,7 @@ var A2uiRunHandler = class {
         "X-Agent-Thread-Id": options.threadId
       } : {}
     });
-    const projector = new A2uiProjector(this.projection);
+    const projector = new A2uiProjector(options.projection ?? this.projection);
     const write = /* @__PURE__ */ __name((messages) => {
       for (const message of messages) res.write(`${JSON.stringify(message)}
 `);
@@ -7196,7 +7257,7 @@ var A2uiRunHandler = class {
 };
 function a2uiAdapter(options = {}) {
   const path = (options.path ?? "a2ui").replace(/^\/+|\/+$/g, "");
-  const { path: _path, quietMs, maxActionBytes, ...projection } = options;
+  const { path: _path, quietMs, maxActionBytes, maxDataModelBytes, ...projection } = options;
   let A2uiController = class A2uiController extends A2uiRunHandler {
     static {
       __name(this, "A2uiController");
@@ -7205,12 +7266,28 @@ function a2uiAdapter(options = {}) {
       super(agent, actorResolver, projection.catalog === void 0 && catalog !== void 0 ? {
         ...projection,
         catalog
-      } : projection, quietMs, maxActionBytes);
+      } : projection, quietMs, maxActionBytes, maxDataModelBytes);
+    }
+    thread(req, threadId, catalog) {
+      return this.replay(req, threadId, catalog);
     }
     run(req, res, body) {
       return this.handle(req, res, body);
     }
   };
+  _ts_decorate29([
+    Get13(`${path}/threads/:threadId`),
+    _ts_param27(0, Req15()),
+    _ts_param27(1, Param7("threadId")),
+    _ts_param27(2, Query7("catalog")),
+    _ts_metadata27("design:type", Function),
+    _ts_metadata27("design:paramtypes", [
+      typeof Request === "undefined" ? Object : Request,
+      String,
+      Object
+    ]),
+    _ts_metadata27("design:returntype", typeof ReturnType === "undefined" ? Object : ReturnType)
+  ], A2uiController.prototype, "thread", null);
   _ts_decorate29([
     Post9(path),
     HttpCode3(200),