@agent-relay/factory 0.1.16 → 0.1.18

package/dist/fleet/relay-fleet-client.js

@@ -1,74 +1,133 @@
-import { randomUUID } from 'node:crypto';
+import { AgentRelay } from '@agent-relay/sdk';
+import { resolveRelayAgentToken, resolveRelayWorkspaceKey } from './relay-workspace-key.js';
 const knownCapabilities = new Set(['spawn:claude', 'spawn:codex', 'workflow:run']);
 const openStatuses = new Set(['pending', 'dispatched', 'invoked']);
 const terminalStatuses = new Set(['completed', 'failed', 'denied']);
-const DEFAULT_COMPLETION_TIMEOUT_MS = 5 * 60_000;
+const DEFAULT_AGENT_NAME = 'factory';
+const DEFAULT_SPAWN_ACK_TIMEOUT_MS = 5 * 60_000;
 const DEFAULT_POLL_INTERVAL_MS = 1_000;
+const DEFAULT_EXIT_WATCH_INTERVAL_MS = 15_000;
+// 2× the engine's 45s node-liveness TTL so one missed heartbeat sweep cannot
+// synthesize a false exit.
+const DEFAULT_NODE_OFFLINE_GRACE_MS = 90_000;
+const DEFAULT_REGISTRATION_GRACE_MS = 60_000;
 export class RelayFleetClient {
     #options;
-    // Built lazily on first network use so that constructing the client (and
-    // therefore createFleet({ backend: 'relay' })) never throws merely because no
-    // token is configured. The token check lives in HttpRelayFleetTransport's
-    // constructor and only fires when a method actually needs the transport.
-    #transport;
-    #spawnActionName;
-    #releaseActionName;
-    #completionTimeoutMs;
+    #agentName;
+    #spawnAckTimeoutMs;
     #pollIntervalMs;
+    #exitWatchIntervalMs;
+    #nodeOfflineGraceMs;
+    #registrationGraceMs;
+    #createRelay;
+    #now;
     #sleep;
+    #log;
     #agentExitListeners = new Set();
     #deliveryFailedListeners = new Set();
     #agentMessageListeners = new Set();
     #eventUnsubscribers = [];
-    #subscribed = false;
+    #tracked = new Map();
+    // Resolved lazily on first network use so constructing the client (and
+    // therefore createFleet({ backend: 'relay' })) never throws merely because no
+    // token is configured.
+    #messaging;
+    #messagingReady;
+    #eventsStarted = false;
     #disposed = false;
+    #watchTimer;
+    #reconciling;
     constructor(options = {}) {
         this.#options = options;
-        this.#spawnActionName = options.spawnActionName ?? 'spawn';
-        this.#releaseActionName = options.releaseActionName ?? 'release';
-        this.#completionTimeoutMs = options.completionTimeoutMs ?? DEFAULT_COMPLETION_TIMEOUT_MS;
+        this.#agentName = options.agentName ?? DEFAULT_AGENT_NAME;
+        this.#spawnAckTimeoutMs = options.spawnAckTimeoutMs ?? DEFAULT_SPAWN_ACK_TIMEOUT_MS;
         this.#pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.#exitWatchIntervalMs = options.exitWatchIntervalMs ?? DEFAULT_EXIT_WATCH_INTERVAL_MS;
+        this.#nodeOfflineGraceMs = options.nodeOfflineGraceMs ?? DEFAULT_NODE_OFFLINE_GRACE_MS;
+        this.#registrationGraceMs = options.registrationGraceMs ?? DEFAULT_REGISTRATION_GRACE_MS;
+        this.#createRelay = options.createRelay ?? ((relayOptions) => new AgentRelay(relayOptions));
+        this.#now = options.now ?? Date.now;
         this.#sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
-        this.#transport = options.transport;
-    }
-    #getTransport() {
-        this.#transport ??= new HttpRelayFleetTransport(this.#options);
-        return this.#transport;
+        this.#log = options.log ?? (() => { });
+        this.#messaging = options.messaging;
+    }
+    /** Agents spawned through this client that have not exited or been released. */
+    trackedAgents() {
+        return this.#tracked;
+    }
+    /** Re-adopt agents recorded in the in-flight registry after a restart. */
+    hydrateTracked(agents) {
+        for (const agent of agents) {
+            if (this.#tracked.has(agent.name))
+                continue;
+            // spawnedAtMs of 0 skips the registration grace: a hydrated agent was
+            // registered long ago, so absence from the roster is a real exit.
+            this.#tracked.set(agent.name, {
+                invocationId: agent.invocationId,
+                node: agent.node,
+                spawnedAtMs: 0,
+            });
+        }
+        this.#syncExitWatcher();
+    }
+    /**
+     * Reconcile tracked agents against the engine roster, synthesizing exits for
+     * agents that went offline (or whose node died) without a push signal. The
+     * exit watcher runs this on an interval; callers may invoke it directly for
+     * a deterministic sweep (startup recovery, tests).
+     */
+    reconcileTrackedAgents() {
+        this.#reconciling ??= this.#reconcileTracked().finally(() => {
+            this.#reconciling = undefined;
+        });
+        return this.#reconciling;
     }
     async spawn(input) {
-        const invocationId = input.invocationId ?? newInvocationId('spawn', input.name);
-        const actionInput = spawnActionInput(input, { includeSelfNode: false });
-        const ack = await this.#getTransport().invokeAction(this.#spawnActionName, actionInput, { invocationId });
-        const invocation = await this.#awaitInvocation(this.#spawnActionName, ack.invocationId || invocationId, ack);
-        return spawnResultFromInvocation(input.name, input.sessionRef, invocation);
+        const messaging = await this.#ensureMessaging();
+        const ack = await messaging.placement.spawn({
+            capability: input.capability,
+            // 'self' from the orchestrator means "no placement preference": let the
+            // engine pick the least-loaded eligible node.
+            ...(input.node && input.node !== 'self' ? { node: input.node } : {}),
+            ...(input.repo ? { repo: input.repo } : {}),
+            input: spawnActionInput(input),
+            ...(this.#options.placementTtlMs !== undefined ? { ttlMs: this.#options.placementTtlMs } : {}),
+            log: this.#log,
+        });
+        const invocation = await this.#awaitInvocation(ack.actionName || 'spawn', ack);
+        const result = spawnResultFromInvocation(input.name, input.sessionRef, invocation);
+        this.#track(result.name, ack);
+        return result;
     }
     async resume(input) {
         const name = input.name ?? input.sessionRef;
-        const invocationId = newInvocationId('resume', name);
-        const actionInput = spawnActionInput({
+        return await this.spawn({
             name,
             capability: input.capability ?? 'spawn:codex',
             node: input.node,
             sessionRef: input.sessionRef,
-        }, { includeSelfNode: false });
-        const ack = await this.#getTransport().invokeAction(this.#spawnActionName, actionInput, { invocationId });
-        const invocation = await this.#awaitInvocation(this.#spawnActionName, ack.invocationId || invocationId, ack);
-        return spawnResultFromInvocation(name, input.sessionRef, invocation);
+        });
     }
     async release(name, reason) {
-        const invocationId = newInvocationId('release', name);
-        const ack = await this.#getTransport().invokeAction(this.#releaseActionName, {
-            name,
-            agent: name,
-            ...(reason ? { reason } : {}),
-        }, { invocationId });
-        await this.#awaitInvocation(this.#releaseActionName, ack.invocationId || invocationId, ack);
+        const messaging = await this.#ensureMessaging();
+        try {
+            const ack = await messaging.commands.invoke('release', {
+                name,
+                agent: name,
+                ...(reason ? { reason } : {}),
+            });
+            await this.#awaitInvocation(ack.actionName || 'release', ack);
+        }
+        finally {
+            this.#tracked.delete(name);
+            this.#syncExitWatcher();
+        }
     }
     async roster() {
-        const transport = this.#getTransport();
+        const messaging = await this.#ensureMessaging();
         const [agents, nodes] = await Promise.all([
-            transport.listAgents(),
-            transport.listNodes(),
+            messaging.agents.list({ status: 'all' }),
+            messaging.nodes.list(),
         ]);
         return {
             agents: agents.map((agent) => ({ name: agent.name })),
@@ -79,18 +138,17 @@ export class RelayFleetClient {
             })),
         };
     }
