@haywoodmarx/agent-pager 0.1.2 → 0.2.0

package/dist/src/launch/on-demand.js

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ProtocolError } from "../broker/protocol.js";
 import { resolveBunExecutable } from "./runtime.js";
-import { brokerLockHasCurrentIdentity, brokerLockIsLive, brokerLockPath, isCurrentBrokerServiceIdentity, processIsAlive, processStartedAt, readBrokerLock, startTimeStillMatches, readBrokerOwner, readBrokerOwnerPid, } from "./broker-lock.js";
+import { BROKER_EXIT_POLL_MS, BROKER_EXIT_TIMEOUT_MS, BrokerServiceExitTimeoutError, brokerLockHasCurrentIdentity, brokerLockIsLive, brokerLockIsReplaceable, brokerLockPath, isCurrentBrokerServiceIdentity, processIsAlive, processStartedAt, readBrokerLock, startTimeStillMatches, readBrokerOwner, SERVICE_BUILD_ID, } from "./broker-lock.js";
 /** Bounds one loopback endpoint probe, which either answers promptly or is treated as unreachable. */
 export const BROKER_PROBE_TIMEOUT_MS = 2_000;
 /**
@@ -99,17 +99,6 @@ export class BrokerServiceUnreachableError extends ProtocolError {
         this.name = "BrokerServiceUnreachableError";
     }
 }
-/** Named failure raised when a signalled broker service is still running once the exit budget is spent. */
-export class BrokerServiceExitTimeoutError extends ProtocolError {
-    /**
-     * Construct the failure reported when the owner ignores or outlasts its termination signal.
-     * @param pid - Process id of the owner that was signalled.
-     */
-    constructor(pid) {
-        super("validation_failed", `broker service pid ${String(pid)} was signalled to exit and is still running`);
-        this.name = "BrokerServiceExitTimeoutError";
-    }
-}
 /** Named failure raised when an upgrade encounters a live pre-identity service. */
 export class LegacyBrokerServiceError extends ProtocolError {
     /**
@@ -143,6 +132,9 @@ export function liveBrokerEndpoints(lock, isAlive, startedAt) {
 }
 /**
  * Adopt a running broker service or start one detached and wait for its endpoints.
+ *
+ * Never signals a running service itself. A foreign owner that {@link brokerLockIsReplaceable}
+ * accepts is left for the started service to stop while it takes the lock; any other is refused.
  * @param environment - Resolved configuration shared by the caller and service process.
  * @param overrides - Optional process and timing seams for isolated verification.
  * @returns - Live loopback endpoints owned by the singleton service process.
@@ -150,11 +142,10 @@ export function liveBrokerEndpoints(lock, isAlive, startedAt) {
 export async function ensureBrokerService(environment, overrides = {}) {
     const dependencies = { ...defaultDependencies(), ...overrides };
     const lockPath = brokerLockPath(environment.dbPath);
-    const ownerPid = readBrokerOwnerPid(lockPath);
     const candidate = readBrokerLock(lockPath);
-    if (ownerPid && dependencies.processIsAlive(ownerPid) && !brokerLockHasCurrentIdentity(candidate)) {
-        throw new LegacyBrokerServiceError(ownerPid);
-    }
+    const refused = refusedForeignOwner(lockPath, readBrokerOwner(lockPath), candidate, dependencies);
+    if (refused !== undefined)
+        throw new LegacyBrokerServiceError(refused);
     const existing = liveBrokerEndpoints(candidate, dependencies.processIsAlive, dependencies.processStartedAt);
     if (existing) {
         // The lock already proved this is the current build, so a probe that misses is a slow or
@@ -189,11 +180,12 @@ export async function ensureBrokerService(environment, overrides = {}) {
     let unanswered;
     try {
         while (dependencies.now() <= deadline) {
-            const loopOwnerPid = readBrokerOwnerPid(lockPath);
+            const loopOwner = readBrokerOwner(lockPath);
+            const loopOwnerPid = loopOwner?.pid;
             const loopCandidate = readBrokerLock(lockPath);
-            if (loopOwnerPid && dependencies.processIsAlive(loopOwnerPid) && !brokerLockHasCurrentIdentity(loopCandidate)) {
-                throw new LegacyBrokerServiceError(loopOwnerPid);
-            }
+            const loopRefused = refusedForeignOwner(lockPath, loopOwner, loopCandidate, dependencies);
+            if (loopRefused !== undefined)
+                throw new LegacyBrokerServiceError(loopRefused);
             const endpoints = liveBrokerEndpoints(loopCandidate, dependencies.processIsAlive, dependencies.processStartedAt);
             unanswered = undefined;
             if (endpoints) {
@@ -243,13 +235,6 @@ export async function ensureBrokerService(environment, overrides = {}) {
         child.releaseOutput();
     }
 }
-/**
- * Bounds waiting for a signalled owner to exit. It must exceed `SHUTDOWN_GRACE_MS` in `cli.ts`, the
- * time a stopping service allows its endpoints to close before it exits on its own.
- */
-const BROKER_EXIT_TIMEOUT_MS = 10_000;
-/** Spaces the liveness polls made while a signalled owner shuts down. */
-const BROKER_EXIT_POLL_MS = 50;
 /**
  * Stop the broker service that owns the configured database, whichever build started it.
  *
@@ -261,13 +246,10 @@ const BROKER_EXIT_POLL_MS = 50;
  */
 export async function stopBrokerService(environment, overrides = {}) {
     const dependencies = {
-        processIsAlive,
-        processStartedAt,
+        ...systemProcessDependencies(),
         signal: (pid, signal) => {
             process.kill(pid, signal);
         },
-        wait: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
-        now: Date.now,
         ...overrides,
     };
     const owner = readBrokerOwner(brokerLockPath(environment.dbPath));
@@ -376,8 +358,21 @@ function spawnCapturingStderr(command, args, environment) {
         },
     };
 }
