@haywoodmarx/agent-pager 0.1.3 → 0.2.1

package/README.md

@@ -52,9 +52,9 @@ pager status
 pager <implementation-id> [--session-name <name>] -- <implementation-arguments>
 ```
 
-The bare implementation form starts or adopts the loopback service automatically. A command already running in a hosted terminal keeps the implementation in that terminal with inherited stdio. Otherwise, it prefers an available discovered terminal provider and falls back to inherited stdio; implementation exit status is propagated to the invoking shell. A session name is also the agent's routable alias and is unique within the working directory across implementations. Supplying it again rejoins that broker identity once its holder's harness has shut down gracefully and its connector has said so, its attachment heartbeat lease has lapsed, or the holder was archived; while the holder is attached, the launch exits non-zero naming the holder and the harness does not start. Omitting it creates an ephemeral identity that is reaped once its attachment heartbeat lease lapses, or, when a conversation key makes it resumable, once it has been detached for the resumable retention window, shortened to the unused window while it has never sent a message or received one addressed to it alone. An ephemeral identity that never attached is reaped once its attach reservations have lapsed. Archiving an identity from the operator TUI ends its attachments and hides it, while messages sent to it wait; attaching again un-archives it. A named identity detached for the named archive window is archived too, and comes back when its conversation attaches or its holder resumes its attachment. Otherwise an archived identity, ephemeral or named, is reaped once the archive retention window has passed since its first archive, and reaping dead-letters its unsettled mail. The first sweep after an upgrade reaps every identity already archived for longer than that window.
+The bare implementation form starts or adopts the loopback service automatically. A command already running in a hosted terminal keeps the implementation in that terminal with inherited stdio. Otherwise, it prefers an available discovered terminal provider and falls back to inherited stdio; implementation exit status is propagated to the invoking shell. A session name is also the agent's routable alias and is unique within its workspace across implementations. A session's workspace is the Git repository its working directory belongs to, so the main worktree, every linked worktree, and every subdirectory of them share one; a directory outside any repository is a workspace of its own. Agents in one workspace address each other by bare alias. Supplying it again rejoins that broker identity once its holder's harness has shut down gracefully and its connector has said so, its attachment heartbeat lease has lapsed, or the holder was archived; while the holder is attached, the launch exits non-zero naming the holder and the harness does not start. Omitting it creates an ephemeral identity that is reaped once its attachment heartbeat lease lapses, or, when a conversation key makes it resumable, once it has been detached for the resumable retention window, shortened to the unused window while it has never sent a message or received one addressed to it alone. An ephemeral identity that never attached is reaped once its attach reservations have lapsed. Archiving an identity from the operator TUI ends its attachments and hides it, while messages sent to it wait; attaching again un-archives it. Purging an identity from the operator TUI, on its own or with others in its workspace's archive section, deletes it and ends any session still attached to it; a message it exchanged with an identity that remains stays in that identity's history, and any still waiting in its inbox is dead-lettered. A named identity detached for the named archive window is archived too, and comes back when its conversation attaches or its holder resumes its attachment. Otherwise an archived identity, ephemeral or named, is reaped once the archive retention window has passed since its first archive, and reaping dead-letters its unsettled mail. The first sweep after an upgrade reaps every identity already archived for longer than that window.
 
-The authenticated `whoami` MCP tool returns the agent id, current alias, and previous aliases. `update_agent_alias` atomically replaces the current alias and durable session name; assigning one to an unnamed agent makes that identity durable. Prior names remain reserved. Sending to one is rejected with `recipient_alias_changed` and the current alias rather than silently redirecting the message.
+The authenticated `whoami` MCP tool returns the caller's identity and the address that reaches it from any workspace. [`src/messaging/tools.ts`](src/messaging/tools.ts) describes what each tool returns. `update_agent_alias` atomically replaces the current alias and durable session name; assigning one to an unnamed agent makes that identity durable. `move_to_workspace` moves an agent into another workspace, keeping its identity and inbox. Prior names and addresses remain reserved until the identity is purged. Sending to one is rejected with `recipient_alias_changed` and the current address rather than silently redirecting the message. An alias another agent holds is taken over only with `force`, which hands that agent's identity to the caller, tells its session and ends it, so that session's next call runs as a fresh unnamed agent.
 
 The package also exposes its Pi integration as a Pi package. `pi install npm:@haywoodmarx/agent-pager` enables directly started Pi sessions to discover or start the broker and register themselves; `pager pi -- <pi-arguments>` loads the same extension explicitly for a wrapper-managed session.
 
@@ -64,8 +64,8 @@ Pager does not change a harness's permission settings. A session that has to wai
 
 The broker starts on demand: `pager` with no command, and every harness connecting over MCP, adopts the running broker or starts one. `pager status` reports whether the broker is running, its pid, its MCP endpoint, the database it serves, the installed pager version, and the version of the running broker. `pager exit` stops it, and `pager restart` stops it and starts a fresh one. `pager serve` runs the broker in the foreground.
 
-Callers adopt a running service only when its database-adjacent lock and `/health` agree on the service identity; concurrent starters race for that lock and every caller adopts the winner. The adoption rules are declared in [`src/launch/on-demand.ts`](src/launch/on-demand.ts) and [`src/launch/broker-lock.ts`](src/launch/broker-lock.ts).
+Callers adopt a running service only when its database-adjacent lock and `/health` agree on the service identity; concurrent starters race for that lock and every caller adopts the winner. The adoption rules, and which running broker from an older release a starting one replaces, are declared in [`src/launch/on-demand.ts`](src/launch/on-demand.ts) and [`src/launch/broker-lock.ts`](src/launch/broker-lock.ts).
 
-Back up the database before an upgrade if its current state matters. Schema changes are destructive: a database whose schema marker or required columns do not match the running build is recreated, discarding every identity and message it held, and the recreation is reported with the counts it deleted on the standard error of the command that started the service, whether that is `pager serve` or an on-demand start. The marker is part of the service adoption identity, so a build that would recreate the database cannot displace a running service that owns it. Deleting the database and starting the service also creates an empty broker.
+Back up the database before an upgrade if its current state matters. Schema changes are destructive: a database whose schema marker or required columns do not match the running build is recreated, discarding every identity and message it held, and the recreation is reported with the counts it deleted on the standard error of the command that started the service, whether that is `pager serve` or an on-demand start. The marker is part of the service adoption identity, so no build adopts a running service whose schema differs from its own, and a newer release that replaces an older one recreates the database when their schemas differ. Deleting the database and starting the service also creates an empty broker.
 
 Per-implementation installation and conformance documentation is indexed under [`docs/implementations/acceptance/`](docs/implementations/acceptance/README.md).

package/dist/src/broker/address.d.ts

@@ -7,6 +7,13 @@ export declare function parseAgentAddress(value: string): {
     sessionName: string;
     workspace: string | null;
 };
+/**
+ * Join an alias and a workspace name into the address that reaches the agent from any workspace.
+ * @param alias - Session name with or without its leading at-sign.
+ * @param workspace - Workspace name as {@link uniquePathNames} assigns it.
+ * @returns - Address in the form {@link parseAgentAddress} reads.
+ */
+export declare function formatAgentAddress(alias: string, workspace: string): string;
 /**
  * Conform a caller-supplied workspace name to the form {@link uniquePathNames} names a workspace by.
  * @param value - Untrusted workspace name, as it appears after the at-sign of an address.

package/dist/src/broker/address.js

@@ -14,6 +14,15 @@ export function parseAgentAddress(value) {
     const workspace = parseWorkspaceName(withoutPrefix.slice(separator + 1));
     return { sessionName: validateRegistrationSessionName(withoutPrefix.slice(0, separator)), workspace };
 }
+/**
+ * Join an alias and a workspace name into the address that reaches the agent from any workspace.
+ * @param alias - Session name with or without its leading at-sign.
+ * @param workspace - Workspace name as {@link uniquePathNames} assigns it.
+ * @returns - Address in the form {@link parseAgentAddress} reads.
+ */
+export function formatAgentAddress(alias, workspace) {
+    return `${normalizeAlias(alias)}@${workspace}`;
+}
 /**
  * Conform a caller-supplied workspace name to the form {@link uniquePathNames} names a workspace by.
  * @param value - Untrusted workspace name, as it appears after the at-sign of an address.

package/dist/src/broker/broker.d.ts

@@ -84,6 +84,52 @@ export type BroadcastResult = {
         message: string;
     }[];
 };
+/** Identity of one agent, as reported to that agent. */
+export type AgentIdentity = {
+    /** Stable broker identity. */
+    id: AgentId;
+    /** Current alias, with its leading at-sign. */
+    alias: string;
+    /** Name of the workspace the alias is unique within, as an address carries it. */
+    workspace: string;
+    /** Address that reaches the agent from any workspace. */
+    address: string;
+    /** Aliases the agent held before its current one. */
+    previousAliases: string[];
+};
+/** Options for {@link Broker.relocateAgent}. */
+export type AgentRelocationRequest = {
+    /**
+     * Workspace to move into: a name as {@link Broker.listAgents} reports it, or an absolute directory,
+     * which names the workspace a registration from it would join. Absent keeps the current workspace.
+     */
+    workspace?: string;
+    /** Alias to hold in the target workspace, with an optional leading at-sign. Absent keeps the current alias. */
+    alias?: string;
+    /**
+     * Whether to take over the identity that holds or reserves the alias in the target workspace, rather
+     * than fail with `alias_conflict`.
+     */
+    force?: boolean;
+};
+/** Records the takeover a forced relocation performed. */
+export type AliasClaim = {
+    /** Address taken, as it reached the identity's previous holder. */
+    address: string;
+    /** Identity taken over, which the caller now acts as. */
+    agentId: AgentId;
+    /** Identity the caller gave up; a send to its address is redirected to `agentId`. */
+    retiredId: AgentId;
+    /** Address the caller held before the claim. */
+    retiredAddress: string;
+};
+/** Outcome of {@link Broker.relocateAgent}. */
+export type AgentRelocation = {
+    /** Identity the caller now acts as, as reported to it. */
+    identity: AgentIdentity;
+    /** Takeover performed, or null when the caller kept its own identity. */
+    claim: AliasClaim | null;
+};
 /** Options for {@link Broker.fetch}. */
 export type BrokerFetchRequest = {
     /** Agent whose queue is fetched from. */
@@ -103,13 +149,19 @@ export type BrokerOptions = {
      */
     now: () => number;
     /**
-     * Reports the branch checked out at a workspace path, or null when it is not a repository.
+     * Reports the branch checked out at an agent's working directory, or null when it is not a repository.
      *
-     * A port rather than a direct call because the real one is a `git` subprocess: it must run before
-     * the write transaction opens, and a test must be able to assert the persisted row without
-     * shelling out to whatever branch the developer's own checkout happens to be on.
+     * Called before a registration's write transaction opens, so it may block on a subprocess.
      */
     workspaceBranch: (path: string) => string | null;
+    /**
+     * Reports the directory naming the workspace an agent's working directory belongs to: the same
+     * directory for every working directory whose agents address each other by bare alias.
+     *
+     * Called before a registration's write transaction opens, so it may block on a subprocess. A
+     * throw is reported through `report`, and the working directory names its own workspace.
+     */
+    workspaceRoot: (workingDirectory: string) => string;
     /** Sets the lifetime of an unacknowledged message claim. */
     visibilityTimeoutMs?: number;
     /** Sets the delay before the first redelivery wake for an inbox whose messages went unclaimed. */
@@ -187,7 +239,7 @@ export declare class Broker {
     /**
      * Opens a durable broker database with the supplied timing and routing policies.
      * @param path - SQLite database location, or memory sentinel, for durable state.
-     * @param options - Clock, workspace-branch lookup, and diagnostics sink are required; see {@link BrokerOptions} for its optional fields.
+     * @param options - Clock, workspace-branch and workspace-root lookups, and diagnostics sink are required; see {@link BrokerOptions} for its optional fields.
      */
     constructor(path: string, options: BrokerOptions);
     /** Close the broker database connection. */
@@ -222,7 +274,8 @@ export declare class Broker {
     subscribeCommits(listener: BrokerCommitListener): () => void;
     /**
      * Register a concrete agent under one workspace-unique session name.
-     * @param args - Caller-supplied identity, topology, and implementation values.
+     * @param args - Caller-supplied identity, topology, and implementation values. `workspacePath` is
+     * the directory the agent works in, which registers it in the workspace that directory belongs to.
      * @returns - Stable agent identity registered in the requested team.
      */
     registerAgent(args: {
@@ -237,15 +290,17 @@ export declare class Broker {
     /**
      * Register or rejoin an implementation identity without a prior launch reservation.
      *
-     * A `sessionKey` makes the identity resumable: the same harness conversation returning after a
-     * restart resolves to the identity it already owns, keeping its alias, inbox, and traffic, whatever
-     * the caller passes as `sessionName`. Without one, rejoining still falls back to matching the alias.
+     * A `sessionKey` makes the identity resumable: the same harness conversation returning to the same
+     * working directory after a restart resolves to the identity it already owns, keeping its alias,
+     * inbox, and traffic, whatever the caller passes as `sessionName`. Without one, rejoining still
+     * falls back to matching the alias.
      *
      * A `continuesSessionKey` is the key a conversation was known by before it continued under
      * `sessionKey`. When `sessionKey` owns no identity yet, the identity the continued key owns moves
      * to `sessionKey`, its holder displaced, so the alias, inbox, and traffic follow the conversation.
-     * @param args - Validated workspace, implementation, optional alias, optional resumable key, and
-     * the key of the conversation that one continues, which requires the resumable key.
+     * @param args - Directory the agent works in, which registers it in the workspace that directory
+     * belongs to; implementation; optional alias; optional resumable key; and the key of the
+     * conversation that one continues, which requires the resumable key.
      * @returns - Stable agent identity, its current alias, and a fresh single-use attachment reservation.
      */
     registerAgentWithoutReservation(args: {
@@ -267,24 +322,37 @@ export declare class Broker {
      * @param requestedAlias - Workspace-unique name, with an optional leading at-sign.
      * @returns - Current identity and alias history after the replacement.
      */
-    updateAgentAlias(agentId: AgentId, requestedAlias: string): {
-        id: AgentId;
-        alias: string;
-        previousAliases: string[];
-    };
+    updateAgentAlias(agentId: AgentId, requestedAlias: string): AgentIdentity;
     /**
-     * Return the authenticated identity, current alias, and prior routable names.
+     * Move an agent to another workspace, rename it, or both, in one step.
+     *
+     * The alias must be free in the target workspace: held by nobody else and reserved as nobody
+     * else's retired name. Without `force` a taken alias fails with `alias_conflict` naming its holder
+     * and changes nothing. With `force` the caller takes the holder's identity over: its id, alias,
+     * inbox and alias history become the caller's, and the identity joins the target workspace, which
+     * is the caller's own when the request names none; the caller's own connections and
+     * conversation key move onto it, and the caller's previous identity is retired with its messages
+     * moved across and its aliases reserved as redirects to the claimed identity. The holder's own
+     * sessions and unconsumed attach reservations end, so a session or resume token it presents is
+     * refused as expired, and a claim token it held acknowledges nothing.
+     *
+     * A move keeps every alias the agent held reserved in the workspace it leaves, redirecting to its
+     * current address, and carries its alias history into the workspace it joins.
+     * @param agentId - Authenticated identity asking to move or rename.
+     * @param request - Target workspace, alias, and whether to take the alias over from its holder.
+     * @returns - The identity the caller now acts as, and the takeover when one was performed.
+     */
+    relocateAgent(agentId: AgentId, request: AgentRelocationRequest): AgentRelocation;
+    /**
+     * Return an agent's identity as reported to that agent.
      * @param agentId - Stable identity to inspect.
      * @returns - Identity details safe to return to the owning agent.
      */
-    agentIdentity(agentId: AgentId): {
-        id: AgentId;
-        alias: string;
-        previousAliases: string[];
-    };
+    agentIdentity(agentId: AgentId): AgentIdentity;
     /**
      * Reserve an identity and single-use attach reservation for a future process.
-     * @param args - Registration name, team, and workspace the reservation is created under.
+     * @param args - Registration name, team, and the directory the future process works in, which
+     * creates the reservation in the workspace that directory belongs to.
      * @returns - Reservation identity and one-time reservation for the future agent.
      */
     reserveAgent(args: {
@@ -548,7 +616,8 @@ export declare class Broker {
     operationalEvents(): BrokerOperationalEvent[];
     /**
      * Append an operational event recording the outcome of a delivery notification attempt.
-     * @param messageId - Message the notification outcome is recorded against.
+     * @param messageId - Message the notification outcome is recorded against; an outcome for a
+     * message deleted while its notification was in flight is dropped.
      * @param outcome - Observed notification result recorded for diagnostics.
      */
     recordNotification(messageId: string, outcome: NotificationOutcome): void;
@@ -604,6 +673,25 @@ export declare class Broker {
      * @returns - Durable acceptance, reporting whether this call created it.
      */
     acceptOperatorArchive(commandId: string, agentId: AgentId): BrokerOperatorCommandAcceptance;
+    /**
+     * Accept one operator purge request, deleting the named identities and their records.
+     *
+     * A message is deleted with its events and claims only when neither end is an identity that
+     * outlives the purge. A message exchanged with one that does stays in that identity's history,
+     * naming the purged end by its raw id, and is dead-lettered if it was still waiting in a purged
+     * inbox. Operator command records keep the ids they targeted, so a retried command is still
+     * answered from its record, and the identity's sessions are kept ended, so a process still
+     * attached to it is told it was ended. Claims a purged identity made on a kept message stay as
+     * that message's delivery attempts, and operator stream events already published about the
+     * identity stay in the replay journal until it trims them. Every other row naming a purged identity
+     * is deleted.
+     * Workspace rows are kept even when no identity remains in them, because previous addresses
+     * into a workspace and the short names of other workspaces are resolved from them.
+     * @param commandId - Correlates retries of the same operator request.
+     * @param agentIds - Distinct agents the operator asked to purge, in any lifecycle state.
+     * @returns - Durable acceptance, reporting whether this call created it.
+     */
+    acceptOperatorPurge(commandId: string, agentIds: readonly AgentId[]): BrokerOperatorCommandAcceptance;
     /**
      * Returns the broker snapshot, optionally scoped to one workspace.
      *