@x1a0f3n9/dsh-client-ui-tool 0.1.5-rc.3

package/lib/index.js

@@ -0,0 +1,6 @@
+//#region lib/types/index.js
+/** Host loader entry for the browser-only Tool UI plugin. */
+/** Provides no host-side behavior. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/types/client/apply.d.ts

@@ -0,0 +1,10 @@
+/** Register the Tool call tree, details renderer, and built-in atomic views. */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+/** Required services: the slot registry and the Remote face carrying the Host home used for POSIX `~`. */
+export declare const inject: string[];
+/**
+ * Mount the whole-Tool renderers and built-in atomic Tool registrations.
+ * @param ctx - Client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=apply.d.ts.map

package/lib/types/client/contract/slots.d.ts

@@ -0,0 +1,100 @@
+/** Tool UI slot declarations and their composed component props. */
+import type { HostObservable, InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime } from '@x1a0f3n9/dsh-client-ui-slots';
+import type { RemoteHostFacts } from '@x1a0f3n9/dsh-api-remotes/client';
+import type { OpenFileOptions, ToolCallBlock } from '@x1a0f3n9/dsh-client-ui-chat/client';
+import type { MessageImageLoader, MessageImageSource } from '@x1a0f3n9/dsh-client-ui-conversation/client';
+declare module '@x1a0f3n9/dsh-client-ui-slots' {
+    interface SlotMap {
+        /**
+         * Keyed atomic Tool call view, dispatched by the wire Tool name. Register
+         * with `key: '<tool name>'` to own how one tool's calls render inside a
+         * turn — the key domain is open (any wire tool name, including a tool your
+         * own package registered), so there is no compile-time key set to pick
+         * from and a typo simply never renders.
+         *
+         * A key the shipped composition already covers is replaced, not shared;
+         * an unclaimed key falls back to the generic tool row, so registering is
+         * additive for your own tool and a takeover for a shipped one. The owner
+         * passes the call's identity, its frozen running-or-settled node, and the
+         * expansion state (see ToolCallOwnerProps), so the view stays a pure
+         * function of what the turn already knows.
+         */
+        'tool.call.toolview': {
+            kind: 'keyed';
+            scope: 'session';
+            owner: ToolCallOwnerProps;
+        };
+        /**
+         * Durable images of a settled image-bearing Tool call, rendered through
+         * the attachment presentation plugin. The Tool layer never imports an
+         * attachment implementation: a toolview declares this slot as a child and
+         * renders it with the image card's references plus the session-authorized
+         * loader it received in its owner, and the attachment plugin fills the
+         * gallery. Composing no attachment presentation plugin renders nothing,
+         * which is why the image card keeps its own envelope text beside the
+         * gallery. A child slot is declared by exactly one entry: registering a
+         * second toolview that declares the same child throws at load, so a
+         * future image-bearing tool must reuse this entry or own a distinct
+         * slot.
+         */
+        'tool.call.images': {
+            kind: 'single';
+            scope: 'session';
+            owner: ToolImagesOwnerProps;
+        };
+    }
+}
+/** Owner currency of the Tool image gallery slot: references plus the loader. */
+export interface ToolImagesOwnerProps {
+    /** Durable references or submission-echo previews in result order. */
+    images: readonly MessageImageSource[];
+    /** Session-authorized image URL loader for the durable arm. */
+    loadImage: MessageImageLoader;
+    /** Horizontal placement inside the owning record. */
+    align: 'start' | 'end';
+}
+/** Standard owner currency supplied to every atomic Tool view. */
+export interface ToolCallOwnerProps {
+    /** Tool call identity, stable across running and settled forms. */
+    callId: string;
+    /** Wire Tool name and keyed dispatch value. */
+    toolName: string;
+    /** Frozen running call or settled result node. */
+    block: ToolCallBlock;
+    /** Session workspace root for relative summaries. */
+    cwd?: string | undefined;
+    /** Host account home; POSIX home-rooted summaries display as `~`. */
+    home?: string | undefined;
+    /**
+     * Open a Tool argument path. A view that knows which line the call was about
+     * passes it, and the opened surface lands there.
+     */
+    openFile: (path: string, options?: OpenFileOptions) => void;
+    /**
+     * Session-authorized image loader for the `tool.call.images` slot, supplied
+     * by the chat node that owns this call. A composed chat node always
+     * supplies it (`ChatNodeOwnerProps.loadImage` is required), so the tool
+     * layer never imports an attachment implementation nor handles URL
+     * authorization.
+     */
+    loadImage: MessageImageLoader;
+    /** Inspect this call in the trajectory view when available. */
+    inspect?: (() => void) | undefined;
+}
+/** Full props of a registered atomic Tool view. */
+export type ToolCallViewProps = PropsRuntime<'tool.call.toolview'>;
+/** Injected Host description for POSIX home-path display. */
+export type ToolHostInfoInjected = {
+    hooks: {
+        /**
+         * Fixed Host facts, reached through a hook rather than injected as values:
+         * the renderer memoizes an entry's inject result for the registration's
+         * lifetime, so facts read there would freeze at whatever the first render
+         * saw. Select the field the view needs (`info => info.home`).
+         */
+        hostInfo: HostObservable<RemoteHostFacts>;
+    };
+};
+/** Full props of the Tool call-tree renderer registered as a `tool-call` Chat Node. */
+export type ToolTreeProps = PropsRuntime<'conversation.chat.node', 'tool-call'> & PropsRenderSlots<'tool.call.toolview'> & PropsLocale<'conversation'> & InjectFace<ToolHostInfoInjected>;
+//# sourceMappingURL=slots.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,4 @@
+/** Browser Tool plugin: whole-call composition and keyed atomic Tool views. */
+export { apply, inject } from './apply.ts';
+export type { ToolCallOwnerProps, ToolCallViewProps, ToolHostInfoInjected, ToolTreeProps, } from './contract/slots.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locale.d.ts

