@teaflask/assistant 0.3.0 → 0.6.0

package/src/components/tool-views/action-view.ts

@@ -1,204 +0,0 @@
-// teaflask.action — the package's one view for every `action__{slug}`
-// tool (tool-views.md, rung 3): customer HTTP actions are structurally
-// our tools — generated from the catalog, their arguments always the
-// same three-key envelope {path_params, query, body} — so one shipped
-// view renders any org's action, in every host, with zero customer
-// frontend work. It reads the recorded call and nothing else: the
-// method and path template ride only the execution-request marker, not
-// the call's bounded props, so they are deliberately not shown — a
-// built-in gets no privileged data. Producer transforms and argument
-// ledger: docs/tool-view-ledgers.md. Arm reachability and the two
-// truncation channels: the tool-view arm-reachability record.
-//   settledOutcomeNotesOf arms — REACHABLE: tool-row no longer gates
-//     output, so a refused, errored (output-error), denied, cancelled,
-//     superseded or offloaded rung-3 call renders its arm in production;
-//     a still-RUNNING call renders none (input-streaming/input-available
-//     break out to []).
-//   resultText === undefined early return — unreachable today (its call
-//     site is guarded by settledWithResult); kept as totality: a view
-//     never throws on posed props.
-
-import type { ToolViewCall, ToolViewProps } from "../../core/tool-view.js";
-import { prettyPrintParameters } from "../pretty-print.js";
-import { CARD_BLOCK_CLASS } from "./parts-classes.js";
-import {
-  actionEnvelopeOf,
-  actionFailureOf,
-  captionRow,
-  card,
-  el,
-  factRows,
-  note,
-  recordOf,
-  scrollRegion,
-  settledOutcomeNotesOf,
-  settledWithResult,
-  statelessToolView,
-} from "./view-dom.js";
-
-const REQUEST_SECTIONS = [
-  ["path_params", "Path parameters"],
-  ["query", "Query"],
-  ["body", "Body"],
-] as const;
-
-const VALUE_PANE_CLASS =
-  "tf:m-0 tf:whitespace-pre-wrap tf:font-mono tf:text-xs tf:text-tf-foreground";
-
-export const actionToolView = statelessToolView(_renderAction);
-
-function _renderAction({ call }: ToolViewProps): HTMLElement {
-  const root = el("div", "tf:flex tf:flex-col tf:gap-2");
-  root.dataset.tfActionView = "";
-  const sections: HTMLElement[] = [];
-  for (const [key, label] of REQUEST_SECTIONS) {
-    const value = call.args[key];
-    if (value === undefined || value === null) {
-      continue;
-    }
-    // An empty record is the same absence the argument ledger already
-    // describes — a labeled section holding "{}" would be a content-free
-    // frame. An empty ARRAY body still renders: "[]" is a value the
-    // customer's endpoint received.
-    const record = recordOf(value);
-    if (record !== null && Object.keys(record).length === 0) {
-      continue;
-    }
-    sections.push(captionRow(label), _valueRows(value));
-  }
-  if (sections.length > 0) {
-    root.append(card(sections));
-  }
-  root.append(...settledOutcomeNotesOf(call));
-  if (call.status === "output-error") {
-    _appendFieldProblems(root, call);
-  }
-  if (settledWithResult(call)) {
-    _appendResponse(root, call);
-  }
-  return root;
-}
-
-/** A failure's per-field problems as property rows, the one structured
- *  fact a failed action carries: the row beside this view already says
- *  Failed and the human reason, so the view adds the fields alone —
- *  never the status or error code. Nothing when the API named none. */
-function _appendFieldProblems(root: HTMLElement, call: ToolViewCall): void {
-  const detail = actionFailureOf(call.errorText)?.detail;
-  const fields = detail?.fields ?? [];
-  if (fields.length === 0) {
-    return;
-  }
-  const rows = factRows(
-    fields.map(
-      (field) => [field.path === "" ? "—" : field.path, field.message] as const,
-    ),
-  );
-  rows.dataset.tfActionFieldProblems = "";
-  const parts = [captionRow("Field problems"), rows];
-  const omitted = detail?.fieldsOmitted ?? 0;
-  if (omitted > 0) {
-    // The API named more than the record carries: say so, never let a
-    // partial list read as the whole.
-    const more = captionRow(
-      `${String(omitted)} more ${omitted === 1 ? "problem" : "problems"} not listed here.`,
-    );
-    more.dataset.tfActionFieldProblemsOmitted = String(omitted);
-    parts.push(more);
-  }
-  root.append(card(parts));
-}
-
-/** A record becomes property rows (one per top-level key, nested values
- *  pretty-printed); anything else — an array, a scalar — is one
- *  pretty-printed block on the same card-child grammar as the rows: the
- *  hairline above, the rows' inset. Either rides in a bounded scrolling
- *  well: a body can run to the door's 20k, and a value that tall would
- *  be the transcript's height, not a card's. */
-function _valueRows(value: unknown): HTMLElement {
-  const record = recordOf(value);
-  if (record !== null) {
-    return scrollRegion([
-      factRows(
-        Object.entries(record).map(
-          ([key, entry]) => [key, _valueOf(entry)] as const,
-        ),
-      ),
-    ]);
-  }
-  const wrapper = el("div", CARD_BLOCK_CLASS);
-  wrapper.dataset.tfActionValueBlock = "";
-  wrapper.append(el("pre", VALUE_PANE_CLASS, prettyPrintParameters(value)));
-  return scrollRegion([wrapper]);
-}
-
-function _valueOf(value: unknown): string | HTMLElement {
-  if (typeof value === "string") {
-    return value === "" ? "—" : value;
-  }
-  if (
-    typeof value === "number" ||
-    typeof value === "boolean" ||
-    typeof value === "bigint"
-  ) {
-    return String(value);
-  }
-  if (value === null || value === undefined) {
-    return "—";
-  }
-  return el("pre", VALUE_PANE_CLASS, prettyPrintParameters(value));
-}
-
-function _appendResponse(root: HTMLElement, call: ToolViewCall): void {
-  if (call.resultText === undefined) {
-    return;
-  }
-  const envelope = actionEnvelopeOf(call.resultText);
-  if (envelope === null) {
-    // Covers the wire's 20k clip too: `call.truncated` is set only by a
-    // WELL-FORMED envelope whose result.truncated is true — which by
-    // construction parsed — so "unparseable but flagged truncated"
-    // cannot co-occur and earns no arm of its own.
-    root.append(
-      note(
-        "The response couldn't be read as an action result and isn't rendered.",
-      ),
-    );
-    return;
-  }
-  const rows: HTMLElement[] = [];
-  let status: HTMLElement | undefined;
-  if (envelope.status !== null) {
-    status = el(
-      "span",
-      envelope.status >= 400
-        ? "tf:font-medium tf:text-tf-destructive"
-        : "tf:text-tf-muted-foreground",
-      `HTTP ${String(envelope.status)}`,
-    );
-    status.dataset.tfActionStatus = String(envelope.status);
-  }
-  rows.push(
-    captionRow(
-      envelope.truncated ? "Response (truncated)" : "Response",
-      status,
-    ),
-  );
-  if (envelope.truncated) {
-    rows.push(
-      captionRow(
-        "The response body was truncated by the client to fit the size cap.",
-      ),
-    );
-  }
-  if (
-    envelope.body === undefined ||
-    envelope.body === null ||
-    envelope.body === ""
-  ) {
-    rows.push(captionRow("Empty response body."));
-  } else {
-    rows.push(_valueRows(envelope.body));
-  }
-  root.append(card(rows));
-}

