@signalcore/ui 0.1.0 → 1.0.0-beta.1

package/dist/stream/builder.d.ts

@@ -1,176 +0,0 @@
-/**
- * The conversation with the builder as a list of blocks, built by folding events.
- *
- * Pure: the same events give the same transcript, whether they arrive live from the stream or
- * replayed from history. Only the block that changes gets a new object, so memoized components
- * re-render just that block while tokens stream in.
- *
- * The events are the builder's vocabulary (`signalcore_builder.events` on the server), the one
- * `build.sessions.say` streams and `build.sessions.history` replays.
- */
-import type { RequestCardData } from "../request/types.js";
-import type { SurfaceData } from "../surface/types.js";
-/** A request put to the owner, as `RequestCard` draws it. */
-export type Card = RequestCardData;
-export interface Change {
-    id: string;
-    change: "added" | "changed" | "removed";
-    what: "automation" | "skill";
-    title: string;
-}
-/** The change a turn closed (`docs/product-identity.md` section 4): what the owner activates. */
-export interface ChangeRef {
-    id: string;
-    description: string;
-    state: string;
-}
-export type BuildEvent = {
-    type: "owner";
-    text: string;
-} | {
-    type: "text";
-    text: string;
-} | {
-    type: "tool";
-    id: string;
-    name: string;
-    input: Record<string, unknown>;
-} | {
-    type: "tool_done";
-    id: string;
-    ok: boolean;
-    summary: string;
-} | ({
-    type: "card";
-} & Card)
-/** Something the builder showed the owner (a surface of the catalog). */
- | {
-    type: "surface";
-    surface: SurfaceData;
-} | {
-    type: "published";
-    version: number;
-    summary: string;
-} | {
-    type: "configured";
-}
-/** Where to look on the canvas: "automation:<id>", "automations" or "knowledge". */
- | {
-    type: "canvas";
-    focus: string;
-} | {
-    type: "changes";
-    items: Change[];
-    learned: string[];
-    change?: ChangeRef | null;
-}
-/**
- * Where a browser the agent drives is now, for the `Browser` surface the chat already shows
- * for that session. Live only: history keeps the surface, not each step.
- */
- | {
-    type: "browser";
-    session_id: string;
-    status: "open" | "closed";
-    step?: number;
-    caption?: string;
-    url?: string;
-    title?: string;
-    summary?: string;
-} | {
-    type: "error";
-    message: string;
-} | {
-    type: "done";
-    ok: boolean;
-    turns: number;
-    cost_usd: number | null;
-    session_id: string | null;
-    errors: string[];
-};
-/** Our own server's events: checking the tag is enough, anything else is ignored. */
-export declare function isBuildEvent(value: unknown): value is BuildEvent;
-export type StepStatus = "running" | "ok" | "error" | "stopped";
-export type Block = {
-    kind: "owner";
-    id: string;
-    text: string;
-} | {
-    kind: "text";
-    id: string;
-    text: string;
-    open: boolean;
-} | {
-    kind: "step";
-    id: string;
-    name: string;
-    input: Record<string, unknown>;
-    status: StepStatus;
-    summary?: string;
-} | {
-    kind: "card";
-    id: string;
-    card: Card;
-} | {
-    kind: "surface";
-    id: string;
-    surface: SurfaceData;
-} | {
-    kind: "published";
-    id: string;
-    version: number;
-    summary: string;
-} | {
-    kind: "changes";
-    id: string;
-    items: Change[];
-    learned: string[];
-    change: ChangeRef | null;
-} | {
-    kind: "error";
-    id: string;
-    message: string;
-};
-export interface TurnResult {
-    ok: boolean;
-    costUsd: number | null;
-    durationMs: number;
-}
-export interface Transcript {
-    blocks: Block[];
-    /** A turn is streaming. */
-    live: boolean;
-    turnStartedAt: number | null;
-    lastTurn: TurnResult | null;
-    /** What the builder is working on, for the canvas to show; `seq` changes on every event. */
-    focus: {
-        target: string;
-        seq: number;
-    } | null;
-}
-export type TranscriptAction = 
-/** Replace everything with a conversation read back, plus cards still waiting for an answer. */
-{
-    type: "load";
-    events: BuildEvent[];
-    pending: Card[];
-}
-/** The owner sent a message: the turn begins. */
- | {
-    type: "start";
-    text: string;
-    at: number;
-} | {
-    type: "event";
-    event: BuildEvent;
-    at: number;
-}
-/** The turn ended without its `done` (stopped, or the connection was lost). */
- | {
-    type: "stop";
-    at: number;
-};
-export declare const emptyTranscript: Transcript;
-export declare function reduceTranscript(state: Transcript, action: TranscriptAction): Transcript;
-/** What the builder is doing right now, for the status line. */
-export declare function activity(state: Transcript): Block | undefined;

