@teaflask/assistant 0.0.0 → 0.3.0

package/src/contract/events.ts

@@ -0,0 +1,117 @@
+// The stream's frozen AG-UI event vocabulary. Structural shapes come from
+// @ag-ui/core; CUSTOM marker names and payloads are generated from
+// serving-openapi.json. Clients MUST ignore unrecognized events and fields.
+
+import type {
+  ApprovalRequestedMarker,
+  ApprovalResolvedMarker,
+  InterruptAnswerConsumedMarker,
+  RunResumedMarker,
+  SubagentResultsDeliveredMarker,
+  ToolExecutionRequestedMarker,
+} from "../generated/models/index.js";
+import { AssistantStreamMarkerName } from "../generated/models/index.js";
+
+// The @ag-ui/core subset the backend emits: product truth, not generated.
+export type AssistantStreamEventType =
+  | "TEXT_MESSAGE_START"
+  | "TEXT_MESSAGE_CONTENT"
+  | "TEXT_MESSAGE_END"
+  | "REASONING_START"
+  | "REASONING_END"
+  | "REASONING_MESSAGE_START"
+  | "REASONING_MESSAGE_CONTENT"
+  | "REASONING_MESSAGE_END"
+  | "TOOL_CALL_START"
+  | "TOOL_CALL_ARGS"
+  | "TOOL_CALL_END"
+  | "TOOL_CALL_RESULT"
+  | "RUN_STARTED"
+  | "RUN_FINISHED"
+  | "RUN_ERROR"
+  | "CUSTOM";
+
+// A retried activity attempt, emitted only when attempt > 1 — never a
+// message; the client reads it for retry severance only (stream-resume).
+export const RUN_RESUMED_EVENT_NAME = AssistantStreamMarkerName.run_resumed;
+
+export type RunResumedPayload = RunResumedMarker;
+
+// One per pending approval while the turn awaits input; tool_call_id anchors
+// the ask to the already-streamed tool call (the card is keyed by interrupt_id).
+export const APPROVAL_REQUESTED_EVENT_NAME =
+  AssistantStreamMarkerName.approval_requested;
+
+// The approval-inbox decoder guarantees these server-defaulted fields.
+export type ApprovalRequestedPayload = ApprovalRequestedMarker &
+  Required<
+    Pick<
+      ApprovalRequestedMarker,
+      | "tool_args"
+      | "tool_input_schema"
+      | "tool_output_schema"
+      | "round"
+      | "gated"
+      | "trust_available"
+    >
+  >;
+
+// The durable receipt of a human's answer to an approval_requested ask —
+// never a message; a replayed receipt flips the replayed card to answered.
+export const APPROVAL_RESOLVED_EVENT_NAME =
+  AssistantStreamMarkerName.approval_resolved;
+
+export type ApprovalResolvedPayload = ApprovalResolvedMarker;
+
+// A resume carried this pause's answer into the agent: never
+// rendered, it is consumed evidence for the pending-decision-gap derivation.
+export const INTERRUPT_ANSWER_CONSUMED_EVENT_NAME =
+  AssistantStreamMarkerName.interrupt_answer_consumed;
+
+export type InterruptAnswerConsumedPayload = InterruptAnswerConsumedMarker;
+
+// The turn settled failed outside any single tool — never a
+// message or banner. Its live run ends in RUN_ERROR; on replay the terminal
+// demotes to RUN_FINISHED and this marker is the failure's durable record.
+export const TURN_FAILED_EVENT_NAME = AssistantStreamMarkerName.turn_failed;
+
+// The member ended the turn; same { receipt } shape as turn_failed.
+export const TURN_STOPPED_EVENT_NAME = AssistantStreamMarkerName.turn_stopped;
+
+// One per pending client-executed tool call while the turn awaits input —
+// this package's execution loop executes it and POSTs the result back.
+export const TOOL_EXECUTION_REQUESTED_EVENT_NAME =
+  AssistantStreamMarkerName.tool_execution_requested;
+
+// The execution-inbox decoder guarantees these server-defaulted fields.
+export type ToolExecutionRequestedPayload = ToolExecutionRequestedMarker &
+  Required<Pick<ToolExecutionRequestedMarker, "round">>;
+
+// Durable receipt of a delivered result: a reconnect never re-runs the request.
+export const TOOL_RESULT_RECORDED_EVENT_NAME =
+  AssistantStreamMarkerName.tool_result_recorded;
+
+// Backend-authored human copy for one tool call, anchored by tool_call_id. May
+// arrive more than once per call: merged per field by tool-call-display-anchors.ts.
+export const TOOL_CALL_ANNOTATED_EVENT_NAME =
+  AssistantStreamMarkerName.tool_call_annotated;
+
+// A machine-started delivery turn opens its run with this receipt
+// naming the settled dispatches it pushes. A quiet divider, never a message.
+export const SUBAGENT_RESULTS_DELIVERED_EVENT_NAME =
+  AssistantStreamMarkerName.subagent_results_delivered;
+
+export type SubagentResultsDeliveredPayload = SubagentResultsDeliveredMarker;
+
+// The turn's settled token totals: one per settled turn that had
+// usage to sum, landed just before the terminal. Only finality "final" is
+// settled truth ("partial" sums are lower bounds); absence means UNKNOWN —
+// never an estimate or zero.
+export const TURN_USAGE_RECORDED_EVENT_NAME =
+  AssistantStreamMarkerName.turn_usage_recorded;
+
+// One agent-memory row actually written during the run; a dedup
+// no-op emits nothing. memory_id reconciles re-deliveries. End-user safe:
+// a scope token and a canned sentence, never the memory's content.
+export const MEMORY_UPDATED_EVENT_NAME =
+  AssistantStreamMarkerName.memory_updated;

