maka-agent 0.2.0-dev.4.20260830 → 0.2.0-dev.41.20260918

package/node_modules/@maka/runtime-host/dist/server/host-kernel.js

@@ -25,11 +25,12 @@ import { removeHostRegistration, writeHostRegistration } from '../control/regist
 import { decodeClientFrame, encodeProtocolMessage, HOST_OPERATION_SPECS, negotiateProtocol, RUNTIME_HOST_COMPATIBILITY_EPOCH, RUNTIME_HOST_PROTOCOL_VERSION, RUNTIME_HOST_REGISTRATION_SCHEMA_VERSION, requireHostGeneration, } from '../protocol/index.js';
 import { RuntimeHostConnectionSession, } from './connection-session.js';
 import { composeOperationHandlers, createUnavailableDomainOperationHandlers, } from './operation-dispatcher.js';
-import { issueAccessCredential, acknowledgeCollaborationTurnRequest, createCollaborationTurnRequest, decideCollaborationTurnRequest, finalizeAccessCredential, prepareCollaborationInvitation, queryCollaborationTurnRequests, prepareAccessCredential, prepareAccessCredentialRotation, replaceAccessCredential, revokeAccessCredential, revokeAccessPrincipal, revokeAccessCredentialRotation, revokeCollaborationGrant, revokeCollaborationPrincipal, } from './access-authority.js';
+import { issueAccessCredential, acknowledgeCollaborationTurnRequest, createCollaborationTurnRequest, decideCollaborationTurnRequest, withdrawCollaborationTurnRequest, finalizeAccessCredential, prepareCollaborationInvitation, queryCollaborationTurnRequests, prepareAccessCredential, prepareAccessCredentialRotation, replaceAccessCredential, revokeAccessCredential, revokeAccessPrincipal, revokeAccessCredentialRotation, revokeCollaborationGrant, revokeCollaborationPrincipal, renameCollaborationPrincipal, } from './access-authority.js';
 import { runtimeHostLogBuffer } from '../process-diagnostics.js';
 import { startLocalRuntimeHostListenerSet, } from './listener-set.js';
 import { HostResidencyRegistry } from './host-residency-registry.js';
 import { createPeerMeshOperationHandlers } from './peer-mesh-authority.js';
+import { createHostResourceCollector } from './host-resource-collector.js';
 const DEFAULT_IDLE_GRACE_MS = 30_000;
 const DEFAULT_HANDSHAKE_TIMEOUT_MS = 5_000;
 const DEFAULT_SHUTDOWN_GRACE_MS = 10_000;
