@beeuni/sdk 0.1.0

package/dist/core/session/turn-end-cause.d.ts

@@ -0,0 +1,22 @@
+import type { SessionTurnEndError, SessionTurnEnded, SessionTurnFailure } from '../rest/projects-client/sessions.js';
+export interface SessionTurnOutcome {
+    last_ended?: SessionTurnEnded;
+    recent_failures?: SessionTurnFailure[];
+    atMs?: number;
+}
+export declare function turnEndCause(outcome: SessionTurnOutcome | undefined, messageId: string | null | undefined): SessionTurnEndError | null;
+export type TurnEndNotice = {
+    kind: 'sandbox-memory';
+    usedPct: number | null;
+    detail: string | null;
+} | {
+    kind: 'cause';
+    name: string | null;
+    message: string;
+} | {
+    kind: 'unexplained';
+};
+export declare function turnEndNotice(outcome: SessionTurnOutcome | undefined, messageId: string | null | undefined, transcript: {
+    hasError: boolean;
+    isAbort: boolean;
+}): TurnEndNotice | null;

package/dist/core/session/turn-end-cause.js

@@ -0,0 +1,41 @@
+import { isAbortError } from '../http/abort-error.js';
+import { TURN_END_SETTLE_MS } from './turn-end-settle.js';
+export function turnEndCause(outcome, messageId) {
+    if (!outcome || !messageId)
+        return null;
+    const listed = outcome.recent_failures?.find((failure) => failure.message_id === messageId);
+    const lastEnded = outcome.last_ended;
+    const error = listed?.error ??
+        (lastEnded?.message_id === messageId && lastEnded.end_reason === 'failed'
+            ? lastEnded.error
+            : undefined);
+    if (!error?.message)
+        return null;
+    if (isAbortError({ name: error.name ?? undefined, message: error.message }))
+        return null;
+    return error;
+}
+const SANDBOX_MEMORY_GUARD = 'SandboxMemoryGuard';
+export function turnEndNotice(outcome, messageId, transcript) {
+    if (!outcome || !messageId)
+        return null;
+    if (transcript.hasError && !transcript.isAbort)
+        return null;
+    const cause = turnEndCause(outcome, messageId);
+    if (cause?.message) {
+        if (cause.name !== SANDBOX_MEMORY_GUARD) {
+            return { kind: 'cause', name: cause.name, message: cause.message };
+        }
+        const pct = cause.message.match(/(\d{1,3})%/)?.[1];
+        const detail = cause.message.split(':')[0]?.trim() || null;
+        return { kind: 'sandbox-memory', usedPct: pct ? Number(pct) : null, detail };
+    }
+    const listed = outcome.recent_failures?.find((failure) => failure.message_id === messageId);
+    if (!listed)
+        return null;
+    const endedMs = listed.ended_at ? Date.parse(listed.ended_at) : Number.NaN;
+    const provisional = Number.isFinite(endedMs) &&
+        typeof outcome.atMs === 'number' &&
+        outcome.atMs - endedMs < TURN_END_SETTLE_MS;
+    return provisional ? null : { kind: 'unexplained' };
+}

package/dist/core/session/turn-end-settle.d.ts

@@ -0,0 +1 @@
+export declare const TURN_END_SETTLE_MS = 2500;

package/dist/core/session/turn-end-settle.js

@@ -0,0 +1 @@
+export const TURN_END_SETTLE_MS = 2_500;

package/dist/core/session/url.d.ts

