@dudousxd/nestjs-agent 1.36.2 → 1.38.0

package/dist/{index-CJdTomOT.d.cts → index-BJFM1tG8.d.cts}

@@ -1,5 +1,5 @@
 import { A2uiStreamOptions, a2uiThreadReplay } from '@dudousxd/nestjs-agent-core/a2ui';
-import { AgentAttachmentConfig, AttachmentStagingStore, AgentStore, Actor, ListActionProposals, ActionProposalView, ActionProposalMutationView, TextActionProposalVocabulary, AgentRunner, ModelCatalog, QuotaProvider, ActionApprovalMode, MessageAttachment, QuotaReport, ModelCatalogView, AgentHostContext, AttachmentRef, PageContext, ChatQueueState, SubscribeOptions, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver } from '@dudousxd/nestjs-agent-core';
+import { AgentAttachmentConfig, AttachmentStagingStore, AgentStore, Actor, ListActionProposals, ActionProposalView, ActionProposalMutationView, TextActionProposalVocabulary, AgentRunner, ModelCatalog, QuotaProvider, ActionApprovalMode, MessageAttachment, QuotaReport, ModelCatalogView, AgentHostContext, AttachmentRef, PageContext, ChatQueueState, SubscribeOptions, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, AiUsageInput, AiUsageOptions, AiUsageResult, ActorResolver } from '@dudousxd/nestjs-agent-core';
 import { Request, Response } from 'express';
 import { UiCapabilities } from '@dudousxd/nestjs-agent-core/genui';
 import { b as AgentModuleOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter } from './chat-queue.service-fopUN313.cjs';