package/src/contract/identity.ts

@@ -0,0 +1,12 @@
+// The token handshake and the session self-check. The shapes are generated
+// from serving-openapi.json; this file keeps the package's public names
+// stable over the generated ones.
+
+export type {
+  CurrentVisitorResponse as WhoamiResponse,
+  EndUserIdentity,
+  MintVisitorTokenRequest,
+  MintVisitorTokenResponse,
+  PublishableKeyMode,
+  VisitorTier,
+} from "../generated/models/index.js";

package/src/contract/subscriptions.ts

@@ -0,0 +1,11 @@
+// The subscription-connect surfaces. The shapes are generated
+// from serving-openapi.json; this file keeps the package's public names
+// stable over the generated ones.
+
+export type {
+  CreateDeviceAuthorizationResponse as SubscriptionDeviceAuthorization,
+  PollDeviceAuthorizationResponse as SubscriptionDeviceAuthorizationPoll,
+  ServingSubscriptionStatus as SubscriptionStatus,
+  SubscriptionCredentialState,
+  SubscriptionProvider,
+} from "../generated/models/index.js";

package/src/contract/telemetry.ts

@@ -0,0 +1,105 @@
+// The package's product-telemetry seam: safety-critical human
+// controls must never fail silently, so the approval submit path narrates
+// itself as events the host forwards through onTelemetry (never an SDK here).
+
+import { AGUIError } from "@ag-ui/core";
+
+/** Why an attempted approval submit produced no request. */
+export type ApprovalSubmitDropReason =
+  // No active conversation to answer into — should be impossible while a card
+  // renders; reported as an error too.
+  | "no_active_thread"
+  // The live inbox holds no card for this interrupt (a stale render).
+  | "card_missing"
+  // A benign double-click: the first submit is already in flight.
+  | "already_submitting"
+  // The rendered card lagged the live one, which already settled.
+  | "not_actionable_answered"
+  | "not_actionable_stale"
+  // No turn could be resolved to answer into, even after a refresh.
+  | "no_turn_id";
+
+/** ApprovalCardStatus["kind"] (core/approval-inbox.ts) restated: the contract
+ *  layer never imports core; the store's `card.status.kind` pass pins drift. */
+type ApprovalCardStatusKind =
+  "actionable" | "submitting" | "answered" | "stale";
+
+export interface ApprovalSubmitTelemetryEvent {
+  name:
+    | "approval_submit_attempted"
+    | "approval_submit_sent"
+    | "approval_submit_dropped";
+  properties: {
+    interrupt_id: string;
+    thread_id: string | null;
+    approved: boolean;
+    trusted: boolean;
+    /** The rendered card's status kind at handler entry. */
+    card_status: ApprovalCardStatusKind;
+    parked: boolean;
+    drop_reason?: ApprovalSubmitDropReason;
+  };
+}
+
+/** How a stream fetch failed: where in the request's life the wire died,
+ *  since each class has a different owner (network, edge, origin, client). */
+export type StreamFailureClass =
+  // The fetch rejected before any response arrived (DNS, CORS, offline).
+  | "network_rejected"
+  // A response arrived non-2xx; `status` carries it.
+  | "http_error"
+  // A 2xx was accepted but its body offered no readable stream.
+  | "no_body"
+  // The SSE body died mid-read after events had flowed.
+  | "mid_stream"
+  // The event pipeline refused what arrived (protocol/validation).
+  | "parse_or_validation"
+  // Our own abort; the recorder filters these — the class exists for totality.
+  | "client_abort";
+
+/** One stream failure, narrated for the host's analytics. Cursor fields
+ *  locate it on the recorded log; NEVER message text, tool args or prompts. */
+export interface StreamFailedTelemetryEvent {
+  name: "assistant_stream_failed";
+  properties: {
+    failure_class: StreamFailureClass;
+    /** The HTTP status when a response arrived; null before one. */
+    status: number | null;
+    thread_id: string | null;
+    /** The resume snapshot's cursor a reconnect would replay past. */
+    resume_cursor: string | null;
+    /** The last SSE `id:` the dying connection committed. */
+    last_committed_sse_id: string | null;
+  };
+}
+
+export type AssistantTelemetryEvent =
+  ApprovalSubmitTelemetryEvent | StreamFailedTelemetryEvent;
+
+/** Classify a stream failure off the transport's shapes: runHttpRequest
+ *  stamps `.status` on a non-2xx, a missing body is its fixed sentence,
+ *  protocol refusals are AGUIError, schema rejections are raw ZodErrors. A
+ *  network death is a bare TypeError at BOTH ends of the request's life, so
+ *  the caller says whether the body delivered any bytes (keepalives count):
+ *  with bytes the wire died mid-stream; without, no response ever flowed. */
+export function streamFailureClassOf(
+  error: Error,
+  context: { sawBodyBytes: boolean },
+): StreamFailureClass {
+  if (error.name === "AbortError" || /\baborted?\b/i.test(error.message)) {
+    return "client_abort";
+  }
+  if (typeof (error as { status?: unknown }).status === "number") {
+    return "http_error";
+  }
+  if (error instanceof AGUIError || error.name === "ZodError") {
+    return "parse_or_validation";
+  }
+  if (error.message.includes("Failed to getReader")) {
+    return "no_body";
+  }
+  if (error instanceof TypeError) {
+    return context.sawBodyBytes ? "mid_stream" : "network_rejected";
+  }
+  return "mid_stream";
+}