@@ -0,0 +1,49 @@
+export interface DetectedLocalhostUrl {
+    originalUrl: string;
+    port: number;
+    path: string;
+    startIndex: number;
+    endIndex: number;
+    inCodeBlock: boolean;
+}
+export interface ParsedLocalhostUrl {
+    originalUrl: string;
+    port: number;
+    path: string;
+}
+export interface SubdomainUrlOptions {
+    sandboxId: string;
+    backendPort: number;
+    apiBaseUrl: string;
+    previewUrlTemplate?: string | null;
+}
+export declare function isAppRouteUrl(rawUrl: string | undefined): boolean;
+export declare function parseLocalhostUrl(rawUrl: string | undefined): ParsedLocalhostUrl | null;
+export declare function detectLocalhostUrls(text: string): DetectedLocalhostUrl[];
+export declare function hasLocalhostUrls(text: string): boolean;
+export declare function stripTrailingSlashes(value: string): string;
+export declare function hasPreviewTarget(subdomainOpts: SubdomainUrlOptions): boolean;
+export declare function rewriteLocalhostUrl(port: number, path: string, subdomainOpts: SubdomainUrlOptions): string;
+export declare function buildStaticFilePreviewUrl(filePath: string | undefined, options: SubdomainUrlOptions): string | undefined;
+export declare function buildStaticFileServicePath(filePath: string): string;
+export declare function buildStaticFileLocalUrl(filePath: string): string;
+export declare function getStaticFileHealthPath(): string;
+export declare function buildStaticFileHealthPreviewUrl(options: SubdomainUrlOptions): string;
+export declare function getProxyBaseUrl(port: number, subdomainOpts: SubdomainUrlOptions): string;
+export declare function isProxiableLocalhostUrl(url: string): boolean;
+export declare function proxyLocalhostUrl(url: string | undefined, subdomainOpts: SubdomainUrlOptions): string | undefined;
+export declare function toInternalUrl(port: number, path?: string): string;
+export declare function parseSubdomainUrl(url: string): {
+    port: number;
+    sandboxId: string;
+    backendPort: number;
+    path: string;
+} | null;
+export declare function proxyUrlToInternal(proxyUrl: string): string | null;
+export declare function isPreviewUrl(url: string): boolean;
+export declare function isInternalLocalhostUrl(url: string): boolean;
+export declare function buildWebProxyUrl(targetUrl: string, subdomainOpts: SubdomainUrlOptions): string | null;
+export declare function parseWebProxyUrl(proxyUrl: string): string | null;
+export declare function isWebProxyUrl(url: string): boolean;
+export declare function isExternalUrl(rawUrl: string): boolean;
+export declare function normalizeExternalInput(input: string): string | null;

package/dist/core/session/url.js

