@xpert-ai/xpert-sdk 0.17.0 → 0.18.0

package/dist/tests/view-file-preview.test.js

@@ -0,0 +1,86 @@
+import { describe, expect, it, vi } from 'vitest';
+import { Client } from "../client.js";
+describe('authenticated image previews', () => {
+    it.each([false, true])('reads one binary response with the full request context (group=%s)', async (group) => {
+        const bytes = new Uint8Array([82, 73, 70, 70, 0, 255]);
+        const fetch = vi.fn().mockImplementation(async () => new Response(bytes, {
+            headers: {
+                'content-type': 'image/webp',
+                'content-disposition': "inline; filename*=UTF-8''%E5%9B%BE.webp",
+            },
+        }));
+        const onRequest = vi.fn((_url, init) => ({
+            ...init,
+            headers: { ...init.headers, 'x-context': 'current' },
+        }));
+        const client = new Client({
+            apiUrl: 'https://example.test/proxy/api/ai/',
+            apiKey: 'test',
+            defaultHeaders: { 'organization-id': 'org' },
+            callerOptions: { fetch, maxRetries: 0 },
+            onRequest,
+        });
+        const view = group ? client.forGroupWorkbench('group/1').viewHosts : client.viewHosts;
+        const signal = new AbortController().signal;
+        const runtimeScope = { projectId: 'project', conversationId: 'conversation' };
+        const result = await view.readFilePreview('agent', 'assistant', 'view', { fileKey: 'file', targetId: 'version', variant: 'thumbnail' }, { runtimeScope, signal });
+        expect(result.fileName).toBe('图.webp');
+        expect(new Uint8Array(await result.blob.arrayBuffer())).toEqual(bytes);
+        expect(result.blob.type).toBe('image/webp');
+        expect(fetch).toHaveBeenCalledTimes(1);
+        const [url, init] = fetch.mock.calls[0];
+        expect(String(url)).toBe(`https://example.test/proxy/api/ai/${group ? 'groups/group%2F1/workbench/' : ''}workspace-files/view-sessions/preview`);
+        expect(init).toMatchObject({
+            method: 'POST',
+            signal,
+            credentials: 'omit',
+            redirect: 'error',
+            headers: {
+                'x-context': 'current',
+                'organization-id': 'org',
+                'x-xpert-view-project-id': 'project',
+            },
+        });
+        expect(JSON.parse(String(init?.body))).toEqual({
+            hostType: 'agent',
+            hostId: 'assistant',
+            viewKey: 'view',
+            fileKey: 'file',
+            targetId: 'version',
+            variant: 'thumbnail',
+            runtimeScope,
+        });
+        expect(onRequest).toHaveBeenCalledOnce();
+    });
+    it.each([401, 403, 404, 415])('preserves HTTP %s without returning an error body as an image', async (status) => {
+        const fetch = vi
+            .fn()
+            .mockImplementation(async () => new Response('Denied', { status }));
+        const client = new Client({
+            apiUrl: 'https://example.test/api/ai',
+            callerOptions: { fetch, maxRetries: 0 },
+        });
+        await expect(client.viewHosts.readFilePreview('agent', 'assistant', 'view', {
+            fileKey: 'file',
+            variant: 'original',
+        })).rejects.toMatchObject({ status });
+        expect(fetch).toHaveBeenCalledOnce();
+    });
+    it.each([
+        ['text/html', 'inline; filename="image.png"'],
+        ['image/png', ''],
+        ['image/png', "inline; filename*=UTF-8''..%2Fimage.png"],
+    ])('rejects invalid binary metadata: %s %s', async (type, disposition) => {
+        const client = new Client({
+            apiUrl: 'https://example.test/api/ai',
+            callerOptions: {
+                fetch: async () => new Response('data', {
+                    headers: { 'content-type': type, 'content-disposition': disposition },
+                }),
+                maxRetries: 0,
+            },
+        });
+        await expect(client.viewHosts.readFilePreview('agent', 'assistant', 'view', { fileKey: 'file' })).rejects.toThrow();
+    });
+});
+//# sourceMappingURL=view-file-preview.test.js.map

