@arcote.tech/arc-chat 0.7.11 → 0.7.13

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/arc-chat",
   "type": "module",
-  "version": "0.7.11",
+  "version": "0.7.13",
   "private": false,
   "description": "Chat module with AI integration for Arc framework",
   "main": "./src/index.ts",
@@ -10,12 +10,12 @@
     "type-check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@arcote.tech/arc": "^0.7.11",
-    "@arcote.tech/arc-ai": "^0.7.11",
-    "@arcote.tech/arc-ai-voice": "^0.7.11",
-    "@arcote.tech/arc-auth": "^0.7.11",
-    "@arcote.tech/arc-ds": "^0.7.11",
-    "@arcote.tech/platform": "^0.7.11",
+    "@arcote.tech/arc": "^0.7.13",
+    "@arcote.tech/arc-ai": "^0.7.13",
+    "@arcote.tech/arc-ai-voice": "^0.7.13",
+    "@arcote.tech/arc-auth": "^0.7.13",
+    "@arcote.tech/arc-ds": "^0.7.13",
+    "@arcote.tech/platform": "^0.7.13",
     "lucide-react": ">=0.400.0",
     "react": ">=18.0.0",
     "typescript": "^5.0.0"

package/src/aggregates/message.ts

@@ -100,6 +100,13 @@ export const createMessageAggregate = <
          * otwiera SSE i streaming jest visible od pierwszego chunka.
          */
         assistantMessageId: messageId.optional(),
