@mlpal/yodex-ui 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @mlpal/yodex-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React components and a session hook for yodex frontends, over the `yodex serve` wire protocol
+(`@mlpal/harness-protocol`). One engine, many frontends: the workspace UI, the VS Code panel and
+the serve web page all render the same events with these.
+
+```tsx
+import { useYodexSession, Transcript, Composer, RunStatus, PermissionPrompt, QuestionForm, SessionList } from "@mlpal/yodex-ui";
+import "@mlpal/yodex-ui/styles.css";   // utilities, mapped onto your tokens
+import "@mlpal/yodex-ui/theme.css";    // the default tokens; skip if your app defines them
+
+function Chat({ url, token }: { url: string; token?: string }) {
+  const s = useYodexSession({ url, token, run: { mode: "cruise" } });
+  return (
+    <div className="flex h-full flex-col">
+      <Transcript
+        items={s.state.items}
+        footer={
+          <>
+            {s.state.pendingPermissions.map((p) => <PermissionPrompt key={p.id} request={p} onAllow={s.allow} onDeny={s.deny} />)}
+            {s.state.pendingQuestion && <QuestionForm request={s.state.pendingQuestion} onSubmit={s.answer} onDecline={(id) => s.answer(id, { declined: true, answers: [] })} />}
+            <RunStatus running={s.state.running} startedAt={s.state.runStartedAt} activity={s.state.activity} lastResult={s.state.lastResult} usageTotal={s.state.usageTotal} connection={s.state.connection} onStop={s.stop} onApprove={s.approve} />
+          </>
+        }
+      />
+      <Composer onSubmit={(text, attachments) => s.run(text, attachments)} running={s.state.running} onStop={s.stop} />
+    </div>
+  );
+}
+```
+
+- `useYodexSession` owns one socket (reconnect with jittered backoff, request-id correlation) and
+  reduces the stream into `SessionState`: transcript rows, plan, pending permission and question
+  prompts, run status, usage, session and model lists.
+- The reducer and client are framework-free (`YodexClient`, `reduce`, `applyEvent`) for hosts that
+  are not React.
+- Styling: Tailwind utilities compiled against the Obsidian Intelligence token names
+  (`--background`, `--primary`, `--muted`, `--success`, `--warning`, `--info`, …). Every component
+  works at 390 px width with 44 px touch targets.
+- `state.capabilities` mirrors `ready.capabilities` ("questions", "approval", "attachments",
+  "sessions_v2", …): the hook refuses attachments the server cannot take, `QuestionForm` and the
+  approval controls only ever show when the server asks, and a `yodex/1` server still works.

package/dist/client/client.d.ts

