@digitornai/sdk 0.1.0

package/dist/reducer.js

@@ -0,0 +1,181 @@
+const MAX_EVENTS = 500;
+function messageText(m) {
+    if (!m)
+        return "";
+    if (typeof m.content === "string" && m.content)
+        return m.content;
+    if (Array.isArray(m.parts)) {
+        return m.parts.map((p) => p.text ?? p.content ?? "").join("");
+    }
+    return "";
+}
+function ensureStreamingAssistant(messages) {
+    const last = messages[messages.length - 1];
+    if (last && last.role === "assistant" && last.streaming) {
+        return { messages, tail: last };
+    }
+    const fresh = {
+        role: "assistant",
+        content: "",
+        streaming: true,
+        toolCalls: [],
+        ts: Date.now(),
+    };
+    return { messages: [...messages, fresh], tail: fresh };
+}
+function replaceTail(messages, next) {
+    return [...messages.slice(0, -1), next];
+}
+function applyEvent(state, env) {
+    const lastSeq = env.seq > state.lastSeq ? env.seq : state.lastSeq;
+    const events = [...state.events, env].slice(-MAX_EVENTS);
+    const base = { ...state, lastSeq, events };
+    switch (env.type) {
+        case "user_message": {
+            const cid = env.correlation_id;
+            if (cid && state.messages.some((m) => m.correlationId === cid)) {
+                return base;
+            }
+            const msg = {
+                role: "user",
+                content: messageText(env.message),
+                correlationId: cid,
+                ts: Date.now(),
+            };
+            return { ...base, messages: [...state.messages, msg] };
+        }
+        case "turn_started":
+        case "message_started":
+            return { ...base, turnActive: true, status: "streaming", error: null };
+        case "assistant_delta": {
+            const { messages, tail } = ensureStreamingAssistant(state.messages);
+            const next = { ...tail, content: tail.content + messageText(env.message) };
+            return {
+                ...base,
+                status: "streaming",
+                messages: replaceTail(messages, next),
+            };
+        }
+        case "assistant_reasoning_delta": {
+            const { messages, tail } = ensureStreamingAssistant(state.messages);
+            const delta = env.message?.reasoning ?? messageText(env.message);
+            const next = { ...tail, reasoning: (tail.reasoning ?? "") + delta };
+            return {
+                ...base,
+                status: "thinking",
+                messages: replaceTail(messages, next),
+            };
+        }
+        case "assistant_message":
+        case "message_done": {
+            const { messages, tail } = ensureStreamingAssistant(state.messages);
+            const full = messageText(env.message);
+            const next = {
+                ...tail,
+                content: full || tail.content,
+                reasoning: env.message?.reasoning ?? tail.reasoning,
+                streaming: false,
+            };
+            return { ...base, messages: replaceTail(messages, next) };
+        }
+        case "tool_call": {
+            if (!env.tool)
+                return base;
+            const { messages, tail } = ensureStreamingAssistant(state.messages);
+            const call = {
+                callId: env.tool.call_id,
+                name: env.tool.name,
+                args: env.tool.arguments,
+                status: env.tool.status ?? "running",
+            };
+            const next = { ...tail, toolCalls: [...(tail.toolCalls ?? []), call] };
+            return {
+                ...base,
+                status: "tool_use",
+                messages: replaceTail(messages, next),
+            };
+        }
+        case "tool_result": {
+            if (!env.tool)
+                return base;
+            const messages = state.messages.map((m) => {
+                if (m.role !== "assistant" || !m.toolCalls)
+                    return m;
+                return {
+                    ...m,
+                    toolCalls: m.toolCalls.map((c) => c.callId === env.tool.call_id
+                        ? { ...c, status: env.tool.status ?? "done", result: env.tool.text }
+                        : c),
+                };
+            });
+            return { ...base, messages };
+        }
+        case "approval_request": {
+            if (!env.approval)
+                return base;
+            const a = env.approval;
+            if (state.approvals.some((x) => x.id === a.id))
+                return base;
+            return {
+                ...base,
+                approvals: [
+                    ...state.approvals,
+                    { id: a.id, kind: a.kind, payload: a.payload, status: a.status },
+                ],
+            };
+        }
+        case "approval_granted":
+        case "approval_denied": {
+            const id = env.approval?.id;
+            if (!id)
+                return base;
+            return {
+                ...base,
+                approvals: state.approvals.filter((x) => x.id !== id),
+            };
+        }
+        case "turn_ended": {
+            const last = state.messages[state.messages.length - 1];
+            const messages = last && last.role === "assistant" && last.streaming
+                ? replaceTail(state.messages, { ...last, streaming: false })
+                : state.messages;
+            return { ...base, turnActive: false, status: "idle", messages };
+        }
+        case "error":
+            return {
+                ...base,
+                status: "error",
+                turnActive: false,
+                error: env.error?.message ?? "Unknown error",
+            };
+        default:
+            return base;
+    }
+}
+export function reduce(state, action) {
+    switch (action.type) {
+        case "connected":
+            return { ...state, connected: true, error: null };
+        case "disconnected":
+            return { ...state, connected: false };
+        case "local_user":
+            return {
+                ...state,
+                turnActive: true,
+                status: "streaming",
+                messages: [
+                    ...state.messages,
+                    {
+                        role: "user",
+                        content: action.content,
+                        correlationId: action.correlationId,
+                        ts: Date.now(),
+                    },
+                ],
+            };
+        case "event":
+            return applyEvent(state, action.env);
+        default:
+            return state;
+    }
+}

