@teaflask/assistant 0.0.0 → 0.3.0

package/src/core/tool-view.ts

@@ -0,0 +1,261 @@
+// The tool-view contract (tool-views.md): one view per tool call, resolved
+// once over four rungs, mounted once in the row's body for the call's whole
+// lifecycle. A view is a presentation of a tool call, not an approval
+// mechanism — it receives the call and nothing else. The imperative adapter
+// is canonical; the React registry is sugar over the same lifecycle: one
+// contract, two spellings, never two systems. Runtime-React-free by design.
+
+import { actionToolView } from "../components/tool-views/action-view.js";
+import { commandToolView } from "../components/tool-views/command-view.js";
+import { docsSearchToolView } from "../components/tool-views/docs-search-view.js";
+import { fileEditToolView } from "../components/tool-views/file-edit-view.js";
+import { questionsToolView } from "../components/tool-views/questions-view.js";
+import type { ToolCallState } from "./tool-call-display.js";
+
+/** The resolved palette a view renders under — "light" | "dark", never the
+ *  authored "auto" (use-resolved-theme-mode.ts resolves it). */
+export type ToolViewThemeMode = "light" | "dark";
+
+/** A JSON Schema document, verbatim from the wire: the catalog row's
+ *  declared shape, untyped by design — data a view may read, never validated. */
+export type JsonSchema = Record<string, unknown>;
+
+/** The recorded tool call a view presents — the contract's entire data
+ *  surface. The generics default to today's untyped behaviour so generated
+ *  per-org argument types are usable when they arrive. */
+export interface ToolViewCall<
+  TArgs = Record<string, unknown>,
+  TResult = unknown,
+> {
+  toolName: string;
+  toolCallId: string;
+  status: ToolCallState;
+  /** True while a pending approval or elicitation anchored to this call
+   *  awaits the member. The view may say so; it can never decide. */
+  awaitingDecision: boolean;
+  /** The streamed arguments, parsed, minus the protocol-reserved `caption`
+   *  — the row's label, never an argument. `{}` while the argument text is
+   *  still arriving or is not a JSON record. */
+  args: TArgs;
+  /** The result parsed for presentation: the tool-result/v1 envelope
+   *  unwrapped (core/tool-result-envelope.ts), other JSON passed through.
+   *  Absent until it lands, when not JSON, or when `truncated`. */
+  result?: TResult;
+  /** The result verbatim from the wire; absent until it lands (and
+   *  withheld upstream on errored, denied, cancelled, refused and
+   *  offloaded calls, exactly as the technical panes withhold it). */
+  resultText?: string;
+  /** True when the wire's result was degraded to fit the size cap: the
+   *  bytes in `resultText` are honest; `result` refuses to structure them. */
+  truncated?: boolean;
+  /** True when the wire's result was the context offloader's
+   *  model-facing replacement, not the tool's output. */
+  offloaded?: boolean;
+  errorText?: string;
+  refusalText?: string;
+  /** The tool's registered argument schema, when the wire carried one (the
+   *  `approval_requested` marker or `tool_call_annotated`). Absent
+   *  is a legitimate answer — `undefined`, never `{}`, never inferred — and
+   *  a view must degrade, never demand. The runtime door beside `TArgs`. */
+  argsSchema?: JsonSchema;
+  /** The tool's registered success-result schema (`tool_output_schema`)
+   *  — same channels and absence semantics as `argsSchema`. */
+  resultSchema?: JsonSchema;
+}
+
+/** What a view receives — the call, and the one ambient fact it may not
+ *  resolve itself. Additively extensible: a future `actions` member is a
+ *  recorded reserved step (tool-views.md), never this contract's. */
+export interface ToolViewProps<
+  TArgs = Record<string, unknown>,
+  TResult = unknown,
+> {
+  call: ToolViewCall<TArgs, TResult>;
+  context: { themeMode: ToolViewThemeMode };
+}
+
+/** A mounted view. `update` MUST apply new props in place, so local UI
+ *  state survives the call's status advancing; `destroy` runs on unmount. */
+export interface ToolViewInstance<
+  TArgs = Record<string, unknown>,
+  TResult = unknown,
+> {
+  update(props: ToolViewProps<TArgs, TResult>): void;
+  destroy(): void;
+}
+
+/** The canonical authoring form: an imperative mount into a package-owned
+ *  container. A throw from `mount` or `update` is the adapter's one failure
+ *  channel — the slot reports it and resolution falls to the rung below.
+ *  `mount`/`update` are METHOD declarations on purpose: bivariant parameters
+ *  let a typed adapter assign into the default-typed registration slot
+ *  (docs/tool-call-contract.md, "Adapter typing" — use `type` aliases). */
+export interface ToolViewAdapter<
+  TArgs = Record<string, unknown>,
+  TResult = unknown,
+> {
+  mount(
+    container: HTMLElement,
+    props: ToolViewProps<TArgs, TResult>,
+  ): ToolViewInstance<TArgs, TResult>;
+}
+
+/** The operation-mark role: the identical lifecycle over identical props,
+ *  named apart so the roles can diverge additively (tool-view-slot.tsx). */
+export interface IconAdapter<
+  TArgs = Record<string, unknown>,
+  TResult = unknown,
+> {
+  mount(
+    container: HTMLElement,
+    props: ToolViewProps<TArgs, TResult>,
+  ): ToolViewInstance<TArgs, TResult>;
+}
+
+/** One registration, two roles: a view, an icon, or both. `version` is the
+ *  contract version the adapters target; a wire ref resolves only on exact
+ *  match (rungs 1 and 3). Default-typed slots: registries are heterogeneous. */
+export interface ToolViewRegistration {
+  version: number;
+  view?: ToolViewAdapter;
+  icon?: IconAdapter;
+}
+
+/** The registry a trusted host supplies (`toolViews` on the provider or the
+ *  script-tag elements), keyed by the wire key a backend annotation names
+ *  (rung 1) or the host's exact tool name (rung 2). No code rides the wire. */
+export type ToolViewRegistry = Readonly<Record<string, ToolViewRegistration>>;
+
+/** The reserved namespace for package-shipped views (rung 3). */
+const RESERVED_TOOL_VIEW_KEY_PREFIX = "teaflask.";
+
+/** True for keys the package owns. A reserved key never resolves through
+ *  the HOST registry — by wire key or tool name — so tool output can never
+ *  name a privileged view and a host cannot occupy the namespace. */
+export function isReservedToolViewKey(key: string): boolean {
+  return key.startsWith(RESERVED_TOOL_VIEW_KEY_PREFIX);
+}
+
+/** Rung 3 — the package's own views under reserved `teaflask.*` keys, as
+ *  vanilla adapters (runtime-React-free); the backend names them beside the
+ *  tools in tool_call_display.py. Frozen: nothing registers here at runtime. */
+export const PACKAGE_TOOL_VIEWS: ToolViewRegistry = Object.freeze({
+  "teaflask.questions": { version: 1, view: questionsToolView },
+  "teaflask.action": { version: 1, view: actionToolView },
+  "teaflask.command": { version: 1, view: commandToolView },
+  "teaflask.file-edit": { version: 1, view: fileEditToolView },
+  "teaflask.docs-search": { version: 1, view: docsSearchToolView },
+});
+
+/** The tool name a granted catalog action mounts as
+ *  (the serving side's action_tool_name): the slug shown on the
+ *  Actions page, under the `action__` prefix — the one spelling a HOST
+ *  gets. The dashboard's agent-config twin (draft-writers.ts, kept apart
+ *  by the import law) is pinned equal to this and the backend constant by
+ *  the dashboard's action-tool-prefix test. */
+export function actionToolName(slug: string): string {
+  return `action__${slug}`;
+}
+
+/** A registry written in action SLUGS — the names the Actions page shows
+ *  — keyed for rung 2 by the tool name each slug mounts as. A registry
+ *  of ordinary tool names composes beside it with a spread. */
+export function actionToolViews(
+  bySlug: Readonly<Record<string, ToolViewRegistration>>,
+): ToolViewRegistry {
+  const registry: Record<string, ToolViewRegistration> = {};
+  for (const [slug, registration] of Object.entries(bySlug)) {
+    registry[actionToolName(slug)] = registration;
+  }
+  return registry;
+}
+
+/** A statically resolved view candidate: which rung answered, under
+ *  which key, with which adapter. */
+export interface ResolvedToolView {
+  rung: 1 | 2 | 3;
+  key: string;
+  adapter: ToolViewAdapter;
+}
+
+export interface ResolvedToolViewIcon {
+  rung: 1 | 2 | 3;
+  key: string;
+  adapter: IconAdapter;
+}
+
+/** The presenter's tool-view slot: the rung 1–3 candidates in ladder order,
+ *  per role, plus the lazily assembled call (tool-call-presentation.ts).
+ *  Rung 4 — the package default — is the definitional terminal, never a
+ *  list member: exhausting `views` IS the resolution "package default". */
+export interface ToolViewResolution {
+  views: readonly ResolvedToolView[];
+  icons: readonly ResolvedToolViewIcon[];
+  call: ToolViewCall;
+}
+
+/** The four-rung resolution ladder (docs/tool-call-contract.md, "The
+ *  resolution ladder"), static half: host registry by exact `{key,
+ *  version}` (1), host registry by exact tool name (2), package built-ins
+ *  by reserved `teaflask.*` key (3); rung 4 is the definitional default.
+ *  Own-property-guarded lookups; reserved keys refused at both host rungs. */
+export function resolvedToolViewsOf(
+  ref: { key: string; version: number } | undefined,
+  toolName: string,
+  registry: ToolViewRegistry | undefined,
+  builtIns: ToolViewRegistry = PACKAGE_TOOL_VIEWS,
+): {
+  views: readonly ResolvedToolView[];
+  icons: readonly ResolvedToolViewIcon[];
+} {
+  const candidates: {
+    rung: 1 | 2 | 3;
+    key: string;
+    registration: ToolViewRegistration;
+  }[] = [];
+  if (ref !== undefined && !isReservedToolViewKey(ref.key)) {
+    const registration = _ownRegistrationOf(registry, ref.key);
+    if (registration !== undefined) {
+      if (registration.version === ref.version) {
+        candidates.push({ rung: 1, key: ref.key, registration });
+      }
+    }
+  }
+  if (!isReservedToolViewKey(toolName)) {
+    const registration = _ownRegistrationOf(registry, toolName);
+    if (registration !== undefined) {
+      candidates.push({ rung: 2, key: toolName, registration });
+    }
+  }
+  if (ref !== undefined && isReservedToolViewKey(ref.key)) {
+    const registration = _ownRegistrationOf(builtIns, ref.key);
+    if (registration !== undefined) {
+      if (registration.version === ref.version) {
+        candidates.push({ rung: 3, key: ref.key, registration });
+      }
+    }
+  }
+  const views: ResolvedToolView[] = [];
+  const icons: ResolvedToolViewIcon[] = [];
+  for (const { rung, key, registration } of candidates) {
+    if (registration.view !== undefined) {
+      views.push({ rung, key, adapter: registration.view });
+    }
+    if (registration.icon !== undefined) {
+      icons.push({ rung, key, adapter: registration.icon });
+    }
+  }
+  return { views, icons };
+}
+
+function _ownRegistrationOf(
+  registry: ToolViewRegistry | undefined,
+  key: string,
+): ToolViewRegistration | undefined {
+  if (registry === undefined) {
+    return undefined;
+  }
+  return Object.prototype.hasOwnProperty.call(registry, key)
+    ? registry[key]
+    : undefined;
+}

