@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/runtime/remote/reconnect.js

@@ -0,0 +1,242 @@
+/**
+ * Remote Substrate — Reconnect Engine
+ *
+ * Implements reconnect with handshake tokens, epoch tracking,
+ * replay from last acknowledged offset, and idempotent command submission.
+ *
+ * The reconnect engine drives the transport state machine:
+ *   disconnected → initializing → authenticating → connected → syncing → degraded
+ *   → reconnecting → ... (retry loop)
+ *   → terminal_failure (max attempts exceeded or non-retryable error)
+ */
+import { CONTROL_RETRY_POLICY, computeRetryDelay, shouldRetry, } from './transport-contract.js';
+import { randomUUID } from 'node:crypto';
+import { logger } from '../../utils/logger.js';
+import { summarizeError } from '../../utils/error-display.js';
+/** Default reconnect policy. */
+const DEFAULT_RECONNECT_POLICY = Object.freeze({
+    ...CONTROL_RETRY_POLICY,
+    maxAttempts: 10,
+    initialDelayMs: 1_000,
+    maxDelayMs: 30_000,
+    retryOn: ['network', 'timeout', 'server', 'transient'],
+});
+/** Default replay configuration. */
+const DEFAULT_REPLAY_CONFIG = Object.freeze({
+    lastAckedOffset: 0,
+    maxReplayCount: 500,
+    enabled: true,
+});
+/**
+ * ReconnectEngine — manages the full reconnect lifecycle with backoff and replay.
+ *
+ * Usage:
+ * ```ts
+ * const engine = new ReconnectEngine(adapter, identity, replayConfig, callbacks);
+ * await engine.connect(); // blocks until connected or terminal failure
+ * // After a failure detected externally:
+ * await engine.reconnect(); // drives the retry loop
+ * engine.dispose(); // cancel any pending reconnect
+ * ```
+ */
+export class ReconnectEngine {
+    adapter;
+    identity;
+    callbacks;
+    _policy;
+    _replay;
+    _handshakeToken;
+    _epoch = 0;
+    _lastAckedOffset;
+    _attempts = 0;
+    _disposed = false;
+    _pendingTimer = null;
+    /** Negotiated protocol from the last successful handshake. */
+    _negotiatedProtocol;
+    constructor(adapter, identity, replayConfig, callbacks, reconnectPolicy) {
+        this.adapter = adapter;
+        this.identity = identity;
+        this.callbacks = callbacks;
+        this._policy = reconnectPolicy
+            ? Object.freeze({ ...DEFAULT_RECONNECT_POLICY, ...reconnectPolicy })
+            : DEFAULT_RECONNECT_POLICY;
+        this._replay = replayConfig
+            ? Object.freeze({ ...DEFAULT_REPLAY_CONFIG, ...replayConfig })
+            : DEFAULT_REPLAY_CONFIG;
+        this._lastAckedOffset = this._replay.lastAckedOffset;
+    }
+    /** Current handshake token (undefined until first successful connect). */
+    get handshakeToken() {
+        return this._handshakeToken;
+    }
+    /** Current server epoch. */
+    get epoch() {
+        return this._epoch;
+    }
+    /** Offset of the last acknowledged message. */
+    get lastAckedOffset() {
+        return this._lastAckedOffset;
+    }
+    /** Number of reconnect attempts since last successful connect. */
+    get attempts() {
+        return this._attempts;
+    }
+    /**
+     * The negotiated protocol from the last successful handshake.
+     * Undefined until the first successful connect.
+     */
+    get negotiatedProtocol() {
+        return this._negotiatedProtocol;
+    }
+    /**
+     * Update the last acknowledged offset.
+     * Call this whenever an ack is sent or a message is durably processed.
+     *
+     * @param offset - The offset to record as acknowledged.
+     */
+    ackOffset(offset) {
+        if (offset > this._lastAckedOffset) {
+            this._lastAckedOffset = offset;
+        }
+    }
+    /**
+     * Perform the initial connect attempt.
+     *
+     * @param authToken - Bearer token from the AuthProvider.
+     * @returns True on success, false on terminal failure.
+     */
+    async connect(authToken) {
+        if (this._disposed)
+            return false;
+        return this._attemptConnect(authToken, false);
+    }
+    /**
+     * Drive the reconnect retry loop.
+     *
+     * Attempts reconnection up to `policy.maxAttempts` times using
+     * exponential backoff with jitter. Calls callbacks at each state transition.
+     *
+     * @param getAuthToken - Called before each attempt to get a fresh token.
+     * @returns True if eventually connected, false on terminal failure.
+     */
+    async reconnect(getAuthToken) {
+        if (this._disposed)
+            return false;
+        while (this._attempts < this._policy.maxAttempts) {
+            if (this._disposed)
+                return false;
+            this._attempts++;
+            const delayMs = computeRetryDelay(this._policy, this._attempts);
+            this.callbacks?.onReconnecting?.(this._attempts, this._policy.maxAttempts, delayMs);
+            logger.debug('ReconnectEngine: scheduling reconnect attempt', {
+                attempt: this._attempts,
+                maxAttempts: this._policy.maxAttempts,
+                delayMs,
+            });
+            await this._sleep(delayMs);
+            if (this._disposed)
+                return false;
+            const authToken = await getAuthToken();
+            const connected = await this._attemptConnect(authToken, true);
+            if (connected) {
+                this._attempts = 0;
+                return true;
+            }
+            // If not connected and not retryable, terminal failure was already signalled
+        }
+        const error = `ReconnectEngine: max reconnect attempts (${this._policy.maxAttempts}) exceeded`;
+        logger.error(error);
+        this.callbacks?.onTerminalFailure(error);
+        return false;
+    }
+    /** Cancel any pending reconnect timer and mark engine as disposed. */
+    dispose() {
+        this._disposed = true;
+        if (this._pendingTimer !== null) {
+            clearTimeout(this._pendingTimer);
+            this._pendingTimer = null;
+        }
+    }
+    // ── Private helpers ──────────────────────────────────────────────────────────
+    async _attemptConnect(authToken, isReconnect) {
+        if (this._disposed)
+            return false;
+        this.callbacks?.onInitializing?.(this._attempts);
+        this.callbacks?.onAuthenticating?.();
+        const outcome = await this.adapter.connect(this.identity, this._lastAckedOffset, authToken);
+        if (!outcome.success) {
+            // Version incompatibility is always terminal — never retry
+            if (outcome.incompatibilityCode) {
+                logger.error('ReconnectEngine: incompatible peer version — terminal failure', {
+                    error: outcome.error,
+                    incompatibilityCode: outcome.incompatibilityCode,
+                });
+                if (this._disposed)
+                    return false;
+                this.callbacks?.onTerminalFailure(outcome.error);
+                return false;
+            }
+            const retryable = outcome.retryable && shouldRetry(this._policy, outcome.category);
+            logger.warn('ReconnectEngine: connect attempt failed', {
+                error: outcome.error,
+                category: outcome.category,
+                retryable,
+                isReconnect,
+            });
+            if (!retryable) {
+                this.callbacks?.onTerminalFailure(outcome.error);
+                return false;
+            }
+            this.callbacks?.onDisconnected?.(outcome.error, true);
+            return false;
+        }
+        // Success path
+        const { token, epoch, replayFromOffset, negotiatedProtocol } = outcome;
+        this._epoch = epoch;
+        this._handshakeToken = token;
+        this._negotiatedProtocol = negotiatedProtocol;
+        if (this.callbacks?.onVersionNegotiated) {
+            this.callbacks.onVersionNegotiated(negotiatedProtocol);
+        }
+        this.callbacks?.onConnected(token, epoch);
+        // Trigger replay if enabled and the server offers messages to replay
+        if (this._replay.enabled && replayFromOffset > 0) {
+            this.callbacks?.onSyncing?.();
+            try {
+                await this.adapter.requestReplay(replayFromOffset, this._replay.maxReplayCount);
+            }
+            catch (err) {
+                // Replay failure is non-fatal — degraded mode, not terminal
+                logger.warn('ReconnectEngine: replay request failed (degraded mode)', {
+                    err: summarizeError(err),
+                });
+            }
+        }
+        logger.debug('ReconnectEngine: connected successfully', {
+            sessionId: this.identity.sessionId,
+            epoch,
+            lastAckedOffset: this._lastAckedOffset,
+        });
+        return true;
+    }
+    _sleep(ms) {
+        return new Promise((resolve) => {
+            this._pendingTimer = setTimeout(() => {
+                this._pendingTimer = null;
+                resolve();
+            }, ms);
+        });
+    }
+}
+/**
+ * Generate an idempotent submission key for a command.
+ *
+ * The key combines the session ID with a random UUID so that retried
+ * submissions with the same key can be deduplicated by the server.
+ *
+ * @param sessionId - Durable session ID.
+ * @returns A stable key string for use as `idempotencyKey`.
+ */
+export function generateIdempotencyKey(sessionId) {
+    return `${sessionId}:${randomUUID()}`;
+}

