@seanmars/tospec 0.23.0 → 0.26.0-beta

package/dist/core/dashboard-hub.d.ts

@@ -0,0 +1,258 @@
+/**
+ * In-memory state of the dashboard hub: one entry per project, keyed by its
+ * root, holding the last snapshot any of its sessions pushed, and per live
+ * session what it is doing (its status, a short activity log, the question it
+ * waits on). Nothing is persisted and nothing is read from disk — a hub
+ * restart starts empty, and every live session re-registers on its next poll.
+ *
+ * The mod cannot listen on a port, so the hub never calls it. Requests the
+ * snapshot does not answer, and every write, wait in a per-project queue
+ * until one of that project's sessions long-polls for them. The page drives a
+ * session in one way only: it answers the question that session asked.
+ */
+import { type DashboardRequest, type DashboardResponse } from './dashboard-routes.js';
+export type HubCommand = {
+    id: string;
+    kind: 'query';
+    request: DashboardRequest;
+} | {
+    id: string;
+    kind: 'refresh';
+};
+/** `working` and `idle` are what the mod reports; `waiting` is an open ask. */
+export type SessionStatus = 'working' | 'waiting' | 'idle';
+export type ActivityKind = 'prompt' | 'reply' | 'tool' | 'ask' | 'answer' | 'permission';
+/** One line of a session's activity log. */
+export interface ActivityEvent {
+    /** Order within the session, from 1: a browser that holds up to n wants what follows n. */
+    seq: number;
+    /** ISO time the hub received it. */
+    at: string;
+    kind: ActivityKind;
+    text?: string;
+    tool?: string;
+    target?: string;
+    /** A tool that succeeded, or a permission that was granted. */
+    ok?: boolean;
+}
+export interface AskOption {
+    label: string;
+    description?: string;
+}
+export interface AskQuestion {
+    question: string;
+    header?: string;
+    multiSelect: boolean;
+    options: AskOption[];
+}
+/** What a waiting session waits on: an AskUserQuestion, or a tool's permission. */
+export type PendingAsk = {
+    id: string;
+    kind: 'question';
+    questions: AskQuestion[];
+} | {
+    id: string;
+    kind: 'permission';
+    tool: string;
+    target: string;
+};
+export type AskAnswer = {
+    kind: 'question';
+    answers: Record<string, string>;
+} | {
+    kind: 'permission';
+    allow: boolean;
+};
+/** What a mod's wait on an ask resolves to. */
+export type AskWaitResult = {
+    answer: AskAnswer;
+} | {
+    pending: true;
+} | {
+    closed: 'gone';
+};
+export type HubEvent = {
+    type: 'projects';
+} | {
+    type: 'change';
+    project: string;
+} | {
+    type: 'activity';
+    project: string;
+    session: SessionSummary;
+    events: ActivityEvent[];
+};
+/** One live Claude Code session of a project. */
+export interface SessionSummary {
+    /** The Claude Code session id. */
+    id: string;
+    /** ISO time it registered (or came back after expiring). */
+    connectedAt: string;
+    /** ISO time it last pushed or polled. */
+    lastSeenAt: string;
+    status: SessionStatus;
+    /** ISO time the status last changed. */
+    statusSince: string;
+    /** What it is doing while working, e.g. `Edit src/cli/index.ts`. */
+    action?: string;
+    /** Its oldest open ask, while waiting. */
+    ask?: PendingAsk;
+}
+export interface ProjectSummary {
+    key: string;
+    root: string;
+    name: string;
+    /** ISO time of the last snapshot. */
+    updatedAt: string;
+    /** The session whose push is the snapshot being served. */
+    updatedBy: string;
+    /** True while at least one session is live. */
+    online: boolean;
+    /** Live sessions, oldest connection first. */
+    sessions: SessionSummary[];
+}
+export interface HubOptions {
+    now?: () => number;
+    /** A session that has not polled for this long no longer counts as live. */
+    sessionTtlMs?: number;
+    /** How long a poll, or a wait on an ask, is held open before it answers empty. */
+    pollHoldMs?: number;
+    /** How long a relayed request waits for a session's reply. */
+    relayTimeoutMs?: number;
+    /**
+     * Whether the dashboard may act rather than watch: answer a session's
+     * questions (an AskUserQuestion, a permission) or write a task. The server
+     * sets it from the bind address: only a loopback-bound hub is interactive.
+     */
+    interactive?: boolean;
+}
+/** A rejected push or poll; `status` is the HTTP answer the server gives. */
+export declare class HubRequestError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * The project's identity: two sessions in the same root share one entry. Case
+ * folded on Windows, whose paths are case-insensitive.
+ */
+export declare function projectKey(root: string): string;
+/** Per-session log length: enough for the last few turns, bounded per session. */
+export declare const ACTIVITY_LOG_LIMIT = 200;
+/** One event's text; the mod cuts to this too, so the bound holds whoever sent it. */
+export declare const ACTIVITY_TEXT_LIMIT = 500;
+export declare class DashboardHub {
+    private readonly projects;
+    private readonly pending;
+    private readonly asks;
+    private readonly listeners;
+    private readonly now;
+    private readonly sessionTtlMs;
+    private readonly pollHoldMs;
+    private readonly relayTimeoutMs;
+    readonly interactive: boolean;
+    constructor(options?: HubOptions);
+    subscribe(listener: (event: HubEvent) => void): () => void;
+    private emit;
+    /**
+     * Registers or refreshes a project from a pushed snapshot. The newest push
+     * wins whichever session sent it: every session of a project reads the same
+     * files, so "newest" is the only order that matters.
+     */
+    acceptSnapshot(session: unknown, snapshot: unknown): string;
+    /**
+     * Marks a session seen. One that expired and comes back counts as a new
+     * connection, so its `connectedAt` says when this stretch began, and its
+     * log starts over with it.
+     */
+    private touch;
+    /** Broadcasts `projects` when the live session set changed; true if it did. */
+    private refreshPresence;
+    /**
+     * Hands queued commands to a session, waiting up to `pollHoldMs` for one.
+     * Null means the hub does not know this project (it restarted): the session
+     * should push a snapshot first.
+     */
+    poll(key: unknown, session: unknown, signal?: AbortSignal): Promise<HubCommand[] | null>;
+    /** Settles a relayed request. False when it already timed out or never existed. */
+    reply(id: unknown, response: unknown): boolean;
+    /**
+     * A session ended or unregistered. The project and its snapshot stay, as last
+     * known.
+     *
+     * Its held poll is released first: a waiting poll counts as live, so leaving
+     * it held kept the project online for up to `pollHoldMs` after an explicit
+     * unregister. Released before the delete, since a delivery refreshes the
+     * session's last-seen time.
+     */
+    leave(key: unknown, session: unknown): void;
+    listProjects(): ProjectSummary[];
+    /**
+     * Serves a read from the snapshot, relaying a miss to a live session. Client
+     * errors are cached like successes (a 404 stays a 404 until the next push);
+     * a 5xx or an offline answer is not, so the next try asks again.
+     */
+    read(key: string, requestPath: string): Promise<DashboardResponse>;
+    /**
+     * Relays a write. A success empties the cache, so reads that follow ask the
+     * session for the files as they are now rather than for the pre-write
+     * snapshot; the session pushes a fresh one on its own shortly after.
+     */
+    write(key: string, request: DashboardRequest): Promise<DashboardResponse>;
+    /** Asks a live session for a fresh snapshot. False when none is live. */
+    requestRefresh(key: string): boolean;
+    /**
+     * Takes a mod's report: its status (`working` from a turn's start to its
+     * end), what it is doing now, and log events. False for a project the hub
+     * does not know, so the mod registers again.
+     */
+    reportActivity(key: unknown, session: unknown, report: unknown): boolean;
+    /** A session's summary and log, for a browser opening its panel. */
+    sessionLog(key: string, session: string): {
+        session: SessionSummary;
+        events: ActivityEvent[];
+    } | null;
+    private appendEvent;
+    private emitActivity;
+    /**
+     * Opens an ask for a session, which then reads as waiting. The terminal asks
+     * the same question at the same time, and the first answer stands: `hold`
+     * says whether the dashboard may answer at all (it is interactive), so the
+     * mod knows whether to wait for it.
+     */
+    openAsk(key: unknown, session: unknown, ask: unknown): {
+        id: string;
+        hold: boolean;
+    };
+    /**
+     * The mod's wait for the dashboard's answer, held up to `pollHoldMs`: a hook
+     * waiting on a `$` call costs it none of its time budget, where one waiting
+     * on its own timer would.
+     */
+    waitAsk(id: unknown, signal?: AbortSignal): Promise<AskWaitResult>;
+    /** The dashboard's answer to an open ask. */
+    answerAsk(key: string, session: string, id: unknown, answer: unknown): DashboardResponse;
+    /**
+     * Withdraws an ask the dashboard can no longer answer: the person answered
+     * it in the terminal, so the page drops its controls instead of offering a
+     * second answer. An ask the dashboard already answered stays as it is.
+     */
+    closeAsk(id: unknown, text?: string): void;
+    private logAskEnd;
+    private dropAsksOf;
+    /**
+     * Forgets sessions past their ttl (a session that crashed never says it
+     * left) and broadcasts the change; the server calls it on a timer.
+     */
+    sweep(): void;
+    /** Releases every held poll, wait and pending relay; the hub is unusable after. */
+    close(): void;
+    /** Sessions seen within the ttl, or holding a poll; oldest connection first. */
+    private liveSessions;
+    private summarize;
+    /** The session's oldest ask the dashboard can still answer. */
+    private openAskOf;
+    private isOnline;
+    private enqueue;
+    private relay;
+}
+//# sourceMappingURL=dashboard-hub.d.ts.map

package/dist/core/dashboard-hub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-hub.d.ts","sourceRoot":"","sources":["../../src/core/dashboard-hub.ts"],"names":[],"mappings":"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"}