@beeuni/sdk 0.1.0

package/dist/react/use-wake-escalation.d.ts

@@ -0,0 +1,31 @@
+import { type WakeEscalationLimits, type WakeEscalationState } from '../core/session/wake-escalation.js';
+export interface UseWakeEscalationInput {
+    enabled?: boolean;
+    waking: boolean;
+    runtimeReachable: boolean;
+    progress: string;
+    serverGaveUp: boolean;
+    onRetryStart: () => void;
+    onRestart: () => void;
+    limits?: WakeEscalationLimits;
+    projectId?: string;
+    sessionId?: string;
+}
+export interface ServerWakeLadder {
+    status: 'idle' | 'waking' | 'escalating' | 'exhausted';
+    retried: boolean;
+    restarts: number;
+    max_restarts: number;
+    silent_since: string | null;
+}
+export declare function wakeEscalationViewFromServer(ladder: ServerWakeLadder, nowMs: number): WakeEscalationView;
+export interface WakeEscalationView {
+    status: WakeEscalationState['status'];
+    attempts: WakeEscalationState['attempts'];
+    attemptNumber: number;
+    note: string | null;
+    exhausted: boolean;
+    summary: string | null;
+    msSinceProgress: number;
+}
+export declare function useWakeEscalation(input: UseWakeEscalationInput): WakeEscalationView;

package/dist/react/use-wake-escalation.js

@@ -0,0 +1,82 @@
+'use client';
+import { useQuery } from '@tanstack/react-query';
+import { useEffect, useRef, useState } from 'react';
+import { qk } from './query-keys.js';
+import { useSessionStreamConnected } from './use-session-stream.js';
+import { advanceWakeEscalation, initialWakeEscalationState, wakeEscalationAttemptSummary, wakeEscalationNote, } from '../core/session/wake-escalation.js';
+export function wakeEscalationViewFromServer(ladder, nowMs) {
+    const attempts = [
+        ...(ladder.retried ? [{ step: 'retry-start', atMs: 0 }] : []),
+        ...Array.from({ length: ladder.restarts }, () => ({ step: 'restart', atMs: 0 })),
+    ];
+    const silentSince = ladder.silent_since ? Date.parse(ladder.silent_since) : Number.NaN;
+    const state = {
+        ...initialWakeEscalationState,
+        status: ladder.status,
+        attempts,
+        msSinceProgress: Number.isFinite(silentSince) ? Math.max(0, nowMs - silentSince) : 0,
+    };
+    return {
+        status: state.status,
+        attempts,
+        attemptNumber: attempts.length + 1,
+        note: wakeEscalationNote(state),
+        exhausted: state.status === 'exhausted',
+        summary: wakeEscalationAttemptSummary(state),
+        msSinceProgress: state.msSinceProgress,
+    };
+}
+const WAKE_TICK_MS = 1_000;
+export function useWakeEscalation(input) {
+    const { enabled = true, waking, runtimeReachable, progress, serverGaveUp, onRetryStart, onRestart, limits, projectId = '', sessionId = '', } = input;
+    const streamConnected = useSessionStreamConnected(projectId, sessionId);
+    const runtimeControl = useQuery({
+        queryKey: qk.project.sessionRuntimeControl(projectId, sessionId),
+        queryFn: () => null,
+        enabled: false,
+    }).data;
+    const serverLadder = streamConnected ? (runtimeControl?.wake_ladder ?? null) : null;
+    const [state, setState] = useState(initialWakeEscalationState);
+    const stateRef = useRef(state);
+    const [tick, setTick] = useState(0);
+    const actionsRef = useRef({ onRetryStart, onRestart });
+    const limitsRef = useRef(limits);
+    useEffect(() => {
+        actionsRef.current = { onRetryStart, onRestart };
+        limitsRef.current = limits;
+    });
+    const serverActive = serverLadder !== null && (serverLadder.status === 'waking' || serverLadder.status === 'escalating');
+    const active = serverLadder ? serverActive : enabled && waking && !runtimeReachable;
+    useEffect(() => {
+        if (!active)
+            return;
+        const id = setInterval(() => setTick((value) => value + 1), WAKE_TICK_MS);
+        return () => clearInterval(id);
+    }, [active]);
+    useEffect(() => {
+        const next = advanceWakeEscalation(stateRef.current, {
+            nowMs: Date.now(),
+            waking: enabled && waking && !serverLadder,
+            runtimeReachable,
+            progress,
+            serverGaveUp,
+        }, limitsRef.current);
+        stateRef.current = next;
+        setState(next);
+        if (next.dispatch === 'retry-start')
+            actionsRef.current.onRetryStart();
+        else if (next.dispatch === 'restart')
+            actionsRef.current.onRestart();
+    }, [enabled, waking, runtimeReachable, progress, serverGaveUp, tick, serverLadder]);
+    if (serverLadder)
+        return wakeEscalationViewFromServer(serverLadder, Date.now());
+    return {
+        status: state.status,
+        attempts: state.attempts,
+        attemptNumber: state.attempts.length + 1,
+        note: wakeEscalationNote(state),
+        exhausted: state.status === 'exhausted',
+        summary: wakeEscalationAttemptSummary(state),
+        msSinceProgress: state.msSinceProgress,
+    };
+}

