@namzu/sdk 46.0.0 → 48.1.0

package/src/manager/session/turn-recorder.ts

@@ -10,6 +10,7 @@ import {
 	type SessionLogEntry,
 	type SessionLogHead,
 	SessionMessageFold,
+	withMessageId,
 } from '../../store/session-log/index.js'
 import type { SpillRef } from '../../store/session-log/spill.js'
 import { getActiveSpanContext } from '../../telemetry/runtime-accessors.js'
@@ -52,6 +53,7 @@ import {
 } from '../../utils/cost.js'
 import { asCheckpointId, generateAuditEventId, generateMessageId } from '../../utils/id.js'
 import { childSessionEnded } from '../agent/child-session.js'
+import { assertSessionLogAttribution } from './attribution.js'
 
 /** Which provider and model a cost is priced against. */
 export interface PricingSubject {
@@ -66,10 +68,29 @@ export interface RecordedMessage {
 	readonly messageId?: MessageId
 }
 
+/**
+ * Stamp (or clear) `id` on a message already living in `recorder.messages`,
+ * in place — the recorder's own bookkeeping (`#ids`, `#recorded`, `#view`)
+ * is keyed by object IDENTITY, so replacing the array element the way
+ * `withMessageId` does would desync it. `recorder.messages`/`Turn.messages`
+ * is the one place a message a HOST passed in is allowed to change under
+ * it: once the kernel records that exact object, it is stamped with the id
+ * its record was given, which is the id `BaseMessage.id` documents. A
+ * message read from the log for a DIFFERENT purpose (a fold a host did not
+ * hand in, a checkpoint restore) is never this function's object — it goes
+ * through `withMessageId`, a copy, because nothing here owns it to mutate.
+ */
+function stampMessageId(message: Message, id: MessageId | undefined): void {
+	if (id === undefined) delete (message as { id?: MessageId }).id
+	else (message as { id?: MessageId }).id = id
+}
+
 /** How {@link TurnRecorder.open} takes the session's writer lease and starts an empty log. */
 export interface TurnRecorderOpenOptions {
 	/** A lease the caller already holds. Absent: the recorder claims one and releases it at the end. */
 	readonly lease?: SessionLease
+	/** A lease claimed by the query prelude, transferred to the recorder for release. */
+	readonly ownLease?: boolean
 	/** The holder name for a lease the recorder claims. */
 	readonly holder?: string
 	/** Lease time-to-live for a lease the recorder claims. Renewed while the turn runs. */
@@ -197,6 +218,9 @@ export class TurnRecorder {
 	#released = false
 	#leaseHolder = ''
 	#leaseTtlMs = DEFAULT_TURN_LEASE_TTL_MS
+	#leaseHeartbeat: ReturnType<typeof setInterval> | undefined
+	#leaseRenewal: Promise<void> = Promise.resolve()
+	#leaseRenewalError: unknown
 	#chain: Promise<void> = Promise.resolve()
 	#failure: unknown = undefined
 	#view: ViewEntry[] = []
@@ -233,7 +257,10 @@ export class TurnRecorder {
 			throw new NamzuError({
 				code: 'invalid_config',
 				message: `The session log belongs to session ${config.sessionLog.sessionId}, not ${config.sessionId}.`,
-				details: { sessionId: config.sessionId, logSessionId: config.sessionLog.sessionId },
+				details: {
+					sessionId: config.sessionId,
+					logSessionId: config.sessionLog.sessionId,
+				},
 			})
 		}
 		this.#turn = {
@@ -344,7 +371,10 @@ export class TurnRecorder {
 	get costInfo(): CostInfo {
 		const unpriced = Math.max(0, this.tokenUsage.totalTokens - this.#turn.tokenUsage.totalTokens)
 		return unpriced > 0
-			? { ...this.#turn.costInfo, unpricedTokens: this.#turn.costInfo.unpricedTokens + unpriced }
+			? {
+					...this.#turn.costInfo,
+					unpricedTokens: this.#turn.costInfo.unpricedTokens + unpriced,
+				}
 			: this.#turn.costInfo
 	}
 
@@ -570,60 +600,114 @@ export class TurnRecorder {
 	async open(options: TurnRecorderOpenOptions): Promise<RecordedMessage[]> {
 		if (this.#phase !== 'new') throw new Error('TurnRecorder.open was already called.')
 		this.#leaseTtlMs = options.leaseTtlMs ?? DEFAULT_TURN_LEASE_TTL_MS
-		this.#leaseHolder = options.holder ?? `namzu:${process.pid}:${this.turnId}`
-		if (options.lease) {
-			this.#lease = options.lease
-		} else {
-			const lease = await this.log.claim({ holder: this.#leaseHolder, ttlMs: this.#leaseTtlMs })
-			if (lease === null) {
-				const active = await this.log.activeTurn()
-				if (active) {
-					throw new TurnInProgressError({
-						sessionId: this.sessionId,
-						activeTurnId: active.turnId,
-						state: 'running',
+		this.#leaseHolder =
+			options.holder ?? options.lease?.holder ?? `namzu:${process.pid}:${this.turnId}`
+		try {
+			if (options.lease) {
+				this.#lease = options.lease
+				this.#ownsLease = options.ownLease === true
+			}
+			// Claiming a log may repair a torn tail. Refuse a foreign owner
+			// before that mutation, then recheck under the lease below.
+			await assertSessionLogAttribution(this.log, this.#config)
+			if (!options.lease) {
+				const lease = await this.log.claim({
+					holder: this.#leaseHolder,
+					ttlMs: this.#leaseTtlMs,
+					repairTornTail: false,
+				})
+				if (lease === null) {
+					const active = await this.log.activeTurn()
+					if (active) {
+						throw new TurnInProgressError({
+							sessionId: this.sessionId,
+							activeTurnId: active.turnId,
+							state: 'running',
+						})
+					}
+					throw new NamzuError({
+						code: 'invalid_config',
+						message: `Session ${this.sessionId} is leased by another writer; wait for it to finish or pass the lease you hold.`,
+						details: { sessionId: this.sessionId },
 					})
 				}
-				throw new NamzuError({
-					code: 'invalid_config',
-					message: `Session ${this.sessionId} is leased by another writer; wait for it to finish or pass the lease you hold.`,
-					details: { sessionId: this.sessionId },
+				this.#lease = lease
+				this.#ownsLease = true
+			}
+			const lease = this.#lease
+			if (!lease) throw new Error('TurnRecorder.open did not acquire a writer lease.')
+			if (this.#ownsLease) {
+				this.#leaseHeartbeat = setInterval(() => this.#queueLeaseRenewal(), this.#leaseTtlMs / 2)
+				this.#leaseHeartbeat.unref()
+			}
+			const head = await this.log.head()
+			if (head === null) {
+				this.#lastEntry = await this.log.append(lease, {
+					type: 'session_started',
+					projectId: this.projectId,
+					tenantId: this.tenantId,
+					topicId: this.topicId,
+					cwd: options.session.cwd,
+					agent: {
+						id: this.#config.agentId,
+						name: this.#config.agentName,
+						...(options.session.agentType ? { type: options.session.agentType } : {}),
+					},
+					...(options.session.origin ? { origin: options.session.origin } : {}),
+					...(options.session.forkedFrom ? { forkedFrom: options.session.forkedFrom } : {}),
 				})
+			} else {
+				await assertSessionLogAttribution(this.log, this.#config)
 			}
-			this.#lease = lease
-			this.#ownsLease = true
+			if (options.session.forkedFrom) {
+				this.#turn.forkedFrom = options.session.forkedFrom
+			}
+			this.#phase = 'open'
+			return await readFoldedHistory(this.log)
+		} catch (error) {
+			await this.release()
+			throw error
 		}
-		const head = await this.log.head()
-		if (head === null) {
-			this.#lastEntry = await this.log.append(this.#lease, {
-				type: 'session_started',
-				projectId: this.projectId,
-				tenantId: this.tenantId,
-				topicId: this.topicId,
-				cwd: options.session.cwd,
-				agent: {
-					id: this.#config.agentId,
-					name: this.#config.agentName,
-					...(options.session.agentType ? { type: options.session.agentType } : {}),
-				},
-				...(options.session.origin ? { origin: options.session.origin } : {}),
-				...(options.session.forkedFrom ? { forkedFrom: options.session.forkedFrom } : {}),
+	}
+
+	/** Serialize timer and write-triggered renewals so release uses the latest token. */
+	#queueLeaseRenewal(): void {
+		this.#leaseRenewal = this.#leaseRenewal
+			.then(async () => {
+				if (!this.#ownsLease || this.#released || this.#leaseRenewalError !== undefined) return
+				const current = this.#lease
+				if (!current) return
+				const renewed = await this.log.claim({
+					holder: this.#leaseHolder,
+					ttlMs: this.#leaseTtlMs,
+					repairTornTail: false,
+				})
+				if (renewed === null || renewed.fence !== current.fence) {
+					if (renewed !== null) await this.log.release(renewed).catch(() => undefined)
+					throw new NamzuError({
+						code: 'invalid_config',
+						message: `Session ${this.sessionId} lost its writer lease during the turn.`,
+						details: { sessionId: this.sessionId },
+					})
+				}
+				this.#lease = renewed
+			})
+			.catch((error: unknown) => {
+				this.#leaseRenewalError ??= error
 			})
-		}
-		if (options.session.forkedFrom) {
-			this.#turn.forkedFrom = options.session.forkedFrom
-		}
-		this.#phase = 'open'
-		return readFoldedHistory(this.log)
 	}
 
 	/** Renew a lease this recorder claimed when it is past half its life. */
 	async #leaseForWrite(): Promise<SessionLease> {
-		const lease = this.#lease
-		if (!lease) throw new Error('TurnRecorder.open must run before the turn writes.')
-		if (this.#ownsLease && lease.expiresAt - Date.now() < this.#leaseTtlMs / 2) {
-			const renewed = await this.log.claim({ holder: this.#leaseHolder, ttlMs: this.#leaseTtlMs })
-			if (renewed) this.#lease = renewed
+		if (!this.#lease) throw new Error('TurnRecorder.open must run before the turn writes.')
+		if (this.#ownsLease) {
+			await this.#leaseRenewal
+			if (this.#leaseRenewalError !== undefined) throw this.#leaseRenewalError
+			if (this.#lease.expiresAt - Date.now() < this.#leaseTtlMs / 2) {
+				this.#queueLeaseRenewal()
+				await this.#leaseRenewal
+				if (this.#leaseRenewalError !== undefined) throw this.#leaseRenewalError
+			}
 		}
 		return this.#lease as SessionLease
 	}
@@ -631,10 +715,12 @@ export class TurnRecorder {
 	/** Give up a lease the recorder claimed. Never throws. */
 	async release(): Promise<void> {
 		if (!this.#ownsLease || !this.#lease) return
-		const lease = this.#lease
-		this.#ownsLease = false
 		this.#released = true
-		await this.log.release(lease).catch(() => undefined)
+		if (this.#leaseHeartbeat !== undefined) clearInterval(this.#leaseHeartbeat)
+		this.#leaseHeartbeat = undefined
+		await this.#leaseRenewal
+		this.#ownsLease = false
+		await this.log.release(this.#lease).catch(() => undefined)
 	}
 
 	#enqueue<T>(operation: () => Promise<T>): Promise<T> {
@@ -842,7 +928,9 @@ export class TurnRecorder {
 	recordChildSessionEvent(
 		event: Extract<
 			SessionEvent,
-			{ type: 'child_session_spawned' | 'child_session_messaged' | 'child_session_idled' }
+			{
+				type: 'child_session_spawned' | 'child_session_messaged' | 'child_session_idled'
+			}
 		>,
 		childLog?: SessionLog,
 	): Promise<SessionLogEntry | undefined> {
@@ -877,8 +965,12 @@ export class TurnRecorder {
 		if (!target?.id) return
 		const current = target.message as AssistantMessage
 		if (current.content === result) return
-		const replacement: AssistantMessage = { ...current, content: result }
 		const targetMessageId = target.id
+		const replacement: AssistantMessage = {
+			...current,
+			content: result,
+			id: targetMessageId,
+		}
 		await this.#enqueue(() =>
 			this.#append({
 				type: 'message_replaced',
@@ -911,11 +1003,15 @@ export class TurnRecorder {
 	 */
 	pushMessage(
 		message: Message,
-		options: { readonly messageId?: MessageId; readonly transient?: boolean } = {},
+		options: {
+			readonly messageId?: MessageId
+			readonly transient?: boolean
+		} = {},
 	): void {
 		if (options.messageId) {
 			this.#ids.set(message, options.messageId)
 			this.#recorded.set(message, options.messageId)
+			stampMessageId(message, options.messageId)
 		}
 		if (options.transient) this.#transient.add(message)
 		this.#turn.messages.push(message)
@@ -965,6 +1061,7 @@ export class TurnRecorder {
 			this.#ids.set(message, id)
 		}
 		this.#recorded.set(message, id)
+		stampMessageId(message, id)
 		return id
 	}
 
@@ -1054,6 +1151,11 @@ export class TurnRecorder {
 		for (const entry of summaryEntries) {
 			entry.id = undefined
 			this.#ids.delete(entry.message)
+			// A summary member is no longer individually recorded — a fresh
+			// fold would show it with no id, so its object stops claiming one
+			// too. `entry.message` is the same object `live` holds at this
+			// position (built from it, above), so this is what a caller sees.
+			stampMessageId(entry.message, undefined)
 		}
 		const summary = summaryEntries.map((entry) => entry.message)
 		const keptMessageIds = keptEntries.map((entry) => entry.id as MessageId)
@@ -1129,7 +1231,11 @@ export class TurnRecorder {
 			type: 'audit',
 			...(event.turnId ? { turnId: event.turnId } : {}),
 			auditId: event.id,
-			actor: { kind: 'agent', agentId: this.#turn.metadata.agentId, tenantId: this.tenantId },
+			actor: {
+				kind: 'agent',
+				agentId: this.#turn.metadata.agentId,
+				tenantId: this.tenantId,
+			},
 			...(input.persona !== undefined ? { persona: input.persona } : {}),
 			action: input.what.action,
 			...(input.what.tool !== undefined ? { tool: input.what.tool } : {}),
@@ -1241,19 +1347,69 @@ export async function readFoldedHistory(
 	const out: RecordedMessage[] = []
 	const spilled = fold.spilledSummary
 	if (spilled) {
+		// `withMessageId(message, undefined)` strips any id already embedded in
+		// the spilled JSON — same as the inline branch below, and for the same
+		// reason `readEverRecordedMessages`'s doc comment gives: a summary
+		// member has no record of its own. A synthesized summary never had an
+		// id, so this is invisible there; a fork's seeded summary IS the
+		// source session's own already-id'd messages, and without this a
+		// spilled (large) fork's first live turn reads its fold back carrying
+		// a DIFFERENT session's ids and fails reconciliation as foreign.
 		for (const message of JSON.parse(await log.readSpill(spilled.spill)) as Message[]) {
-			out.push({ message })
+			out.push({ message: withMessageId(message, undefined) })
 		}
 	}
 	for (const entry of fold.entries()) {
 		const message = entry.spill
 			? (JSON.parse(await log.readSpill(entry.spill as SpillRef)) as Message)
 			: entry.message
-		out.push({ message, ...(entry.messageId ? { messageId: entry.messageId } : {}) })
+		out.push({
+			message: withMessageId(message, entry.messageId),
+			...(entry.messageId ? { messageId: entry.messageId } : {}),
+		})
 	}
 	return out
 }
 
+/**
+ * Every message this session's log has ever recorded, keyed by the durable
+ * id its `message` record gave it — including one a compaction has since
+ * folded into a summary and dropped from {@link readFoldedHistory}'s
+ * current fold. A `message_replaced` record's content wins over the message
+ * it targets, the log's own precedence for "what this id means now."
+ *
+ * A compaction summary member has no entry here: it was never its own
+ * `message` record (see {@link RecordedMessage.messageId}), so nothing can
+ * recognise it by id — a caller's copy of it is reconciled by value instead.
+ */
+export async function readEverRecordedMessages(
+	log: SessionLog,
+): Promise<ReadonlyMap<MessageId, Message>> {
+	const latest = new Map<MessageId, { readonly content: Message; readonly spill?: SpillRef }>()
+	for await (const entry of log.read()) {
+		const record = entry.record as SessionRecord
+		if (record.type === 'message') {
+			latest.set(record.messageId, {
+				content: record.content,
+				...(record.spill ? { spill: record.spill } : {}),
+			})
+		} else if (record.type === 'message_replaced') {
+			latest.set(record.targetMessageId, {
+				content: record.content,
+				...(record.spill ? { spill: record.spill } : {}),
+			})
+		}
+	}
+	const resolved = new Map<MessageId, Message>()
+	for (const [id, entry] of latest) {
+		const content = entry.spill
+			? (JSON.parse(await log.readSpill(entry.spill)) as Message)
+			: entry.content
+		resolved.set(id, withMessageId(content, id))
+	}
+	return resolved
+}
+
 /**
  * A session's audit trail: its `audit` records as {@link AuditEvent}s, in log
  * order, each numbered among the session's audit entries. What

package/src/peers/address.ts

@@ -0,0 +1,58 @@
+/**
+ * Peer addresses are URIs so a later cross-machine transport can be added
+ * without redesigning the registry or the protocol: `uds:<path>` and
+ * `pipe:<name>` today, `a2a:https://…` later (design §1.1). Only the two
+ * local schemes are ever SERVED or DIALED by this package; `a2a:` addresses
+ * are recognised so a reader can tell them apart, not connected to.
+ *
+ * @experimental
+ */
+
+import { join } from 'node:path'
+import { peerSocketFileName } from './dir.js'
+
+export type PeerAddress =
+	| { readonly scheme: 'uds'; readonly path: string }
+	| { readonly scheme: 'pipe'; readonly path: string }
+	| { readonly scheme: 'a2a'; readonly url: string }
+
+export class PeerAddressError extends Error {
+	override readonly name = 'PeerAddressError'
+}
+
+/** The `uds:<path>` address for a session's socket inside a hardened runtime directory. */
+export function udsPeerAddress(runtimeDir: string, sessionId: string): string {
+	return `uds:${join(runtimeDir, peerSocketFileName(sessionId))}`
+}
+
+/**
+ * The `pipe:<name>` address for a session's Windows named pipe.
+ *
+ * `<name>` is the full pipe path Node's `net` module dials directly
+ * (`\\.\pipe\namzu-<uid-hash>-<session-short>`, design §1.1) — coded here for
+ * completeness; this package does not run its tests on win32, so the shape
+ * is reviewed rather than exercised.
+ */
+export function pipePeerAddress(uidHash: string, sessionShort: string): string {
+	return `pipe:\\\\.\\pipe\\namzu-${uidHash}-${sessionShort}`
+}
+
+/** Parse a peer address URI. Throws {@link PeerAddressError} on an unrecognised or empty scheme. */
+export function parsePeerAddress(address: string): PeerAddress {
+	if (address.startsWith('uds:')) {
+		const path = address.slice('uds:'.length)
+		if (path.length === 0) throw new PeerAddressError(`Empty uds: address: ${address}`)
+		return { scheme: 'uds', path }
+	}
+	if (address.startsWith('pipe:')) {
+		const path = address.slice('pipe:'.length)
+		if (path.length === 0) throw new PeerAddressError(`Empty pipe: address: ${address}`)
+		return { scheme: 'pipe', path }
+	}
+	if (address.startsWith('a2a:')) {
+		const url = address.slice('a2a:'.length)
+		if (url.length === 0) throw new PeerAddressError(`Empty a2a: address: ${address}`)
+		return { scheme: 'a2a', url }
+	}
+	throw new PeerAddressError(`Unrecognised peer address scheme: ${address}`)
+}

package/src/peers/client.ts

@@ -0,0 +1,202 @@
+/**
+ * A client for one connection of `namzu-peer/1`: connect, write one request
+ * line, read one response line, close. Mirrors the shape of this
+ * repository's other local control clients (`queryRunner` in
+ * `packages/cli/src/integrations/resident/runner-control.ts`,
+ * `callEndpoint` in `packages/cli/src/schedule/daemon/endpoint.ts`): an
+ * authenticated response PROVES responsiveness, and its absence never proves
+ * the peer is dead — only that this attempt could not reach it.
+ *
+ * @experimental
+ */
+
+import { createConnection } from 'node:net'
+import { parsePeerAddress } from './address.js'
+import {
+	type DeliverRequest,
+	type DeliverResponse,
+	DeliverResponseSchema,
+	MAX_PEER_REQUEST_BYTES,
+	type NoticeRequest,
+	type NoticeResponse,
+	NoticeResponseSchema,
+	PEER_PROTOCOL_VERSION,
+	type PingRequest,
+	type PingResponse,
+	PingResponseSchema,
+	type SubscribeIdleRequest,
+	type SubscribeIdleResponse,
+	SubscribeIdleResponseSchema,
+} from './protocol.js'
+import type { PeerRecord } from './record.js'
+
+const DEFAULT_TIMEOUT_MS = 2_000
+
+export class PeerClientError extends Error {
+	override readonly name = 'PeerClientError'
+}
+
+/** An authenticated reply proves responsiveness; every other outcome names why none arrived. */
+export type PeerClientResult<T> =
+	| ({ readonly kind: 'responded' } & T)
+	| { readonly kind: 'unreachable'; readonly reason: string }
+
+function connectPath(address: string): string {
+	const parsed = parsePeerAddress(address)
+	if (parsed.scheme === 'a2a') {
+		throw new PeerClientError(`PeerClient cannot dial an a2a: address directly: ${address}`)
+	}
+	return parsed.path
+}
+
+/** One request, one response, one connection. */
+function sendPeerRequest<T>(
+	address: string,
+	request: unknown,
+	parseResponse: (value: unknown) => T,
+	timeoutMs: number,
+): Promise<PeerClientResult<T>> {
+	return new Promise((resolve) => {
+		let settled = false
+		const finish = (result: PeerClientResult<T>): void => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			socket.destroy()
+			resolve(result)
+		}
+		const unreachable = (error: unknown): void =>
+			finish({
+				kind: 'unreachable',
+				reason: error instanceof Error ? error.message : String(error),
+			})
+		const timer = setTimeout(() => unreachable(new Error('Peer request timed out.')), timeoutMs)
+		let path: string
+		try {
+			path = connectPath(address)
+		} catch (error) {
+			clearTimeout(timer)
+			resolve({
+				kind: 'unreachable',
+				reason: error instanceof Error ? error.message : String(error),
+			})
+			return
+		}
+		const socket = createConnection({ path })
+		let buffered = Buffer.alloc(0)
+		socket.once('error', unreachable)
+		socket.once('close', () =>
+			unreachable(new Error('Peer connection closed before a response arrived.')),
+		)
+		socket.once('connect', () => {
+			socket.write(`${JSON.stringify(request)}\n`)
+		})
+		socket.on('data', (chunk: Buffer) => {
+			if (buffered.length + chunk.length > MAX_PEER_REQUEST_BYTES) {
+				unreachable(new Error('Peer response exceeded the size limit.'))
+				return
+			}
+			buffered = Buffer.concat([buffered, chunk])
+			const newline = buffered.indexOf(10)
+			if (newline < 0) return
+			try {
+				const parsed: unknown = JSON.parse(buffered.subarray(0, newline).toString('utf8'))
+				finish({ kind: 'responded', ...parseResponse(parsed) })
+			} catch (error) {
+				unreachable(error)
+			}
+		})
+	})
+}
+
+export interface PeerClientOptions {
+	/** Default 2000ms. */
+	readonly timeoutMs?: number
+}
+
+/**
+ * `ping`, `deliver`, `subscribe_idle` and `notice` over `namzu-peer/1`.
+ *
+ * `deliver`/`subscribeIdle`/`notice` read the RECIPIENT's token from the
+ * `PeerRecord` passed in — the wire's token is always the recipient's own,
+ * asserted by the caller and verified by the server (design §1.1, §1.3).
+ * `ping` takes a bare address and carries no token; see the file header for
+ * why.
+ */
+export class PeerClient {
+	private readonly timeoutMs: number
+
+	constructor(options: PeerClientOptions = {}) {
+		this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+	}
+
+	ping(address: string, timeoutMs = this.timeoutMs): Promise<PeerClientResult<PingResponse>> {
+		const request: PingRequest = { protocol: PEER_PROTOCOL_VERSION, op: 'ping' }
+		return sendPeerRequest(address, request, (value) => PingResponseSchema.parse(value), timeoutMs)
+	}
+
+	deliver(
+		record: Pick<PeerRecord, 'address' | 'token'>,
+		message: Omit<DeliverRequest, 'protocol' | 'op' | 'token'>,
+	): Promise<PeerClientResult<DeliverResponse>> {
+		const request: DeliverRequest = {
+			protocol: PEER_PROTOCOL_VERSION,
+			op: 'deliver',
+			token: record.token,
+			...message,
+		}
+		return sendPeerRequest(
+			record.address,
+			request,
+			(value) => DeliverResponseSchema.parse(value),
+			this.timeoutMs,
+		)
+	}
+
+	subscribeIdle(
+		record: Pick<PeerRecord, 'address' | 'token'>,
+		message: Omit<SubscribeIdleRequest, 'protocol' | 'op' | 'token'>,
+	): Promise<PeerClientResult<SubscribeIdleResponse>> {
+		const request: SubscribeIdleRequest = {
+			protocol: PEER_PROTOCOL_VERSION,
+			op: 'subscribe_idle',
+			token: record.token,
+			...message,
+		}
+		return sendPeerRequest(
+			record.address,
+			request,
+			(value) => SubscribeIdleResponseSchema.parse(value),
+			this.timeoutMs,
+		)
+	}
+
+	notice(
+		record: Pick<PeerRecord, 'address' | 'token'>,
+		message: Omit<NoticeRequest, 'protocol' | 'op' | 'token'>,
+	): Promise<PeerClientResult<NoticeResponse>> {
+		const request: NoticeRequest = {
+			protocol: PEER_PROTOCOL_VERSION,
+			op: 'notice',
+			token: record.token,
+			...message,
+		}
+		return sendPeerRequest(
+			record.address,
+			request,
+			(value) => NoticeResponseSchema.parse(value),
+			this.timeoutMs,
+		)
+	}
+}
+
+/** A bare liveness probe: `true` iff an unauthenticated `ping` answers within `timeoutMs`. Used by `listLivePeers`. */
+export function pingPeer(address: string, timeoutMs = DEFAULT_TIMEOUT_MS): Promise<boolean> {
+	const request: PingRequest = { protocol: PEER_PROTOCOL_VERSION, op: 'ping' }
+	return sendPeerRequest(
+		address,
+		request,
+		(value) => PingResponseSchema.parse(value),
+		timeoutMs,
+	).then((result) => result.kind === 'responded')
+}