+    // `from`/`data` are not representable on the agent-scoped messaging surface:
+    // every send is authored by the factory's own agent identity.
     async sendMessage(input) {
-        await this.#getTransport().sendMessage(input);
+        await this.#send(input);
     }
-    async waitForInjected(input, opts) {
-        const transport = this.#getTransport();
-        const sent = await transport.sendMessage(input);
-        const eventId = sent.eventId;
-        const targets = sent.targets ?? [input.to];
-        if (!eventId) {
-            return { eventId: newInvocationId('message', input.to), targets };
-        }
-        return await transport.waitForDelivery?.(eventId, opts) ?? { eventId, targets };
+    // The SDK exposes no sender-side delivery query yet, so a successful send —
+    // a durable inbox row on the engine — is the injected signal. Upstream:
+    // deliveries.forMessage(messageId) would make this authoritative.
+    async waitForInjected(input, _opts) {
+        const message = await this.#send(input);
+        return { eventId: message.id, targets: [input.to] };
     }
     onDeliveryFailed(listener) {
         this.#ensureEventSubscription();
@@ -109,207 +167,254 @@ export class RelayFleetClient {
     onAgentExit(listener) {
         this.#ensureEventSubscription();
         this.#agentExitListeners.add(listener);
+        this.#syncExitWatcher();
         return () => {
             this.#agentExitListeners.delete(listener);
+            this.#syncExitWatcher();
         };
     }
     async dispose() {
         if (this.#disposed)
             return;
         this.#disposed = true;
+        if (this.#watchTimer) {
+            clearInterval(this.#watchTimer);
+            this.#watchTimer = undefined;
+        }
         for (const unsubscribe of this.#eventUnsubscribers.splice(0)) {
             unsubscribe();
         }
         this.#agentExitListeners.clear();
         this.#deliveryFailedListeners.clear();
         this.#agentMessageListeners.clear();
-        // Only dispose a transport we actually built; never construct one here.
-        await this.#transport?.dispose?.();
-        this.#subscribed = false;
+        this.#tracked.clear();
+        if (this.#eventsStarted) {
+            await this.#messaging?.events.disconnect().catch(() => { });
+        }
     }
-    async #awaitInvocation(actionName, invocationId, initial) {
-        let status = initial.status ?? 'pending';
+    async #send(input) {
+        const messaging = await this.#ensureMessaging();
+        try {
+            if (input.to.startsWith('#')) {
+                return await messaging.messages.send({ channel: input.to.slice(1), text: input.text });
+            }
+            return await messaging.messages.direct({
+                to: input.to.startsWith('@') ? input.to.slice(1) : input.to,
+                text: input.text,
+            });
+        }
+        catch (error) {
+            // Keep the orchestrator's registration-lag retry classification working:
+            // a DM to an agent the engine has not registered yet is retryable.
+            if (isUnknownRecipientError(error)) {
+                throw new Error(`recipient unavailable: ${errorMessage(error)}`);
+            }
+            throw error;
+        }
+    }
+    #ensureMessaging() {
+        if (this.#messaging)
+            return Promise.resolve(this.#messaging);
+        this.#messagingReady ??= this.#bootstrapMessaging().catch((error) => {
+            // Allow a later call to retry a failed bootstrap (transient network, etc).
+            this.#messagingReady = undefined;
+            throw error;
+        });
+        return this.#messagingReady;
+    }
+    async #bootstrapMessaging() {
+        const env = this.#options.env;
+        const workspaceKey = resolveRelayWorkspaceKey({
+            workspaceKey: this.#options.workspaceKey,
+            ...(env ? { env, activeWorkspaceKey: () => undefined } : {}),
+        });
+        let agentToken = resolveRelayAgentToken({
+            agentToken: this.#options.agentToken,
+            ...(env ? { env } : {}),
+        });
+        if (!workspaceKey && !agentToken) {
+            throw new Error('RelayFleetClient requires a workspace key (rk_live_…) or agent token (at_live_…); set RELAY_WORKSPACE_KEY or RELAY_AGENT_TOKEN');
+        }
+        if (!agentToken) {
+            agentToken = await this.#registerFactoryAgent(workspaceKey);
+        }
+        const relay = this.#createRelay({
+            ...(workspaceKey ? { workspaceKey } : {}),
+            agentToken,
+            ...(this.#options.baseUrl ? { baseUrl: this.#options.baseUrl } : {}),
+        });
+        this.#messaging = relay.messaging;
+        return this.#messaging;
+    }
+    // Rotate-on-start is idempotent and leaves nothing secret on disk: the
+    // factory adopts its standing workspace identity and mints a fresh token.
+    async #registerFactoryAgent(workspaceKey) {
+        const bootstrap = this.#createRelay({
+            workspaceKey,
+            ...(this.#options.baseUrl ? { baseUrl: this.#options.baseUrl } : {}),
+        });
+        const agents = bootstrap.messaging.agents;
+        const register = agents.registerOrRotate?.bind(agents) ?? agents.register.bind(agents);
+        const registration = await register({ name: this.#agentName });
+        return registration.token;
+    }
+    async #awaitInvocation(actionName, ack) {
+        const messaging = await this.#ensureMessaging();
+        let status = ack.status ?? 'pending';
         let invocation;
-        const deadline = Date.now() + this.#completionTimeoutMs;
+        const deadline = Date.now() + this.#spawnAckTimeoutMs;
         while (!terminalStatuses.has(status)) {
             if (Date.now() > deadline) {
-                throw new Error(`Timed out waiting for ${actionName} invocation ${invocationId} to complete (last status: ${status})`);
+                throw new Error(`Timed out waiting for ${actionName} invocation ${ack.invocationId} to complete (last status: ${status})`);
             }
             if (!openStatuses.has(status)) {
-                throw new Error(`Unexpected ${actionName} invocation ${invocationId} status: ${status}`);
+                throw new Error(`Unexpected ${actionName} invocation ${ack.invocationId} status: ${status}`);
             }
             await this.#sleep(this.#pollIntervalMs);
-            invocation = await this.#getTransport().getInvocation(actionName, invocationId);
-            status = invocation.status ?? 'pending';
+            invocation = await messaging.commands.getInvocation(actionName, ack.invocationId);
+            status = invocation.status || 'pending';
         }
-        invocation ??= await this.#getTransport().getInvocation(actionName, invocationId);
+        invocation ??= await messaging.commands.getInvocation(actionName, ack.invocationId);
         if (status === 'failed' || status === 'denied') {
-            throw new Error(`${actionName} invocation ${invocationId} ${status}${invocation.error ? `: ${invocation.error}` : ''}`);
+            throw new Error(`${actionName} invocation ${ack.invocationId} ${status}${invocation.error ? `: ${invocation.error}` : ''}`);
         }
         return invocation;
     }