package/src/contract/threads.ts

@@ -0,0 +1,38 @@
+// The conversation surfaces: send, list, detail, approval. The shapes are
+// generated from serving-openapi.json; this file keeps the package's
+// public names stable over the generated ones. The serving contract
+// stays normative for semantics (additive-only policy, tier rules).
+
+export type {
+  CreateServingAttachmentUploadResponse as AttachmentUploadIntent,
+  HighlightResult,
+  NavigateResult,
+  PrefillFormResult,
+  ReadPageResult,
+  ResolveServingTurnApprovalRequest as ResolveTurnApprovalRequest,
+  ResolveServingTurnApprovalResponse as ResolveTurnApprovalResponse,
+  ResolveServingTurnToolResultsRequest as ResolveTurnToolResultsRequest,
+  ResolveServingTurnToolResultsResponse as ResolveTurnToolResultsResponse,
+  SendServingAssistantMessageRequest as SendAssistantMessageRequest,
+  SendServingAssistantMessageResponse as SendAssistantMessageResponse,
+  ServingApprovalDelivery as ApprovalDelivery,
+  ServingAssistantThreadDetailResponse as AssistantThreadDetailResponse,
+  ServingAssistantThreadResponse as ServingAssistantThread,
+  ServingAssistantTurnResponse as ServingAssistantTurn,
+  ServingAttachmentResponse as ServingAttachment,
+  ServingTurnApprovalDecision as TurnApprovalDecision,
+  ServingTurnAttachmentResponse as TurnAttachment,
+  StopServingTurnResponse as StopTurnResponse,
+  ThreadModelPickResponse as ThreadModelPick,
+  AssistantTurnStatus as TurnStatus,
+} from "../generated/models/index.js";
+
+// Mirrors the send surface's message length bound, so the limit is felt
+// while typing rather than as a 422 after submitting. A runtime value the
+// schema carries only as a maxLength annotation — tests/contract-parity
+// pins it to serving-openapi.json.
+export const ASSISTANT_MESSAGE_MAX_CHARS = 4000;
+
+// Mirrors the send surface's attachment_ids bound the same way — the
+// composer refuses an eleventh chip instead of surfacing a 422.
+export const ASSISTANT_MAX_ATTACHMENTS = 10;