@@ -0,0 +1,415 @@
+import { SANDBOX_PORTS } from '../rest/platform-client/types.js';
+const LOCALHOST_URL_REGEX = /https?:\/\/(?:localhost|127\.0\.0\.1):\d{1,5}[^\s)"'<>]*/g;
+const SUBDOMAIN_URL_REGEX = /^https?:\/\/p(\d+)-([^.]+)\.localhost(?::(\d+))?(\/.*)?$/;
+const PREVIEW_ORIGIN_URL_REGEX = /^https?:\/\/(?:dev|staging|prod|preview)-p(\d+)-([a-z0-9-]+)\.[^/]+?(?::(\d+))?(\/.*)?$/i;
+const EXCLUDED_PORTS = new Set([
+    22,
+    4096,
+    parseInt(SANDBOX_PORTS.BEEUNI_MASTER, 10),
+]);
+function isSubdomainUrl(url) {
+    return SUBDOMAIN_URL_REGEX.test(url);
+}
+function normalizePath(path) {
+    if (!path)
+        return '/';
+    let normalized = path;
+    const markdownBoundary = normalized.indexOf('](');
+    if (markdownBoundary !== -1) {
+        normalized = normalized.slice(0, markdownBoundary);
+    }
+    const encodedBoundary = normalized.toLowerCase().indexOf('%5d(');
+    if (encodedBoundary !== -1) {
+        normalized = normalized.slice(0, encodedBoundary);
+    }
+    if (!normalized)
+        return '/';
+    return normalized.startsWith('/') ? normalized : `/${normalized}`;
+}
+function stripMarkdownArtifacts(url) {
+    const markerIndex = url.indexOf('](');
+    if (markerIndex === -1)
+        return url;
+    return url.slice(0, markerIndex);
+}
+const LEADING_WRAPPERS = new Set(["'", '"', '`', '<', '(', '[']);
+const TRAILING_WRAPPERS = new Set(['>', "'", '"', '`', ')', ']', ',', ';', '.', '!', '?']);
+function stripUrlWrappers(url) {
+    let start = 0;
+    let end = url.length;
+    while (start < end && (url[start] === ' ' || url[start] === '\t'))
+        start++;
+    while (end > start && (url[end - 1] === ' ' || url[end - 1] === '\t'))
+        end--;
+    while (start < end && LEADING_WRAPPERS.has(url[start]))
+        start++;
+    while (end > start && TRAILING_WRAPPERS.has(url[end - 1]))
+        end--;
+    return url.slice(start, end);
+}
+function extractLocalhostCandidate(text) {
+    const match = text.match(/https?:\/\/(?:localhost|127\.0\.0\.1):\d{1,5}[^\s"'<>)]*/i);
+    return match?.[0] ?? null;
+}
+const BEEUNI_MASTER_PROXY_REGEX = /^\/proxy\/(\d{1,5})(\/.*)?$/;
+const APP_ROUTE_PREFIXES = /^\/(connectors|settings|dashboard|projects|agents|skills|tools|commands|support|changelog|files|p|browser|desktop|terminal|sessions|services|workspace|channels|scheduled-tasks|marketplace|templates|tunnel|admin|auth)(\/|$|\?)/;
+export function isAppRouteUrl(rawUrl) {
+    if (!rawUrl)
+        return false;
+    try {
+        const parsed = new URL(rawUrl);
+        if (parsed.hostname !== 'localhost' && parsed.hostname !== '127.0.0.1')
+            return false;
+        return APP_ROUTE_PREFIXES.test(parsed.pathname);
+    }
+    catch {
+        return false;
+    }
+}
+export function parseLocalhostUrl(rawUrl) {
+    if (!rawUrl)
+        return null;
+    const candidate = stripUrlWrappers(stripMarkdownArtifacts(rawUrl.trim()));
+    const subdomain = parseSubdomainUrl(candidate);
+    if (subdomain) {
+        const path = normalizePath(subdomain.path || '/');
+        return {
+            originalUrl: `http://localhost:${subdomain.port}${path}`,
+            port: subdomain.port,
+            path,
+        };
+    }
+    try {
+        const parsed = new URL(candidate);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            return null;
+        if (parsed.hostname !== 'localhost' && parsed.hostname !== '127.0.0.1')
+            return null;
+        if (!parsed.port)
+            return null;
+        let port = parseInt(parsed.port, 10);
+        if (!Number.isInteger(port) || port < 1 || port > 65535)
+            return null;
+        let pathStr = `${parsed.pathname || '/'}${parsed.search}${parsed.hash}`;
+        const beeuniMasterPort = parseInt(SANDBOX_PORTS.BEEUNI_MASTER, 10);
+        if (port === beeuniMasterPort) {
+            const proxyMatch = parsed.pathname.match(BEEUNI_MASTER_PROXY_REGEX);
+            if (proxyMatch) {
+                const realPort = parseInt(proxyMatch[1], 10);
+                if (realPort >= 1 && realPort <= 65535) {
+                    port = realPort;
+                    pathStr = normalizePath(`${proxyMatch[2] || '/'}${parsed.search}${parsed.hash}`);
+                    return {
+                        originalUrl: `http://localhost:${port}${pathStr}`,
+                        port,
+                        path: pathStr,
+                    };
+                }
+            }
+        }
+        const path = normalizePath(pathStr);
+        return {
+            originalUrl: `${parsed.protocol}//${parsed.hostname}:${port}${path}`,
+            port,
+            path,
+        };
+    }
+    catch {
+        const extracted = extractLocalhostCandidate(rawUrl);
+        if (extracted && extracted !== rawUrl) {
+            return parseLocalhostUrl(extracted);
+        }
+        return null;
+    }
+}
+function getCodeRanges(text) {
+    const ranges = [];
+    const fencedRegex = /```[\s\S]*?```/g;
+    let m;
+    while ((m = fencedRegex.exec(text)) !== null) {
+        ranges.push([m.index, m.index + m[0].length]);
+    }
+    const inlineRegex = /`[^`\n]+`/g;
+    while ((m = inlineRegex.exec(text)) !== null) {
+        const start = m.index;
+        const end = start + m[0].length;
+        const insideFenced = ranges.some(([rs, re]) => start >= rs && end <= re);
+        if (!insideFenced) {
+            ranges.push([start, end]);
+        }
+    }
+    return ranges;
+}
+function isInsideCodeBlock(index, ranges) {
+    return ranges.some(([start, end]) => index >= start && index < end);
+}
+export function detectLocalhostUrls(text) {
+    const results = [];
+    const seen = new Set();
+    const codeRanges = getCodeRanges(text);
+    LOCALHOST_URL_REGEX.lastIndex = 0;
+    let match;
+    while ((match = LOCALHOST_URL_REGEX.exec(text)) !== null) {
+        const parsed = parseLocalhostUrl(match[0]);
+        if (!parsed)
+            continue;
+        const { originalUrl, port, path } = parsed;
+        if (port < 1 || port > 65535 || EXCLUDED_PORTS.has(port))
+            continue;
+        if (seen.has(originalUrl))
+            continue;
+        seen.add(originalUrl);
+        results.push({
+            originalUrl,
+            port,
+            path,
+            startIndex: match.index,
+            endIndex: match.index + originalUrl.length,
+            inCodeBlock: isInsideCodeBlock(match.index, codeRanges),
+        });
+    }
+    return results;
+}
+export function hasLocalhostUrls(text) {
+    return detectLocalhostUrls(text).length > 0;
+}
+function isBackendOnLocalhost(apiBaseUrl) {
+    try {
+        const { hostname } = new URL(apiBaseUrl);
+        return hostname === 'localhost' || hostname === '127.0.0.1';
+    }
+    catch {
+        return false;
+    }
+}
+function sandboxHostLabel(sandboxId) {
+    return sandboxId.trim().toLowerCase().split('_').join('-');
+}
+export function stripTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47)
+        end--;
+    return value.slice(0, end);
+}
+function previewOriginUrl(port, safePath, opts) {
+    const template = opts.previewUrlTemplate;
+    if (!template || !template.includes('{port}') || !template.includes('{sandbox}'))
+        return null;
+    const origin = template
+        .split('{port}')
+        .join(String(port))
+        .split('{sandbox}')
+        .join(sandboxHostLabel(opts.sandboxId));
+    return `${stripTrailingSlashes(origin)}${safePath}`;
+}
+export function hasPreviewTarget(subdomainOpts) {
+    return subdomainOpts.sandboxId.trim().length > 0;
+}
+export function rewriteLocalhostUrl(port, path, subdomainOpts) {
+    const safePath = normalizePath(path);
+    if (!hasPreviewTarget(subdomainOpts))
+        return toInternalUrl(port, safePath);
+    const originUrl = previewOriginUrl(port, safePath, subdomainOpts);
+    if (originUrl)
+        return originUrl;
+    if (!isBackendOnLocalhost(subdomainOpts.apiBaseUrl)) {
+        const base = stripTrailingSlashes(subdomainOpts.apiBaseUrl);
+        return `${base}/p/${subdomainOpts.sandboxId}/${port}${safePath}`;
+    }
+    return `http://p${port}-${sandboxHostLabel(subdomainOpts.sandboxId)}.localhost:${subdomainOpts.backendPort}${safePath}`;
+}
+export function buildStaticFilePreviewUrl(filePath, options) {
+    if (!filePath)
+        return undefined;
+    const relativePath = filePath.replace(/^\/workspace\//, '').replace(/^\/+/, '');
+    const encodedPath = relativePath
+        .split('/')
+        .filter(Boolean)
+        .map((segment) => encodeURIComponent(segment))
+        .join('/');
+    return rewriteLocalhostUrl(3211, `/open?path=/workspace/${encodedPath}`, options);
+}
+export function buildStaticFileServicePath(filePath) {
+    const absolutePath = filePath.startsWith('/workspace')
+        ? filePath
+        : `/workspace/${filePath.replace(/^\/+/, '')}`;
+    const encodedPath = absolutePath
+        .split('/')
+        .filter(Boolean)
+        .map((segment) => encodeURIComponent(segment))
+        .join('/');
+    return `/open?path=/${encodedPath}`;
+}
+export function buildStaticFileLocalUrl(filePath) {
+    return `http://localhost:3211${buildStaticFileServicePath(filePath)}`;
+}
+export function getStaticFileHealthPath() {
+    return '/health';
+}
+export function buildStaticFileHealthPreviewUrl(options) {
+    return rewriteLocalhostUrl(3211, getStaticFileHealthPath(), options);
+}
+export function getProxyBaseUrl(port, subdomainOpts) {
+    return rewriteLocalhostUrl(port, '/', subdomainOpts);
+}
+export function isProxiableLocalhostUrl(url) {
+    const parsed = parseLocalhostUrl(url);
+    if (!parsed)
+        return false;
+    if (EXCLUDED_PORTS.has(parsed.port))
+        return false;
+    if (isAppRouteUrl(url))
+        return false;
+    return true;
+}
+export function proxyLocalhostUrl(url, subdomainOpts) {
+    if (!url)
+        return url;
+    const parsed = parseLocalhostUrl(url);
+    if (!parsed)
+        return url;
+    if (!isProxiableLocalhostUrl(parsed.originalUrl))
+        return parsed.originalUrl;
+    return rewriteLocalhostUrl(parsed.port, parsed.path, subdomainOpts);
+}
+export function toInternalUrl(port, path = '/') {
+    return `http://localhost:${port}${path}`;
+}
+const PATH_PROXY_URL_REGEX = /^https?:\/\/[^/]+\/v1\/p\/([^/]+)\/(\d+)(\/.*)?$/;
+export function parseSubdomainUrl(url) {
+    const subMatch = url.match(SUBDOMAIN_URL_REGEX);
+    if (subMatch) {
+        return {
+            port: parseInt(subMatch[1], 10),
+            sandboxId: subMatch[2],
+            backendPort: subMatch[3] ? parseInt(subMatch[3], 10) : 80,
+            path: subMatch[4] || '/',
+        };
+    }
+    const originMatch = url.match(PREVIEW_ORIGIN_URL_REGEX);
+    if (originMatch) {
+        let backendPort = 443;
+        try {
+            const parsed = new URL(url);
+            backendPort = parsed.port
+                ? parseInt(parsed.port, 10)
+                : parsed.protocol === 'https:'
+                    ? 443
+                    : 80;
+        }
+        catch {
+            return null;
+        }
+        return {
+            port: parseInt(originMatch[1], 10),
+            sandboxId: originMatch[2],
+            backendPort,
+            path: originMatch[4] || '/',
+        };
+    }
+    const pathMatch = url.match(PATH_PROXY_URL_REGEX);
+    if (pathMatch) {
+        try {
+            const parsed = new URL(url);
+            return {
+                port: parseInt(pathMatch[2], 10),
+                sandboxId: pathMatch[1],
+                backendPort: parseInt(parsed.port, 10) || (parsed.protocol === 'https:' ? 443 : 80),
+                path: pathMatch[3] || '/',
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+export function proxyUrlToInternal(proxyUrl) {
+    try {
+        const subdomain = parseSubdomainUrl(proxyUrl);
+        if (subdomain) {
+            return `http://localhost:${subdomain.port}${subdomain.path}`;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function isPreviewUrl(url) {
+    return (isSubdomainUrl(url)
+        || PREVIEW_ORIGIN_URL_REGEX.test(url)
+        || PATH_PROXY_URL_REGEX.test(url));
+}
+export function isInternalLocalhostUrl(url) {
+    try {
+        const { hostname, port } = new URL(url);
+        return (hostname === 'localhost' || hostname === '127.0.0.1') && port !== '';
+    }
+    catch {
+        return false;
+    }
+}
+const WEB_PROXY_PATH_PREFIX = '/web-proxy/';
+export function buildWebProxyUrl(targetUrl, subdomainOpts) {
+    try {
+        const parsed = new URL(targetUrl);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            return null;
+        const scheme = parsed.protocol.replace(':', '');
+        const proxyPath = `${WEB_PROXY_PATH_PREFIX}${scheme}/${parsed.host}${parsed.pathname}${parsed.search}${parsed.hash}`;
+        const kmPort = parseInt(SANDBOX_PORTS.BEEUNI_MASTER, 10);
+        const baseUrl = rewriteLocalhostUrl(kmPort, '/', subdomainOpts);
+        return `${baseUrl.replace(/\/$/, '')}${proxyPath}`;
+    }
+    catch {
+        return null;
+    }
+}
+export function parseWebProxyUrl(proxyUrl) {
+    try {
+        const url = new URL(proxyUrl);
+        const wpIdx = url.pathname.indexOf(WEB_PROXY_PATH_PREFIX);
+        if (wpIdx === -1)
+            return null;
+        const remainder = url.pathname.slice(wpIdx + WEB_PROXY_PATH_PREFIX.length);
+        const match = remainder.match(/^(https?)\/([\w.\-]+(?::\d+)?)(\/.*)?$/);
+        if (!match)
+            return null;
+        const scheme = match[1];
+        const host = match[2];
+        const path = match[3] || '/';
+        return `${scheme}://${host}${path}${url.search}${url.hash}`;
+    }
+    catch {
+        return null;
+    }
+}
+export function isWebProxyUrl(url) {
+    try {
+        return new URL(url).pathname.includes(WEB_PROXY_PATH_PREFIX);
+    }
+    catch {
+        return url.includes(WEB_PROXY_PATH_PREFIX);
+    }
+}
+export function isExternalUrl(rawUrl) {
+    if (!rawUrl)
+        return false;
+    const trimmed = rawUrl.trim();
+    if (/^https?:\/\/(?!localhost|127\.0\.0\.1)/i.test(trimmed))
+        return true;
+    if (/^[a-z0-9][\w.-]*\.[a-z]{2,}/i.test(trimmed))
+        return true;
+    return false;
+}
+export function normalizeExternalInput(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    if (/^https?:\/\//i.test(trimmed))
+        return trimmed;
+    if (/^[a-z0-9][\w.-]*\.[a-z]{2,}/i.test(trimmed))
+        return `https://${trimmed}`;
+    return null;
+}

package/dist/core/session/wake-escalation.d.ts

@@ -0,0 +1,37 @@
+export declare const WAKE_NO_PROGRESS_MS = 75000;
+export declare const WAKE_MAX_RESTARTS = 2;
+export declare const WAKE_ESCALATION_COOLDOWN_MS = 20000;
+export type WakeEscalationStep = 'retry-start' | 'restart';
+export type WakeEscalationDispatch = 'none' | WakeEscalationStep;
+export type WakeEscalationStatus = 'idle' | 'waking' | 'escalating' | 'exhausted';
+export interface WakeAttempt {
+    step: WakeEscalationStep;
+    atMs: number;
+}
+export interface WakeEscalationState {
+    status: WakeEscalationStatus;
+    dispatch: WakeEscalationDispatch;
+    fingerprint: string | null;
+    lastProgressAtMs: number | null;
+    lastDispatchAtMs: number | null;
+    attempts: readonly WakeAttempt[];
+    msSinceProgress: number;
+    settled: boolean;
+}
+export interface WakeObservation {
+    nowMs: number;
+    waking: boolean;
+    runtimeReachable: boolean;
+    progress: string;
+    serverGaveUp: boolean;
+}
+export interface WakeEscalationLimits {
+    noProgressMs?: number;
+    maxRestarts?: number;
+    cooldownMs?: number;
+}
+export declare function initialWakeEscalationState(): WakeEscalationState;
+export declare function wakeProgressFingerprint(parts: readonly (string | number | boolean | null | undefined)[]): string;
+export declare function advanceWakeEscalation(state: WakeEscalationState, observation: WakeObservation, limits?: WakeEscalationLimits): WakeEscalationState;
+export declare function wakeEscalationNote(state: WakeEscalationState): string | null;
+export declare function wakeEscalationAttemptSummary(state: WakeEscalationState): string | null;

package/dist/core/session/wake-escalation.js

@@ -0,0 +1,104 @@
+export const WAKE_NO_PROGRESS_MS = 75_000;
+export const WAKE_MAX_RESTARTS = 2;
+export const WAKE_ESCALATION_COOLDOWN_MS = 20_000;
+export function initialWakeEscalationState() {
+    return {
+        status: 'idle',
+        dispatch: 'none',
+        fingerprint: null,
+        lastProgressAtMs: null,
+        lastDispatchAtMs: null,
+        attempts: [],
+        msSinceProgress: 0,
+        settled: false,
+    };
+}
+export function wakeProgressFingerprint(parts) {
+    return parts.filter((part) => part !== null && part !== undefined).join('|');
+}
+function nextStep(attempts, maxRestarts) {
+    if (attempts.length === 0)
+        return 'retry-start';
+    const restarts = attempts.filter((attempt) => attempt.step === 'restart').length;
+    return restarts < maxRestarts ? 'restart' : null;
+}
+export function advanceWakeEscalation(state, observation, limits = {}) {
+    const noProgressMs = limits.noProgressMs ?? WAKE_NO_PROGRESS_MS;
+    const maxRestarts = limits.maxRestarts ?? WAKE_MAX_RESTARTS;
+    const cooldownMs = limits.cooldownMs ?? WAKE_ESCALATION_COOLDOWN_MS;
+    if (observation.runtimeReachable) {
+        return { ...initialWakeEscalationState(), settled: true };
+    }
+    if (!observation.waking) {
+        return { ...state, dispatch: 'none', fingerprint: null, lastProgressAtMs: null, msSinceProgress: 0 };
+    }
+    if (state.settled)
+        return { ...initialWakeEscalationState(), settled: true };
+    const previousProgressAtMs = state.lastProgressAtMs;
+    const first = previousProgressAtMs === null;
+    const changed = observation.progress !== state.fingerprint;
+    const lastProgressAtMs = previousProgressAtMs === null || changed ? observation.nowMs : previousProgressAtMs;
+    const msSinceProgress = Math.max(0, observation.nowMs - lastProgressAtMs);
+    const base = {
+        ...state,
+        dispatch: 'none',
+        fingerprint: observation.progress,
+        lastProgressAtMs,
+        msSinceProgress,
+        status: state.attempts.length > 0 ? 'escalating' : 'waking',
+    };
+    if (state.status === 'exhausted')
+        return { ...base, status: 'exhausted' };
+    const stalled = !first && !changed && msSinceProgress >= noProgressMs;
+    if (!observation.serverGaveUp && !stalled)
+        return base;
+    if (state.lastDispatchAtMs !== null &&
+        observation.nowMs - state.lastDispatchAtMs < cooldownMs) {
+        return base;
+    }
+    const step = nextStep(state.attempts, maxRestarts);
+    if (!step)
+        return { ...base, status: 'exhausted' };
+    return {
+        ...base,
+        status: 'escalating',
+        dispatch: step,
+        attempts: [...state.attempts, { step, atMs: observation.nowMs }],
+        lastDispatchAtMs: observation.nowMs,
+        lastProgressAtMs: observation.nowMs,
+        msSinceProgress: 0,
+    };
+}
+const STEP_VERB = {
+    'retry-start': 'retrying',
+    restart: 'restarting',
+};
+export function wakeEscalationNote(state) {
+    if (state.status !== 'escalating')
+        return null;
+    const last = state.attempts[state.attempts.length - 1];
+    if (!last)
+        return null;
+    return `Still waking — ${STEP_VERB[last.step]} the runtime (attempt ${state.attempts.length + 1})`;
+}
+function countWord(count) {
+    if (count === 1)
+        return 'once';
+    if (count === 2)
+        return 'twice';
+    return `${count} times`;
+}
+export function wakeEscalationAttemptSummary(state) {
+    if (state.status !== 'exhausted')
+        return null;
+    const restarts = state.attempts.filter((attempt) => attempt.step === 'restart').length;
+    const retried = state.attempts.some((attempt) => attempt.step === 'retry-start');
+    if (!retried && restarts === 0)
+        return null;
+    const parts = [];
+    if (retried)
+        parts.push('re-issuing the wake');
+    if (restarts > 0)
+        parts.push(`restarting the session ${countWord(restarts)}`);
+    return `Tried: ${parts.join(', then ')}.`;
+}

package/dist/core/session/wire-id-unwrap.d.ts

@@ -0,0 +1,2 @@
+export declare function absoluteWireIdClockAt(ms: number): bigint;
+export declare function unwrapWireIdClock(clock: bigint, anchor: bigint): bigint;