package/dist/platform/runtime/remote/recovery.d.ts

@@ -0,0 +1,11 @@
+import type { AcpConnection } from '../store/domains/acp.js';
+import type { RemoteRunnerContract } from './types.js';
+import type { RemoteHeartbeatSnapshot } from './heartbeat.js';
+export interface RemoteRecoveryAction {
+    readonly id: string;
+    readonly label: string;
+    readonly command: string;
+    readonly reason: string;
+}
+export declare function deriveRemoteRecoveryActions(connection?: AcpConnection | null, contract?: RemoteRunnerContract | null, heartbeat?: RemoteHeartbeatSnapshot): RemoteRecoveryAction[];
+//# sourceMappingURL=recovery.d.ts.map

package/dist/platform/runtime/remote/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/remote/recovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAE9D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,2BAA2B,CACzC,UAAU,CAAC,EAAE,aAAa,GAAG,IAAI,EACjC,QAAQ,CAAC,EAAE,oBAAoB,GAAG,IAAI,EACtC,SAAS,CAAC,EAAE,uBAAuB,GAClC,oBAAoB,EAAE,CAqCxB"}

package/dist/platform/runtime/remote/recovery.js

@@ -0,0 +1,36 @@
+export function deriveRemoteRecoveryActions(connection, contract, heartbeat) {
+    const actions = [];
+    const runnerId = contract?.runnerId ?? connection?.agentId ?? 'selected';
+    const taskId = connection?.taskId ?? contract?.taskId;
+    if (connection?.lastError || contract?.transport.lastError) {
+        actions.push({
+            id: 'review-health',
+            label: 'Review remote health',
+            command: '/health review',
+            reason: connection?.lastError ?? contract?.transport.lastError ?? 'Remote transport reported an error.',
+        });
+    }
+    if (heartbeat?.status === 'stale') {
+        actions.push({
+            id: 'reconnect',
+            label: 'Reinspect remote runtime',
+            command: `/remote show ${runnerId}`,
+            reason: heartbeat.detail,
+        });
+    }
+    if (taskId) {
+        actions.push({
+            id: 'resume',
+            label: 'Resume bound remote task',
+            command: `/task status ${taskId}`,
+            reason: `Remote session is still bound to task ${taskId}.`,
+        });
+    }
+    actions.push({
+        id: 'remote-panel',
+        label: 'Open remote workspace',
+        command: '/remote',
+        reason: 'Inspect transport, runner contracts, and artifacts together.',
+    });
+    return actions;
+}

