agent-relay 13.4.1 → 15.0.0-next.0

package/README.md

@@ -346,19 +346,22 @@ sandbox is selected. Ambient credentials and persisted Cloud routing do not
 change the local default. Workforce reporting metadata requires remote placement.
 Automatic placement and release need only the workspace key.
 
-The sandbox path provisions a fresh hosted instance and makes the Relayfile
-mount mandatory by default. Inside a GitHub checkout, Relay infers the Git root,
-repository identity, exact `HEAD`, and caller-relative directory. Cloud uses the
-pinned workspace's connected GitHub credential to seed that revision into
-Relayfile, and the worker starts in the decoded source tree under
-`/workspace/github/repos/<owner>/<repo>/contents`. The long-running Relayfile
-daemon keeps the mounted source tree synchronized with the workspace while
-GitHub push events update the workspace's repository source. Use `--checkout`
-when a task needs a separate static Git clone; that mode keeps the live
-Relayfile mirror available separately. Use `--sandbox-provider daytona` or
-`--sandbox-provider e2b` to require an operator-enabled provider; omit the flag
-to let Cloud's sandbox router choose. Pass `--no-sandbox-relayfile` only when a
-deliberately bare sandbox is desired. If provisioning times out or the spawn
+The sandbox path provisions a fresh hosted instance. Inside a GitHub checkout,
+Relay infers the Git root, repository identity, exact pushed `HEAD`, and caller-relative
+directory. Cloud makes a depth-1 clone, fetches that exact SHA, verifies `HEAD`,
+and starts the worker under `/srv/agent-workforce/<repo>`. Repository tasks start
+without waiting for Relayfile context. `--checkout` explicitly selects the same
+static mode. Outside Git, the default still requires the workspace Relayfile mount.
+
+Use `--sandbox-relayfile` to require live context before dispatch. Without
+`--checkout`, this retains the live repository mirror under
+`/workspace/github/repos/<owner>/<repo>/contents`; with `--checkout`, it mounts
+context separately from the Git clone. An explicit `--sandbox-relayfile-path`
+also requires its selected context before startup. `--no-sandbox-relayfile`
+explicitly disables mounting (combine with `--checkout` to clone repository files).
+Use `--sandbox-provider daytona` or `--sandbox-provider e2b` to require an
+operator-enabled provider; omit the flag to let Cloud's sandbox router choose.
+If provisioning times out or the spawn
 fails, Relay asks Cloud to delete the newly created sandbox. Runs without a
 custom name use one `sbx_<UUID>` identity and the matching
 `fleet-sandbox-<UUID>` node name. Legacy custom `--sandbox-name` values remain supported when no
@@ -380,7 +383,7 @@ reachable from a configured GitHub remote. This prevents a remote worker from
 silently starting at a different revision. Commit and push local work before
 retrying when Relay reports dirty files or an unreachable commit.
 
-With `--checkout`, sandbox provisioning also clones the attested `HEAD` under
+In default repository mode or with `--checkout`, sandbox provisioning clones the attested `HEAD` under
 `/srv/agent-workforce/<repo>`. The checkout must have no tracked changes or
 untracked source files, and the exact commit must be reachable from an origin
 remote. Relay's generated `.agentworkforce/relay/workspace-key.json`,
@@ -403,7 +406,7 @@ release commands reuse the persisted project route; if that remote session is
 unavailable, the command reports the routing failure instead of selecting a
 same-named local worker.
 
-From a clean repository already pinned to a Relay workspace, the ordinary live
+From a clean repository already pinned to a Relay workspace, the checkout-first
 path is:
 
 ```bash
@@ -416,31 +419,44 @@ agent-relay fleet agent list
 agent-relay fleet release cloud-zero-config
 ```
 
-Invoking the live command from `packages/web` starts the worker at
-`/workspace/github/repos/<owner>/<repo>/contents/packages/web`. The repository
-source metadata is available beside `contents` under `.relayfile`, `.skills`
-is mounted from the same workspace, and no `.git` directory is written into the
-Relayfile mirror.
+Invoking the command from `packages/web` starts the worker at
+`/srv/agent-workforce/<repo>/packages/web`, with `.git` available and `HEAD`
+pinned to the requested revision.
 