+/**
+ * Build the operating-system process and timing seams shared by starting and stopping a service.
+ * @returns - Seams backed by the process table, timers and the wall clock.
+ */
+function systemProcessDependencies() {
+    return {
+        processIsAlive,
+        processStartedAt,
+        wait: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+        now: Date.now,
+    };
+}
 function defaultDependencies() {
     return {
+        ...systemProcessDependencies(),
         spawnService: spawnCapturingStderr,
         report: (message) => {
             process.stderr.write(message.endsWith("\n") ? message : `${message}\n`);
@@ -386,8 +381,7 @@ function defaultDependencies() {
             command: resolveBunExecutable(environment.processEnv),
             args: [fileURLToPath(new URL("./cli.js", import.meta.url)), "serve"],
         }),
-        processIsAlive,
-        processStartedAt,
+        buildId: SERVICE_BUILD_ID,
         endpointsReady: async ({ mcpUrl, snapshotUrl }) => {
             let health;
             let snapshot;
@@ -421,8 +415,6 @@ function defaultDependencies() {
                 return "unhealthy";
             }
         },
-        wait: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
-        now: Date.now,
     };
 }
 function adoptionRetryDelayMs(probes) {
@@ -433,3 +425,30 @@ function ownerStartTimeMatches(lock, startedAt) {
         return true;
     return startTimeStillMatches(lock.ownerStartedAt, startedAt(lock.pid));
 }
+/**
+ * Name the live foreign owner this caller must refuse.
+ *
+ * An owner counts as live only when its process started at the time its lock records.
+ * @param lockPath - Lock file both records were read from, read again before refusing.
+ * @param owner - Owner read from any structurally valid lock, current or legacy.
+ * @param lock - The same file read as a lock record this build accepts, when it is one.
+ * @param dependencies - Process seams reading liveness and start times.
+ * @returns - The owner's pid when it must be refused, or undefined when it is absent, stale, current,
+ * or replaceable.
+ */
+function refusedForeignOwner(lockPath, owner, lock, dependencies) {
+    if (owner === undefined || !dependencies.processIsAlive(owner.pid))
+        return undefined;
+    const startedAt = dependencies.processStartedAt(owner.pid);
+    if (owner.startedAt !== undefined && !startTimeStillMatches(owner.startedAt, startedAt))
+        return undefined;
+    if (brokerLockHasCurrentIdentity(lock))
+        return undefined;
+    if (lock?.pid === owner.pid && brokerLockIsReplaceable(lock, startedAt, dependencies.buildId))
+        return undefined;
+    // An owner that another starting service is replacing can exit, or remove its lock, between the
+    // reads above, leaving no start time or record to judge. It is a departing owner, not a foreign one.
+    if (!dependencies.processIsAlive(owner.pid) || readBrokerOwner(lockPath)?.pid !== owner.pid)
+        return undefined;
+    return owner.pid;
+}

package/dist/src/launch/runtime-composition.js

@@ -15,6 +15,7 @@ import { discoverImplementationRegistry, implementationId, } from "../implementa
 import { DirectTerminalProvider, ForegroundTerminalProvider, LaunchService, } from "./launch.js";
 import { spawnForegroundProcess } from "./terminal.js";
 import { systemWorkspaceBranch } from "./workspace-branch.js";
+import { systemWorkspaceRoot } from "./workspace-root.js";
 import { initializePagerStore } from "../configuration.js";
 import { isPlainObject } from "../shared/guards.js";
 export { readRuntimeEnvironment } from "./environment.js";
@@ -33,6 +34,7 @@ export function createBroker(environment) {
     return new Broker(environment.dbPath, {
         now: Date.now,
         workspaceBranch: systemWorkspaceBranch,
+        workspaceRoot: systemWorkspaceRoot,
         report: (message) => {
             process.stderr.write(`${message}\n`);
         },

package/dist/src/launch/runtime.js

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { accessSync, constants, realpathSync } from "node:fs";
 import { delimiter, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { compareNumericVersions, parseNumericVersion } from "../shared/versions.js";
 import { readRuntimeEnvironment } from "./environment.js";
 /** Bounds one probe of an external runtime executable. */
 const RUNTIME_PROBE_TIMEOUT_MS = 10_000;
@@ -32,22 +33,11 @@ export class BunRuntimeError extends Error {
  * @returns - True when the version is at or above the supported floor.
  */
 export function satisfiesBunVersionFloor(version) {
-    const candidate = numericVersion(version);
-    const minimum = numericVersion(MINIMUM_BUN_VERSION);
+    const candidate = parseNumericVersion(version, "prefix");
+    const minimum = parseNumericVersion(MINIMUM_BUN_VERSION, "prefix");
     if (!candidate || !minimum)
         return false;
-    for (let index = 0; index < minimum.length; index += 1) {
-        const difference = (candidate[index] ?? 0) - (minimum[index] ?? 0);
-        if (difference !== 0)
-            return difference > 0;
-    }
-    return true;
-}
-function numericVersion(version) {
-    const match = /^(\d+)\.(\d+)\.(\d+)/u.exec(version);
-    if (!match)
-        return undefined;
-    return [Number(match[1]), Number(match[2]), Number(match[3])];
+    return compareNumericVersions(candidate, minimum) >= 0;
 }
 /**
  * Fail fast when the current process is not a supported Bun runtime.

package/dist/src/launch/service.d.ts

@@ -10,6 +10,7 @@ import { type OperatorTransportSchedulerPort } from "../operator/transport.js";
 import { type OperatorUpdateSourcePort } from "../operator/updates.js";
 import { type BrokerLockOwner } from "./broker-lock.js";
 export { systemWorkspaceBranch } from "./workspace-branch.js";
+export { systemWorkspaceRoot } from "./workspace-root.js";
 /** Schedules the service's timers, none of which may keep the process alive. */
 export interface BrokerServiceSchedulerPort extends OperatorTransportSchedulerPort {
     /**

package/dist/src/launch/service.js

@@ -9,13 +9,16 @@ import { startMcpServer } from "../messaging/mcp.js";
 import { NotificationHub, NotificationScheduler } from "../messaging/notifications.js";
 import { PushDeliveryService } from "../messaging/push-delivery.js";
 import { OperatorCommandService } from "../operator/commands.js";
+import { rememberRepositoryInspections } from "../operator/repository.js";
 import { createSystemRepositoryProjectionDependencies } from "../operator/repository-system.js";
 import { issueOperatorClientId, startOperatorTransport, } from "../operator/transport.js";
 import { SqliteOperatorEventStore } from "../operator/update-store.js";
 import { OperatorUpdateService } from "../operator/updates.js";
 import { currentBrokerServiceIdentity } from "./broker-lock.js";
 import { systemWorkspaceBranch } from "./workspace-branch.js";
+import { systemWorkspaceRoot } from "./workspace-root.js";
 export { systemWorkspaceBranch } from "./workspace-branch.js";
+export { systemWorkspaceRoot } from "./workspace-root.js";
 /** Tables whose rows can move the moment a sweep next has work to do. */
 const SWEEP_DEADLINE_TABLES = ["agents", "sessions", "messages", "wakes"];
 /** Sets how often the watchdog checks that the database this service serves still exists. */
@@ -26,6 +29,10 @@ const OPERATOR_HEARTBEAT_INTERVAL_MS = 5_000;
 const OPERATOR_LIVENESS_TIMEOUT_MS = 15_000;
 /** Sets the entropy of an operator control id, in bytes. */
 const CONTROL_ID_BYTES = 12;
+/** Bounds how long one directory's Git inspection stands in for a fresh one in operator projections. */
+const REPOSITORY_INSPECTION_TTL_MS = 30_000;
+/** Bounds each Git command the operator projection runs; one that runs longer is treated as having failed. */
+const REPOSITORY_DISCOVERY_TIMEOUT_MS = 2_000;
 /** Delays the retry after a sweep failed, so a persistent failure cannot spin on a due deadline. */
 const SWEEP_FAILURE_RETRY_MS = 1_000;
 /** Reports that a configured loopback endpoint could not take its port. */
@@ -137,6 +144,7 @@ export class BrokerService {
             this.#broker = this.#options.openBroker(this.#databasePath, {
                 now,
                 workspaceBranch: systemWorkspaceBranch,
+                workspaceRoot: systemWorkspaceRoot,
                 report: this.#report,
                 ...(config
                     ? {
@@ -194,6 +202,13 @@ export class BrokerService {
                     forgetDeliveryAddress: (agentId) => {
                         pushDelivery.forget(agentId);
                     },
+                    notifySessionClaimed: (claim) => {
+                        notifications.publishSessionClaimed(claim.agentId, {
+                            claimedAddress: claim.address,
+                            claimantAddress: claim.retiredAddress,
+                            claimantId: claim.retiredId,
+                        });
+                    },
                 },
                 host: bindHost,
                 healthIdentity: currentBrokerServiceIdentity(),
@@ -423,12 +438,19 @@ export class BrokerService {
             const descriptors = new Map();
             for (const descriptor of this.#implementations.descriptors())
                 descriptors.set(descriptor.id, descriptor);
+            const repositoryDiscovery = createSystemRepositoryProjectionDependencies({
+                gitTimeoutMs: REPOSITORY_DISCOVERY_TIMEOUT_MS,
+            });
             const operatorUpdates = new OperatorUpdateService({
                 source: broker,
                 store,
                 now: this.#now,
                 projection: {
-                    ...createSystemRepositoryProjectionDependencies(),
+                    fileSystem: repositoryDiscovery.fileSystem,
+                    git: rememberRepositoryInspections(repositoryDiscovery.git, {
+                        now: this.#now,
+                        ttlMs: REPOSITORY_INSPECTION_TTL_MS,
+                    }),
                     implementations: {
                         find: (implementationId) => {
                             const descriptor = descriptors.get(implementationId);

package/dist/src/launch/workspace-branch.d.ts

@@ -1,10 +1,10 @@
 /**
- * Report the branch checked out at a workspace path.
+ * Report the branch checked out at an agent's working directory.
  *
  * A standalone module so a caller composing only the broker itself avoids pulling in the whole
  * `BrokerService` module graph for one `git` lookup.
- * @param path - Absolute workspace path to inspect.
+ * @param path - Absolute working directory to inspect.
  * @returns - Current branch name, or null when the path is not a repository, is detached, or the
- * lookup did not answer within {@link WORKSPACE_BRANCH_TIMEOUT_MS}.
+ * lookup failed or did not answer within {@link WORKSPACE_BRANCH_TIMEOUT_MS}.
  */
 export declare function systemWorkspaceBranch(path: string): string | null;

package/dist/src/launch/workspace-branch.js

@@ -1,27 +1,19 @@
-import { execFileSync } from "node:child_process";
-/**
- * Bounds the branch lookup, which runs a subprocess against a path this process does not control.
- *
- * The branch is a label on a workspace row; nothing waits on it, so a slow answer is discarded
- * rather than waited for.
- */
+import { runGit } from "../operator/repository-system.js";
+/** Bounds the branch lookup; a lookup that runs longer is treated as having failed. */
 const WORKSPACE_BRANCH_TIMEOUT_MS = 2_000;
 /**
- * Report the branch checked out at a workspace path.
+ * Report the branch checked out at an agent's working directory.
  *
  * A standalone module so a caller composing only the broker itself avoids pulling in the whole
  * `BrokerService` module graph for one `git` lookup.
- * @param path - Absolute workspace path to inspect.
+ * @param path - Absolute working directory to inspect.
  * @returns - Current branch name, or null when the path is not a repository, is detached, or the
- * lookup did not answer within {@link WORKSPACE_BRANCH_TIMEOUT_MS}.
+ * lookup failed or did not answer within {@link WORKSPACE_BRANCH_TIMEOUT_MS}.
  */
 export function systemWorkspaceBranch(path) {
     try {
-        return (execFileSync("git", ["-C", path, "branch", "--show-current"], {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-            timeout: WORKSPACE_BRANCH_TIMEOUT_MS,
-        }).trim() || null);
+        const result = runGit("git", ["-C", path, "branch", "--show-current"], WORKSPACE_BRANCH_TIMEOUT_MS);
+        return result.kind === "ok" ? result.stdout.trim() || null : null;
     }
     catch {
         return null;

package/dist/src/launch/workspace-root.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Report the directory that names the workspace a working directory belongs to.
+ *
+ * Inside a Git repository that is one directory for every worktree of the repository, so the main
+ * worktree, every linked worktree, and every subdirectory of any of them share one workspace: the
+ * directory holding the repository's `.git` or `.bare` directory.
+ * @param path - Absolute working directory to inspect.
+ * @returns - Canonical directory naming the repository containing the path, or the path itself when
+ * it is not inside a repository, its Git directory is not named `.git` or `.bare`, or it does not exist.
+ * @throws {RepositoryDiscoveryError} When Git cannot answer: it is missing, failed, or did not answer
+ * within {@link WORKSPACE_ROOT_TIMEOUT_MS}.
+ */
+export declare function systemWorkspaceRoot(path: string): string;

package/dist/src/launch/workspace-root.js

@@ -0,0 +1,27 @@
+import { existsSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { discoverRepositoryCommonDirectory } from "../operator/repository-system.js";
+/** Bounds the repository lookup; a lookup that runs longer is treated as having failed. */
+const WORKSPACE_ROOT_TIMEOUT_MS = 2_000;
+/** Git directory names whose containing directory is the checkout or project they belong to. */
+const REPOSITORY_DIRECTORY_NAMES = new Set([".git", ".bare"]);
+/**
+ * Report the directory that names the workspace a working directory belongs to.
+ *
+ * Inside a Git repository that is one directory for every worktree of the repository, so the main
+ * worktree, every linked worktree, and every subdirectory of any of them share one workspace: the
+ * directory holding the repository's `.git` or `.bare` directory.
+ * @param path - Absolute working directory to inspect.
+ * @returns - Canonical directory naming the repository containing the path, or the path itself when
+ * it is not inside a repository, its Git directory is not named `.git` or `.bare`, or it does not exist.
+ * @throws {RepositoryDiscoveryError} When Git cannot answer: it is missing, failed, or did not answer
+ * within {@link WORKSPACE_ROOT_TIMEOUT_MS}.
+ */
+export function systemWorkspaceRoot(path) {
+    if (!existsSync(path))
+        return path;
+    const commonDirectory = discoverRepositoryCommonDirectory(path, { gitTimeoutMs: WORKSPACE_ROOT_TIMEOUT_MS });
+    if (commonDirectory === null)
+        return path;
+    return REPOSITORY_DIRECTORY_NAMES.has(basename(commonDirectory)) ? dirname(commonDirectory) : path;
+}

package/dist/src/messaging/delivery-client.d.ts

@@ -90,6 +90,23 @@ export declare class BrokerDeliveryClient {
      */
     call(tool: string, args: Record<string, unknown>): Promise<unknown>;
 }
+/** A failure the broker answered with its own error code. */
+export declare class BrokerRefusal extends Error {
+    /** The broker's error code, such as `expired`. */
+    readonly code: string;
+    /**
+     * Construct a refusal carrying the broker's message and code.
+     * @param message - The broker's own explanation.
+     * @param code - The broker's error code for the refusal.
+     */
+    constructor(message: string, code: string);
+}
+/**
+ * Report whether a failure is the broker refusing the session presented as expired.
+ * @param error - Rejection from a broker request.
+ * @returns - True only for a refusal the broker coded `expired`.
+ */
+export declare function isExpiredRefusal(error: unknown): boolean;
 /**
  * Build one compatibility-path tool call, without session headers.
  * @param tool - Tool the broker dispatches on; connector-only tools are accepted on this path.

package/dist/src/messaging/delivery-client.js

@@ -118,6 +118,29 @@ export class BrokerDeliveryClient {
         return compatibilityPayload(response, `Broker ${tool}`);
     }
 }
+/** A failure the broker answered with its own error code. */
+export class BrokerRefusal extends Error {
+    /** The broker's error code, such as `expired`. */
+    code;
+    /**
+     * Construct a refusal carrying the broker's message and code.
+     * @param message - The broker's own explanation.
+     * @param code - The broker's error code for the refusal.
+     */
+    constructor(message, code) {
+        super(message);
+        this.name = "BrokerRefusal";
+        this.code = code;
+    }
+}
+/**
+ * Report whether a failure is the broker refusing the session presented as expired.
+ * @param error - Rejection from a broker request.
+ * @returns - True only for a refusal the broker coded `expired`.
+ */
+export function isExpiredRefusal(error) {
+    return error instanceof BrokerRefusal && error.code === "expired";
+}
 /**
  * Build one compatibility-path tool call, without session headers.
  * @param tool - Tool the broker dispatches on; connector-only tools are accepted on this path.
@@ -227,7 +250,14 @@ async function parseEnvelopeBody(response, operation) {
 function envelopeFailure(response, payload, operation) {
     const error = asRecord(payload?.error);
     const message = typeof error?.message === "string" ? error.message : `${operation} failed (${String(response.status)})`;
-    return new Error(message);
+    const code = refusalCode(error);
+    return code === undefined ? new Error(message) : new BrokerRefusal(message, code);
+}
+function refusalCode(error) {
+    const rpcData = asRecord(error?.data);
+    if (typeof rpcData?.code === "string")
+        return rpcData.code;
+    return typeof error?.code === "string" ? error.code : undefined;
 }
 /**
  * Accept an object carrying only permitted fields, rejecting anything additional.

package/dist/src/messaging/identity-statement.d.ts

@@ -0,0 +1,7 @@
+import type { AgentIdentity } from "../broker/broker.js";
+/**
+ * State the identity a session acts as, in the words the broker uses for it.
+ * @param identity - Identity as `whoami` reports it.
+ * @returns - Text naming the alias, workspace, address and agent id, and nothing else.
+ */
+export declare function agentIdentityStatement(identity: AgentIdentity): string;

package/dist/src/messaging/identity-statement.js

@@ -0,0 +1,8 @@
+/**
+ * State the identity a session acts as, in the words the broker uses for it.
+ * @param identity - Identity as `whoami` reports it.
+ * @returns - Text naming the alias, workspace, address and agent id, and nothing else.
+ */
+export function agentIdentityStatement(identity) {
+    return `You are ${identity.alias} in workspace ${identity.workspace}, reachable from any workspace at ${identity.address}. Your agent id is ${identity.id}.`;
+}

package/dist/src/messaging/mcp.d.ts

@@ -1,4 +1,4 @@
-import type { Broker } from "../broker/broker.js";
+import type { AliasClaim, Broker } from "../broker/broker.js";
 import { type AgentId } from "../broker/protocol.js";
 import type { NotificationScheduler } from "./notifications.js";
 /** Supplies notification and push-address operations to the MCP transport. */
@@ -17,11 +17,17 @@ export type McpNotificationPort = {
      * @param agentId - Identity whose address is no longer answered.
      */
     forgetDeliveryAddress?: (agentId: AgentId) => void;
+    /**
+     * Tells the process displaced from an identity that another process took the identity over,
+     * at the address that process registered for it. Called after the takeover committed.
+     * @param claim - The identity taken and what the claiming process gave up.
+     */
+    notifySessionClaimed?: (claim: AliasClaim) => void;
 };
 /** Names the request header an attached session presents its host delivery address in. */
 export declare const DELIVERY_ADDRESS_HEADER = "x-pager-delivery-address";
 /** Broker operations the MCP server reaches. */
-export type McpBrokerPort = Pick<Broker, "ack" | "adoptSessionKey" | "agentIdentity" | "attach" | "broadcast" | "fetch" | "listAgents" | "listTeamMembers" | "registerAgentWithoutReservation" | "releaseAttachments" | "reserveAttachment" | "resolveSession" | "resumeSession" | "send" | "sessionLeaseTtlMs" | "status" | "updateAgentAlias">;
+export type McpBrokerPort = Pick<Broker, "ack" | "adoptSessionKey" | "agentIdentity" | "attach" | "broadcast" | "fetch" | "listAgents" | "listTeamMembers" | "registerAgentWithoutReservation" | "releaseAttachments" | "relocateAgent" | "reserveAttachment" | "resolveSession" | "resumeSession" | "send" | "sessionLeaseTtlMs" | "status">;
 /** Represents a running MCP server and the operation that stops it. */
 export type McpServerHandle = {
     /** Locates the MCP endpoint the server is bound to. */

package/dist/src/messaging/mcp.js

@@ -4,6 +4,7 @@ import { LOOPBACK_HOST } from "../configuration-defaults.js";
 import { closeServer, listenServer, urlHost, writeJson } from "../shared/http.js";
 import { isPlainObject } from "../shared/guards.js";
 import { assertProtocolVersion, FETCH_LIMIT_DEFAULT, FETCH_LIMIT_MAX, normalizeMessageSubject, normalizeMessageType, ATTACH_HEADER, ProtocolError, validateImplementationId, validateSessionKey, } from "../broker/protocol.js";
+import { agentIdentityStatement } from "./identity-statement.js";
 import { MCP_TOOLS } from "./tools.js";
 import { PAGER_VERSION } from "../version.js";
 /**
@@ -234,7 +235,19 @@ function runTool(context, attached, tool, args, surface) {
         case "update_agent_alias":
             if (typeof args.alias !== "string")
                 throw new ProtocolError("validation_failed", "Agent alias is required");
-            return broker.updateAgentAlias(attached.agentId, args.alias);
+            return relocate(context, attached.agentId, { alias: args.alias, force: forceFlag(args.force) });
+        case "move_to_workspace":
+            if (typeof args.workspace !== "string" || args.workspace === "") {
+                throw new ProtocolError("validation_failed", "Target workspace is required");
+            }
+            if (args.alias !== undefined && typeof args.alias !== "string") {
+                throw new ProtocolError("validation_failed", "Agent alias must be a string");
+            }
+            return relocate(context, attached.agentId, {
+                workspace: args.workspace,
+                ...(typeof args.alias === "string" ? { alias: args.alias } : {}),
+                force: forceFlag(args.force),
+            });
         case "adopt_session_key": {
             return broker.adoptSessionKey(attached.agentId, validateSessionKey(args.sessionKey));
         }
@@ -283,6 +296,32 @@ function runTool(context, attached, tool, args, surface) {
             throw new ProtocolError("validation_failed", "Unknown tool");
     }
 }
+/**
+ * Move or rename the caller, and tell a displaced process once the takeover is durable.
+ *
+ * The claiming process's own address is still registered under the identity it gave up; its next
+ * request registers it under the identity it now acts as.
+ * @param context - Server context carrying the broker and the optional notification port.
+ * @param agentId - Identity the caller authenticated as.
+ * @param request - Target workspace, alias, and whether to take the alias over.
+ * @returns - The identity the caller now acts as, as `whoami` reports it.
+ */
+function relocate(context, agentId, request) {
+    const { broker, notifications } = context;
+    const relocation = broker.relocateAgent(agentId, request);
+    if (relocation.claim) {
+        notifications?.notifySessionClaimed?.(relocation.claim);
+        notifications?.forgetDeliveryAddress?.(relocation.claim.retiredId);
+    }
+    return relocation.identity;
+}
+function forceFlag(value) {
+    if (value === undefined)
+        return false;
+    if (typeof value !== "boolean")
+        throw new ProtocolError("validation_failed", "force must be a boolean");
+    return value;
+}
 /**
  * Report whether a decoded body claims to be a JSON-RPC request.
  *
@@ -302,6 +341,17 @@ function isMcpRequest(value) {
 function namedParameter(params, name) {
     return isPlainObject(params) ? params[name] : undefined;
 }
+/**
+ * Answer one JSON-RPC request on the broker's MCP endpoint.
+ *
+ * An `initialize` request attaches a new session, or resumes the one it presents, and its result's
+ * `instructions` is {@link agentIdentityStatement} for the identity the session now acts as, the
+ * same text for an attach and a resume.
+ * @param context - Broker, notification and diagnostics collaborators the server runs with.
+ * @param request - HTTP request carrying the JSON-RPC body and the session headers.
+ * @param response - HTTP response the result or error is written to.
+ * @param rpc - Decoded JSON-RPC request.
+ */
 function handleMcpRequest(context, request, response, rpc) {
     const { broker } = context;
     if (rpc.method === "initialize") {
@@ -324,8 +374,10 @@ function handleMcpRequest(context, request, response, rpc) {
         // The session above is already established by the time this can throw, so an internal failure here
         // must still carry its headers — otherwise a client that just attached or transparently resumed is
         // left presenting credentials the server has already superseded.
+        let instructions;
         try {
             registerDeliveryAddress(context, request, attached.agentId);
+            instructions = agentIdentityStatement(broker.agentIdentity(attached.agentId));
         }
         catch (error) {
             if (error instanceof ProtocolError) {
@@ -340,6 +392,7 @@ function handleMcpRequest(context, request, response, rpc) {
             protocolVersion: typeof declared === "string" ? declared : DEFAULT_MCP_PROTOCOL_VERSION,
             capabilities: { tools: {} },
             serverInfo: { name: "pager", version: PAGER_VERSION },
+            instructions,
         }, headers);
         return;
     }