@@ -0,0 +1,3 @@
+/** Locale namespace supplied by the conversation owner to Tool renderers. */
+export declare const CONVERSATION_NS = "conversation";
+//# sourceMappingURL=locale.d.ts.map

package/lib/types/client/tool/ToolCallTree.d.ts

@@ -0,0 +1,9 @@
+import type { ToolTreeProps } from '../contract/slots.ts';
+/**
+ * Render one root Tool call and its recursive children through the same
+ * atomic keyed dispatch.
+ * @param props - whole-Tool owner data and the Tool-owned child-slot share.
+ * @returns the Tool call tree.
+ */
+export declare function ToolCallTree({ renderSlot, node, cwd, openFile, inspectCall, loadImage, useHostInfo, t, }: ToolTreeProps): import("react").JSX.Element;
+//# sourceMappingURL=ToolCallTree.d.ts.map

package/lib/types/client/tool/components/AskQuestionCard.d.ts

@@ -0,0 +1,11 @@
+/** Ask-user transcript rendering from validated plain card data. @module */
+import type { AskQuestionCardModel } from '../models/ask-question-card-model.ts';
+/**
+ * Render a validated ask-user transcript from plain card data.
+ * @param props - Localized transcript card data.
+ * @returns the readable answered or unanswered question list.
+ */
+export declare function AskQuestionCard({ card }: {
+    card: AskQuestionCardModel;
+}): import("react").JSX.Element;
+//# sourceMappingURL=AskQuestionCard.d.ts.map

package/lib/types/client/tool/components/ToolRow.d.ts

