@pellux/goodvibes-sdk 0.18.13 → 0.18.15

package/dist/_internal/platform/runtime/remote/index.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Remote Substrate — Public API
+ *
+ * Barrel export and `createRemoteSubstrate()` factory.
+ *
+ * The remote substrate layer covers identity, handshake, sync, and transport:
+ * - Durable identity stable across reconnects
+ * - Handshake tokens with epoch tracking
+ * - Typed transport messages (control / data / ack / failure)
+ * - Reconnect engine with exponential backoff and replay
+ * - State sync into runtime store domains
+ * - Observability panel data provider
+ */
+import { RemoteObservabilityProvider } from '@pellux/goodvibes-sdk/platform/runtime/remote/observability';
+import type { RemoteSubstrateConfig, RemoteSession, RemoteTask, RemoteHealth, DurableIdentity } from '@pellux/goodvibes-sdk/platform/runtime/remote/types';
+import type { SyncStoreCallbacks } from '@pellux/goodvibes-sdk/platform/runtime/remote/sync';
+import type { TransportAdapter } from '@pellux/goodvibes-sdk/platform/runtime/remote/reconnect';
+export type { DurableIdentity, HandshakeToken, ReplayConfig, RemoteSession, RemoteTask, RemoteHealth, RemoteSubstrateConfig, RemoteConnectionHealth, RemoteRunnerContract, RemoteRunnerCapabilityCeiling, RemoteExecutionArtifact, RemoteRunnerEvidenceSummary, TransportMessage, ControlMessage, DataMessage, AckMessage, FailureMessage, TransportMessageBase, TransportMessageClass, TransportErrorCategory, RetryPolicy, AuthProvider, } from '@pellux/goodvibes-sdk/platform/runtime/remote/types';
+export type { IdentitySnapshot, } from '@pellux/goodvibes-sdk/platform/runtime/remote/identity';
+export type { ConnectOutcome, TransportAdapter, ReconnectEngineCallbacks, } from '@pellux/goodvibes-sdk/platform/runtime/remote/reconnect';
+export type { SyncStoreCallbacks, } from '@pellux/goodvibes-sdk/platform/runtime/remote/sync';
+export type { RemoteConnectionSnapshot, RemoteTaskSnapshot, RemoteObservabilitySnapshot, } from '@pellux/goodvibes-sdk/platform/runtime/remote/observability';
+export { CONTROL_RETRY_POLICY, DATA_RETRY_POLICY, ACK_RETRY_POLICY, FAILURE_RETRY_POLICY, createControlMessage, createDataMessage, createAckMessage, createFailureMessage, computeRetryDelay, shouldRetry, } from '@pellux/goodvibes-sdk/platform/runtime/remote/transport-contract';
+export type { ControlMessageType, DataMessageType, ControlPayloads, DataPayloads, } from '@pellux/goodvibes-sdk/platform/runtime/remote/transport-contract';
+export { CURRENT_PROTOCOL_VERSION, TRANSPORT_COMPATIBILITY_MATRIX, VersionMismatchError, negotiateProtocolVersion, } from '@pellux/goodvibes-sdk/platform/runtime/remote/transport-contract';
+export type { ProtocolVersion, CompatibilityMatrix, CompatibilityEntry, VersionNegotiationResult, NegotiatedProtocol, DowngradeReason, } from '@pellux/goodvibes-sdk/platform/runtime/remote/types';
+export { DurableIdentityManager } from '@pellux/goodvibes-sdk/platform/runtime/remote/identity';
+export { ReconnectEngine, generateIdempotencyKey } from '@pellux/goodvibes-sdk/platform/runtime/remote/reconnect';
+export { RemoteStateSyncer, createNoOpSyncCallbacks, buildAcpConnectionEntry, countActiveRemoteConnections, extractRemoteTaskIds } from '@pellux/goodvibes-sdk/platform/runtime/remote/sync';
+export { RemoteObservabilityProvider } from '@pellux/goodvibes-sdk/platform/runtime/remote/observability';
+export { deriveRemoteCapabilities, } from '@pellux/goodvibes-sdk/platform/runtime/remote/capabilities';
+export type { RemoteCapabilityId, RemoteCapabilitySnapshot, } from '@pellux/goodvibes-sdk/platform/runtime/remote/capabilities';
+export { deriveRemoteHeartbeat, } from '@pellux/goodvibes-sdk/platform/runtime/remote/heartbeat';
+export type { RemoteHeartbeatSnapshot, } from '@pellux/goodvibes-sdk/platform/runtime/remote/heartbeat';
+export { deriveRemoteNegotiation, } from '@pellux/goodvibes-sdk/platform/runtime/remote/negotiation';
+export type { RemoteNegotiationSnapshot, } from '@pellux/goodvibes-sdk/platform/runtime/remote/negotiation';
+export { deriveRemoteRecoveryActions, } from '@pellux/goodvibes-sdk/platform/runtime/remote/recovery';
+export type { RemoteRecoveryAction, } from '@pellux/goodvibes-sdk/platform/runtime/remote/recovery';
+export { buildRemoteSessionStateSnapshot, } from '@pellux/goodvibes-sdk/platform/runtime/remote/session-state';
+export type { RemoteSessionStateSnapshot, } from '@pellux/goodvibes-sdk/platform/runtime/remote/session-state';
+export { RemoteSupervisor, } from './supervisor.js';
+export type { RemoteSupervisorSnapshot, } from './supervisor.js';
+export { RemoteRunnerRegistry, exportRemoteArtifactForAgent, importRemoteArtifact, } from './runner-registry.js';
+export type { DistributedPeerKind, DistributedPairRequestStatus, DistributedPeerStatus, DistributedWorkPriority, DistributedWorkStatus, DistributedWorkType, DistributedSessionBridge, DistributedApprovalBridge, DistributedAutomationBridge, DistributedRuntimePairRequest, DistributedPeerTokenRecord, DistributedPeerRecord, DistributedPendingWork, DistributedRuntimeAuditRecord, DistributedPeerAuth, DistributedNodeHostContract, } from '@pellux/goodvibes-sdk/platform/runtime/remote/distributed-runtime';
+export { DistributedRuntimeManager, getDistributedNodeHostContract, } from '@pellux/goodvibes-sdk/platform/runtime/remote/distributed-runtime';
+/**
+ * RemoteSubstrate — high-level facade wiring together all remote substrate components.
+ *
+ * This class composes DurableIdentityManager, ReconnectEngine, RemoteStateSyncer,
+ * and RemoteObservabilityProvider into a single, lifecycle-managed unit.
+ *
+ * Callers supply a TransportAdapter (the actual I/O layer) and optional
+ * SyncStoreCallbacks (to apply state changes to local store domains).
+ *
+ * @example
+ * ```ts
+ * const substrate = createRemoteSubstrate({
+ *   endpoint: 'wss://remote.example.com/agent',
+ *   identity: identityManager.current,
+ *   authProvider: { getToken: async () => 'bearer-token' },
+ * });
+ *
+ * substrate.attach(wsAdapter, storeCallbacks);
+ * await substrate.connect();
+ *
+ * // Panel rendering:
+ * const obs = substrate.observability;
+ * obs.subscribe(() => renderRemotePanel(obs.getSnapshot()));
+ * ```
+ */
+export declare class RemoteSubstrate {
+    private readonly config;
+    private adapter;
+    private readonly _identity;
+    private readonly _observability;
+    private _syncer;
+    private _engine;
+    private _session;
+    private _epoch;
+    private _disposed;
+    constructor(config: RemoteSubstrateConfig, adapter?: TransportAdapter | null);
+    /** The observability panel data provider for this substrate. */
+    get observability(): RemoteObservabilityProvider;
+    /** Current remote session snapshot. */
+    get session(): RemoteSession;
+    /** Current durable identity. */
+    get identity(): DurableIdentity;
+    /**
+     * Attach a transport adapter and store callbacks.
+     *
+     * Must be called before `connect()`. Can be called again after reconnection
+     * with a new adapter (e.g. replacing a failed WebSocket with a fresh one).
+     *
+     * @param adapter - The transport I/O adapter.
+     * @param storeCallbacks - Optional store mutation callbacks for state sync.
+     */
+    attach(adapter: TransportAdapter, storeCallbacks?: SyncStoreCallbacks): void;
+    /**
+     * Establish the initial connection to the remote substrate.
+     *
+     * @returns True if connected successfully, false on terminal failure.
+     */
+    connect(): Promise<boolean>;
+    /**
+     * Drive the reconnect loop after a connection failure.
+     *
+     * @returns True if eventually reconnected, false on terminal failure.
+     */
+    reconnect(): Promise<boolean>;
+    /**
+     * Acknowledge a received message offset.
+     *
+     * @param offset - The message offset to acknowledge.
+     */
+    ackOffset(offset: number): void;
+    /**
+     * Apply an incoming remote task update.
+     *
+     * @param task - Remote task snapshot from the transport.
+     */
+    receiveTaskUpdate(task: RemoteTask): void;
+    /**
+     * Apply an incoming remote health update.
+     *
+     * @param health - Remote health snapshot from the transport.
+     */
+    receiveHealthUpdate(health: RemoteHealth): void;
+    /** Dispose the substrate, cancelling any pending reconnects. */
+    dispose(): void;
+    private _buildInitialSession;
+    private _rebuildEngine;
+    private _getAuthToken;
+}
+/**
+ * Create a new RemoteSubstrate instance.
+ *
+ * @param config - Remote substrate configuration.
+ * @param adapter - Optional transport adapter (can be attached later via `attach()`).
+ * @returns A new RemoteSubstrate instance.
+ *
+ * @example
+ * ```ts
+ * const substrate = createRemoteSubstrate({
+ *   endpoint: 'wss://remote.example.com/agent',
+ *   identity: {
+ *     sessionId: crypto.randomUUID(),
+ *     taskId: crypto.randomUUID(),
+ *     agentId: crypto.randomUUID(),
+ *     createdAt: Date.now(),
+ *     generation: 1,
+ *   },
+ * });
+ *
+ * substrate.attach(myTransportAdapter, storeCallbacks);
+ * const connected = await substrate.connect();
+ * ```
+ */
+export declare function createRemoteSubstrate(config: RemoteSubstrateConfig, adapter?: TransportAdapter): RemoteSubstrate;
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/runtime/remote/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/remote/index.ts"],"names":[],"mappings":"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"}