package/dist/reviewMode.d.ts

@@ -0,0 +1,33 @@
+/** A review command the host relays to the app (from the chat, or the app's own
+ *  chrome). `accept`/`reject` act on one proposal by `id`; the `*-all` variants
+ *  act on every pending one. */
+export interface ReviewCommand {
+    /** `*-all`: every pending change. `next`/`prev`: move to and focus the
+     *  neighbouring change (one-by-one review). `accept-current`/`reject-current`:
+     *  resolve the change currently focused/at the cursor. `accept`/`reject`: a
+     *  specific change by `id`. */
+    action: "accept-all" | "reject-all" | "next" | "prev" | "accept-current" | "reject-current" | "accept" | "reject";
+    /** Proposal id for `accept`/`reject`; ignored by the others. */
+    id?: string;
+}
+/** State an app publishes so the host can surface a review affordance ("12
+ *  suggestions — Accept all / Review"). */
+export interface ProposalsState {
+    /** Pending proposals awaiting the person's decision. 0 clears the affordance. */
+    count: number;
+    /** Optional label for the current review context ("12 suggestions",
+     *  "3 changes in this section"). The host may show it verbatim. */
+    label?: string;
+}
+/**
+ * Report the current pending-proposals state to the host. Call it whenever the
+ * count changes (a suggestion lands, one is accepted/rejected). `count: 0`
+ * removes the chat's review affordance. Vanilla — safe from any editor.
+ */
+export declare function reportProposals(state: ProposalsState): void;
+/**
+ * Subscribe to review commands the host relays (Accept all / Reject all / accept
+ * one / reject one). The app applies them in its own engine (e.g. SuperDoc
+ * acceptAll). Returns an unsubscribe function. Vanilla — usable outside React.
+ */
+export declare function onReviewCommand(handler: (cmd: ReviewCommand) => void): () => void;

package/dist/reviewMode.js

@@ -0,0 +1,59 @@
+// The Digitorn "review" primitive — the generic channel for "the assistant
+// PROPOSES changes the person accepts or rejects", reusable by ANY app (a docx
+// editor's tracked changes, a spreadsheet's proposed cells, a slide edit, a
+// code diff). The SDK knows nothing app-specific: an app REPORTS how many
+// proposals are pending, and RECEIVES accept/reject commands the host relays
+// (e.g. from an "Accept all" button in the chat). How proposals are produced
+// and rendered is entirely the app's business.
+//
+// Pairs with Digitorn's native mode system: an app exposes an "Auto" and a
+// "Suggestions" mode (app.yaml), whose per-mode system_prompt tells the agent
+// whether to edit directly or as tracked changes. This channel is only the
+// review surface on top of that.
+//
+// No React import at module scope, so a vanilla (non-React) editor can import
+// `reportProposals` / `onReviewCommand` directly.
+/**
+ * Report the current pending-proposals state to the host. Call it whenever the
+ * count changes (a suggestion lands, one is accepted/rejected). `count: 0`
+ * removes the chat's review affordance. Vanilla — safe from any editor.
+ */
+export function reportProposals(state) {
+    if (typeof window === "undefined")
+        return;
+    const count = Math.max(0, Math.floor(Number(state.count) || 0));
+    try {
+        window.parent?.postMessage({
+            type: "digi:proposals-state",
+            count,
+            label: typeof state.label === "string" ? state.label.slice(0, 80) : undefined,
+        }, "*");
+    }
+    catch {
+        /* cross-origin parent may reject — nothing to fall back to */
+    }
+}
+/**
+ * Subscribe to review commands the host relays (Accept all / Reject all / accept
+ * one / reject one). The app applies them in its own engine (e.g. SuperDoc
+ * acceptAll). Returns an unsubscribe function. Vanilla — usable outside React.
+ */
+export function onReviewCommand(handler) {
+    if (typeof window === "undefined")
+        return () => { };
+    const listener = (ev) => {
+        const d = ev.data;
+        if (!d || typeof d !== "object" || d.type !== "digi:review-command")
+            return;
+        const action = d.action;
+        const valid = [
+            "accept-all", "reject-all", "next", "prev",
+            "accept-current", "reject-current", "accept", "reject",
+        ];
+        if (!valid.includes(action))
+            return;
+        handler({ action, id: typeof d.id === "string" ? d.id : undefined });
+    };
+    window.addEventListener("message", listener);
+    return () => window.removeEventListener("message", listener);
+}

