Skip to content

Commit edd4335

Browse files
thymikeeclaude
andcommitted
feat(daemon): quiesce request that retires an idle daemon atomically
A daemon now answers an authenticated, instance-fenced daemon_quiesce request: it closes admission and counts requests in flight, sessions, repair sessions and live leases in one synchronous step, refuses with daemon-busy (reopening admission) if it holds any, and otherwise drains and exits. It publishes capabilities in daemon.json so a client can tell a daemon that can quiesce from one that predates it. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
1 parent 4c1c786 commit edd4335

10 files changed

Lines changed: 674 additions & 15 deletions

File tree

‎docs/adr/0006-daemon-rpc-protocol-version.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,3 +84,28 @@ the gap and its reason instead of implying coverage. See `test/wire-compat/READM
8484
Legacy remote daemons without `rpcProtocolVersion` remain reachable. This keeps the first release of
8585
the proxy compatible with older HTTP daemons, but it means absence of the marker is not proof of
8686
compatibility.
87+
88+
## Daemon capabilities and quiesce
89+
90+
A daemon on the local state directory publishes `capabilities` in `daemon.json`. This is the
91+
command-level metadata the decision above prefers to a protocol bump. A daemon that predates a
92+
capability omits it, so a client treats absence as "cannot do this" and never infers it from the
93+
package version.
94+
95+
`quiesce` is how a client replaces an incompatible daemon without destroying other clients' work.
96+
The client sends `daemon_quiesce` with the daemon token and the pid and start time recorded in
97+
`daemon.json`. The daemon checks the token and that it is that instance, refuses a request that
98+
reached it as a remote-origin one, then closes admission and counts what it holds in a single
99+
synchronous step: requests in flight, sessions, repair sessions and live leases. Any of them
100+
refuses with `daemon-busy` and reopens admission in that same step. Otherwise it answers
101+
`draining`, keeps admission closed, and shuts down. The request is answered before dispatch, so
102+
it joins neither the in-flight count nor the command registry.
103+
104+
The daemon accepts a quiesce only when it can prove its own start time and the request names it with the pid; a daemon that cannot is never addressed. A
105+
client never signals a daemon that did not accept one, except to retire it after it answered
106+
`draining`.
107+
108+
The census counts what the contract names and nothing else. A resumable upload still streaming and
109+
a host-administration human-control hold that names no lease are outside it, the same boundary
110+
idle reap draws, so a quiesce can end them. A daemon started with an HTTP auth hook marks every
111+
HTTP request remote-origin and so refuses a quiesce over HTTP; the socket transport is unaffected.

‎packages/daemon-contracts/src/daemon-registration-owner.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ import { withDaemonDiagnosticsScope } from './daemon-diagnostics-scope.ts';
2626
import type { DaemonCodeOrigin } from '@agent-device/host-kit/code-signature';
2727
import {
2828
resolveDaemonPaths,
29+
type DaemonCapability,
2930
type DaemonPaths,
3031
type DaemonServerMode,
3132
} from './daemon-resolution.ts';
@@ -51,6 +52,8 @@ export type DaemonRegistrationFields = Readonly<{
5152
codeOrigin: DaemonCodeOrigin;
5253
codeSignature: string;
5354
policyDigest?: string;
55+
/** What this daemon can do beyond the base RPC contract; absent from daemons that predate it. */
56+
capabilities?: readonly DaemonCapability[];
5457
}>;
5558
type DaemonRegistrationRemoval =
5659
| Readonly<{ state: 'removed' }>

‎packages/daemon-contracts/src/daemon-resolution.ts‎

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,9 @@ export type { DaemonServerMode, DaemonTransportPreference };
1313
* daemon both read this subset — the client to find or launch a daemon, the daemon to bind one —
1414
* so it sits at the process root rather than under `packages/daemon/src/`, where a client would have to
1515
* reach daemon internals to resolve an address. `packages/daemon/src/core/config.ts` adds the request-scoping
16-
* rules that only the daemon applies on top of this.
16+
* rules that only the daemon applies on top of this. What a daemon publishes about itself
17+
* (`capabilities`) and the one request that asks it to leave (`quiesce`) belong here for the same
18+
* reason: the client addresses a daemon with them and the daemon answers by them.
1719
*/
1820

1921
export type DaemonPaths = {
@@ -94,3 +96,48 @@ export function resolveDaemonTransportPreference(
9496
if (normalized === 'dual') return 'auto';
9597
return 'auto';
9698
}
99+
100+
// The quiesce request is how a client asks an idle daemon to leave so a compatible one can take
101+
// its state directory. The client and the daemon share this vocabulary, so neither owns it.
102+
103+
/** What a daemon can do beyond the base RPC contract, published in its `daemon.json`. */
104+
export const DAEMON_CAPABILITIES = ['quiesce'] as const;
105+
export type DaemonCapability = (typeof DAEMON_CAPABILITIES)[number];
106+
107+
export const DAEMON_QUIESCE_COMMAND = 'daemon_quiesce';
108+
109+
/** The reason a daemon gives every request it refuses once it has begun to leave. */
110+
export const DAEMON_SHUTTING_DOWN_REASON = 'daemon_shutting_down';
111+
112+
export const DAEMON_QUIESCE_REASONS = {
113+
busy: 'daemon-busy',
114+
instanceMismatch: 'daemon-instance-mismatch',
115+
} as const;
116+
117+
/** The daemon instance a quiesce request is addressed to; any other instance refuses it. */
118+
export type DaemonQuiesceFence = Readonly<{
119+
pid: number;
120+
/** Null when the daemon could not prove its start time, as its `daemon.json` records. */
121+
processStartTime: string | null;
122+
}>;
123+
124+
/** What a daemon holds. It leaves a quiesce request only when all four counts are zero. */
125+
export type DaemonQuiesceCensus = Readonly<{
126+
inFlightRequests: number;
127+
sessions: number;
128+
repairSessions: number;
129+
leases: number;
130+
}>;
131+
132+
export function readDaemonQuiesceFence(input: unknown): DaemonQuiesceFence | undefined {
133+
if (typeof input !== 'object' || input === null) return undefined;
134+
const { pid, processStartTime } = input as Record<string, unknown>;
135+
if (!Number.isInteger(pid)) return undefined;
136+
if (processStartTime !== null && typeof processStartTime !== 'string') return undefined;
137+
return { pid: pid as number, processStartTime };
138+
}
139+
140+
export function readDaemonCapabilities(value: unknown): readonly DaemonCapability[] {
141+
if (!Array.isArray(value)) return [];
142+
return DAEMON_CAPABILITIES.filter((capability) => value.includes(capability));
143+
}

‎packages/daemon/src/core/__tests__/session-store-lifetime.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
22
import fs from 'node:fs';
33
import { test } from 'vitest';
44
import { AppError } from '@agent-device/kernel/errors';
5+
import { DAEMON_SHUTTING_DOWN_REASON } from '@agent-device/daemon-contracts/daemon-resolution';
56
import {
67
makeSession,
78
makeRepairCompleteSession,
@@ -110,7 +111,7 @@ test('shutdown closes draft admission while allowing the current lifetime to set
110111
store.closeAdmission();
111112
assert.throws(
112113
() => store.publish('late-draft', makeSession('late-draft')),
113-
(error) => error instanceof AppError && error.details?.reason === 'daemon_shutting_down',
114+
(error) => error instanceof AppError && error.details?.reason === DAEMON_SHUTTING_DOWN_REASON,
114115
);
115116
store.update(ref, { appName: 'Settled' });
116117
assert.equal(store.requireCurrent(ref).appName, 'Settled');

0 commit comments

Comments
 (0)