@dudousxd/nestjs-agent 1.17.1 → 1.19.0

package/dist/index.cjs

@@ -27,6 +27,7 @@ __export(index_exports, {
   AGENT_TOOL_BRAND: () => AGENT_TOOL_BRAND,
   AI_TOOL_METADATA: () => AI_TOOL_METADATA,
   ATTACHMENT_PAGE_SIZE: () => ATTACHMENT_PAGE_SIZE,
+  AgUiRunHandler: () => AgUiRunHandler,
   Agent: () => Agent,
   AgentApprovalPortAdapter: () => AgentApprovalPortAdapter,
   AgentDepsFactory: () => AgentDepsFactory2,
@@ -60,6 +61,7 @@ __export(index_exports, {
   SystemPrompt: () => SystemPrompt,
   SystemPromptContributor: () => SystemPromptContributor,
   ToolsController: () => ToolsController,
+  agUiAdapter: () => agUiAdapter,
   attachmentLimits: () => attachmentLimits,
   declaredSkillProvider: () => declaredSkillProvider,
   defaultRequestUserMapper: () => defaultRequestUserMapper,
@@ -1026,6 +1028,9 @@ var AgentService = class {
         actor: params.actor,
         ...params.transient === true ? {
           transient: true
+        } : {},
+        ...params.newThreadId !== void 0 ? {
+          id: params.newThreadId
         } : {}
       });
       threadId = created.id;
@@ -1450,6 +1455,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 import_common4.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);
@@ -4996,7 +5033,7 @@ function sharedProviders(durable) {
     },
     {
       provide: import_nestjs_agent_core27.AGENT_ROLES_POLICY,
-      useFactory: /* @__PURE__ */ __name((options) => options.rolesPolicy ?? new import_nestjs_agent_core27.DefaultRolesPolicy(options.defaultRoles), "useFactory"),
+      useFactory: /* @__PURE__ */ __name((options) => options.rolesPolicy ?? (options.emptyRoles === "deny" ? new import_nestjs_agent_core27.ClosedRolesPolicy(options.defaultRoles) : new import_nestjs_agent_core27.DefaultRolesPolicy(options.defaultRoles)), "useFactory"),
       inject: [
         import_nestjs_agent_core27.AGENT_OPTIONS
       ]
@@ -5138,15 +5175,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);
   }
 }
@@ -5172,7 +5222,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,
@@ -5180,21 +5230,22 @@ var AgentModule = class _AgentModule {
         import_core4.DiscoveryModule,
         routerFor(path)
       ],
