@teaflask/assistant 0.0.0 → 0.3.0

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

@@ -0,0 +1,204 @@
+// 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

@@ -0,0 +1,95 @@
+// 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

@@ -0,0 +1,203 @@
+// 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;
+}