@selvakumaresra/specship 0.3.0 → 0.4.0

package/dist/designer/run-state.js

@@ -0,0 +1,353 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunStateObserver = exports.TURN_RPCS = exports.OMELETTE_TURN_SERVICE = void 0;
+exports.turnRpcFromUrl = turnRpcFromUrl;
+exports.observedRpcPathFromUrl = observedRpcPathFromUrl;
+exports.isTurnRpcUrl = isTurnRpcUrl;
+exports.classifyEvent = classifyEvent;
+const cdp_trace_1 = require("./cdp-trace");
+exports.OMELETTE_TURN_SERVICE = 'anthropic.omelette.api.v1alpha.OmeletteService';
+exports.TURN_RPCS = ['Chat', 'RenewTurn', 'ReleaseTurn'];
+function num(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+function eventWallMs(params) {
+    const syntheticTraceTs = num(params.ts);
+    if (syntheticTraceTs !== null)
+        return syntheticTraceTs;
+    const wallTime = num(params.wallTime);
+    return wallTime !== null ? wallTime * 1000 : null;
+}
+function requestId(params) {
+    return typeof params.requestId === 'string' ? params.requestId : undefined;
+}
+function turnRpcFromUrl(url) {
+    if (!url)
+        return null;
+    let path = url;
+    try {
+        path = new URL(url).pathname;
+    }
+    catch {
+        // Some tests pass path fragments directly.
+    }
+    const escapedService = exports.OMELETTE_TURN_SERVICE.replace(/\./g, '\\.');
+    const match = path.match(new RegExp(`(?:^|/)${escapedService}/(Chat|RenewTurn|ReleaseTurn)(?:$|[/?#])`));
+    if (!match?.[1])
+        return null;
+    return exports.TURN_RPCS.includes(match[1]) ? match[1] : null;
+}
+function observedRpcPathFromUrl(url) {
+    if (!url)
+        return null;
+    let path = url;
+    try {
+        path = new URL(url).pathname;
+    }
+    catch {
+        // Some tests pass path fragments directly.
+    }
+    const serviceIdx = path.indexOf(`${exports.OMELETTE_TURN_SERVICE}/`);
+    if (serviceIdx >= 0)
+        return path.slice(serviceIdx);
+    const idx = path.indexOf('OmeletteService/');
+    return idx >= 0 ? path.slice(idx) : null;
+}
+function isTurnRpcUrl(url) {
+    return turnRpcFromUrl(url) !== null;
+}
+function urlFromParams(method, params) {
+    if (typeof params.requestUrl === 'string')
+        return params.requestUrl;
+    if (typeof params.url === 'string')
+        return params.url;
+    if (method === 'Network.requestWillBeSent') {
+        const req = (0, cdp_trace_1.asRec)(params.request);
+        return typeof req.url === 'string' ? req.url : '';
+    }
+    if (method === 'Network.responseReceived') {
+        const resp = (0, cdp_trace_1.asRec)(params.response);
+        return typeof resp.url === 'string' ? resp.url : '';
+    }
+    return '';
+}
+function isCriticalRpc(rpc) {
+    return rpc === 'Chat' || rpc === 'RenewTurn';
+}
+function classifyEvent(method, rawParams, runStartTs) {
+    const params = (0, cdp_trace_1.asRec)(rawParams);
+    const wallMs = eventWallMs(params);
+    if (wallMs !== null && wallMs < runStartTs)
+        return null;
+    const url = urlFromParams(method, params);
+    const rpc = turnRpcFromUrl(url);
+    if (method === 'Network.requestWillBeSent') {
+        if (rpc === 'Chat')
+            return { kind: 'chat-open', requestId: requestId(params) };
+        if (rpc === 'RenewTurn')
+            return { kind: 'heartbeat', requestId: requestId(params) };
+        if (rpc === 'ReleaseTurn')
+            return { kind: 'release', requestId: requestId(params) };
+        return null;
+    }
+    if (method === 'Network.dataReceived' && rpc === 'Chat') {
+        return { kind: 'chat-chunk', requestId: requestId(params) };
+    }
+    if (method === 'Network.responseReceived') {
+        const response = (0, cdp_trace_1.asRec)(params.response);
+        const status = num(response.status);
+        if (status !== null && status >= 400 && isCriticalRpc(rpc)) {
+            return { kind: 'critical-error', rpc, status };
+        }
+        return null;
+    }
+    if (method === 'Network.loadingFailed' && isCriticalRpc(rpc)) {
+        return { kind: 'critical-error', rpc, status: 'failed' };
+    }
+    return null;
+}
+class RunStateObserver extends cdp_trace_1.CdpSession {
+    now;
+    currentState = 'idle';
+    runStartTs = 0;
+    lastActivity = 0;
+    priorRunSignals = 0;
+    terminalResult = null;
+    watchdog = null;
+    waiters = [];
+    requestUrls = new Map();
+    observedRpcPaths = new Set();
+    signalCounts = {
+        chatOpen: 0,
+        chatChunk: 0,
+        heartbeat: 0,
+        release: 0,
+        criticalError: 0,
+        observerLost: 0
+    };
+    closeCount = 0;
+    constructor(ws, target, opts = {}) {
+        super(ws, target, opts);
+        this.now = opts.now ?? (() => Date.now());
+    }
+    static async attach(opts = {}) {
+        if (typeof WebSocket === 'undefined')
+            return null;
+        try {
+            const { ws, target } = await RunStateObserver.connectTarget(opts);
+            const observer = new RunStateObserver(ws, target, opts);
+            await observer.start();
+            return observer;
+        }
+        catch {
+            return null;
+        }
+    }
+    async start() {
+        await this.enableDomains();
+    }
+    beginRun() {
+        if (this.terminalResult)
+            return;
+        this.runStartTs = this.now();
+        this.lastActivity = this.runStartTs;
+        this.priorRunSignals = 0;
+        this.requestUrls.clear();
+        this.observedRpcPaths.clear();
+        this.resetSignalCounts();
+        this.currentState = 'running';
+    }
+    get state() {
+        if (this.terminalResult)
+            return this.terminalResult.terminal;
+        return this.currentState;
+    }
+    awaitTerminal({ stallMs = 25_000, hardTimeoutMs = 20 * 60_000 } = {}) {
+        if (this.terminalResult)
+            return Promise.resolve(this.terminalResult);
+        this.armWatchdog(stallMs, hardTimeoutMs);
+        this.checkSilence(stallMs, hardTimeoutMs);
+        if (this.terminalResult)
+            return Promise.resolve(this.terminalResult);
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    close() {
+        this.clearWatchdog();
+        if (this.closeSocket())
+            this.closeCount++;
+    }
+    signalSummary() {
+        return {
+            ...this.signalCounts,
+            observedRpcPaths: [...this.observedRpcPaths].sort()
+        };
+    }
+    closeCountForTest() {
+        return this.closeCount;
+    }
+    consumeSignalForTest(signal) {
+        this.consumeSignal(signal);
+    }
+    socketGapForTest(detail = { reason: 'test' }) {
+        this.onSocketGap(detail);
+    }
+    tickForTest({ stallMs = 25_000, hardTimeoutMs = 20 * 60_000 } = {}) {
+        this.checkSilence(stallMs, hardTimeoutMs);
+    }
+    onEvent(method, rawParams, _sessionId) {
+        if (this.currentState === 'idle' && !this.terminalResult)
+            return;
+        const params = this.enrichParams(method, rawParams);
+        // Terminal events (responseReceived / loadingFailed) carry no `wallTime`, so
+        // classifyEvent's stale-timestamp guard cannot filter a prior turn's late
+        // failure. Only honor them when the request was first seen *this run* — its
+        // id is in `requestUrls`, which `enrichParams` populates at requestWillBeSent
+        // for events at/after `runStartTs`. Otherwise a stale 4xx for a pre-run RPC
+        // would read its own `response.url` and falsely latch BLOCKED.
+        if (method === 'Network.responseReceived' || method === 'Network.loadingFailed') {
+            const id = requestId(params);
+            if (!id || !this.requestUrls.has(id))
+                return;
+        }
+        const signal = classifyEvent(method, params, this.runStartTs);
+        if (signal)
+            this.consumeSignal(signal);
+    }
+    onSocketGap(_detail) {
+        // A one-shot ReleaseTurn fired during a CDP reconnect gap can't be recovered
+        // (CDP won't re-deliver events from the gap), so even a *successful* reconnect
+        // would leave an active run waiting out the hard timeout. Degrade to
+        // observer-lost immediately for an active run so the controller hands off to
+        // the HTML waiter. The observer-lost latch also stops the base reconnect loop
+        // (it sets `stopped`), which is what we want once we've handed off.
+        if (this.currentState === 'running' || this.currentState === 'stalled') {
+            this.consumeSignal({ kind: 'observer-lost' });
+        }
+    }
+    onSocketReconnectFailed() {
+        this.consumeSignal({ kind: 'observer-lost' });
+    }
+    enrichParams(method, rawParams) {
+        const params = { ...(0, cdp_trace_1.asRec)(rawParams) };
+        const id = requestId(params);
+        if (method === 'Network.requestWillBeSent' && id) {
+            const wallMs = eventWallMs(params);
+            if (wallMs !== null && wallMs < this.runStartTs)
+                return params;
+            const req = (0, cdp_trace_1.asRec)(params.request);
+            const url = typeof req.url === 'string' ? req.url : '';
+            if (url) {
+                this.requestUrls.set(id, url);
+                const rpcPath = observedRpcPathFromUrl(url);
+                if (rpcPath)
+                    this.observedRpcPaths.add(rpcPath);
+            }
+        }
+        else if (id && !params.requestUrl) {
+            const url = this.requestUrls.get(id);
+            if (url)
+                params.requestUrl = url;
+        }
+        return params;
+    }
+    consumeSignal(signal) {
+        if (this.terminalResult)
+            return;
+        this.countSignal(signal);
+        if (signal.kind === 'observer-lost') {
+            this.latch('observer-lost');
+            return;
+        }
+        if (this.currentState === 'idle')
+            return;
+        if (signal.kind === 'chat-open' || signal.kind === 'chat-chunk' || signal.kind === 'heartbeat') {
+            this.lastActivity = this.now();
+            this.priorRunSignals++;
+            this.currentState = 'running';
+            return;
+        }
+        if (signal.kind === 'release') {
+            if (this.priorRunSignals === 0)
+                return;
+            this.latch('finished');
+            return;
+        }
+        if (signal.kind === 'critical-error') {
+            this.latch('blocked', `${signal.rpc} ${signal.status === 'failed' ? 'failed' : `HTTP ${signal.status}`}`);
+        }
+    }
+    countSignal(signal) {
+        if (signal.kind === 'chat-open')
+            this.signalCounts.chatOpen++;
+        else if (signal.kind === 'chat-chunk')
+            this.signalCounts.chatChunk++;
+        else if (signal.kind === 'heartbeat')
+            this.signalCounts.heartbeat++;
+        else if (signal.kind === 'release')
+            this.signalCounts.release++;
+        else if (signal.kind === 'critical-error')
+            this.signalCounts.criticalError++;
+        else if (signal.kind === 'observer-lost')
+            this.signalCounts.observerLost++;
+    }
+    resetSignalCounts() {
+        this.signalCounts.chatOpen = 0;
+        this.signalCounts.chatChunk = 0;
+        this.signalCounts.heartbeat = 0;
+        this.signalCounts.release = 0;
+        this.signalCounts.criticalError = 0;
+        this.signalCounts.observerLost = 0;
+    }
+    checkSilence(stallMs, hardTimeoutMs) {
+        if (this.terminalResult || this.currentState === 'idle')
+            return;
+        const now = this.now();
+        const silence = now - this.lastActivity;
+        const elapsed = now - this.runStartTs;
+        if (silence > hardTimeoutMs) {
+            this.latch('timeout', `silent for ${silence}ms`);
+        }
+        else if (elapsed > hardTimeoutMs) {
+            // Absolute wall-clock cap. A run that keeps heartbeating (RenewTurn ~10s)
+            // but never releases never accumulates enough *silence* to time out — so
+            // without this it would hang indefinitely (worse than the old HTML waiter,
+            // which always had a true Date.now()-based budget). Bound total duration.
+            this.latch('timeout', `exceeded ${hardTimeoutMs}ms wall-clock budget (elapsed ${elapsed}ms)`);
+        }
+        else if (silence > stallMs) {
+            this.currentState = 'stalled';
+        }
+    }
+    armWatchdog(stallMs, hardTimeoutMs) {
+        if (this.watchdog)
+            return;
+        const intervalMs = Math.max(250, Math.min(1000, stallMs, hardTimeoutMs));
+        this.watchdog = setInterval(() => this.checkSilence(stallMs, hardTimeoutMs), intervalMs);
+    }
+    clearWatchdog() {
+        if (!this.watchdog)
+            return;
+        clearInterval(this.watchdog);
+        this.watchdog = null;
+    }
+    latch(terminal, reason) {
+        if (this.terminalResult)
+            return;
+        this.terminalResult = {
+            terminal,
+            // runStartTs stays 0 if the socket died before beginRun() ran; report 0
+            // elapsed rather than now()-0 (epoch millis), which would otherwise
+            // collapse the controller's HTML-fallback budget to ~1ms.
+            elapsedMs: this.runStartTs === 0 ? 0 : Math.max(0, this.now() - this.runStartTs),
+            ...(reason ? { reason } : {})
+        };
+        this.clearWatchdog();
+        this.close();
+        const waiters = this.waiters.splice(0);
+        for (const resolve of waiters)
+            resolve(this.terminalResult);
+    }
+}
+exports.RunStateObserver = RunStateObserver;

package/dist/designer/session-store.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSession = getSession;
+exports.upsertSession = upsertSession;
+exports.listSessions = listSessions;
+exports.appendHistory = appendHistory;
+exports.stateDir = stateDir;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const ROOT = process.env.DESIGNER_STATE_DIR || node_path_1.default.join(node_os_1.default.homedir(), '.designer');
+const SESSIONS_FILE = node_path_1.default.join(ROOT, 'sessions.json');
+function ensureRoot() {
+    node_fs_1.default.mkdirSync(ROOT, { recursive: true });
+}
+function readAll() {
+    ensureRoot();
+    if (!node_fs_1.default.existsSync(SESSIONS_FILE))
+        return {};
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(SESSIONS_FILE, 'utf8')) || {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeAll(data) {
+    ensureRoot();
+    node_fs_1.default.writeFileSync(SESSIONS_FILE, JSON.stringify(data, null, 2));
+}
+function getSession(key) {
+    return readAll()[key] || null;
+}
+function upsertSession(key, patch) {
+    const all = readAll();
+    const prev = all[key] || { key, createdAt: new Date().toISOString(), history: [] };
+    const next = { ...prev, ...patch, updatedAt: new Date().toISOString() };
+    all[key] = next;
+    writeAll(all);
+    return next;
+}
+function listSessions() {
+    return Object.values(readAll());
+}
+function appendHistory(key, entry) {
+    const all = readAll();
+    const prev = all[key] || { key, createdAt: new Date().toISOString(), history: [] };
+    prev.history = [...(prev.history || []), { ...entry, at: new Date().toISOString() }];
+    prev.updatedAt = new Date().toISOString();
+    all[key] = prev;
+    writeAll(all);
+    return prev;
+}
+function stateDir() {
+    return ROOT;
+}