package/src/core/activity-title.ts

@@ -0,0 +1,15 @@
+// Compact visible activity copy for a dispatch label: the first
+// MAX_TITLE_CHARS characters of the whitespace-collapsed label, with an
+// ellipsis when anything was cut. No sentence detection — a prefix is all
+// a one-line row needs, and callers keep the complete label in the title
+// attribute.
+
+const MAX_TITLE_CHARS = 64;
+
+export function activityTitleOf(label: string): string {
+  const compact = label.trim().replace(/\s+/g, " ");
+  if (compact.length <= MAX_TITLE_CHARS) {
+    return compact;
+  }
+  return `${compact.slice(0, MAX_TITLE_CHARS - 1).trimEnd()}…`;
+}

package/src/core/activity.ts

@@ -0,0 +1,134 @@
+import type { ServingAssistantTurn, TurnStatus } from "../contract/threads.js";
+import type { ApprovalCardModel } from "./approval-inbox.js";
+import type { PendingDecisionGap } from "./pending-decision-gap.js";
+
+// The read-only activity feed: enough for a small surface (a companion,
+// a badge, a doorbell) to render presence — is something happening, does
+// a human need to act, how did the last thing end — without pulling in
+// the transcript. Consumed through useAssistantActivity() in React and
+// store.activity.get()/.subscribe() anywhere else.
+
+export interface AssistantActivityResult {
+  // The identity a doorbell needs: two consecutive identical failures
+  // still differ by the turn that produced them.
+  turnId: string;
+  status: TurnStatus;
+  failureSentence: string | null;
+}
+
+export interface AssistantActivitySnapshot {
+  busy: boolean;
+  newestTurnStatus: TurnStatus | null;
+  // The identity a per-event dismissal needs while the turn is still
+  // live: the same turn's awaiting_input never re-bubbles once handled,
+  // and lastResult only names turns that already settled.
+  newestTurnId: string | null;
+  // Cards a human can still act on (actionable or mid-submit) — the
+  // companion's most important number: a parked turn waiting on an
+  // approval is exactly when presence matters most.
+  pendingApprovalCount: number;
+  // The published pending-decision gap: the server names
+  // interrupts this client could build nothing for. Rides the feed so
+  // every carrier of "does a human need to act" — the sr-only announcer
+  // included — reads the same fact the visible alert does; without it
+  // the announcer said "working" over an alert that said "waiting".
+  // Reference-stable while its signature holds.
+  pendingDecisionGap: PendingDecisionGap | null;
+  lastResult: AssistantActivityResult | null;
+}
+
+export const IDLE_ACTIVITY: AssistantActivitySnapshot = {
+  busy: false,
+  newestTurnStatus: null,
+  newestTurnId: null,
+  pendingApprovalCount: 0,
+  pendingDecisionGap: null,
+  lastResult: null,
+};
+
+export function activitySnapshotOf(args: {
+  busy: boolean;
+  newestTurn: ServingAssistantTurn | null;
+  approvalCards: readonly ApprovalCardModel[];
+  pendingDecisionGap: PendingDecisionGap | null;
+  lastResult: AssistantActivityResult | null;
+}): AssistantActivitySnapshot {
+  return {
+    busy: args.busy,
+    newestTurnStatus: args.newestTurn?.status ?? null,
+    newestTurnId: args.newestTurn?.id ?? null,
+    pendingApprovalCount: args.approvalCards.filter(_cardAwaitsTheHuman).length,
+    pendingDecisionGap: args.pendingDecisionGap,
+    lastResult: args.lastResult,
+  };
+}
+
+/** A settled turn becomes the feed's last result; a live one (queued,
+ *  working, awaiting_input, parked) leaves the previous result standing.
+ *  Machine turns (kind non-null, the delivery push) report here too,
+ *  DELIBERATELY: this feed's contract is "how did the last thing end",
+ *  not "did your message fail" — the conversation-level failure banner
+ *  (failureSentenceOf) is the surface that hides them. */
+export function settledResultOf(
+  turn: ServingAssistantTurn,
+): AssistantActivityResult | null {
+  if (!isTerminalTurnStatus(turn.status)) {
+    return null;
+  }
+  return {
+    turnId: turn.id,
+    status: turn.status,
+    failureSentence: turn.status === "failed" ? (turn.error ?? null) : null,
+  };
+}
+
+export function sameActivitySnapshot(
+  a: AssistantActivitySnapshot,
+  b: AssistantActivitySnapshot,
+): boolean {
+  return (
+    a.busy === b.busy &&
+    a.newestTurnStatus === b.newestTurnStatus &&
+    a.newestTurnId === b.newestTurnId &&
+    a.pendingApprovalCount === b.pendingApprovalCount &&
+    // Reference identity is sound: the store keeps the published gap
+    // reference-stable while its signature holds.
+    a.pendingDecisionGap === b.pendingDecisionGap &&
+    _sameResult(a.lastResult, b.lastResult)
+  );
+}
+
+function _sameResult(
+  a: AssistantActivityResult | null,
+  b: AssistantActivityResult | null,
+): boolean {
+  if (a === null || b === null) {
+    return a === b;
+  }
+  return (
+    a.turnId === b.turnId &&
+    a.status === b.status &&
+    a.failureSentence === b.failureSentence
+  );
+}
+
+function _cardAwaitsTheHuman(card: ApprovalCardModel): boolean {
+  return card.status.kind === "actionable" || card.status.kind === "submitting";
+}
+
+/** Terminal turn statuses — the run reached an outcome and will not
+ *  produce further work. The completed-episode fold (core/run-folds.ts)
+ *  keys on this rather than on "running" (queued/working) so a
+ *  HITL pause (awaiting_input, parked) never unifies a turn mid-flight
+ *  and then pops its prose back out of the fold on resume. The one
+ *  settled-turn predicate in the package: the approval inbox's terminal
+ *  reconcile and the execution inbox's ledger's-word close both read it,
+ *  so the four words are spelled once against the generated union. */
+export function isTerminalTurnStatus(status: TurnStatus): boolean {
+  return (
+    status === "succeeded" ||
+    status === "failed" ||
+    status === "superseded" ||
+    status === "stopped"
+  );
+}

package/src/core/agent-identity.ts

@@ -0,0 +1,22 @@
+// TeaFlask agent identity tokens (contract law 10). The DOM hooks
+// [data-tf-agent-identity] / [data-tf-subagent-identity] carry these as
+// their VALUES — a valueless hook is not an identity (TVC-090/091 read
+// the tokens, not the attributes' presence).
+//
+// Ownership note: this module mints the identity tokens alone; the
+// marks and their visible treatment are the renderer's. Every mark must
+// derive its token from this module — a second token spelling would
+// break TVC-091's cross-surface stability law.
+
+/** The primary assistant's identity token — one agent, one constant. */
+export const PRIMARY_AGENT_IDENTITY_TOKEN = "teaflask";
+
+/**
+ * A subagent's identity token: the child SESSION is the coworker's
+ * identity (a resume chain deliberately shares it — several asks
+ * of ONE coworker wear one mark), and the prefix makes a collision with
+ * the primary token structurally impossible.
+ */
+export function subagentIdentityTokenOf(childSessionId: string): string {
+  return `subagent:${childSessionId}`;
+}