-    #ensureEventSubscription() {
-        if (this.#subscribed)
-            return;
-        this.#subscribed = true;
-        const unsubscribe = this.#getTransport().onEvent?.((event) => this.#handleEvent(event));
-        if (unsubscribe)
-            this.#eventUnsubscribers.push(unsubscribe);
+    #track(name, ack) {
+        this.#tracked.set(name, {
+            invocationId: ack.invocationId,
+            node: ack.placement?.node ?? ack.dispatchedNodeId ?? undefined,
+            spawnedAtMs: this.#now(),
+        });
+        this.#syncExitWatcher();
+    }
+    #syncExitWatcher() {
+        const shouldRun = !this.#disposed && this.#tracked.size > 0 && this.#agentExitListeners.size > 0;
+        if (shouldRun && !this.#watchTimer) {
+            this.#watchTimer = setInterval(() => {
+                void this.reconcileTrackedAgents().catch((error) => {
+                    this.#log(`relay fleet exit reconciliation failed: ${errorMessage(error)}`);
+                });
+            }, this.#exitWatchIntervalMs);
+            this.#watchTimer.unref?.();
+        }
+        else if (!shouldRun && this.#watchTimer) {
+            clearInterval(this.#watchTimer);
+            this.#watchTimer = undefined;
+        }
     }