package/dist/shared.d.ts

@@ -0,0 +1,24 @@
+export interface SharedDocOptions {
+    /** Debounce (ms) before writing a local change back to the workdir.
+     *  Default 200. High-frequency editors (Excalidraw, canvases) benefit
+     *  from a slightly higher value. */
+    writeDebounceMs?: number;
+}
+/**
+ * `useSharedDoc` - convenience for the common "one JSON file" case: a workdir
+ * document synced two-way with the agent. It is just sugar over `useWorkspace`
+ * + `useWatch`.
+ *
+ *   - The agent edits the file → `useWatch` fires → we re-read → re-render.
+ *   - `setDoc(next)` writes it back (debounced) so the agent sees user edits.
+ *
+ * Echo from your own writes is suppressed so you never loop. Apps whose state
+ * is NOT a single JSON (a folder, many files, binary…) use `useWatch` +
+ * `useWorkspace` directly instead.
+ *
+ * @example Excalidraw - the agent draws in real time
+ * ```tsx
+ * const [scene, setScene] = useSharedDoc("scene.excalidraw", { elements: [] });
+ * ```
+ */
+export declare function useSharedDoc<T = unknown>(path: string, initial?: T, options?: SharedDocOptions): [T | undefined, (next: T) => void];

package/dist/shared.js

@@ -0,0 +1,55 @@
+import * as React from "react";
+import { useWorkspace, useWatch } from "./workspace.js";
+/**
+ * `useSharedDoc` - convenience for the common "one JSON file" case: a workdir
+ * document synced two-way with the agent. It is just sugar over `useWorkspace`
+ * + `useWatch`.
+ *
+ *   - The agent edits the file → `useWatch` fires → we re-read → re-render.
+ *   - `setDoc(next)` writes it back (debounced) so the agent sees user edits.
+ *
+ * Echo from your own writes is suppressed so you never loop. Apps whose state
+ * is NOT a single JSON (a folder, many files, binary…) use `useWatch` +
+ * `useWorkspace` directly instead.
+ *
+ * @example Excalidraw - the agent draws in real time
+ * ```tsx
+ * const [scene, setScene] = useSharedDoc("scene.excalidraw", { elements: [] });
+ * ```
+ */
+export function useSharedDoc(path, initial, options = {}) {
+    const { readFile, writeFile } = useWorkspace();
+    const [value, setValue] = React.useState(initial);
+    // The exact bytes we last wrote - a change event echoing our own write is
+    // ignored so a write→event→read→setState loop never fires.
+    const lastWritten = React.useRef(null);
+    const read = React.useCallback(async () => {
+        const text = await readFile(path);
+        if (text === undefined)
+            return; // missing / unreadable - keep current
+        if (text === lastWritten.current)
+            return; // our own echo
+        try {
+            setValue(text ? JSON.parse(text) : undefined);
+        }
+        catch {
+            /* invalid JSON mid-write - keep current, next event retries */
+        }
+    }, [readFile, path]);
+    React.useEffect(() => {
+        void read();
+    }, [read]);
+    useWatch(path, () => void read());
+    const timer = React.useRef(null);
+    const setDoc = React.useCallback((next) => {
+        setValue(next);
+        const content = JSON.stringify(next);
+        if (timer.current)
+            clearTimeout(timer.current);
+        timer.current = setTimeout(() => {
+            lastWritten.current = content;
+            void writeFile(path, content);
+        }, options.writeDebounceMs ?? 200);
+    }, [writeFile, path, options.writeDebounceMs]);
+    return [value, setDoc];
+}

package/dist/topbar.d.ts