@@ -0,0 +1,75 @@
+import { type ReactNode } from 'react';
+import type { PropsRenderSlots, TranslateNS } from '@x1a0f3n9/dsh-client-ui-slots';
+import type { OpenFileOptions } from '@x1a0f3n9/dsh-client-ui-chat/client';
+import type { MessageImageLoader } from '@x1a0f3n9/dsh-client-ui-conversation/client';
+import { type DiffCardModel } from '../models/diff-card-model.ts';
+import { type ReadCardModel } from '../models/read-card-model.ts';
+import type { ImageCardModel } from '../models/image-card-model.ts';
+import { type SearchCardModel } from '../models/search-card-model.ts';
+import { type TerminalCardModel } from '../models/terminal-card-model.ts';
+import type { AskQuestionCardModel } from '../models/ask-question-card-model.ts';
+import { type ToolRowState, type ToolRowVariant } from '../models/tool-call-model.ts';
+import type { WebCardModelProps } from '../models/web-card-model.ts';
+export interface ToolRowProps {
+    t: TranslateNS<'conversation'>;
+    variant: ToolRowVariant;
+    /** Wire tool name for tool-owned styling layered over the generic variant. */
+    toolName?: string | undefined;
+    icon: ReactNode;
+    title: string;
+    summary: string;
+    /**
+     * Trailing summary fragment rendered outside the ellipsized summary text, so
+     * a narrow row clips the summary before this. For a fragment whose whole
+     * value is surviving that clip — the todo row's parallel-active count.
+     * null/absent = the summary is the whole collapsed content. Dropped on an
+     * error row, whose collapsed summary is the failure line instead.
+     */
+    summarySuffix?: string | null | undefined;
+    /** Original argument JSON formatted only while the row is expanded. */
+    bodyRaw?: string | null | undefined;
+    /** Flattened result text for the expanded Output section; null/absent = no output section. */
+    output?: string | null | undefined;
+    /** Ask-user transcript card; card fields are mutually exclusive and replace text sections. */
+    askQuestion?: AskQuestionCardModel | null | undefined;
+    /** Error first line shown as the collapsed summary on an error row; null/absent = keep `summary`. */
+    errorSummary?: string | null | undefined;
+    /** Terminal card; card fields are mutually exclusive and replace text sections. */
+    terminal?: TerminalCardModel | null | undefined;
+    diff?: DiffCardModel | null | undefined;
+    read?: ReadCardModel | null | undefined;
+    /**
+     * Image-card material for a call whose result is an image (derived by
+     * `imageCardModel`). Rendered through the `tool.call.images` slot, so the
+     * tool layer never imports an attachment implementation nor handles URL
+     * authorization.
+     */
+    image?: ImageCardModel | null | undefined;
+    /**
+     * Dispatch the image gallery through the tool-owned `tool.call.images`
+     * slot, supplied by the toolview that owns this row together with the
+     * session-authorized loader.
+     */
+    renderSlot?: PropsRenderSlots<'tool.call.images'>['renderSlot'] | undefined;
+    /** Session-authorized image URL loader for the gallery slot. */
+    loadImage?: MessageImageLoader | undefined;
+    search?: SearchCardModel | null | undefined;
+    web?: WebCardModelProps | null | undefined;
+    state: ToolRowState;
+    /**
+     * Filesystem path from tool args; when set with onOpenFile, the summary
+     * renders as a hover-underline link that opens the host default app.
+     */
+    filePath?: string | undefined;
+    /** 1-based line the call was about; absent = open the file at its beginning. */
+    filePathLine?: number | undefined;
+    /** Open the path (already cwd-resolved), landing on `filePathLine` when given. */
+    onOpenFile?: ((path: string, options?: OpenFileOptions) => void) | undefined;
+    /**
+     * Jump to this call in the trajectory view: a hover-revealed Inspect pill
+     * over the expanded body. Absent = no affordance.
+     */
+    inspect?: (() => void) | undefined;
+}
+export declare function ToolRow({ t, variant, toolName, icon, title, summary, summarySuffix, bodyRaw, output, askQuestion, errorSummary, terminal, diff, read, image, renderSlot, loadImage, search, web, state, filePath, filePathLine, onOpenFile, inspect, }: ToolRowProps): import("react").JSX.Element;
+//# sourceMappingURL=ToolRow.d.ts.map

package/lib/types/client/tool/models/ask-question-card-model.d.ts

@@ -0,0 +1,22 @@
+/** Pure ask-user transcript card data shared by its presenter and renderer. @module */
+interface AnsweredQuestionCardItem {
+    id: string;
+    question: string;
+    answers: readonly string[];
+}
+interface UnansweredQuestionCardItem {
+    id: string;
+    question: string;
+}
+/** Validated, localized data rendered by the ask-user transcript card. */
+export type AskQuestionCardModel = {
+    kind: 'answered';
+    questions: readonly AnsweredQuestionCardItem[];
+    skippedLabel: string;
+} | {
+    kind: 'unanswered';
+    questions: readonly UnansweredQuestionCardItem[];
+    verdict: string;
+};
+export {};
+//# sourceMappingURL=ask-question-card-model.d.ts.map