package/dist/transcript.d.ts

@@ -0,0 +1,50 @@
+import type { Message, Part } from './core/runtime/runtime-types.js';
+export interface TranscriptOptions {
+    thinking: boolean;
+    toolDetails: boolean;
+    assistantMetadata: boolean;
+}
+export interface SessionInfo {
+    id: string;
+    title: string;
+    time: {
+        created: number;
+        updated: number;
+    };
+}
+interface TranscriptMessageInfo {
+    id: string;
+    role: 'user' | 'assistant';
+    agent?: string;
+    modelID?: string;
+    time?: {
+        created?: number;
+        completed?: number;
+    };
+}
+interface TranscriptPartState {
+    status?: string;
+    input?: unknown;
+    output?: string;
+    error?: string;
+}
+interface TranscriptPart {
+    id: string;
+    type: string;
+    synthetic?: boolean;
+    text?: string;
+    tool?: string;
+    state?: TranscriptPartState;
+}
+export interface MessageWithParts {
+    info: Message;
+    parts: Part[];
+}
+interface TranscriptMessage {
+    info: TranscriptMessageInfo;
+    parts: TranscriptPart[];
+}
+export declare const DEFAULT_TRANSCRIPT_OPTIONS: TranscriptOptions;
+export declare function formatTranscript(session: SessionInfo, messages: TranscriptMessage[], options?: TranscriptOptions): string;
+export declare function getTranscriptFilename(sessionId: string, _title?: string): string;
+export {};

package/dist/transcript.js

