@opencxh/domain 1.135.0 → 1.137.0

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`.
@@ -107,6 +155,31 @@ export interface AiToolDescriptor extends AiTool {
 export interface AiToolInvokeRequest {
     tool: string;
     arguments?: Record<string, unknown>;
+    /**
+     * Wat er in déze beurt al gebeurd is, voor een tool die niet alleen zijn eigen
+     * argumenten nodig heeft maar ook de context waarin hij wordt aangeroepen.
+     *
+     * Optioneel en additief, net als de extra velden op {@link AiToolDescriptor}:
+     * een tool die dit negeert gedraagt zich exact als voorheen.
+     *
+     * De aanleiding is bronvermelding die klopt. De runner verzamelt al de
+     * {@link ToolSource}s van álle tools in een beurt, maar het invoke-contract
+     * droeg alleen `{tool, arguments}` — dus een tool die iets *bewaart* (een
+     * artefact, een geheugen-item) kon niet vastleggen waar het uit is opgebouwd.
+     * Het model ernaar laten raden levert verzonnen bronvermelding op, precies wat
+     * `ToolSource` moest voorkomen.
+     */
+    turn?: AiToolTurnContext;
+}
+/** Zie {@link AiToolInvokeRequest.turn}. */
+export interface AiToolTurnContext {
+    /** Het gesprek waarin deze beurt loopt, als er een is. */
+    conversationId?: string;
+    /**
+     * Wat er tot nu toe in deze beurt is geraadpleegd, ontdubbeld. Bevat **niet**
+     * de resultaten van deze call zelf — die bestaan nog niet.
+     */
+    sources?: ToolSource[];
 }
 /** One step in the assistant's tool-use trace, persisted on the message. */
 export interface ToolTraceEntry {

package/package.json

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