package/dist/platform/runtime/remote/session-state.d.ts

@@ -0,0 +1,30 @@
+import type { AcpConnection } from '../store/domains/acp.js';
+import type { RemoteRunnerContract } from './types.js';
+import type { RemoteCapabilitySnapshot } from './capabilities.js';
+import type { RemoteHeartbeatSnapshot } from './heartbeat.js';
+import type { RemoteRecoveryAction } from './recovery.js';
+import type { RemoteNegotiationSnapshot } from './negotiation.js';
+export interface RemoteSessionStateSnapshot {
+    readonly runnerId: string;
+    readonly label: string;
+    readonly transportState: string;
+    readonly taskId?: string;
+    readonly messageCount: number;
+    readonly errorCount: number;
+    readonly lastError?: string;
+    readonly heartbeat: RemoteHeartbeatSnapshot;
+    readonly negotiation: RemoteNegotiationSnapshot;
+    readonly capabilities: readonly RemoteCapabilitySnapshot[];
+    readonly recovery: readonly RemoteRecoveryAction[];
+}
+export declare function buildRemoteSessionStateSnapshot(input: {
+    runnerId: string;
+    label: string;
+    connection?: AcpConnection | null;
+    contract?: RemoteRunnerContract | null;
+    heartbeat: RemoteHeartbeatSnapshot;
+    negotiation: RemoteNegotiationSnapshot;
+    capabilities: readonly RemoteCapabilitySnapshot[];
+    recovery: readonly RemoteRecoveryAction[];
+}): RemoteSessionStateSnapshot;
+//# sourceMappingURL=session-state.d.ts.map