package/lib/types/client/tool/models/diff-card-model.d.ts

@@ -0,0 +1,37 @@
+/** Pure diff-card derivation from raw file-mutation calls and result metadata. @module */
+import type { DiffBlockProps } from '@x1a0f3n9/dsh-client-ui-primitives';
+import type { ToolCallBlock } from './tool-call-model.ts';
+/**
+ * Diff-body lines the chat row shows before collapsing the middle — half the
+ * primitive's own default, which the details panel keeps. A chat row is a
+ * summary surface inside the message flow: the flow must stay scannable across
+ * many calls, while the details panel is the single-call reading surface. The
+ * same split {@link CHAT_TERMINAL_MAX_LINES} draws for a terminal card, so the
+ * two card kinds cap a long body at the same place in the flow. A design
+ * constant of this UI's row geometry, not a deployment choice.
+ */
+export declare const CHAT_DIFF_MAX_LINES = 8;
+/**
+ * The {@link DiffBlock} props this derivation owns. Picked off the primitive's
+ * props so the two stay in step; `maxLines`/`className` belong to each render
+ * site.
+ */
+export interface DiffCardModel {
+    /**
+     * The props {@link DiffBlock} draws. Held as a nested object so a render site
+     * spreads exactly the primitive's own surface and can never leak a
+     * neighbouring field into it.
+     */
+    card: Pick<DiffBlockProps, 'diffs'>;
+}
+/**
+ * Derive running diffs for root write/edit and `str_replace_editor`
+ * create/replace calls, plus applied settled diffs for root write/edit calls.
+ * A successful write with valid empty metadata uses its argument-derived
+ * whole-file diff, matching create and identical-overwrite presentation;
+ * `str_replace_editor` settles through Generic because it has no result view.
+ * @param block - running or settled Tool block.
+ * @returns the diff-card props, or null for the generic path.
+ */
+export declare function diffCardModel(block: ToolCallBlock): DiffCardModel | null;
+//# sourceMappingURL=diff-card-model.d.ts.map

package/lib/types/client/tool/models/image-card-model.d.ts

@@ -0,0 +1,45 @@
+/** Pure image-card derivation from raw result content and metadata. @module */
+import type { ImageAttachmentRef } from '@x1a0f3n9/dsh-attachment';
+import type { ToolCallBlock } from './tool-call-model.ts';
+/**
+ * The image-card material one settled call contributes: the display label plus
+ * the durable references the attachment slot renders as a gallery.
+ *
+ * The bytes are not here. `attachmentId` is opaque and provider-owned, so a UI
+ * resolves it to a session-authorized URL at render time; this model never parses
+ * it nor derives a path from it.
+ */
+export interface ImageCardModel {
+    /** Card label: the read path, shortened the way every other card's is. */
+    label: string;
+    /** The durable images this result returned, in result order. */
+    images: readonly {
+        readonly attachment: ImageAttachmentRef;
+    }[];
+    /**
+     * The model-facing envelope text, for the line under the gallery.
+     *
+     * Taken from the result's own text block rather than the row's flattened
+     * result text: an image read's content is `[text envelope, image block]`, and
+     * flattening JSON.stringifies the image block, which would print the raw
+     * attachment object under the picture — the symptom this card exists to remove.
+     */
+    text: string;
+}
+/**
+ * Derive a settled image card after validating the call head, persisted
+ * metadata (or its argument fallback), and the model-facing image envelope.
+ *
+ * The card is result-side only: a call carries no content until `execute`
+ * returns, so a running `read_image` has none and this returns null for it.
+ * Both root and nested calls settle as ToolResultNode; the nested one (a
+ * read_image dispatched from inside run_code) persists no presentationMeta, so
+ * its label falls back to the call's own `file_path` argument.
+ * @param block - running or settled Tool block.
+ * @param sessionCwd - the session workspace root; a workspace-rooted absolute
+ *   path label displays relative to it. Absent leaves the path as authored.
+ * @param home - host account home; a leftover POSIX home path displays as `~`.
+ * @returns the image-card props, or null for the generic path.
+ */
+export declare function imageCardModel(block: ToolCallBlock, sessionCwd?: string, home?: string): ImageCardModel | null;
+//# sourceMappingURL=image-card-model.d.ts.map

