@agent-relay/factory 0.1.72 → 0.1.74

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

@@ -1,5 +1,8 @@
+import { createHash } from 'node:crypto';
 import { AgentRelay } from '@agent-relay/sdk';
+import { describeControlPlaneError } from './control-plane-circuit.js';
 import { resolveRelayAgentToken, resolveRelayWorkspaceKey } from './relay-workspace-key.js';
+import { RelaycastTeammateDirectory } from './teammates.js';
 const knownCapabilities = new Set(['spawn:claude', 'spawn:codex', 'workflow:run', 'preview:tailscale-serve']);
 const openStatuses = new Set(['pending', 'dispatched', 'invoked']);
 const terminalStatuses = new Set(['completed', 'failed', 'denied']);
@@ -112,11 +115,26 @@ export class RelayFleetClient {
     // therefore createFleet({ backend: 'relay' })) never throws merely because no
     // token is configured.
     #messaging;
+    #teammateDirectory;
     #messagingReady;
+    #messageStreamIdentityReady;
     #lifecycleActionReady;
     #authenticatedAgentName;
     #eventsStarted = false;
+    #eventSubscriptionReady;
+    #messageObservabilityReady;
+    #resolveMessageObservability;
+    #rejectMessageObservability;
     #disposed = false;
+    /**
+     * The fleet socket's own status.
+     *
+     * Kept here rather than inferred by callers because the dial is
+     * fire-and-forget: `#ensureEventSubscription` cannot return its outcome, so
+     * without this the ONLY trace of a failed connect was a `#log` line that no
+     * health surface reads.
+     */
+    #fleetConnect = { state: 'never-attempted', attempts: 0 };
     #watchTimer;
     #reconciling;
     #pendingReleaseRetry;
@@ -146,6 +164,7 @@ export class RelayFleetClient {
         this.#log = options.log ?? (() => { });
         this.#readOnly = options.readOnly ?? false;
         this.#messaging = options.messaging;
+        this.#teammateDirectory = options.teammateDirectory;
     }
     /** Agents spawned through this client that have not exited or been released. */
     trackedAgents() {
@@ -416,8 +435,84 @@ export class RelayFleetClient {
             })),
         };
     }
+    async discoverTeammates(query) {
+        this.#teammateDirectory ??= this.#createTeammateDirectory();
+        return await this.#teammateDirectory.discover(query);
+    }
     // `from`/`data` are not representable on the agent-scoped messaging surface:
     // every send is authored by the factory's own agent identity.