package/dist/tests/view-file-preview.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-file-preview.test.js","sourceRoot":"","sources":["../../src/tests/view-file-preview.test.ts"],"names":[],"mappings":"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"}

package/dist/tests/view-file-preview.test.mjs

@@ -0,0 +1,86 @@
+import { describe, expect, it, vi } from 'vitest';
+import { Client } from "../client.mjs";
+describe('authenticated image previews', () => {
+    it.each([false, true])('reads one binary response with the full request context (group=%s)', async (group) => {
+        const bytes = new Uint8Array([82, 73, 70, 70, 0, 255]);
+        const fetch = vi.fn().mockImplementation(async () => new Response(bytes, {
+            headers: {
+                'content-type': 'image/webp',
+                'content-disposition': "inline; filename*=UTF-8''%E5%9B%BE.webp",
+            },
+        }));
+        const onRequest = vi.fn((_url, init) => ({
+            ...init,
+            headers: { ...init.headers, 'x-context': 'current' },
+        }));
+        const client = new Client({
+            apiUrl: 'https://example.test/proxy/api/ai/',
+            apiKey: 'test',
+            defaultHeaders: { 'organization-id': 'org' },
+            callerOptions: { fetch, maxRetries: 0 },
+            onRequest,
+        });
+        const view = group ? client.forGroupWorkbench('group/1').viewHosts : client.viewHosts;
+        const signal = new AbortController().signal;
+        const runtimeScope = { projectId: 'project', conversationId: 'conversation' };
+        const result = await view.readFilePreview('agent', 'assistant', 'view', { fileKey: 'file', targetId: 'version', variant: 'thumbnail' }, { runtimeScope, signal });
+        expect(result.fileName).toBe('图.webp');
+        expect(new Uint8Array(await result.blob.arrayBuffer())).toEqual(bytes);
+        expect(result.blob.type).toBe('image/webp');
+        expect(fetch).toHaveBeenCalledTimes(1);
+        const [url, init] = fetch.mock.calls[0];
+        expect(String(url)).toBe(`https://example.test/proxy/api/ai/${group ? 'groups/group%2F1/workbench/' : ''}workspace-files/view-sessions/preview`);
+        expect(init).toMatchObject({
+            method: 'POST',
+            signal,
+            credentials: 'omit',
+            redirect: 'error',
+            headers: {
+                'x-context': 'current',
+                'organization-id': 'org',
+                'x-xpert-view-project-id': 'project',
+            },
+        });
+        expect(JSON.parse(String(init?.body))).toEqual({
+            hostType: 'agent',
+            hostId: 'assistant',
+            viewKey: 'view',
+            fileKey: 'file',
+            targetId: 'version',
+            variant: 'thumbnail',
+            runtimeScope,
+        });
+        expect(onRequest).toHaveBeenCalledOnce();
+    });
+    it.each([401, 403, 404, 415])('preserves HTTP %s without returning an error body as an image', async (status) => {
+        const fetch = vi
+            .fn()
+            .mockImplementation(async () => new Response('Denied', { status }));
+        const client = new Client({
+            apiUrl: 'https://example.test/api/ai',
+            callerOptions: { fetch, maxRetries: 0 },
+        });
+        await expect(client.viewHosts.readFilePreview('agent', 'assistant', 'view', {
+            fileKey: 'file',
+            variant: 'original',
+        })).rejects.toMatchObject({ status });
+        expect(fetch).toHaveBeenCalledOnce();
+    });
+    it.each([
+        ['text/html', 'inline; filename="image.png"'],
+        ['image/png', ''],
+        ['image/png', "inline; filename*=UTF-8''..%2Fimage.png"],
+    ])('rejects invalid binary metadata: %s %s', async (type, disposition) => {
+        const client = new Client({
+            apiUrl: 'https://example.test/api/ai',
+            callerOptions: {
+                fetch: async () => new Response('data', {
+                    headers: { 'content-type': type, 'content-disposition': disposition },
+                }),
+                maxRetries: 0,
+            },
+        });
+        await expect(client.viewHosts.readFilePreview('agent', 'assistant', 'view', { fileKey: 'file' })).rejects.toThrow();
+    });
+});
+//# sourceMappingURL=view-file-preview.test.mjs.map

