@tagit/ai-client-core 1.7.0-beta.54.1 → 1.7.0-beta.56.2

package/README.md

@@ -1,14 +1,14 @@
 # @tagit/ai-client-core
 
-Headless TypeScript client core for the tagIt AI orchestrator.
+Headless TypeScript client core for the Knotiv AI Orchestrator.
 
 Use this package when you want to talk to the orchestrator directly and manage your own UI. It owns request shaping, streaming, retries, cancellation, conversation state, and optional collector emission.
 
 This README is the source of truth for the core package.
 
-## What Is tagIt?
+## What Is Knotiv?
 
-tagIt is the platform for building governed AI experiences. It gives teams a way to define AI use cases, connect models, optionally attach MCP servers, and shape the orchestration logic that drives the overall experience.
+Knotiv is the platform for building governed AI experiences. It gives teams a way to define AI use cases, connect models, optionally attach MCP servers, and shape the orchestration logic that drives the overall experience.
 
 ## What Is the AI Orchestrator?
 
@@ -16,11 +16,11 @@ The AI Orchestrator is the runtime layer that executes a use case. It combines t
 
 ## Why This Package Exists
 
-`@tagit/ai-client-core` is the client-side engine that connects your app to a tagIt account and a configured AI Orchestrator. You need a tagIt account and at least one configured use case before this package can drive a real experience.
+`@tagit/ai-client-core` is the client-side engine that connects your app to a Knotiv account and a configured AI Orchestrator. You need a Knotiv account and at least one configured Agent before this package can drive a real experience.
 
 MCP servers are optional, but they can extend the orchestrator with tools and external capabilities.
 