+    //
+    // That identity is also the `target` stamped on every inbound message (see
+    // `#emitAgentMessage`), so a reply waiter must match against it rather than
+    // against the `from` its caller asked to send as.
+    //
+    // `#authenticatedAgentName` starts life as the CONFIGURED `agentName` and is
+    // only replaced with the server's answer once something has called
+    // `agents.me()`. Returning it synchronously would hand out that pre-auth
+    // guess, which is wrong whenever an injected `messaging` or an existing
+    // `agentToken` authenticates as a different name. Resolve it for real.
+    async effectiveSender() {
+        const messaging = await this.#ensureMessaging();
+        const identity = await messaging.agents.me();
+        const resolved = identity.name?.trim();
+        if (resolved)
+            this.#authenticatedAgentName = resolved;
+        return this.#authenticatedAgentName;
+    }
+    /**
+     * Identify the actual Relay workspace stream rather than this wrapper.
+     * Multiple clients authenticated to one workspace receive the same direct
+     * messages, so their uncorrelated ask/reply claims must contend.
+     */
+    async messageStreamIdentity() {
+        this.#messageStreamIdentityReady ??= (async () => {
+            const messaging = await this.#ensureMessaging();
+            const baseUrl = canonicalRelayBaseUrl(this.#options.baseUrl);
+            const explicitScope = this.#options.messageStreamScope;
+            if (this.#options.messaging && explicitScope !== undefined) {
+                if (typeof explicitScope === 'string') {
+                    const fingerprint = createHash('sha256').update(explicitScope).digest('base64url');
+                    return `relay:${baseUrl}:explicit:${fingerprint}`;
+                }
+                return explicitScope;
+            }
+            try {
+                const workspace = await messaging.workspace.info();
+                const workspaceId = typeof workspace.id === 'string' ? workspace.id.trim() : '';
+                if (workspaceId)
+                    return `relay:${baseUrl}:workspace:${workspaceId}`;
+            }
+            catch (error) {
+                // Older/injected messaging surfaces may not expose workspace.info(). A
+                // credential fingerprint or the injected object below still preserves
+                // a stable boundary without failing an otherwise usable message path.
+                this.#log(`Unable to resolve Relay workspace identity for teammate claims: ${errorMessage(error)}`);
+            }
+            // Separate injected wrappers are not evidence of separate streams. If
+            // the surface cannot identify its workspace and the caller supplied no
+            // explicit scope, fail closed by sharing one endpoint-scoped registry.
+            // This may conservatively serialize identical participants in two legacy
+            // workspaces, but it cannot admit two waiters for one unknown stream.
+            if (this.#options.messaging)
+                return `relay:${baseUrl}:injected:unknown`;
+            const env = this.#options.env;
+            const agentToken = resolveRelayAgentToken({
+                agentToken: this.#registeredAgentToken ?? this.#options.agentToken,
+                ...(env ? { env } : {}),
+            });
+            const workspaceKey = resolveRelayWorkspaceKey({
+                workspaceKey: this.#options.workspaceKey,
+                ...(env ? { env, activeWorkspaceKey: () => undefined } : {}),
+            });
+            const credential = agentToken ?? workspaceKey;
+            if (credential) {
+                const fingerprint = createHash('sha256').update(credential).digest('base64url');
+                return `relay:${baseUrl}:credential:${fingerprint}`;
+            }
+            return messaging;
+        })();
+        return await this.#messageStreamIdentityReady;
+    }
     async sendMessage(input) {
         await this.#send(input);
     }
@@ -484,6 +579,7 @@ export class RelayFleetClient {
             }
         }
         this.#disposed = true;