@@ -0,0 +1,78 @@
+/**
+ * A button (or a small dropdown, via ``items``) the app adds to the host's
+ * top bar - the same bar Digitorn renders its own Code/Preview tabs and the
+ * GitHub/Publish buttons into. Only shown while THIS custom view is the
+ * active tab; switching away removes it automatically.
+ *
+ * Only ``label``/``icon`` cross the postMessage boundary - the host owns
+ * the actual chrome. ``onClick`` stays in your own code and never leaves
+ * the iframe; the host just tells you which id was clicked.
+ */
+/**
+ * Bounded, themed style knobs for one button - not raw CSS. Every value is
+ * an enum the host maps to its own design tokens, so a view can stand its
+ * button out (a prominent "Deploy" CTA, a compact icon-only refresh) while
+ * staying visually native to Digitorn's chrome - and without a "data only"
+ * postMessage payload turning into arbitrary styling/markup control over
+ * the host's own page.
+ */
+export interface TopBarActionStyle {
+    /** Button height/padding/text size. Default `"md"`. */
+    size?: "sm" | "md" | "lg";
+    /** Text weight. Default `"medium"`. */
+    weight?: "normal" | "medium" | "semibold" | "bold";
+    /** Corner rounding. Default `"rounded"`. */
+    shape?: "square" | "rounded" | "pill";
+    /** `"ghost"` (default, blends into the bar), `"outline"` (bordered), or
+     *  `"solid"` (filled - reach for this on the one action that should read
+     *  as the primary CTA, e.g. a "Deploy" button). */
+    variant?: "ghost" | "outline" | "solid";
+    /** `"default"` (neutral) or `"accent"` (Digitorn's brand color). */
+    tone?: "default" | "accent";
+}
+export interface TopBarAction {
+    id: string;
+    label: string;
+    /** A lucide icon name, e.g. "git-branch". Falls back to a generic icon. */
+    icon?: string;
+    onClick?: () => void;
+    /**
+     * Opens this URL in a new tab instead of relaying a click - `onClick` is
+     * ignored when this is set. Popups a host-relayed `onClick` opens with
+     * `window.open` get blocked: the click happens in the host's real DOM,
+     * but `window.open` would run later inside the iframe on a postMessage,
+     * which browsers don't count as the same user gesture. The host opens
+     * `href` itself, synchronously, in the click it actually received.
+     */
+    href?: string;
+    style?: TopBarActionStyle;
+    /** Turns this entry into a small dropdown instead of a plain button. */
+    items?: {
+        id: string;
+        label: string;
+        icon?: string;
+        onClick?: () => void;
+        href?: string;
+        style?: TopBarActionStyle;
+    }[];
+}
+/**
+ * Register this view's top-bar actions with the host. Call with an empty
+ * array (or unmount) to clear them - e.g. because the current screen inside
+ * your app doesn't have any right now.
+ *
+ * ```tsx
+ * useTopBarActions([
+ *   { id: "clone", label: "Clone", icon: "git-branch", onClick: () => setCloneOpen(true) },
+ *   { id: "more", label: "More", icon: "more-horizontal", items: [
+ *     { id: "reset", label: "Reset", onClick: () => reset() },
+ *     { id: "docs", label: "Docs", onClick: () => switchView("docs") },
+ *   ]},
+ * ]);
+ * ```
+ */
+export declare function useTopBarActions(actions: TopBarAction[]): void;
+/** Asks the host to switch the workspace to another view - a built-in one
+ *  ("code" | "preview" | "changes" | "activity" | "documents" | "project")
+ *  or another `custom_views` id. */
+export declare function switchView(viewId: string): void;

package/dist/topbar.js

