@dudousxd/nestjs-agent 1.17.1 → 1.18.0

package/dist/index.js

@@ -950,6 +950,9 @@ var AgentService = class {
         actor: params.actor,
         ...params.transient === true ? {
           transient: true
+        } : {},
+        ...params.newThreadId !== void 0 ? {
+          id: params.newThreadId
         } : {}
       });
       threadId = created.id;
@@ -1374,6 +1377,38 @@ var AgentService = class {
     });
     throw new RunNotActiveException(runId);
   }
+  /** Who owns the thread, or `null` when there is no such (live) thread. */
+  async threadOwner(threadId) {
+    return this.store.ownerOfThread(threadId);
+  }
+  /**
+  * May `actor` continue the run whose stream is `runId` — the AG-UI resume? Only the actor whose
+  * thread is streaming it (`403` otherwise), and only while it still is: a run that is over is
+  * waiting on no one (`409 run_not_active`), whatever an old interrupt id says.
+  */
+  async assertResumable(actor, runId) {
+    const owner = await this.store.ownerOfActiveStream(runId);
+    if (owner === null) {
+      throw new RunNotActiveException(runId);
+    }
+    if (owner !== actor.id) {
+      throw new ForbiddenException("run belongs to another actor");
+    }
+  }
+  /**
+  * Everything {@link approve} / {@link reject} check before they signal — who may decide, and
+  * that the request has not lapsed — without signalling. For a caller that settles several
+  * decisions at once and must refuse all of them if one is refused (an AG-UI resume).
+  */
+  async checkDecision(actor, toolCallId2) {
+    await this.assertMayDecide(actor, toolCallId2);
+    await this.assertNotExpired(toolCallId2);
+  }
+  /** Everything {@link answer} checks before it signals, without signalling — see {@link checkDecision}. */
+  async checkAnswer(actor, toolCallId2, answers2) {
+    await this.assertOwnsToolCall(actor, toolCallId2);
+    await this.assertAnswersFit(toolCallId2, answers2);
+  }
   async cancel(actor, runId) {
     await this.assertOwnsActiveStream(actor, runId);
     return this.runner.cancel(runId);
@@ -5062,15 +5097,28 @@ var BASE_CONTROLLERS = [
   ConfigController,
   AttachmentsController
 ];
-var GUARDABLE_CONTROLLERS = BASE_CONTROLLERS;
-function controllersForSurface(surface) {
-  return surface === "engine" ? [] : BASE_CONTROLLERS;
+function adapterControllers(adapters) {
+  return (adapters ?? []).flatMap((adapter) => adapter.controllers);
+}
+__name(adapterControllers, "adapterControllers");
+function adapterProviders(adapters) {
+  return (adapters ?? []).flatMap((adapter) => adapter.providers ?? []);
+}
+__name(adapterProviders, "adapterProviders");
+function controllersForSurface(surface, adapters) {
+  return surface === "engine" ? [] : [
+    ...BASE_CONTROLLERS,
+    ...adapterControllers(adapters)
+  ];
 }
 __name(controllersForSurface, "controllersForSurface");
 var GUARDS_METADATA = "__guards__";
-function applyGuards(guards) {
+function applyGuards(guards, adapters) {
   const resolved = guards ?? [];
-  for (const controller of GUARDABLE_CONTROLLERS) {
+  for (const controller of [
+    ...BASE_CONTROLLERS,
+    ...adapterControllers(adapters)
+  ]) {
     Reflect.defineMetadata(GUARDS_METADATA, resolved, controller);
   }
 }
@@ -5096,7 +5144,7 @@ var AgentModule = class _AgentModule {
   }
   static forRoot(options) {
     const path = options.path ?? DEFAULT_PATH;
-    applyGuards(options.guards);
+    applyGuards(options.guards, options.adapters);
     return {
       module: _AgentModule,
       global: true,
@@ -5104,21 +5152,22 @@ var AgentModule = class _AgentModule {
         DiscoveryModule,
         routerFor(path)
       ],
-      controllers: controllersForSurface(options.surface),
+      controllers: controllersForSurface(options.surface, options.adapters),
       providers: [
         {
           provide: AGENT_OPTIONS7,
           useValue: options
         },
         ...sharedProviders(options.durable ?? false),
-        ...guardProviders(options.guards)
+        ...guardProviders(options.guards),
+        ...adapterProviders(options.adapters)
       ],
       exports: exportsFor()
     };
   }
   static forRootAsync(options) {
     const path = options.path ?? DEFAULT_PATH;
-    applyGuards(options.guards);
+    applyGuards(options.guards, options.adapters);
     return {
       module: _AgentModule,
       global: true,
@@ -5127,7 +5176,7 @@ var AgentModule = class _AgentModule {
         routerFor(path),
         ...options.imports ?? []
       ],
-      controllers: controllersForSurface(options.surface),
+      controllers: controllersForSurface(options.surface, options.adapters),
       providers: [
         {
           provide: AGENT_OPTIONS7,
@@ -5145,7 +5194,8 @@ var AgentModule = class _AgentModule {
           inject: options.inject ?? []
         },
         ...sharedProviders(options.durable ?? false),
-        ...guardProviders(options.guards)
+        ...guardProviders(options.guards),
+        ...adapterProviders(options.adapters)
       ],
       exports: exportsFor()
     };
@@ -5156,6 +5206,326 @@ AgentModule = _ts_decorate22([
   Module({})
 ], AgentModule);
 
+// src/ag-ui/ag-ui.adapter.ts
+import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER14, AGENT_ATTACHMENT_STAGING as AGENT_ATTACHMENT_STAGING5, AGENT_OPTIONS as AGENT_OPTIONS8 } from "@dudousxd/nestjs-agent-core";
+import { AG_UI_CUSTOM, agUiEvents, agUiFramesFromNdjson, agUiSse, parseRunInput, planResume, readAnswersPayload, readApprovalPayload, readContext, readForwardedProps, readUserTurn } from "@dudousxd/nestjs-agent-core/ag-ui";
+import { BadRequestException as BadRequestException6, Body as Body6, Controller as Controller14, ForbiddenException as ForbiddenException3, HttpCode as HttpCode2, Inject as Inject21, Optional as Optional9, Post as Post7, Req as Req13, Res as Res2 } from "@nestjs/common";
+function _ts_decorate23(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") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate23, "_ts_decorate");
+function _ts_metadata22(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
+}
+__name(_ts_metadata22, "_ts_metadata");
+function _ts_param21(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param21, "_ts_param");
+var AG_UI_VIA = "ag-ui";
+function invalid(code, message) {
+  return new BadRequestException6({
+    statusCode: 400,
+    code,
+    message
+  });
+}
+__name(invalid, "invalid");
+function warningEvents(warnings) {
+  return warnings.map((message) => ({
+    type: "CUSTOM",
+    name: AG_UI_CUSTOM.warning,
+    value: {
+      message
+    }
+  }));
+}
+__name(warningEvents, "warningEvents");
+var AgUiRunHandler = class {
+  static {
+    __name(this, "AgUiRunHandler");
+  }
+  agent;
+  actorResolver;
+  options;
+  staging;
+  quietMs;
+  constructor(agent, actorResolver, options, staging, quietMs) {
+    this.agent = agent;
+    this.actorResolver = actorResolver;
+    this.options = options;
+    this.staging = staging;
+    this.quietMs = quietMs;
+  }
+  async handle(req, res, body) {
+    const input = parseRunInput(body);
+    if (typeof input === "string") {
+      throw invalid("invalid_input", input);
+    }
+    const forwarded = readForwardedProps(input.forwardedProps);
+    const actor = await this.actorResolver.resolve(req);
+    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.");
+    }
+    const quiet = this.quietMs !== void 0 ? {
+      quietMs: this.quietMs
+    } : {};
+    if (input.resume !== void 0 && input.resume.length > 0) {
+      const plan = planResume(input.resume);
+      if (typeof plan === "string") {
+        throw invalid("invalid_resume", plan);
+      }
+      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];
+      if (first !== void 0) {
+        const streamRunId = first.address.stream;
+        await this.agent.assertResumable(actor, streamRunId);
+        await this.settle(actor, plan.decisions);
+        await this.pipe(res, streamRunId, {
+          threadId: input.threadId,
+          runId: input.runId,
+          streamRunId,
+          skip: first.address.position,
+          answered: plan.decisions.map((decision) => decision.address.toolCallId),
+          ...quiet,
+          preamble: warningEvents(warnings)
+        });
+        return;
+      }
+    }
+    const turn = readUserTurn(input.messages);
+    if (turn === null) {
+      throw invalid("no_user_message", "messages carries no user message to answer");
+    }
+    warnings.push(...turn.dropped);
+    const owner = await this.agent.threadOwner(input.threadId);
+    if (owner !== null && owner !== actor.id) {
+      throw new ForbiddenException3("thread belongs to another actor");
+    }
+    const refs = await this.stage(actor, turn.media, warnings);
+    if (turn.text.trim().length === 0 && refs.length === 0) {
+      throw invalid("no_user_message", "the user message to answer is empty");
+    }
+    const context = readContext(input.context);
+    const pageContext = forwarded.pageContext !== void 0 || context !== void 0 ? {
+      ...forwarded.pageContext,
+      ...context !== void 0 ? {
+        agUiContext: context
+      } : {}
+    } : void 0;
+    const started = await this.agent.chat({
+      actor,
+      message: turn.text,
+      ...owner !== null ? {
+        threadId: input.threadId
+      } : {
+        newThreadId: input.threadId
+      },
+      ...forwarded.agent !== void 0 ? {
+        agentName: forwarded.agent
+      } : {},
+      ...forwarded.model !== void 0 ? {
+        model: forwarded.model
+      } : {},
+      ...pageContext !== void 0 ? {
+        pageContext
+      } : {},
+      ...refs.length > 0 ? {
+        attachments: refs
+      } : {}
+    });
+    await this.pipe(res, started.runId, {
+      threadId: input.threadId,
+      runId: input.runId,
+      streamRunId: started.runId,
+      streamThreadId: started.threadId,
+      ...quiet,
+      preamble: warningEvents(warnings)
+    });
+  }
+  /** Stage the turn's inline media through the bound store, within its limits; say what was not used. */
+  async stage(actor, media, warnings) {
+    const refs = [];
+    const limits = attachmentLimits(this.options, this.staging);
+    for (const item of media) {
+      const label = `The ${item.kind} "${item.filename}" was not used`;
+      if (this.staging === void 0) {
+        warnings.push(`${label}: attachments are not enabled on this agent.`);
+      } else if (refs.length >= limits.maxPerMessage) {
+        warnings.push(`${label}: a message carries at most ${limits.maxPerMessage} attachments.`);
+      } else if (!limits.allowedContentTypes.includes(item.contentType)) {
+        warnings.push(`${label}: ${item.contentType} is not an accepted type.`);
+      } else if (item.data.length > limits.maxBytes) {
+        warnings.push(`${label}: it is larger than ${limits.maxBytes} bytes.`);
+      } else {
+        try {
+          const staged = await this.staging.stage({
+            data: item.data,
+            filename: item.filename,
+            contentType: item.contentType,
+            sizeBytes: item.data.length,
+            actor
+          });
+          refs.push({
+            mediaId: staged.mediaId
+          });
+        } catch {
+          warnings.push(`${label}: it could not be stored.`);
+        }
+      }
+    }
+    return refs;
+  }
+  /**
+  * 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.
+  */
+  async settle(actor, decisions) {
+    const deliveries = [];
+    for (const { address, entry } of decisions) {
+      const { toolCallId: toolCallId2 } = address;
+      const abandoned = entry.status === "cancelled";
+      if (address.kind === "approval") {
+        await this.agent.checkDecision(actor, toolCallId2);
+        const decision = abandoned ? {
+          approved: false
+        } : readApprovalPayload(entry.payload);
+        if (decision === null) {
+          throw invalid("invalid_resume", "an approval is answered with { approved: boolean, reason?, remember? }");
+        }
+        const reason = rejectReason(decision.reason ?? (abandoned ? "abandoned" : void 0));
+        deliveries.push(() => decision.approved ? this.agent.approve(actor, toolCallId2, {
+          via: AG_UI_VIA,
+          ...decision.remember === true ? {
+            remember: true
+          } : {}
+        }) : this.agent.reject(actor, toolCallId2, reason, {
+          via: AG_UI_VIA
+        }));
+        continue;
+      }
+      if (abandoned) {
+        await this.agent.checkAnswer(actor, toolCallId2, {});
+        deliveries.push(() => this.agent.skip(actor, toolCallId2, {
+          via: AG_UI_VIA
+        }));
+        continue;
+      }
+      const read = readAnswersPayload(entry.payload);
+      if (read === null) {
+        throw invalid("invalid_resume", "a question set is answered with { answers: { <questionId>: string[] } }");
+      }
+      const answers2 = answers(read) ?? {};
+      await this.agent.checkAnswer(actor, toolCallId2, answers2);
+      deliveries.push(() => this.agent.answer(actor, toolCallId2, answers2, {
+        via: AG_UI_VIA
+      }));
+    }
+    for (const deliver of deliveries) await deliver();
+  }
+  /**
+  * 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 pipe(res, runId, options) {
+    res.status(200);
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache, no-transform");
+    res.setHeader("Connection", "keep-alive");
+    res.setHeader("X-Accel-Buffering", "no");
+    res.setHeader("X-Agent-Run-Id", runId);
+    res.flushHeaders();
+    let terminal = false;
+    try {
+      const frames = agUiFramesFromNdjson(this.agent.subscribe(runId));
+      for await (const event of agUiEvents(frames, options)) {
+        if (event.type === "RUN_FINISHED" || event.type === "RUN_ERROR") terminal = true;
+        res.write(agUiSse(event));
+      }
+    } catch {
+      if (!terminal) {
+        res.write(agUiSse({
+          type: "RUN_ERROR",
+          message: "The run could not be followed.",
+          code: "run_failed"
+        }));
+      }
+    }
+    res.end();
+  }
+};
+function agUiAdapter(options = {}) {
+  const path = (options.path ?? "ag-ui").replace(/^\/+|\/+$/g, "");
+  const quietMs = options.quietMs;
+  let AgUiController = class AgUiController extends AgUiRunHandler {
+    static {
+      __name(this, "AgUiController");
+    }
+    constructor(agent, actorResolver, moduleOptions, staging) {
+      super(agent, actorResolver, moduleOptions, staging, quietMs);
+    }
+    run(req, res, body) {
+      return this.handle(req, res, body);
+    }
+  };
+  _ts_decorate23([
+    Post7(path),
+    HttpCode2(200),
+    _ts_param21(0, Req13()),
+    _ts_param21(1, Res2()),
+    _ts_param21(2, Body6()),
+    _ts_metadata22("design:type", Function),
+    _ts_metadata22("design:paramtypes", [
+      typeof Request === "undefined" ? Object : Request,
+      typeof Response === "undefined" ? Object : Response,
+      Object
+    ]),
+    _ts_metadata22("design:returntype", typeof Promise === "undefined" ? Object : Promise)
+  ], AgUiController.prototype, "run", null);
+  AgUiController = _ts_decorate23([
+    Controller14(),
+    _ts_param21(0, Inject21(AgentService)),
+    _ts_param21(1, Inject21(AGENT_ACTOR_RESOLVER14)),
+    _ts_param21(2, Inject21(AGENT_OPTIONS8)),
+    _ts_param21(3, Optional9()),
+    _ts_param21(3, Inject21(AGENT_ATTACHMENT_STAGING5)),
+    _ts_metadata22("design:type", Function),
+    _ts_metadata22("design:paramtypes", [
+      typeof AgentService === "undefined" ? Object : AgentService,
+      typeof ActorResolver === "undefined" ? Object : ActorResolver,
+      typeof AgentModuleOptions === "undefined" ? Object : AgentModuleOptions,
+      typeof AttachmentStagingStore === "undefined" ? Object : AttachmentStagingStore
+    ])
+  ], AgUiController);
+  return {
+    name: "ag-ui",
+    controllers: [
+      AgUiController
+    ]
+  };
+}
+__name(agUiAdapter, "agUiAdapter");
+
 // src/resolver/header-actor-resolver.ts
 import { UnauthorizedException } from "@nestjs/common";
 function readHeader(req, name) {
@@ -5238,6 +5608,7 @@ export {
   AGENT_TOOL_BRAND,
   AI_TOOL_METADATA,
   ATTACHMENT_PAGE_SIZE,
+  AgUiRunHandler,
   Agent,
   AgentApprovalPortAdapter,
   AgentDepsFactory2 as AgentDepsFactory,
@@ -5271,6 +5642,7 @@ export {
   SystemPrompt,
   SystemPromptContributor,
   ToolsController,
+  agUiAdapter,
   attachmentLimits,
   declaredSkillProvider,
   defaultRequestUserMapper,