package/dist/stream/builder.js

@@ -1,202 +0,0 @@
-/**
- * The conversation with the builder as a list of blocks, built by folding events.
- *
- * Pure: the same events give the same transcript, whether they arrive live from the stream or
- * replayed from history. Only the block that changes gets a new object, so memoized components
- * re-render just that block while tokens stream in.
- *
- * The events are the builder's vocabulary (`signalcore_builder.events` on the server), the one
- * `build.sessions.say` streams and `build.sessions.history` replays.
- */
-const TYPES = new Set([
-    "owner",
-    "text",
-    "tool",
-    "tool_done",
-    "card",
-    "surface",
-    "published",
-    "configured",
-    "canvas",
-    "changes",
-    "browser",
-    "error",
-    "done",
-]);
-/** Our own server's events: checking the tag is enough, anything else is ignored. */
-export function isBuildEvent(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        "type" in value &&
-        typeof value.type === "string" &&
-        TYPES.has(value.type));
-}
-export const emptyTranscript = {
-    blocks: [],
-    live: false,
-    turnStartedAt: null,
-    lastTurn: null,
-    focus: null,
-};
-export function reduceTranscript(state, action) {
-    switch (action.type) {
-        case "load": {
-            let next = emptyTranscript;
-            for (const event of action.events)
-                next = apply(next, event, null);
-            const shown = new Set(next.blocks.map((b) => (b.kind === "card" ? b.card.request_id : "")));
-            for (const card of action.pending) {
-                if (!shown.has(card.request_id))
-                    next = push(next, { kind: "card", id: "", card });
-            }
-            return { ...next, focus: null, blocks: close(next.blocks), live: false };
-        }
-        case "start": {
-            const next = push(state, { kind: "owner", id: "", text: action.text });
-            return { ...next, live: true, turnStartedAt: action.at, lastTurn: null };
-        }
-        case "event":
-            return apply(state, action.event, action.at);
-        case "stop": {
-            const blocks = close(state.blocks).map((b) => b.kind === "step" && b.status === "running" ? { ...b, status: "stopped" } : b);
-            return { ...state, blocks, live: false, turnStartedAt: null };
-        }
-    }
-}
-/** `at` is when the event arrived; null when replaying history, where it is unknown. */
-function apply(state, event, at) {
-    switch (event.type) {
-        case "owner":
-            return push(state, { kind: "owner", id: "", text: event.text });
-        case "text": {
-            const last = state.blocks.at(-1);
-            if (last?.kind === "text" && last.open) {
-                return replaceLast(state, { ...last, text: last.text + event.text });
-            }
-            return push(state, { kind: "text", id: "", text: event.text, open: true });
-        }
-        case "tool":
-            return push(state, {
-                kind: "step",
-                id: event.id,
-                name: event.name,
-                input: event.input,
-                status: "running",
-            });
-        case "tool_done":
-            return {
-                ...state,
-                blocks: state.blocks.map((b) => b.kind === "step" && b.id === event.id
-                    ? { ...b, status: event.ok ? "ok" : "error", summary: event.summary }
-                    : b),
-            };
-        case "card": {
-            const card = {
-                request_id: event.request_id,
-                kind: event.kind,
-                title: event.title,
-                payload: event.payload,
-            };
-            return push(state, { kind: "card", id: "", card });
-        }
-        case "surface":
-            return push(state, { kind: "surface", id: "", surface: event.surface });
-        case "published":
-            return push(state, {
-                kind: "published",
-                id: "",
-                version: event.version,
-                summary: event.summary,
-            });
-        case "error":
-            return push(state, { kind: "error", id: "", message: event.message });
-        case "done": {
-            const started = state.turnStartedAt;
-            const blocks = close(state.blocks);
-            const errors = event.errors.map((message, i) => ({
-                kind: "error",
-                id: `e${blocks.length + i}`,
-                message,
-            }));
-            return {
-                ...state,
-                blocks: [...blocks, ...errors],
-                live: false,
-                turnStartedAt: null,
-                lastTurn: started !== null && at !== null
-                    ? { ok: event.ok, costUsd: event.cost_usd, durationMs: at - started }
-                    : state.lastTurn,
-            };
-        }
-        case "canvas":
-            return { ...state, focus: { target: event.focus, seq: (state.focus?.seq ?? 0) + 1 } };
-        case "changes":
-            return push(state, {
-                kind: "changes",
-                id: "",
-                items: event.items,
-                learned: event.learned,
-                change: event.change ?? null,
-            });
-        case "browser":
-            return showBrowser(state, event);
-        case "configured":
-            return state;
-    }
-}
-// What a browser event can say about the session; each one is written only when it carries it.
-const BROWSER_FIELDS = ["status", "caption", "step", "url", "title", "summary"];
-const isSession = (component, sessionId) => component.component === "Browser" && component.session_id === sessionId;
-/**
- * A browser event says where a session is now. It lands in the `Browser` component the chat
- * already shows for that session (the last surface that holds it), so it adds no block, and a
- * session the chat never showed changes nothing.
- */
-function showBrowser(state, event) {
-    const index = state.blocks.findLastIndex((block) => block.kind === "surface" &&
-        block.surface.components.some((component) => isSession(component, event.session_id)));
-    const block = state.blocks[index];
-    if (block?.kind !== "surface")
-        return state;
-    const carried = {};
-    for (const field of BROWSER_FIELDS) {
-        if (event[field] !== undefined)
-            carried[field] = event[field];
-    }
-    const components = block.surface.components.map((component) => isSession(component, event.session_id) ? { ...component, ...carried } : component);
-    return replaceAt(state, index, { ...block, surface: { ...block.surface, components } });
-}
-/** Append a block, closing the one before it (a reply ends when something else starts). */
-function push(state, block) {
-    const blocks = close(state.blocks);
-    const id = block.id || `${block.kind}-${blocks.length}`;
-    return { ...state, blocks: [...blocks, { ...block, id }] };
-}
-function replaceAt(state, index, block) {
-    return { ...state, blocks: state.blocks.map((b, i) => (i === index ? block : b)) };
-}
-function replaceLast(state, block) {
-    return replaceAt(state, state.blocks.length - 1, block);
-}
-/** Mark the trailing reply as finished. */
-function close(blocks) {
-    const last = blocks.at(-1);
-    if (last?.kind !== "text" || !last.open)
-        return blocks;
-    return [...blocks.slice(0, -1), { ...last, open: false }];
-}
-/** What the builder is doing right now, for the status line. */
-export function activity(state) {
-    if (!state.live)
-        return undefined;
-    for (let i = state.blocks.length - 1; i >= 0; i--) {
-        const block = state.blocks[i];
-        if (block?.kind === "step" && block.status === "running")
-            return block;
-        if (block?.kind === "owner")
-            return undefined;
-        if (block?.kind === "text" && block.open)
-            return block;
-    }
-    return undefined;
-}