package/lib/types/client/tool/models/primitive-labels.d.ts

@@ -0,0 +1,36 @@
+/** Localized copy adapters for Cordis-free UI primitives used by Tool cards. */
+import type { DiffBlockLabels, MarkdownLabels, ReadBlockLabels, SearchBlockLabels, WebBlockLabels } from '@x1a0f3n9/dsh-client-ui-primitives';
+import type { TranslateNS } from '@x1a0f3n9/dsh-client-ui-slots';
+type T = TranslateNS<'conversation'>;
+/**
+ * Build localized Markdown chrome labels.
+ * @param t - Conversation locale seat.
+ * @returns Markdown chrome labels.
+ */
+export declare function markdownLabels(t: T): MarkdownLabels;
+/**
+ * Build localized diff-card chrome labels.
+ * @param t - Conversation locale seat.
+ * @returns Diff-card chrome labels.
+ */
+export declare function diffBlockLabels(t: T): DiffBlockLabels;
+/**
+ * Build localized read-card chrome labels.
+ * @param t - Conversation locale seat.
+ * @returns Read-card chrome labels.
+ */
+export declare function readBlockLabels(t: T): ReadBlockLabels;
+/**
+ * Build localized search-card chrome labels.
+ * @param t - Conversation locale seat.
+ * @returns Search-card chrome labels.
+ */
+export declare function searchBlockLabels(t: T): SearchBlockLabels;
+/**
+ * Build localized web-card chrome labels.
+ * @param t - Conversation locale seat.
+ * @returns Web-card chrome labels.
+ */
+export declare function webBlockLabels(t: T): WebBlockLabels;
+export {};
+//# sourceMappingURL=primitive-labels.d.ts.map

package/lib/types/client/tool/models/raw-tool-call.d.ts

@@ -0,0 +1,27 @@
+/** Shared narrowing for raw Tool call and result fields consumed by card models. */
+import type { ToolCallBlock, ToolResultNode } from '@x1a0f3n9/dsh-client-ui-chat/client';
+/** A parsed, in-window Tool call whose arguments are a JSON object. */
+export interface ParsedToolCall {
+    name: string;
+    args: Record<string, unknown>;
+}
+/**
+ * Parse the call head paired with one immutable Tool block.
+ * @param block - running or settled Tool block.
+ * @returns the Tool name and object arguments, or null when the call head or valid JSON object is unavailable.
+ */
+export declare function parsedToolCall(block: ToolCallBlock): ParsedToolCall | null;
+/**
+ * Read the exact single text block consumed by first-party card derivations.
+ * @param block - settled Tool result.
+ * @returns its text, or undefined for any other content layout.
+ */
+export declare function singleResultText(block: ToolResultNode): string | undefined;
+/**
+ * Validate the optional escalation pair shared by first-party shell and file
+ * mutation tools.
+ * @param args - parsed open-root Tool arguments.
+ * @returns whether the declared escalation fields form a valid pair.
+ */
+export declare function validEscalationFields(args: Record<string, unknown>): boolean;
+//# sourceMappingURL=raw-tool-call.d.ts.map

package/lib/types/client/tool/models/read-card-model.d.ts