@@ -60,6 +61,7 @@ export class RuntimeHostKernel {
     #transportAuthorities = new Map();
     #operationDrainWaiters = new Set();
     #residencies = new HostResidencyRegistry();
+    #resourceCollector = createHostResourceCollector();
     #lifecycle;
     #handshakeTimeoutMs;
     #shutdownGraceMs;
@@ -68,6 +70,7 @@ export class RuntimeHostKernel {
     #hasAcceptedConnection = false;
     #activeOperations = 0;
     #activeCommandOperations = 0;
+    #handoff;
     #retainedUntilProcessExit = false;
     #composition;
     #compositionDrainBegun = false;
@@ -162,7 +165,8 @@ export class RuntimeHostKernel {
     get compositionDescriptor() {
         return this.#options.composition.descriptor;
     }
-    close() {
+    close(input) {
+        this.#shutdownReason ??= input?.reason;
         this.#requestDrain();
         return this.closed;
     }
@@ -201,7 +205,7 @@ export class RuntimeHostKernel {
                 this.#composition = await this.#options.composition.create({
                     owner: this.#options.owner,
                     hostEpoch: this.hostEpoch,
-                    acquireResidency: (label) => this.#acquireResidency(label),
+                    acquireResidency: (label, kind) => this.#acquireResidency(label, kind),
                     retainUntilProcessExit: () => this.#retainUntilProcessExit(),
                     requestDrain: () => this.#requestDrain(),
                     ...(this.#options.accessAuthority
@@ -228,6 +232,8 @@ export class RuntimeHostKernel {
         }
         this.#state = 'ready';
         await this.#publishRegistration();
+        if (!this.#shutdownRequested)
+            this.#composition?.startMaintenance?.();
         this.#scheduleIdleIfNeeded();
     }
     #accept(connection) {
@@ -237,6 +243,9 @@ export class RuntimeHostKernel {
         void this.#serveConnection(connection).finally(() => {
             this.#handshakingTransports.delete(transport);
             this.#transportAuthorities.delete(transport);
+            // A handshake that never completes keeps the Host visible to the idle
+            // timer while it is in flight; once it settles, idle must re-evaluate.
+            this.#scheduleIdleIfNeeded();
         });
     }
     async #serveConnection(connection) {
@@ -300,7 +309,17 @@ export class RuntimeHostKernel {
     }
     async #admitHandshake(hello, transport, authority) {
         const admittedState = await this.#readAdmissionState();
-        if (!admittedState) {
+        if (!admittedState || this.#handoff) {
+            return {
+                kind: 'draining',
+                hostEpoch: this.hostEpoch,
+                compositionId: this.compositionDescriptor.id,
+                compositionRevision: this.compositionDescriptor.revision,
+            };
+        }
+        const initialClientAdmission = this.#options.initialClientAdmission;
+        if (initialClientAdmission &&
+            !initialClientAdmission.isClientAdmitted(hello.clientInstanceId)) {
             return {
                 kind: 'draining',
                 hostEpoch: this.hostEpoch,
@@ -321,7 +340,13 @@ export class RuntimeHostKernel {
             hello.generation !== undefined &&
             hello.generation !== this.#options.generation;
         if (generationMismatch && hello.takeover?.expectedHostEpoch === this.hostEpoch) {
-            if (authority.principalKind === 'local_owner' && this.#isTrueIdle()) {
+            const residencyCount = hello.activitySnapshotVersion === 2
+                ? this.#residencies.drainCount
+                : this.#residencies.activeCount;
+            if (authority.principalKind === 'local_owner' &&
+                residencyCount === 0 &&
+                this.#hasNoObservedWork(transport)) {
+                this.#shutdownReason = 'retirement';
                 this.#requestDrain();
                 return {
                     kind: 'draining',
@@ -345,11 +370,12 @@ export class RuntimeHostKernel {
                 compositionRevision: this.compositionDescriptor.revision,
                 ...(this.#options.generation === undefined ? {} : { generation: this.#options.generation }),
                 state: admittedState,
-                replacement: this.#lifecycle.kind === 'ephemeral' && this.#isTrueIdle()
+                replacement: this.#lifecycle.kind === 'ephemeral' && this.#isSettledForReplacementAdvice()
                     ? 'wait_for_idle_exit'
                     : 'blocked_by_residency',
-                ...(generationMismatch && authority.principalKind === 'local_owner'
-                    ? { activity: this.#activitySnapshot() }
+                ...(authority.principalKind === 'local_owner' &&
+                    (generationMismatch || hello.activitySnapshotVersion === 2)
+                    ? { activity: this.#activitySnapshot(hello.activitySnapshotVersion) }
                     : {}),
             };
         }
@@ -360,6 +386,9 @@ export class RuntimeHostKernel {
         this.#cancelIdle();
         return {
             kind: 'accepted',
+            ...(hello.activitySnapshotVersion === 2 && this.#composition?.prepareHandoff
+                ? { cooperativeHandoff: true }
+                : {}),
             rootId: this.#options.owner.capability.rootId,
             hostEpoch: this.hostEpoch,
             connectionId: randomUUID(),
@@ -385,6 +414,10 @@ export class RuntimeHostKernel {
     async #beginOperation(frame) {
         if (!(await this.#readAdmissionState()))
             return 'host_draining';
+        if (this.#handoff &&
+            HOST_OPERATION_SPECS[frame.operation].mode === 'command' &&
+            (this.#handoff.commandsClosed || frame.operation !== 'turn.stop'))
+            return 'host_draining';
         if (HOST_OPERATION_SPECS[frame.operation].availability !== 'bootstrap' &&
             this.#state !== 'ready') {
             return 'host_not_ready';
@@ -458,21 +491,18 @@ export class RuntimeHostKernel {
         }
         this.#settleLifecycleAfterWork();
     }
-    #acquireResidency(label) {
-        const residency = this.#residencies.acquire(label);
+    #acquireResidency(label, kind = 'drain') {
+        const residency = this.#residencies.acquire(label, kind, () => this.#settleLifecycleAfterWork());
         this.#cancelIdle();
-        return {
-            release: () => {
-                residency.release();
-                this.#settleLifecycleAfterWork();
-            },
-        };
+        return residency;
     }
     #retainUntilProcessExit() {
         if (this.#retainedUntilProcessExit)
             return;
         this.#retainedUntilProcessExit = true;
-        this.#residencies.acquire('process-retention');
+        // Not work in flight: the marker only blocks idle exit, so it must not
+        // stall the drain it accompanies.
+        this.#residencies.acquire('process-retention', 'idle');
         this.#cancelIdle();
     }
     #createOperationHandlers(domainHandlers) {
@@ -485,6 +515,7 @@ export class RuntimeHostKernel {
                 ok: true,
                 result: {
                     ...this.#statusSnapshot(),
+                    upgradeBlockingActivity: this.#hasUpgradeBlockingActivity(0),
                     compositionModules: this.#composition?.moduleIds ?? [],
                     residencies: this.#residencies.snapshot(),
                     protocolVersion: RUNTIME_HOST_PROTOCOL_VERSION,
@@ -500,7 +531,11 @@ export class RuntimeHostKernel {
                         .map((entry) => collapseHomePath(entry, homedir(), process.platform)),
                 },
             }),
-            'host.upgrade.prepare': async (input) => {
+            'host.resources.query': async () => ({
+                ok: true,
+                result: await this.#resourceCollector.snapshot(this.hostEpoch),
+            }),
+            'host.upgrade.prepare': async (input, context) => {
                 if (input.expectedHostEpoch !== this.hostEpoch) {
                     return {
                         ok: false,
@@ -510,8 +545,11 @@ export class RuntimeHostKernel {
                         },
                     };
                 }
-                if (!input.allowInterruptActiveTasks && this.#hasUpgradeBlockingActivity()) {
-                    return { ok: true, result: { kind: 'active_tasks' } };
+                if (!input.allowInterruptActiveTasks && this.#hasUpgradeBlockingActivity(1)) {
+                    if (!input.allowCooperativeHandoff ||
+                        !(await this.#prepareCooperativeHandoff(context.inputClosedSignal))) {
+                        return { ok: true, result: { kind: 'active_tasks' } };
+                    }
                 }
                 this.#shutdownReason = 'retirement';
                 this.#requestDrain();
@@ -539,6 +577,7 @@ export class RuntimeHostKernel {
                     },
                 },
             'collaboration.grant.revoke': async (input) => this.#settleAccessCredentialMutation(revokeCollaborationGrant(this.#options.accessAuthority, input)),
+            'collaboration.principal.rename': async (input) => renameCollaborationPrincipal(this.#options.accessAuthority, input),
             'collaboration.principal.revoke': async (input) => this.#settleAccessCredentialMutation(revokeCollaborationPrincipal(this.#options.accessAuthority, input.principalId)),
             'collaboration.turn-request.create': async (input, context) => this.#settleAccessCredentialMutation(createCollaborationTurnRequest(this.#options.accessAuthority, context.principal, input)),
             'collaboration.turn-request.query': async (input, context) => queryCollaborationTurnRequests(this.#options.accessAuthority, {
@@ -546,6 +585,7 @@ export class RuntimeHostKernel {
                 principalKind: context.principalKind,
             }, input),
             'collaboration.turn-request.acknowledge': async (input, context) => this.#settleAccessCredentialMutation(acknowledgeCollaborationTurnRequest(this.#options.accessAuthority, context.principal, input)),
+            'collaboration.turn-request.withdraw': async (input, context) => this.#settleAccessCredentialMutation(withdrawCollaborationTurnRequest(this.#options.accessAuthority, context.principal, input)),
             'collaboration.turn-request.decide': async (input, context) => this.#settleAccessCredentialMutation(decideCollaborationTurnRequest(this.#options.accessAuthority, context.principal, input)),
         }, createPeerMeshOperationHandlers(this.#options.peerMesh, {
             requestDrain: () => this.#requestDrain(),
@@ -559,6 +599,7 @@ export class RuntimeHostKernel {
         return outcome;
     }
     #statusSnapshot() {
+        const peer = this.peerListeners[0];
         return {
             hostEpoch: this.hostEpoch,
             compositionId: this.compositionDescriptor.id,
@@ -567,20 +608,95 @@ export class RuntimeHostKernel {
             connections: this.#acceptedTransports.size,
             activeOperations: this.#activeOperations,
             activeResidencies: this.#residencies.activeCount,
+            ...(peer
+                ? {
+                    peerEndpoint: peer.reachability,
+                }
+                : {}),
         };
     }
-    #activitySnapshot() {
+    #activitySnapshot(version) {
         return {
             connections: this.#acceptedTransports.size,
             activeOperations: this.#activeOperations,
             processUptimeSeconds: Math.max(0, Math.floor(process.uptime())),
             residencies: this.#residencies.snapshot(),
+            ...(version === 2
+                ? {
+                    drainResidencies: this.#residencies.drainCount,
+                    ...(this.#composition?.prepareHandoff ? { cooperativeHandoff: true } : {}),
+                }
+                : {}),
         };
     }
-    #hasUpgradeBlockingActivity() {
-        if (this.#activeCommandOperations > 1)
+    #hasUpgradeBlockingActivity(selfCommands) {
+        // The request's own accepted transport is expected. Any other live
+        // connection arrived after discovery or remained attached and therefore
+        // requires explicit interruption authority before retirement. Callers
+        // pass how many of the in-flight commands are their own: the
+        // `host.upgrade.prepare` command counts itself, while the diagnostics
+        // query path runs outside the command counter.
+        if (this.#acceptedTransports.size > 1)
+            return true;
+        if (this.#activeCommandOperations > selfCommands)
             return true;
-        return this.#residencies.snapshot().some(({ label }) => label !== 'process-retention');
+        return this.#residencies.drainCount > 0;
+    }
+    async #prepareCooperativeHandoff(inputClosedSignal) {
+        if (!inputClosedSignal ||
+            inputClosedSignal.aborted ||
+            !this.#composition?.prepareHandoff ||
+            this.#handoff ||
+            this.#acceptedTransports.size > 1 ||
+            this.#activeCommandOperations > 1)
+            return false;
+        const handoff = { abort: new AbortController(), commandsClosed: false, committing: false };
+        this.#handoff = handoff;
+        const cancelOnDisconnect = () => {
+            if (!handoff.committing)
+                handoff.abort.abort();
+        };
+        inputClosedSignal.addEventListener('abort', cancelOnDisconnect, { once: true });
+        const timer = setTimeout(() => handoff.abort.abort(), 10_000);
+        let prepared;
+        try {
+            prepared = await this.#composition.prepareHandoff(this.hostEpoch, handoff.abort.signal);
+            if (!prepared || handoff.abort.signal.aborted || this.#activeCommandOperations !== 1)
+                return false;
+            handoff.commandsClosed = true;
+            if (!(await prepared.seal()))
+                return false;
+            const residencies = await prepared.residencies();
+            if (!residencies ||
+                handoff.abort.signal.aborted ||
+                !(await this.#hasLiveOwnerOrDrain()) ||
+                handoff.abort.signal.aborted ||
+                this.#handoff !== handoff ||
+                this.#acceptedTransports.size !== 1 ||
+                this.#activeCommandOperations !== 1 ||
+                this.#residencies.hasDrainResidenciesExcept(residencies))
+                return false;
+            // No await between the final exact-handle proof and closing all command
+            // admission. After this cut cancellation must not restart the old runs.
+            handoff.committing = true;
+            clearTimeout(timer);
+            await prepared.detach();
+            return true;
+        }
+        finally {
+            clearTimeout(timer);
+            inputClosedSignal.removeEventListener('abort', cancelOnDisconnect);
+            if (handoff.committing) {
+                this.#shutdownReason = 'retirement';
+                this.#requestDrain();
+            }
+            else {
+                handoff.abort.abort();
+                prepared?.cancel();
+            }
+            if (this.#handoff === handoff)
+                this.#handoff = undefined;
+        }
     }
     #beginCompositionDrain() {
         if (!this.#composition || this.#compositionDrainBegun)
@@ -606,8 +722,9 @@ export class RuntimeHostKernel {
             return;
         // One timer authority per lifecycle phase: until the first connection is
         // accepted, only #initialConnectionDeadline governs (it defers under an
-        // in-flight handshake, which #isTrueIdle() cannot see); afterwards the
-        // idle timer owns the idleGraceMs exit.
+        // in-flight handshake up to a bounded number of times); afterwards the
+        // idle timer owns the idleGraceMs exit, with in-flight handshakes visible
+        // to #isTrueIdle().
         if (!this.#hasAcceptedConnection)
             return;
         if (!this.#isTrueIdle() || this.#idleTimer)
@@ -620,6 +737,25 @@ export class RuntimeHostKernel {
         }, this.#lifecycle.idleGraceMs);
     }
     #isTrueIdle() {
+        return this.#residencies.activeCount === 0 && this.#hasNoObservedWork();
+    }
+    #hasNoObservedWork(exceptHandshaking) {
+        // A transport mid-handshake keeps the Host busy, except the one whose
+        // admission is being decided right now: counting it would make every
+        // true-idle takeover observe itself as activity.
+        const handshaking = exceptHandshaking !== undefined && this.#handshakingTransports.has(exceptHandshaking)
+            ? this.#handshakingTransports.size - 1
+            : this.#handshakingTransports.size;
+        return (this.#state === 'ready' &&
+            this.#acceptedTransports.size === 0 &&
+            handshaking === 0 &&
+            this.#activeOperations === 0);
+    }
+    // The replacement advice in a rejection is what a stale Client acts on.
+    // In-flight handshakes resolve within milliseconds and must not flip that
+    // advice, so unlike the idle timer and the takeover decision it ignores
+    // the handshaking set entirely.
+    #isSettledForReplacementAdvice() {
         return (this.#state === 'ready' &&
             this.#acceptedTransports.size === 0 &&
             this.#activeOperations === 0 &&

package/node_modules/@maka/runtime-host/dist/server/host-residency-registry.js

@@ -21,60 +21,81 @@ export class HostResidencyRegistry {
     #counts = new Map();
     #drainWaiters = new Set();
     #activeCount = 0;
+    #drainHandles = new Set();
+    /** Residencies of either kind keep the process alive against idle exit. */
     get activeCount() {
         return this.#activeCount;
     }
-    acquire(label) {
+    /** Only drain-kind residencies block maintenance probes and graceful close. */
+    get drainCount() {
+        return this.#drainHandles.size;
+    }
+    hasDrainResidenciesExcept(allowed) {
+        const proven = new Set(allowed);
+        return [...this.#drainHandles].some((handle) => !proven.has(handle));
+    }
+    acquire(label, kind = 'drain', onRelease) {
         requireResidencyLabel(label);
         this.#activeCount += 1;
-        this.#counts.set(label, (this.#counts.get(label) ?? 0) + 1);
+        const counts = this.#counts.get(label) ?? { total: 0, drain: 0 };
+        counts.total += 1;
+        if (kind === 'drain')
+            counts.drain += 1;
+        this.#counts.set(label, counts);
         let active = true;
-        return {
+        const handle = {
             release: () => {
                 if (!active)
                     return;
                 active = false;
-                this.#release(label);
+                this.#drainHandles.delete(handle);
+                this.#release(label, kind);
+                onRelease?.();
             },
         };
+        if (kind === 'drain')
+            this.#drainHandles.add(handle);
+        return handle;
     }
     snapshot() {
         return [...this.#counts]
             .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
-            .map(([label, count]) => Object.freeze({ label, count }));
+            .map(([label, counts]) => Object.freeze({ label, count: counts.total }));
     }
     waitForEmpty() {
-        return this.#waitForEmptyExcept(undefined);
+        return this.#waitForDrainEmptyExcept(undefined);
     }
     waitForEmptyExcept(excludedLabel) {
         requireResidencyLabel(excludedLabel);
-        return this.#waitForEmptyExcept(excludedLabel);
+        return this.#waitForDrainEmptyExcept(excludedLabel);
     }
-    #release(label) {
-        const count = this.#counts.get(label);
-        if (count === undefined || count === 0 || this.#activeCount === 0) {
+    #release(label, kind) {
+        const counts = this.#counts.get(label);
+        if (counts === undefined || counts.total === 0 || this.#activeCount === 0) {
             throw new Error('Runtime Host residency underflow');
         }
-        if (count === 1)
-            this.#counts.delete(label);
-        else
-            this.#counts.set(label, count - 1);
+        counts.total -= 1;
+        if (kind === 'drain') {
+            counts.drain -= 1;
+        }
         this.#activeCount -= 1;
+        if (counts.total === 0)
+            this.#counts.delete(label);
         for (const waiter of this.#drainWaiters) {
-            if (!this.#isEmptyExcept(waiter.excludedLabel))
+            if (!this.#isDrainEmptyExcept(waiter.excludedLabel))
                 continue;
             this.#drainWaiters.delete(waiter);
             waiter.resolve();
         }
     }
-    #waitForEmptyExcept(excludedLabel) {
-        if (this.#isEmptyExcept(excludedLabel))
+    #waitForDrainEmptyExcept(excludedLabel) {
+        if (this.#isDrainEmptyExcept(excludedLabel))
             return Promise.resolve();
         return new Promise((resolve) => this.#drainWaiters.add({ excludedLabel, resolve }));
     }
-    #isEmptyExcept(excludedLabel) {
-        for (const [label, count] of this.#counts) {
-            if (count > 0 && label !== excludedLabel)
+    #isDrainEmptyExcept(excludedLabel) {
+        for (const [label, counts] of this.#counts) {
+            if (counts.drain > 0 && label !== excludedLabel)
                 return false;
         }
         return true;