@aparte/core 0.22.0 → 0.24.0

package/dist/types/tools.d.ts

@@ -3,6 +3,7 @@
  * Provider-agnostic tool calling interface
  */
 import type { AparteToolCallSegment } from './segments.js';
+import type { AparteIconName } from '../config/icon-provider.js';
 /** Definition of a tool the AI can call */
 export interface AparteTool {
     name: string;
@@ -160,6 +161,82 @@ export type AparteToolSummary = (segment: AparteToolCallSegment) => string;
  * falls back to the JSON.
  */
 export type AparteToolInputFormatter = (input: Record<string, unknown>) => string;
+/**
+ * Which tools a registration names: one exact name, a RegExp tested against the name
+ * (`name.search(re) !== -1`, so a `g` flag is harmless), or `'*'` for every tool nothing
+ * more specific describes.
+ */
+export type AparteToolMatcher = string | RegExp;
+/**
+ * How a tool's calls are shown — registered with `registerToolDisplay(matcher, display)`.
+ *
+ * Every field is optional; what is left out keeps core's default row. The tool's NAME is
+ * the app's wire format and core never turns it into words on its own: `label` is how an
+ * app gives a person something better to read than `web_search`.
+ */
+export interface AparteToolDisplay {
+    /**
+     * What the row and the approval question call the tool, in place of its identifier.
+     * Plain text, never HTML. A function reads the call (its status, its input); one that
+     * throws falls back to the identifier.
+     */
+    label?: string | ((segment: AparteToolCallSegment) => string);
+    /**
+     * The row's glyph: an icon-provider key (`file`, `edit`, `terminal`… — or `search`,
+     * `globe` from `@aparte/core/icons` once registered). Unknown keys fall back to `tool`.
+     */
+    icon?: AparteIconName | (string & {});
+    /** What the call targets, after the label — see {@link AparteToolSummary}. */
+    summary?: AparteToolSummary;
+    /** The arguments as a person reads them — see {@link AparteToolInputFormatter}. */
+    formatInput?: AparteToolInputFormatter;
+    /**
+     * Draw nothing for these calls. The call stays in the message, in storage and in the
+     * model's history; an approval it needs is still asked.
+     */
+    hidden?: boolean;
+    /** Open the row's disclosure by default (a segment's own `collapsed` wins). */
+    open?: boolean;
+    /**
+     * What is behind the line. Left out, Input and Output: the arguments and the result,
+     * a developer's view. `false`, nothing: the line alone, with no disclosure, for a chat
+     * whose reader should not be one click from raw JSON (`open` and a segment's
+     * `collapsed` then have nothing to open). A function: what it returns, in place of
+     * Input and Output — see {@link AparteToolDetails}.
+     */
+    details?: false | AparteToolDetails;
+    /**
+     * The line a person reads in a conversational chat, where the default is an agent's.
+     * While the call runs, the label shimmers (`aparte-shimmer`) instead of a spinner and
+     * "Running"; once it is done, nothing marks success — the label's tense says it, so
+     * write one that reads the status ("Searching the web…" / "Searched the web" / a plain
+     * "Search the web" for the rest). Under reduced motion the shimmer holds still, so that
+     * label is what says the call runs. A wait
+     * for approval, a refusal, a failure and a stop still show their word and note. The
+     * words it does not show are still read by a screen reader. The target is set in the
+     * chat's font and the chevron moves to the end of the line; the row carries
+     * `data-quiet` for a stylesheet of your own.
+     */
+    quiet?: boolean;
+}
+/**
+ * What a row shows behind its line, in place of Input and Output: a list of sources for a
+ * search, a sentence for a write. Called when the row is drawn and on every update of the
+ * call, so it can read the status and the result as they land — and on a language switch,
+ * whose words are written into the nodes already there when the shape is the same.
+ *
+ * Return an **HTMLElement** and nothing goes through `innerHTML`. Return a **string** and
+ * core inserts it as HTML after the config's HTML sanitizer (`setHtmlSanitizer`, as for
+ * Markdown): what it shows comes from a tool's result, so a script or an event handler in
+ * it is removed. Escape the call's values all the same (`escapeHtml`): the sanitizer keeps
+ * markup that is harmless but can still mislead. Return `''` for nothing behind the
+ * line yet: no disclosure, which appears once there is something (a result, say).
+ *
+ * A function that throws costs the row its detail, never its line, and never falls back
+ * to the raw Input and Output. Register the same function rather than a new closure each
+ * time: a different `details` redraws the messages on screen.
+ */
+export type AparteToolDetails = (segment: AparteToolCallSegment) => HTMLElement | string;
 /**
  * Per-tool segment renderer.
  * Registered via aparteGlobalConfig.registerToolRenderer(toolName, renderer).

package/dist/types/tools.d.ts.map

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

package/dist/utils/format-duration.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A duration as a person reads it, in the locale's own units: "8s", "1m 12s", "1 min 12 s".
+ *
+ * `Intl`'s narrow unit style rather than a sentence of our own: the units, their order and
+ * their spacing are the locale's, and a translation never has to spell "seconds". A floor
+ * of one second — a block that took 300ms still took time, and "0s" reads as nothing.
+ */
+export declare function formatDuration(ms: number, tag?: string): string;
+//# sourceMappingURL=format-duration.d.ts.map

package/dist/utils/format-duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-duration.d.ts","sourceRoot":"","sources":["../../src/utils/format-duration.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAc/D"}

package/dist/utils/tool-line.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What a tool call is called, and what it targets — read by the transcript row AND by the
+ * approval question, so a person cannot read the two differently (the same reason
+ * `tool-input.ts` exists for the arguments).
+ */
+import type { AparteConfig } from '../config/aparte-config.js';
+import type { AparteToolCallSegment } from '../types/index.js';
+/**
+ * The name a call goes by: the label its display declares (`registerToolDisplay`), else
+ * the identifier — the app's wire format, which core never turns into words on its own.
+ * A label that throws or says nothing costs the call its label, not its render.
+ */
+export declare function toolNameOf(segment: AparteToolCallSegment, config: AparteConfig): {
+    text: string;
+    isLabel: boolean;
+};
+/**
+ * What a call targets, from the summary its display declares — `''` when there is none,
+ * or when it throws: a summary reads model-chosen input, and a bad one must cost the call
+ * its one line, not the bubble its render.
+ */
+export declare function toolTargetOf(segment: AparteToolCallSegment, config: AparteConfig): string;
+//# sourceMappingURL=tool-line.d.ts.map

package/dist/utils/tool-line.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-line.d.ts","sourceRoot":"","sources":["../../src/utils/tool-line.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE/D;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,qBAAqB,EAAE,MAAM,EAAE,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAUnH;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,qBAAqB,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CASzF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aparte/core",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "homepage": "https://apartejs.dev/",
   "description": "AI chat and agent UI components as Web Components, with the agent loop inside — zero third-party dependencies",
   "type": "module",
@@ -79,7 +79,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@aparte/engine": "0.22.0"
+    "@aparte/engine": "0.24.0"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",