package/dist/tests/view-file-preview.test.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-file-preview.test.mjs","sourceRoot":"","sources":["../../src/tests/view-file-preview.test.ts"],"names":[],"mappings":"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"}

package/dist/thread-activity.d.ts

@@ -1,8 +1,10 @@
+import { type ThreadControlView } from './thread-control-view.js';
 import type { TMessageContentResourceCard } from './resource-card.js';
 /** Complete discovery snapshot. Reconnect replaces discovery state; tokens use runs.joinStream. */
 export interface ThreadActivitySnapshot {
     version: 1;
     threadId: string;
+    controlView?: ThreadControlView;
     runs: Array<{
         id: string;
         status: string;

package/dist/thread-activity.js

@@ -1,9 +1,12 @@
+import { isThreadControlView } from "./thread-control-view.js";
 export function isThreadActivitySnapshot(value) {
     if (!value || typeof value !== 'object' || !('version' in value) || value.version !== 1 ||
         !('threadId' in value) || typeof value.threadId !== 'string' ||
         !('runs' in value) || !Array.isArray(value.runs) ||
         !('cards' in value) || !Array.isArray(value.cards))
         return false;
+    if ('controlView' in value && value.controlView !== undefined && !isThreadControlView(value.controlView))
+        return false;
     // Card payloads use the shared resource-card parser at the rendering boundary.
     return value.runs.every((run) => !!run && typeof run === 'object' &&
         'id' in run && typeof run.id === 'string' &&

package/dist/thread-activity.js.map

@@ -1 +1 @@
-{"version":3,"file":"thread-activity.js","sourceRoot":"","sources":["../src/thread-activity.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,KAAK,CAAC;QACnF,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAC5D,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;QAChD,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrE,+EAA+E;IAC/E,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QACxE,IAAI,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;QACzC,QAAQ,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;QACjD,WAAW,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ;QACvD,WAAW,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ;QACvD,iBAAiB,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,eAAe,KAAK,QAAQ,CAAC,CAAC;AACzE,CAAC"}
+{"version":3,"file":"thread-activity.js","sourceRoot":"","sources":["../src/thread-activity.ts"],"names":[],"mappings":"OAAO,EAAE,mBAAmB,EAA0B;AAYtD,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,KAAK,CAAC;QACnF,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAC5D,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;QAChD,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrE,IAAI,aAAa,IAAI,KAAK,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,WAAW,CAAC;QAAE,OAAO,KAAK,CAAC;IACvH,+EAA+E;IAC/E,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QACxE,IAAI,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;QACzC,QAAQ,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;QACjD,WAAW,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ;QACvD,WAAW,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ;QACvD,iBAAiB,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,eAAe,KAAK,QAAQ,CAAC,CAAC;AACzE,CAAC"}

package/dist/thread-activity.mjs

@@ -1,9 +1,12 @@
+import { isThreadControlView } from "./thread-control-view.mjs";
 export function isThreadActivitySnapshot(value) {
     if (!value || typeof value !== 'object' || !('version' in value) || value.version !== 1 ||
         !('threadId' in value) || typeof value.threadId !== 'string' ||
         !('runs' in value) || !Array.isArray(value.runs) ||
         !('cards' in value) || !Array.isArray(value.cards))
         return false;
+    if ('controlView' in value && value.controlView !== undefined && !isThreadControlView(value.controlView))
+        return false;
     // Card payloads use the shared resource-card parser at the rendering boundary.
     return value.runs.every((run) => !!run && typeof run === 'object' &&
         'id' in run && typeof run.id === 'string' &&

package/dist/thread-activity.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"thread-activity.mjs","sourceRoot":"","sources":["../src/thread-activity.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,KAAK,CAAC;QACnF,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAC5D,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;QAChD,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrE,+EAA+E;IAC/E,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QACxE,IAAI,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;QACzC,QAAQ,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;QACjD,WAAW,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ;QACvD,WAAW,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ;QACvD,iBAAiB,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,eAAe,KAAK,QAAQ,CAAC,CAAC;AACzE,CAAC"}
+{"version":3,"file":"thread-activity.mjs","sourceRoot":"","sources":["../src/thread-activity.ts"],"names":[],"mappings":"OAAO,EAAE,mBAAmB,EAA0B;AAYtD,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,KAAK,CAAC;QACnF,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAC5D,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;QAChD,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrE,IAAI,aAAa,IAAI,KAAK,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,WAAW,CAAC;QAAE,OAAO,KAAK,CAAC;IACvH,+EAA+E;IAC/E,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QACxE,IAAI,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;QACzC,QAAQ,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;QACjD,WAAW,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ;QACvD,WAAW,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ;QACvD,iBAAiB,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,eAAe,KAAK,QAAQ,CAAC,CAAC;AACzE,CAAC"}

package/dist/thread-control-view.d.ts

@@ -0,0 +1,23 @@
+/** Public hints only. The host revalidates every action against its durable execution state. */
+export type ThreadControlActions = {
+    canPause: boolean;
+    canResume: boolean;
+    canTerminate: boolean;
+    canSend: boolean;
+    canQueue: boolean;
+    canRetry: boolean;
+    canRespond: boolean;
+};
+export type ThreadControlView = {
+    version: 1;
+    threadId: string;
+    runId: string | null;
+    /** Decimal durable clock; do not compare revisions as strings or timestamps. */
+    revision: string;
+    state: 'idle' | 'running' | 'pausing' | 'paused' | 'stopping' | 'settling' | 'input_required' | 'confirming' | 'completed' | 'stopped' | 'failed';
+    actions: ThreadControlActions;
+    pauseId?: string;
+};
+export declare function isThreadControlView(value: unknown): value is ThreadControlView;
+/** Revisions order the whole thread, including replacement runs. Never let an old response restore controls. */
+export declare function mergeThreadControlView(previous: ThreadControlView | undefined, incoming: ThreadControlView): ThreadControlView;

package/dist/thread-control-view.js

@@ -0,0 +1,57 @@
+const states = [
+    'idle',
+    'running',
+    'pausing',
+    'paused',
+    'stopping',
+    'settling',
+    'input_required',
+    'confirming',
+    'completed',
+    'stopped',
+    'failed',
+];
+export function isThreadControlView(value) {
+    if (!value ||
+        typeof value !== 'object' ||
+        !('version' in value) ||
+        value.version !== 1 ||
+        !('threadId' in value) ||
+        typeof value.threadId !== 'string' ||
+        !value.threadId ||
+        !('runId' in value) ||
+        !(value.runId === null || (typeof value.runId === 'string' && value.runId.length > 0)) ||
+        !('revision' in value) ||
+        typeof value.revision !== 'string' ||
+        !/^[1-9][0-9]*$/.test(value.revision) ||
+        !('state' in value) ||
+        typeof value.state !== 'string' ||
+        !states.includes(value.state) ||
+        ('pauseId' in value && typeof value.pauseId !== 'string') ||
+        !('actions' in value) ||
+        !value.actions ||
+        typeof value.actions !== 'object')
+        return false;
+    const actions = value.actions;
+    return ('canPause' in actions &&
+        typeof actions.canPause === 'boolean' &&
+        'canResume' in actions &&
+        typeof actions.canResume === 'boolean' &&
+        'canTerminate' in actions &&
+        typeof actions.canTerminate === 'boolean' &&
+        'canSend' in actions &&
+        typeof actions.canSend === 'boolean' &&
+        'canQueue' in actions &&
+        typeof actions.canQueue === 'boolean' &&
+        'canRetry' in actions &&
+        typeof actions.canRetry === 'boolean' &&
+        'canRespond' in actions &&
+        typeof actions.canRespond === 'boolean');
+}
+/** Revisions order the whole thread, including replacement runs. Never let an old response restore controls. */
+export function mergeThreadControlView(previous, incoming) {
+    if (!previous || previous.threadId !== incoming.threadId)
+        return incoming;
+    return BigInt(incoming.revision) < BigInt(previous.revision) ? previous : incoming;
+}
+//# sourceMappingURL=thread-control-view.js.map

package/dist/thread-control-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-control-view.js","sourceRoot":"","sources":["../src/thread-control-view.ts"],"names":[],"mappings":"AA+BA,MAAM,MAAM,GAAsB;IAChC,MAAM;IACN,SAAS;IACT,SAAS;IACT,QAAQ;IACR,UAAU;IACV,UAAU;IACV,gBAAgB;IAChB,YAAY;IACZ,WAAW;IACX,SAAS;IACT,QAAQ;CACT,CAAC;AAEF,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,IACE,CAAC,KAAK;QACN,OAAO,KAAK,KAAK,QAAQ;QACzB,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC;QACrB,KAAK,CAAC,OAAO,KAAK,CAAC;QACnB,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC;QACtB,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAClC,CAAC,KAAK,CAAC,QAAQ;QACf,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC;QACnB,CAAC,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACtF,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC;QACtB,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAClC,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;QACrC,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC;QACnB,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;QAC/B,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC;QAC7B,CAAC,SAAS,IAAI,KAAK,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC;QACzD,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC;QACrB,CAAC,KAAK,CAAC,OAAO;QACd,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;QAEjC,OAAO,KAAK,CAAC;IACf,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,OAAO,CACL,UAAU,IAAI,OAAO;QACrB,OAAO,OAAO,CAAC,QAAQ,KAAK,SAAS;QACrC,WAAW,IAAI,OAAO;QACtB,OAAO,OAAO,CAAC,SAAS,KAAK,SAAS;QACtC,cAAc,IAAI,OAAO;QACzB,OAAO,OAAO,CAAC,YAAY,KAAK,SAAS;QACzC,SAAS,IAAI,OAAO;QACpB,OAAO,OAAO,CAAC,OAAO,KAAK,SAAS;QACpC,UAAU,IAAI,OAAO;QACrB,OAAO,OAAO,CAAC,QAAQ,KAAK,SAAS;QACrC,UAAU,IAAI,OAAO;QACrB,OAAO,OAAO,CAAC,QAAQ,KAAK,SAAS;QACrC,YAAY,IAAI,OAAO;QACvB,OAAO,OAAO,CAAC,UAAU,KAAK,SAAS,CACxC,CAAC;AACJ,CAAC;AAED,gHAAgH;AAChH,MAAM,UAAU,sBAAsB,CACpC,QAAuC,EACvC,QAA2B;IAE3B,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC1E,OAAO,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AACrF,CAAC"}

package/dist/thread-control-view.mjs

@@ -0,0 +1,57 @@
+const states = [
+    'idle',
+    'running',
+    'pausing',
+    'paused',
+    'stopping',
+    'settling',
+    'input_required',
+    'confirming',
+    'completed',
+    'stopped',
+    'failed',
+];
+export function isThreadControlView(value) {
+    if (!value ||
+        typeof value !== 'object' ||
+        !('version' in value) ||
+        value.version !== 1 ||
+        !('threadId' in value) ||
+        typeof value.threadId !== 'string' ||
+        !value.threadId ||
+        !('runId' in value) ||
+        !(value.runId === null || (typeof value.runId === 'string' && value.runId.length > 0)) ||
+        !('revision' in value) ||
+        typeof value.revision !== 'string' ||
+        !/^[1-9][0-9]*$/.test(value.revision) ||
+        !('state' in value) ||
+        typeof value.state !== 'string' ||
+        !states.includes(value.state) ||
+        ('pauseId' in value && typeof value.pauseId !== 'string') ||
+        !('actions' in value) ||
+        !value.actions ||
+        typeof value.actions !== 'object')
+        return false;
+    const actions = value.actions;
+    return ('canPause' in actions &&
+        typeof actions.canPause === 'boolean' &&
+        'canResume' in actions &&
+        typeof actions.canResume === 'boolean' &&
+        'canTerminate' in actions &&
+        typeof actions.canTerminate === 'boolean' &&
+        'canSend' in actions &&
+        typeof actions.canSend === 'boolean' &&
+        'canQueue' in actions &&
+        typeof actions.canQueue === 'boolean' &&
+        'canRetry' in actions &&
+        typeof actions.canRetry === 'boolean' &&
+        'canRespond' in actions &&
+        typeof actions.canRespond === 'boolean');
+}
+/** Revisions order the whole thread, including replacement runs. Never let an old response restore controls. */
+export function mergeThreadControlView(previous, incoming) {
+    if (!previous || previous.threadId !== incoming.threadId)
+        return incoming;
+    return BigInt(incoming.revision) < BigInt(previous.revision) ? previous : incoming;
+}
+//# sourceMappingURL=thread-control-view.mjs.map

package/dist/thread-control-view.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-control-view.mjs","sourceRoot":"","sources":["../src/thread-control-view.ts"],"names":[],"mappings":"AA+BA,MAAM,MAAM,GAAsB;IAChC,MAAM;IACN,SAAS;IACT,SAAS;IACT,QAAQ;IACR,UAAU;IACV,UAAU;IACV,gBAAgB;IAChB,YAAY;IACZ,WAAW;IACX,SAAS;IACT,QAAQ;CACT,CAAC;AAEF,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,IACE,CAAC,KAAK;QACN,OAAO,KAAK,KAAK,QAAQ;QACzB,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC;QACrB,KAAK,CAAC,OAAO,KAAK,CAAC;QACnB,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC;QACtB,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAClC,CAAC,KAAK,CAAC,QAAQ;QACf,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC;QACnB,CAAC,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACtF,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC;QACtB,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAClC,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;QACrC,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC;QACnB,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;QAC/B,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC;QAC7B,CAAC,SAAS,IAAI,KAAK,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC;QACzD,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC;QACrB,CAAC,KAAK,CAAC,OAAO;QACd,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;QAEjC,OAAO,KAAK,CAAC;IACf,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,OAAO,CACL,UAAU,IAAI,OAAO;QACrB,OAAO,OAAO,CAAC,QAAQ,KAAK,SAAS;QACrC,WAAW,IAAI,OAAO;QACtB,OAAO,OAAO,CAAC,SAAS,KAAK,SAAS;QACtC,cAAc,IAAI,OAAO;QACzB,OAAO,OAAO,CAAC,YAAY,KAAK,SAAS;QACzC,SAAS,IAAI,OAAO;QACpB,OAAO,OAAO,CAAC,OAAO,KAAK,SAAS;QACpC,UAAU,IAAI,OAAO;QACrB,OAAO,OAAO,CAAC,QAAQ,KAAK,SAAS;QACrC,UAAU,IAAI,OAAO;QACrB,OAAO,OAAO,CAAC,QAAQ,KAAK,SAAS;QACrC,YAAY,IAAI,OAAO;QACvB,OAAO,OAAO,CAAC,UAAU,KAAK,SAAS,CACxC,CAAC;AACJ,CAAC;AAED,gHAAgH;AAChH,MAAM,UAAU,sBAAsB,CACpC,QAAuC,EACvC,QAA2B;IAE3B,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC1E,OAAO,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AACrF,CAAC"}

package/dist/types.stream.d.ts

@@ -1,7 +1,6 @@
 import type { Message } from "./types.messages.js";
 import type { Interrupt, Metadata, Config, ThreadTask } from "./schema.js";
 /**
-import type { SubgraphCheckpointsStreamEvent } from "./types.stream.subgraph.js";
  * Stream modes
  * - "values": Stream only the state values.
  * - "messages": Stream complete messages.
@@ -34,13 +33,16 @@ export type ValuesStreamEvent<StateType> = {
     event: "values";
     data: StateType;
 };
+export type SubgraphValuesStreamEvent<StateType> = AsSubgraph<ValuesStreamEvent<StateType>>;
 /**
  * Stream event with message chunks coming from LLM invocations inside nodes.
  */
 export type MessagesTupleStreamEvent = {
+    id?: string;
     event: "messages";
     data: [message: Message, config: MessageTupleMetadata];
 };
+export type SubgraphMessagesTupleStreamEvent = AsSubgraph<MessagesTupleStreamEvent>;
 /**
  * Metadata stream event with information about the run and thread
  */
@@ -63,6 +65,7 @@ export type ErrorStreamEvent = {
         message: string;
     };
 };
+export type SubgraphErrorStreamEvent = AsSubgraph<ErrorStreamEvent>;
 /**
  * Stream event with updates to the state after each step.
  * The streamed outputs include the name of the node that
@@ -75,13 +78,16 @@ export type UpdatesStreamEvent<UpdateType> = {
         [node: string]: UpdateType;
     };
 };
+export type SubgraphUpdatesStreamEvent<UpdateType> = AsSubgraph<UpdatesStreamEvent<UpdateType>>;
 /**
  * Streaming custom data from inside the nodes.
  */
 export type CustomStreamEvent<T> = {
+    id?: string;
     event: "custom";
     data: T;
 };
+export type SubgraphCustomStreamEvent<T> = AsSubgraph<CustomStreamEvent<T>>;
 type MessagesMetadataStreamEvent = {
     id?: string;
     event: "messages/metadata";
@@ -151,6 +157,7 @@ type SubgraphCheckpointsStreamEvent<StateType> = AsSubgraph<CheckpointsStreamEve
  * @deprecated Use `streamMode: "messages-tuple"` instead.
  */
 export type MessagesStreamEvent = MessagesMetadataStreamEvent | MessagesCompleteStreamEvent | MessagesPartialStreamEvent;
+export type SubgraphMessagesStreamEvent = AsSubgraph<MessagesMetadataStreamEvent> | AsSubgraph<MessagesCompleteStreamEvent> | AsSubgraph<MessagesPartialStreamEvent>;
 /**
  * Stream event with detailed debug information.
  */
@@ -159,6 +166,7 @@ export type DebugStreamEvent = {
     event: "debug";
     data: unknown;
 };
+export type SubgraphDebugStreamEvent = AsSubgraph<DebugStreamEvent>;
 /**
  * Stream event with events occurring during execution.
  */
@@ -175,6 +183,7 @@ export type EventsStreamEvent = {
         data: unknown;
     };
 };
+export type SubgraphEventsStreamEvent = AsSubgraph<EventsStreamEvent>;
 /**
  * Stream event with a feedback key to signed URL map. Set `feedbackKeys` in
  * the `RunsStreamPayload` to receive this event.

package/dist/view-file-preview.d.ts

@@ -0,0 +1,11 @@
+/** A preview is resolved and authorized in the same request that returns its bytes. */
+export interface XpertViewFilePreviewRequest {
+    fileKey: string;
+    targetId?: string;
+    variant?: 'thumbnail' | 'original';
+}
+export interface XpertViewFilePreviewResult {
+    blob: Blob;
+    fileName: string;
+}
+export declare function readViewFilePreviewResponse(response: Response): Promise<XpertViewFilePreviewResult>;

package/dist/view-file-preview.js

@@ -0,0 +1,16 @@
+export async function readViewFilePreviewResponse(response) {
+    const disposition = response.headers.get('content-disposition') ?? '';
+    const encoded = /filename\*=UTF-8''([^;]+)/i.exec(disposition)?.[1];
+    const fileName = encoded
+        ? decodeURIComponent(encoded)
+        : /filename="([^"\r\n]+)"/i.exec(disposition)?.[1];
+    if (!fileName || /[/\\\u0000-\u001f\u007f]/.test(fileName)) {
+        throw new Error('Invalid image preview filename.');
+    }
+    const blob = await response.blob();
+    if (!['image/png', 'image/jpeg', 'image/webp', 'image/gif'].includes(blob.type.split(';')[0].trim())) {
+        throw new Error('Invalid image preview content type.');
+    }
+    return { blob, fileName };
+}
+//# sourceMappingURL=view-file-preview.js.map

package/dist/view-file-preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-file-preview.js","sourceRoot":"","sources":["../src/view-file-preview.ts"],"names":[],"mappings":"AAYA,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,QAAkB;IAElB,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,EAAE,CAAC;IACtE,MAAM,OAAO,GAAG,4BAA4B,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,QAAQ,GAAG,OAAO;QACtB,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC;QAC7B,CAAC,CAAC,yBAAyB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACrD,IAAI,CAAC,QAAQ,IAAI,0BAA0B,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,IACE,CAAC,CAAC,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAChG,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAC5B,CAAC"}

package/dist/view-file-preview.mjs

@@ -0,0 +1,16 @@
+export async function readViewFilePreviewResponse(response) {
+    const disposition = response.headers.get('content-disposition') ?? '';
+    const encoded = /filename\*=UTF-8''([^;]+)/i.exec(disposition)?.[1];
+    const fileName = encoded
+        ? decodeURIComponent(encoded)
+        : /filename="([^"\r\n]+)"/i.exec(disposition)?.[1];
+    if (!fileName || /[/\\\u0000-\u001f\u007f]/.test(fileName)) {
+        throw new Error('Invalid image preview filename.');
+    }
+    const blob = await response.blob();
+    if (!['image/png', 'image/jpeg', 'image/webp', 'image/gif'].includes(blob.type.split(';')[0].trim())) {
+        throw new Error('Invalid image preview content type.');
+    }
+    return { blob, fileName };
+}
+//# sourceMappingURL=view-file-preview.mjs.map

package/dist/view-file-preview.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-file-preview.mjs","sourceRoot":"","sources":["../src/view-file-preview.ts"],"names":[],"mappings":"AAYA,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,QAAkB;IAElB,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,EAAE,CAAC;IACtE,MAAM,OAAO,GAAG,4BAA4B,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,QAAQ,GAAG,OAAO;QACtB,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC;QAC7B,CAAC,CAAC,yBAAyB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACrD,IAAI,CAAC,QAAQ,IAAI,0BAA0B,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,IACE,CAAC,CAAC,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAChG,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAC5B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/xpert-sdk",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "SDK Core functionality package",
   "type": "module",
   "main": "dist/index.js",
@@ -20,11 +20,11 @@
     "p-queue": "^6.6.2",
     "p-retry": "4",
     "socket.io-client": "^4.8.4",
-    "uuid": "^9.0.0"
+    "uuid": "^9.0.0",
+    "@types/json-schema": "^7.0.15"
   },
   "devDependencies": {
     "@types/node": "^22.16.3",
-    "@types/json-schema": "^7.0.15",
     "rimraf": "^6.0.1",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",