@@ -0,0 +1,93 @@
+export const DEFAULT_TRANSCRIPT_OPTIONS = {
+    thinking: false,
+    toolDetails: true,
+    assistantMetadata: true,
+};
+function titleCase(str) {
+    if (!str)
+        return str;
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+function formatDuration(ms) {
+    const seconds = ms / 1000;
+    if (seconds < 60)
+        return `${seconds.toFixed(1)}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remaining = seconds % 60;
+    return `${minutes}m ${remaining.toFixed(0)}s`;
+}
+function formatPart(part, options) {
+    if (part.type === 'text' && !part.synthetic) {
+        return `${part.text ?? ''}\n\n`;
+    }
+    if (part.type === 'reasoning') {
+        if (options.thinking) {
+            return `> _Thinking:_\n>\n> ${(part.text ?? '').replace(/\n/g, '\n> ')}\n\n`;
+        }
+        return '';
+    }
+    if (part.type === 'tool') {
+        let result = `**Tool: ${part.tool ?? 'unknown'}**\n`;
+        if (options.toolDetails && part.state?.input) {
+            try {
+                const inputStr = typeof part.state.input === 'string'
+                    ? part.state.input
+                    : JSON.stringify(part.state.input, null, 2);
+                result += `\n<details>\n<summary>Input</summary>\n\n\`\`\`json\n${inputStr}\n\`\`\`\n\n</details>\n`;
+            }
+            catch {
+            }
+        }
+        if (options.toolDetails && part.state?.status === 'completed' && part.state.output) {
+            const output = part.state.output;
+            const truncated = output.length > 2000 ? output.slice(0, 2000) + '\n... (truncated)' : output;
+            result += `\n<details>\n<summary>Output</summary>\n\n\`\`\`\n${truncated}\n\`\`\`\n\n</details>\n`;
+        }
+        if (options.toolDetails && part.state?.status === 'error' && part.state.error) {
+            result += `\n**Error:**\n\`\`\`\n${part.state.error}\n\`\`\`\n`;
+        }
+        result += '\n';
+        return result;
+    }
+    return '';
+}
+function formatAssistantHeader(msg, includeMetadata) {
+    if (!includeMetadata)
+        return `## Assistant\n\n`;
+    const agent = msg.agent ? titleCase(msg.agent) : 'Assistant';
+    const model = msg.modelID || '';
+    let duration = '';
+    if (msg.time?.completed && msg.time?.created) {
+        duration = formatDuration(msg.time.completed - msg.time.created);
+    }
+    const meta = [model, duration].filter(Boolean).join(' · ');
+    return meta ? `## ${agent} (${meta})\n\n` : `## ${agent}\n\n`;
+}
+function formatMessage(msg, parts, options) {
+    let result = '';
+    if (msg.role === 'user') {
+        result += `## User\n\n`;
+    }
+    else {
+        result += formatAssistantHeader(msg, options.assistantMetadata);
+    }
+    for (const part of parts) {
+        result += formatPart(part, options);
+    }
+    return result;
+}
+export function formatTranscript(session, messages, options = DEFAULT_TRANSCRIPT_OPTIONS) {
+    let transcript = `# ${session.title || 'Untitled Session'}\n\n`;
+    transcript += `**Session ID:** \`${session.id}\`\n`;
+    transcript += `**Created:** ${new Date(session.time.created).toLocaleString()}\n`;
+    transcript += `**Updated:** ${new Date(session.time.updated).toLocaleString()}\n\n`;
+    transcript += `---\n\n`;
+    for (const msg of messages) {
+        transcript += formatMessage(msg.info, msg.parts, options);
+        transcript += `---\n\n`;
+    }
+    return transcript;
+}
+export function getTranscriptFilename(sessionId, _title) {
+    return `session-${sessionId}.md`;
+}

package/dist/workspace-search/client.d.ts

@@ -0,0 +1,19 @@
+import { type WorkspaceSearchEntry, type WorkspaceSearchOptions } from './core.js';
+export interface WorkspaceSearchRuntimeOptions extends WorkspaceSearchOptions {
+    apiLimit?: number;
+}
+export interface WorkspaceSearchFileClient {
+    listFiles(path: string): Promise<{
+        path: string;
+        type: string;
+    }[]>;
+    findFiles(query: string, options?: {
+        type?: 'file' | 'directory';
+        limit?: number;
+    }): Promise<string[]>;
+}
+export declare function createWorkspaceSearchClient(client: WorkspaceSearchFileClient, getCacheKey?: () => string): {
+    searchWorkspaceFileEntries: (query: string, options?: WorkspaceSearchRuntimeOptions) => Promise<WorkspaceSearchEntry[]>;
+    searchWorkspaceFilePaths: (query: string, options?: WorkspaceSearchRuntimeOptions) => Promise<string[]>;
+    searchWorkspaceFiles: (query: string, limit?: number) => Promise<string[]>;
+};

package/dist/workspace-search/client.js

