@opencxh/domain 1.134.14 → 1.136.0

package/dist/platform/ai-attachments.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Files the assistant can be handed.
+ *
+ * The ask pipeline was text-only in name as well as in fact — `AIMessageInput`
+ * declared `type: "text"` and nothing ever set anything else. This is the shape
+ * that widens it, plus the two things every caller has to agree on: which
+ * formats survive, and how big they may be.
+ *
+ * Deliberately no parsing here. Anthropic, OpenAI and Gemini all accept images
+ * and PDFs directly, so the bytes go to the model and there is no document
+ * extractor to own. Office formats are the price of that: no vendor takes a
+ * `.docx`, so we say so instead of failing quietly.
+ */
+/** What we can do with a file, decided by its mime type. */
+export type AIAttachmentKind = 
+/** Sent as image content; the model actually sees it. */
+"image"
+/** Sent as a document; the model reads the pages. */
+ | "pdf"
+/** Inlined into the prompt as text. */
+ | "text"
+/** Has a route, but not this one — the existing transcription path. */
+ | "audio"
+/** No vendor accepts it and we do not extract it. */
+ | "unsupported";
+/**
+ * Classify a file. Matches on the full mime type rather than a prefix: `image/*`
+ * would wave through `image/tiff` and `image/heic`, which no vendor accepts and
+ * which are common enough coming off a phone to matter.
+ */
+export declare function aiAttachmentKind(mimeType: string | undefined | null): AIAttachmentKind;
+/**
+ * Ceilings, in bytes of the decoded file.
+ *
+ * Two reasons these are low. Vendors cap individual parts (images around 5MB,
+ * PDFs far larger but slow), and base64 adds a third on top of whatever we send.
+ * But the binding reason is {@link AI_ATTACHMENT_TURN_BUDGET}: Anthropic and
+ * Gemini are stateless, so everything still in the history is re-uploaded on
+ * every single turn of the conversation.
+ */
+export declare const AI_ATTACHMENT_LIMITS: Record<Exclude<AIAttachmentKind, "unsupported">, number>;
+/**
+ * Total decoded bytes any single turn may carry to the model.
+ *
+ * This is the number that keeps a long conversation from becoming expensive:
+ * attachments from earlier turns are re-hydrated only while they fit under this,
+ * oldest dropped first. What falls outside becomes a text placeholder, so the
+ * model is told a file was there rather than being left to assume it never was.
+ */
+export declare const AI_ATTACHMENT_TURN_BUDGET: number;
+/** How many attachments one turn may carry, regardless of size. */
+export declare const AI_ATTACHMENT_MAX_PER_TURN = 5;
+/**
+ * Where the bytes come from.
+ *
+ * `inline` exists only on the way in — a file the user just picked. It is never
+ * persisted: storing base64 on the message would bloat the row and, worse, make
+ * the history re-send it forever. The other two are references the server can
+ * re-read on demand, which is why "attach something already in the product"
+ * costs nothing to keep.
+ */
+export type AIAttachmentSource = 
+/** Base64 of the file, for this request only. */
+{
+    kind: "inline";
+    data: string;
+}
+/** An attachment on a communication activity (a mail attachment). */
+ | {
+    kind: "activity";
+    activityId: string;
+    attachmentId: string;
+}
+/** A file in the storage app. */
+ | {
+    kind: "storage";
+    fileId: string;
+}
+/**
+ * The bytes are gone: an inline file that has been persisted, or one dropped
+ * to stay inside the turn budget. Kept rather than removed so the model and
+ * the UI can both say "there was a file here".
+ */
+ | {
+    kind: "expired";
+};
+export interface AIAttachment {
+    filename: string;
+    mimeType: string;
+    /** Decoded size in bytes. Set by the client for `inline`, by the server otherwise. */
+    size: number;
+    source: AIAttachmentSource;
+}
+/** An attachment the server has resolved to actual bytes, ready for an adapter. */
+export interface ResolvedAIAttachment {
+    filename: string;
+    mimeType: string;
+    kind: Exclude<AIAttachmentKind, "unsupported">;
+    /** Base64 of the file — what every vendor's inline-data field wants. */
+    data: string;
+    size: number;
+}
+/** Why an attachment did not make it to the model. */
+export interface RejectedAIAttachment {
+    filename: string;
+    reason: "unsupported" | "too-large" | "unreadable" | "over-budget" | "too-many";
+}
+/**
+ * Is this file acceptable at all? Checked on both sides: the client refuses
+ * before uploading, the server refuses before spending a model call. Size is in
+ * decoded bytes.
+ */
+export declare function aiAttachmentRejection(mimeType: string, size: number): RejectedAIAttachment["reason"] | null;

package/dist/platform/ai-attachments.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/platform/ai-tools.d.ts

@@ -44,11 +44,59 @@ export interface AiToolCall {
     name: string;
     arguments: Record<string, unknown>;
 }
+/**
+ * Something a tool read, so the answer can say where it looked.
+ *
+ * A tool's `content` is prose written for the model, which means the provenance
+ * inside it — an article id, a conversation title — is only recoverable by
+ * parsing text the tool is free to reformat. This is the same information handed
+ * over as data instead.
+ *
+ * These are the things that were **consulted**, not a claim about which ones the
+ * answer leaned on: a search that returns five articles returns five sources
+ * whether the model used one of them or all five. Label them accordingly in the
+ * UI; asking the model to cite would be more precise and less trustworthy,
+ * because a model will invent a reference.
+ */
+export interface ToolSource {
+    /**
+     * What sort of thing this is, e.g. `"kb-article"`, `"memory"`, `"interaction"`.
+     * Open string: an app may cite something the platform has no notion of, and a
+     * closed union would need a domain change per app.
+     */
+    kind: string;
+    /** Shown to the user. */
+    title: string;
+    /** Stable id within its kind, when there is one. */
+    id?: string;
+    /** A second line: a snippet, a date, an author. */
+    detail?: string;
+    /**
+     * Shell-absolute in-product route, including the `/apps/<app>` prefix — the
+     * source may well belong to a different app than the one showing it.
+     *
+     * Follow it with the **kernel** router (`sdk` from `@opencxh/app-sdk`), not an
+     * app's own: `createApp().router.navigate` prefixes the calling app's id, which
+     * would turn `/apps/kb/…` into `/apps/ai/apps/kb/…`.
+     *
+     * Absent when the thing has no page of its own — a memory item, for instance —
+     * which is a reason to show it without a link, not a reason to hide it.
+     */
+    url?: string;
+}
 /** The result of executing a tool call, fed back to the model. */
 export interface AiToolResult {
     id: string;
     content: string;
     isError?: boolean;
+    /**
+     * What this call read. Optional and additive, like the fields on
+     * {@link AiToolDescriptor}: a tool that sets nothing behaves exactly as before.
+     *
+     * Persisted for free — `ToolTraceEntry.result` already rides along on the
+     * stored `AIMessage`, so the thread keeps its provenance without a new entity.
+     */
+    sources?: ToolSource[];
 }
 /**
  * Returned by an app's `GET /provider/ai-tools/describe`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencxh/domain",
-  "version": "1.134.14",
+  "version": "1.136.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",