@teaflask/assistant 0.3.0 → 0.6.0

package/src/contract/events.ts

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

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

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

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

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

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

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

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