-To learn more about tagIt and the orchestrator setup, visit [tagit.live](https://tagit.live).
+To learn more about Knotiv and Orchestrator setup, visit [knotiv.com](https://knotiv.com).
 
 ## What This Package Provides
 
@@ -54,7 +54,7 @@ npm install @tagit/ai-client-core
 import { AIClient, createDefaultConfig } from '@tagit/ai-client-core';
 
 const client = new AIClient(
-  createDefaultConfig('uc-default-1lji40', 'https://ai.tagit.live', {
+  createDefaultConfig('uc-default-1lji40', window.location.origin, {
     user: {
       entityId: 'anonymous-or-authenticated-user-id',
       userId: 'optional-friendly-user-id',
@@ -67,11 +67,6 @@ const client = new AIClient(
       title: 'Optional conversation title',
       memoryMaxTurns: 6,
     },
-    conversationHistory: {
-      enabled: true,
-      surface: '/optional/page-or-product-surface',
-      recentLimit: 5,
-    },
     agents: [
       {
         useCaseId: 'uc-default-1lji40',
@@ -79,9 +74,6 @@ const client = new AIClient(
         description: 'General product help.',
       },
     ],
-    orchestrator: {
-      apiKey: import.meta.env.VITE_TAGIT_AI_ORCHESTRATOR_API_KEY,
-    },
     collector: {
       enabled: false,
     },
@@ -89,6 +81,12 @@ const client = new AIClient(
 );
 ```
 
+This browser example calls your application's same-origin `POST /v2/chat`
+route. That route authenticates the caller, selects or validates the permitted
+Agent, and forwards the request to Knotiv with the server-only API key. Do not
+put an Orchestrator API key in `VITE_*`, `NEXT_PUBLIC_*`, or any other
+browser-readable environment variable.
+
 ## Core Concepts
 
 ### `AIClient`
@@ -123,7 +121,7 @@ The core client is driven by a validated `ClientConfig`. If a field is omitted,
 This helper builds a safe starting config.
 
 ```ts
-const config = createDefaultConfig('uc-default-1lji40', 'https://ai.tagit.live', {
+const config = createDefaultConfig('uc-default-1lji40', window.location.origin, {
   collector: {
     enabled: false,
   },
@@ -133,11 +131,12 @@ const config = createDefaultConfig('uc-default-1lji40', 'https://ai.tagit.live',
 | Field | Type / values | Default | What it does | Example |
 |---|---|---:|---|---|
 | `useCaseId` | `string` | required | Runtime use case identifier used by the orchestrator. | `'uc-default-1lji40'` |
-| `orchestratorUrl` | URL string | required | Base URL for the orchestrator. Do not include `/v2/chat`. | `'https://ai.tagit.live'` |
-| `options.orchestrator` | partial orchestrator config | `undefined` | Overrides specific orchestrator fields. | `{ apiKey: '...' }` |
+| `orchestratorUrl` | URL string | required | Base URL for the request path. In browser code, use your application's same-origin origin. Do not include `/v2/chat`. | `window.location.origin` |
+| `options.orchestrator` | partial orchestrator config | `undefined` | Overrides specific orchestrator fields. | `{ timeoutMs: 30000 }` |
 | `options.user` | user identity config | `undefined` | Shared identity used by orchestrator memory and collector events. | `{ entityId: 'user_123' }` |
 | `options.conversation` | conversation config | `undefined` | Durable conversation id, title, and memory window. | `{ memoryMaxTurns: 6 }` |
 | `options.conversationHistory` | history config | `undefined` | Enables durable list/load and lifecycle APIs. | `{ enabled: true }` |
+| `options.resources` | resource workspace config | `undefined` | Enables private file upload, selection, and conversation attachments through a host-authenticated transport. | `{ enabled: true, transport }` |
 | `options.agents` | `AgentOption[]` | `undefined` | Optional host-authorized agents available to this client instance. | `[{ useCaseId, name }]` |
 | `options.defaultUseCaseId` | string | `undefined` | Initial active agent when `agents` is supplied. | `'uc-support'` |
 | `options.onActiveAgentChange` | function | `undefined` | Callback when the initial or selected agent becomes active. | `(agent) => setAgent(agent)` |
@@ -151,7 +150,7 @@ Use `agents` when one embedded client should let the user switch between multipl
 
 ```ts
 const client = new AIClient(
-  createDefaultConfig('uc-platform-help', 'https://ai.tagit.live', {
+  createDefaultConfig('uc-platform-help', window.location.origin, {
     agents: [
       {
         useCaseId: 'uc-platform-help',
@@ -185,7 +184,7 @@ The SDK calls the resolver immediately before each send. The host decides what v
 
 ```ts
 const client = new AIClient(
-  createDefaultConfig('uc-platform-help', 'https://ai.tagit.live', {
+  createDefaultConfig('uc-platform-help', window.location.origin, {
     user: { entityId: currentUser.uid, userId: currentUser.uid },
     agents,
     resolveRequestOptions(agent, context) {
@@ -250,15 +249,72 @@ When `conversationHistory.enabled` is `true`, the client must be able to resolve
 | `conversationHistory.newConversationId` | function | no | Custom durable conversation id generator. | `() => crypto.randomUUID()` |
 | `conversationHistory.transport` | `ConversationHistoryTransport` | no | Custom history transport. Constructor transport option takes precedence. | `customTransport` |
 
+### Private Resource Workspace Config
+
+`resources` enables governed private files and conversation attachments. The
+host remains responsible for authentication and Workspace selection. The SDK
+never accepts a user ID, account ID, or Workspace ID from the model.
+
+Use `FetchConversationResourceTransport` with a short-lived signed-in user
+token, or provide a custom server-backed `ConversationResourceTransport`.
+
+```ts
+import {
+  AIClient,
+  FetchConversationResourceTransport,
+  createDefaultConfig,
+} from '@tagit/ai-client-core';
+
+const resourceTransport = new FetchConversationResourceTransport({
+  baseUrl: 'https://beta.knotiv.com',
+  accountId,
+  contextId: workspaceId,
+  headers: async () => ({
+    Authorization: `Bearer ${await currentUser.getIdToken()}`,
+  }),
+});
+
+const client = new AIClient(
+  createDefaultConfig(useCaseId, orchestratorUrl, {
+    user: { entityId: currentUser.uid, userId: currentUser.uid },
+    resources: {
+      enabled: true,
+      transport: resourceTransport,
+      allowUpload: true,
+      allowPicker: true,
+      maxSelected: 5,
+    },
+  }),
+);
+```
+
+Supported uploads are TXT, Markdown, CSV, JSON, and PDF. The orchestrator
+accepts at most ten resource references per request. Storage buckets and object
+paths are never included in chat requests.
+
+| Field | Type / values | Required | What it does |
+|---|---|---:|---|
+| `resources.enabled` | `boolean` | yes | Enables the resource APIs and UI capability. |
+| `resources.transport` | `ConversationResourceTransport` | yes unless supplied to the constructor | Performs authenticated upload, list, attach, and detach operations. |
+| `resources.allowUpload` | `boolean` | no | Shows upload controls in the stock React UI. |
+| `resources.allowPicker` | `boolean` | no | Shows the recent private resource picker. |
+| `resources.acceptedMimeTypes` | file input accept string | no | Narrows the browser file picker. |
+| `resources.maxSelected` | integer from 1 to 10 | no | Limits attachments selected for a conversation. |
+
+Custom shells can call `listResources()`, `uploadResource()`,
+`listResourceAttachments()`, `attachResource()`, and `detachResource()` on the
+client. Pass selected references through `sendMessage(message, {
+resourceReferences })`.
+
 ### Orchestrator Config
 
 `orchestrator.baseUrl` should point to the orchestrator root URL, not `/v2/chat`. The client appends `/v2/chat` internally.
 
 | Field | Type / values | Required | What it does | Example |
 |---|---|---:|---|---|
-| `orchestrator.baseUrl` | URL string | yes | Base URL for the orchestrator. | `https://ai.tagit.live` |
+| `orchestrator.baseUrl` | URL string | yes | Base URL for the request path. In browser code, use your application's same-origin origin. | `window.location.origin` |
 | `orchestrator.useCaseId` | string | yes | Runtime use case ID to execute. | `uc-default-1lji40` |
-| `orchestrator.apiKey` | string | no | Optional API key sent as `X-Api-Key`. | `import.meta.env.VITE_TAGIT_AI_ORCHESTRATOR_API_KEY` |
+| `orchestrator.apiKey` | string | no | Server-only API key sent as `X-Api-Key`. Do not set it in browser-delivered code. | `process.env.KNOTIV_ORCHESTRATOR_API_KEY` |
 | `orchestrator.snapshotId` | string | no | Pins the client to a specific orchestration snapshot. | `snapshot_2026_04_14` |
 | `orchestrator.timeoutMs` | positive integer | no | Request timeout in milliseconds. | `30000` |
 | `orchestrator.maxRetries` | nonnegative integer | no | Number of retry attempts for transient failures. | `3` |
@@ -488,6 +544,56 @@ const transport: OrchestratorTransport = {
 };
 ```
 
+## Browser integration
+
+For a browser application, the supported request path is:
+
+```text
+Browser -> same-origin application route -> Knotiv Orchestrator
+```
+
+The application's route keeps the Knotiv API key on the server and is
+responsible for authenticating its user, authorizing the Agent, accepting only
+approved runtime context, and proxying the normal or streamed response. The
+browser should configure `baseUrl` as `window.location.origin` and should not
+set `orchestrator.apiKey`.
+
+For local Vite development, a proxy can make the local application route look
+same-origin while the proxy adds the server-only key. This is a development
+convenience, not a production credential boundary:
+
+```ts
+// vite.config.ts
+import { defineConfig, loadEnv } from 'vite';
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), '');
+
+  return {
+    server: {
+      proxy: {
+        '/v2': {
+          target: env.KNOTIV_ORCHESTRATOR_BASE_URL,
+          changeOrigin: true,
+          headers: {
+            'X-Api-Key': env.KNOTIV_ORCHESTRATOR_API_KEY,
+          },
+        },
+      },
+    },
+  };
+});
+```
+
+Keep `KNOTIV_ORCHESTRATOR_API_KEY` in `.env.local` or another server-only
+secret store. Do not prefix it with `VITE_`.
+
+For production, implement an authenticated same-origin route that fixes the
+permitted Agent and user identity on the server, validates incoming runtime
+context, and forwards the response stream. The [AI Client guide](https://knotiv.gitbook.io/knotiv/embed-and-integrate/ai-client)
+includes a Next.js route example. If you enable conversation history, provide
+authenticated `/v2/conversations` routes too.
+
 ## Related Package
 
 If you want the full embeddable React widget, install:

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AgentListUpdateOptions, AgentListUpdateResult, AgentOption, ClientConfig, ClientEventListener, ConversationHistoryCreateOptions, ConversationHistoryListOptions, ConversationHistoryListResult, ConversationHistoryLifecycleOptions, ConversationHistoryLoadOptions, ConversationHistoryMessagesResult, ConversationHistoryTransport, ConversationHistoryUpdateOptions, ConversationSummary, ConversationState, SendMessageOptions } from './types.js';
+import type { AgentListUpdateOptions, AgentListUpdateResult, AgentOption, ClientConfig, ClientEventListener, ConversationHistoryCreateOptions, ConversationHistoryListOptions, ConversationHistoryListResult, ConversationHistoryLifecycleOptions, ConversationHistoryLoadOptions, ConversationHistoryMessagesResult, ConversationHistoryTransport, ConversationResource, ConversationResourceReference, ConversationResourceTransport, ConversationResourceUpload, ConversationHistoryUpdateOptions, ConversationSummary, ConversationState, SendMessageOptions } from './types.js';
 import { type OrchestratorTransport } from './transport.js';
 /**
  * Headless AI client core
@@ -12,11 +12,13 @@ export declare class AIClient {
     private abortReason;
     private transport;
     private conversationHistoryTransport;
+    private conversationResourceTransport;
     private createdConversationIds;
     private activeAgentGeneration;
     constructor(config: ClientConfig, options?: {
         transport?: OrchestratorTransport;
         conversationHistoryTransport?: ConversationHistoryTransport;
+        conversationResourceTransport?: ConversationResourceTransport;
     });
     private resolveConfiguredDefaultAgentId;
     private cloneAgent;
@@ -40,6 +42,19 @@ export declare class AIClient {
         allowDelete: boolean;
         allowRestore: boolean;
     };
+    getConversationResourceCapabilities(): {
+        enabled: boolean;
+        allowUpload: boolean;
+        allowPicker: boolean;
+        acceptedMimeTypes: string;
+        maxSelected: number;
+    };
+    private requireConversationResourceTransport;
+    listResources(): Promise<ConversationResource[]>;
+    uploadResource(input: ConversationResourceUpload): Promise<ConversationResource>;
+    listResourceAttachments(conversationId?: string): Promise<ConversationResourceReference[]>;
+    attachResource(resourceId: string, conversationId?: string): Promise<ConversationResourceReference>;
+    detachResource(resourceId: string, conversationId?: string): Promise<void>;
     /**
      * Subscribe to client events
      */

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -8,6 +8,32 @@ import { StreamSession } from './stream-session.js';
 function generateId() {
     return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
 }
+function resolveLifecycleErrorResponse(errorBody) {
+    try {
+        const payload = JSON.parse(errorBody);
+        const errorCode = typeof payload.error?.code === 'string'
+            ? payload.error.code
+            : typeof payload.code === 'string'
+                ? payload.code
+                : undefined;
+        if (errorCode === 'use_case_inactive') {
+            return {
+                errorCode,
+                safeMessage: 'This agent is currently disabled. Ask an authorized operator to enable it before trying again.',
+            };
+        }
+        if (errorCode === 'use_case_archived') {
+            return {
+                errorCode,
+                safeMessage: 'This agent is archived and cannot receive new requests.',
+            };
+        }
+        return { errorCode };
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Headless AI client core
  * Handles orchestrator communication, streaming, and conversation state
@@ -56,6 +82,12 @@ export class AIClient {
             writable: true,
             value: null
         });
+        Object.defineProperty(this, "conversationResourceTransport", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
         Object.defineProperty(this, "createdConversationIds", {
             enumerable: true,
             configurable: true,
@@ -76,6 +108,8 @@ export class AIClient {
                 (this.config.conversationHistory?.enabled
                     ? new FetchConversationHistoryTransport(this.buildConversationHistoryTransportContext())
                     : null);
+        this.conversationResourceTransport =
+            options?.conversationResourceTransport ?? this.config.resources?.transport ?? null;
         const initialUseCaseId = this.resolveConfiguredDefaultAgentId(this.config);
         this.config.orchestrator.useCaseId = initialUseCaseId;
         const initialConversationId = this.config.conversation?.conversationId?.trim() ||
@@ -246,6 +280,43 @@ export class AIClient {
             allowRestore: history?.allowRestore !== false,
         };
     }
+    getConversationResourceCapabilities() {
+        const resources = this.config.resources;
+        return {
+            enabled: resources?.enabled === true && this.conversationResourceTransport !== null,
+            allowUpload: resources?.allowUpload !== false,
+            allowPicker: resources?.allowPicker !== false,
+            acceptedMimeTypes: resources?.acceptedMimeTypes ||
+                'text/plain,text/markdown,text/csv,application/json,application/pdf',
+            maxSelected: Math.min(10, Math.max(1, resources?.maxSelected ?? 10)),
+        };
+    }
+    requireConversationResourceTransport() {
+        if (!this.config.resources?.enabled || !this.conversationResourceTransport) {
+            throw this.createError({
+                code: 'CONFIG_ERROR',
+                message: 'Conversation resources require resources.enabled and an authenticated transport',
+                safeMessage: 'Resource workspace is not configured.',
+                retryable: false,
+            });
+        }
+        return this.conversationResourceTransport;
+    }
+    listResources() {
+        return this.requireConversationResourceTransport().listResources();
+    }
+    uploadResource(input) {
+        return this.requireConversationResourceTransport().uploadResource(input);
+    }
+    listResourceAttachments(conversationId = this.resolveConversationId()) {
+        return this.requireConversationResourceTransport().listAttachments(conversationId);
+    }
+    attachResource(resourceId, conversationId = this.resolveConversationId()) {
+        return this.requireConversationResourceTransport().attachResource(conversationId, resourceId);
+    }
+    detachResource(resourceId, conversationId = this.resolveConversationId()) {
+        return this.requireConversationResourceTransport().detachResource(conversationId, resourceId);
+    }
     /**
      * Subscribe to client events
      */
@@ -541,6 +612,10 @@ export class AIClient {
                 role: 'user',
                 content: this.truncateMessage('user', userMessage),
                 timestamp: Date.now(),
+                resourceReferences: resolvedOptions?.resourceReferences?.map((reference) => ({
+                    ...reference,
+                    resource: reference.resource ? { ...reference.resource } : undefined,
+                })),
             };
             this.conversationState.messages.push(userMsg);
             this.checkAndTrimHistory();
@@ -673,6 +748,13 @@ export class AIClient {
         if (options?.expectedRevision !== undefined) {
             request.expected_revision = options.expectedRevision;
         }
+        if (options?.resourceReferences?.length) {
+            request.resource_references = options.resourceReferences.map((reference) => ({
+                schemaVersion: 'conversation_resource_reference.v1',
+                resourceId: reference.resourceId,
+                purpose: 'attachment',
+            }));
+        }
         if (options?.tools) {
             request.tools = options.tools;
         }
@@ -710,13 +792,20 @@ export class AIClient {
             if (!response.ok) {
                 const error = await response.text().catch(() => 'Unknown error');
                 const retryable = response.status >= 500 || response.status === 429;
+                const lifecycleError = resolveLifecycleErrorResponse(error);
                 throw this.createError({
                     code: 'REQUEST_FAILED',
                     message: `Orchestrator error (${response.status}): ${error}`,
-                    safeMessage: `Request failed with status ${response.status}.`,
+                    safeMessage: lifecycleError.safeMessage ??
+                        `Request failed with status ${response.status}.`,
                     retryable,
                     statusCode: response.status,
-                    details: { responseBody: error },
+                    details: {
+                        responseBody: error,
+                        ...(lifecycleError.errorCode
+                            ? { orchestratorErrorCode: lifecycleError.errorCode }
+                            : {}),
+                    },
                 });
             }
             this.emit({ type: 'streaming_started' });