package/dist/platform/runtime/remote/session-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-state.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/remote/session-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAElE,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,uBAAuB,CAAC;IAC5C,QAAQ,CAAC,WAAW,EAAE,yBAAyB,CAAC;IAChD,QAAQ,CAAC,YAAY,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC3D,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACpD;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACvC,SAAS,EAAE,uBAAuB,CAAC;IACnC,WAAW,EAAE,yBAAyB,CAAC;IACvC,YAAY,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAClD,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAC3C,GAAG,0BAA0B,CAiB7B"}

package/dist/platform/runtime/remote/session-state.js

@@ -0,0 +1,18 @@
+export function buildRemoteSessionStateSnapshot(input) {
+    const { connection, contract } = input;
+    return Object.freeze({
+        runnerId: input.runnerId,
+        label: input.label,
+        transportState: connection?.transportState ?? contract?.transport.state ?? 'disconnected',
+        ...(connection?.taskId ?? contract?.taskId ? { taskId: connection?.taskId ?? contract?.taskId } : {}),
+        messageCount: connection?.messageCount ?? contract?.transport.messageCount ?? 0,
+        errorCount: connection?.errorCount ?? contract?.transport.errorCount ?? 0,
+        ...(connection?.lastError ?? contract?.transport.lastError
+            ? { lastError: connection?.lastError ?? contract?.transport.lastError }
+            : {}),
+        heartbeat: input.heartbeat,
+        negotiation: input.negotiation,
+        capabilities: input.capabilities,
+        recovery: input.recovery,
+    });
+}