+        /**
+         * JSON-encoded `string[]` z fileId'ami arc-files attachmentów do tej
+         * konkretnej wiadomości. Listener AI generation ładuje `ArcFile`
+         * records i przekazuje je w `CompletionRequest.files`. Nie zapisujemy
+         * w aggregate fields — flow jest read-once przez listener z event.
+         */
+        attachmentsJson: string().optional(),
       },
       async (ctx, event) => {
         const p = event.payload;
@@ -253,6 +260,12 @@ export const createMessageAggregate = <
         scopeId,
         content: string().minLength(1),
         model: string(),
+        /**
+         * Opcjonalna JSON-encoded `string[]` z fileId'ami arc-files
+         * dołączonymi do user message. Listener AI generation ładuje
+         * pełne records po stronie serwera.
+         */
+        attachmentsJson: string().optional(),
       }).handle(
         ONLY_SERVER &&
         (async (ctx, params) => {
@@ -282,6 +295,7 @@ export const createMessageAggregate = <
             content: params.content,
             model: params.model,
             assistantMessageId: assistantMsgId,
+            attachmentsJson: params.attachmentsJson,
           });
 
           return { messageId: userMsgId, sessionId, assistantMessageId: assistantMsgId };

package/src/chat-builder.ts

@@ -55,6 +55,22 @@ export interface ChatReactComponentOptions {
 
 // ─── Chat Data ──────────────────────────────────────────────────
 
+/**
+ * Map snapshot token params (decoded payload of the token that protects this
+ * chat) to the scopeId we charge for an AI call. Consumers wire this via
+ * `.billTo(fn)`. Examples for typical setups:
+ *
+ *   .billTo(p => p.accountId)    // per-user billing
+ *   .billTo(p => p.workspaceId)  // per-workspace billing
+ *
+ * Called inside the ai-generation-listener with `ctx.$auth.params` (which
+ * is the decoded payload of the token snapshotted at `messageSent` emit
+ * time — i.e. whatever token the chat's `.protectBy(...)` is configured
+ * with). The returned string becomes the `_id` of the ledger row that gets
+ * debited.
+ */
+export type BillToFn = (tokenParams: Record<string, any>) => string;
+
 export interface ArcChatData {
   name: string;
   identifyBy: ArcId<any> | null;
@@ -67,6 +83,19 @@ export interface ArcChatData {
   tools: ArcToolAny[];
   maxExecutionCount: number;
   toolChoice: "auto" | "required" | { type: "function"; name: string };
+  alias: string | null;
+  billTo: BillToFn | null;
+  /**
+   * `arc-files` aggregate dla file attachmentów (PDF/DOCX/...) do user
+   * messages. Gdy ustawione, listener AI generation:
+   *   - ładuje `ArcFile` records po fileId'ach z `attachmentsJson` user msg,
+   *   - przekazuje je w `CompletionRequest.files`,
+   *   - po complete cachuje `boundProviderFiles` w aggregate'cie (lazy
+   *     upload do OpenAI Files API → file_id zapisany w `providerFileIdsJson`).
+   *
+   * Consumer wstrzykuje przez `.attachFiles({ File })`.
+   */
+  attachFiles: { File: any } | null;
 }
 
 const defaultChatData = {
@@ -81,6 +110,9 @@ const defaultChatData = {
   tools: [],
   maxExecutionCount: 10,
   toolChoice: "auto" as const,
+  alias: null,
+  billTo: null,
+  attachFiles: null,
 } as const satisfies ArcChatData;
 
 type DefaultChatData = typeof defaultChatData;
@@ -164,6 +196,41 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
     } as any);
   }
 
+  /**
+   * Billing alias for this chat — written to the `usageRecorded` event
+   * payload (see `@arcote.tech/arc-ai`). Defaults to chat `name`. Override
+   * when you want consistent reporting across renames or to group multiple
+   * chats under one alias for admin SQL reports.
+   *
+   *   chat("identityConsultation").alias("chat-identity")...
+   */
+  alias<const A extends string>(alias: A) {
+    return new ArcChat<Merge<Data, { alias: A }>>({
+      ...this.data,
+      alias,
+    } as any);
+  }
+
+  /**
+   * Decide which scopeId to bill for an AI call made from this chat.
+   *
+   * Called with the decoded params of the token snapshotted at `messageSent`
+   * emit time (i.e. the token used in `.protectBy(...)`). The returned string
+   * becomes the `_id` of the row in `creditLedger` that gets debited.
+   *
+   *   .billTo(p => p.accountId)    // per-user billing
+   *   .billTo(p => p.workspaceId)  // per-workspace billing
+   *
+   * Required when `.ai(...)` config has billing wired — `build()` throws
+   * otherwise. Without billing, this method is a no-op.
+   */
+  billTo(fn: BillToFn) {
+    return new ArcChat<Merge<Data, { billTo: BillToFn }>>({
+      ...this.data,
+      billTo: fn,
+    } as any);
+  }
+
   createTool<const N extends string>(name: N) {
     type IdType = Data["identifyBy"] extends ArcId<any>
       ? $type<Data["identifyBy"]>
@@ -182,6 +249,22 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
     } as any);
   }
 