package/src/components/tool-views/command-view.ts

@@ -1,95 +0,0 @@
-// teaflask.command — a command and its output (tool-views.md, rung 3) as
-// one terminal block: `$ command`, then what it printed. Authored for
-// sandbox_bash and docs_filesystem, which share the shape (a `command`
-// string), and total over their two recorded result formats — the
-// {output, error} record and plain text — by SHAPE, never by tool name:
-// the package presents its own tools only through the opaque-key seam.
-// Argument ledger and producer transforms: docs/tool-view-ledgers.md. Arm
-// reachability and the two truncation channels (1: the envelope's
-// result.truncated → call.truncated; 2: the mapper's 20k clip, invisible
-// client-side and the COMMON one here): the tool-view arm-reachability
-// record.
-//   settledOutcomeNotesOf arms — REACHABLE: tool-row no longer gates
-//     output, so a refused, errored (output-error), denied, cancelled,
-//     superseded or offloaded rung-3 call renders its arm in production;
-//     a still-RUNNING call renders none.
-//   call.truncated arm — channel 1 only: when the unwrapper says the
-//     recorded copy is degraded, the view must refuse to structure it.
-
-import type { ToolViewProps } from "../../core/tool-view.js";
-import {
-  el,
-  note,
-  recordOf,
-  settledOutcomeNotesOf,
-  settledWithResult,
-  statelessToolView,
-  stringOf,
-  terminal,
-} from "./view-dom.js";
-
-/** docsfs's model-facing replacement for a silent exit-0 run
- *  (_render_run_result) — not stdout, so never rendered as output. */
-const DOCS_NO_OUTPUT_SENTENCE =
-  "The command ran with exit code 0 and produced no output.";
-const INCOMPLETE = "The recorded output is incomplete and isn't rendered.";
-const NO_OUTPUT = "The command produced no output.";
-
-export const commandToolView = statelessToolView(_renderCommand);
-
-function _renderCommand({ call }: ToolViewProps): HTMLElement {
-  const root = el("div", "tf:flex tf:flex-col tf:gap-2");
-  root.dataset.tfCommandView = "";
-  const command = stringOf(call.args.command);
-  const streams = settledWithResult(call) ? _streamsOf(call) : null;
-  // The block exists for a prompt line or a stream — an empty or absent
-  // command with nothing printed would paint an empty bordered pre.
-  const hasCommand = command !== null && command !== "";
-  if (hasCommand || streams?.kind === "streams") {
-    root.append(
-      terminal({
-        command,
-        output: streams?.kind === "streams" ? streams.output : undefined,
-        stderr: streams?.kind === "streams" ? streams.stderr : undefined,
-      }),
-    );
-  }
-  root.append(...settledOutcomeNotesOf(call));
-  if (streams?.kind === "note") {
-    root.append(note(streams.text));
-  }
-  return root;
-}
-
-type Streams =
-  | { kind: "streams"; output: string; stderr: string }
-  | { kind: "note"; text: string };
-
-function _streamsOf(call: ToolViewProps["call"]): Streams | null {
-  if (call.truncated === true) {
-    return { kind: "note", text: INCOMPLETE };
-  }
-  // The sandbox_bash shape: {"output": stdout, "error": stderr} — both
-  // strings by construction.
-  const result = recordOf(call.result);
-  const output = result === null ? null : stringOf(result.output);
-  const stderr = result === null ? null : stringOf(result.error);
-  if (output !== null && stderr !== null) {
-    return output === "" && stderr === ""
-      ? { kind: "note", text: NO_OUTPUT }
-      : { kind: "streams", output, stderr };
-  }
-  // The mapper's 20k clip (channel 2) cuts the bash record mid-JSON:
-  // parse fails and resultText holds the cut document, not the output.
-  if (call.result === undefined && call.resultText?.startsWith("{") === true) {
-    return { kind: "note", text: INCOMPLETE };
-  }
-  // The docs_filesystem shape: one text block (stdout, plus [stderr] /
-  // [exit code N] markers only when they occurred).
-  if (call.resultText === undefined) {
-    return null;
-  }
-  return call.resultText === "" || call.resultText === DOCS_NO_OUTPUT_SENTENCE
-    ? { kind: "note", text: NO_OUTPUT }
-    : { kind: "streams", output: call.resultText, stderr: "" };
-}