@@ -167,6 +167,22 @@ interface ChatParams {
 interface ThreadDefaultAgentReader {
     defaultAgentForThread(threadId: string): Promise<string | null>;
 }
+/** What {@link AgentService.forkThread} takes past the thread and the message to copy up to. */
+interface ForkThreadParams {
+    /**
+     * The HOST already decided this actor may read the thread — "continue this conversation" from a
+     * link its owner shared. Skips the ownership check, and the copy belongs to the CALLER, not the
+     * source's owner; the original is left as it was. Never set it from a request's own claim: the
+     * `POST /threads/:id/fork-from/:messageId` route never does, so it stays owner-only.
+     */
+    authorized?: boolean;
+    /**
+     * The copy's tenant — see `ForkThreadOptions.tenantRef`. Absent keeps the SOURCE's, even when the
+     * copy now belongs to someone else; forking across tenants, pass the caller's
+     * (`actor.tenantRef ?? null`). `null` clears it.
+     */
+    tenantRef?: string | null;
+}
 /** Like {@link ThreadDefaultAgentReader}, for the thread's pinned model. */
 interface ThreadModelReader {
     modelForThread(threadId: string): Promise<string | null>;
@@ -430,7 +446,12 @@ declare class AgentService {
     listThreads(actorRef: string): Promise<ThreadSummary[]>;
     getThread(actor: Actor, threadId: string): Promise<ThreadDetail | null>;
     deleteThread(actor: Actor, threadId: string): Promise<void>;
-    forkThread(actor: Actor, threadId: string, fromMessageId: string): Promise<ThreadSummary>;
+    /**
+     * Copy a thread up to `fromMessageId` (inclusive) into a new one. By default only the thread's
+     * owner may, and the copy is theirs. With `params.authorized`, the host has vouched for `actor`
+     * (a share link it checked) and the copy is `actor`'s — see {@link ForkThreadParams}.
+     */
+    forkThread(actor: Actor, threadId: string, fromMessageId: string, params?: ForkThreadParams): Promise<ThreadSummary>;
     /** Kept for source compatibility — a thin wrapper over the more general `updateThread`. */
     renameThread(actor: Actor, threadId: string, title: string): Promise<void>;
     /**
@@ -567,6 +588,22 @@ declare class AgentService {
     private resolveRunForToolCall;
     /** Authorization seam for `cancel`: the caller must own the thread currently streaming this run. */
     private assertOwnsActiveStream;
+    /**
+     * Record AI spend that did not come from an agent turn — a transcription, a TTS render, a batch of
+     * embeddings, a direct OpenAI/OpenRouter SDK call — on the same ledger the agent's turns write, so
+     * cost, quota and the dashboard see one figure.
+     *
+     * Never throws into the caller's flow by default: a failed write or an invalid input is logged and
+     * answered with `{ recorded: false, error }`. Pass `{ throwOnError: true }` where losing the row
+     * must fail the caller.
+     *
+     * Counted against `actorRef` like an agent turn: the ledger is the budget (`LedgerQuotaProvider`),
+     * so its tokens count in the token windows (a row with no tokens adds 0 there) and its `costUsd` in
+     * the USD windows. A `QuotaStore` counter is bumped only where loop deps carry one (`AgentModule`
+     * wires none). `actorRef: null` is platform cost, recorded under `PLATFORM_ACTOR_REF` and counted
+     * against nobody.
+     */
+    recordUsage(input: AiUsageInput, options?: AiUsageOptions): Promise<AiUsageResult>;
 }
 
 interface A2uiAdapterOptions extends A2uiStreamOptions {
@@ -647,4 +684,4 @@ declare class A2uiRunHandler {
  */
 declare function a2uiAdapter(options?: A2uiAdapterOptions): AgentProtocolAdapter;
 
-export { AgentService as A, type ChatParams as C, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES as D, MAX_ATTACHMENTS_PER_MESSAGE as M, NO_USER_MESSAGE_CODE as N, type QueuedSend as Q, type ThreadDefaultAgentReader as T, ActionProposalService as a, type A2uiAdapterOptions as b, A2uiRunHandler as c, type AttachmentLimits as d, type ChatSendMode as e, type ChatSendResult as f, DEFAULT_MAX_ATTACHMENT_BYTES as g, type ThreadModelReader as h, a2uiAdapter as i, attachmentLimits as j };
+export { AgentService as A, type ChatParams as C, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES as D, type ForkThreadParams as F, MAX_ATTACHMENTS_PER_MESSAGE as M, NO_USER_MESSAGE_CODE as N, type QueuedSend as Q, type ThreadDefaultAgentReader as T, ActionProposalService as a, type A2uiAdapterOptions as b, A2uiRunHandler as c, type AttachmentLimits as d, type ChatSendMode as e, type ChatSendResult as f, DEFAULT_MAX_ATTACHMENT_BYTES as g, type ThreadModelReader as h, a2uiAdapter as i, attachmentLimits as j };

package/dist/{index-D1xRrnCq.d.ts → index-De98CGXa.d.ts}

@@ -1,5 +1,5 @@
 import { A2uiStreamOptions, a2uiThreadReplay } from '@dudousxd/nestjs-agent-core/a2ui';
-import { AgentAttachmentConfig, AttachmentStagingStore, AgentStore, Actor, ListActionProposals, ActionProposalView, ActionProposalMutationView, TextActionProposalVocabulary, AgentRunner, ModelCatalog, QuotaProvider, ActionApprovalMode, MessageAttachment, QuotaReport, ModelCatalogView, AgentHostContext, AttachmentRef, PageContext, ChatQueueState, SubscribeOptions, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver } from '@dudousxd/nestjs-agent-core';
+import { AgentAttachmentConfig, AttachmentStagingStore, AgentStore, Actor, ListActionProposals, ActionProposalView, ActionProposalMutationView, TextActionProposalVocabulary, AgentRunner, ModelCatalog, QuotaProvider, ActionApprovalMode, MessageAttachment, QuotaReport, ModelCatalogView, AgentHostContext, AttachmentRef, PageContext, ChatQueueState, SubscribeOptions, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, AiUsageInput, AiUsageOptions, AiUsageResult, ActorResolver } from '@dudousxd/nestjs-agent-core';
 import { Request, Response } from 'express';
 import { UiCapabilities } from '@dudousxd/nestjs-agent-core/genui';
 import { b as AgentModuleOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter } from './chat-queue.service-YjiKVTKE.js';
@@ -167,6 +167,22 @@ interface ChatParams {
 interface ThreadDefaultAgentReader {
     defaultAgentForThread(threadId: string): Promise<string | null>;
 }
+/** What {@link AgentService.forkThread} takes past the thread and the message to copy up to. */
+interface ForkThreadParams {
+    /**
+     * The HOST already decided this actor may read the thread — "continue this conversation" from a
+     * link its owner shared. Skips the ownership check, and the copy belongs to the CALLER, not the
+     * source's owner; the original is left as it was. Never set it from a request's own claim: the
+     * `POST /threads/:id/fork-from/:messageId` route never does, so it stays owner-only.
+     */
+    authorized?: boolean;
+    /**
+     * The copy's tenant — see `ForkThreadOptions.tenantRef`. Absent keeps the SOURCE's, even when the
+     * copy now belongs to someone else; forking across tenants, pass the caller's
+     * (`actor.tenantRef ?? null`). `null` clears it.
+     */
+    tenantRef?: string | null;
+}
 /** Like {@link ThreadDefaultAgentReader}, for the thread's pinned model. */
 interface ThreadModelReader {
     modelForThread(threadId: string): Promise<string | null>;
@@ -430,7 +446,12 @@ declare class AgentService {
     listThreads(actorRef: string): Promise<ThreadSummary[]>;
     getThread(actor: Actor, threadId: string): Promise<ThreadDetail | null>;
     deleteThread(actor: Actor, threadId: string): Promise<void>;
-    forkThread(actor: Actor, threadId: string, fromMessageId: string): Promise<ThreadSummary>;
+    /**
+     * Copy a thread up to `fromMessageId` (inclusive) into a new one. By default only the thread's
+     * owner may, and the copy is theirs. With `params.authorized`, the host has vouched for `actor`
+     * (a share link it checked) and the copy is `actor`'s — see {@link ForkThreadParams}.
+     */
+    forkThread(actor: Actor, threadId: string, fromMessageId: string, params?: ForkThreadParams): Promise<ThreadSummary>;
     /** Kept for source compatibility — a thin wrapper over the more general `updateThread`. */
     renameThread(actor: Actor, threadId: string, title: string): Promise<void>;
     /**
@@ -567,6 +588,22 @@ declare class AgentService {
     private resolveRunForToolCall;
     /** Authorization seam for `cancel`: the caller must own the thread currently streaming this run. */
     private assertOwnsActiveStream;
+    /**
+     * Record AI spend that did not come from an agent turn — a transcription, a TTS render, a batch of
+     * embeddings, a direct OpenAI/OpenRouter SDK call — on the same ledger the agent's turns write, so
+     * cost, quota and the dashboard see one figure.
+     *
+     * Never throws into the caller's flow by default: a failed write or an invalid input is logged and
+     * answered with `{ recorded: false, error }`. Pass `{ throwOnError: true }` where losing the row
+     * must fail the caller.
+     *
+     * Counted against `actorRef` like an agent turn: the ledger is the budget (`LedgerQuotaProvider`),
+     * so its tokens count in the token windows (a row with no tokens adds 0 there) and its `costUsd` in
+     * the USD windows. A `QuotaStore` counter is bumped only where loop deps carry one (`AgentModule`
+     * wires none). `actorRef: null` is platform cost, recorded under `PLATFORM_ACTOR_REF` and counted
+     * against nobody.
+     */
+    recordUsage(input: AiUsageInput, options?: AiUsageOptions): Promise<AiUsageResult>;
 }
 
 interface A2uiAdapterOptions extends A2uiStreamOptions {
@@ -647,4 +684,4 @@ declare class A2uiRunHandler {
  */
 declare function a2uiAdapter(options?: A2uiAdapterOptions): AgentProtocolAdapter;
 
-export { AgentService as A, type ChatParams as C, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES as D, MAX_ATTACHMENTS_PER_MESSAGE as M, NO_USER_MESSAGE_CODE as N, type QueuedSend as Q, type ThreadDefaultAgentReader as T, ActionProposalService as a, type A2uiAdapterOptions as b, A2uiRunHandler as c, type AttachmentLimits as d, type ChatSendMode as e, type ChatSendResult as f, DEFAULT_MAX_ATTACHMENT_BYTES as g, type ThreadModelReader as h, a2uiAdapter as i, attachmentLimits as j };
+export { AgentService as A, type ChatParams as C, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES as D, type ForkThreadParams as F, MAX_ATTACHMENTS_PER_MESSAGE as M, NO_USER_MESSAGE_CODE as N, type QueuedSend as Q, type ThreadDefaultAgentReader as T, ActionProposalService as a, type A2uiAdapterOptions as b, A2uiRunHandler as c, type AttachmentLimits as d, type ChatSendMode as e, type ChatSendResult as f, DEFAULT_MAX_ATTACHMENT_BYTES as g, type ThreadModelReader as h, a2uiAdapter as i, attachmentLimits as j };

package/dist/index.cjs

@@ -1723,6 +1723,7 @@ function _ts_param4(paramIndex, decorator) {
   };
 }
 __name(_ts_param4, "_ts_param");
+var usageLogger = new import_common6.Logger("AgentService");
 var NO_USER_MESSAGE_CODE = "no_user_message";
 function sendableParams(params) {
   const message = params.message;
@@ -2550,9 +2551,28 @@ var AgentService2 = class {
     await this.assertOwnsThread(actor, threadId);
     return this.store.softDeleteThread(threadId);
   }
-  async forkThread(actor, threadId, fromMessageId) {
-    await this.assertOwnsThread(actor, threadId);
-    return this.store.forkThread(threadId, fromMessageId);
+  /**
+  * Copy a thread up to `fromMessageId` (inclusive) into a new one. By default only the thread's
+  * owner may, and the copy is theirs. With `params.authorized`, the host has vouched for `actor`
+  * (a share link it checked) and the copy is `actor`'s — see {@link ForkThreadParams}.
+  */
+  async forkThread(actor, threadId, fromMessageId, params = {}) {
+    if (params.authorized === true) {
+      if (await this.store.ownerOfThread(threadId) === null) {
+        throw new import_common6.NotFoundException(`thread ${threadId} not found`);
+      }
+    } else {
+      await this.assertOwnsThread(actor, threadId);
+    }
+    const options = {
+      ...params.authorized === true ? {
+        actorRef: actor.id
+      } : {},
+      ...params.tenantRef !== void 0 ? {
+        tenantRef: params.tenantRef
+      } : {}
+    };
+    return this.store.forkThread(threadId, fromMessageId, options);
   }
   /** Kept for source compatibility — a thin wrapper over the more general `updateThread`. */
   async renameThread(actor, threadId, title) {
@@ -2947,6 +2967,31 @@ var AgentService2 = class {
       throw new import_common6.ForbiddenException("run belongs to another actor");
     }
   }
+  /**
+  * Record AI spend that did not come from an agent turn — a transcription, a TTS render, a batch of
+  * embeddings, a direct OpenAI/OpenRouter SDK call — on the same ledger the agent's turns write, so
+  * cost, quota and the dashboard see one figure.
+  *
+  * Never throws into the caller's flow by default: a failed write or an invalid input is logged and
+  * answered with `{ recorded: false, error }`. Pass `{ throwOnError: true }` where losing the row
+  * must fail the caller.
+  *
+  * Counted against `actorRef` like an agent turn: the ledger is the budget (`LedgerQuotaProvider`),
+  * so its tokens count in the token windows (a row with no tokens adds 0 there) and its `costUsd` in
+  * the USD windows. A `QuotaStore` counter is bumped only where loop deps carry one (`AgentModule`
+  * wires none). `actorRef: null` is platform cost, recorded under `PLATFORM_ACTOR_REF` and counted
+  * against nobody.
+  */
+  recordUsage(input, options = {}) {
+    return (0, import_nestjs_agent_core9.recordAiUsage)({
+      store: this.store,
+      quota: this.deps.forAgent().quota,
+      day: utcDay(),
+      input,
+      options,
+      warn: /* @__PURE__ */ __name((message) => usageLogger.warn(message), "warn")
+    });
+  }
 };
 AgentService2 = _ts_decorate5([
   (0, import_common6.Injectable)(),
@@ -6157,10 +6202,12 @@ var InlineAgentRunner = class _InlineAgentRunner {
   }
   async start(input, options = {}) {
     const runId = options.runId ?? crypto.randomUUID();
+    const acceptedAt = Date.now();
     const day = input.day ?? utcDay();
     const deps = this.factory.forAgent(input.agentName);
     this.live.add(runId);
     const hooks = this.topLevelHooks({
+      acceptedAt,
       runId,
       deps,
       actor: input.actor,
@@ -6182,8 +6229,9 @@ var InlineAgentRunner = class _InlineAgentRunner {
       const timed = durationMs !== void 0 ? {
         durationMs
       } : {};
+      const measured = (0, import_nestjs_agent_core32.runEndTimings)(error);
       if (error instanceof import_nestjs_agent_core32.RunCancelledError) {
-        await this.settleCancelled(runId, input, deps, durationMs);
+        await this.settleCancelled(runId, input, deps, durationMs, measured);
         return;
       }
       const message = error instanceof Error ? error.message : String(error);
@@ -6195,6 +6243,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
         code,
         message,
         ...timed,
+        ...measured,
         context: (0, import_nestjs_agent_core32.agentRunContext)(input)
       });
       await this.store.recordRunEnd?.({
@@ -6272,7 +6321,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
   * the stream ENDED after a `cancelled` frame rather than failed, so a client that retries failed
   * streams does not retry this one.
   */
-  async settleCancelled(runId, input, deps, durationMs) {
+  async settleCancelled(runId, input, deps, durationMs, measured = {}) {
     this.logger.log(`agent run ${runId} cancelled`);
     const timed = durationMs !== void 0 ? {
       durationMs
@@ -6281,6 +6330,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
       runId,
       threadId: input.threadId,
       ...timed,
+      ...measured,
       context: (0, import_nestjs_agent_core32.agentRunContext)(input)
     });
     const writer = await deps.sink.open(runId);
@@ -6373,9 +6423,10 @@ var InlineAgentRunner = class _InlineAgentRunner {
     });
   }
   topLevelHooks(args) {
-    const { runId, deps, actor, day, threadId, chainBelow, input } = args;
+    const { runId, deps, actor, day, threadId, chainBelow, input, acceptedAt } = args;
     return {
       runId,
+      queueMs: /* @__PURE__ */ __name(() => Date.now() - acceptedAt, "queueMs"),
       // The loop ends the stream when the turn completes. Just before, the thread passes to the next
       // queued message (or is released), and the reader is told which — so by the time a client
       // sees the run end, the thread is already free or already running what it queued.
@@ -6500,10 +6551,12 @@ var InlineAgentRunner = class _InlineAgentRunner {
       const timed = durationMs !== void 0 ? {
         durationMs
       } : {};
+      const measured = (0, import_nestjs_agent_core32.runEndTimings)(error);
       const settled = {
         runId,
         threadId: subThread.id,
         ...timed,
+        ...measured,
         context: (0, import_nestjs_agent_core32.agentRunContext)(childInput)
       };
       if (cancelled) {