@@ -0,0 +1,119 @@
+import type { ClientMessage, ContentBlock, ServerMessage } from "@mlpal/harness-protocol";
+import type { AskOutcome, ConnectionState, IncomingMessage } from "./types";
+/** The subset of the WebSocket API the client uses, so tests can inject a fake. */
+export interface SocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(): void;
+    onopen: ((ev: unknown) => void) | null;
+    onclose: ((ev: unknown) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+}
+export type SocketFactory = (url: string) => SocketLike;
+export interface RunOptions {
+    sessionId?: string;
+    model?: string;
+    mode?: string;
+    /** yodex/2: the HOP for this run (must be the server's own unless it claims "hop_per_run"),
+     *  the working directory under the workspace root, and attachments ("attachments"). */
+    hop?: string;
+    cwd?: string;
+    blocks?: ContentBlock[];
+}
+/** Outgoing messages: the protocol's ClientMessage (yodex/2, additive over yodex/1). */
+export type OutgoingMessage = ClientMessage;
+export interface YodexClientOptions {
+    /** ws:// or wss:// URL of `yodex serve`'s /ws endpoint. */
+    url: string;
+    /** Appended as ?token= when the proxy does not inject Authorization on the upgrade. */
+    token?: string;
+    onMessage: (m: IncomingMessage) => void;
+    onState?: (s: ConnectionState) => void;
+    socketFactory?: SocketFactory;
+    /** Reconnect backoff bounds, ms. */
+    backoffMs?: {
+        min: number;
+        max: number;
+    };
+    requestTimeoutMs?: number;
+    /** Injected for deterministic tests. */
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (h: unknown) => void;
+    random?: () => number;
+}
+/**
+ * A yodex serve client: one socket per session view, reconnect with jittered exponential
+ * backoff, and request-id correlation for the list_* / load_session round-trips. Everything
+ * streamed (events, permission and question requests, done, error) goes to `onMessage`;
+ * the reducer in ./reducer turns it into view state.
+ */
+export declare class YodexClient {
+    private socket;
+    private closedByUser;
+    private attempt;
+    private reconnectHandle;
+    private readonly pending;
+    private readonly opts;
+    private seq;
+    state: ConnectionState;
+    constructor(options: YodexClientOptions);
+    get url(): string;
+    connect(): void;
+    close(): void;
+    private setState;
+    private open;
+    private scheduleReconnect;
+    private failPending;
+    get connected(): boolean;
+    send(m: OutgoingMessage): void;
+    private requestId;
+    /** Send a request carrying a requestId and resolve with the server's correlated reply. */
+    request<T extends ServerMessage["type"]>(m: OutgoingMessage & {
+        requestId: string;
+    }, _expect: T): Promise<Extract<ServerMessage, {
+        type: T;
+    }>>;
+    /** Start a turn. Returns the requestId the matching `done` will carry. */
+    run(prompt: string, options?: RunOptions): string;
+    interrupt(): void;
+    sendPeer(sessionId: string, text: string): void;
+    respondPermission(id: string, decision: "allow" | "deny", reason?: string): void;
+    respondQuestion(id: string, outcome: AskOutcome): void;
+    respondApproval(sessionId: string, decision: "allow" | "deny", reason?: string): void;
+    listSessions(): Promise<{
+        type: "sessions";
+        requestId?: string;
+        sessions: import("@mlpal/harness-protocol").SessionSummary[];
+    }>;
+    listModels(): Promise<{
+        type: "models";
+        requestId?: string;
+        models: Array<{
+            tag: string;
+            displayName: string;
+        }>;
+    }>;
+    listSkills(): Promise<{
+        type: "skills";
+        requestId?: string;
+        skills: Array<{
+            name: string;
+            description: string;
+        }>;
+    }>;
+    loadSession(sessionId: string): Promise<{
+        type: "session_history";
+        requestId?: string;
+        sessionId: string;
+        messages: import("@mlpal/harness-protocol").SDKMessage[];
+        pendingQuestion?: {
+            id: string;
+            questions: import("@mlpal/harness-protocol").AskQuestion[];
+        };
+        pendingApproval?: import("@mlpal/harness-protocol").PendingApproval;
+        live?: boolean;
+    }>;
+}

package/dist/client/reducer.d.ts

@@ -0,0 +1,16 @@
+import type { EngineEvent, ResultEvent, Usage } from "@mlpal/harness-protocol";
+import type { SessionAction, SessionState } from "./types";
+export declare function initialState(): SessionState;
+/**
+ * Apply one engine event. `live` distinguishes the running stream from a history replay:
+ * a human turn on the live stream was already echoed locally by `local_user`, so it is
+ * skipped there and rendered only from history.
+ */
+export declare function applyEvent(state: SessionState, ev: EngineEvent, live: boolean): SessionState;
+export declare function reduce(state: SessionState, action: SessionAction): SessionState;
+export declare function elapsedLabel(ms: number): string;
+export declare function resultLabel(r: ResultEvent): {
+    label: string;
+    tone: "ok" | "bad" | "warn" | "muted";
+};
+export declare function formatTokens(u: Usage): string;

package/dist/client/types.d.ts