-For a static Git checkout, opt in explicitly:
+Attach optional context later using `cloudWorkspaceId` and `sandboxId` from the
+spawn response (this uses Cloud sign-in):
 
 ```bash
-agent-relay fleet spawn codex \
-  --name cloud-checkout \
-  --task "Inspect this repository and report its current commit" \
-  --sandbox \
-  --checkout
+agent-relay fleet relayfile attach \
+  --cloud-workspace-id <Cloud-workspace-UUID> \
+  --sandbox-id <sbx_UUID> \
+  --path '/linear' '/.skills'
 ```
 
+Omit `--path` for the full workspace. For a dev sandbox, add
+`--cloud-api-url https://dev.agentrelay.com/cloud`. The command waits at most
+five minutes by default, reports the separate mount path, and does not restart
+the worker or retry a failed attachment. Pending detached preparation is polled
+against the same sandbox within that shared deadline. Tell an already running worker the
+returned path when its task needs that context. The mount uses its own directory;
+it never overlays the Git checkout. Attachment failure leaves the repository task
+running.
+
+For a live repository mirror that must be ready before the task starts, add
+`--sandbox-relayfile` to spawn. Its decoded tree contains no `.git`; its source
+metadata sits beside `contents` under `.relayfile`. Use
+`--checkout --sandbox-relayfile` for a Git checkout plus required live context.
+
 In checkout mode, invoking spawn from `packages/web` places the worker in that
 same relative directory in the remote clone. In both modes, private repositories
 use the pinned workspace's connected GitHub access; a repository-access error
 means that connection must be granted access to the repository. No GitHub token
 or workspace key needs to be copied into the task, mount, or checkout.
 
-With `--checkout`, the Git checkout and Relayfile mirror are separate trees. In
+With `--checkout --sandbox-relayfile`, the Git checkout and Relayfile mirror are
+separate trees. Checkout-only mode has no Relayfile mirror or workspace skills. In
 the ordinary live mode, source files are decoded from Relayfile records without
-placing `.git` in the mirror. Workspace `.skills` are exposed through the agent
+placing `.git` in the mirror. When a live mount is requested at startup, workspace `.skills` are exposed through the agent
 CLIs' usual skill directories, and the worker's task context identifies the
 mirror and exact source revision.
 
@@ -618,7 +634,7 @@ of polling `gh`. `--to self` cannot be combined with `--spawn`.
 
 `local` remains as a deprecated hidden alias of `node` (it prints a one-time warning).
 
-Node workflow runs use Relayflows for YAML, TypeScript, and Python workflow files.
+Node workflow runs use Relayflows for YAML and TypeScript workflow files.
 
 Hosted equivalents live under `agent-relay cloud …`.
 

package/dist/cli/agent-relay-mcp.d.ts

@@ -3,7 +3,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { AgentRelayMcpServerOptions, AgentType, RegistrationSession, RelayCastLike, SessionSetter } from './mcp/types.js';
 export type { AgentRelayMcpServerOptions } from './mcp/types.js';
 export declare const AGENT_RELAY_MCP_VERSION: string;