@@ -0,0 +1,43 @@
+/** Pure read-card derivation from raw result content and metadata. @module */
+import type { ReadBlockProps } from '@x1a0f3n9/dsh-client-ui-primitives';
+import type { ToolCallBlock } from './tool-call-model.ts';
+/**
+ * Content lines the chat row's resident read body shows before collapsing the
+ * middle — half the primitive's own default, which the details panel keeps. A
+ * chat row is a summary surface inside the message flow: the flow must stay
+ * scannable across many calls, while the details panel is the single-call
+ * reading surface. A design constant of this UI's row geometry, not a
+ * deployment choice, so it is fixed here rather than a plugin Config field. The
+ * same split [`CHAT_TERMINAL_MAX_LINES`](./terminal-card-model.ts) draws for
+ * terminal output.
+ */
+export declare const CHAT_READ_MAX_LINES = 8;
+/**
+ * The {@link ReadBlock} props this derivation owns. Picked off the primitive's
+ * props so the two stay in step; `maxLines`/`className` belong to each render
+ * site.
+ */
+export type ReadCardModel = Pick<ReadBlockProps, 'label' | 'lines' | 'totalLines' | 'lang'>;
+/**
+ * The line one `read` call was about, from its arguments.
+ *
+ * `offset` is the read tool's own 1-based start line, so opening the path can
+ * land where the model looked. Available while the call is still running,
+ * unlike the persisted metadata, because the arguments carry it. The arguments
+ * are model-produced JSON: only an integer of at least 1 is a line, and a call
+ * whose `offset` is anything else names none.
+ * @param block - running or settled Tool block.
+ * @returns the 1-based line, or undefined when the call named none.
+ */
+export declare function readCallLine(block: ToolCallBlock): number | undefined;
+/**
+ * Derive a settled root read card after validating its persisted metadata and
+ * model-facing read envelope.
+ * @param block - running or settled Tool block.
+ * @param sessionCwd - the session workspace root; a workspace-rooted absolute
+ *   path label displays relative to it. Absent leaves the path as authored.
+ * @param home - host account home; a leftover POSIX home path displays as `~`.
+ * @returns the read-card props, or null for the generic path.
+ */
+export declare function readCardModel(block: ToolCallBlock, sessionCwd?: string, home?: string): ReadCardModel | null;
+//# sourceMappingURL=read-card-model.d.ts.map

package/lib/types/client/tool/models/search-card-model.d.ts

@@ -0,0 +1,23 @@
+/** Pure search-card derivation from raw grep/glob result metadata. @module */
+import type { SearchBlockProps } from '@x1a0f3n9/dsh-client-ui-primitives';
+import type { ToolCallBlock } from './tool-call-model.ts';
+type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : never;
+/** The {@link SearchBlockProps} union minus each render site's own fields. */
+type SearchBlockModelProps = DistributiveOmit<SearchBlockProps, 'labels' | 'maxLines' | 'className'>;
+/** Result rows retained in a Chat card before its middle collapses. */
+export declare const CHAT_SEARCH_MAX_LINES = 8;
+/** Search-card props plus an optional locator for a capped full result. */
+export interface SearchCardModel {
+    /** Props consumed by {@link SearchBlock}. */
+    card: SearchBlockModelProps;
+    /** Raw result text containing the full-result locator for a capped search. */
+    recovery: string | undefined;
+}
+/**
+ * Derive a settled root grep/glob card from persisted metadata.
+ * @param block - running or settled Tool block.
+ * @returns search-card props, or null for the generic path.
+ */
+export declare function searchCardModel(block: ToolCallBlock): SearchCardModel | null;
+export {};
+//# sourceMappingURL=search-card-model.d.ts.map

package/lib/types/client/tool/models/terminal-card-model.d.ts