package/dist/stream/reduce.d.ts

@@ -1,51 +0,0 @@
-import type { Schemas } from "@signalcore/sdk";
-import type { RequestCardData } from "../request/types.js";
-import type { SurfaceData } from "../surface/types.js";
-/** One event of a run's journal, as the API sends it (the contract's own union). */
-export type RunEvent = Schemas["RunEventPage"]["items"][number];
-/**
- * Where the stream stands: `connecting` before the first answer, `streaming` while events come,
- * `paused` while the run waits for an answer to a request, `done` when the run ended, `failed`
- * when the stream could not be kept (see `error`).
- */
-export type StreamStatus = "connecting" | "streaming" | "paused" | "done" | "failed";
-export interface StreamState {
-    /** The run this state is of: a state of another run is not this one's. */
-    runId: string | undefined;
-    /** Everything the run recorded, in order. */
-    events: RunEvent[];
-    /** What the agent showed (`ui.surface`), in order, the ones that can be drawn. */
-    surfaces: SurfaceData[];
-    /** What the run asked of the owner (`request.created`), as cards to answer. */
-    requests: RequestCardData[];
-    status: StreamStatus;
-    error: Error | undefined;
-    /** The `id` of the last event seen: where to go on from after a drop. */
-    lastEventId: string | undefined;
-}
-export type Step = {
-    type: "begin";
-    runId: string | undefined;
-    lastEventId: string | undefined;
-} | {
-    type: "event";
-    event: RunEvent;
-    id: string | undefined;
-} | {
-    type: "status";
-    status: StreamStatus;
-} | {
-    type: "failed";
-    error: Error;
-} | {
-    type: "payloads";
-    pending: PendingRequest[];
-};
-/** A request as the API lists it, with the payload its card is drawn from. */
-export interface PendingRequest {
-    id: string;
-    agent_id: string;
-    payload: Record<string, unknown>;
-}
-export declare function begin(runId: string | undefined, lastEventId: string | undefined): StreamState;
-export declare function reduce(state: StreamState, step: Step): StreamState;

