maka-agent 0.2.0-dev.12.20260901 → 0.2.0-dev.14.20260902

package/node_modules/@maka/runtime/dist/tool-result-archive-transition.js

@@ -16,10 +16,33 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+/**
+ * The one writer that turns a Tool Result prune decision into durable truth
+ * (#4283).
+ *
+ * Both prune paths — the current Turn's active prune before the next provider
+ * step, and the prior Turn's stale prune before compaction — come through here.
+ * They used to keep their replacement in a Turn-local map and a policy-carried
+ * ref table respectively, so each owned a private recovery contract and neither
+ * survived a restart. Now each records one `ModelProjectionTransition`, and the
+ * Session reducer is the only thing that decides what the model sees.
+ *
+ * Write order is the whole safety argument:
+ *
+ * 1. Archive the replaced body. A failure here leaves the projection untouched.
+ * 2. Append the transition. A failure here leaves an artifact nothing points
+ *    at — unreachable by the reducer, so safe to reclaim once something does —
+ *    and again leaves the projection untouched.
+ * 3. Only then may a caller show the replacement.
+ *
+ * There is no state in which the model has lost content the ledger cannot
+ * explain, and none in which a completed tool effect is repeated.
+ */
+import { MATERIALIZED_IMAGE_TOKENS } from '@maka/core/attachments';
 import { DURABLE_TOOL_RESULT_PROJECTION_VERSION } from '@maka/core/durable-tool-result-projection';
 import { buildModelProjectionTransition, } from '@maka/core/model-projection-transition';
 import { estimateTokens, finitePositive, sha256, turnKey, utf8ByteLength, } from './context-budget-helpers.js';
-import { durableProjectionToToolResultOutput } from './durable-tool-result-projection.js';
+import { durableProjectionToToolResultOutput, projectionArtifactMedia, } from './durable-tool-result-projection.js';
 import { baseToolResultProjection, nextInChain } from './model-projection-transition-ledger.js';
 import { ARCHIVED_TOOL_RESULT_REWRITE_VERSION, buildArchivedToolResultPlaceholder, isArchivedToolResultPlaceholder, serializeToolResultForArchive, } from './tool-result-archive.js';
 const DEFAULT_MAX_TOOL_RESULT_ESTIMATED_TOKENS = 2048;
@@ -168,8 +191,16 @@ export function collectStaleToolResultArchiveCandidates(events, prunePolicy, cha
             continue;
         const serializedResult = serializedToolResultProjection(sourceProjection);
         const originalBytes = utf8ByteLength(serializedResult);
-        const originalEstimatedTokens = estimateTokens(serializedResult.length, charsPerToken);
-        if (originalEstimatedTokens <= maxResultEstimatedTokens)
+        const media = projectionArtifactMedia(sourceProjection);
+        // An artifact serializes to a short reference and materializes to real
+        // image bytes, so the string alone would price a screenshot at nothing.
+        const originalEstimatedTokens = estimateTokens(serializedResult.length, charsPerToken) +
+            media.length * MATERIALIZED_IMAGE_TOKENS;
+        // A result that carries media is always a candidate: archiving it drops
+        // whole images from the request, which is worth doing whatever the
+        // reference text around them happens to weigh. The size gate is there to
+        // spare small text results, so it only decides those.
+        if (media.length === 0 && originalEstimatedTokens <= maxResultEstimatedTokens)
             continue;
         candidates.push({
             runtimeEventId: event.id,

package/node_modules/@maka/runtime/dist/tool-runtime.js

@@ -1571,6 +1571,18 @@ export class ToolRuntime {
                     });
                 }
                 catch (error) {
+                    try {
+                        await input.tool.compensateDurableOutcomeCommitFailure?.({
+                            result,
+                            isError,
+                            sessionId: this.input.sessionId,
+                            operationId,
+                        });
+                    }
+                    catch {
+                        // T2 remains authoritative. Compensation is deliberately best-effort
+                        // and must never replace the persistence failure that triggered it.
+                    }
                     throw new RuntimeCommitBoundaryError('T2', error);
                 }
                 committedOutcome = {

package/node_modules/@maka/runtime-host/dist/adapter/session-projector.js

@@ -410,9 +410,6 @@ export class RuntimeHostSessionProjector {
                 recoverable: false,
                 reason: root.failureClass,
                 message: root.failureMessage ?? `Turn failed: ${root.failureClass}`,
-                ...(root.contextBudgetExhaustedDetail
-                    ? { details: { contextBudgetExhaustedDetail: root.contextBudgetExhaustedDetail } }
-                    : {}),
             });
         }
         else {

package/node_modules/@maka/runtime-host/dist/client/catalog-reader.js

@@ -30,6 +30,16 @@ export class RuntimeHostCatalogReadError extends Error {
         this.name = 'RuntimeHostCatalogReadError';
     }
 }