@@ -0,0 +1,87 @@
+/** Pure terminal-card derivation from raw Tool call and result fields. @module */
+import type { TerminalBlockLabels, TerminalBlockProps } from '@x1a0f3n9/dsh-client-ui-primitives';
+import type { TranslateNS } from '@x1a0f3n9/dsh-client-ui-slots';
+import type { ToolCallBlock } from './tool-call-model.ts';
+/**
+ * Build the TerminalBlock display copy from the conversation locale seat —
+ * the one place the primitive's label surface pairs with this package's
+ * dictionary, shared by every terminal render site (chat row, bash row,
+ * details panel).
+ * @param t - the render site's conversation locale seat.
+ * @returns the full label set for {@link TerminalBlockProps}'s `labels`.
+ */
+export declare function terminalBlockLabels(t: TranslateNS<'conversation'>): TerminalBlockLabels;
+/**
+ * The {@link TerminalBlock} props this derivation owns. Picked off the
+ * primitive's props so the two stay in step; `maxLines`/`className` belong to
+ * each render site.
+ */
+export interface TerminalCardModel {
+    /**
+     * The locale-neutral props {@link TerminalBlock} draws. The render site adds
+     * `command` after resolving {@link copy} through its locale seat.
+     */
+    card: Pick<TerminalBlockProps, 'cwd' | 'output' | 'exitCode' | 'signal' | 'running'>;
+    /**
+     * Verbatim Tool data or semantic `terminal_send` data. Product copy stays
+     * unresolved until a render site supplies its locale seat.
+     */
+    copy: {
+        readonly kind: 'shell';
+        readonly command: string;
+        readonly description: string | undefined;
+    } | {
+        readonly kind: 'terminal-send';
+        readonly text: string;
+        readonly sessionId: string;
+    };
+}
+interface LocalizedTerminalCardModel {
+    readonly card: Pick<TerminalBlockProps, 'command' | 'cwd' | 'output' | 'exitCode' | 'signal' | 'running'>;
+    readonly description: string | undefined;
+}
+/**
+ * Resolve locale-owned `terminal_send` copy while preserving Tool-authored
+ * shell commands and descriptions verbatim.
+ * @param model - locale-neutral terminal card data.
+ * @param t - the render site's conversation locale seat.
+ * @returns terminal props and description ready for rendering.
+ */
+export declare function localizeTerminalCardModel(model: TerminalCardModel, t: TranslateNS<'conversation'>): LocalizedTerminalCardModel;
+/**
+ * True when a settled terminal card reports a failing exit — a non-zero code
+ * or a terminating signal. The bash tool settles a failing command as a
+ * completed call (`isError` stays false: the exit status is result data), so
+ * this is the collapsed row's only failure signal; without it the red exit
+ * pill would be visible only after expanding the card.
+ * @param model - a derived terminal card.
+ * @returns whether the card's exit status is a failure.
+ */
+export declare function terminalFailed(model: TerminalCardModel): boolean;
+/**
+ * Identify a settled root call from the persistent Bash or PowerShell tool.
+ * Its result stays on the generic input/output path because the persistent
+ * shell can report resets and partial output without one process exit status.
+ * @param block - running or settled Tool block.
+ * @returns whether the block is a settled persistent-shell call.
+ */
+export declare function isSettledPersistentShellCall(block: ToolCallBlock): boolean;
+/**
+ * Identify a settled foreground shell preview whose spill footer can hide the exit marker.
+ * @param block - running or settled Tool block.
+ * @returns whether the shell output must remain generic without an inferred exit status.
+ */
+export declare function isSpilledShellCall(block: ToolCallBlock): boolean;
+/**
+ * Derive terminal props for supported shell and terminal-send calls, including
+ * nested Code Dispatch calls. Standard shell results parse their final status
+ * marker; persistent shell results, spill previews, background calls, errors,
+ * and malformed input use the generic path. {@link isSettledPersistentShellCall} lets that generic
+ * persistent result remain expandable without inventing one process status.
+ * @param block - running or settled Tool block.
+ * @param sessionCwd - session workspace root used to resolve workdir.
+ * @returns locale-neutral terminal-card data, or null for the generic path.
+ */
+export declare function terminalCardModel(block: ToolCallBlock, sessionCwd?: string): TerminalCardModel | null;
+export {};
+//# sourceMappingURL=terminal-card-model.d.ts.map

