@adonis-agora/agent 0.60.1 → 0.62.0

package/dist/src/react/core/media/index.js

@@ -0,0 +1,135 @@
+import { normalizeAgentPath } from '../client.js';
+import { readErrorResponse, reportHttpError, } from '../http-error.js';
+import { streamChunks } from './tus.js';
+/**
+ * Resumable attachment uploads through `@adonis-agora/media`, in one line:
+ *
+ * ```tsx
+ * <AgentProvider attachments={{ upload: mediaAttachments() }}>
+ * ```
+ *
+ * Reuses the client's own connection (origin, path, headers, credentials), so it needs no
+ * configuration. Also takes `new AgentClient({ attachments: { upload: mediaAttachments() } })`.
+ */
+export function mediaAttachments(options = {}) {
+    return (file, uploadOptions, connection) => createMediaUpload({
+        ...options,
+        baseUrl: connection.baseUrl,
+        path: connection.path,
+        getHeaders: connection.headers,
+        fetch: connection.fetch,
+        ...(connection.credentials !== undefined ? { credentials: connection.credentials } : {}),
+        ...(connection.onHttpError !== undefined ? { onHttpError: connection.onHttpError } : {}),
+    })(file, uploadOptions);
+}
+/**
+ * A non-2xx answer from the agent's upload routes. Carries what `AgentHttpError` does — `status`
+ * (413 too large, 415 type refused, 404 not yours), the server's `message`, `code` and `body` —
+ * as its own class because this subpath is bundled apart from the root entry, where an
+ * `instanceof AgentHttpError` would not match a copy. Both satisfy `AgentRequestError`.
+ */
+export class MediaUploadError extends Error {
+    status;
+    method;
+    path;
+    body;
+    code;
+    constructor(status, method, path, statusText, answer = { body: undefined, message: undefined, code: undefined }) {
+        super(answer.message ?? `Attachment upload failed: ${method} ${path} → ${status} ${statusText}`);
+        this.status = status;
+        this.method = method;
+        this.path = path;
+        this.name = 'MediaUploadError';
+        this.body = answer.body;
+        this.code = answer.code;
+    }
+}
+/**
+ * A resumable `upload` for `useAttachments`, backed by `@adonis-agora/media` on the server
+ * (`MediaAttachmentStaging` from `@adonis-agora/agent/media`):
+ *
+ * 1. `POST <path>/attachments/uploads` — the agent validates the file and opens a tus session the
+ *    actor owns;
+ * 2. the bytes stream to the media adapter’s own tus endpoint in chunks (`streamChunks`), reporting
+ *    progress and honouring the abort signal;
+ * 3. `POST <path>/attachments/uploads/:mediaId/complete` — the agent confirms the bytes landed and
+ *    answers the `MessageAttachment` the turn will reference by `mediaId`.
+ *
+ * An aborted or failed upload is discarded server-side (`DELETE`), best effort.
+ */
+export function createMediaUpload(options = {}) {
+    const origin = (options.baseUrl ?? '').replace(/\/$/, '');
+    const base = `${origin}${normalizeAgentPath(options.path)}/attachments/uploads`;
+    const baseFetch = () => options.fetch ?? fetch;
+    // Every request — the agent's and media's tus PATCHes — rides the same credentials mode.
+    const fetchWithCredentials = (input, init) => baseFetch()(input, {
+        ...init,
+        ...(options.credentials !== undefined ? { credentials: options.credentials } : {}),
+    });
+    const headers = async () => ({
+        ...options.headers,
+        ...((await options.getHeaders?.()) ?? {}),
+    });
+    const discard = (mediaId) => {
+        void (async () => {
+            await fetchWithCredentials(`${base}/${encodeURIComponent(mediaId)}`, {
+                method: 'DELETE',
+                headers: await headers(),
+            });
+        })().catch(() => undefined);
+    };
+    const call = async (method, url, body) => {
+        const response = await fetchWithCredentials(url, {
+            method,
+            headers: {
+                accept: 'application/json',
+                ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+                ...(await headers()),
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!response.ok) {
+            const error = new MediaUploadError(response.status, method, url, response.statusText, await readErrorResponse(response));
+            reportHttpError(options.onHttpError, error);
+            throw error;
+        }
+        return (await response.json());
+    };
+    return async (file, { signal, onProgress } = {}) => {
+        signal?.throwIfAborted();
+        const begun = await call('POST', base, {
+            filename: file.name,
+            contentType: file.type,
+            size: file.size,
+        });
+        const onAbort = () => discard(begun.mediaId);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            const location = /^https?:\/\//.test(begun.location)
+                ? begun.location
+                : `${origin}${begun.location}`;
+            await streamChunks(location, file, {
+                resume: false,
+                fetchImpl: fetchWithCredentials,
+                getHeaders: headers,
+                ...(options.chunkSize !== undefined ? { chunkSize: options.chunkSize } : {}),
+                ...(options.retries !== undefined ? { retries: options.retries } : {}),
+                ...(signal !== undefined ? { signal } : {}),
+                onProgress: (sent, total) => onProgress?.(total > 0 ? sent / total : 1),
+            });
+            signal?.throwIfAborted();
+            const attachment = await call('POST', `${base}/${encodeURIComponent(begun.mediaId)}/complete`);
+            onProgress?.(1);
+            return attachment;
+        }
+        catch (error) {
+            if (!signal?.aborted)
+                discard(begun.mediaId);
+            throw error;
+        }
+        finally {
+            signal?.removeEventListener('abort', onAbort);
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/src/react/core/media/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/react/core/media/index.ts"],"names":[],"mappings":"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"}

package/dist/src/react/core/media/tus.d.ts

@@ -0,0 +1,13 @@
+interface StreamChunksOptions {
+    chunkSize?: number;
+    retries?: number;
+    resume?: boolean;
+    fetchImpl?: typeof fetch;
+    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    signal?: AbortSignal;
+    onProgress?: (sent: number, total: number) => void;
+}
+/** Browser-only sequential tus uploads; connection headers refresh on every request. */
+export declare function streamChunks(location: string, data: Blob, options?: StreamChunksOptions): Promise<void>;
+export {};
+//# sourceMappingURL=tus.d.ts.map

package/dist/src/react/core/media/tus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tus.d.ts","sourceRoot":"","sources":["../../../../../src/react/core/media/tus.ts"],"names":[],"mappings":"AAAA,UAAU,mBAAmB;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpD;AAED,wFAAwF;AACxF,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,IAAI,EACV,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,IAAI,CAAC,CAwDf"}

package/dist/src/react/core/media/tus.js

@@ -0,0 +1,59 @@
+/** Browser-only sequential tus uploads; connection headers refresh on every request. */
+export async function streamChunks(location, data, options = {}) {
+    const chunkSize = options.chunkSize ?? 5 * 1024 * 1024;
+    const retries = options.retries ?? 3;
+    if (!Number.isSafeInteger(chunkSize) || chunkSize < 1)
+        throw new RangeError('chunkSize must be a positive safe integer');
+    if (!Number.isSafeInteger(retries) || retries < 1 || retries > 20)
+        throw new RangeError('retries must be 1–20');
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const headers = async () => ({ 'Tus-Resumable': '1.0.0', ...(await options.getHeaders?.()) });
+    let offset = 0;
+    options.signal?.throwIfAborted();
+    if (options.resume !== false) {
+        const response = await fetchImpl(location, {
+            method: 'HEAD',
+            headers: await headers(),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        if (response.ok) {
+            const reported = Number(response.headers.get('Upload-Offset') ?? 0);
+            if (!Number.isSafeInteger(reported) || reported < 0 || reported > data.size)
+                throw new Error('Invalid tus Upload-Offset');
+            offset = reported;
+        }
+    }
+    options.onProgress?.(offset, data.size);
+    while (offset < data.size) {
+        options.signal?.throwIfAborted();
+        const end = Math.min(offset + chunkSize, data.size);
+        for (let attempt = 0; attempt < retries; attempt++) {
+            try {
+                const response = await fetchImpl(location, {
+                    method: 'PATCH',
+                    headers: {
+                        ...(await headers()),
+                        'Content-Type': 'application/offset+octet-stream',
+                        'Upload-Offset': String(offset),
+                    },
+                    body: data.slice(offset, end),
+                    ...(options.signal ? { signal: options.signal } : {}),
+                });
+                if (!response.ok)
+                    throw new Error(`Media upload PATCH failed at offset ${offset}: ${response.status} ${response.statusText}`);
+                const reported = Number(response.headers.get('Upload-Offset') ?? end);
+                if (!Number.isSafeInteger(reported) || reported <= offset || reported > data.size)
+                    throw new Error('Invalid tus Upload-Offset');
+                offset = reported;
+                options.onProgress?.(offset, data.size);
+                break;
+            }
+            catch (error) {
+                options.signal?.throwIfAborted();
+                if (attempt === retries - 1)
+                    throw error;
+            }
+        }
+    }
+}
+//# sourceMappingURL=tus.js.map

package/dist/src/react/core/media/tus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tus.js","sourceRoot":"","sources":["../../../../../src/react/core/media/tus.ts"],"names":[],"mappings":"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"}

package/dist/src/react/core/presentation/phrasing.d.ts

@@ -0,0 +1,25 @@
+import type { ToolCatalogEntry, ToolPresentation } from '../../../index.js';
+/** Tool name → how the server said it is spoken about. */
+export type ToolCatalog = Record<string, ToolPresentation>;
+/** Index `GET <base>/tools` by tool name, keeping only the tools that declared a presentation. */
+export declare function toolCatalogFrom(entries: readonly ToolCatalogEntry[]): ToolCatalog;
+/** Dotted-path read. `undefined` rather than a throw, so a template can outlive a field. */
+export declare function readPath(value: unknown, path: string): unknown;
+/**
+ * Fill `{dotted.path}` placeholders from `context`. A placeholder with nothing behind it collapses
+ * along with the whitespace in front of it, so "Reading {key}" degrades to "Reading" rather than
+ * printing braces at a person; a filled one keeps the whitespace the author wrote ("({n} files)").
+ */
+export declare function fillTemplate(template: string, context: unknown): string;
+/**
+ * The sentence for one call: the presentation's `running` or `done` template over the call's input.
+ *
+ * Nothing here reads the tool's name. A tool the catalog does not describe — added since the catalog
+ * loaded, or declared without a presentation — is narrated generically (`fallback`), because the only
+ * other thing available to say is its identifier.
+ */
+export declare function phraseFor(presentation: ToolPresentation | undefined, input: unknown, isSettled: boolean, fallback?: {
+    running: string;
+    done: string;
+}): string;
+//# sourceMappingURL=phrasing.d.ts.map

package/dist/src/react/core/presentation/phrasing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phrasing.d.ts","sourceRoot":"","sources":["../../../../../src/react/core/presentation/phrasing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE5E,0DAA0D;AAC1D,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAE3D,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,WAAW,CAMjF;AAED,4FAA4F;AAC5F,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAK9D;AAUD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAQvE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,YAAY,EAAE,gBAAgB,GAAG,SAAS,EAC1C,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,OAAO,EAClB,QAAQ,GAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAyC,GACjF,MAAM,CAMR"}

package/dist/src/react/core/presentation/phrasing.js

@@ -0,0 +1,58 @@
+/** Index `GET <base>/tools` by tool name, keeping only the tools that declared a presentation. */
+export function toolCatalogFrom(entries) {
+    const catalog = {};
+    for (const entry of entries) {
+        if (entry.presentation !== undefined)
+            catalog[entry.name] = entry.presentation;
+    }
+    return catalog;
+}
+/** Dotted-path read. `undefined` rather than a throw, so a template can outlive a field. */
+export function readPath(value, path) {
+    return path.split('.').reduce((current, key) => {
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        return current[key];
+    }, value);
+}
+function renderValue(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value))
+        return value.map(renderValue).filter(Boolean).join(', ');
+    return '';
+}
+/**
+ * Fill `{dotted.path}` placeholders from `context`. A placeholder with nothing behind it collapses
+ * along with the whitespace in front of it, so "Reading {key}" degrades to "Reading" rather than
+ * printing braces at a person; a filled one keeps the whitespace the author wrote ("({n} files)").
+ */
+export function fillTemplate(template, context) {
+    return template
+        .replace(/(\s*)\{([\w.]+)\}/g, (_match, space, path) => {
+        const rendered = renderValue(readPath(context, path));
+        return rendered === '' ? '' : `${space}${rendered}`;
+    })
+        .replace(/\s{2,}/g, ' ')
+        .trim();
+}
+/**
+ * The sentence for one call: the presentation's `running` or `done` template over the call's input.
+ *
+ * Nothing here reads the tool's name. A tool the catalog does not describe — added since the catalog
+ * loaded, or declared without a presentation — is narrated generically (`fallback`), because the only
+ * other thing available to say is its identifier.
+ */
+export function phraseFor(presentation, input, isSettled, fallback = { running: 'Working', done: 'Done' }) {
+    if (presentation === undefined)
+        return isSettled ? fallback.done : fallback.running;
+    const filled = fillTemplate(isSettled ? presentation.done : presentation.running, input);
+    // A sentence made only of slots, called before those fields have streamed, leaves nothing. The
+    // label is still the server's word for this tool, and a blank line reads as nothing happening.
+    return filled === '' ? presentation.label : filled;
+}
+//# sourceMappingURL=phrasing.js.map

package/dist/src/react/core/presentation/phrasing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phrasing.js","sourceRoot":"","sources":["../../../../../src/react/core/presentation/phrasing.ts"],"names":[],"mappings":"AAKA,kGAAkG;AAClG,MAAM,UAAU,eAAe,CAAC,OAAoC;IAClE,MAAM,OAAO,GAAgB,EAAE,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;YAAE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,YAAY,CAAC;IACjF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,QAAQ,CAAC,KAAc,EAAE,IAAY;IACnD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAU,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE;QACtD,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACtE,OAAQ,OAAmC,CAAC,GAAG,CAAC,CAAC;IACnD,CAAC,EAAE,KAAK,CAAC,CAAC;AACZ,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAClF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnF,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,OAAgB;IAC7D,OAAO,QAAQ;SACZ,OAAO,CAAC,oBAAoB,EAAE,CAAC,MAAM,EAAE,KAAa,EAAE,IAAY,EAAE,EAAE;QACrE,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QACtD,OAAO,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,QAAQ,EAAE,CAAC;IACtD,CAAC,CAAC;SACD,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CACvB,YAA0C,EAC1C,KAAc,EACd,SAAkB,EAClB,QAAQ,GAAsC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE;IAElF,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;IACpF,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACzF,+FAA+F;IAC/F,+FAA+F;IAC/F,OAAO,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;AACrD,CAAC"}

package/dist/src/react/core/presentation/result-view.d.ts

@@ -0,0 +1,43 @@
+import type { ToolResultField, ToolResultView } from '../../../index.js';
+/** One labelled reading of a `metrics` view. */
+export interface ResolvedReading {
+    label: string;
+    /** The value as text (`—` for nothing). */
+    value: string;
+    unit: string | null;
+}
+/**
+ * A tool's output resolved through its view into plain data a renderer draws — never the payload
+ * itself. `null` from {@link resolveResultView} means "draw nothing".
+ */
+export type ResolvedResultView = {
+    kind: 'metrics';
+    readings: ResolvedReading[];
+} | {
+    kind: 'table';
+    columns: ToolResultField[];
+    rows: string[][];
+    empty: string | null;
+} | {
+    kind: 'log';
+    lines: string[];
+} | {
+    kind: 'note';
+    text: string;
+};
+/**
+ * A view for an output whose tool declared none, from its shape: an array of flat records is a
+ * table, an array of strings a log, a flat record a set of readings. `undefined` when nothing fits —
+ * a serialized payload is what a person-facing surface exists to avoid, so failing to infer must not
+ * fall back to one.
+ */
+export declare function inferResultView(output: unknown): ToolResultView | undefined;
+/**
+ * Read `output` through `view` (or one inferred from its shape when `view` is omitted and `infer` is
+ * on). `null` when there is nothing to draw: an `elsewhere` view, an empty reading set, a missing
+ * array. A table whose rows array is present but empty resolves with no rows and its `empty` line.
+ */
+export declare function resolveResultView(output: unknown, view: ToolResultView | undefined, options?: {
+    infer?: boolean;
+}): ResolvedResultView | null;
+//# sourceMappingURL=result-view.d.ts.map

package/dist/src/react/core/presentation/result-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-view.d.ts","sourceRoot":"","sources":["../../../../../src/react/core/presentation/result-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGzE,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,eAAe,EAAE,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,eAAe,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACrF;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAenC;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAsB3E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,cAAc,GAAG,SAAS,EAChC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,kBAAkB,GAAG,IAAI,CAqC3B"}

package/dist/src/react/core/presentation/result-view.js

@@ -0,0 +1,90 @@
+import { fillTemplate, readPath } from './phrasing.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function toText(value) {
+    if (value === null || value === undefined)
+        return '—';
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    if (Array.isArray(value))
+        return value.map(toText).join(', ');
+    return '—';
+}
+/**
+ * A view for an output whose tool declared none, from its shape: an array of flat records is a
+ * table, an array of strings a log, a flat record a set of readings. `undefined` when nothing fits —
+ * a serialized payload is what a person-facing surface exists to avoid, so failing to infer must not
+ * fall back to one.
+ */
+export function inferResultView(output) {
+    if (!isRecord(output))
+        return undefined;
+    for (const [key, value] of Object.entries(output)) {
+        if (!Array.isArray(value) || value.length === 0)
+            continue;
+        if (value.every((entry) => typeof entry === 'string')) {
+            return { kind: 'log', lines: key };
+        }
+        if (value.every(isRecord)) {
+            const first = value[0];
+            return {
+                kind: 'table',
+                rows: key,
+                columns: Object.keys(first)
+                    .filter((column) => !isRecord(first[column]))
+                    .map((column) => ({ path: column, label: column })),
+            };
+        }
+    }
+    const fields = Object.entries(output)
+        .filter(([, value]) => ['string', 'number', 'boolean'].includes(typeof value))
+        .map(([key]) => ({ path: key, label: key }));
+    return fields.length > 0 ? { kind: 'metrics', fields } : undefined;
+}
+/**
+ * Read `output` through `view` (or one inferred from its shape when `view` is omitted and `infer` is
+ * on). `null` when there is nothing to draw: an `elsewhere` view, an empty reading set, a missing
+ * array. A table whose rows array is present but empty resolves with no rows and its `empty` line.
+ */
+export function resolveResultView(output, view, options = {}) {
+    const resolved = view ?? (options.infer === true ? inferResultView(output) : undefined);
+    if (resolved === undefined || resolved.kind === 'elsewhere')
+        return null;
+    switch (resolved.kind) {
+        case 'note': {
+            const text = fillTemplate(resolved.text, output);
+            return text === '' ? null : { kind: 'note', text };
+        }
+        case 'metrics': {
+            const readings = resolved.fields
+                .map((field) => ({ field, value: readPath(output, field.path) }))
+                .filter((entry) => entry.value !== undefined && entry.value !== null)
+                .map(({ field, value }) => ({
+                label: field.label,
+                value: toText(value),
+                unit: field.unit ?? null,
+            }));
+            return readings.length === 0 ? null : { kind: 'metrics', readings };
+        }
+        case 'log': {
+            const lines = readPath(output, resolved.lines);
+            if (!Array.isArray(lines) || lines.length === 0)
+                return null;
+            return { kind: 'log', lines: lines.map(toText) };
+        }
+        case 'table': {
+            const rows = readPath(output, resolved.rows);
+            if (!Array.isArray(rows))
+                return null;
+            return {
+                kind: 'table',
+                columns: resolved.columns,
+                rows: rows.map((row) => resolved.columns.map((column) => toText(readPath(row, column.path)))),
+                empty: rows.length === 0 ? (resolved.empty ?? null) : null,
+            };
+        }
+    }
+}
+//# sourceMappingURL=result-view.js.map

package/dist/src/react/core/presentation/result-view.js.map

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

package/dist/src/react/core/presentation/tool-activity.d.ts

@@ -0,0 +1,106 @@
+import type { ToolConfirmation, ToolPresentation, ToolPresentationTone } from '../../../index.js';
+import type { AnyToolUIPart, TranscriptToolCall } from '../transcript/model.js';
+import { type ToolCatalog } from './phrasing.js';
+import { type ResolvedResultView } from './result-view.js';
+/**
+ * Where one call stands, as a person reads it:
+ *  - `running` — input streaming or the tool executing;
+ *  - `awaiting-approval` — an `action` call parked on a person;
+ *  - `done` / `failed` / `denied` — settled. A tool that RETURNS `{ error }` has failed just as much
+ *    as one that threw; the two arrive differently and read the same to a person.
+ */
+export type ToolCallStatus = 'running' | 'awaiting-approval' | 'done' | 'failed' | 'denied' | 'queued' | 'executing' | 'succeeded';
+export interface ToolCallState {
+    status: ToolCallStatus;
+    isSettled: boolean;
+    isFailed: boolean;
+    isDenied: boolean;
+    output: unknown;
+    error: string | null;
+}
+/** Whether the stream classified this call as an `action` (it parks for approval before it runs). */
+export declare function isActionCall(part: AnyToolUIPart): boolean;
+export declare function toolCallState(part: AnyToolUIPart): ToolCallState;
+/**
+ * Which failed calls the model went on to correct, by call id: a call that failed and was followed,
+ * in the same run, by a SUCCESS of the same tool. The operator wants to know a retry happened, not
+ * to read every attempt. A failed read is not corrected by a successful query.
+ */
+export declare function correctedCallIds(parts: readonly AnyToolUIPart[]): Set<string>;
+/** Everything a surface needs to talk about one call without naming it. */
+export interface ToolCallDescription {
+    status: ToolCallStatus;
+    /** "Querying orders" / "Queried orders" — or the generic fallback when the tool declared nothing. */
+    phrase: string;
+    /** The server's noun phrase for the tool; `null` when it declared no presentation. */
+    label: string | null;
+    icon: string | null;
+    tone: ToolPresentationTone;
+    detail: string | null;
+    /** The approval prompt, templated over the call's input; `null` when the tool declared none. */
+    confirm: {
+        title: string;
+        verb: string;
+        detail: string | null;
+    } | null;
+    /** The output read through its view, once the call is `done`; `null` otherwise or when nothing to draw. */
+    result: ResolvedResultView | null;
+    error: string | null;
+    presentation: ToolPresentation | null;
+}
+export interface DescribeToolCallOptions {
+    /** Resolved strings from the call preflight override the tool catalog templates. */
+    confirmation?: ToolConfirmation;
+    /** Words for a tool the catalog does not describe. Default `Working` / `Done`. */
+    fallback?: {
+        running: string;
+        done: string;
+    };
+    /** Infer a result view from the output's shape when the tool declared none. Default `false`. */
+    inferResult?: boolean;
+}
+export declare function describeToolCall(part: AnyToolUIPart, catalog: ToolCatalog | undefined, options?: DescribeToolCallOptions): ToolCallDescription;
+/**
+ * Calls folded under one key — "Database query ×3" — with the state that matters most across them.
+ */
+export interface ToolActivityGroup {
+    key: string;
+    /** The server's label for the group's tool; `null` when it declared no presentation. */
+    label: string | null;
+    icon: string | null;
+    /** Worst-first across the calls: running › awaiting-approval › failed › denied › done. */
+    status: ToolCallStatus;
+    count: number;
+    /** The phrase of the group's LATEST call — what is happening now. */
+    phrase: string;
+    calls: TranscriptToolCall[];
+    /** Calls nested under the group's calls (all depths), when nesting was not expanded. */
+    innerCount: number;
+}
+export interface GroupToolActivityOptions {
+    catalog?: ToolCatalog;
+    /**
+     * What makes two calls "the same activity". Default: the tool's presentation `label`, else its
+     * name. Flippy-style source grouping passes its own (e.g. `github:search`).
+     */
+    keyOf?: (call: TranscriptToolCall, presentation: ToolPresentation | undefined) => string;
+    /**
+     * Replace a call that has nested calls with those calls (recursively), so the activity reads as
+     * what the code-mode run DID rather than "ran code". Default `false`: groups are built over the
+     * top-level calls, and `innerCount` says how much ran beneath them.
+     */
+    expandNested?: boolean;
+    /** Drop failed calls the model corrected with a later success of the same tool. Default `false`. */
+    hideCorrected?: boolean;
+    fallback?: {
+        running: string;
+        done: string;
+    };
+}
+/**
+ * Fold a tool run into activity groups, in order of first appearance. Pass `block.roots` (the
+ * transcript's call tree) so nesting is honoured; a flat `block.calls` works too and simply has
+ * nothing nested.
+ */
+export declare function groupToolActivity(calls: readonly TranscriptToolCall[], options?: GroupToolActivityOptions): ToolActivityGroup[];
+//# sourceMappingURL=tool-activity.d.ts.map

package/dist/src/react/core/presentation/tool-activity.d.ts.map

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