+export class RuntimeHostSessionCatalogRevisionChangedError extends Error {
+    expectedRevision;
+    actualRevision;
+    constructor(expectedRevision, actualRevision) {
+        super('Runtime Host Session catalog revision changed');
+        this.expectedRevision = expectedRevision;
+        this.actualRevision = actualRevision;
+        this.name = 'RuntimeHostSessionCatalogRevisionChangedError';
+    }
+}
 export async function readRuntimeHostConnectionCatalog(connection) {
     const { first, pages } = await collectStablePages('connection', async () => {
         const result = await connection.request('connection.catalog.query', { kind: 'start' });
@@ -105,21 +115,38 @@ export async function readRuntimeHostInvocableSkills(connection, target) {
     return pages.flatMap((page) => page.items);
 }
 export async function readRuntimeHostSessions(connection) {
-    const { pages } = await collectStablePages('session', async () => {
-        const result = await connection.request('session.catalog.query', {
-            kind: 'list_start',
-        });
-        return result.kind === 'page' ? result : null;
-    }, async (revision, cursor) => {
-        const result = await connection.request('session.catalog.query', {
-            kind: 'list_continue',
-            revision,
-            cursor,
-        });
-        return result.kind === 'page' ? result : null;
-    });
+    const readPageOrRestart = async (cursor) => {
+        try {
+            return await readRuntimeHostSessionCatalogPage(connection, cursor);
+        }
+        catch (error) {
+            if (error instanceof RuntimeHostSessionCatalogRevisionChangedError)
+                return null;
+            throw error;
+        }
+    };
+    const { pages } = await collectStablePages('session', () => readPageOrRestart(), (_revision, cursor) => readPageOrRestart(cursor));
     return pages.flatMap((page) => page.sessions);
 }
+export async function readRuntimeHostSessionCatalogPage(connection, cursor) {
+    const result = await connection.request('session.catalog.query', cursor
+        ? { kind: 'list_continue', revision: cursor.revision, cursor: cursor.cursor }
+        : { kind: 'list_start' });
+    if (result.kind === 'revision_changed') {
+        throw new RuntimeHostSessionCatalogRevisionChangedError(result.expectedRevision, result.actualRevision);
+    }
+    if (result.kind !== 'page' || (cursor && result.revision !== cursor.revision)) {
+        throw new RuntimeHostCatalogReadError('session', 'invalid_projection');
+    }
+    if (cursor && result.nextCursor === cursor.cursor) {
+        throw new RuntimeHostCatalogReadError('session', 'repeated_cursor');
+    }
+    return {
+        revision: result.revision,
+        sessions: result.sessions,
+        nextCursor: result.nextCursor === null ? null : { revision: result.revision, cursor: result.nextCursor },
+    };
+}
 export async function readRuntimeHostProjects(connection) {
     return readRuntimeHostProjectCatalog(connection, 'summary');
 }

package/node_modules/@maka/runtime-host/dist/client/connection.js

@@ -22,7 +22,7 @@ import { performance } from 'node:perf_hooks';
 import WebSocket from 'ws';
 import { discoverMarkedStorageRoot, prepareStorageRootControlDirectory, resolveExistingStorageRootControlDirectory, resolveStorageRoot, } from '@maka/storage/root-authority';
 import { readHostRegistration, RuntimeHostRegistrationError } from '../control/registration.js';
-import { decodeHostFrame, encodeProtocolMessage, isClientCapabilityHostFrameKind, HOST_OPERATION_SPECS, INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID, RUNTIME_HOST_COMPATIBILITY_EPOCH, RUNTIME_HOST_MAX_IN_FLIGHT_DOMAIN_REQUESTS, RUNTIME_HOST_MAX_MESSAGE_BYTES, requireClientInstanceId, requireHostCompositionId, requireHostGeneration, requireHostRootId, validateProtocolRange, } from '../protocol/index.js';
+import { decodeHostFrame, encodeProtocolMessage, isClientCapabilityHostFrameKind, isHostActivityIdle, HOST_OPERATION_SPECS, INTERACTIVE_RUNTIME_HOST_COMPOSITION_ID, RUNTIME_HOST_COMPATIBILITY_EPOCH, RUNTIME_HOST_MAX_IN_FLIGHT_DOMAIN_REQUESTS, RUNTIME_HOST_MAX_MESSAGE_BYTES, requireClientInstanceId, requireHostCompositionId, requireHostGeneration, requireHostRootId, validateProtocolRange, } from '../protocol/index.js';
 import { FramedTransport, RuntimeHostTransportError } from '../transport/framed-transport.js';
 import { WebSocketTransport } from '../transport/websocket-transport.js';
 import { ClientSessionSubscription, RuntimeHostSubscriptionError, } from './session-subscription.js';
@@ -94,17 +94,20 @@ class RuntimeHostConnectionImpl {
     #sessionCatalogChangeListeners = new Set();
     #scheduledTaskChangeListeners = new Set();
     #livenessTimer;
+    #livenessProbeDeadline;
     #livenessProbePending = false;
     #inFlightDomainRequests = 0;
     #terminalError;
     #livenessIntervalMs;
     #onLivenessProbe;
+    #onHostStatus;
     constructor(transport, accepted, 
     // livenessIntervalMs is validated by connectResolvedRuntimeHost alongside
     // the other connect timeouts, before any transport work happens.
     options) {
         this.#livenessIntervalMs = options?.livenessIntervalMs ?? DEFAULT_LIVENESS_INTERVAL_MS;
         this.#onLivenessProbe = options?.onLivenessProbe;
+        this.#onHostStatus = options?.onHostStatus;
         this.#transport = transport;
         this.rootId = accepted.rootId;
         this.hostEpoch = accepted.hostEpoch;
@@ -131,6 +134,7 @@ class RuntimeHostConnectionImpl {
             onFailure: (error) => this.#fail(error),
         });
         void this.#readResponses();
+        this.#scheduleLivenessCheck();
     }
     request(operation, input, timeoutMs) {
         if (isHostStatusOperation(operation)) {
@@ -180,7 +184,6 @@ class RuntimeHostConnectionImpl {
                 ...(isDomainRequest ? { domainState: 'queued' } : {}),
                 timer,
             });
-            this.#scheduleLivenessCheck();
         });
         const frame = {
             requestId,
@@ -221,6 +224,12 @@ class RuntimeHostConnectionImpl {
             this.#fail(error);
             throw error;
         }
+        try {
+            this.#onHostStatus?.(status);
+        }
+        catch {
+            // Observation cannot control the authenticated connection it watches.
+        }
         return status;
     }
     openSessionSubscription(input, timeoutMs) {
@@ -333,7 +342,6 @@ class RuntimeHostConnectionImpl {
             if (retired?.operation === frame.operation) {
                 this.#retiredRequests.delete(frame.requestId);
                 this.#releaseDomainSlot(retired);
-                this.#scheduleLivenessCheck();
                 return;
             }
             this.#fail(new Error('Runtime Host returned an unmatched operation response'));
@@ -346,7 +354,6 @@ class RuntimeHostConnectionImpl {
         this.#pendingRequests.delete(frame.requestId);
         if (pending.timer)
             clearTimeout(pending.timer);
-        this.#scheduleLivenessCheck();
         if (frame.ok) {
             try {
                 const accepted = pending.accept(frame.result);
@@ -423,7 +430,6 @@ class RuntimeHostConnectionImpl {
             if (index !== -1)
                 this.#queuedDomainFrames.splice(index, 1);
             pending.reject(interruptedRequestError(pending.operation, 'not_dispatched', 'timeout', error));
-            this.#scheduleLivenessCheck();
             return;
         }
         this.#retiredRequests.set(requestId, {
@@ -431,7 +437,6 @@ class RuntimeHostConnectionImpl {
             ...(pending.domainState === 'in_flight' ? { domainState: pending.domainState } : {}),
         });
         pending.reject(interruptedRequestError(pending.operation, 'dispatched', 'timeout', error));
-        this.#scheduleLivenessCheck();
     }
     #releaseDomainSlot(request) {
         if (request.domainState !== 'in_flight')
@@ -441,20 +446,20 @@ class RuntimeHostConnectionImpl {
         this.#drainDomainRequests();
     }
     #resetLivenessCheck() {
+        // Any authenticated Host frame proves the transport is still making
+        // progress, even when a periodic status observation is slow.
+        this.#resetLivenessProbeDeadline();
+        // A status observer needs periodic route observations even while other
+        // Session traffic keeps the connection active.
+        if (this.#onHostStatus)
+            return;
         if (this.#livenessTimer)
             clearTimeout(this.#livenessTimer);
         this.#livenessTimer = undefined;
         this.#scheduleLivenessCheck();
     }
     #scheduleLivenessCheck() {
-        if (this.#terminalError ||
-            this.#livenessTimer ||
-            this.#livenessProbePending ||
-            !this.#hasOutstandingDomainRequest()) {
-            if (!this.#hasOutstandingDomainRequest() && this.#livenessTimer) {
-                clearTimeout(this.#livenessTimer);
-                this.#livenessTimer = undefined;
-            }
+        if (this.#terminalError || this.#livenessTimer || this.#livenessProbePending) {
             return;
         }
         this.#livenessTimer = setTimeout(() => {
@@ -462,21 +467,12 @@ class RuntimeHostConnectionImpl {
             this.#startLivenessProbe();
         }, this.#livenessIntervalMs);
     }
-    #hasOutstandingDomainRequest() {
-        if (this.#retiredRequests.size > 0)
-            return true;
-        for (const pending of this.#pendingRequests.values()) {
-            if (pending.operation !== 'host.status')
-                return true;
-        }
-        return false;
-    }
     #startLivenessProbe() {
-        if (this.#terminalError || this.#livenessProbePending || !this.#hasOutstandingDomainRequest()) {
+        if (this.#terminalError || this.#livenessProbePending)
             return;
-        }
         this.#livenessProbePending = true;
-        void this.#requestOperation('host.status', {}, DEFAULT_LIVENESS_TIMEOUT_MS, (status) => {
+        this.#resetLivenessProbeDeadline();
+        void this.#requestOperation('host.status', {}, undefined, (status) => {
             this.#validateHostStatusIdentity(status);
             try {
                 this.#onLivenessProbe?.();
@@ -485,13 +481,26 @@ class RuntimeHostConnectionImpl {
                 // Diagnostics hook: an observer exception must never fail the
                 // connection it is watching.
             }
-        }, 'connection')
+        }, 'request')
             .catch((error) => this.#fail(asError(error)))
             .finally(() => {
+            if (this.#livenessProbeDeadline)
+                clearTimeout(this.#livenessProbeDeadline);
+            this.#livenessProbeDeadline = undefined;
             this.#livenessProbePending = false;
             this.#scheduleLivenessCheck();
         });
     }
+    #resetLivenessProbeDeadline() {
+        if (!this.#livenessProbePending || this.#terminalError)
+            return;
+        if (this.#livenessProbeDeadline)
+            clearTimeout(this.#livenessProbeDeadline);
+        this.#livenessProbeDeadline = setTimeout(() => {
+            this.#livenessProbeDeadline = undefined;
+            this.#fail(requestTimeoutError('host.status'));
+        }, DEFAULT_LIVENESS_TIMEOUT_MS);
+    }
     #acceptSubscriptionFrame(frame) {
         const subscription = this.#subscriptions.get(frame.subscriptionId);
         if (!subscription) {
@@ -545,6 +554,9 @@ class RuntimeHostConnectionImpl {
         if (this.#livenessTimer)
             clearTimeout(this.#livenessTimer);
         this.#livenessTimer = undefined;
+        if (this.#livenessProbeDeadline)
+            clearTimeout(this.#livenessProbeDeadline);
+        this.#livenessProbeDeadline = undefined;
         this.#queuedDomainFrames.length = 0;
         this.#inFlightDomainRequests = 0;
         for (const pending of this.#pendingRequests.values()) {
@@ -628,6 +640,7 @@ export async function connectRemoteRuntimeHost(input) {
             handshakeTimeoutMs: normalized.handshakeTimeoutMs,
             livenessIntervalMs: normalized.livenessIntervalMs,
             onLivenessProbe: input.onLivenessProbe,
+            onHostStatus: input.onHostStatus,
             connectionResource: input.connectionResource,
         });
     }
@@ -639,11 +652,13 @@ export async function connectRemoteRuntimeHost(input) {
 export async function connectRuntimeHostMessageTransport(input) {
     let resourceTransferred = false;
     let timer;
+    let handshakeTimedOut = false;
     try {
         const normalized = normalizeConnectRuntimeHostInput(input);
         const compositionId = requireHostCompositionId(input.compositionId);
         const expectedRootId = requireHostRootId(input.expectedRootId);
         timer = setTimeout(() => {
+            handshakeTimedOut = true;
             input.transport.abort(new Error('Timed out handshaking with Runtime Host'));
         }, normalized.handshakeTimeoutMs);
         const result = await exchangeRuntimeHostHandshake({
@@ -654,6 +669,7 @@ export async function connectRuntimeHostMessageTransport(input) {
             expectedRootId,
             livenessIntervalMs: normalized.livenessIntervalMs,
             onLivenessProbe: input.onLivenessProbe,
+            onHostStatus: input.onHostStatus,
             connectionResource: input.connectionResource,
             ...(input.peerPath ? { peerPath: input.peerPath } : {}),
         });
@@ -672,7 +688,10 @@ export async function connectRuntimeHostMessageTransport(input) {
         if (error instanceof RuntimeHostCompositionMismatchError) {
             return { kind: 'unavailable', reason: 'composition_mismatch' };
         }
-        return { kind: 'unavailable', reason: 'handshake_failed' };
+        return {
+            kind: 'unavailable',
+            reason: handshakeTimedOut ? 'handshake_timed_out' : 'handshake_failed',
+        };
     }
     finally {
         if (timer)
@@ -819,6 +838,7 @@ export async function connectResolvedRuntimeHost(input) {
             hostProtocol: { min: registration.protocolMin, max: registration.protocolMax },
             livenessIntervalMs,
             onLivenessProbe: input.onLivenessProbe,
+            onHostStatus: input.onHostStatus,
         });
         if (result.kind === 'connected') {
             if (generation !== undefined &&
@@ -838,9 +858,7 @@ export async function connectResolvedRuntimeHost(input) {
             return registration.lifecycleMode === 'ephemeral' &&
                 result.handshake.state === 'ready' &&
                 result.handshake.activity !== undefined &&
-                result.handshake.activity.connections === 0 &&
-                result.handshake.activity.activeOperations === 0 &&
-                result.handshake.activity.residencies.length === 0
+                isHostActivityIdle(result.handshake.activity)
                 ? {
                     kind: 'upgrade_required',
                     registration,
@@ -954,6 +972,7 @@ async function exchangeRuntimeHostHandshake(input) {
         connection: new RuntimeHostConnectionImpl(input.transport, handshake, {
             livenessIntervalMs: input.livenessIntervalMs,
             onLivenessProbe: input.onLivenessProbe,
+            onHostStatus: input.onHostStatus,
             connectionResource: input.connectionResource,
             ...(input.peerPath ? { peerPath: input.peerPath } : {}),
         }),

package/node_modules/@maka/runtime-host/dist/client/host-profile.js

@@ -41,6 +41,7 @@ const PROFILE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const PEER_ID_MAX_BYTES = 160;
 const PEER_ADDRESS_MAX_BYTES = 2 * 1024;
 const PEER_ROUTE_MAX = 16;
+const DEFAULT_PEER_HANDSHAKE_TIMEOUT_MS = 5_000;
 const PROFILE_CREDENTIAL_RECORD_PREFIX = 'maka-runtime-host-profile-credential-v1:';
 const PROFILE_INCARNATION_ID_MAX_BYTES = 128;
 export const RUNTIME_HOST_ACCESS_CREDENTIAL_MAX_BYTES = 8 * 1024;
@@ -173,6 +174,9 @@ export async function connectRemoteRuntimeHostProfile(input, overrides = {}) {
             expectedRootId: input.profile.rootId,
             clientInstanceId: input.clientInstanceId,
             peerClient: requireRuntimeHostPeerClient(input.peerClient),
+            ...(input.refreshPeerRoutes === undefined
+                ? {}
+                : { refreshPeerRoutes: input.refreshPeerRoutes }),
             ...(input.signal === undefined ? {} : { signal: input.signal }),
             ...(input.connectTimeoutMs === undefined ? {} : { connectTimeoutMs: input.connectTimeoutMs }),
             ...(input.handshakeTimeoutMs === undefined
@@ -181,6 +185,7 @@ export async function connectRemoteRuntimeHostProfile(input, overrides = {}) {
             ...(input.onConnectionPhase === undefined
                 ? {}
                 : { onConnectionPhase: input.onConnectionPhase }),
+            ...(input.onHostStatus === undefined ? {} : { onHostStatus: input.onHostStatus }),
         });
     }
     else {
@@ -224,6 +229,7 @@ export async function connectRemoteRuntimeHostProfile(input, overrides = {}) {
             ...(input.handshakeTimeoutMs === undefined
                 ? {}
                 : { handshakeTimeoutMs: input.handshakeTimeoutMs }),
+            ...(input.onHostStatus === undefined ? {} : { onHostStatus: input.onHostStatus }),
         });
         try {
             input.signal?.throwIfAborted();
@@ -272,11 +278,13 @@ function requireConnectOnlySshEndpoint(transport) {
 }
 export async function connectPeerRuntimeHost(input) {
     input.signal?.throwIfAborted();
+    const handshakeTimeoutMs = input.handshakeTimeoutMs ?? DEFAULT_PEER_HANDSHAKE_TIMEOUT_MS;
     const stream = await input.peerClient.connect({
         peerId: input.transport.peerId,
         routeHints: input.transport.routeHints,
         coordinationRelays: input.transport.coordinationRelays,
         directDeadlineMs: Math.min(input.connectTimeoutMs ?? 40_000, 120_000),
+        ...(input.refreshPeerRoutes === undefined ? {} : { refreshRoutes: input.refreshPeerRoutes }),
     }, input.signal, input.onConnectionPhase);
     const abort = () => stream.abort();
     input.signal?.addEventListener('abort', abort, { once: true });
@@ -287,7 +295,7 @@ export async function connectPeerRuntimeHost(input) {
         input.signal?.throwIfAborted();
         notifyConnectionPhase(input.onConnectionPhase, 'authenticating');
         await writeRuntimeHostPeerAuthentication(stream, input.credential);
-        const authentication = await readRuntimeHostPeerAuthenticationResult(stream, input.handshakeTimeoutMs);
+        const authentication = await readRuntimeHostPeerAuthenticationResult(stream, handshakeTimeoutMs);
         if (!authentication.accepted) {
             throw new RuntimeHostProfileConnectionError('credential_rejected', `Runtime Host profile ${input.profileId} rejected its access credential`);
         }
@@ -301,9 +309,14 @@ export async function connectPeerRuntimeHost(input) {
                 max: RUNTIME_HOST_PROTOCOL_VERSION,
             },
             clientInstanceId: input.clientInstanceId,
-            ...(input.handshakeTimeoutMs === undefined
-                ? {}
-                : { handshakeTimeoutMs: input.handshakeTimeoutMs }),
+            handshakeTimeoutMs,
+            onHostStatus: (status) => {
+                const endpoint = status.peerEndpoint;
+                if (endpoint?.peerId === input.transport.peerId) {
+                    input.peerClient.observeAuthenticatedRoutes(endpoint);
+                }
+                input.onHostStatus?.(status);
+            },
             ...(stream.path ? { peerPath: stream.path } : {}),
         });
         input.signal?.throwIfAborted();
@@ -357,6 +370,9 @@ export function remoteRuntimeHostUnavailableError(subject, reason) {
         case 'unreachable':
             message = `${subject} could not reach its endpoint`;
             break;
+        case 'handshake_timed_out':
+            message = `${subject} timed out while establishing its protocol session`;
+            break;
         default:
             message = `${subject} is unavailable (${reason})`;
     }
@@ -589,6 +605,34 @@ class FileRuntimeHostProfileCatalog {
             return { rebound: true, document: next };
         });
     }
+    updateRemoteProfileIfCurrent(target, update) {
+        const expectedProfile = decodeRemoteRuntimeHostProfile(target.profile);
+        const expectedIncarnationId = requireProfileIncarnationId(target.profileIncarnationId);
+        return this.#exclusive(async () => {
+            const current = await this.#readSnapshot();
+            const profile = current.profiles.find((candidate) => candidate.id === expectedProfile.id && candidate.kind === 'remote');
+            if (!profile || !sameRemoteRuntimeHostProfileTarget(profile, expectedProfile))
+                return false;
+            const credential = await this.credentials.get(profile);
+            if (credential?.profileIncarnationId !== expectedIncarnationId)
+                return false;
+            const value = update(profile);
+            if (value === profile)
+                return true;
+            const updated = decodeRemoteRuntimeHostProfile(value);
+            if (updated.id !== profile.id ||
+                !sameRemoteRuntimeHostProfileTarget(updated, profile) ||
+                runtimeHostProfileAccess(updated) !== runtimeHostProfileAccess(profile)) {
+                throw new Error('A Runtime Host profile metadata update must retain its connection');
+            }
+            const next = decodeRuntimeHostProfileDocument({
+                schemaVersion: PROFILE_SCHEMA_VERSION,
+                profiles: current.profiles.map((candidate) => candidate.id === updated.id ? updated : candidate),
+            });
+            await writeProfileDocument(this.path, next);
+            return true;
+        });
+    }
     mutateRemoteProfileIfCurrent(target, mutation) {
         const expectedProfile = decodeRemoteRuntimeHostProfile(target.profile);
         const expectedIncarnationId = requireProfileIncarnationId(target.profileIncarnationId);

package/node_modules/@maka/runtime-host/dist/client/index.js

@@ -30,7 +30,7 @@ export { RUNTIME_HOST_REMOTE_INCOMPATIBLE_CODE, RuntimeHostRemoteCompatibilityEr
 export { RuntimeHostSubscriptionError, } from './session-subscription.js';
 export { RuntimeHostStartupError, runtimeHostStartupError, } from './startup-error.js';
 export { connectRuntimeHostWslEnvironment, listRuntimeHostWslDistributions, normalizeRuntimeHostWslDistribution, normalizeRuntimeHostWslOperatorPath, resolveSystemRuntimeHostWslExecutable, } from './wsl-environment.js';
-export { RuntimeHostCatalogReadError, readRuntimeHostConnectionCatalog, readRuntimeHostInvocableSkills, readRuntimeHostProjectDetails, readRuntimeHostResources, readRuntimeHostProjects, readRuntimeHostSessions, readRuntimeHostSkillCatalog, } from './catalog-reader.js';
+export { RuntimeHostCatalogReadError, RuntimeHostSessionCatalogRevisionChangedError, readRuntimeHostConnectionCatalog, readRuntimeHostInvocableSkills, readRuntimeHostProjectDetails, readRuntimeHostResources, readRuntimeHostProjects, readRuntimeHostSessionCatalogPage, readRuntimeHostSessions, readRuntimeHostSkillCatalog, } from './catalog-reader.js';
 export { connectOrSpawnRuntimeHost, } from './connect-or-spawn.js';
 export { abortable, waitForRuntimeHostReady } from './wait-for-ready.js';
 export { createRuntimeHostCandidateLaunchBarrier, } from './candidate-launch-barrier.js';
@@ -40,7 +40,7 @@ export { startRuntimeHostCapabilityProviderService, } from './capability-provide
 export { loadOrCreateRuntimeHostClientInstanceId } from './client-instance-identity.js';
 export { projectSessionCatalogSummary } from './session-catalog-summary.js';
 export { consumeAccessCredentialDelivery } from '../control/access-credential-delivery.js';
-export { decodeRuntimeHostOwnerConnectionCode, encodeRuntimeHostOwnerConnectionCode, } from './owner-connection-code.js';
+export { decodeRuntimeHostOwnerConnectionCode, encodeRuntimeHostOwnerConnectionCode, issueRuntimeHostOwnerConnectionCode, REMOTE_DESKTOP_OWNER_ACCESS_POLICY, } from './owner-connection-code.js';
 export { ensureRuntimeHostPeerIdentity } from '../transport/peer-native.js';
 export { createRuntimeHostPeerClient, createRuntimeHostPeerClientFromEnvironment, } from './peer-client.js';
 export { createOAuthPresentationClientProvider, } from './oauth-presentation.js';

package/node_modules/@maka/runtime-host/dist/client/owner-connection-code.js

@@ -17,14 +17,22 @@
  * under the License.
  */
 import { z } from 'zod';
-import { requireHostRootId } from '../protocol/index.js';
+import { consumeAccessCredentialDelivery } from '../control/access-credential-delivery.js';
+import { REMOTE_OWNER_OPERATION_GRANTS, requireHostRootId } from '../protocol/index.js';
 import { decodeRuntimeHostRemoteTransport, RUNTIME_HOST_ACCESS_CREDENTIAL_MAX_BYTES, } from './host-profile.js';
 const PREFIX = 'maka-runtime-host:connect:v1:';
 const ENCODED_MAX_BYTES = 48 * 1024;
+export const REMOTE_DESKTOP_OWNER_ACCESS_POLICY = Object.freeze({
+    principalKind: 'remote_owner',
+    operationGrants: REMOTE_OWNER_OPERATION_GRANTS,
+    canPublishClientCapabilities: true,
+    canUseHostPaths: false,
+});
 const boundedString = (maxBytes) => z
     .string()
     .min(1)
     .refine((value) => Buffer.byteLength(value, 'utf8') <= maxBytes);
+const nameSchema = boundedString(128);
 const payloadSchema = z
     .object({
     schemaVersion: z.literal(1),
@@ -42,6 +50,29 @@ const payloadSchema = z
     credential: boundedString(RUNTIME_HOST_ACCESS_CREDENTIAL_MAX_BYTES),
 })
     .strict();
+/**
+ * Issue one pending Owner credential and bind it to the Host's current,
+ * authenticated Direct peer endpoint. The credential remains one-time and
+ * short-lived until the importing Client finalizes it.
+ */
+export async function issueRuntimeHostOwnerConnectionCode(input) {
+    const name = nameSchema.parse(input.name);
+    const rootId = requireHostRootId(input.client.rootId);
+    const endpoint = (await input.client.status()).peerEndpoint;
+    if (!endpoint)
+        throw new Error('Runtime Host Direct peer is not available');
+    if (input.expectedPeerId && endpoint.peerId !== input.expectedPeerId) {
+        throw new Error('Runtime Host Direct peer identity changed');
+    }
+    const transport = requireDirectPeerTransport({ kind: 'libp2p-direct', ...endpoint });
+    const prepared = await input.client.request('access.credential.prepare', {
+        ...REMOTE_DESKTOP_OWNER_ACCESS_POLICY,
+        principalId: input.principalId,
+        bindClientInstance: true,
+    });
+    const credential = await consumeAccessCredentialDelivery(input.rootPath, prepared.deliveryId, prepared.credentialId);
+    return encodeRuntimeHostOwnerConnectionCode({ name, rootId, transport, credential });
+}
 export function encodeRuntimeHostOwnerConnectionCode(input) {
     const transport = requireDirectPeerTransport(input.transport);
     const payload = payloadSchema.parse({ schemaVersion: 1, ...input, transport });

package/node_modules/@maka/runtime-host/dist/client/peer-client.js

@@ -38,6 +38,7 @@ class RuntimeHostPeerClientImpl {
     #automaticRelayDiscovery;
     #webRtcStunUrls;
     #routeResolver;
+    #authenticatedRoutes = new Map();
     #endpoint;
     #draining;
     #meshDraining;
@@ -95,9 +96,19 @@ class RuntimeHostPeerClientImpl {
             throw normalizePeerError(error);
         });
     }
+    observeAuthenticatedRoutes(input) {
+        if (input.routeHints.length === 0 && input.coordinationRelays.length === 0)
+            return;
+        this.#authenticatedRoutes.set(input.peerId, Object.freeze({
+            routeHints: Object.freeze([...input.routeHints]),
+            coordinationRelays: Object.freeze([...input.coordinationRelays]),
+        }));
+    }
     async connect(input, signal, onPhase) {
-        notifyPhase(onPhase, 'discovering');
-        await this.#prepareRoutes(input, signal);
+        if (input.refreshRoutes !== false) {
+            notifyPhase(onPhase, 'discovering');
+            await this.#prepareRoutes(input, signal);
+        }
         notifyPhase(onPhase, 'connecting');
         return this.#connect(input, signal, 'application');
     }
@@ -193,10 +204,17 @@ class RuntimeHostPeerClientImpl {
         const endpoint = this.#requireEndpoint();
         const requestId = this.#allocateRequestId();
         const discovered = kind === 'application' ? this.#routeResolver?.resolveRoutes(input.peerId) : undefined;
+        const authenticated = kind === 'application' ? this.#authenticatedRoutes.get(input.peerId) : undefined;
         const connection = endpoint[kind === 'application' ? 'connect' : 'connectMeshControl']({
             ...input,
-            routeHints: mergeAddresses(discovered?.routeHints ?? [], input.routeHints),
-            coordinationRelays: mergeAddresses(discovered?.coordinationRelays ?? [], input.coordinationRelays),
+            routeHints: mergeAddresses(discovered?.routeHints ?? [], [
+                ...(authenticated?.routeHints ?? []),
+                ...input.routeHints,
+            ]),
+            coordinationRelays: mergeAddresses(discovered?.coordinationRelays ?? [], [
+                ...(authenticated?.coordinationRelays ?? []),
+                ...(input.coordinationRelays ?? []),
+            ]),
             transitRelayPeerIds: mergeValues(discovered?.transitRelayPeerIds ?? [], input.transitRelayPeerIds, 64),
             requestId,
         });