package/dist/platform/runtime/remote/sync.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Remote Substrate — State Sync
+ *
+ * Mirrors remote task and health state into
+ * local runtime store domains (AcpDomainState, TaskDomainState).
+ *
+ * The sync layer is a one-way bridge: remote data flows into local store
+ * domains via the provided mutation callbacks. The store remains the
+ * single source of truth for local rendering — remote state is a projection.
+ */
+import type { RemoteTask, RemoteHealth, RemoteSession } from './types.js';
+import type { AcpDomainState, AcpConnection } from '../store/domains/acp.js';
+import type { RuntimeTask, TaskDomainState } from '../store/domains/tasks.js';
+/**
+ * Callbacks supplied by the runtime store to apply state mutations.
+ *
+ * The sync layer never touches the store directly — it calls these
+ * callbacks and lets the store manage its own invariants.
+ */
+export interface SyncStoreCallbacks {
+    /**
+     * Update ACP connection entry for the remote session.
+     *
+     * @param agentId - Durable agent ID of the remote connection.
+     * @param patch - Partial AcpConnection fields to update.
+     */
+    updateAcpConnection(agentId: string, patch: Partial<AcpConnection>): void;
+    /**
+     * Upsert a remote task into the tasks domain.
+     *
+     * @param task - Remote task snapshot to sync.
+     */
+    upsertRemoteTask(task: RuntimeTask): void;
+    /**
+     * Mark a remote task as terminal in the tasks domain.
+     *
+     * @param taskId - Task ID to finalize.
+     * @param status - Terminal status.
+     * @param error - Optional error message.
+     */
+    finalizeRemoteTask(taskId: string, status: Extract<RuntimeTask['status'], 'completed' | 'failed' | 'cancelled'>, error?: string): void;
+}
+/**
+ * RemoteStateSyncer — applies incoming remote state snapshots into local domains.
+ *
+ * Owns the translation from `RemoteTask`/`RemoteHealth` types (remote-facing)
+ * into `RuntimeTask` / ACP domain types (local store-facing).
+ *
+ * @example
+ * ```ts
+ * const syncer = new RemoteStateSyncer(storeCallbacks);
+ *
+ * // Called by the transport layer when a STATE_SNAPSHOT message arrives:
+ * syncer.syncSnapshot(session, incomingTasks, incomingHealth);
+ *
+ * // Called for incremental task updates:
+ * syncer.syncTaskUpdate(session, remoteTask);
+ * ```
+ */
+export declare class RemoteStateSyncer {
+    private readonly callbacks;
+    constructor(callbacks: SyncStoreCallbacks);
+    /**
+     * Sync a full remote state snapshot into local store domains.
+     *
+     * Called when a STATE_SNAPSHOT data message arrives after reconnect sync.
+     * Applies all tasks and the health status in a single pass.
+     *
+     * @param session - Current remote session (provides identity context).
+     * @param tasks - Remote tasks from the snapshot.
+     * @param health - Remote health snapshot.
+     */
+    syncSnapshot(session: RemoteSession, tasks: readonly RemoteTask[], health: RemoteHealth): void;
+    /**
+     * Sync an incremental task update.
+     *
+     * Called when a TASK_UPDATE or TASK_SUBMIT data message arrives.
+     *
+     * @param session - Current remote session.
+     * @param task - Updated remote task.
+     */
+    syncTaskUpdate(session: RemoteSession, task: RemoteTask): void;
+    /**
+     * Sync an incremental health update.
+     *
+     * Called when a HEALTH_REPORT data message arrives.
+     *
+     * @param session - Current remote session.
+     * @param health - Updated health snapshot.
+     */
+    syncHealthUpdate(session: RemoteSession, health: RemoteHealth): void;
+    /**
+     * Sync transport state change into the ACP connection entry.
+     *
+     * Called by the reconnect engine on every state transition.
+     *
+     * @param session - Current remote session.
+     */
+    syncTransportState(session: RemoteSession): void;
+    private _applyRemoteTask;
+    private _applyHealth;
+}
+/**
+ * Returns a no-op SyncStoreCallbacks implementation.
+ * Useful when the store is not yet initialized or sync is disabled.
+ */
+export declare function createNoOpSyncCallbacks(): SyncStoreCallbacks;
+/**
+ * Build an initial AcpConnection domain entry from a remote session.
+ *
+ * Call this when registering a new remote connection with the ACP store domain.
+ *
+ * @param session - Remote session snapshot.
+ * @param label - Human-readable connection label.
+ * @returns An AcpConnection suitable for inserting into AcpDomainState.connections.
+ */
+export declare function buildAcpConnectionEntry(session: RemoteSession, label: string): AcpConnection;
+/**
+ * Count active remote connections in an ACP domain state snapshot.
+ *
+ * @param state - ACP domain state snapshot.
+ * @returns Number of connections that are not yet completing.
+ */
+export declare function countActiveRemoteConnections(state: AcpDomainState): number;
+/**
+ * Extract remote task IDs from a tasks domain snapshot.
+ *
+ * @param state - Tasks domain state snapshot.
+ * @returns Array of task IDs whose kind === 'acp'.
+ */
+export declare function extractRemoteTaskIds(state: TaskDomainState): string[];
+//# sourceMappingURL=sync.d.ts.map