package/dist/_internal/platform/runtime/remote/index.js

@@ -0,0 +1,305 @@
+/**
+ * Remote Substrate — Public API
+ *
+ * Barrel export and `createRemoteSubstrate()` factory.
+ *
+ * The remote substrate layer covers identity, handshake, sync, and transport:
+ * - Durable identity stable across reconnects
+ * - Handshake tokens with epoch tracking
+ * - Typed transport messages (control / data / ack / failure)
+ * - Reconnect engine with exponential backoff and replay
+ * - State sync into runtime store domains
+ * - Observability panel data provider
+ */
+import { randomUUID } from 'node:crypto';
+import { DurableIdentityManager } from '@pellux/goodvibes-sdk/platform/runtime/remote/identity';
+import { ReconnectEngine } from '@pellux/goodvibes-sdk/platform/runtime/remote/reconnect';
+import { RemoteStateSyncer, createNoOpSyncCallbacks } from '@pellux/goodvibes-sdk/platform/runtime/remote/sync';
+import { RemoteObservabilityProvider } from '@pellux/goodvibes-sdk/platform/runtime/remote/observability';
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+export { 
+// Transport contract
+CONTROL_RETRY_POLICY, DATA_RETRY_POLICY, ACK_RETRY_POLICY, FAILURE_RETRY_POLICY, createControlMessage, createDataMessage, createAckMessage, createFailureMessage, computeRetryDelay, shouldRetry, } from '@pellux/goodvibes-sdk/platform/runtime/remote/transport-contract';
+export { CURRENT_PROTOCOL_VERSION, TRANSPORT_COMPATIBILITY_MATRIX, VersionMismatchError, negotiateProtocolVersion, } from '@pellux/goodvibes-sdk/platform/runtime/remote/transport-contract';
+export { DurableIdentityManager } from '@pellux/goodvibes-sdk/platform/runtime/remote/identity';
+export { ReconnectEngine, generateIdempotencyKey } from '@pellux/goodvibes-sdk/platform/runtime/remote/reconnect';
+export { RemoteStateSyncer, createNoOpSyncCallbacks, buildAcpConnectionEntry, countActiveRemoteConnections, extractRemoteTaskIds } from '@pellux/goodvibes-sdk/platform/runtime/remote/sync';
+export { RemoteObservabilityProvider } from '@pellux/goodvibes-sdk/platform/runtime/remote/observability';
+export { deriveRemoteCapabilities, } from '@pellux/goodvibes-sdk/platform/runtime/remote/capabilities';
+export { deriveRemoteHeartbeat, } from '@pellux/goodvibes-sdk/platform/runtime/remote/heartbeat';
+export { deriveRemoteNegotiation, } from '@pellux/goodvibes-sdk/platform/runtime/remote/negotiation';
+export { deriveRemoteRecoveryActions, } from '@pellux/goodvibes-sdk/platform/runtime/remote/recovery';
+export { buildRemoteSessionStateSnapshot, } from '@pellux/goodvibes-sdk/platform/runtime/remote/session-state';
+export { RemoteSupervisor, } from './supervisor.js';
+export { RemoteRunnerRegistry, exportRemoteArtifactForAgent, importRemoteArtifact, } from './runner-registry.js';
+export { DistributedRuntimeManager, getDistributedNodeHostContract, } from '@pellux/goodvibes-sdk/platform/runtime/remote/distributed-runtime';
+// ── RemoteSubstrate facade ────────────────────────────────────────────────────
+/**
+ * RemoteSubstrate — high-level facade wiring together all remote substrate components.
+ *
+ * This class composes DurableIdentityManager, ReconnectEngine, RemoteStateSyncer,
+ * and RemoteObservabilityProvider into a single, lifecycle-managed unit.
+ *
+ * Callers supply a TransportAdapter (the actual I/O layer) and optional
+ * SyncStoreCallbacks (to apply state changes to local store domains).
+ *
+ * @example
+ * ```ts
+ * const substrate = createRemoteSubstrate({
+ *   endpoint: 'wss://remote.example.com/agent',
+ *   identity: identityManager.current,
+ *   authProvider: { getToken: async () => 'bearer-token' },
+ * });
+ *
+ * substrate.attach(wsAdapter, storeCallbacks);
+ * await substrate.connect();
+ *
+ * // Panel rendering:
+ * const obs = substrate.observability;
+ * obs.subscribe(() => renderRemotePanel(obs.getSnapshot()));
+ * ```
+ */
+export class RemoteSubstrate {
+    config;
+    adapter;
+    _identity;
+    _observability;
+    _syncer;
+    _engine = null;
+    _session;
+    _epoch = 0;
+    _disposed = false;
+    constructor(config, adapter = null) {
+        this.config = config;
+        this.adapter = adapter;
+        this._identity = new DurableIdentityManager(config.identity);
+        this._observability = new RemoteObservabilityProvider();
+        this._syncer = new RemoteStateSyncer(createNoOpSyncCallbacks());
+        this._session = this._buildInitialSession();
+    }
+    /** The observability panel data provider for this substrate. */
+    get observability() {
+        return this._observability;
+    }
+    /** Current remote session snapshot. */
+    get session() {
+        return this._session;
+    }
+    /** Current durable identity. */
+    get identity() {
+        return this._identity.current;
+    }
+    /**
+     * Attach a transport adapter and store callbacks.
+     *
+     * Must be called before `connect()`. Can be called again after reconnection
+     * with a new adapter (e.g. replacing a failed WebSocket with a fresh one).
+     *
+     * @param adapter - The transport I/O adapter.
+     * @param storeCallbacks - Optional store mutation callbacks for state sync.
+     */
+    attach(adapter, storeCallbacks) {
+        this.adapter = adapter;
+        this._syncer = new RemoteStateSyncer(storeCallbacks ?? createNoOpSyncCallbacks());
+        this._rebuildEngine();
+    }
+    /**
+     * Establish the initial connection to the remote substrate.
+     *
+     * @returns True if connected successfully, false on terminal failure.
+     */
+    async connect() {
+        if (this._disposed || !this._engine) {
+            logger.error('RemoteSubstrate.connect: substrate disposed or no adapter attached');
+            return false;
+        }
+        const authToken = await this._getAuthToken();
+        return this._engine.connect(authToken);
+    }
+    /**
+     * Drive the reconnect loop after a connection failure.
+     *
+     * @returns True if eventually reconnected, false on terminal failure.
+     */
+    async reconnect() {
+        if (this._disposed || !this._engine)
+            return false;
+        return this._engine.reconnect(() => this._getAuthToken());
+    }
+    /**
+     * Acknowledge a received message offset.
+     *
+     * @param offset - The message offset to acknowledge.
+     */
+    ackOffset(offset) {
+        this._engine?.ackOffset(offset);
+        this._session = {
+            ...this._session,
+            lastAckedOffset: Math.max(this._session.lastAckedOffset, offset),
+        };
+        this._observability.updateSession(this._session);
+    }
+    /**
+     * Apply an incoming remote task update.
+     *
+     * @param task - Remote task snapshot from the transport.
+     */
+    receiveTaskUpdate(task) {
+        const tasks = new Map(this._session.remoteTasks);
+        tasks.set(task.taskId, task);
+        this._session = { ...this._session, remoteTasks: tasks };
+        this._syncer.syncTaskUpdate(this._session, task);
+        this._observability.updateSession(this._session);
+    }
+    /**
+     * Apply an incoming remote health update.
+     *
+     * @param health - Remote health snapshot from the transport.
+     */
+    receiveHealthUpdate(health) {
+        this._session = { ...this._session, health };
+        this._syncer.syncHealthUpdate(this._session, health);
+        this._observability.updateSession(this._session);
+    }
+    /** Dispose the substrate, cancelling any pending reconnects. */
+    dispose() {
+        this._disposed = true;
+        this._engine?.dispose();
+        this._engine = null;
+        this._observability.untrackSession(this._session.connectionId);
+        this._observability.dispose();
+        logger.debug('RemoteSubstrate: disposed', { connectionId: this._session.connectionId });
+    }
+    // ── Private helpers ──────────────────────────────────────────────────────────
+    _buildInitialSession() {
+        return {
+            connectionId: randomUUID(),
+            identity: this._identity.current,
+            endpoint: this.config.endpoint,
+            transportState: 'disconnected',
+            handshakeToken: undefined,
+            replayConfig: {
+                lastAckedOffset: 0,
+                maxReplayCount: 500,
+                enabled: true,
+                ...this.config.replayConfig,
+            },
+            reconnectAttempts: 0,
+            lastConnectedAt: undefined,
+            lastError: undefined,
+            remoteTasks: new Map(),
+            health: { status: 'unreachable', updatedAt: Date.now() },
+            messagesSent: 0,
+            messagesReceived: 0,
+            lastAckedOffset: 0,
+        };
+    }
+    _rebuildEngine() {
+        this._engine?.dispose();
+        if (!this.adapter)
+            return;
+        const callbacks = {
+            onInitializing: (attempt) => {
+                this._session = { ...this._session, transportState: 'initializing', reconnectAttempts: attempt };
+                this._observability.updateSession(this._session);
+                this._syncer.syncTransportState(this._session);
+            },
+            onAuthenticating: () => {
+                this._session = { ...this._session, transportState: 'authenticating' };
+                this._observability.updateSession(this._session);
+                this._syncer.syncTransportState(this._session);
+            },
+            onConnected: (token, epoch) => {
+                this._epoch = epoch;
+                this._session = {
+                    ...this._session,
+                    transportState: 'connected',
+                    handshakeToken: token,
+                    lastConnectedAt: Date.now(),
+                    lastError: undefined,
+                    reconnectAttempts: 0,
+                };
+                this._observability.updateSession(this._session);
+                this._syncer.syncTransportState(this._session);
+            },
+            onSyncing: () => {
+                this._session = { ...this._session, transportState: 'syncing' };
+                this._observability.updateSession(this._session);
+                this._syncer.syncTransportState(this._session);
+            },
+            onReconnecting: (attempt, maxAttempts, _delayMs) => {
+                this._session = {
+                    ...this._session,
+                    transportState: 'reconnecting',
+                    reconnectAttempts: attempt,
+                };
+                this._observability.updateSession(this._session);
+                this._syncer.syncTransportState(this._session);
+                logger.warn('RemoteSubstrate: reconnecting', {
+                    attempt,
+                    maxAttempts,
+                    sessionId: this._session.identity.sessionId,
+                });
+            },
+            onDisconnected: (reason, willRetry) => {
+                this._session = {
+                    ...this._session,
+                    transportState: 'disconnected',
+                    lastError: reason,
+                };
+                this._observability.updateSession(this._session);
+                this._syncer.syncTransportState(this._session);
+                logger.warn('RemoteSubstrate: disconnected', { reason, willRetry });
+            },
+            onTerminalFailure: (error) => {
+                this._session = {
+                    ...this._session,
+                    transportState: 'terminal_failure',
+                    lastError: error,
+                };
+                this._observability.updateSession(this._session);
+                this._syncer.syncTransportState(this._session);
+                logger.error('RemoteSubstrate: terminal failure', {
+                    error,
+                    sessionId: this._session.identity.sessionId,
+                });
+            },
+        };
+        this._engine = new ReconnectEngine(this.adapter, this._identity.current, this.config.replayConfig, callbacks, this.config.reconnectPolicy);
+        this._observability.trackSession(this._session);
+    }
+    async _getAuthToken() {
+        if (this.config.authProvider) {
+            return this.config.authProvider.getToken();
+        }
+        return '';
+    }
+}
+// ── Factory function ──────────────────────────────────────────────────────────
+/**
+ * Create a new RemoteSubstrate instance.
+ *
+ * @param config - Remote substrate configuration.
+ * @param adapter - Optional transport adapter (can be attached later via `attach()`).
+ * @returns A new RemoteSubstrate instance.
+ *
+ * @example
+ * ```ts
+ * const substrate = createRemoteSubstrate({
+ *   endpoint: 'wss://remote.example.com/agent',
+ *   identity: {
+ *     sessionId: crypto.randomUUID(),
+ *     taskId: crypto.randomUUID(),
+ *     agentId: crypto.randomUUID(),
+ *     createdAt: Date.now(),
+ *     generation: 1,
+ *   },
+ * });
+ *
+ * substrate.attach(myTransportAdapter, storeCallbacks);
+ * const connected = await substrate.connect();
+ * ```
+ */
+export function createRemoteSubstrate(config, adapter) {
+    return new RemoteSubstrate(config, adapter ?? null);
+}