-export declare const AGENT_RELAY_MCP_INSTRUCTIONS = "You are an AI agent in a collaborative workspace powered by Agent Relay. You can communicate with other agents using these MCP tools:\n\n## Coordination rule\n- When the user asks you to work with, contact, coordinate with, or wait for named participants that already exist in this Agent Relay workspace, use Agent Relay tools such as \"list_agents\", \"send_dm\", \"post_message\", and \"check_inbox\".\n- Existing Relay participants are not local or built-in subagents. Do not replace them with your CLI's native subagent, team, task, or collaboration feature.\n- Do not claim to have contacted or waited for a Relay participant unless the corresponding Relay tool call succeeded.\n\n## Getting Started\n1. The current project workspace is resumed automatically when one was selected before\n2. Call \"create_workspace\" only when you explicitly want to start a new workspace session\n3. If someone shared an existing workspace key with you, call \"set_workspace_key\"\n4. When a workspace key is available at startup, this MCP server auto-registers the session as RELAY_AGENT_NAME (or \"orchestrator\" by default). Otherwise call \"register_agent\" with your agent name to join the workspace\n5. Use \"list_channels\" to see available channels\n6. Use \"join_channel\" to join channels of interest\n7. Use \"check_inbox\" to see unread messages and mentions\n\n## Communication\n- Post messages to channels with \"post_message\"\n- Send direct messages with \"send_dm\"\n- Reply to threads with \"reply_to_thread\"\n- React to messages with \"add_reaction\"\n\n## Fleet\n- Use \"query_nodes\" to find fleet nodes by capability or name\n- Use \"spawn\" with either a CLI or an AgentWorkforce persona to invoke the fleet spawn action on an eligible node\n- Persona spawns require a node exposing \"spawn:persona\" through @agentworkforce/local-surface's defineWorkforcePersonaSpawnNode\n\n## Best Practices\n- Check your inbox regularly for new messages and mentions\n- Use channels for topic-based discussions\n- Use threads for detailed discussions to keep channels organized\n- React with emoji to acknowledge messages\n- Keep messages concise and actionable";
+export declare const AGENT_RELAY_MCP_INSTRUCTIONS = "You are an AI agent in a collaborative workspace powered by Agent Relay. You can communicate with other agents using these MCP tools:\n\n## Coordination rule\n- When the user asks you to work with, contact, coordinate with, or wait for named participants that already exist in this Agent Relay workspace, use Agent Relay tools such as \"list_agents\", \"send_dm\", \"post_message\", and \"check_inbox\".\n- Existing Relay participants are not local or built-in subagents. Do not replace them with your CLI's native subagent, team, task, or collaboration feature.\n- Do not claim to have contacted or waited for a Relay participant unless the corresponding Relay tool call succeeded.\n\n## Getting Started\n1. The current project workspace is resumed automatically when one was selected before\n2. Call \"create_workspace\" only when you explicitly want to start a new workspace session\n3. If someone shared an existing workspace key with you, call \"set_workspace_key\"\n4. When a workspace key is available at startup, this MCP server registers the session automatically: as RELAY_AGENT_NAME when it is set, otherwise as your tool plus the project folder (for example \"claude-myproject\", with a short suffix when another live session holds that name). Call \"register_agent\" to choose a different name, or to join when no workspace key was available\n5. Use \"list_channels\" to see available channels\n6. Use \"join_channel\" to join channels of interest\n7. Use \"check_inbox\" to see unread messages and mentions\n\n## Communication\n- Post messages to channels with \"post_message\"\n- Send direct messages with \"send_dm\"\n- Reply to threads with \"reply_to_thread\"\n- React to messages with \"add_reaction\"\n\n## Fleet\n- Use \"query_nodes\" to find fleet nodes by capability or name\n- Use \"spawn\" with either a CLI or an AgentWorkforce persona to invoke the fleet spawn action on an eligible node\n- Persona spawns require a node exposing \"spawn:persona\" through @agentworkforce/local-surface's defineWorkforcePersonaSpawnNode\n\n## Best Practices\n- Check your inbox regularly for new messages and mentions\n- Use channels for topic-based discussions\n- Use threads for detailed discussions to keep channels organized\n- React with emoji to acknowledge messages\n- Keep messages concise and actionable";
 type RegisterAgentWithRebindArgs = {
     session: RegistrationSession;
     setSession: SessionSetter;

package/dist/cli/agent-relay-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-relay-mcp.d.ts","sourceRoot":"","sources":["../../src/cli/agent-relay-mcp.ts"],"names":[],"mappings":";AAgBA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA0DpE,OAAO,KAAK,EAEV,0BAA0B,EAC1B,SAAS,EAET,mBAAmB,EACnB,aAAa,EACb,aAAa,EAEd,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAEjE,eAAO,MAAM,uBAAuB,QACuC,CAAC;AAoU5E,eAAO,MAAM,4BAA4B,unEAgCF,CAAC;AAiBxC,KAAK,2BAA2B,GAAG;IACjC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,UAAU,EAAE,aAAa,CAAC;IAC1B,QAAQ,EAAE,MAAM,aAAa,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B,gFAAgF;IAChF,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAcF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASrE;AAqCD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAOjE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAMnF;AAsID,wBAAsB,uBAAuB,CAAC,EAC5C,OAAO,EACP,UAAU,EACV,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,qBAAqB,GACtB,EAAE,2BAA2B,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA+FhE;AA22BD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B,GAAG,SAAS,CAgOxF;AASD,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,0BAA0B,CAAC,CA0BrC;AAED,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAwChG;AAED,wBAAgB,cAAc,IAAI,0BAA0B,CAsC3D"}
+{"version":3,"file":"agent-relay-mcp.d.ts","sourceRoot":"","sources":["../../src/cli/agent-relay-mcp.ts"],"names":[],"mappings":";AAgBA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA+DpE,OAAO,KAAK,EAEV,0BAA0B,EAC1B,SAAS,EAGT,mBAAmB,EACnB,aAAa,EACb,aAAa,EAEd,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAEjE,eAAO,MAAM,uBAAuB,QACuC,CAAC;AAoU5E,eAAO,MAAM,4BAA4B,uxEAgCF,CAAC;AAiBxC,KAAK,2BAA2B,GAAG;IACjC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,UAAU,EAAE,aAAa,CAAC;IAC1B,QAAQ,EAAE,MAAM,aAAa,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B,gFAAgF;IAChF,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAcF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASrE;AAqCD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAOjE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAMnF;AAsID,wBAAsB,uBAAuB,CAAC,EAC5C,OAAO,EACP,UAAU,EACV,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,qBAAqB,GACtB,EAAE,2BAA2B,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA+FhE;AA22BD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B,GAAG,SAAS,CA0OxF;AAqMD,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,0BAA0B,CAAC,CA0BrC;AAED,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAyChG;AAED,wBAAgB,cAAc,IAAI,0BAA0B,CAkD3D"}

package/dist/cli/agent-relay-mcp.js

@@ -7,11 +7,14 @@ import { fileURLToPath } from 'node:url';
 import { isDeepStrictEqual } from 'node:util';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { ListToolsRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, InitializeRequestSchema, ListToolsRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { AgentRelay, RELAYCAST_SDK_VERSION, createAgentClient, createObserverToken, createRealtimeClient, createWorkspaceClient, isInvalidAgentTokenError, safeRelayErrorMessage, } from '@agent-relay/sdk';
 import { z } from 'zod';
 import { declaredWorkforceMetadata } from './lib/registration-metadata.js';
 import { isBundledBunEntrypointPath } from './lib/agent-relay-mcp-command.js';
+import { guardCredentialOrigin } from './lib/relaycast-origin-binding.js';
+import { isAgentAlreadyExists, takeOverAgent } from './lib/agent-takeover.js';
+import { pickAvailableName, sessionBaseName } from './lib/mcp-session-name.js';
 import { DEFAULT_AGENT_REGISTRATION_TIMEOUT_MS, withAgentRegistrationDeadline, withDeadline, } from './lib/agent-registration.js';
 import { attributableReleaseReason } from './lib/release-reason.js';
 import { sanitizedSpawnReceipt, spawnPlacementReceipt, } from './lib/spawn-lifecycle.js';
@@ -283,7 +286,7 @@ export const AGENT_RELAY_MCP_INSTRUCTIONS = `You are an AI agent in a collaborat
 1. The current project workspace is resumed automatically when one was selected before
 2. Call "create_workspace" only when you explicitly want to start a new workspace session
 3. If someone shared an existing workspace key with you, call "set_workspace_key"
-4. When a workspace key is available at startup, this MCP server auto-registers the session as RELAY_AGENT_NAME (or "orchestrator" by default). Otherwise call "register_agent" with your agent name to join the workspace
+4. When a workspace key is available at startup, this MCP server registers the session automatically: as RELAY_AGENT_NAME when it is set, otherwise as your tool plus the project folder (for example "claude-myproject", with a short suffix when another live session holds that name). Call "register_agent" to choose a different name, or to join when no workspace key was available
 5. Use "list_channels" to see available channels
 6. Use "join_channel" to join channels of interest
 7. Use "check_inbox" to see unread messages and mentions
@@ -1425,8 +1428,185 @@ export function createAgentRelayMcpServer(options) {
             return result;
         });
     }
+    if (options.autoRegister) {
+        installSessionAutoRegistration(mcpServer, handlers, options.autoRegister, {
+            getSession,
+            setSession,
+            getRelay,
+            agentType: options.agentType,
+            baseUrl: options.baseUrl,
+        });
+    }
     return mcpServer;
 }
+const RELAYCAST_HOSTED_ORIGIN = 'https://cast.agentrelay.com';
+/** Under Relaycast's 60s presence TTL, with room for one missed beat. */
+const SESSION_HEARTBEAT_MS = 25_000;
+/** How an auto-registered session marks itself offline when it ends. */
+const sessionDisconnectors = new WeakMap();
+/**
+ * Names of the sessions connected right now. The presence endpoint tracks
+ * live connections (a session that exits drops out within its heartbeat TTL,
+ * at once when it disconnects cleanly), where the roster's `online` filter
+ * keeps a registration for minutes after its process is gone.
+ */
+async function liveAgentNames(relay, workspaceKey, baseUrl, fetchImpl) {
+    const live = new Set();
+    try {
+        const response = await fetchImpl(new URL('/v1/agents/presence', baseUrl ?? RELAYCAST_HOSTED_ORIGIN), {
+            headers: { authorization: `Bearer ${workspaceKey}` },
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (response.ok) {
+            const body = (await response.json());
+            if (Array.isArray(body.data)) {
+                for (const entry of body.data) {
+                    if (entry?.status === 'online' && typeof entry.agent_name === 'string')
+                        live.add(entry.agent_name);
+                }
+                return live;
+            }
+        }
+    }
+    catch {
+        // Fall back to the roster below.
+    }
+    try {
+        for (const agent of await relay.agents.list({ status: 'online' })) {
+            const name = agent?.name;
+            if (typeof name === 'string')
+                live.add(name);
+        }
+    }
+    catch {
+        // Without either, the base name is still the best guess.
+    }
+    return live;
+}
+/**
+ * Register a session that has no configured name as soon as the MCP client
+ * says who it is. The name comes from `clientInfo.name` and the folder the
+ * tool started in (`claude-myproject`); a live session already holding it
+ * pushes this one to `claude-myproject-2`. Tool calls wait for the
+ * registration, so the first call never races it.
+ */
+function installSessionAutoRegistration(mcpServer, handlers, autoRegister, ctx) {
+    const fetchImpl = autoRegister.fetch ?? globalThis.fetch;
+    let pending = null;
+    const register = async (clientName) => {
+        const base = sessionBaseName({ clientName, hint: autoRegister.clientHint, cwd: autoRegister.cwd });
+        const workspaceKey = ctx.getSession().workspaceKey;
+        const live = await liveAgentNames(ctx.getRelay(), workspaceKey, ctx.baseUrl, fetchImpl);
+        const name = pickAvailableName(base, live);
+        let token;
+        let registeredName;
+        try {
+            const payload = await registerAgentWithRebind({
+                session: ctx.getSession(),
+                setSession: ctx.setSession,
+                getRelay: ctx.getRelay,
+                name,
+                type: ctx.agentType ?? 'agent',
+            });
+            token = typeof payload.token === 'string' ? payload.token : null;
+            registeredName = typeof payload.registered_name === 'string' ? payload.registered_name : null;
+        }
+        catch (error) {
+            // The name belongs to an earlier session of this tool in this folder
+            // that is no longer connected (a restart): resume that identity.
+            if (!isAgentAlreadyExists(error))
+                throw error;
+            const grant = await takeOverAgent({ workspaceKey, baseUrl: ctx.baseUrl, fetch: fetchImpl }, name, 'agent-relay mcp: resume the identity of an earlier session of this tool in this folder');
+            token = grant.token;
+            registeredName = grant.name;
+        }
+        if (token && registeredName) {
+            const agents = new Map(ctx.getSession().agents);
+            agents.set(registeredName, createRegisteredAgent(registeredName, token));
+            ctx.setSession({ agentToken: token, agentName: registeredName, agents });
+            startHeartbeat();
+        }
+    };
+    // Keep this session present while it runs, so the next session in the same
+    // folder sees the name is taken. Presence lapses about a minute after the
+    // last beat, which is how a crashed session frees its name.
+    let heartbeat;
+    const beat = () => {
+        const token = ctx.getSession().agentToken;
+        if (!token)
+            return;
+        void fetchImpl(new URL('/v1/agents/heartbeat', ctx.baseUrl ?? RELAYCAST_HOSTED_ORIGIN), {
+            method: 'POST',
+            headers: { authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(5_000),
+        }).catch(() => undefined);
+    };
+    const startHeartbeat = () => {
+        if (heartbeat)
+            return;
+        beat();
+        heartbeat = setInterval(beat, SESSION_HEARTBEAT_MS);
+        heartbeat.unref?.();
+    };
+    // Read clientInfo from the initialize request itself, and start right after
+    // answering it, so nothing depends on the order a client's messages land in.
+    const initialize = handlers.get('initialize');
+    if (initialize) {
+        mcpServer.server.setRequestHandler(InitializeRequestSchema, async (req, extra) => {
+            const result = await initialize(req, extra);
+            const session = ctx.getSession();
+            if (!pending && session.workspaceKey && !session.agentToken) {
+                pending = register(req.params.clientInfo?.name).catch((error) => {
+                    process.stderr.write(`[agent-relay] Could not register this session automatically (${safeRelayErrorMessage(error)}). ` +
+                        'Call "register_agent" to join the workspace.\n');
+                });
+            }
+            return result;
+        });
+    }
+    const callTool = handlers.get('tools/call');
+    if (callTool) {
+        mcpServer.server.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
+            if (pending)
+                await pending;
+            return (await callTool(req, extra));
+        });
+    }
+    // Leave cleanly so the next session in this folder can take the name at once.
+    sessionDisconnectors.set(mcpServer, async () => {
+        if (heartbeat)
+            clearInterval(heartbeat);
+        const token = ctx.getSession().agentToken;
+        if (!token)
+            return;
+        ctx.getSession().wsBridge?.stop();
+        await fetchImpl(new URL('/v1/agents/disconnect', ctx.baseUrl ?? RELAYCAST_HOSTED_ORIGIN), {
+            method: 'POST',
+            headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+            body: '{}',
+            signal: AbortSignal.timeout(2_000),
+        }).catch(() => undefined);
+    });
+}
+/**
+ * Mark an auto-registered session offline when its tool stops it: stdin
+ * closes (the MCP stdio shutdown) or the process is signalled.
+ */
+function disconnectSessionOnExit(mcpServer) {
+    const disconnect = sessionDisconnectors.get(mcpServer);
+    if (!disconnect)
+        return;
+    let closing = false;
+    const shutdown = () => {
+        if (closing)
+            return;
+        closing = true;
+        void Promise.race([disconnect(), new Promise((resolve) => setTimeout(resolve, 2_500))]).finally(() => process.exit(0));
+    };
+    process.stdin.once('end', shutdown);
+    for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'])
+        process.once(signal, shutdown);
+}
 /** Relaycast agent tokens are opaque `at_live_<hex>` literals. Anything else
  * (for example a RelayAuth JWT carried in RELAY_AGENT_TOKEN by `relay on start`)
  * is not a valid Relaycast credential and must be replaced. */
@@ -1493,6 +1673,7 @@ export async function startAgentRelayMcpStdio(options) {
     });
     const transport = new StdioServerTransport();
     await mcpServer.connect(transport);
+    disconnectSessionOnExit(mcpServer);
 }
 export function optionsFromEnv() {
     let workspaceKey = resolveEnv('RELAY_WORKSPACE_KEY') ??
@@ -1514,21 +1695,33 @@ export function optionsFromEnv() {
             // session can still be selected explicitly with set_workspace_key.
         }
     }
-    const agentName = resolveEnv('RELAY_AGENT_NAME') ??
-        resolveEnv('RELAY_CLAW_NAME') ??
-        (workspaceKey ? 'orchestrator' : undefined);
+    // With no configured name the session is named after the MCP client and the
+    // project folder once the client connects (see installSessionAutoRegistration),
+    // so two sessions never share one identity.
+    const agentName = resolveEnv('RELAY_AGENT_NAME') ?? resolveEnv('RELAY_CLAW_NAME');
+    // An agent token has no workspace identity encoded locally. Only reuse it
+    // when the workspace was selected alongside it through the environment;
+    // a persisted project/store fallback must register into that workspace
+    // instead of silently pairing it with a possibly stale ambient token.
+    const agentToken = resumedPersistedWorkspace ? undefined : resolveEnv('RELAY_AGENT_TOKEN');
+    // The same rule as the CLI: a credential bound to a self-hosted or local
+    // server (by `relay init`, `workspace join`, …) only ever goes back to it,
+    // so the MCP server never sends it to the hosted default.
+    const credential = workspaceKey ?? agentToken;
+    const baseUrl = credential
+        ? guardCredentialOrigin(credential, resolveEnv('RELAY_BASE_URL'))
+        : resolveEnv('RELAY_BASE_URL');
     return {
         workspaceKey,
-        baseUrl: resolveEnv('RELAY_BASE_URL'),
-        // An agent token has no workspace identity encoded locally. Only reuse it
-        // when the workspace was selected alongside it through the environment;
-        // a persisted project/store fallback must register into that workspace
-        // instead of silently pairing it with a possibly stale ambient token.
-        agentToken: resumedPersistedWorkspace ? undefined : resolveEnv('RELAY_AGENT_TOKEN'),
+        baseUrl,
+        agentToken,
         agentName,
         agentType: normalizeAgentType(resolveEnv('RELAY_AGENT_TYPE')),
         strictAgentName: envFlagEnabled(resolveEnv('RELAY_STRICT_AGENT_NAME')),
         skipBootstrap: envFlagEnabled(resolveEnv('RELAY_SKIP_BOOTSTRAP')),
+        autoRegister: workspaceKey && !agentName && !agentToken
+            ? { cwd: process.cwd(), clientHint: resolveEnv('AGENT_RELAY_CLIENT') }
+            : undefined,
     };
 }
 if (isEntrypoint()) {