@@ -0,0 +1,137 @@
+import type { AskQuestion, Author, ContentBlock, PendingApproval, ResultEvent, ServerCapability, ServerMessage, SessionSummary, ToolResultBlocks, Usage } from "@mlpal/harness-protocol";
+export type { AskAnswer, AskOption, AskOutcome, AskQuestion, PendingApproval, ServerCapability } from "@mlpal/harness-protocol";
+/** One rendered row of a session's transcript. Built by the reducer from the wire events. */
+export type TranscriptItem = {
+    kind: "user";
+    id: string;
+    text: string;
+    author: Author;
+    ts: string;
+    blocks?: ContentBlock[];
+} | {
+    kind: "assistant";
+    id: string;
+    text: string;
+    ts: string;
+    live: boolean;
+} | {
+    kind: "tool";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    ts: string;
+    result?: ToolOutcome;
+} | {
+    kind: "plan";
+    id: "plan";
+    items: PlanItem[];
+} | {
+    kind: "result";
+    id: string;
+    result: ResultEvent;
+} | {
+    kind: "error";
+    id: string;
+    message: string;
+    ts: string;
+} | {
+    kind: "compact";
+    id: string;
+    replacedMessages: number;
+    ts: string;
+};
+export interface ToolOutcome {
+    content: string;
+    isError: boolean;
+    diff?: string;
+    blocks?: ToolResultBlocks;
+}
+export type PlanStatus = "pending" | "in_progress" | "completed";
+export interface PlanItem {
+    /** The tracker's `#id` once its TaskCreate result names it; the tool_use id before that. */
+    id: string;
+    subject: string;
+    description?: string;
+    status: PlanStatus;
+}
+export interface PendingPermission {
+    id: string;
+    sessionId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+}
+export interface PendingQuestion {
+    id: string;
+    sessionId: string;
+    questions: AskQuestion[];
+}
+export type ConnectionState = "connecting" | "connected" | "reconnecting" | "closed";
+export interface SessionState {
+    connection: ConnectionState;
+    protocol?: string;
+    /** What the server serves beyond yodex/1 (ready.capabilities); empty on a yodex/1 server. */
+    capabilities: ServerCapability[];
+    /** The server's HOP and workspace root, from ready. */
+    hop?: string;
+    rootCwd?: string;
+    /** A run is streaming on this session on another connection (load_session.live). */
+    liveElsewhere?: boolean;
+    /** The last run parked at the safety edge; `approve` resumes it. */
+    pendingApproval?: PendingApproval;
+    sessionId?: string;
+    model?: string;
+    cwd?: string;
+    items: TranscriptItem[];
+    running: boolean;
+    runStartedAt?: number;
+    /** What the agent is doing right now, for the status row: a tool name or "Thinking". */
+    activity?: string;
+    lastResult?: ResultEvent;
+    usageTotal: Usage;
+    pendingPermissions: PendingPermission[];
+    pendingQuestion?: PendingQuestion;
+    sessions: SessionSummary[];
+    models: Array<{
+        tag: string;
+        displayName: string;
+    }>;
+    skills: Array<{
+        name: string;
+        description: string;
+    }>;
+    /** The last transport or server error, cleared on the next run. */
+    error?: string;
+}
+/** The server stream (yodex/2, additive over yodex/1). Unknown messages are ignored. */
+export type IncomingMessage = ServerMessage;
+export type SessionAction = {
+    type: "connection";
+    state: ConnectionState;
+} | {
+    type: "server";
+    message: IncomingMessage;
+} | {
+    type: "history";
+    sessionId: string;
+    messages: unknown[];
+} | {
+    type: "local_user";
+    text: string;
+    ts: string;
+    blocks?: ContentBlock[];
+} | {
+    type: "run_started";
+    sessionId?: string;
+    at: number;
+} | {
+    type: "permission_answered";
+    id: string;
+} | {
+    type: "question_answered";
+    id: string;
+} | {
+    type: "error";
+    message: string;
+} | {
+    type: "clear";
+};

package/dist/client/useYodexSession.d.ts

@@ -0,0 +1,35 @@
+import { type RunOptions, type SocketFactory, YodexClient } from "./client";
+import type { AskOutcome, SessionState } from "./types";
+export interface UseYodexSessionOptions {
+    url: string;
+    token?: string;
+    /** Load this session's history on connect and run turns against it. */
+    sessionId?: string;
+    /** Default run options (model, mode, hop, cwd) applied to every turn. */
+    run?: RunOptions;
+    autoConnect?: boolean;
+    socketFactory?: SocketFactory;
+}
+export interface Attachment {
+    name: string;
+    mediaType: string;
+    /** base64 payload, no data: prefix. */
+    data: string;
+}
+export interface YodexSession {
+    state: SessionState;
+    client: YodexClient;
+    /** Send a turn. Attachments ride as image blocks once the server speaks yodex/2. */
+    run: (text: string, attachments?: Attachment[], options?: RunOptions) => void;
+    stop: () => void;
+    allow: (permissionId: string) => void;
+    deny: (permissionId: string, reason?: string) => void;
+    answer: (questionId: string, outcome: AskOutcome) => void;
+    approve: (decision: "allow" | "deny", reason?: string) => void;
+    loadSession: (sessionId: string) => Promise<void>;
+    refreshSessions: () => Promise<void>;
+    refreshModels: () => Promise<void>;
+    newSession: () => void;
+}
+/** One session view over one socket: connect, replay, stream, answer. */
+export declare function useYodexSession(options: UseYodexSessionOptions): YodexSession;