package/src/components/tool-views/docs-search-view.ts

@@ -1,203 +0,0 @@
-// teaflask.docs-search — the package's view for the docs_search tool
-// (tool-views.md, rung 3): the sections the search returned as list rows
-// in a card — title and heading, the section's address and dates, the
-// matched text — instead of one prose block. It renders the recorded
-// call alone: the hit list is parsed from the tool's own text format
-// (docs_search.py::_render_hits), authored knowledge of our own tool,
-// never a shape sniffed off arbitrary output. Anything that is not that
-// format renders verbatim in a pane, so a format change degrades to the
-// honest text rather than a wrong structure.
-//   settledOutcomeNotesOf arms — REACHABLE: a refused, errored
-//     (output-error), denied, cancelled, superseded or offloaded call
-//     renders its arm; a still-running call renders none (the switch
-//     breaks out); see view-dom.ts.
-//   call.truncated arm — channel 1 only (the envelope flag); the
-//     mapper's 20k clip is invisible here and a cut hit list renders
-//     its complete hits with the cut tail as its last hit's text.
-
-import type { ToolViewProps } from "../../core/tool-view.js";
-import { CARD_BLOCK_CLASS, CARD_TITLE_CLASS } from "./parts-classes.js";
-import {
-  badge,
-  boneRows,
-  captionRow,
-  card,
-  el,
-  fileGlyph,
-  listRow,
-  note,
-  pane,
-  scrollRegion,
-  settledOutcomeNotesOf,
-  settledWithResult,
-  statelessToolView,
-  stringOf,
-} from "./view-dom.js";
-
-/** The producer's no-hits sentence, verbatim (docs_search.py). */
-const NO_HITS_SENTENCE = "No documentation sections matched this query.";
-
-/** `[slug#anchor] Title › Heading` — the first line of every hit. */
-const HIT_HEADLINE = /^\[([^\]#\s]+)#([^\]\s]*)\] (.*)$/;
-/** `Updated: 2026-09-01 · Verified: 2026-09-03` — the optional facts line. */
-const HIT_FACTS =
-  /^Updated: \d{4}-\d{2}-\d{2}( · Verified: \d{4}-\d{2}-\d{2})?$/;
-
-const EXCERPT_CLASS =
-  "tf:mt-0.5 tf:line-clamp-2 tf:text-xs tf:text-tf-muted-foreground";
-
-export interface DocsSearchHit {
-  slug: string;
-  anchor: string;
-  title: string;
-  heading: string | null;
-  facts: string | null;
-  content: string;
-}
-
-export const docsSearchToolView = statelessToolView(_renderDocsSearch);
-
-function _renderDocsSearch({ call }: ToolViewProps): HTMLElement {
-  const root = el("div", "tf:flex tf:flex-col tf:gap-2");
-  root.dataset.tfDocsSearchView = "";
-  const query = stringOf(call.args.query);
-  const title =
-    query === null || query.trim() === ""
-      ? "Results"
-      : `Results for “${query}”`;
-  root.append(...settledOutcomeNotesOf(call));
-  if (!settledWithResult(call) || call.resultText === undefined) {
-    if (
-      call.status === "input-streaming" ||
-      call.status === "input-available"
-    ) {
-      // A gated call is not in flight: the consent reading is the query
-      // as a proposal row with the wait as its badge, never pulsing bones
-      // beside a "Needs input" pill.
-      root.append(
-        call.awaitingDecision
-          ? _proposalCard(query)
-          : el("p", CARD_TITLE_CLASS, title),
-      );
-      if (!call.awaitingDecision) {
-        root.append(boneRows(3));
-      }
-    }
-    return root;
-  }
-  if (call.truncated === true) {
-    root.append(
-      note("The recorded results are incomplete and aren't rendered."),
-    );
-    return root;
-  }
-  if (call.resultText.trim() === NO_HITS_SENTENCE) {
-    root.append(card([captionRow("No sections matched.")], title));
-    return root;
-  }
-  const hits = docsSearchHitsOf(call.resultText);
-  if (hits === null) {
-    // The card title already names the results; the pane's label says
-    // what the pane is — the record as it stands, not the format.
-    root.append(
-      card([_cardInterior(pane("As recorded", call.resultText))], title),
-    );
-    return root;
-  }
-  root.append(card([scrollRegion(hits.map(_hitRow))], title));
-  return root;
-}
-
-function _proposalCard(query: string | null): HTMLElement {
-  const row = listRow({
-    title:
-      query === null || query.trim() === ""
-        ? "Documentation search"
-        : `“${query}”`,
-    secondary: "Search your docs",
-    trailing: badge("Awaiting your decision"),
-  });
-  row.dataset.tfDocsSearchProposal = "";
-  return card([row]);
-}
-
-/** The hit list, or null when the text is not the producer's format.
- *  A hit ends where the next begins — a blank line and then a headline
- *  line (_render_hits joins hits with one blank line) — never at a blank
- *  line alone: a section's content keeps its own paragraph breaks
- *  (mdv1_chunker rejoins a section's blocks with blank lines). */
-export function docsSearchHitsOf(resultText: string): DocsSearchHit[] | null {
-  const lines = resultText.split("\n");
-  let headline = HIT_HEADLINE.exec(lines[0] ?? "");
-  if (headline === null) {
-    return null;
-  }
-  const hits: DocsSearchHit[] = [];
-  let start = 1;
-  for (let index = 1; index <= lines.length; index += 1) {
-    const atEnd = index === lines.length;
-    const next =
-      !atEnd && lines[index - 1] === ""
-        ? HIT_HEADLINE.exec(lines[index] ?? "")
-        : null;
-    if (!atEnd && next === null) {
-      continue;
-    }
-    // The separator blank line belongs to neither hit.
-    hits.push(_hitOf(headline, lines.slice(start, atEnd ? index : index - 1)));
-    if (next === null) {
-      break;
-    }
-    headline = next;
-    start = index + 1;
-  }
-  return hits;
-}
-
-function _hitOf(
-  headline: RegExpExecArray,
-  body: readonly string[],
-): DocsSearchHit {
-  const [, slug, anchor, titleAndHeading] = headline;
-  // The producer appends the heading once, at the end (`{title} › {heading}`),
-  // so the LAST separator is the join — a title may carry the glyph itself.
-  const separator = titleAndHeading.lastIndexOf(" › ");
-  const title =
-    separator === -1 ? titleAndHeading : titleAndHeading.slice(0, separator);
-  const heading =
-    separator === -1 ? null : titleAndHeading.slice(separator + 3);
-  const facts = HIT_FACTS.test(body[0] ?? "") ? body[0] : null;
-  const content = body.slice(facts === null ? 0 : 1).join("\n");
-  return { slug, anchor, title, heading, facts, content };
-}
-
-/** The card's interior for a flush block (the pane): the card-child
- *  grammar every non-row block wears — the rows' inset, a hairline
- *  above unless it opens the card. */
-function _cardInterior(child: HTMLElement): HTMLElement {
-  const wrapper = el("div", CARD_BLOCK_CLASS);
-  wrapper.append(child);
-  return wrapper;
-}
-
-function _hitRow(hit: DocsSearchHit): HTMLElement {
-  // The row reads like a document row: the doc's title, then where in it
-  // the match sits (its heading, its address). The dates the producer
-  // appends are model-facing evidence and stay off the row.
-  const where =
-    hit.heading === null || hit.heading === ""
-      ? hit.slug
-      : `${hit.heading} · ${hit.slug}`;
-  const excerpt =
-    hit.content.trim() === ""
-      ? undefined
-      : el("span", EXCERPT_CLASS, hit.content.trim());
-  const row = listRow({
-    icon: fileGlyph(),
-    title: hit.title,
-    secondary: where,
-    below: excerpt,
-  });
-  row.dataset.tfDocsSearchHit = hit.slug;
-  return row;
-}