@@ -0,0 +1,229 @@
+import { dedupeWorkspaceSearchEntries, mergeWorkspaceSearchEntries, normalizeSearchQuery, parseWorkspacePaths, rankWorkspaceSearchEntry, searchIndexedWorkspaceEntries, toWorkspaceSearchEntry, workspaceQueryLooksPathLike, } from './core.js';
+const INDEX_TTL_MS = 60_000;
+const INDEX_MAX_ENTRIES = 5_000;
+const INDEX_CONCURRENCY = 6;
+const INDEX_SKIP_DIR_NAMES = new Set([
+    '.git',
+    '.next',
+    '.pnpm',
+    '.turbo',
+    '.yarn',
+    'build',
+    'coverage',
+    'dist',
+    'node_modules',
+]);
+export function createWorkspaceSearchClient(client, getCacheKey = () => '') {
+    const workspaceIndexCaches = new Map();
+    function toDirectoryPath(path) {
+        return path.replace(/\/+$/, '');
+    }
+    function toResultPath(entry) {
+        return entry.isDir ? `${entry.path}/` : entry.path;
+    }
+    function getCacheForServer(serverUrl) {
+        return workspaceIndexCaches.get(serverUrl);
+    }
+    function setCacheForServer(serverUrl, cache) {
+        workspaceIndexCaches.set(serverUrl, cache);
+    }
+    function nodeToWorkspaceEntry(node) {
+        return toWorkspaceSearchEntry(node.path, node.type === 'directory');
+    }
+    async function readDirectoryEntries(dirPath) {
+        try {
+            const nodes = await client.listFiles(dirPath);
+            return dedupeWorkspaceSearchEntries(nodes.map(nodeToWorkspaceEntry));
+        }
+        catch {
+            return [];
+        }
+    }
+    async function getBackendEntries(query, options) {
+        const limit = options.apiLimit ?? Math.max(options.limit ?? 50, 100);
+        if (options.type === 'file') {
+            const fileOnly = await client.findFiles(query, { type: 'file', limit }).catch(() => []);
+            return parseWorkspacePaths(fileOnly);
+        }
+        if (options.type === 'directory') {
+            const dirsOnly = await client.findFiles(query, { type: 'directory', limit }).catch(() => []);
+            return parseWorkspacePaths(dirsOnly.map((path) => `${path.replace(/\/+$/, '')}/`));
+        }
+        const [fileOnly, broad, dirsOnly] = await Promise.all([
+            client.findFiles(query, { type: 'file', limit }).catch(() => []),
+            client.findFiles(query, { limit }).catch(() => []),
+            client.findFiles(query, { type: 'directory', limit }).catch(() => []),
+        ]);
+        const normalizedDirs = dirsOnly.map((path) => path.replace(/\/+$/, ''));
+        return parseWorkspacePaths([...fileOnly, ...broad, ...dirsOnly], normalizedDirs);
+    }
+    function rankSegmentName(name, segment) {
+        const lowerName = name.toLowerCase();
+        const lowerSegment = segment.toLowerCase();
+        if (!lowerSegment)
+            return 0;
+        if (lowerName === lowerSegment)
+            return 0;
+        if (lowerName.startsWith(lowerSegment))
+            return 10;
+        if (lowerName.includes(lowerSegment))
+            return 20;
+        let index = 0;
+        for (let i = 0; i < lowerName.length && index < lowerSegment.length; i++) {
+            if (lowerName[i] === lowerSegment[index])
+                index += 1;
+        }
+        return index === lowerSegment.length ? 30 : 1000;
+    }
+    function filterSegmentEntries(entries, segment, options) {
+        return entries
+            .filter((entry) => {
+            if (options?.type === 'file' && entry.isDir)
+                return false;
+            if (options?.type === 'directory' && !entry.isDir)
+                return false;
+            return rankSegmentName(entry.name, segment) < 1000;
+        })
+            .sort((left, right) => {
+            const leftRank = rankSegmentName(left.name, segment);
+            const rightRank = rankSegmentName(right.name, segment);
+            if (leftRank !== rightRank)
+                return leftRank - rightRank;
+            return left.path.localeCompare(right.path);
+        });
+    }
+    async function searchByPathTraversal(query, options) {
+        const normalizedQuery = normalizeSearchQuery(query);
+        if (!workspaceQueryLooksPathLike(normalizedQuery))
+            return [];
+        const segments = normalizedQuery
+            .replace(/^\/workspace\/?/i, '')
+            .replace(/^workspace\/?/i, '')
+            .split('/')
+            .filter(Boolean);
+        if (segments.length === 0)
+            return [];
+        const parentSegments = segments.slice(0, -1);
+        const leafSegment = segments[segments.length - 1] || '';
+        let candidateDirs = [toWorkspaceSearchEntry('/workspace', true)];
+        for (const segment of parentSegments) {
+            const childLists = await Promise.all(candidateDirs.slice(0, INDEX_CONCURRENCY).map((dir) => readDirectoryEntries(dir.path)));
+            const matches = dedupeWorkspaceSearchEntries(childLists.flat().filter((entry) => entry.isDir));
+            candidateDirs = filterSegmentEntries(matches, segment, { type: 'directory' }).slice(0, INDEX_CONCURRENCY);
+            if (candidateDirs.length === 0)
+                return [];
+        }
+        const leafLists = await Promise.all(candidateDirs
+            .slice(0, INDEX_CONCURRENCY)
+            .map((dir) => readDirectoryEntries(toDirectoryPath(dir.path))));
+        const leafMatches = filterSegmentEntries(dedupeWorkspaceSearchEntries(leafLists.flat()), leafSegment, options);
+        return leafMatches
+            .sort((left, right) => {
+            const leftRank = rankWorkspaceSearchEntry(left, normalizedQuery);
+            const rightRank = rankWorkspaceSearchEntry(right, normalizedQuery);
+            if (leftRank !== rightRank)
+                return leftRank - rightRank;
+            return left.path.localeCompare(right.path);
+        })
+            .slice(0, options.limit ?? 50);
+    }
+    async function buildWorkspaceIndex() {
+        const queue = ['/workspace'];
+        const seenDirs = new Set(['/workspace']);
+        const indexed = new Map();
+        while (queue.length > 0 && indexed.size < INDEX_MAX_ENTRIES) {
+            const batch = queue.splice(0, INDEX_CONCURRENCY);
+            const listed = await Promise.all(batch.map((dir) => readDirectoryEntries(dir)));
+            for (const entries of listed) {
+                for (const entry of entries) {
+                    const key = `${entry.path}:${entry.isDir ? 'dir' : 'file'}`;
+                    if (!indexed.has(key))
+                        indexed.set(key, entry);
+                    if (entry.isDir &&
+                        !seenDirs.has(entry.path) &&
+                        !INDEX_SKIP_DIR_NAMES.has(entry.name) &&
+                        indexed.size < INDEX_MAX_ENTRIES) {
+                        seenDirs.add(entry.path);
+                        queue.push(entry.path);
+                    }
+                }
+            }
+        }
+        return Array.from(indexed.values());
+    }
+    async function getWorkspaceIndexEntries() {
+        const serverUrl = getCacheKey();
+        const current = getCacheForServer(serverUrl);
+        const now = Date.now();
+        if (current && current.entries.length > 0 && now - current.fetchedAt < INDEX_TTL_MS) {
+            return current.entries;
+        }
+        if (current?.inFlight) {
+            return current.inFlight;
+        }
+        const inFlight = buildWorkspaceIndex()
+            .then((entries) => {
+            setCacheForServer(serverUrl, {
+                entries,
+                fetchedAt: Date.now(),
+            });
+            return entries;
+        })
+            .catch(() => {
+            const fallback = current?.entries ?? [];
+            setCacheForServer(serverUrl, {
+                entries: fallback,
+                fetchedAt: current?.fetchedAt ?? 0,
+            });
+            return fallback;
+        });
+        setCacheForServer(serverUrl, {
+            entries: current?.entries ?? [],
+            fetchedAt: current?.fetchedAt ?? 0,
+            inFlight,
+        });
+        return inFlight;
+    }
+    function shouldLoadIndex(query, results, limit) {
+        if (workspaceQueryLooksPathLike(query)) {
+            if (results.length === 0)
+                return true;
+            const bestRank = rankWorkspaceSearchEntry(results[0], query);
+            return bestRank > 20 && results.length < Math.min(limit, 5);
+        }
+        return results.length < Math.min(limit, 10);
+    }
+    async function searchWorkspaceFileEntries(query, options) {
+        const normalizedQuery = normalizeSearchQuery(query);
+        if (!normalizedQuery)
+            return [];
+        const resolvedOptions = {
+            limit: options?.limit ?? 50,
+            type: options?.type,
+            apiLimit: options?.apiLimit,
+        };
+        const [backendEntries, traversedEntries] = await Promise.all([
+            getBackendEntries(normalizedQuery, resolvedOptions),
+            searchByPathTraversal(normalizedQuery, resolvedOptions),
+        ]);
+        let merged = mergeWorkspaceSearchEntries(backendEntries, traversedEntries, normalizedQuery, resolvedOptions);
+        if (!shouldLoadIndex(normalizedQuery, merged, resolvedOptions.limit ?? 50)) {
+            return merged;
+        }
+        const indexEntries = await getWorkspaceIndexEntries();
+        const indexedMatches = searchIndexedWorkspaceEntries(indexEntries, normalizedQuery, {
+            limit: Math.max((resolvedOptions.limit ?? 50) * 4, 200),
+            type: resolvedOptions.type,
+        });
+        merged = mergeWorkspaceSearchEntries(merged, indexedMatches, normalizedQuery, resolvedOptions);
+        return merged;
+    }
+    async function searchWorkspaceFilePaths(query, options) {
+        const entries = await searchWorkspaceFileEntries(query, options);
+        return entries.map(toResultPath);
+    }
+    async function searchWorkspaceFiles(query, limit = 50) {
+        return searchWorkspaceFilePaths(query, { limit, apiLimit: Math.max(limit, 100) });
+    }
+    return { searchWorkspaceFileEntries, searchWorkspaceFilePaths, searchWorkspaceFiles };
+}