-    #handleEvent(event) {
-        const deliveryFailed = deliveryFailedFromEvent(event);
-        if (deliveryFailed) {
-            for (const listener of this.#deliveryFailedListeners) {
-                listener(deliveryFailed);
+    async #reconcileTracked() {
+        if (this.#tracked.size === 0)
+            return;
+        const messaging = await this.#ensureMessaging();
+        const [agents, nodes] = await Promise.all([
+            messaging.agents.list({ status: 'all' }),
+            messaging.nodes.list(),
+        ]);
+        const agentsByName = new Map(agents.map((agent) => [agent.name, agent]));
+        const nodeLive = new Map(nodes.map((node) => [node.name, node.live ?? node.status === 'online']));
+        const nowMs = this.#now();
+        for (const [name, entry] of [...this.#tracked]) {
+            const row = agentsByName.get(name);
+            if (!row || row.status === 'offline') {
+                // A just-spawned agent may not have registered with the engine yet;
+                // absence only counts as an exit once the grace window has passed.
+                if (nowMs - entry.spawnedAtMs < this.#registrationGraceMs)
+                    continue;
+                this.#emitExit(name, 'exited');
+                continue;
             }
-        }
-        const message = agentMessageFromEvent(event);
-        if (message) {
-            for (const listener of this.#agentMessageListeners) {
-                listener(message);
+            if (!entry.node)
+                continue;
+            if (nodeLive.get(entry.node) === false || !nodeLive.has(entry.node)) {
+                entry.nodeOfflineSinceMs ??= nowMs;
+                if (nowMs - entry.nodeOfflineSinceMs >= this.#nodeOfflineGraceMs) {
+                    this.#emitExit(name, 'node-offline');
+                }
             }
-        }
-        const exit = agentExitFromEvent(event);
-        if (exit) {
-            for (const listener of this.#agentExitListeners) {
-                listener(exit.name, exit.reason);
+            else {
+                entry.nodeOfflineSinceMs = undefined;
             }
         }
     }
-}
-class HttpRelayFleetTransport {
-    #baseUrl;
-    #token;
-    #fetch;
-    #eventListeners = new Set();
-    #socket;
-    constructor(options) {
-        this.#baseUrl = (options.baseUrl ?? env('RELAYCAST_BASE_URL') ?? env('AGENT_RELAY_BASE_URL') ?? 'https://api.relaycast.dev').replace(/\/+$/, '');
-        this.#token = options.agentToken ?? env('RELAY_AGENT_TOKEN') ?? options.workspaceKey ?? env('RELAY_WORKSPACE_KEY') ?? env('RELAY_API_KEY') ?? '';
-        if (!this.#token) {
-            throw new Error('RelayFleetClient requires agentToken or workspaceKey (or RELAY_AGENT_TOKEN / RELAY_WORKSPACE_KEY)');
+    #emitExit(name, reason) {
+        this.#tracked.delete(name);
+        this.#syncExitWatcher();
+        for (const listener of this.#agentExitListeners) {
+            listener(name, reason);
         }
-        this.#fetch = options.fetch ?? globalFetch;
     }
-    async invokeAction(actionName, input, opts) {
-        const data = await this.#request(`/v1/actions/${encodeURIComponent(actionName)}/invoke`, {
-            input,
-            invocation_id: opts.invocationId,
-            invocationId: opts.invocationId,
+    #ensureEventSubscription() {
+        if (this.#eventsStarted)
+            return;
+        this.#eventsStarted = true;
+        void this.#subscribeEvents().catch((error) => {
+            this.#eventsStarted = false;
+            this.#log(`relay fleet event subscription failed: ${errorMessage(error)}`);
         });
-        return invocationAckFrom(data, opts.invocationId, actionName);
-    }
-    async getInvocation(actionName, invocationId) {
-        const data = await this.#request(`/v1/actions/${encodeURIComponent(actionName)}/invocations/${encodeURIComponent(invocationId)}`);
-        return invocationFrom(data, invocationId, actionName);
-    }
-    async listAgents() {
-        const data = await this.#request('/v1/agents?status=all');
-        return Array.isArray(data) ? data.map(agentFrom).filter(isRelayFleetAgent) : [];
-    }
-    async listNodes() {
-        const data = await this.#request('/v1/nodes');
-        return Array.isArray(data) ? data.map(nodeFrom).filter(isRelayFleetNode) : [];
-    }
-    async sendMessage(input) {
-        const data = input.to.startsWith('#')
-            ? await this.#request(`/v1/channels/${encodeURIComponent(input.to.slice(1))}/messages`, {
-                text: input.text,
-                ...(input.data ? { metadata: input.data } : {}),
-            })
-            : await this.#request('/v1/dm', {
-                to: input.to.startsWith('@') ? input.to.slice(1) : input.to,
-                text: input.text,
-                ...(input.data ? { metadata: input.data } : {}),
-            });
-        return {
-            eventId: readString(asRecord(data), 'id', 'message_id', 'event_id'),
-            targets: [input.to],
-        };
-    }
-    onEvent(listener) {
-        this.#eventListeners.add(listener);
-        this.#connectEvents();
-        return () => {
-            this.#eventListeners.delete(listener);
-            if (this.#eventListeners.size === 0) {
-                this.#socket?.close();
-                this.#socket = undefined;
-            }
-        };
     }
-    dispose() {
-        this.#socket?.close();
-        this.#socket = undefined;
-        this.#eventListeners.clear();
+    async #subscribeEvents() {
+        const messaging = await this.#ensureMessaging();
+        if (this.#disposed)
+            return;
+        messaging.events.connect();
+        this.#eventUnsubscribers.push(messaging.events.on('any', (event) => this.#handleEvent(event)));
     }
-    async #request(path, body) {
-        const response = await this.#fetch(`${this.#baseUrl}${path}`, {
-            method: body ? 'POST' : 'GET',
-            headers: {
-                Authorization: `Bearer ${this.#token}`,
-                ...(body ? { 'Content-Type': 'application/json' } : {}),
-            },
-            ...(body ? { body: JSON.stringify(body) } : {}),
-        });
-        const payload = await readResponsePayload(response);
-        const record = asRecord(payload);
-        if (!response.ok || record?.ok === false) {
-            const error = asRecord(record?.error);
-            const message = readString(error, 'message') ?? response.statusText;
-            throw new Error(`Relay fleet request failed (${response.status}): ${message}`);
+    #handleEvent(event) {
+        switch (event.type) {
+            case 'dmReceived':
+            case 'groupDmReceived':
+                this.#emitAgentMessage(event.message, this.#agentName);
+                break;
+            case 'messageCreated':
+            case 'threadReply':
+                this.#emitAgentMessage(event.message, event.channel);
+                break;
+            case 'agentOffline':
+                this.#handleAgentOffline(event.agent.name);
+                break;
+            default:
+                break;
         }
-        return record && 'data' in record ? record.data : payload;
     }
-    #connectEvents() {
-        if (this.#socket)
+    #emitAgentMessage(message, fallbackTarget) {
+        const from = message.from?.name;
+        if (!from || from === this.#agentName)
             return;
-        const WebSocketCtor = globalThis.WebSocket;
-        if (!WebSocketCtor)
-            return;
-        const url = new URL('/v1/ws', this.#baseUrl.replace(/^http/, 'ws'));
-        url.searchParams.set('token', this.#token);
-        const socket = new WebSocketCtor(url.toString());
-        this.#socket = socket;
-        socket.onmessage = (message) => {
-            try {
-                const parsed = JSON.parse(String(message.data));
-                if (parsed && typeof parsed === 'object') {
-                    this.#emitEvent(parsed);
-                }
-            }
-            catch {
-                // Drop malformed event frames; the polling path remains authoritative for invocations.
-            }
-        };
-        socket.onclose = () => {
-            if (this.#socket === socket)
-                this.#socket = undefined;
-        };
-        socket.onerror = () => {
-            if (this.#socket === socket)
-                this.#socket = undefined;
-            try {
-                socket.close();
-            }
-            catch {
-                // noop
-            }
+        let target;
+        const messageTarget = message.target;
+        if (messageTarget?.kind === 'agent' && typeof messageTarget.agentName === 'string') {
+            target = messageTarget.agentName;
+        }
+        else if (messageTarget?.kind === 'channel' && typeof messageTarget.channelName === 'string') {
+            target = messageTarget.channelName;
+        }
+        const agentMessage = {
+            from,
+            target: target ?? fallbackTarget,
+            body: message.text,
+            ...(message.threadId || message.parentId ? { threadId: message.threadId ?? message.parentId } : {}),
+            ...(message.id ? { eventId: message.id } : {}),
         };
-    }
-    #emitEvent(event) {
-        for (const listener of this.#eventListeners) {
-            listener(event);
+        for (const listener of this.#agentMessageListeners) {
+            listener(agentMessage);
         }
     }
+    // Presence offline is a push hint for exits of agents this client spawned.
+    // The roster reconciliation watcher remains the authoritative exit detector.
+    #handleAgentOffline(name) {
+        if (!this.#tracked.has(name))
+            return;
+        this.#emitExit(name, 'offline');
+    }
 }
-function spawnActionInput(input, opts) {
+// Placement injects capability/node/target_node/repo/cli on top of this
+// payload; spawn_mode/exit_after_task request task-exit lifecycle from the
+// broker on the placed node.
+function spawnActionInput(input) {
     return definedRecord({
-        capability: input.capability,
         name: input.name,
         agent: input.name,
-        node: input.node && (opts.includeSelfNode || input.node !== 'self') ? input.node : undefined,
-        repo: input.repo,
         clone_path: input.clonePath,
         clonePath: input.clonePath,
         session_ref: input.sessionRef,
@@ -321,6 +426,7 @@ function spawnActionInput(input, opts) {
         cwd: input.cwd,
         channels: input.channel ? [input.channel] : undefined,
         restart_policy: input.restartPolicy,
+        ...(input.capability.startsWith('spawn:') ? { spawn_mode: 'task_exit', exit_after_task: true } : {}),
     });
 }
 function spawnResultFromInvocation(fallbackName, fallbackSessionRef, invocation) {
@@ -341,109 +447,16 @@ function spawnResultFromInvocation(fallbackName, fallbackSessionRef, invocation)
 }
 function normalizeCapabilities(capabilities) {
     const names = (capabilities ?? [])
-        .map((capability) => typeof capability === 'string' ? capability : capability.name)
-        .filter((capability) => typeof capability === 'string' && knownCapabilities.has(capability));
+        .map((capability) => capability.name)
+        .filter((name) => knownCapabilities.has(name));
     return [...new Set(names)];
 }
-function deliveryFailedFromEvent(event) {
-    const type = event.type;
-    if (type !== 'delivery.failed' && type !== 'delivery_failed')
-        return undefined;
-    const to = readString(event, 'to', 'recipient', 'recipient_name', 'recipientName', 'agent_name', 'agentName');
-    if (!to)
-        return undefined;
-    return definedRecord({
-        to,
-        msgId: readString(event, 'message_id', 'messageId', 'msg_id', 'msgId', 'id'),
-        reason: readString(event, 'reason', 'error'),
-    });
+function isUnknownRecipientError(error) {
+    const message = errorMessage(error);
+    return /not[ _]found|unknown (agent|recipient)|no such (agent|recipient)|unregistered/i.test(message);
 }
-function agentMessageFromEvent(event) {
-    const type = event.type;
-    if (type !== 'message.created' && type !== 'dm.received' && type !== 'group_dm.received' && type !== 'thread.reply') {
-        return undefined;
-    }
-    const message = asRecord(event.message) ?? event;
-    const fromRecord = asRecord(message.from);
-    const target = asRecord(message.target);
-    const from = readString(fromRecord, 'name') ?? readString(message, 'from', 'from_name', 'fromName', 'agent_name', 'agentName');
-    const body = readString(message, 'text', 'body');
-    if (!from || body === undefined)
-        return undefined;
-    const targetName = readString(target, 'agentName', 'agent_name', 'channelName', 'channel_name')
-        ?? readString(message, 'to', 'target', 'channel', 'channel_name', 'channelName')
-        ?? 'factory';
-    return definedRecord({
-        from,
-        target: targetName,
-        body,
-        threadId: readString(message, 'threadId', 'thread_id', 'parentId', 'parent_id'),
-        eventId: readString(message, 'id', 'messageId', 'message_id', 'event_id', 'eventId'),
-    });
-}
-function agentExitFromEvent(event) {
-    const type = event.type;
-    if (type !== 'agent.exited' && type !== 'agent.exit' && type !== 'agent.status.offline' && type !== 'session.released') {
-        return undefined;
-    }
-    const agent = asRecord(event.agent);
-    const name = readString(event, 'name', 'agent_name', 'agentName') ?? readString(agent, 'name');
-    if (!name)
-        return undefined;
-    return definedRecord({
-        name,
-        reason: readString(event, 'reason', 'status') ?? (type === 'agent.status.offline' ? 'offline' : undefined),
-    });
-}
-function invocationAckFrom(value, fallbackInvocationId, fallbackActionName) {
-    const record = asRecord(value) ?? {};
-    return {
-        invocationId: readString(record, 'invocation_id', 'invocationId') ?? fallbackInvocationId,
-        actionName: readString(record, 'action_name', 'actionName') ?? fallbackActionName,
-        status: readString(record, 'status'),
-        dispatchedNodeId: readString(record, 'dispatched_node_id', 'dispatchedNodeId') ?? null,
-        input: asRecord(record.input),
-    };
-}
-function invocationFrom(value, fallbackInvocationId, fallbackActionName) {
-    const record = asRecord(value) ?? {};
-    return {
-        ...invocationAckFrom(record, fallbackInvocationId, fallbackActionName),
-        output: record.output,
-        error: readString(record, 'error') ?? null,
-        completedAt: readString(record, 'completed_at', 'completedAt') ?? null,
-    };
-}
-function agentFrom(value) {
-    const record = asRecord(value);
-    const name = readString(record, 'name');
-    return name ? { name } : undefined;
-}
-function isRelayFleetAgent(value) {
-    return !!value;
-}
-function nodeFrom(value) {
-    const record = asRecord(value);
-    const name = readString(record, 'name');
-    if (!record || !name)
-        return undefined;
-    return {
-        name,
-        status: readString(record, 'status'),
-        live: readBoolean(record, 'live') ?? readBoolean(record, 'handlers_live', 'handlersLive'),
-        capabilities: Array.isArray(record.capabilities) ? record.capabilities : [],
-    };
-}
-function isRelayFleetNode(value) {
-    return !!value;
-}
-async function readResponsePayload(response) {
-    try {
-        return await response.json();
-    }
-    catch {
-        return await response.text();
-    }
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
 }
 function definedRecord(input) {
     return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
@@ -473,16 +486,6 @@ function readNumber(record, ...keys) {
     }
     return undefined;
 }
-function readBoolean(record, ...keys) {
-    if (!record)
-        return undefined;
-    for (const key of keys) {
-        const value = record[key];
-        if (typeof value === 'boolean')
-            return value;
-    }
-    return undefined;
-}
 function readNumberArray(record, ...keys) {
     if (!record)
         return undefined;
@@ -496,14 +499,4 @@ function readNumberArray(record, ...keys) {
     }
     return undefined;
 }
-function newInvocationId(prefix, name) {
-    return `factory:${prefix}:${name}:${randomUUID()}`;
-}
-function env(name) {
-    const value = process.env[name];
-    return value && value.trim() ? value.trim() : undefined;
-}
-function globalFetch(...args) {
-    return fetch(...args);
-}
 //# sourceMappingURL=relay-fleet-client.js.map