package/dist/components/AssistantMessage.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Assistant prose as sanitised markdown: GFM tables and task lists, raw HTML skipped, links
+ * opened in a new tab. `live` marks a still-streaming turn.
+ */
+export declare function AssistantMessage({ text, live, className }: {
+    text: string;
+    live?: boolean;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/components/Composer.d.ts

@@ -0,0 +1,37 @@
+export interface ComposerAttachment {
+    name: string;
+    mediaType: string;
+    /** base64 payload, no data: prefix. */
+    data: string;
+    /** object URL for the thumbnail; revoked when removed. */
+    previewUrl?: string;
+}
+export interface HopOption {
+    value: string;
+    label: string;
+    description?: string;
+}
+export interface ComposerProps {
+    onSubmit: (text: string, attachments: ComposerAttachment[]) => void;
+    /** While a run is live the send button becomes Stop. */
+    running?: boolean;
+    onStop?: () => void;
+    disabled?: boolean;
+    /** Shown as a placeholder reason while disabled, e.g. "Workspace is waking up". */
+    disabledReason?: string;
+    placeholder?: string;
+    hopOptions?: HopOption[];
+    hop?: string;
+    onHopChange?: (hop: string) => void;
+    /** A slot beside the HOP picker (model picker, mode pill). */
+    leading?: React.ReactNode;
+    maxAttachmentBytes?: number;
+    className?: string;
+    autoFocus?: boolean;
+}
+/**
+ * The input: a growing textarea, Enter sends and Shift+Enter breaks a line, images paste or
+ * drop in as attachments, a HOP picker slot, Stop while running, and an outside-controlled
+ * disabled state for a sleeping workspace.
+ */
+export declare function Composer({ onSubmit, running, onStop, disabled, disabledReason, placeholder, hopOptions, hop, onHopChange, leading, maxAttachmentBytes, className, autoFocus }: ComposerProps): import("react").JSX.Element;

package/dist/components/DiffView.d.ts

@@ -0,0 +1,9 @@
+export declare function diffCounts(diff: string): {
+    added: number;
+    removed: number;
+};
+/** A unified diff, line by line. Render-only: the engine computed it, the model never sees it. */
+export declare function DiffView({ diff, className }: {
+    diff: string;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/components/PermissionPrompt.d.ts

@@ -0,0 +1,9 @@
+import type { PendingPermission } from "../client/types";
+export declare function permissionSummary(p: PendingPermission): string;
+/** The engine asks before a tool runs. Allow / Deny, with `a` / `d` as keys while focused. */
+export declare function PermissionPrompt({ request, onAllow, onDeny, className }: {
+    request: PendingPermission;
+    onAllow: (id: string) => void;
+    onDeny: (id: string, reason?: string) => void;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/components/PlanChecklist.d.ts

@@ -0,0 +1,6 @@
+import type { PlanItem } from "../client/types";
+/** The agent's task list (TaskCreate / TaskUpdate), re-rendered in place as it changes. */
+export declare function PlanChecklist({ items, className }: {
+    items: PlanItem[];
+    className?: string;
+}): import("react").JSX.Element | null;

package/dist/components/QuestionForm.d.ts

@@ -0,0 +1,19 @@
+import type { AskOutcome, AskQuestion, PendingQuestion } from "../client/types";
+/** What the person has picked or typed so far, per question index. */
+export interface QuestionDraft {
+    selected: string[][];
+    notes: string[];
+}
+export declare function emptyDraft(questions: AskQuestion[]): QuestionDraft;
+/** The ask.ts outcome: labels and free text per question; a closed form is `declined`. */
+export declare function buildOutcome(questions: AskQuestion[], draft: QuestionDraft, declined?: boolean): AskOutcome;
+/**
+ * AskUserQuestion as a form: one tab per question, single or multi select with optional
+ * previews, free text, Submit or close-to-decline. The outcome shape mirrors harness ask.ts.
+ */
+export declare function QuestionForm({ request, onSubmit, onDecline, className }: {
+    request: PendingQuestion;
+    onSubmit: (id: string, outcome: AskOutcome) => void;
+    onDecline: (id: string) => void;
+    className?: string;
+}): import("react").JSX.Element | null;

package/dist/components/RunStatus.d.ts

@@ -0,0 +1,17 @@
+import type { ResultEvent, Usage } from "@mlpal/harness-protocol";
+import type { ConnectionState } from "../client/types";
+export interface RunStatusProps {
+    running: boolean;
+    startedAt?: number;
+    activity?: string;
+    lastResult?: ResultEvent;
+    usageTotal?: Usage;
+    connection?: ConnectionState;
+    onStop?: () => void;
+    onApprove?: (decision: "allow" | "deny") => void;
+    className?: string;
+    /** Injected clock for deterministic rendering. */
+    now?: () => number;
+}
+/** One row: what the agent is doing with elapsed time while running; the result line after. */
+export declare function RunStatus({ running, startedAt, activity, lastResult, usageTotal, connection, onStop, onApprove, className, now }: RunStatusProps): import("react").JSX.Element | null;

package/dist/components/SessionList.d.ts

@@ -0,0 +1,15 @@
+import type { SessionSummary } from "@mlpal/harness-protocol";
+/** A SessionSummary; the yodex/2 fields (hop, relCwd, projectName, …) are present when the
+ *  server claims "sessions_v2". */
+export type SessionRow = SessionSummary;
+export declare function groupSessions(rows: SessionRow[]): Array<{
+    project: string;
+    rows: SessionRow[];
+}>;
+export declare function SessionList({ sessions, selectedId, onSelect, onNew, className }: {
+    sessions: SessionRow[];
+    selectedId?: string;
+    onSelect: (sessionId: string) => void;
+    onNew?: () => void;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/components/ToolCall.d.ts

@@ -0,0 +1,13 @@
+import type { TranscriptItem } from "../client/types";
+type ToolItem = Extract<TranscriptItem, {
+    kind: "tool";
+}>;
+/** The one argument worth showing in the header: a command, a path, a pattern, a prompt. */
+export declare function toolSummary(name: string, input: Record<string, unknown>): string;
+/** One tool call with its result, collapsed to a single row by default. */
+export declare function ToolCall({ item, defaultOpen, onOpenFile }: {
+    item: ToolItem;
+    defaultOpen?: boolean;
+    onOpenFile?: (path: string) => void;
+}): import("react").JSX.Element;
+export {};

package/dist/components/Transcript.d.ts

@@ -0,0 +1,12 @@
+import type { TranscriptItem } from "../client/types";
+export interface TranscriptProps {
+    items: TranscriptItem[];
+    /** Keep the view pinned to the bottom while new rows arrive, unless the reader scrolled up. */
+    autoScroll?: boolean;
+    onOpenFile?: (path: string) => void;
+    /** Rendered after the last row: pending prompts, the status line. */
+    footer?: React.ReactNode;
+    emptyState?: React.ReactNode;
+    className?: string;
+}
+export declare function Transcript({ items, autoScroll, onOpenFile, footer, emptyState, className }: TranscriptProps): import("react").JSX.Element;

package/dist/components/cn.d.ts

@@ -0,0 +1,2 @@
+import { type ClassValue } from "clsx";
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export * from "./client/types";
+export { YodexClient, type YodexClientOptions, type RunOptions, type SocketLike, type SocketFactory, type OutgoingMessage } from "./client/client";
+export { reduce, applyEvent, initialState, elapsedLabel, resultLabel, formatTokens } from "./client/reducer";
+export { useYodexSession, type UseYodexSessionOptions, type YodexSession, type Attachment } from "./client/useYodexSession";
+export { Transcript, type TranscriptProps } from "./components/Transcript";
+export { AssistantMessage } from "./components/AssistantMessage";
+export { ToolCall, toolSummary } from "./components/ToolCall";
+export { DiffView, diffCounts } from "./components/DiffView";
+export { PermissionPrompt, permissionSummary } from "./components/PermissionPrompt";
+export { QuestionForm, buildOutcome, type QuestionDraft } from "./components/QuestionForm";
+export { PlanChecklist } from "./components/PlanChecklist";
+export { RunStatus } from "./components/RunStatus";
+export { SessionList, groupSessions, type SessionRow } from "./components/SessionList";
+export { Composer, type ComposerProps, type ComposerAttachment, type HopOption } from "./components/Composer";
+export { cn } from "./components/cn";