package/lib/types/client/tool/models/tool-call-model.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Pure row-model derivation for tool summary rows: variant classification,
+ * one-line summary, expansion-time body input, and flattened result output
+ * from the frozen call slice. Input material comes from the call ARGUMENTS;
+ * output and error material from the settled result node. A supported terminal
+ * call gets its expanded body from `terminalCardModel` instead.
+ */
+import type { ToolCallBlock, ToolResultNode } from '@x1a0f3n9/dsh-client-ui-chat/client';
+import type { LocaleKeysOf } from '@x1a0f3n9/dsh-client-ui-slots';
+export type { ToolCallBlock } from '@x1a0f3n9/dsh-client-ui-chat/client';
+/** Tool-call row variants selected by the generic atomic renderer. */
+export type ToolRowVariant = 'search' | 'read' | 'bash' | 'write' | 'edit' | 'code' | 'others';
+/** Row state semantic; colors self-supplied via StateDot (design gives none). */
+export type ToolRowState = 'running' | 'ok' | 'error' | 'stopped';
+type ToolTitleKey = Extract<LocaleKeysOf<'conversation'>, `tool.title.${string}`>;
+/** Locale key per generic row variant. */
+export declare const VARIANT_TITLE_KEYS: {
+    readonly search: "tool.title.search";
+    readonly read: "tool.title.read";
+    readonly bash: "tool.title.bash";
+    readonly write: "tool.title.write";
+    readonly edit: "tool.title.edit";
+    readonly code: "tool.title.code";
+    readonly others: "tool.title.generic";
+};
+/**
+ * Classify a tool name into its row variant.
+ * @param toolName - wire tool name.
+ * @returns matching variant, others when unknown.
+ */
+export declare function classifyTool(toolName: string): ToolRowVariant;
+/** Everything ToolRow needs, derived once from the frozen slice. */
+export interface ToolRowModel {
+    variant: ToolRowVariant;
+    titleKey: ToolTitleKey;
+    summary: string;
+    /**
+     * Filesystem path from args (`path` / `file_path`) when the row is a file
+     * tool; absent for URL reads and non-file tools. The chat view resolves
+     * relative values against the session cwd before opening.
+     */
+    filePath: string | undefined;
+    /** Original argument JSON retained for expansion-time body formatting. */
+    bodyRaw: string | null;
+    /** Flattened result text ({@link resultText}); null while running or when the result carries no text. */
+    output: string | null;
+    /** First line of the result text on an error row; null for every other state. */
+    errorSummary: string | null;
+    state: ToolRowState;
+}
+/**
+ * Flatten a settled result's content blocks to display text: text blocks
+ * verbatim, other block shapes as pretty JSON. Empty content on a failed call
+ * falls back to the structured error's `name: code` line.
+ * @param node - the settled result node.
+ * @returns the flattened result text (may be empty).
+ */
+export declare function resultText(node: ToolResultNode): string;
+/**
+ * Format one argument payload when its generic input body becomes visible.
+ * @param variant - row presentation selected for the Tool name.
+ * @param argsRaw - original argument JSON or incomplete raw text.
+ * @returns display body, or null for empty input.
+ */
+export declare function formatToolBody(variant: ToolRowVariant, argsRaw: string): string | null;
+/**
+ * Derive the full row model from a frozen call slice.
+ * @param toolName - wire tool name (dispatch-supplied; survives windowless results).
+ * @param block - RunningToolCall or ToolResultNode off the snapshot caches.
+ * @param cwd - session workspace root; workspace-rooted path summaries display relative to it.
+ * @param home - host account home; a leftover POSIX home path displays as `~`.
+ * @returns the row model.
+ */
+export declare function toolRowModel(toolName: string, block: ToolCallBlock, cwd?: string, home?: string): ToolRowModel;
+//# sourceMappingURL=tool-call-model.d.ts.map

package/lib/types/client/tool/models/web-card-model.d.ts

@@ -0,0 +1,14 @@
+/** Pure web-card derivation from raw web result metadata. @module */
+import type { WebBlockProps } from '@x1a0f3n9/dsh-client-ui-primitives';
+import type { ToolCallBlock } from './tool-call-model.ts';
+type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : never;
+/** Web-card data owned by the presenter; render sites add localized labels and classes. */
+export type WebCardModelProps = DistributiveOmit<WebBlockProps, 'labels' | 'className'>;
+/**
+ * Derive a settled root web-search or web-fetch card from persisted metadata.
+ * @param block - running or settled Tool block.
+ * @returns web-card props, or null for the generic path.
+ */
+export declare function webCardModel(block: ToolCallBlock): WebCardModelProps | null;
+export {};
+//# sourceMappingURL=web-card-model.d.ts.map