package/dist/stream/reduce.js

@@ -1,58 +0,0 @@
-import { isAnswerable } from "../request/cards.js";
-import { surfaceOf } from "../surface/check.js";
-export function begin(runId, lastEventId) {
-    return {
-        runId,
-        events: [],
-        surfaces: [],
-        requests: [],
-        status: "connecting",
-        error: undefined,
-        lastEventId,
-    };
-}
-export function reduce(state, step) {
-    switch (step.type) {
-        case "begin":
-            return begin(step.runId, step.lastEventId);
-        case "event":
-            return {
-                ...state,
-                events: [...state.events, step.event],
-                surfaces: withSurface(state.surfaces, step.event),
-                requests: withRequest(state.requests, step.event),
-                lastEventId: step.id ?? state.lastEventId,
-            };
-        case "status":
-            return { ...state, status: step.status };
-        case "failed":
-            return { ...state, status: "failed", error: step.error };
-        case "payloads":
-            return {
-                ...state,
-                requests: state.requests.map((card) => {
-                    const found = step.pending.find((item) => item.id === card.request_id);
-                    return found ? { ...card, agent_id: found.agent_id, payload: found.payload } : card;
-                }),
-            };
-    }
-}
-function withSurface(surfaces, event) {
-    if (event.type !== "ui.surface")
-        return surfaces;
-    const surface = surfaceOf(event.surface);
-    return surface ? [...surfaces, surface] : surfaces;
-}
-function withRequest(requests, event) {
-    if (event.type !== "request.created" || !isAnswerable(event.kind))
-        return requests;
-    if (requests.some((card) => card.request_id === event.request_id))
-        return requests;
-    const card = {
-        request_id: event.request_id,
-        kind: event.kind,
-        title: event.title,
-        payload: {},
-    };
-    return [...requests, card];
-}

package/dist/stream/untilAborted.d.ts