-      controllers: controllersForSurface(options.surface),
+      controllers: controllersForSurface(options.surface, options.adapters),
       providers: [
         {
           provide: import_nestjs_agent_core27.AGENT_OPTIONS,
           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,
@@ -5203,7 +5254,7 @@ var AgentModule = class _AgentModule {
         routerFor(path),
         ...options.imports ?? []
       ],
-      controllers: controllersForSurface(options.surface),
+      controllers: controllersForSurface(options.surface, options.adapters),
       providers: [
         {
           provide: import_nestjs_agent_core27.AGENT_OPTIONS,
@@ -5221,7 +5272,8 @@ var AgentModule = class _AgentModule {
           inject: options.inject ?? []
         },
         ...sharedProviders(options.durable ?? false),
-        ...guardProviders(options.guards)
+        ...guardProviders(options.guards),
+        ...adapterProviders(options.adapters)
       ],
       exports: exportsFor()
     };
@@ -5232,8 +5284,328 @@ AgentModule = _ts_decorate22([
   (0, import_common23.Module)({})
 ], AgentModule);
 
-// src/resolver/header-actor-resolver.ts
+// src/ag-ui/ag-ui.adapter.ts
+var import_nestjs_agent_core28 = require("@dudousxd/nestjs-agent-core");
+var import_ag_ui = require("@dudousxd/nestjs-agent-core/ag-ui");
 var import_common24 = require("@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 import_common24.BadRequestException({
+    statusCode: 400,
+    code,
+    message
+  });
+}
+__name(invalid, "invalid");
+function warningEvents(warnings) {
+  return warnings.map((message) => ({
+    type: "CUSTOM",
+    name: import_ag_ui.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 = (0, import_ag_ui.parseRunInput)(body);
+    if (typeof input === "string") {
+      throw invalid("invalid_input", input);
+    }
+    const forwarded = (0, import_ag_ui.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 = (0, import_ag_ui.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 = (0, import_ag_ui.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 import_common24.ForbiddenException("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 = (0, import_ag_ui.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
+        } : (0, import_ag_ui.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 = (0, import_ag_ui.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 = (0, import_ag_ui.agUiFramesFromNdjson)(this.agent.subscribe(runId));
+      for await (const event of (0, import_ag_ui.agUiEvents)(frames, options)) {
+        if (event.type === "RUN_FINISHED" || event.type === "RUN_ERROR") terminal = true;
+        res.write((0, import_ag_ui.agUiSse)(event));
+      }
+    } catch {
+      if (!terminal) {
+        res.write((0, import_ag_ui.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([
+    (0, import_common24.Post)(path),
+    (0, import_common24.HttpCode)(200),
+    _ts_param21(0, (0, import_common24.Req)()),
+    _ts_param21(1, (0, import_common24.Res)()),
+    _ts_param21(2, (0, import_common24.Body)()),
+    _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([
+    (0, import_common24.Controller)(),
+    _ts_param21(0, (0, import_common24.Inject)(AgentService)),
+    _ts_param21(1, (0, import_common24.Inject)(import_nestjs_agent_core28.AGENT_ACTOR_RESOLVER)),
+    _ts_param21(2, (0, import_common24.Inject)(import_nestjs_agent_core28.AGENT_OPTIONS)),
+    _ts_param21(3, (0, import_common24.Optional)()),
+    _ts_param21(3, (0, import_common24.Inject)(import_nestjs_agent_core28.AGENT_ATTACHMENT_STAGING)),
+    _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
+var import_common25 = require("@nestjs/common");
 function readHeader(req, name) {
   if (typeof req !== "object" || req === null || !("headers" in req)) return void 0;
   const { headers } = req;
@@ -5249,7 +5621,7 @@ var HeaderActorResolver = class {
   resolve(req) {
     const id = readHeader(req, "x-actor-id");
     if (id === void 0 || id.length === 0) {
-      throw new import_common24.UnauthorizedException("HeaderActorResolver: missing x-actor-id header. No default actor is fabricated. Send x-actor-id from a trusted gateway, or configure AgentModule.forRoot({ actorResolver }) with a resolver that reads your authenticated principal.");
+      throw new import_common25.UnauthorizedException("HeaderActorResolver: missing x-actor-id header. No default actor is fabricated. Send x-actor-id from a trusted gateway, or configure AgentModule.forRoot({ actorResolver }) with a resolver that reads your authenticated principal.");
     }
     const roles = (readHeader(req, "x-actor-role") ?? "").split(",").map((role) => role.trim()).filter((role) => role.length > 0);
     const tenantRef = readHeader(req, "x-tenant-ref");
@@ -5264,7 +5636,7 @@ var HeaderActorResolver = class {
 };
 
 // src/resolver/request-user-actor-resolver.ts
-var import_common25 = require("@nestjs/common");
+var import_common26 = require("@nestjs/common");
 function field(user, ...names) {
   for (const name of names) {
     const value = user[name];
@@ -5276,7 +5648,7 @@ __name(field, "field");
 function defaultRequestUserMapper(user) {
   const id = field(user, "id", "sub", "_id", "userId");
   if (id === void 0) {
-    throw new import_common25.UnauthorizedException("requestUserActorResolver: req.user has no id/sub/_id/userId \u2014 pass a mapper: requestUserActorResolver((user) => ({ id: \u2026, roles: \u2026 }))");
+    throw new import_common26.UnauthorizedException("requestUserActorResolver: req.user has no id/sub/_id/userId \u2014 pass a mapper: requestUserActorResolver((user) => ({ id: \u2026, roles: \u2026 }))");
   }
   const rawRoles = field(user, "roles", "role");
   const roles = Array.isArray(rawRoles) ? rawRoles.map(String) : typeof rawRoles === "string" ? [
@@ -5297,7 +5669,7 @@ function requestUserActorResolver(map) {
     async resolve(req) {
       const user = typeof req === "object" && req !== null ? req.user : void 0;
       if (user === void 0 || user === null || user === false) {
-        throw new import_common25.UnauthorizedException("Sign in to use the agent.");
+        throw new import_common26.UnauthorizedException("Sign in to use the agent.");
       }
       if (map !== void 0) return map(user, req);
       return defaultRequestUserMapper(user);
@@ -5315,6 +5687,7 @@ __reExport(index_exports, require("@dudousxd/nestjs-agent-core"), module.exports
   AGENT_TOOL_BRAND,
   AI_TOOL_METADATA,
   ATTACHMENT_PAGE_SIZE,
+  AgUiRunHandler,
   Agent,
   AgentApprovalPortAdapter,
   AgentDepsFactory,
@@ -5348,6 +5721,7 @@ __reExport(index_exports, require("@dudousxd/nestjs-agent-core"), module.exports
   SystemPrompt,
   SystemPromptContributor,
   ToolsController,
+  agUiAdapter,
   attachmentLimits,
   declaredSkillProvider,
   defaultRequestUserMapper,