@tangle-network/agent-app 0.45.54 → 0.45.56

package/dist/web-react/mission-activity.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Mission + delegation observability surfaces — different nouns, one trace
+ * tree:
+ *
+ *  - {@link MissionActivityLane}: the collapsed sub-rows under a mission step
+ *    (what the step's agent is actually doing), expanding to a compact web
+ *    waterfall rendered from the `/trace` converters.
+ *  - {@link AgentActivityPanel}: the standalone cross-context surface — every
+ *    delegation a workspace ran, regardless of which mission (if any) spawned
+ *    it — behind a `fetchActivity` data port with cursor + refresh.
+ *  - {@link FlowWaterfall}: the web counterpart of `/trace`'s ASCII
+ *    `renderWaterfall` (which stays CLI) — proportional bars over a FlowTrace.
+ *
+ * Same styling contract as the rest of `/web-react`: Tailwind classes against
+ * the shared design tokens, inline SVG glyphs, no icon library. The pure
+ * layout/merge/format helpers are exported for tests and reuse.
+ */
+import { type ReactNode } from 'react';
+import type { StepAgentActivity } from '../missions/agent-activity';
+import type { FlowTrace } from '../trace/index';
+export type ActivityTone = 'live' | 'ok' | 'error' | 'neutral';
+/** Map a delegation status (free-form string on the wire) to a render tone. */
+export declare function activityTone(status: string): ActivityTone;
+/** "$0.4000" under a cent shows 4 decimals; null when unknown/zero. */
+export declare function formatActivityCost(costUsd?: number): string | null;
+/** "8s" / "2m 05s" / "1h 12m"; null when unknown. */
+export declare function formatActivityDuration(durationMs?: number): string | null;
+/** A delegation record on the cross-context surface; `missionRef` links a
+ *  promoted delegation back to the mission/step that spawned it. */
+export interface AgentActivityRecord extends StepAgentActivity {
+    missionRef?: {
+        missionId: string;
+        stepId?: string;
+        label?: string;
+    };
+}
+export interface AgentActivityPage {
+    items: AgentActivityRecord[];
+    /** Opaque continuation token; absent ⇒ no further pages. */
+    nextCursor?: string;
+}
+/**
+ * Fold a fetched page into the held rows: dedupe by `taskId` with the
+ * incoming row winning (a refresh re-fetches the head page, so newer
+ * snapshots of in-flight runs replace stale ones), newest `startedAt` first.
+ */
+export declare function mergeActivityPages(existing: AgentActivityRecord[], incoming: AgentActivityRecord[]): AgentActivityRecord[];
+export interface WaterfallRow {
+    name: string;
+    kind: 'pipeline' | 'model' | 'tool';
+    /** Bar geometry as percentages of the trace's total span. */
+    offsetPct: number;
+    widthPct: number;
+    durationLabel: string;
+    approx: boolean;
+    /** False only when the span's meta carries an explicit failure. */
+    ok: boolean;
+}
+/** Project a FlowTrace into proportional bar geometry for {@link FlowWaterfall}. */
+export declare function waterfallLayout(trace: FlowTrace): WaterfallRow[];
+export interface FlowWaterfallProps {
+    trace: FlowTrace;
+}
+/** Compact proportional waterfall over a FlowTrace — span name, bar, duration
+ *  per row; total + cost in the footer. */
+export declare function FlowWaterfall({ trace }: FlowWaterfallProps): import("react").JSX.Element | null;
+export interface MissionActivityLaneProps {
+    /** The step's delegated-run snapshot (`MissionStepState.agentActivity`). */
+    activity: StepAgentActivity[];
+    /** Epoch ms origin for the expanded waterfall — usually the step start. */
+    startedAt?: number;
+    /** Wall clock for extending in-flight runs on the waterfall. */
+    nowMs?: number;
+}
+/**
+ * Collapsed sub-rows under a mission step — one row per delegated run —
+ * expanding to the step's waterfall. Renders nothing for an empty lane.
+ *
+ * A sub-row appears because a delegated run STARTED or FINISHED, which is the
+ * one kind of list change worth choreographing: it arrives, and the group
+ * arrives as a sequence. Keying on `taskId` is what keeps the rest still — the
+ * snapshot re-renders every poll, and a row whose status merely advanced holds
+ * the DOM node it already had.
+ */
+export declare function MissionActivityLane({ activity, startedAt, nowMs }: MissionActivityLaneProps): import("react").JSX.Element | null;
+export interface AgentActivityPanelProps {
+    /** Data port — page through the product's delegation records. Called with
+     *  no cursor on mount/refresh, with `nextCursor` for older pages. */
+    fetchActivity: (cursor?: string) => Promise<AgentActivityPage>;
+    /** Render the mission link for a promoted delegation (chip, anchor, router
+     *  Link — the product's routing, not ours). */
+    renderMissionRef?: (ref: NonNullable<AgentActivityRecord['missionRef']>, record: AgentActivityRecord) => ReactNode;
+    title?: string;
+    emptyLabel?: string;
+}
+export declare function AgentActivityPanel({ fetchActivity, renderMissionRef, title, emptyLabel }: AgentActivityPanelProps): import("react").JSX.Element;

package/dist/web-react/motion.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The React half of the motion primitives that ship in `src/theme/tokens.css`.
+ *
+ * The stylesheet owns every keyframe, duration and easing, and that is the
+ * whole point: a component that writes its own timing is invisible to the
+ * reduced-motion collapse at `:root`, so "it writes its own timing" and "it
+ * ignores reduced motion" are the same defect. The one thing CSS cannot supply
+ * is WHERE in a group a row sits, which is per-element data — hence these two
+ * helpers and nothing else.
+ */
+import { type CSSProperties } from 'react';
+/**
+ * Position in a staggered `.agent-arrive` group. `--stagger-index` is a custom
+ * property and `CSSProperties` has no index signature for one, so the cast is
+ * the only way to hand React a value tokens.css already defines (it declares
+ * the property with a `0` default and caps the delay at 8 steps internally, so
+ * a long list never opens with a multi-second cascade).
+ *
+ * Use it directly only where the group's order is FIXED once rendered — an
+ * ask's option rows, a turn's append-only tool segments. A list that can
+ * re-sort wants {@link useArrivalStyle}.
+ *
+ * `base` merges a caller's own style, because a row that carries layout of its
+ * own would otherwise have to spread the two itself at every call site, and the
+ * spread order matters: the index must win, or a stale `--stagger-index` on the
+ * base silently overrides the position being asked for.
+ */
+export declare function staggerStyle(index: number, base?: CSSProperties): CSSProperties;
+/**
+ * The same style, frozen at the row's first render.
+ *
+ * A settled `.agent-arrive` is finished, not inert: `animation-delay` is part
+ * of its timing, so handing an already-arrived row a LARGER delay pushes it
+ * back into the animation's before-phase and it plays again. Any list that
+ * re-sorts does exactly that — `mergeActivityPages` sorts newest-first, so one
+ * newer run landing on a refresh shifts every row's index by one and the whole
+ * panel would re-animate because nothing about it changed. Freezing the index
+ * at mount makes the arrival a property of ARRIVING rather than of the row's
+ * current position, which is the difference between choreography and flicker.
+ *
+ * Rules of hooks: a row that needs this is a component, not a `.map` body.
+ */
+export declare function useArrivalStyle(index: number): CSSProperties;

package/dist/web-react/provenance-model.d.ts

@@ -0,0 +1,195 @@
+/**
+ * The pure half of the provenance affordance: what kind of claim a value is,
+ * what a reader should DO about it, and what has to be SAID when its origin
+ * cannot be shown.
+ *
+ * Zero React, zero DOM — a loader or a worker can decide a value's standing
+ * before it reaches a screen, and `./provenance`'s `ProvenanceValue` renders
+ * exactly what these functions decide.
+ *
+ * The distinction the module exists to hold: a person typing a number, a
+ * document carrying it, a formula producing it, and a model claiming it are
+ * four different kinds of evidence. Rendered as one grey caption they are
+ * indistinguishable, which is how an unverified model assertion reads to a
+ * reviewer as a transcribed fact.
+ *
+ * Every domain word is a caller parameter: no field names, no document kinds,
+ * and no confidence policy beyond a default the product overrides.
+ */
+/**
+ * How a value came to exist. Four kinds, never interchangeable:
+ *
+ * - `extracted` — read out of a document or message the product can open.
+ * - `entered` — a person typed or confirmed it.
+ * - `computed` — produced from other values, each carrying its own provenance.
+ * - `asserted` — the agent stated it, with nothing outside the model behind it.
+ */
+export type ProvenanceBasis = 'extracted' | 'entered' | 'computed' | 'asserted';
+/** Every basis, in the order a legend should list them. */
+export declare const PROVENANCE_BASES: readonly ProvenanceBasis[];
+/** The words one basis is rendered and announced with. */
+export interface ProvenanceBasisMeta {
+    /** Marker text next to the value — short, and never only a colour. */
+    label: string;
+    /** One plain sentence naming what kind of claim this is. */
+    meaning: string;
+    /** What a reader can hold the value against, or `null` when nothing outside
+     *  the model can. `null` is what makes an `asserted` value uncertifiable at
+     *  any confidence. */
+    checkableAgainst: string | null;
+}
+/** Words for one basis. */
+export declare function provenanceBasisMeta(basis: ProvenanceBasis): ProvenanceBasisMeta;
+/** Whether a source could be resolved. `ready` is the default for a source that
+ *  says nothing. */
+export type ProvenanceSourceStatus = 'ready' | 'loading' | 'unavailable';
+/** One thing a value came from. A `label` is mandatory because an unnamed
+ *  source is the same as no source. */
+export interface ProvenanceSource {
+    /** What the source IS, in the reader's words: "Form W-2 (Acme Corp)",
+     *  "Dana Whitfield", "Engagement letter". */
+    label: string;
+    /** The text in the source that carries the value. */
+    quote?: string;
+    /** Position inside the source — a page, a line, a span, a timestamp. The
+     *  caller's words; nothing here parses it. */
+    locator?: string;
+    /** Click-through target. Absent → the source is named but not openable. */
+    href?: string;
+    /** Defaults to `ready`. */
+    status?: ProvenanceSourceStatus;
+    /** Why an `unavailable` source cannot be opened, in one sentence. */
+    unavailableReason?: string;
+}
+/**
+ * What the reader should DO about a value — the only form confidence takes on
+ * screen. "89% confidence" names no next move; these three do.
+ *
+ * - `settled` — nothing to do.
+ * - `check` — open the source and confirm before relying on it.
+ * - `confirm` — a person has to confirm the value before it is used.
+ */
+export type ProvenanceStanding = 'settled' | 'check' | 'confirm';
+/** The words one standing is rendered and announced with. */
+export interface ProvenanceStandingMeta {
+    /** Short state label. */
+    label: string;
+    /** The next move, as a sentence a person can follow. */
+    action: string;
+}
+/** Words for one standing. */
+export declare function provenanceStandingMeta(standing: ProvenanceStanding): ProvenanceStandingMeta;
+/** The weaker of two standings — `confirm` beats `check` beats `settled`. */
+export declare function weakerProvenanceStanding(a: ProvenanceStanding, b: ProvenanceStanding): ProvenanceStanding;
+/**
+ * Where a product draws its confidence lines. These are a POLICY, not a truth:
+ * a number a model reports about itself means different things per surface, so
+ * the thresholds are a parameter and the number itself never reaches the screen.
+ */
+export interface ProvenanceConfidencePolicy {
+    /** At or above this, a value is `settled`. */
+    settledAtOrAbove: number;
+    /** At or above this (and below `settledAtOrAbove`), a value is `check`.
+     *  Below it, `confirm`. */
+    checkAtOrAbove: number;
+}
+/** The starting policy. Products with a different tolerance pass their own. */
+export declare const DEFAULT_PROVENANCE_CONFIDENCE_POLICY: ProvenanceConfidencePolicy;
+/** A value, where it came from, and — when it was computed — the provenanced
+ *  values it came from. The `inputs` field is what makes the shape compose:
+ *  a computed value's provenance IS its inputs. */
+export interface ProvenanceRecord {
+    /** The value as the reader should see it, already formatted. An empty string
+     *  is a missing value and renders as one, never as blank space. */
+    display: string;
+    /** What the value IS ("Wages", "Filing deadline"). Optional at the top level,
+     *  where the surface around it usually says; rendered for every composed
+     *  input, where nothing else names them. */
+    label?: string;
+    basis: ProvenanceBasis;
+    /** Where it came from. An `extracted` value without one is a gap, not a
+     *  detail. */
+    sources?: readonly ProvenanceSource[];
+    /** The provenanced values a `computed` value was produced from. */
+    inputs?: readonly ProvenanceRecord[];
+    /** How the inputs combine, in the caller's words ("wages + interest"). */
+    derivation?: string;
+    /** 0–1. Never rendered as a number — it selects a standing. */
+    confidence?: number;
+    /** Overrides the standing confidence and basis would produce — a reviewer
+     *  approved it, a gate failed. It can only make a value WEAKER: the
+     *  structural floors below still apply, so a product cannot mark a value
+     *  settled that has no origin on file. */
+    standing?: ProvenanceStanding;
+}
+/** The standing a bare confidence maps to under a policy. */
+export declare function standingFromConfidence(confidence: number, policy?: ProvenanceConfidencePolicy): ProvenanceStanding;
+/** Something missing that the reader has to be TOLD about, because the value
+ *  renders either way and a bare number reads as a fact. */
+export type ProvenanceGapKind = 'no-source' | 'no-inputs' | 'unavailable-source';
+/** One stated gap. `message` is rendered verbatim. */
+export interface ProvenanceGap {
+    kind: ProvenanceGapKind;
+    message: string;
+    /** The source that could not be resolved (`unavailable-source` only). */
+    source?: ProvenanceSource;
+}
+/** The sentence for a source that is not `ready`, or `null` when it is. One
+ *  source of this copy, so the row and the gap list never disagree. */
+export declare function describeProvenanceSourceStatus(source: ProvenanceSource): string | null;
+/**
+ * What this record cannot show, at its own level. Inputs are not walked: every
+ * composed input renders its own gaps next to its own value, where a reader can
+ * act on them.
+ */
+export declare function provenanceGaps(record: ProvenanceRecord): ProvenanceGap[];
+/** The sources still resolving — rendered as their own state, never as an
+ *  absence. A load in flight is not a missing source. */
+export declare function loadingProvenanceSources(record: ProvenanceRecord): ProvenanceSource[];
+/**
+ * This record's own standing, ignoring its inputs.
+ *
+ * The order is: start from the explicit standing, else from confidence, else
+ * from the basis — then apply every structural floor, taking the WEAKEST. The
+ * floors are what a caller cannot talk its way out of:
+ *
+ * - an `asserted` value never reaches `settled` (a model's own confidence
+ *   cannot certify the model's claim — there is nothing to check it against),
+ * - a `no-source` / `no-inputs` gap forces `confirm` (a value dressed as
+ *   evidence with no evidence behind it is worse than an open guess),
+ * - an unopenable source forces `check` (the value may be right; the reader
+ *   just cannot confirm it).
+ */
+export declare function resolveProvenanceStanding(record: ProvenanceRecord, policy?: ProvenanceConfidencePolicy): ProvenanceStanding;
+/**
+ * The standing a reader should see: this record's own, weakened by every value
+ * it was computed from, however deep.
+ *
+ * A total is only as trustworthy as the weakest number in it. Rendering the
+ * parent's own standing instead is how an exact sum of one document figure and
+ * one model guess presents as traced.
+ *
+ * Cycle-safe: a record reachable from itself is counted once.
+ */
+export declare function rollUpProvenanceStanding(record: ProvenanceRecord, policy?: ProvenanceConfidencePolicy, seen?: Set<ProvenanceRecord>): ProvenanceStanding;
+/**
+ * One plain sentence naming where the value came from — the panel's first line
+ * and part of what a screen reader announces. It states the absence when there
+ * is one, so no code path produces silence.
+ */
+export declare function describeProvenance(record: ProvenanceRecord): string;
+/**
+ * The move THIS value's reader can actually make.
+ *
+ * `provenanceStandingMeta().action` is the generic sentence for a standing;
+ * this is the one that accounts for what is on file. "Open the source and
+ * confirm it" is a dead instruction on a value that has no source — an action
+ * a reader cannot perform is the same defect as no action at all.
+ */
+export declare function provenanceNextMove(record: ProvenanceRecord, standing: ProvenanceStanding, policy?: ProvenanceConfidencePolicy): string;
+/**
+ * The accessible name of the disclosure control: the value, how it came to
+ * exist, and — unless there is nothing to do — the next move. This is the
+ * whole affordance for someone who never sees the colour.
+ */
+export declare function provenanceTriggerLabel(record: ProvenanceRecord, standing: ProvenanceStanding): string;

package/dist/web-react/provenance.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `ProvenanceValue` — one value rendered so its origin is discoverable without
+ * navigating away, and openable when there is something to open.
+ *
+ * This is the affordance three verticals each rebuilt: tax renders a source
+ * quote under an expanded return line, legal renders authorities under a
+ * finding, the record grid renders a per-cell marker. Same product promise,
+ * three vocabularies, three sets of gaps.
+ *
+ * What the primitive holds that a hand-rolled caption does not:
+ *
+ * 1. The four bases render differently — a person's entry and a model's
+ *    assertion are never the same pixels. Each carries its own glyph AND its
+ *    own words, so the distinction survives greyscale and a screen reader.
+ * 2. It COMPOSES. A computed value's provenance is its inputs, and each input
+ *    is itself a `ProvenanceValue` with its own disclosure.
+ * 3. Confidence renders as the next move ("Check the source"), never as a
+ *    percentage a reader cannot act on.
+ * 4. The disclosure is a real button — keyboard reachable, `aria-expanded`,
+ *    Escape closes and returns focus, a click outside dismisses, and opening
+ *    one trail closes the one the reader left. Nothing here discloses on hover,
+ *    and no fact lives only in a `title` attribute.
+ * 5. A source that is loading, unopenable, or absent SAYS so. There is no path
+ *    through this component that renders a bare number.
+ *
+ * Layout: an inline-block block-level element, so put it in a table cell, a
+ * list item, or a card — not inside a `<p>`. Sandbox-ui-free, like the rest of
+ * `/web-react`; the model in `./provenance-model` is React-free.
+ */
+import { type ProvenanceBasis, type ProvenanceConfidencePolicy, type ProvenanceRecord, type ProvenanceSource } from './provenance-model';
+export * from './provenance-model';
+/** Properties for one provenanced value and its disclosure. */
+export interface ProvenanceValueProps {
+    /** The value and where it came from. */
+    record: ProvenanceRecord;
+    /**
+     * Open one source in the product's own way (a document pane at the right
+     * page, a drawer, a route). Takes precedence over `href` when both are
+     * present, because a product that routes wants its router — a source with
+     * neither is named but not openable, which is a legitimate state and is
+     * rendered as such.
+     */
+    onOpenSource?: (source: ProvenanceSource, record: ProvenanceRecord) => void;
+    /** Retry resolving an `unavailable` source. Absent → the failure is stated
+     *  without a retry control, never swallowed. */
+    onRetrySource?: (source: ProvenanceSource, record: ProvenanceRecord) => void;
+    /** Where this product draws its confidence lines. */
+    confidencePolicy?: ProvenanceConfidencePolicy;
+    /**
+     * How many levels of composed inputs stay expandable. Past it an input still
+     * renders its value, its basis and its origin sentence — it just stops
+     * carrying its own disclosure, so a deep tree cannot run away and a record
+     * that reaches itself cannot recurse forever. Default 2.
+     */
+    maxDepth?: number;
+    /** Open the disclosure on first render — for a review surface where the
+     *  trail is the point. Several of these coexist: only a reader opening a
+     *  trail closes another one. */
+    defaultOpen?: boolean;
+    /** What an empty `display` renders as. A blank cell is the defect this
+     *  component exists to remove. */
+    missingValueLabel?: string;
+    className?: string;
+}
+/**
+ * A value, its origin marker, and the disclosure that shows where it came
+ * from. The marker states the basis in words and, whenever there is something
+ * to do about the value, the next move — so the standing is legible at rest
+ * and does not depend on anyone opening the panel.
+ */
+export declare function ProvenanceValue({ record, onOpenSource, onRetrySource, confidencePolicy, maxDepth, defaultOpen, missingValueLabel, className, }: ProvenanceValueProps): import("react").JSX.Element;
+/** Properties for the basis legend. */
+export interface ProvenanceLegendProps {
+    /** Only the bases present on screen. Passing all four when only two appear
+     *  teaches distinctions the reader cannot use. */
+    bases: readonly ProvenanceBasis[];
+    className?: string;
+}
+/** The marker key for a surface that renders several bases at once — a review
+ *  pane, a grid, a return. Each row is the same glyph, tone and words the
+ *  markers use, plus what the basis MEANS. */
+export declare function ProvenanceLegend({ bases, className }: ProvenanceLegendProps): import("react").JSX.Element | null;

package/dist/web-react/provider-logo.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Provider brand marks — real logo path data (simple-icons / SVG Logos, both
+ * CC0) inlined so the picker shows actual provider identity instead of
+ * colored-initial monograms. Providers without a usable mark fall back to a
+ * tinted monogram chip. Aliases (z-ai/zai, moonshot/moonshotai, deepseek_ai)
+ * normalize to one entry.
+ */
+import type { ReactNode } from 'react';
+export interface ProviderLogoProps {
+    provider?: string;
+    size?: number;
+}
+/** Real brand mark when we have one; tinted monogram otherwise. */
+export declare function ProviderLogo({ provider, size }: ProviderLogoProps): ReactNode;