@@ -1,7 +0,0 @@
-/**
- * The items of `source` until `signal` aborts. A generator finishes the read it is in before it
- * obeys `return()`, so a stream waiting on a quiet connection would keep a stopped turn on
- * screen until its next event. This stops listening the moment the signal fires and hangs up on
- * the stream behind, in the background.
- */
-export declare function untilAborted<T>(source: AsyncGenerator<T, void>, signal: AbortSignal): AsyncGenerator<T, void>;

package/dist/stream/untilAborted.js

@@ -1,32 +0,0 @@
-const ABORTED = Symbol("aborted");
-/**
- * The items of `source` until `signal` aborts. A generator finishes the read it is in before it
- * obeys `return()`, so a stream waiting on a quiet connection would keep a stopped turn on
- * screen until its next event. This stops listening the moment the signal fires and hangs up on
- * the stream behind, in the background.
- */
-export async function* untilAborted(source, signal) {
-    const aborted = new Promise((resolve) => {
-        if (signal.aborted)
-            resolve(ABORTED);
-        else {
-            signal.addEventListener("abort", () => {
-                resolve(ABORTED);
-            }, { once: true });
-        }
-    });
-    try {
-        for (;;) {
-            const read = source.next();
-            // If the abort wins, this read is never awaited: its failure must not go unheard of.
-            read.catch(() => undefined);
-            const item = await Promise.race([read, aborted]);
-            if (item === ABORTED || item.done)
-                return;
-            yield item.value;
-        }
-    }
-    finally {
-        source.return().catch(() => undefined);
-    }
-}

package/dist/stream/useRunStream.d.ts

@@ -1,26 +0,0 @@
-import { type StreamState } from "./reduce.js";
-export interface RunStreamOptions {
-    /** The `id` of the last event already seen, to go on from there (after a reload). */
-    lastEventId?: string | undefined;
-    /**
-     * Ask the API what the requests a run raises say, to draw them as cards (default). A host that
-     * never draws them, such as the chat of the people an agent serves, turns it off, and the API
-     * is not asked for what nobody will see.
-     */
-    cards?: boolean | undefined;
-}
-/** What a run has said so far; see `StreamState`. `done` is `status === "done"`. */
-export interface RunStream extends StreamState {
-    done: boolean;
-}
-/**
- * Follows a run live through the provider's client (`runs.stream`), accumulating what it says:
- * every event, the surfaces the agent showed, and the requests it is waiting on, as cards ready
- * for `RequestCard`. When the run pauses on a request the stream is closed; once the request is
- * answered (anywhere: this card, the inbox, another tab) it opens again from the last event
- * seen, and carries on until the run is `done`. A stream that drops is opened again the same way.
- *
- * Needs a client with `runs`; without one it stays `connecting`. Stops when the component goes
- * away or `runId` changes.
- */
-export declare function useRunStream(runId: string | undefined, options?: RunStreamOptions): RunStream;

package/dist/stream/useRunStream.js