@@ -0,0 +1,89 @@
+import * as React from "react";
+function flatten(actions) {
+    const map = new Map();
+    for (const a of actions) {
+        if (a.onClick && !a.href)
+            map.set(a.id, a.onClick);
+        for (const s of a.items ?? []) {
+            if (s.onClick && !s.href)
+                map.set(s.id, s.onClick);
+        }
+    }
+    return map;
+}
+/**
+ * Register this view's top-bar actions with the host. Call with an empty
+ * array (or unmount) to clear them - e.g. because the current screen inside
+ * your app doesn't have any right now.
+ *
+ * ```tsx
+ * useTopBarActions([
+ *   { id: "clone", label: "Clone", icon: "git-branch", onClick: () => setCloneOpen(true) },
+ *   { id: "more", label: "More", icon: "more-horizontal", items: [
+ *     { id: "reset", label: "Reset", onClick: () => reset() },
+ *     { id: "docs", label: "Docs", onClick: () => switchView("docs") },
+ *   ]},
+ * ]);
+ * ```
+ */
+export function useTopBarActions(actions) {
+    const handlersRef = React.useRef(new Map());
+    handlersRef.current = flatten(actions);
+    // Full replace, never a diff - simplest contract for both sides. Only
+    // label/icon/id cross the wire; `onClick` stays local (see `flatten`).
+    const wireItems = React.useMemo(() => actions.map((a) => ({
+        id: a.id,
+        label: a.label,
+        icon: a.icon,
+        href: a.href,
+        style: a.style,
+        items: a.items?.map((s) => ({ id: s.id, label: s.label, icon: s.icon, href: s.href, style: s.style })),
+    })), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- content, not identity
+    [JSON.stringify(actions)]);
+    React.useEffect(() => {
+        if (typeof window === "undefined")
+            return;
+        try {
+            window.parent?.postMessage({ type: "digi:topbar-register", items: wireItems }, "*");
+        }
+        catch {
+            /* cross-origin parent may reject - nothing to fall back to here */
+        }
+    }, [wireItems]);
+    React.useEffect(() => {
+        if (typeof window === "undefined")
+            return;
+        const onMessage = (e) => {
+            const d = e.data;
+            if (!d || d.type !== "digi:topbar-click" || typeof d.id !== "string")
+                return;
+            handlersRef.current.get(d.id)?.();
+        };
+        window.addEventListener("message", onMessage);
+        return () => window.removeEventListener("message", onMessage);
+    }, []);
+    React.useEffect(() => {
+        return () => {
+            try {
+                window.parent?.postMessage({ type: "digi:topbar-register", items: [] }, "*");
+            }
+            catch {
+                /* best-effort - the host also clears on iframe unmount */
+            }
+        };
+    }, []);
+}
+/** Asks the host to switch the workspace to another view - a built-in one
+ *  ("code" | "preview" | "changes" | "activity" | "documents" | "project")
+ *  or another `custom_views` id. */
+export function switchView(viewId) {
+    if (typeof window === "undefined")
+        return;
+    try {
+        window.parent?.postMessage({ type: "digi:switch-view", viewId }, "*");
+    }
+    catch {
+        /* cross-origin parent may reject */
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,94 @@
+export type SessionInfo = {
+    baseUrl: string;
+    appId: string;
+    sessionId: string;
+    /** JWT - used only outside the embedded preview. */
+    token?: string;
+    /** Per-session preview token (`?t=`) carried by the embedded-preview URL.
+     *  When present, the SDK reads/writes via the public `preview/files` routes
+     *  instead of the JWT-only `workspace/files` routes - no BFF, no cookie. */
+    previewToken?: string;
+};
+export type MessagePart = {
+    type?: string;
+    text?: string;
+    content?: string;
+};
+export type MessagePayload = {
+    role: string;
+    content?: string;
+    reasoning?: string;
+    parts?: MessagePart[];
+};
+export type ToolPayload = {
+    call_id: string;
+    name: string;
+    arguments?: Record<string, unknown>;
+    status?: string;
+    text?: string;
+};
+export type ApprovalPayload = {
+    id: string;
+    kind: string;
+    payload?: Record<string, unknown>;
+    status?: string;
+    reason?: string;
+};
+export type TurnPayload = {
+    turn_id: string;
+    phase?: string;
+    status?: string;
+    reason?: string;
+};
+export type ErrorPayload = {
+    code?: string;
+    message: string;
+    category?: string;
+};
+export type Envelope = {
+    seq: number;
+    type: string;
+    ts: number;
+    session_id: string;
+    correlation_id?: string;
+    message?: MessagePayload;
+    tool?: ToolPayload;
+    approval?: ApprovalPayload;
+    turn?: TurnPayload;
+    error?: ErrorPayload;
+    [key: string]: unknown;
+};
+export type AgentStatus = "idle" | "thinking" | "tool_use" | "streaming" | "error";
+export type ToolCall = {
+    callId: string;
+    name: string;
+    args?: Record<string, unknown>;
+    status?: string;
+    result?: string;
+};
+export type ChatMessage = {
+    role: "user" | "assistant" | "system";
+    content: string;
+    reasoning?: string;
+    streaming?: boolean;
+    toolCalls?: ToolCall[];
+    correlationId?: string;
+    ts: number;
+};
+export type Approval = {
+    id: string;
+    kind: string;
+    payload?: Record<string, unknown>;
+    status?: string;
+};
+export type State = {
+    connected: boolean;
+    status: AgentStatus;
+    messages: ChatMessage[];
+    turnActive: boolean;
+    approvals: Approval[];
+    events: Envelope[];
+    lastSeq: number;
+    error: string | null;
+};
+export declare const initialState: State;

package/dist/types.js

@@ -0,0 +1,10 @@
+export const initialState = {
+    connected: false,
+    status: "idle",
+    messages: [],
+    turnActive: false,
+    approvals: [],
+    events: [],
+    lastSeq: 0,
+    error: null,
+};