+        this.#settleMessageObservability(new Error('Relay fleet client disposed before its event stream connected'));
         if (this.#watchTimer) {
             clearInterval(this.#watchTimer);
             this.#watchTimer = undefined;
@@ -527,6 +623,25 @@ export class RelayFleetClient {
             throw error;
         }
     }
+    #createTeammateDirectory() {
+        const env = this.#options.env;
+        const token = resolveRelayWorkspaceKey({
+            workspaceKey: this.#options.workspaceKey,
+            ...(env ? { env, activeWorkspaceKey: () => undefined } : {}),
+        }) ?? resolveRelayAgentToken({
+            agentToken: this.#options.agentToken,
+            ...(env ? { env } : {}),
+        });
+        if (!token) {
+            throw new Error('RelayFleetClient teammate discovery requires a workspace key or agent token');
+        }
+        return new RelaycastTeammateDirectory({
+            baseUrl: this.#options.baseUrl,
+            token,
+            fetch: this.#options.directoryFetch,
+            timeoutMs: this.#options.directoryTimeoutMs,
+        });
+    }
     #ensureMessaging() {
         if (this.#messaging)
             return Promise.resolve(this.#messaging);
@@ -586,7 +701,7 @@ export class RelayFleetClient {
     async #registerFactoryAgent(workspaceKey) {
         this.#registrationAttempts += 1;
         if (this.#registrationAttempts > MAX_REGISTRATION_ATTEMPTS) {
-            throw new FactoryAgentRegistrationError(this.#agentName, `gave up after ${MAX_REGISTRATION_ATTEMPTS} registration attempts`);
+            throw new FactoryAgentRegistrationError(this.#agentName, 'MAX_ATTEMPTS', `gave up after ${MAX_REGISTRATION_ATTEMPTS} registration attempts`);
         }
         const bootstrap = this.#createRelay({
             workspaceKey,
@@ -721,7 +836,7 @@ export class RelayFleetClient {
             const existing = asRecord(await agents.get(this.#agentName).catch(() => undefined));
             const agentId = readString(existing, 'id', 'agent_id', 'agentId');
             if (!agentId) {
-                throw new FactoryAgentRegistrationError(this.#agentName, `name is taken but the record could not be read back: ${errorMessage(lastError)}`, { cause: lastError });
+                throw new FactoryAgentRegistrationError(this.#agentName, 'RECORD_UNREADABLE', `name is taken but the record could not be read back: ${errorMessage(lastError)}`, { cause: lastError });
             }
             await this.#assertAgentNotLive(agents, existing);
             try {
@@ -733,10 +848,10 @@ export class RelayFleetClient {
                     continue;
                 if (error instanceof FactoryAgentRegistrationError)
                     throw error;
-                throw new FactoryAgentRegistrationError(this.#agentName, `could not reclaim the existing identity: ${errorMessage(error)}`, { cause: error });
+                throw new FactoryAgentRegistrationError(this.#agentName, 'TAKEOVER_FAILED', `could not reclaim the existing identity: ${errorMessage(error)}`, { cause: error });
             }
         }
-        throw new FactoryAgentRegistrationError(this.#agentName, `could not reclaim the existing identity: ${errorMessage(lastError)}`, { cause: lastError });
+        throw new FactoryAgentRegistrationError(this.#agentName, 'TAKEOVER_EXHAUSTED', `could not reclaim the existing identity: ${errorMessage(lastError)}`, { cause: lastError });
     }
     // Seizing a name from a LIVE agent would strand its credential. Our case is a
     // collision with our own dead record, but the guard is coded rather than
@@ -748,7 +863,7 @@ export class RelayFleetClient {
         // record that says offline gets as far as the presence check.
         const status = readString(existing, 'status');
         if (status !== 'offline') {
-            throw new FactoryAgentRegistrationError(this.#agentName, `refusing to take over agent in status "${status ?? 'unknown'}"; another factory may still hold this identity`);
+            throw new FactoryAgentRegistrationError(this.#agentName, 'STATUS_NOT_OFFLINE', `refusing to take over agent in status "${status ?? 'unknown'}"; another factory may still hold this identity`);
         }
         // Presence is the canonical liveness signal, and the agent record can be
         // stale. Two outcomes are routed apart here, and collapsing them swaps one
@@ -782,10 +897,10 @@ export class RelayFleetClient {
         }
         const seenStatus = readString(entry, 'status');
         if (seenStatus === undefined) {
-            throw new FactoryAgentRegistrationError(this.#agentName, 'presence lists this agent with no status, so it cannot be confirmed offline');
+            throw new FactoryAgentRegistrationError(this.#agentName, 'PRESENCE_STATUS_MISSING', 'presence reported no status for this agent, so it cannot be confirmed offline');
         }
         if (LIVE_AGENT_STATUSES.has(seenStatus)) {
-            throw new FactoryAgentRegistrationError(this.#agentName, `presence reports this agent as "${seenStatus}"; another factory may still hold this identity`);
+            throw new FactoryAgentRegistrationError(this.#agentName, 'PRESENCE_REPORTS_LIVE', `presence reports this agent as "${seenStatus}"; another factory may still hold this identity`);
         }
     }
     /**
@@ -803,10 +918,10 @@ export class RelayFleetClient {
             presence = await agents.presence();
         }
         catch (error) {
-            throw new FactoryAgentRegistrationError(this.#agentName, `presence is unreadable, so the agent cannot be confirmed offline: ${errorMessage(error)}`, { cause: error });
+            throw new FactoryAgentRegistrationError(this.#agentName, 'PRESENCE_UNREADABLE', `presence is unreadable, so the agent cannot be confirmed offline: ${errorMessage(error)}`, { cause: error });
         }
         if (!Array.isArray(presence)) {
-            throw new FactoryAgentRegistrationError(this.#agentName, 'presence is unreadable (it did not return a list), so the agent cannot be confirmed offline');
+            throw new FactoryAgentRegistrationError(this.#agentName, 'PRESENCE_NOT_A_LIST', 'presence is unreadable (it did not return a list), so the agent cannot be confirmed offline');
         }
         // A list whose rows we cannot name is not readable either, however
         // well-formed the array around them is. Omission only means absence if a
@@ -817,7 +932,7 @@ export class RelayFleetClient {
         // here, on the read, rather than inferred from the lookup missing.
         const unnamed = presence.findIndex((row) => readString(asRecord(row), 'agentName', 'agent_name', 'name') === undefined);
         if (unnamed !== -1) {
-            throw new FactoryAgentRegistrationError(this.#agentName, `presence is unreadable (row ${unnamed} carries no agent name), so the agent cannot be confirmed offline`);
+            throw new FactoryAgentRegistrationError(this.#agentName, 'PRESENCE_ROW_UNNAMED', `presence is unreadable (row ${unnamed} carries no agent name), so the agent cannot be confirmed offline`);
         }
         return presence;
     }
@@ -977,20 +1092,103 @@ export class RelayFleetClient {
         if (this.#eventsStarted)
             return;
         this.#eventsStarted = true;
-        void this.#subscribeEvents().catch((error) => {
+        this.#fleetConnect = {
+            ...this.#fleetConnect,
+            state: 'connecting',
+            attempts: this.#fleetConnect.attempts + 1,
+            lastAttemptAtMs: this.#now(),
+        };
+        this.#eventSubscriptionReady = this.#subscribeEvents().catch((error) => {
             this.#eventsStarted = false;
+            this.#eventSubscriptionReady = undefined;
+            // The rejection now lands in a field a health surface can publish. It kept
+            // going only to `#log` before, which is why a fleet client that never
+            // connected was indistinguishable from a healthy one everywhere.
+            this.#fleetConnect = {
+                ...this.#fleetConnect,
+                state: 'failed',
+                lastFailureAtMs: this.#now(),
+                lastError: describeControlPlaneError(error),
+            };
             this.#log(`relay fleet event subscription failed: ${errorMessage(error)}`);
+            throw error;
         });
+        // Nothing here awaits it -- callers that must not miss an inbound message
+        // use `whenMessagesObservable()`. The rejection is re-thrown for them and
+        // swallowed here so a background subscription failure stays non-fatal.
+        void this.#eventSubscriptionReady.catch(() => { });
+    }
+    // `onAgentMessage` returns as soon as the listener is in the local set, but
+    // the SDK handler behind it is installed by an async chain (messaging
+    // bootstrap, then lifecycle registration, then `events.connect()`). A caller
+    // that registers a listener and immediately sends can therefore lose a fast
+    // reply that lands before the transport is actually listening. Await this
+    // between the two.
+    async whenMessagesObservable() {
+        this.#ensureEventSubscription();
+        await this.#eventSubscriptionReady;
+        if (this.#fleetConnect.state === 'connected')
+            return;
+        await this.#messageObservabilityPromise();
+    }
+    #messageObservabilityPromise() {
+        if (this.#fleetConnect.state === 'connected')
+            return Promise.resolve();
+        if (!this.#messageObservabilityReady) {
+            const pending = new Promise((resolve, reject) => {
+                this.#resolveMessageObservability = resolve;
+                this.#rejectMessageObservability = reject;
+            });
+            this.#messageObservabilityReady = pending;
+            // The ask-level deadline may stop awaiting this shared handshake first.
+            // Retain the waiter for another caller, but never surface its later
+            // transport rejection as an unhandled promise.
+            void pending.catch(() => { });
+        }
+        return this.#messageObservabilityReady;
+    }
+    #settleMessageObservability(error) {
+        const resolve = this.#resolveMessageObservability;
+        const reject = this.#rejectMessageObservability;
+        this.#messageObservabilityReady = undefined;
+        this.#resolveMessageObservability = undefined;
+        this.#rejectMessageObservability = undefined;
+        if (error)
+            reject?.(error);
+        else
+            resolve?.();
+    }
+    fleetConnectStatus() {
+        return { ...this.#fleetConnect };
     }
     async #subscribeEvents() {
         const messaging = await this.#ensureMessaging();
-        await this.#ensureLifecycleAction(messaging);
+        if (this.#options.registerLifecycleAction !== false) {
+            await this.#ensureLifecycleAction(messaging);
+        }
         if (this.#disposed)
             return;
-        messaging.events.connect();
-        this.#eventUnsubscribers.push(messaging.events.on('any', (event) => this.#handleEvent(event)));
+        // Listen before dialing so a synchronous lifecycle event cannot race past
+        // the observer. `connect()` is void: returning only proves the SDK accepted
+        // the dial, not that the WebSocket handshake completed.
+        const unsubscribe = messaging.events.on('any', (event) => this.#handleEvent(event));
+        const statusBeforeDial = this.#fleetConnect;
+        try {
+            messaging.events.connect();
+        }
+        catch (error) {
+            unsubscribe();
+            throw error;
+        }
+        this.#eventUnsubscribers.push(unsubscribe);
+        this.#fleetConnect = {
+            ...this.#fleetConnect,
+            ...(this.#fleetConnect === statusBeforeDial ? { state: 'dialed' } : {}),
+            lastDialedAtMs: this.#now(),
+        };
     }
     #handleEvent(event) {
+        this.#observeFleetConnectionEvent(event);
         switch (event.type) {
             case 'dmReceived':
             case 'groupDmReceived':
@@ -1012,6 +1210,45 @@ export class RelayFleetClient {
                 break;
         }
     }
+    /** Translate the SDK's real stream lifecycle into the published status. */
+    #observeFleetConnectionEvent(event) {
+        const now = this.#now();
+        switch (event.type) {
+            case 'disconnected':
+            case 'permanentlyDisconnected':
+                this.#fleetConnect = {
+                    ...this.#fleetConnect,
+                    state: 'failed',
+                    lastFailureAtMs: now,
+                    lastError: 'RelayEventStreamDisconnected',
+                };
+                this.#settleMessageObservability(new Error('Relay event stream disconnected before becoming observable'));
+                return;
+            case 'error':
+                this.#fleetConnect = {
+                    ...this.#fleetConnect,
+                    state: 'failed',
+                    lastFailureAtMs: now,
+                    lastError: 'RelayEventStreamError',
+                };
+                this.#settleMessageObservability(new Error('Relay event stream failed before becoming observable'));
+                return;
+            case 'reconnecting':
+                this.#fleetConnect = { ...this.#fleetConnect, state: 'connecting' };
+                return;
+            default:
+                // `connected` and every data event are confirmations that the event
+                // stream opened. A void `connect()` call alone never reaches this arm.
+                this.#fleetConnect = {
+                    ...this.#fleetConnect,
+                    state: 'connected',
+                    firstEventAtMs: this.#fleetConnect.firstEventAtMs ?? now,
+                    ...(this.#fleetConnect.state !== 'connected' ? { lastConnectedAtMs: now } : {}),
+                    lastError: undefined,
+                };
+                this.#settleMessageObservability();
+        }
+    }
     #emitAgentMessage(message, fallbackTarget) {
         const from = message.from?.name;
         if (!from || from === this.#authenticatedAgentName || from === this.#agentName)
@@ -1303,16 +1540,15 @@ function previewReference(value, placementNode) {
         ...(node ? { node } : {}),
     };
 }
-/**
- * Registration could not converge on a usable agent identity. Named so a
- * six-day silent 409 loop surfaces as one actionable failure instead.
- */
 export class FactoryAgentRegistrationError extends Error {
     agentName;
-    constructor(agentName, detail, options) {
+    /** Uppercase token so `describeControlPlaneError` renders it after the name. */
+    code;
+    constructor(agentName, code, detail, options) {
         super(`Factory agent "${agentName}" could not register with the relay workspace: ${detail}`);
         this.name = 'FactoryAgentRegistrationError';
         this.agentName = agentName;
+        this.code = code;
         if (options && 'cause' in options) {
             ;
             this.cause = options.cause;
@@ -1341,6 +1577,15 @@ function isIdentityMovedError(error) {
         return true;
     return /agent_identity_conflict|no longer has expected id/i.test(errorMessage(error));
 }
+function canonicalRelayBaseUrl(value) {
+    const candidate = value ?? DEFAULT_RELAY_BASE_URL;
+    try {
+        return new URL(candidate).toString().replace(/\/$/u, '');
+    }
+    catch {
+        return candidate.replace(/\/$/u, '');
+    }
+}
 function isUnknownRecipientError(error) {
     const message = errorMessage(error);
     return /not[ _]found|unknown (agent|recipient)|no such (agent|recipient)|unregistered/i.test(message);