package/dist/workspace-search/core.d.ts

@@ -0,0 +1,21 @@
+export interface WorkspaceSearchEntry {
+    path: string;
+    name: string;
+    isDir: boolean;
+}
+export interface WorkspaceSearchOptions {
+    limit?: number;
+    type?: 'file' | 'directory';
+}
+export declare function normalizeSearchQuery(query: string): string;
+export declare function stripWorkspacePrefix(path: string): string;
+export declare function normalizeWorkspacePath(path: string): string;
+export declare function getWorkspaceEntryName(path: string): string;
+export declare function toWorkspaceSearchEntry(path: string, isDir?: boolean): WorkspaceSearchEntry;
+export declare function parseWorkspacePaths(paths: string[], knownDirs?: Iterable<string>): WorkspaceSearchEntry[];
+export declare function workspaceQueryLooksPathLike(query: string): boolean;
+export declare function workspaceEntryMatchesQuery(entry: WorkspaceSearchEntry, query: string, policy?: 'runtime-files'): boolean;
+export declare function rankWorkspaceSearchEntry(entry: WorkspaceSearchEntry, query: string, policy?: 'runtime-files'): number;
+export declare function dedupeWorkspaceSearchEntries(entries: WorkspaceSearchEntry[]): WorkspaceSearchEntry[];
+export declare function searchIndexedWorkspaceEntries(entries: WorkspaceSearchEntry[], query: string, options?: WorkspaceSearchOptions): WorkspaceSearchEntry[];
+export declare function mergeWorkspaceSearchEntries(primary: WorkspaceSearchEntry[], fallback: WorkspaceSearchEntry[], query: string, options?: WorkspaceSearchOptions): WorkspaceSearchEntry[];