package/src/core/transcript-lease.ts

@@ -0,0 +1,54 @@
+// Surface presence — the transcript lease: a mounted transcript chrome
+// registers its presence for its lifetime, and presence is what upgrades
+// the socket policy and arms the leased idle re-read. The _leaseHolders
+// roster stays a store field per the friend convention.
+
+import {
+  publishStore,
+  scheduleConnectionSync,
+} from "./conversation-publish.js";
+import type { AssistantConversationStore } from "./conversation-store.js";
+import { syncIdleRecheck } from "./idle-recheck.js";
+
+/** A mounted transcript chrome registers its presence for its lifetime;
+ *  the release is the returned function (idempotent). Any number of
+ *  surfaces may render the same cells concurrently — the store is the
+ *  only connection driver, so there is nothing left to collide.
+ *  Presence upgrades the socket policy (see syncConnection): a mounted
+ *  surface guarantees the epoch connects once so history paints, and
+ *  the LAST release mid-live-turn changes nothing — the store's own run
+ *  simply keeps streaming (the old CopilotChat-abort handoff dance is
+ *  gone with the chassis). LAW: never bump reconnectNonce
+ *  from this release path — a keyed remount releases and re-acquires in
+ *  one tick during normal reconnects. */
+export function acquireTranscriptLeaseFromStore(
+  store: AssistantConversationStore,
+  surface: string,
+): () => void {
+  store._leaseHolders.push(surface);
+  // A human is present again: the automatic-reconnect budget refills.
+  store._automaticReconnects = 0;
+  // The presence flip may demand a connect (a chrome mounting over a
+  // never-connected epoch); the decision rides the same coalesced
+  // microtask as every other trigger.
+  scheduleConnectionSync(store);
+  // Presence also arms the idle re-read — the acquire path
+  // deliberately never publishes, so the sync must run here.
+  syncIdleRecheck(store);
+  let released = false;
+  return () => {
+    if (released) {
+      return;
+    }
+    released = true;
+    const index = store._leaseHolders.indexOf(surface);
+    if (index !== -1) {
+      store._leaseHolders.splice(index, 1);
+    }
+    // The publish schedules the connect decision on the coalesced
+    // microtask (see scheduleConnectionSync), so a keyed transcript
+    // REMOUNT (release then re-acquire in the same tick) is seen
+    // settled before the store acts.
+    publishStore(store);
+  };
+}