+  /**
+   * Włącza obsługę file attachments dla user messages — listener AI
+   * generation będzie ładował `ArcFile` records, przekazywał je w
+   * `CompletionRequest.files`, i cachował lazy-uploadowane `file_id`'y
+   * provider'ów (OpenAI Files API).
+   *
+   *   const files = arcFiles({ name: "ndt", scopeId: workspaceId, ... });
+   *   chat("identity").attachFiles({ File: files.File }).build();
+   */
+  attachFiles(config: { File: any }): ArcChat<Data> {
+    return new ArcChat<Data>({
+      ...this.data,
+      attachFiles: config,
+    } as any);
+  }
+
   build() {
     const {
       name,
@@ -195,6 +278,9 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
       tools,
       maxExecutionCount,
       toolChoice,
+      alias: aliasOverride,
+      billTo,
+      attachFiles,
     } = this.data;
 
     if (!name) throw new Error("ArcChat: name is required");
@@ -202,6 +288,13 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
     if (!accountId) throw new Error("ArcChat: accountId is required");
     if (!userToken) throw new Error("ArcChat: userToken is required");
     if (!aiConfig) throw new Error("ArcChat: ai is required");
+    // Billing wired but no `.billTo(...)` would silently skip recordUsage —
+    // forbid that. Consumer must explicitly decide which scopeId to charge.
+    if (aiConfig.recordUsage && !billTo) {
+      throw new Error(
+        `ArcChat "${name}": ai() factory has billing wired but chat is missing .billTo(...) — declare how to map snapshot token params to a billing scope, e.g. .billTo(p => p.accountId).`,
+      );
+    }
 
     const messageId = createMessageId({ name });
 
@@ -244,16 +337,65 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
     const serverTools = tools.filter((t) => t.isServerTool);
     const interactiveTools = tools.filter((t) => t.isInteractiveTool);
 
-    // Add ledger element to mutation deps if billing configured
-    const billingElements: ArcContextElement<any>[] = [];
-    if (aiConfig.billing) {
-      for (const el of aiConfig.billing.ledger.elements) {
+    // Add usage-registry aggregate to listener mutate deps so `recordUsage`
+    // (which calls `ctx.mutate(registry).recordUsage(...)`) compiles and runs.
+    // Ledger view is a read-only projection — consumer queries it from React,
+    // listener never writes to it directly.
+    if (aiConfig.usageRegistry) {
+      for (const el of aiConfig.usageRegistry.elements) {
         if (!allMutationElements.includes(el)) allMutationElements.push(el);
         if (!allQueryElements.includes(el)) allQueryElements.push(el);
-        billingElements.push(el);
       }
     }
 
+    // Attachments bridge — gdy chat woła `.attachFiles({File})`, dodajemy
+    // File aggregate do query/mutation deps i budujemy callbacks używane
+    // przez listener do: (a) load ArcFile records dla user attachmentów,
+    // (b) cache providerFileId po lazy upload.
+    let attachmentsBridge: any;
+    if (attachFiles) {
+      const FileAgg = attachFiles.File;
+      if (!allQueryElements.includes(FileAgg)) allQueryElements.push(FileAgg);
+      if (!allMutationElements.includes(FileAgg))
+        allMutationElements.push(FileAgg);
+      attachmentsBridge = {
+        loadAttachments: async (ctx: any, fileIds: string[]) => {
+          const refs: any[] = [];
+          for (const fileId of fileIds) {
+            const rec = await ctx
+              .query(FileAgg)
+              .getById({ _id: fileId });
+            if (!rec) continue;
+            let providerFileIds: Record<string, string> = {};
+            if (typeof rec.providerFileIdsJson === "string") {
+              try {
+                const parsed = JSON.parse(rec.providerFileIdsJson);
+                if (parsed && typeof parsed === "object") providerFileIds = parsed;
+              } catch {}
+            }
+            refs.push({
+              fileId,
+              name: rec.name,
+              mime: rec.mime,
+              s3Key: rec.s3Key,
+              providerFileIds,
+            });
+          }
+          return refs;
+        },
+        bindProviderFileId: async (
+          ctx: any,
+          fileId: string,
+          provider: string,
+          providerFileId: string,
+        ) => {
+          await ctx
+            .mutate(FileAgg)
+            .bindProviderFileId({ _id: fileId, provider, providerFileId });
+        },
+      };
+    }
+
     const listenerConfig = {
       name,
       messageElement: Message,
@@ -265,6 +407,10 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
       allMutationElements,
       maxExecutionCount,
       toolChoice: toolChoice !== "auto" ? toolChoice : undefined,
+      alias: aliasOverride ?? name,
+      recordUsage: aiConfig.recordUsage,
+      billTo: billTo ?? undefined,
+      attachments: attachmentsBridge,
     };
 
     const aiListener = createAiGenerationListener(listenerConfig);

package/src/listeners/ai-generation-listener.ts

@@ -1,8 +1,10 @@
 /// <reference path="../arc.d.ts" />
 import { listener, type ArcContextElement, type ArcFunction } from "@arcote.tech/arc";
 import type {
+  ArcFileRef,
   ArcToolAny,
   AssistantContentBlock,
+  BoundProviderFile,
   Conversation,
   ConversationTurn,
   LLMProvider,
@@ -28,6 +30,60 @@ export interface AiGenerationListenerConfig {
   allMutationElements: ArcContextElement<any>[];
   maxExecutionCount: number;
   toolChoice?: "auto" | "required" | { type: "function"; name: string };
+  /**
+   * Billing alias for this chat — written to the `usageRecorded` event
+   * payload so admin reports can attribute cost back to which chat (e.g.
+   * `"chat-identity"`, `"chat-create-content"`). Defaults to `name` if the
+   * builder didn't override via `.alias(...)`.
+   */
+  alias?: string;
+  /**
+   * Optional billing hook from `ai()` factory. Called after every
+   * `completeAssistantTurn` (each turn, including those that close with
+   * tool calls) so the credit ledger view sees consistent usage events.
+   * No-op when undefined (ai() built without `billing` config).
+   */
+  recordUsage?: (
+    ctx: any,
+    params: {
+      scopeId: string;
+      alias: string;
+      model: string;
+      usage: import("@arcote.tech/arc-ai").TokenUsage;
+      metadata?: Record<string, unknown>;
+    },
+  ) => Promise<void>;
+  /**
+   * Consumer-supplied function from chat-builder's `.billTo(...)` — maps
+   * decoded params of the chat's protection token (snapshotted at
+   * `messageSent` emit time) to the ledger scopeId we charge. Required when
+   * `recordUsage` is set (chat-builder enforces this at build time), so the
+   * listener can treat the pair as always-present in the call site.
+   */
+  billTo?: (tokenParams: Record<string, any>) => string;
+  /**
+   * Wiązanie z fragmentem `arc-files` — wstrzykiwany przez chat-builder gdy
+   * consumer woła `.attachFiles({ File })`.
+   *
+   *  - `loadAttachments(fileIds)` — ładuje `ArcFile` records po fileId'ach
+   *    (dla `request.files`); zwracamy ArcFileRef z aktualnymi
+   *    `providerFileIds` z DB.
+   *  - `bindProviderFileId(fileId, provider, providerFileId)` — wywoływane
+   *    dla każdego `BoundProviderFile` zwróconego przez adapter (cache
+   *    lazy uploadu — przy następnej generacji pomijamy upload).
+   */
+  attachments?: {
+    loadAttachments(
+      ctx: any,
+      fileIds: string[],
+    ): Promise<ArcFileRef[]>;
+    bindProviderFileId(
+      ctx: any,
+      fileId: string,
+      provider: string,
+      providerFileId: string,
+    ): Promise<void>;
+  };
 }
 
 // ─── History reconstruction ─────────────────────────────────────
@@ -195,6 +251,18 @@ interface RunLoopConfig {
    *  lecieć. Następne iteracje (multi-turn po server tool exec) tworzą fresh
    *  rows. */
   preCreatedAssistantMessageId?: string;
+  /** Billing alias — written to `usageRecorded` event payload. Optional;
+   *  no-op when paired `recordUsage` is undefined. */
+  alias?: string;
+  /** Billing hook — see `AiGenerationListenerConfig.recordUsage`. */
+  recordUsage?: AiGenerationListenerConfig["recordUsage"];
+  /** Token-params → scopeId mapper from chat-builder `.billTo(...)`. */
+  billTo?: AiGenerationListenerConfig["billTo"];
+  /** Attachments bridge — see `AiGenerationListenerConfig.attachments`. */
+  attachments?: AiGenerationListenerConfig["attachments"];
+  /** ArcFile records dla attachmentów ostatniego user msg (resolved przed
+   *  generation start; reused per loop iteration). */
+  initialAttachments?: ArcFileRef[];
 }
 
 async function runGenerationLoop(config: RunLoopConfig) {
@@ -272,6 +340,13 @@ async function runGenerationLoop(config: RunLoopConfig) {
       // robi nic.
       startStream(currentTurnId!);
 
+      // Files lecą TYLKO w pierwszej iteracji. Provider z continuation
+      // (OpenAI Responses) trzyma context server-side; provider w full
+      // mode (Claude/Gemini) ignoruje files z warningiem — i tak nie
+      // ma sensu duplikować attachmentów w każdym tool_result roundzie.
+      const filesForRequest =
+        executionCount === 0 ? config.initialAttachments : undefined;
+
       const result = await provider.streamComplete(
         {
           model,
@@ -282,6 +357,9 @@ async function runGenerationLoop(config: RunLoopConfig) {
           // Skraca time-to-first-token dla gpt-5 / o-series — pomija reasoning
           // step. Adaptery bez wsparcia ignorują.
           reasoningEffort: "minimal",
+          ...(filesForRequest && filesForRequest.length > 0
+            ? { files: filesForRequest }
+            : {}),
         },
         (chunk) => {
           if (chunk.type === "text_delta" && chunk.textDelta) {
@@ -318,6 +396,32 @@ async function runGenerationLoop(config: RunLoopConfig) {
         },
       );
 
+      // Cache lazy-uploaded provider file IDs w ArcFile aggregate — żeby
+      // kolejne generacje (i odnowiona historia) pomijały re-upload.
+      if (
+        config.attachments &&
+        result.boundProviderFiles &&
+        result.boundProviderFiles.length > 0
+      ) {
+        for (const bound of result.boundProviderFiles) {
+          try {
+            await config.attachments.bindProviderFileId(
+              ctx,
+              bound.fileId,
+              bound.provider,
+              bound.providerFileId,
+            );
+          } catch (err) {
+            // Best-effort cache — failure tu nie psuje turn'u, tylko
+            // następny request uploadowi plik ponownie.
+            console.warn(
+              "[arc-chat] attachments.bindProviderFileId failed:",
+              err,
+            );
+          }
+        }
+      }
+
       // Append to local history so the next iteration sees this turn.
       const assistantTurn: ConversationTurn = {
         role: "assistant",
@@ -339,15 +443,46 @@ async function runGenerationLoop(config: RunLoopConfig) {
 
       // Close the turn row — same row that was opened above. Final blocks
       // are the SINGLE persistent write of message content in this turn.
-      // Intermediate turns (gdy mamy tool calls) carry blocks + responseId;
-      // ostatni turn nosi też usage.
+      // Usage zapisywane ZAWSZE (intermediate tool turns też zużywają tokeny
+      // i muszą być rozliczone w `recordUsage` poniżej; klient dostaje pełen
+      // history of cost per turn from message rows).
       await ctx.mutate(messageElement).completeAssistantTurn({
         messageId: currentTurnId!,
         blocks: JSON.stringify(result.blocks),
         previousResponseId: result.responseId,
-        usage: hasToolCalls ? undefined : JSON.stringify(result.usage),
+        usage: JSON.stringify(result.usage),
       });
 
+      // Billing hook — emit usageRecorded event for the credit ledger view.
+      // Called after `completeAssistantTurn` so the message row exists in DB
+      // before its cost is attributed.
+      //
+      // chat-builder enforces `.billTo()` is present whenever `recordUsage`
+      // is wired, so the only legitimate "skip" path is "billing not
+      // configured at all" — both undefined. We still guard defensively.
+      if (config.recordUsage && config.alias && config.billTo) {
+        const billingScopeId = config.billTo(
+          ((ctx as any).$auth?.params as Record<string, any>) ?? {},
+        );
+        try {
+          await config.recordUsage(ctx, {
+            scopeId: billingScopeId,
+            alias: config.alias,
+            model,
+            usage: result.usage,
+            metadata: {
+              messageId: currentTurnId!,
+              sessionId,
+              turnIndex: executionCount,
+              chatScopeId: scopeId,
+            },
+          });
+        } catch (err) {
+          // Best-effort: billing failure shouldn't break generation.
+          console.error("[arc-chat] recordUsage failed:", err);
+        }
+      }
+
       // Tear down the in-memory stream: broadcast `done` do subscriberów,
       // close controllery, drop registry entry po grace window. Klient z
       // `done` flippuje isStreaming=false i renderuje final blocks z DB.
@@ -501,6 +636,14 @@ export function createAiGenerationListener(config: AiGenerationListenerConfig) {
       const newTurnsStartIdx = history.length;
       history.push({ role: "user", content: userContent });
 
+      // Załaduj ArcFile records dla attachmentów ostatniego user msg
+      // (jeśli consumer wired `attachments` bridge przez `.attachFiles({File})`).
+      const initialAttachments = await resolveAttachments(
+        ctx,
+        config.attachments,
+        (event.payload as { attachmentsJson?: string }).attachmentsJson,
+      );
+
       await runGenerationLoop({
         ctx,
         messageElement,
@@ -516,6 +659,11 @@ export function createAiGenerationListener(config: AiGenerationListenerConfig) {
         maxExecutionCount,
         toolChoice: config.toolChoice,
         instruction,
+        alias: config.alias,
+        recordUsage: config.recordUsage,
+        billTo: config.billTo,
+        attachments: config.attachments,
+        initialAttachments,
         preCreatedAssistantMessageId: (
           event.payload as { assistantMessageId?: string }
         ).assistantMessageId,
@@ -523,6 +671,36 @@ export function createAiGenerationListener(config: AiGenerationListenerConfig) {
     });
 }
 
+/**
+ * Parsuje `attachmentsJson` (string[] fileIds) i deleguje do
+ * `attachments.loadAttachments(...)`. Brak attachments bridge ALBO brak
+ * JSON ALBO pusta lista → zwraca undefined (request bez `files`).
+ */
+async function resolveAttachments(
+  ctx: any,
+  attachments: AiGenerationListenerConfig["attachments"],
+  attachmentsJson: string | undefined,
+): Promise<ArcFileRef[] | undefined> {
+  if (!attachments || !attachmentsJson) return undefined;
+  let fileIds: string[] = [];
+  try {
+    const parsed = JSON.parse(attachmentsJson);
+    if (Array.isArray(parsed)) {
+      fileIds = parsed.filter((x): x is string => typeof x === "string");
+    }
+  } catch {
+    return undefined;
+  }
+  if (fileIds.length === 0) return undefined;
+  try {
+    const refs = await attachments.loadAttachments(ctx, fileIds);
+    return refs.length > 0 ? refs : undefined;
+  } catch (err) {
+    console.warn("[arc-chat] attachments.loadAttachments failed:", err);
+    return undefined;
+  }
+}
+
 // ─── Listener B: userResponded → AI resume ──────────────────────
 
 export function createAiResumeListener(config: AiGenerationListenerConfig) {
@@ -596,6 +774,10 @@ export function createAiResumeListener(config: AiGenerationListenerConfig) {
         maxExecutionCount,
         toolChoice: config.toolChoice,
         instruction,
+        alias: config.alias,
+        recordUsage: config.recordUsage,
+        billTo: config.billTo,
+        attachments: config.attachments,
         preCreatedAssistantMessageId: (
           event.payload as { assistantMessageId?: string }
         ).assistantMessageId,
@@ -688,6 +870,9 @@ export function createAiRetryListener(config: AiGenerationListenerConfig) {
         maxExecutionCount,
         toolChoice: config.toolChoice,
         instruction,
+        alias: config.alias,
+        recordUsage: config.recordUsage,
+        billTo: config.billTo,
         preCreatedAssistantMessageId: assistantMsgId,
       });
     });

package/src/react/chat-component.tsx

@@ -622,6 +622,9 @@ export function createChatComponent(
             scopeId,
             content,
             model: options.model,
+            ...(options.attachments && options.attachments.length > 0
+              ? { attachmentsJson: JSON.stringify(options.attachments) }
+              : {}),
           });
           // Reszta dzieje się przez auto-subscribe effect powyżej: mutacja
           // emit'uje `assistantTurnStarted` → DB query pushuje fresh assistant