package/dist/platform/runtime/remote/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/remote/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAK9E;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,mBAAmB,CACjB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,IAAI,CAAC;IAER;;;;OAIG;IACH,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IAE1C;;;;;;OAMG;IACH,kBAAkB,CAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC,EAC5E,KAAK,CAAC,EAAE,MAAM,GACb,IAAI,CAAC;CACT;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,kBAAkB;IAE1D;;;;;;;;;OASG;IACH,YAAY,CACV,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,SAAS,UAAU,EAAE,EAC5B,MAAM,EAAE,YAAY,GACnB,IAAI;IAcP;;;;;;;OAOG;IACH,cAAc,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI;IAI9D;;;;;;;OAOG;IACH,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IAIpE;;;;;;OAMG;IACH,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAahD,OAAO,CAAC,gBAAgB;IA6BxB,OAAO,CAAC,YAAY;CAerB;AAID;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,kBAAkB,CAM5D;AAID;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,MAAM,GACZ,aAAa,CAYf;AAID;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,EAAE,CAMrE"}

package/dist/platform/runtime/remote/sync.js

@@ -0,0 +1,194 @@
+/**
+ * Remote Substrate — State Sync
+ *
+ * Mirrors remote task and health state into
+ * local runtime store domains (AcpDomainState, TaskDomainState).
+ *
+ * The sync layer is a one-way bridge: remote data flows into local store
+ * domains via the provided mutation callbacks. The store remains the
+ * single source of truth for local rendering — remote state is a projection.
+ */
+import { logger } from '../../utils/logger.js';
+// ── RemoteStateSyncer ─────────────────────────────────────────────────────────
+/**
+ * RemoteStateSyncer — applies incoming remote state snapshots into local domains.
+ *
+ * Owns the translation from `RemoteTask`/`RemoteHealth` types (remote-facing)
+ * into `RuntimeTask` / ACP domain types (local store-facing).
+ *
+ * @example
+ * ```ts
+ * const syncer = new RemoteStateSyncer(storeCallbacks);
+ *
+ * // Called by the transport layer when a STATE_SNAPSHOT message arrives:
+ * syncer.syncSnapshot(session, incomingTasks, incomingHealth);
+ *
+ * // Called for incremental task updates:
+ * syncer.syncTaskUpdate(session, remoteTask);
+ * ```
+ */
+export class RemoteStateSyncer {
+    callbacks;
+    constructor(callbacks) {
+        this.callbacks = callbacks;
+    }
+    /**
+     * Sync a full remote state snapshot into local store domains.
+     *
+     * Called when a STATE_SNAPSHOT data message arrives after reconnect sync.
+     * Applies all tasks and the health status in a single pass.
+     *
+     * @param session - Current remote session (provides identity context).
+     * @param tasks - Remote tasks from the snapshot.
+     * @param health - Remote health snapshot.
+     */
+    syncSnapshot(session, tasks, health) {
+        logger.debug('RemoteStateSyncer.syncSnapshot: applying state snapshot', {
+            taskCount: tasks.length,
+            healthStatus: health.status,
+            sessionId: session.identity.sessionId,
+        });
+        for (const task of tasks) {
+            this._applyRemoteTask(session, task);
+        }
+        this._applyHealth(session, health);
+    }
+    /**
+     * Sync an incremental task update.
+     *
+     * Called when a TASK_UPDATE or TASK_SUBMIT data message arrives.
+     *
+     * @param session - Current remote session.
+     * @param task - Updated remote task.
+     */
+    syncTaskUpdate(session, task) {
+        this._applyRemoteTask(session, task);
+    }
+    /**
+     * Sync an incremental health update.
+     *
+     * Called when a HEALTH_REPORT data message arrives.
+     *
+     * @param session - Current remote session.
+     * @param health - Updated health snapshot.
+     */
+    syncHealthUpdate(session, health) {
+        this._applyHealth(session, health);
+    }
+    /**
+     * Sync transport state change into the ACP connection entry.
+     *
+     * Called by the reconnect engine on every state transition.
+     *
+     * @param session - Current remote session.
+     */
+    syncTransportState(session) {
+        const { identity, transportState, lastError, reconnectAttempts, messagesSent, messagesReceived } = session;
+        this.callbacks.updateAcpConnection(identity.agentId, {
+            transportState,
+            lastError,
+            errorCount: reconnectAttempts,
+            messageCount: messagesSent + messagesReceived,
+        });
+    }
+    // ── Private helpers ──────────────────────────────────────────────────────────
+    _applyRemoteTask(session, remote) {
+        const isTerminal = (remote.status === 'completed' ||
+            remote.status === 'failed' ||
+            remote.status === 'cancelled');
+        if (isTerminal) {
+            const terminalStatus = remote.status;
+            this.callbacks.finalizeRemoteTask(remote.taskId, terminalStatus, remote.error);
+        }
+        else {
+            const runtimeTask = {
+                id: remote.taskId,
+                kind: 'acp',
+                title: remote.title,
+                status: remote.status,
+                owner: remote.agentId,
+                cancellable: remote.status === 'queued' || remote.status === 'running',
+                childTaskIds: [],
+                queuedAt: remote.updatedAt,
+                startedAt: remote.status !== 'queued' ? remote.updatedAt : undefined,
+                endedAt: undefined,
+                error: remote.error,
+                correlationId: session.identity.sessionId,
+            };
+            this.callbacks.upsertRemoteTask(runtimeTask);
+        }
+    }
+    _applyHealth(session, health) {
+        // Map remote health status to ACP transport state
+        const transportState = (() => {
+            switch (health.status) {
+                case 'healthy': return 'connected';
+                case 'degraded': return 'degraded';
+                case 'unreachable': return 'reconnecting';
+            }
+        })();
+        this.callbacks.updateAcpConnection(session.identity.agentId, {
+            transportState,
+            lastError: health.degradedReason,
+        });
+    }
+}
+// ── No-op sync callbacks (for testing or disabled sync) ──────────────────────
+/**
+ * Returns a no-op SyncStoreCallbacks implementation.
+ * Useful when the store is not yet initialized or sync is disabled.
+ */
+export function createNoOpSyncCallbacks() {
+    return {
+        updateAcpConnection: (_agentId, _patch) => { },
+        upsertRemoteTask: (_task) => { },
+        finalizeRemoteTask: (_taskId, _status, _error) => { },
+    };
+}
+// ── Utility: build initial AcpConnection for a remote session ─────────────────
+/**
+ * Build an initial AcpConnection domain entry from a remote session.
+ *
+ * Call this when registering a new remote connection with the ACP store domain.
+ *
+ * @param session - Remote session snapshot.
+ * @param label - Human-readable connection label.
+ * @returns An AcpConnection suitable for inserting into AcpDomainState.connections.
+ */
+export function buildAcpConnectionEntry(session, label) {
+    return {
+        agentId: session.identity.agentId,
+        label,
+        transportState: session.transportState,
+        connectedAt: session.lastConnectedAt,
+        completing: false,
+        messageCount: session.messagesSent + session.messagesReceived,
+        errorCount: session.reconnectAttempts,
+        lastError: session.lastError,
+        taskId: session.identity.taskId,
+    };
+}
+// ── Utility: domain state accessors ──────────────────────────────────────────
+/**
+ * Count active remote connections in an ACP domain state snapshot.
+ *
+ * @param state - ACP domain state snapshot.
+ * @returns Number of connections that are not yet completing.
+ */
+export function countActiveRemoteConnections(state) {
+    return state.activeConnectionIds.length;
+}
+/**
+ * Extract remote task IDs from a tasks domain snapshot.
+ *
+ * @param state - Tasks domain state snapshot.
+ * @returns Array of task IDs whose kind === 'acp'.
+ */
+export function extractRemoteTaskIds(state) {
+    const ids = [];
+    for (const [id, task] of state.tasks) {
+        if (task.kind === 'acp')
+            ids.push(id);
+    }
+    return ids;
+}