@eidola.app/cli 0.2.0

package/shrine/shared/vessel-resolver.js

@@ -0,0 +1,135 @@
+import { join } from 'node:path';
+import { access } from 'node:fs/promises';
+import { loadEngramFromDirectory, resolveEidolaRuntimeConfig, } from '../../index.js';
+import { buildClipUrl, shouldLoopExpression, shouldReturnToIdle, vesselConfigFromYaml, } from './types.js';
+export class VesselResolver {
+    engramsDir;
+    vesselsDir;
+    activeEngramId = '';
+    loaded = null;
+    shrineConfig = null;
+    lastValidConfig = null;
+    constructor(options) {
+        this.engramsDir = options.engramsDir;
+        this.vesselsDir = options.vesselsDir;
+    }
+    getConfig() {
+        return this.shrineConfig ?? this.lastValidConfig;
+    }
+    async syncEngram(engramId) {
+        if (!engramId) {
+            return this.shrineConfig ?? this.lastValidConfig;
+        }
+        if (engramId === this.activeEngramId && this.shrineConfig) {
+            return this.shrineConfig;
+        }
+        try {
+            const directory = join(this.engramsDir, engramId);
+            const loaded = await loadEngramFromDirectory(directory);
+            this.loaded = loaded;
+            this.activeEngramId = engramId;
+            this.shrineConfig = vesselConfigFromYaml(loaded.vessel, loaded.vessel.pack);
+            this.lastValidConfig = this.shrineConfig;
+            return this.shrineConfig;
+        }
+        catch (error) {
+            console.error('[eidola-shrine] invalid engram; keeping last valid vessel', error);
+            return this.lastValidConfig;
+        }
+    }
+    async buildStatePayload(broadcast, source = 'socket') {
+        const config = (await this.syncEngram(broadcast.engram_id)) ?? this.defaultConfig();
+        if (!config) {
+            return null;
+        }
+        const clip = await this.resolveClipForConfig(config, broadcast.expression);
+        const loop = shouldLoopExpression(broadcast.state, config.idleLoops);
+        const returnToIdle = shouldReturnToIdle(broadcast.state);
+        return {
+            broadcast: {
+                protocol_version: broadcast.protocol_version,
+                ts: broadcast.ts,
+                state: broadcast.state,
+                engram_id: broadcast.engram_id,
+                expression: broadcast.expression,
+                ...(broadcast.visual_state !== undefined
+                    ? { visual_state: broadcast.visual_state }
+                    : {}),
+                ...(broadcast.tool !== undefined ? { tool: broadcast.tool } : {}),
+            },
+            clipUrl: buildClipUrl(config.pack, clip),
+            loop,
+            returnToIdle,
+            source,
+        };
+    }
+    defaultConfig() {
+        if (this.lastValidConfig) {
+            return this.lastValidConfig;
+        }
+        return {
+            rendererType: 'lottie',
+            pack: 'camina-v1',
+            idleClip: 'idle.json',
+            crossfadeMs: 300,
+            idleLoops: true,
+            approvalIdleMs: 3000,
+            successHoldMs: 3000,
+        };
+    }
+    async buildIdlePayload(broadcast) {
+        const config = (await this.syncEngram(broadcast.engram_id)) ?? this.defaultConfig();
+        if (!config) {
+            return null;
+        }
+        const clip = await this.resolveClipForConfig(config, config.idleClip);
+        return {
+            broadcast: {
+                protocol_version: broadcast.protocol_version,
+                ts: broadcast.ts,
+                state: 'idle',
+                engram_id: broadcast.engram_id,
+                expression: clip,
+            },
+            clipUrl: buildClipUrl(config.pack, clip),
+            loop: config.idleLoops,
+            returnToIdle: false,
+            source: 'fallback',
+        };
+    }
+    async resolveClipForConfig(config, clip) {
+        if (config.rendererType === 'component') {
+            return clip;
+        }
+        return this.resolveClip(config.pack, clip, config.idleClip);
+    }
+    async resolveClip(pack, clip, idleClip) {
+        const primary = join(this.vesselsDir, pack, clip);
+        if (await fileExists(primary)) {
+            return clip;
+        }
+        console.error(`[eidola-shrine] missing clip "${clip}"; falling back to idle`);
+        const fallback = join(this.vesselsDir, pack, idleClip);
+        if (await fileExists(fallback)) {
+            return idleClip;
+        }
+        return idleClip;
+    }
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function createDefaultResolver() {
+    const runtime = resolveEidolaRuntimeConfig();
+    return new VesselResolver({
+        engramsDir: runtime.engramsDir,
+        vesselsDir: runtime.vesselsDir,
+    });
+}
+//# sourceMappingURL=vessel-resolver.js.map

package/shrine/shared/vessel-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vessel-resolver.js","sourceRoot":"","sources":["../../src/shared/vessel-resolver.ts"],"names":[],"mappings":"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"}

package/shrine/vendor/mcp.d.ts

@@ -0,0 +1,3 @@
+/** Published eidola package resolves MCP from dist/index.js; dev uses workspace eidola. */
+export * from '@eidola.app/cli';
+//# sourceMappingURL=mcp.d.ts.map

package/shrine/vendor/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/vendor/mcp.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,cAAc,iBAAiB,CAAC"}

package/shrine/vendor/mcp.js

@@ -0,0 +1,3 @@
+/** Published eidola package resolves MCP from dist/index.js; dev uses workspace eidola. */
+export * from '@eidola.app/cli';
+//# sourceMappingURL=mcp.js.map

package/shrine/vendor/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../src/vendor/mcp.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,cAAc,iBAAiB,CAAC"}

package/socket/expression.d.ts

@@ -0,0 +1,3 @@
+import type { VesselConfig } from '../engram/types.js';
+export declare function resolveExpressionClip(state: string, vessel: VesselConfig | null): string;
+//# sourceMappingURL=expression.d.ts.map

package/socket/expression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression.d.ts","sourceRoot":"","sources":["../../src/socket/expression.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAYvD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,GAAG,MAAM,CAsBxF"}

package/socket/expression.js

@@ -0,0 +1,28 @@
+import { isWorkingClusterState } from '../vendor/tool-state.js';
+const IDLE_CLIP = 'idle.json';
+function lookupExpression(state, vessel) {
+    if (vessel.type === 'component' && vessel.fallback) {
+        return vessel.fallback.expressions[state];
+    }
+    return vessel.expressions[state];
+}
+export function resolveExpressionClip(state, vessel) {
+    if (!vessel) {
+        return IDLE_CLIP;
+    }
+    const direct = lookupExpression(state, vessel);
+    if (direct) {
+        return direct;
+    }
+    if (isWorkingClusterState(state) && state !== 'thinking') {
+        const workingClip = lookupExpression('working', vessel);
+        if (workingClip) {
+            return workingClip;
+        }
+    }
+    if (vessel.type === 'component' && vessel.fallback) {
+        return vessel.fallback.expressions.idle ?? IDLE_CLIP;
+    }
+    return vessel.expressions.idle ?? IDLE_CLIP;
+}
+//# sourceMappingURL=expression.js.map

package/socket/expression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression.js","sourceRoot":"","sources":["../../src/socket/expression.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,MAAM,SAAS,GAAG,WAAW,CAAC;AAE9B,SAAS,gBAAgB,CAAC,KAAa,EAAE,MAAoB;IAC3D,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACnD,OAAO,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAa,EAAE,MAA2B;IAC9E,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC/C,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,qBAAqB,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;QACzD,MAAM,WAAW,GAAG,gBAAgB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACxD,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,WAAW,CAAC;QACrB,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACnD,OAAO,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,SAAS,CAAC;IACvD,CAAC;IAED,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,IAAI,SAAS,CAAC;AAC9C,CAAC"}

package/socket/protocol.d.ts

@@ -0,0 +1,16 @@
+import { type StateBroadcast, type StateInboundEvent, type Surface, VESSEL_STATES } from './types.js';
+export interface NormalizedInbound {
+    event: StateInboundEvent;
+    protocolMismatch: boolean;
+    unknownState: boolean;
+    normalizedState: string;
+}
+export declare function parseInboundLine(line: string): StateInboundEvent | null;
+export declare function normalizeInbound(event: StateInboundEvent): NormalizedInbound;
+export declare function isKnownVesselState(state: string): state is (typeof VESSEL_STATES)[number];
+export declare function createBroadcast(state: string, engramId: string, expression: string, ts?: number, tool?: string, visualState?: string): StateBroadcast;
+export declare function serializeBroadcast(broadcast: StateBroadcast): string;
+export declare function createInboundEvent(state: string, surface: Surface, ts?: number): StateInboundEvent;
+export declare function serializeInbound(event: StateInboundEvent): string;
+export declare function isValidSurface(value: string): value is Surface;
+//# sourceMappingURL=protocol.d.ts.map

package/socket/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/socket/protocol.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,OAAO,EACZ,aAAa,EACd,MAAM,YAAY,CAAC;AAapB,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,iBAAiB,CAAC;IACzB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAmBvE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,GAAG,iBAAiB,CAe5E;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAEzF;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,EAAE,GAAE,MAAmB,EACvB,IAAI,CAAC,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,GACnB,cAAc,CAUhB;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,cAAc,GAAG,MAAM,CAEpE;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,EAChB,EAAE,GAAE,MAAmB,GACtB,iBAAiB,CAOnB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAEjE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,OAAO,CAE9D"}

package/socket/protocol.js

@@ -0,0 +1,75 @@
+import { normalizeVesselState, refineGenericWorkingState } from '../vendor/tool-state.js';
+import { z } from 'zod';
+import { STATE_PROTOCOL_VERSION, SURFACES, VESSEL_STATES, } from './types.js';
+const surfaceSchema = z.enum(SURFACES);
+const inboundSchema = z.object({
+    protocol_version: z.string(),
+    ts: z.number(),
+    surface: surfaceSchema,
+    state: z.string(),
+    tool: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export function parseInboundLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    const result = inboundSchema.safeParse(parsed);
+    if (!result.success) {
+        return null;
+    }
+    return result.data;
+}
+export function normalizeInbound(event) {
+    const protocolMismatch = event.protocol_version !== STATE_PROTOCOL_VERSION;
+    const refinedState = normalizeVesselState(refineGenericWorkingState(event.state, event.tool));
+    const knownState = isKnownVesselState(refinedState);
+    const unknownState = !knownState;
+    const normalizedState = protocolMismatch || unknownState ? 'idle' : refinedState;
+    return {
+        event,
+        protocolMismatch,
+        unknownState,
+        normalizedState,
+    };
+}
+export function isKnownVesselState(state) {
+    return VESSEL_STATES.includes(state);
+}
+export function createBroadcast(state, engramId, expression, ts = Date.now(), tool, visualState) {
+    return {
+        protocol_version: STATE_PROTOCOL_VERSION,
+        ts,
+        state,
+        engram_id: engramId,
+        expression,
+        ...(visualState !== undefined && visualState !== state ? { visual_state: visualState } : {}),
+        ...(tool !== undefined ? { tool } : {}),
+    };
+}
+export function serializeBroadcast(broadcast) {
+    return `${JSON.stringify(broadcast)}\n`;
+}
+export function createInboundEvent(state, surface, ts = Date.now()) {
+    return {
+        protocol_version: STATE_PROTOCOL_VERSION,
+        ts,
+        surface,
+        state,
+    };
+}
+export function serializeInbound(event) {
+    return `${JSON.stringify(event)}\n`;
+}
+export function isValidSurface(value) {
+    return SURFACES.includes(value);
+}
+//# sourceMappingURL=protocol.js.map

package/socket/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/socket/protocol.ts"],"names":[],"mappings":"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"}

package/socket/server.d.ts

@@ -0,0 +1,22 @@
+import type { SessionState } from '../session/state.js';
+import { type StateBroadcast, type StateSocketConfig, type Surface } from './types.js';
+export interface StateSocketListenResult {
+    host: string;
+    port: number;
+    /** False when port already owned (e.g. another eidola-mcp instance). MCP tools still run. */
+    listening: boolean;
+}
+export interface StateSocketServer {
+    start(): Promise<StateSocketListenResult>;
+    close(): Promise<void>;
+    isListening(): boolean;
+    broadcastState(input: {
+        state: string;
+        surface?: Surface;
+        tool?: string;
+        metadata?: Record<string, unknown>;
+    }): StateBroadcast;
+    getBuffer(): readonly StateBroadcast[];
+}
+export declare function createStateSocketServer(session: SessionState, config?: StateSocketConfig): StateSocketServer;
+//# sourceMappingURL=server.d.ts.map

package/socket/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/socket/server.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAUxD,OAAO,EAIL,KAAK,cAAc,EAEnB,KAAK,iBAAiB,EACtB,KAAK,OAAO,EACb,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC1C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,WAAW,IAAI,OAAO,CAAC;IACvB,cAAc,CAAC,KAAK,EAAE;QACpB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GAAG,cAAc,CAAC;IACnB,SAAS,IAAI,SAAS,cAAc,EAAE,CAAC;CACxC;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,YAAY,EACrB,MAAM,GAAE,iBAAsB,GAC7B,iBAAiB,CAkOnB"}

package/socket/server.js

@@ -0,0 +1,184 @@
+import { connect, createServer } from 'node:net';
+import { resolveVisualState } from '../vendor/tool-state.js';
+import { resolveExpressionClip } from './expression.js';
+import { createBroadcast, createInboundEvent, normalizeInbound, parseInboundLine, serializeBroadcast, serializeInbound, } from './protocol.js';
+import { DEFAULT_STATE_BUFFER_SIZE, DEFAULT_STATE_SOCKET_PORT, STATE_SOCKET_HOST, } from './types.js';
+import { VisualTurnTracker } from './visual-turn.js';
+export function createStateSocketServer(session, config = {}) {
+    const host = config.host ?? STATE_SOCKET_HOST;
+    const requestedPort = config.port ?? DEFAULT_STATE_SOCKET_PORT;
+    const bufferSize = config.bufferSize ?? DEFAULT_STATE_BUFFER_SIZE;
+    const warn = config.onWarn ?? defaultWarn;
+    const onReassertVessel = config.onReassertVessel;
+    let server = null;
+    let listening = false;
+    const clients = new Set();
+    const buffer = [];
+    const pendingLines = new WeakMap();
+    const visualTurn = new VisualTurnTracker();
+    const pushBuffer = (broadcast) => {
+        buffer.push(broadcast);
+        while (buffer.length > bufferSize) {
+            buffer.shift();
+        }
+    };
+    const writeBroadcast = (socket, broadcast) => {
+        if (socket.destroyed || !socket.writable) {
+            return;
+        }
+        socket.write(serializeBroadcast(broadcast));
+    };
+    const emitBroadcast = (broadcast) => {
+        pushBuffer(broadcast);
+        for (const client of clients) {
+            writeBroadcast(client, broadcast);
+        }
+    };
+    const buildBroadcast = (state, ts, tool, firstToolStarted = false) => {
+        const active = session.getActive();
+        const engramId = active?.engram.id ?? '';
+        const visualState = resolveVisualState({ state, firstToolStarted });
+        const expression = resolveExpressionClip(visualState, active?.vessel ?? null);
+        return createBroadcast(state, engramId, expression, ts ?? Date.now(), tool, visualState);
+    };
+    const processInbound = (event) => {
+        const normalized = normalizeInbound(event);
+        if (normalized.protocolMismatch) {
+            warn(`state socket protocol_version mismatch: expected ${event.protocol_version}; falling back to idle`);
+        }
+        if (normalized.unknownState) {
+            warn(`state socket unknown state: ${event.state}; falling back to idle`);
+        }
+        if (normalized.normalizedState === 'responding' || normalized.normalizedState === 'success') {
+            session.recordAssistantTurn();
+        }
+        const firstToolStarted = visualTurn.update(normalized.normalizedState, event.metadata);
+        return buildBroadcast(normalized.normalizedState, event.ts, event.tool, firstToolStarted);
+    };
+    const shouldReassertVessel = (event) => {
+        return event.metadata?.reassert_vessel === true && session.getActive() !== null;
+    };
+    const handleClientData = (socket, chunk) => {
+        const existing = pendingLines.get(socket) ?? '';
+        const combined = existing + chunk.toString('utf8');
+        const lines = combined.split('\n');
+        const pending = lines.pop() ?? '';
+        pendingLines.set(socket, pending);
+        for (const line of lines) {
+            const event = parseInboundLine(line);
+            if (!event) {
+                if (line.trim()) {
+                    warn('state socket ignored malformed inbound line');
+                }
+                continue;
+            }
+            void (async () => {
+                if (onReassertVessel && shouldReassertVessel(event)) {
+                    try {
+                        await onReassertVessel();
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        warn(`vessel reassert failed: ${message}`);
+                    }
+                }
+                const broadcast = processInbound(event);
+                emitBroadcast(broadcast);
+            })();
+        }
+    };
+    const attachClient = (socket) => {
+        clients.add(socket);
+        for (const replay of buffer) {
+            writeBroadcast(socket, replay);
+        }
+        socket.on('data', (chunk) => handleClientData(socket, chunk));
+        socket.on('close', () => clients.delete(socket));
+        socket.on('error', () => clients.delete(socket));
+    };
+    const forwardStateToExistingSocket = (state, surface = 'manual') => {
+        const event = createInboundEvent(state, surface);
+        const socket = connect({ host, port: requestedPort }, () => {
+            socket.write(serializeInbound(event));
+            socket.end();
+        });
+        socket.on('error', () => {
+            /* silent — overlay bridge degrades without socket */
+        });
+    };
+    return {
+        isListening() {
+            return listening;
+        },
+        async start() {
+            if (server && listening) {
+                const address = server.address();
+                if (address && typeof address === 'object') {
+                    return { host: address.address, port: address.port, listening: true };
+                }
+            }
+            server = createServer((socket) => attachClient(socket));
+            let addrInUse = false;
+            await new Promise((resolve, reject) => {
+                server.once('error', (error) => {
+                    if (error.code === 'EADDRINUSE') {
+                        addrInUse = true;
+                        server?.close();
+                        server = null;
+                        listening = false;
+                        resolve();
+                        return;
+                    }
+                    reject(error);
+                });
+                server.listen(requestedPort, host, () => resolve());
+            });
+            if (addrInUse) {
+                warn(`state socket ${host}:${requestedPort} already in use — MCP tools active; ` +
+                    'stop other eidola-mcp processes so one instance owns the socket and overlay sync.');
+                return { host, port: requestedPort, listening: false };
+            }
+            const address = server.address();
+            if (!address || typeof address !== 'object') {
+                throw new Error('State socket failed to bind');
+            }
+            if (address.address !== '127.0.0.1' && address.address !== '::1') {
+                throw new Error(`State socket must bind localhost only; got ${address.address}`);
+            }
+            listening = true;
+            return { host: address.address, port: address.port, listening: true };
+        },
+        async close() {
+            for (const client of clients) {
+                client.destroy();
+            }
+            clients.clear();
+            if (!server) {
+                return;
+            }
+            await new Promise((resolve, reject) => {
+                server.close((error) => (error ? reject(error) : resolve()));
+            });
+            server = null;
+            listening = false;
+        },
+        broadcastState(input) {
+            const firstToolStarted = visualTurn.update(input.state, input.metadata);
+            const broadcast = buildBroadcast(input.state, undefined, input.tool, firstToolStarted);
+            if (listening) {
+                emitBroadcast(broadcast);
+            }
+            else {
+                forwardStateToExistingSocket(input.state, input.surface ?? 'manual');
+            }
+            return broadcast;
+        },
+        getBuffer() {
+            return [...buffer];
+        },
+    };
+}
+function defaultWarn(message) {
+    console.error('[eidola-state-socket]', message);
+}
+//# sourceMappingURL=server.js.map

package/socket/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/socket/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAA4B,MAAM,UAAU,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,iBAAiB,GAKlB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAsBrD,MAAM,UAAU,uBAAuB,CACrC,OAAqB,EACrB,SAA4B,EAAE;IAE9B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,iBAAiB,CAAC;IAC9C,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,IAAI,yBAAyB,CAAC;IAC/D,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,yBAAyB,CAAC;IAClE,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,IAAI,WAAW,CAAC;IAC1C,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAEjD,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,MAAM,MAAM,GAAqB,EAAE,CAAC;IACpC,MAAM,YAAY,GAAG,IAAI,OAAO,EAAkB,CAAC;IACnD,MAAM,UAAU,GAAG,IAAI,iBAAiB,EAAE,CAAC;IAE3C,MAAM,UAAU,GAAG,CAAC,SAAyB,EAAQ,EAAE;QACrD,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvB,OAAO,MAAM,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;YAClC,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,cAAc,GAAG,CAAC,MAAc,EAAE,SAAyB,EAAQ,EAAE;QACzE,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACzC,OAAO;QACT,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC;IAEF,MAAM,aAAa,GAAG,CAAC,SAAyB,EAAQ,EAAE;QACxD,UAAU,CAAC,SAAS,CAAC,CAAC;QACtB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,cAAc,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QACpC,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,cAAc,GAAG,CACrB,KAAa,EACb,EAAW,EACX,IAAa,EACb,gBAAgB,GAAG,KAAK,EACR,EAAE;QAClB,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC;QACzC,MAAM,WAAW,GAAG,kBAAkB,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC,CAAC;QACpE,MAAM,UAAU,GAAG,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC;QAC9E,OAAO,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IAC3F,CAAC,CAAC;IAEF,MAAM,cAAc,GAAG,CAAC,KAAwB,EAAkB,EAAE;QAClE,MAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAE3C,IAAI,UAAU,CAAC,gBAAgB,EAAE,CAAC;YAChC,IAAI,CACF,oDAAoD,KAAK,CAAC,gBAAgB,wBAAwB,CACnG,CAAC;QACJ,CAAC;QAED,IAAI,UAAU,CAAC,YAAY,EAAE,CAAC;YAC5B,IAAI,CAAC,+BAA+B,KAAK,CAAC,KAAK,wBAAwB,CAAC,CAAC;QAC3E,CAAC;QAED,IAAI,UAAU,CAAC,eAAe,KAAK,YAAY,IAAI,UAAU,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;YAC5F,OAAO,CAAC,mBAAmB,EAAE,CAAC;QAChC,CAAC;QAED,MAAM,gBAAgB,GAAG,UAAU,CAAC,MAAM,CACxC,UAAU,CAAC,eAAe,EAC1B,KAAK,CAAC,QAAQ,CACf,CAAC;QAEF,OAAO,cAAc,CACnB,UAAU,CAAC,eAAe,EAC1B,KAAK,CAAC,EAAE,EACR,KAAK,CAAC,IAAI,EACV,gBAAgB,CACjB,CAAC;IACJ,CAAC,CAAC;IAEF,MAAM,oBAAoB,GAAG,CAAC,KAAwB,EAAW,EAAE;QACjE,OAAO,KAAK,CAAC,QAAQ,EAAE,eAAe,KAAK,IAAI,IAAI,OAAO,CAAC,SAAS,EAAE,KAAK,IAAI,CAAC;IAClF,CAAC,CAAC;IAEF,MAAM,gBAAgB,GAAG,CAAC,MAAc,EAAE,KAAa,EAAQ,EAAE;QAC/D,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAChD,MAAM,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;QAClC,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAElC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,IAAI,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;oBAChB,IAAI,CAAC,6CAA6C,CAAC,CAAC;gBACtD,CAAC;gBACD,SAAS;YACX,CAAC;YAED,KAAK,CAAC,KAAK,IAAI,EAAE;gBACf,IAAI,gBAAgB,IAAI,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;oBACpD,IAAI,CAAC;wBACH,MAAM,gBAAgB,EAAE,CAAC;oBAC3B,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;wBACvE,IAAI,CAAC,2BAA2B,OAAO,EAAE,CAAC,CAAC;oBAC7C,CAAC;gBACH,CAAC;gBAED,MAAM,SAAS,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;gBACxC,aAAa,CAAC,SAAS,CAAC,CAAC;YAC3B,CAAC,CAAC,EAAE,CAAC;QACP,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,YAAY,GAAG,CAAC,MAAc,EAAQ,EAAE;QAC5C,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAEpB,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;YAC5B,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,CAAC;QAED,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;QAC9D,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACjD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC;IAEF,MAAM,4BAA4B,GAAG,CAAC,KAAa,EAAE,UAAmB,QAAQ,EAAQ,EAAE;QACxF,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,GAAG,EAAE;YACzD,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC;YACtC,MAAM,CAAC,GAAG,EAAE,CAAC;QACf,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACtB,qDAAqD;QACvD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,OAAO;QACL,WAAW;YACT,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,KAAK,CAAC,KAAK;YACT,IAAI,MAAM,IAAI,SAAS,EAAE,CAAC;gBACxB,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;gBACjC,IAAI,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;oBAC3C,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;gBACxE,CAAC;YACH,CAAC;YAED,MAAM,GAAG,YAAY,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;YAExD,IAAI,SAAS,GAAG,KAAK,CAAC;YACtB,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC1C,MAAO,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAA4B,EAAE,EAAE;oBACrD,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;wBAChC,SAAS,GAAG,IAAI,CAAC;wBACjB,MAAM,EAAE,KAAK,EAAE,CAAC;wBAChB,MAAM,GAAG,IAAI,CAAC;wBACd,SAAS,GAAG,KAAK,CAAC;wBAClB,OAAO,EAAE,CAAC;wBACV,OAAO;oBACT,CAAC;oBACD,MAAM,CAAC,KAAK,CAAC,CAAC;gBAChB,CAAC,CAAC,CAAC;gBACH,MAAO,CAAC,MAAM,CAAC,aAAa,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;YACvD,CAAC,CAAC,CAAC;YAEH,IAAI,SAAS,EAAE,CAAC;gBACd,IAAI,CACF,gBAAgB,IAAI,IAAI,aAAa,sCAAsC;oBACzE,mFAAmF,CACtF,CAAC;gBACF,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;YACzD,CAAC;YAED,MAAM,OAAO,GAAG,MAAO,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAC5C,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;YACjD,CAAC;YAED,IAAI,OAAO,CAAC,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;gBACjE,MAAM,IAAI,KAAK,CAAC,8CAA8C,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;YACnF,CAAC;YAED,SAAS,GAAG,IAAI,CAAC;YACjB,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QACxE,CAAC;QAED,KAAK,CAAC,KAAK;YACT,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,CAAC;YACD,OAAO,CAAC,KAAK,EAAE,CAAC;YAEhB,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO;YACT,CAAC;YAED,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC1C,MAAO,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAChE,CAAC,CAAC,CAAC;YACH,MAAM,GAAG,IAAI,CAAC;YACd,SAAS,GAAG,KAAK,CAAC;QACpB,CAAC;QAED,cAAc,CAAC,KAAK;YAClB,MAAM,gBAAgB,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;YACxE,MAAM,SAAS,GAAG,cAAc,CAC9B,KAAK,CAAC,KAAK,EACX,SAAS,EACT,KAAK,CAAC,IAAI,EACV,gBAAgB,CACjB,CAAC;YACF,IAAI,SAAS,EAAE,CAAC;gBACd,aAAa,CAAC,SAAS,CAAC,CAAC;YAC3B,CAAC;iBAAM,CAAC;gBACN,4BAA4B,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,IAAI,QAAQ,CAAC,CAAC;YACvE,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,SAAS;YACP,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,OAAe;IAClC,OAAO,CAAC,KAAK,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAC;AAClD,CAAC"}

package/socket/types.d.ts

@@ -0,0 +1,35 @@
+export declare const STATE_PROTOCOL_VERSION = "1.0";
+export declare const STATE_SOCKET_HOST = "127.0.0.1";
+export declare const DEFAULT_STATE_SOCKET_PORT = 9742;
+export declare const DEFAULT_STATE_BUFFER_SIZE = 32;
+export declare const SURFACES: readonly ["cursor", "claude-code", "claude-chat", "cowork", "manual"];
+export type Surface = (typeof SURFACES)[number];
+export declare const VESSEL_STATES: readonly ["idle", "thinking", "waiting", "working", "searching", "writing", "responding", "success", "error", "attention"];
+export type VesselState = (typeof VESSEL_STATES)[number];
+export interface StateInboundEvent {
+    protocol_version: string;
+    ts: number;
+    surface: Surface;
+    state: string;
+    tool?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface StateBroadcast {
+    protocol_version: string;
+    ts: number;
+    state: string;
+    engram_id: string;
+    expression: string;
+    /** Visual tier for renderer playback when it differs from semantic `state`. */
+    visual_state?: string;
+    tool?: string;
+}
+export interface StateSocketConfig {
+    host?: string;
+    port?: number;
+    bufferSize?: number;
+    onWarn?: (message: string) => void;
+    /** Reload the active Engram when hooks request reassert and a session is already bound. */
+    onReassertVessel?: () => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/socket/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/socket/types.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,QAAQ,CAAC;AAE5C,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,eAAO,MAAM,QAAQ,uEAAwE,CAAC;AAE9F,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhD,eAAO,MAAM,aAAa,4HAWhB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,2FAA2F;IAC3F,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC"}

package/socket/types.js

@@ -0,0 +1,18 @@
+export const STATE_PROTOCOL_VERSION = '1.0';
+export const STATE_SOCKET_HOST = '127.0.0.1';
+export const DEFAULT_STATE_SOCKET_PORT = 9742;
+export const DEFAULT_STATE_BUFFER_SIZE = 32;
+export const SURFACES = ['cursor', 'claude-code', 'claude-chat', 'cowork', 'manual'];
+export const VESSEL_STATES = [
+    'idle',
+    'thinking',
+    'waiting',
+    'working',
+    'searching',
+    'writing',
+    'responding',
+    'success',
+    'error',
+    'attention',
+];
+//# sourceMappingURL=types.js.map

package/socket/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/socket/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,sBAAsB,GAAG,KAAK,CAAC;AAE5C,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAE7C,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC;AAE9C,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAE5C,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAI9F,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,MAAM;IACN,UAAU;IACV,SAAS;IACT,SAAS;IACT,WAAW;IACX,SAAS;IACT,YAAY;IACZ,SAAS;IACT,OAAO;IACP,WAAW;CACH,CAAC"}

package/socket/visual-turn.d.ts

@@ -0,0 +1,8 @@
+/** Tracks `firstToolStarted` for visual tier resolution on the state socket. */
+export declare class VisualTurnTracker {
+    private firstToolStarted;
+    getFirstToolStarted(): boolean;
+    reset(): void;
+    update(state: string, metadata?: Record<string, unknown>): boolean;
+}
+//# sourceMappingURL=visual-turn.d.ts.map

package/socket/visual-turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-turn.d.ts","sourceRoot":"","sources":["../../src/socket/visual-turn.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAIhF,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,gBAAgB,CAAS;IAEjC,mBAAmB,IAAI,OAAO;IAI9B,KAAK,IAAI,IAAI;IAIb,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO;CAanE"}

package/socket/visual-turn.js

@@ -0,0 +1,27 @@
+/** Tracks `firstToolStarted` for visual tier resolution on the state socket. */
+const TOOL_CLUSTER_STATES = new Set(['searching', 'writing', 'working']);
+export class VisualTurnTracker {
+    firstToolStarted = false;
+    getFirstToolStarted() {
+        return this.firstToolStarted;
+    }
+    reset() {
+        this.firstToolStarted = false;
+    }
+    update(state, metadata) {
+        if (metadata?.first_tool_started === true) {
+            this.firstToolStarted = true;
+        }
+        else if (metadata?.first_tool_started === false) {
+            this.firstToolStarted = false;
+        }
+        else if (state === 'idle' || state === 'success') {
+            this.firstToolStarted = false;
+        }
+        else if (TOOL_CLUSTER_STATES.has(state)) {
+            this.firstToolStarted = true;
+        }
+        return this.firstToolStarted;
+    }
+}
+//# sourceMappingURL=visual-turn.js.map

package/socket/visual-turn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-turn.js","sourceRoot":"","sources":["../../src/socket/visual-turn.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;AAEzE,MAAM,OAAO,iBAAiB;IACpB,gBAAgB,GAAG,KAAK,CAAC;IAEjC,mBAAmB;QACjB,OAAO,IAAI,CAAC,gBAAgB,CAAC;IAC/B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,gBAAgB,GAAG,KAAK,CAAC;IAChC,CAAC;IAED,MAAM,CAAC,KAAa,EAAE,QAAkC;QACtD,IAAI,QAAQ,EAAE,kBAAkB,KAAK,IAAI,EAAE,CAAC;YAC1C,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAC/B,CAAC;aAAM,IAAI,QAAQ,EAAE,kBAAkB,KAAK,KAAK,EAAE,CAAC;YAClD,IAAI,CAAC,gBAAgB,GAAG,KAAK,CAAC;QAChC,CAAC;aAAM,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACnD,IAAI,CAAC,gBAAgB,GAAG,KAAK,CAAC;QAChC,CAAC;aAAM,IAAI,mBAAmB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1C,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAC/B,CAAC;QAED,OAAO,IAAI,CAAC,gBAAgB,CAAC;IAC/B,CAAC;CACF"}