@@ -1,137 +0,0 @@
-import { useEffect, useReducer } from "react";
-import { useSignalcore } from "../SignalcoreProvider.js";
-import { begin, reduce } from "./reduce.js";
-/** How often a paused run is asked whether it has gone on. */
-const RESUME_POLL_MS = 2_000;
-/** How long to wait before opening a stream that closed without saying why. */
-const RETRY_MS = 1_000;
-/** How many times in a row that may happen without a single event before giving up. */
-const MAX_SILENT_DROPS = 5;
-/**
- * Follows a run live through the provider's client (`runs.stream`), accumulating what it says:
- * every event, the surfaces the agent showed, and the requests it is waiting on, as cards ready
- * for `RequestCard`. When the run pauses on a request the stream is closed; once the request is
- * answered (anywhere: this card, the inbox, another tab) it opens again from the last event
- * seen, and carries on until the run is `done`. A stream that drops is opened again the same way.
- *
- * Needs a client with `runs`; without one it stays `connecting`. Stops when the component goes
- * away or `runId` changes.
- */
-export function useRunStream(runId, options = {}) {
-    const { client } = useSignalcore();
-    const { lastEventId, cards = true } = options;
-    const [state, dispatch] = useReducer(reduce, undefined, () => begin(runId, lastEventId));
-    useEffect(() => {
-        if (!client?.runs || !runId)
-            return undefined;
-        const stop = new AbortController();
-        const send = (step) => {
-            if (!stop.signal.aborted)
-                dispatch(step);
-        };
-        send({ type: "begin", runId, lastEventId });
-        follow(client, runId, lastEventId, stop.signal, send, cards).catch((reason) => {
-            send({ type: "failed", error: reason instanceof Error ? reason : new Error(String(reason)) });
-        });
-        return () => {
-            stop.abort();
-        };
-    }, [client, runId, lastEventId, cards]);
-    // Until the effect has started over for a new run, the state is still the old run's.
-    const current = state.runId === runId ? state : begin(runId, lastEventId);
-    return { ...current, done: current.status === "done" };
-}
-/**
- * The whole life of the stream: open, read, and open again until the run is over. Stopping it
- * (`signal`) ends it with an abort error, which nobody is told of.
- */
-async function follow(client, runId, startAt, signal, send, cards) {
-    const runs = client.runs;
-    if (!runs)
-        return;
-    let lastId = startAt;
-    let silentDrops = 0;
-    for (;;) {
-        signal.throwIfAborted();
-        send({ type: "status", status: "connecting" });
-        let ending;
-        let heard = false;
-        for await (const frame of runs.stream(runId, lastId === undefined ? {} : { lastEventId: lastId })) {
-            signal.throwIfAborted();
-            if (frame.event === "done" || frame.event === "paused") {
-                ending = frame.event;
-                break;
-            }
-            const event = eventOf(frame);
-            if (!event)
-                continue;
-            if (!heard)
-                send({ type: "status", status: "streaming" });
-            heard = true;
-            lastId = frame.id ?? lastId;
-            send({ type: "event", event, id: frame.id });
-            if (cards && event.type === "request.created")
-                void fillIn(client, send);
-        }
-        if (ending === "done") {
-            send({ type: "status", status: "done" });
-            return;
-        }
-        if (ending === "paused") {
-            send({ type: "status", status: "paused" });
-            await untilResumed(client, runId, signal);
-            continue;
-        }
-        // The stream ended without saying why: the connection dropped. Open it again, a few times.
-        silentDrops = heard ? 0 : silentDrops + 1;
-        if (silentDrops >= MAX_SILENT_DROPS)
-            throw new Error("The stream kept closing before the run ended");
-        await sleep(RETRY_MS, signal);
-    }
-}
-/** The journal event a frame carries; its type is the frame's own when the data omits it. */
-function eventOf(frame) {
-    try {
-        const data = frame.json();
-        if (typeof data !== "object" || data === null || Array.isArray(data))
-            return undefined;
-        return { type: frame.event, ...data };
-    }
-    catch {
-        return undefined;
-    }
-}
-/** A request's card is drawn from its payload, which the event leaves out: ask the API for it. */
-async function fillIn(client, send) {
-    const requests = client.requests;
-    if (!requests?.pending)
-        return;
-    try {
-        const page = await requests.pending();
-        send({ type: "payloads", pending: page.items });
-    }
-    catch {
-        // The card stays as bare as the event made it: its title is still worth showing.
-    }
-}
-/** Waits for a paused run to leave `waiting`: its request was answered, wherever that happened. */
-async function untilResumed(client, runId, signal) {
-    const runs = client.runs;
-    if (!runs)
-        return;
-    for (;;) {
-        await sleep(RESUME_POLL_MS, signal);
-        signal.throwIfAborted();
-        if ((await runs.get(runId)).status !== "waiting")
-            return;
-    }
-}
-function sleep(ms, signal) {
-    return new Promise((resolve) => {
-        const timer = setTimeout(resolve, ms);
-        signal.addEventListener("abort", () => {
-            clearTimeout(timer);
-            resolve();
-        }, { once: true });
-    });
-}