package/dist/_internal/platform/runtime/remote/runner-registry.d.ts

@@ -0,0 +1,51 @@
+import type { AgentManager } from '../../tools/agent/index.js';
+import type { RuntimeStore } from '../store/index.js';
+import type { RemoteExecutionArtifact, RemoteRunnerContract, RemoteRunnerPool, RemoteSessionBundle } from '@pellux/goodvibes-sdk/platform/runtime/remote/types';
+export declare class RemoteRunnerRegistry {
+    private readonly agentManager;
+    private readonly contracts;
+    private readonly artifacts;
+    private readonly pools;
+    constructor(agentManager: Pick<AgentManager, 'getStatus' | 'list'>);
+    private resolveConnection;
+    upsertContractForAgent(agentId: string, store?: RuntimeStore): RemoteRunnerContract | null;
+    getContract(agentId: string): RemoteRunnerContract | null;
+    registerContract(contract: RemoteRunnerContract): RemoteRunnerContract;
+    listContracts(): RemoteRunnerContract[];
+    createPool(input: {
+        id: string;
+        label?: string;
+        description?: string;
+        trustClass?: RemoteRunnerPool['trustClass'];
+        preferredTemplate?: string;
+        maxRunners?: number;
+    }): RemoteRunnerPool;
+    getPool(poolId: string): RemoteRunnerPool | null;
+    listPools(): RemoteRunnerPool[];
+    assignRunnerToPool(poolId: string, runnerId: string): RemoteRunnerPool | null;
+    removeRunnerFromPool(poolId: string, runnerId: string): RemoteRunnerPool | null;
+    captureArtifactForAgent(agentId: string, store?: RuntimeStore): RemoteExecutionArtifact | null;
+    captureArtifactForRunner(runnerId: string, store?: RuntimeStore): RemoteExecutionArtifact | null;
+    getArtifact(artifactId: string): RemoteExecutionArtifact | null;
+    listArtifacts(): RemoteExecutionArtifact[];
+    exportArtifact(artifactId: string, explicitPath?: string): Promise<{
+        artifact: RemoteExecutionArtifact;
+        path: string;
+    } | null>;
+    importArtifact(path: string): Promise<RemoteExecutionArtifact>;
+    buildSessionBundle(store?: RuntimeStore): RemoteSessionBundle;
+    exportSessionBundle(store?: RuntimeStore, explicitPath?: string): Promise<{
+        bundle: RemoteSessionBundle;
+        path: string;
+    }>;
+    importSessionBundle(path: string): Promise<RemoteSessionBundle>;
+    buildReviewSummary(artifactId: string): string | null;
+    ensureContractsFromStore(store?: RuntimeStore): void;
+    clear(): void;
+}
+export declare function exportRemoteArtifactForAgent(registry: RemoteRunnerRegistry, agentId: string, store?: RuntimeStore, path?: string): Promise<{
+    artifact: RemoteExecutionArtifact;
+    path: string;
+} | null>;
+export declare function importRemoteArtifact(registry: RemoteRunnerRegistry, path: string): Promise<RemoteExecutionArtifact>;
+//# sourceMappingURL=runner-registry.d.ts.map

package/dist/_internal/platform/runtime/remote/runner-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-registry.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/remote/runner-registry.ts"],"names":[],"mappings":"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"}