agent-relay 2.0.20 → 2.0.22

package/packages/mcp/dist/tools/relay-remove-agent.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+export const relayRemoveAgentSchema = z.object({
+    name: z.string().describe('Name of the agent to remove from the registry'),
+    remove_messages: z.boolean().optional().default(false).describe('Also remove all messages from/to this agent'),
+});
+export const relayRemoveAgentTool = {
+    name: 'relay_remove_agent',
+    description: `Remove a stale agent from the relay registry.
+
+Use this to clean up agents that are no longer needed or have become stale.
+This removes the agent from:
+- The agent registry (agents.json)
+- The sessions table in storage
+- Optionally, all messages from/to this agent
+
+WARNING: This permanently removes the agent's history. Use with caution.`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                description: 'Name of the agent to remove',
+            },
+            remove_messages: {
+                type: 'boolean',
+                description: 'Also remove all messages from/to this agent',
+                default: false,
+            },
+        },
+        required: ['name'],
+    },
+};
+/**
+ * Remove an agent from the registry.
+ */
+export async function handleRelayRemoveAgent(client, input) {
+    const result = await client.removeAgent(input.name, {
+        removeMessages: input.remove_messages,
+    });
+    if (result.success && result.removed) {
+        return `✓ ${result.message}`;
+    }
+    else if (result.success && !result.removed) {
+        return `Agent "${input.name}" was not found in registry or storage.`;
+    }
+    else {
+        return `✗ Failed to remove agent: ${result.message}`;
+    }
+}
+//# sourceMappingURL=relay-remove-agent.js.map

package/packages/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/mcp",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "MCP server for Agent Relay - native messaging tools for AI agents in Claude, Cursor, and VS Code",
   "author": "Agent Workforce Inc.",
   "license": "Apache-2.0",
@@ -47,7 +47,7 @@
     "prepublishOnly": "npm run clean && npm run build && npm test"
   },
   "dependencies": {
-    "@agent-relay/config": "2.0.20",
+    "@agent-relay/config": "2.0.22",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "smol-toml": "^1.6.0",
     "zod": "^3.23.8"

package/packages/memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/memory",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "Semantic memory storage and retrieval system for agent-relay with multiple backend support",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/hooks": "2.0.20"
+    "@agent-relay/hooks": "2.0.22"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/policy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/policy",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "Agent policy management with multi-level fallback (repo, local PRPM, cloud workspace)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "2.0.20"
+    "@agent-relay/config": "2.0.22"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/protocol/dist/types.d.ts

@@ -5,7 +5,7 @@
  * These types define the wire protocol for agent-to-agent communication.
  */
 export declare const PROTOCOL_VERSION = 1;
-export type MessageType = 'HELLO' | 'WELCOME' | 'SEND' | 'DELIVER' | 'ACK' | 'NACK' | 'PING' | 'PONG' | 'ERROR' | 'BUSY' | 'RESUME' | 'BYE' | 'STATE' | 'SYNC' | 'SYNC_SNAPSHOT' | 'SYNC_DELTA' | 'SUBSCRIBE' | 'UNSUBSCRIBE' | 'SHADOW_BIND' | 'SHADOW_UNBIND' | 'LOG' | 'CHANNEL_JOIN' | 'CHANNEL_LEAVE' | 'CHANNEL_MESSAGE' | 'CHANNEL_INFO' | 'CHANNEL_MEMBERS' | 'CHANNEL_TYPING' | 'SPAWN' | 'SPAWN_RESULT' | 'RELEASE' | 'RELEASE_RESULT' | 'STATUS' | 'STATUS_RESPONSE' | 'INBOX' | 'INBOX_RESPONSE' | 'LIST_AGENTS' | 'LIST_AGENTS_RESPONSE' | 'HEALTH' | 'HEALTH_RESPONSE' | 'METRICS' | 'METRICS_RESPONSE';
+export type MessageType = 'HELLO' | 'WELCOME' | 'SEND' | 'DELIVER' | 'ACK' | 'NACK' | 'PING' | 'PONG' | 'ERROR' | 'BUSY' | 'RESUME' | 'BYE' | 'STATE' | 'SYNC' | 'SYNC_SNAPSHOT' | 'SYNC_DELTA' | 'SUBSCRIBE' | 'UNSUBSCRIBE' | 'SHADOW_BIND' | 'SHADOW_UNBIND' | 'LOG' | 'CHANNEL_JOIN' | 'CHANNEL_LEAVE' | 'CHANNEL_MESSAGE' | 'CHANNEL_INFO' | 'CHANNEL_MEMBERS' | 'CHANNEL_TYPING' | 'SPAWN' | 'SPAWN_RESULT' | 'RELEASE' | 'RELEASE_RESULT' | 'STATUS' | 'STATUS_RESPONSE' | 'INBOX' | 'INBOX_RESPONSE' | 'LIST_AGENTS' | 'LIST_AGENTS_RESPONSE' | 'LIST_CONNECTED_AGENTS' | 'LIST_CONNECTED_AGENTS_RESPONSE' | 'REMOVE_AGENT' | 'REMOVE_AGENT_RESPONSE' | 'HEALTH' | 'HEALTH_RESPONSE' | 'METRICS' | 'METRICS_RESPONSE';
 export type PayloadKind = 'message' | 'action' | 'state' | 'thinking';
 /**
  * Base envelope structure for all protocol messages.
@@ -412,12 +412,57 @@ export interface ListAgentsResponsePayload {
         parent?: string;
     }>;
 }
+/**
+ * Payload for LIST_CONNECTED_AGENTS request.
+ * Returns only currently connected agents (not historical/registered agents).
+ */
+export interface ListConnectedAgentsPayload {
+    /** Filter by project */
+    project?: string;
+}
+/**
+ * Payload for LIST_CONNECTED_AGENTS_RESPONSE.
+ */
+export interface ListConnectedAgentsResponsePayload {
+    /** List of currently connected agents */
+    agents: Array<{
+        name: string;
+        cli?: string;
+        idle?: boolean;
+        parent?: string;
+    }>;
+}
+/**
+ * Payload for REMOVE_AGENT request.
+ * Removes an agent from the registry (sessions, agents.json).
+ */
+export interface RemoveAgentPayload {
+    /** Agent name to remove */
+    name: string;
+    /** If true, also removes all messages from/to this agent */
+    removeMessages?: boolean;
+}
+/**
+ * Payload for REMOVE_AGENT_RESPONSE.
+ */
+export interface RemoveAgentResponsePayload {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Whether an agent was actually removed */
+    removed: boolean;
+    /** Human-readable message */
+    message?: string;
+}
 export type StatusEnvelope = Envelope<StatusPayload>;
 export type StatusResponseEnvelope = Envelope<StatusResponsePayload>;
 export type InboxEnvelope = Envelope<InboxPayload>;
 export type InboxResponseEnvelope = Envelope<InboxResponsePayload>;
 export type ListAgentsEnvelope = Envelope<ListAgentsPayload>;
 export type ListAgentsResponseEnvelope = Envelope<ListAgentsResponsePayload>;
+export type ListConnectedAgentsEnvelope = Envelope<ListConnectedAgentsPayload>;
+export type ListConnectedAgentsResponseEnvelope = Envelope<ListConnectedAgentsResponsePayload>;
+export type RemoveAgentEnvelope = Envelope<RemoveAgentPayload>;
+export type RemoveAgentResponseEnvelope = Envelope<RemoveAgentResponsePayload>;
 /**
  * Payload for HEALTH request.
  */

package/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/protocol",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "Wire protocol types and framing for Agent Relay",
   "type": "module",
   "main": "dist/index.js",

package/packages/resiliency/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/resiliency",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "Health monitoring, logging, metrics, and crash resilience utilities for Agent Relay",
   "type": "module",
   "main": "dist/index.js",

package/packages/sdk/dist/client.d.ts

@@ -4,7 +4,7 @@
  *
  * Lightweight client for agent-to-agent communication via Agent Relay daemon.
  */
-import { type Envelope, type SendPayload, type SendMeta, type AckPayload, type PayloadKind, type SpeakOnTrigger, type EntityType, type ChannelMessagePayload, type MessageAttachment, type SpawnResultPayload, type ReleaseResultPayload, type StatusResponsePayload, type InboxMessage, type AgentInfo, type HealthResponsePayload, type MetricsResponsePayload, type CreateProposalOptions, type VoteOptions } from './protocol/types.js';
+import { type Envelope, type SendPayload, type SendMeta, type AckPayload, type PayloadKind, type SpeakOnTrigger, type EntityType, type ChannelMessagePayload, type MessageAttachment, type SpawnResultPayload, type ReleaseResultPayload, type StatusResponsePayload, type InboxMessage, type AgentInfo, type RemoveAgentResponsePayload, type HealthResponsePayload, type MetricsResponsePayload, type CreateProposalOptions, type VoteOptions } from './protocol/types.js';
 export type ClientState = 'DISCONNECTED' | 'CONNECTING' | 'HANDSHAKING' | 'READY' | 'BACKOFF';
 export interface SyncOptions {
     timeoutMs?: number;
@@ -289,6 +289,27 @@ export declare class RelayClient {
     getMetrics(options?: {
         agent?: string;
     }): Promise<MetricsResponsePayload>;
+    /**
+     * List only currently connected agents (not historical/registered agents).
+     * Use this instead of listAgents() when you need accurate liveness information.
+     * @param options - Filter options
+     * @param options.project - Filter by project
+     * @returns Array of currently connected agent info
+     */
+    listConnectedAgents(options?: {
+        project?: string;
+    }): Promise<AgentInfo[]>;
+    /**
+     * Remove an agent from the registry (sessions, agents.json).
+     * Use this to clean up stale agents that are no longer needed.
+     * @param name - Agent name to remove
+     * @param options - Removal options
+     * @param options.removeMessages - Also remove all messages from/to this agent (default: false)
+     * @returns Result indicating if the agent was removed
+     */
+    removeAgent(name: string, options?: {
+        removeMessages?: boolean;
+    }): Promise<RemoveAgentResponsePayload>;
     private setState;
     private sendHello;
     private send;

package/packages/sdk/dist/client.js

@@ -731,6 +731,35 @@ export class RelayClient {
         };
         return this.query('METRICS', payload);
     }
+    /**
+     * List only currently connected agents (not historical/registered agents).
+     * Use this instead of listAgents() when you need accurate liveness information.
+     * @param options - Filter options
+     * @param options.project - Filter by project
+     * @returns Array of currently connected agent info
+     */
+    async listConnectedAgents(options = {}) {
+        const payload = {
+            project: options.project,
+        };
+        const response = await this.query('LIST_CONNECTED_AGENTS', payload);
+        return response.agents || [];
+    }
+    /**
+     * Remove an agent from the registry (sessions, agents.json).
+     * Use this to clean up stale agents that are no longer needed.
+     * @param name - Agent name to remove
+     * @param options - Removal options
+     * @param options.removeMessages - Also remove all messages from/to this agent (default: false)
+     * @returns Result indicating if the agent was removed
+     */
+    async removeAgent(name, options = {}) {
+        const payload = {
+            name,
+            removeMessages: options.removeMessages,
+        };
+        return this.query('REMOVE_AGENT', payload);
+    }
     // Private methods
     setState(state) {
         this._state = state;
@@ -839,6 +868,8 @@ export class RelayClient {
             case 'STATUS_RESPONSE':
             case 'INBOX_RESPONSE':
             case 'LIST_AGENTS_RESPONSE':
+            case 'LIST_CONNECTED_AGENTS_RESPONSE':
+            case 'REMOVE_AGENT_RESPONSE':
             case 'HEALTH_RESPONSE':
             case 'METRICS_RESPONSE':
                 this.handleQueryResponse(envelope);

package/packages/sdk/dist/protocol/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * Protocol exports for @agent-relay/sdk
  */
-export { PROTOCOL_VERSION, type MessageType, type PayloadKind, type Envelope, type EntityType, type HelloPayload, type WelcomePayload, type SendPayload, type SendMeta, type SyncMeta, type DeliveryInfo, type AckPayload, type NackPayload, type BusyPayload, type PingPayload, type PongPayload, type ErrorCode, type ErrorPayload, type LogPayload, type SyncStream, type SyncPayload, type SpeakOnTrigger, type ShadowConfig, type ShadowBindPayload, type ShadowUnbindPayload, type SpawnPayload, type SpawnPolicyDecision, type SpawnResultPayload, type ReleasePayload, type ReleaseResultPayload, type ConsensusType, type VoteValue, type ProposalStatus, type CreateProposalOptions, type VoteOptions, type MessageAttachment, type ChannelJoinPayload, type ChannelLeavePayload, type ChannelMessagePayload, type StatusPayload, type StatusResponsePayload, type InboxPayload, type InboxMessage, type InboxResponsePayload, type ListAgentsPayload, type AgentInfo, type ListAgentsResponsePayload, type HealthPayload, type CrashRecord, type AlertRecord, type HealthResponsePayload, type MetricsPayload, type AgentMetrics, type MetricsResponsePayload, type HelloEnvelope, type WelcomeEnvelope, type SendEnvelope, type DeliverEnvelope, type AckEnvelope, type NackEnvelope, type PingEnvelope, type PongEnvelope, type ErrorEnvelope, type BusyEnvelope, type LogEnvelope, type SyncEnvelope, type ShadowBindEnvelope, type ShadowUnbindEnvelope, type SpawnEnvelope, type SpawnResultEnvelope, type ReleaseEnvelope, type ReleaseResultEnvelope, type ChannelJoinEnvelope, type ChannelLeaveEnvelope, type ChannelMessageEnvelope, type StatusEnvelope, type StatusResponseEnvelope, type InboxEnvelope, type InboxResponseEnvelope, type ListAgentsEnvelope, type ListAgentsResponseEnvelope, type HealthEnvelope, type HealthResponseEnvelope, type MetricsEnvelope, type MetricsResponseEnvelope, } from './types.js';
+export { PROTOCOL_VERSION, type MessageType, type PayloadKind, type Envelope, type EntityType, type HelloPayload, type WelcomePayload, type SendPayload, type SendMeta, type SyncMeta, type DeliveryInfo, type AckPayload, type NackPayload, type BusyPayload, type PingPayload, type PongPayload, type ErrorCode, type ErrorPayload, type LogPayload, type SyncStream, type SyncPayload, type SpeakOnTrigger, type ShadowConfig, type ShadowBindPayload, type ShadowUnbindPayload, type SpawnPayload, type SpawnPolicyDecision, type SpawnResultPayload, type ReleasePayload, type ReleaseResultPayload, type ConsensusType, type VoteValue, type ProposalStatus, type CreateProposalOptions, type VoteOptions, type MessageAttachment, type ChannelJoinPayload, type ChannelLeavePayload, type ChannelMessagePayload, type StatusPayload, type StatusResponsePayload, type InboxPayload, type InboxMessage, type InboxResponsePayload, type ListAgentsPayload, type AgentInfo, type ListAgentsResponsePayload, type ListConnectedAgentsPayload, type ListConnectedAgentsResponsePayload, type RemoveAgentPayload, type RemoveAgentResponsePayload, type HealthPayload, type CrashRecord, type AlertRecord, type HealthResponsePayload, type MetricsPayload, type AgentMetrics, type MetricsResponsePayload, type HelloEnvelope, type WelcomeEnvelope, type SendEnvelope, type DeliverEnvelope, type AckEnvelope, type NackEnvelope, type PingEnvelope, type PongEnvelope, type ErrorEnvelope, type BusyEnvelope, type LogEnvelope, type SyncEnvelope, type ShadowBindEnvelope, type ShadowUnbindEnvelope, type SpawnEnvelope, type SpawnResultEnvelope, type ReleaseEnvelope, type ReleaseResultEnvelope, type ChannelJoinEnvelope, type ChannelLeaveEnvelope, type ChannelMessageEnvelope, type StatusEnvelope, type StatusResponseEnvelope, type InboxEnvelope, type InboxResponseEnvelope, type ListAgentsEnvelope, type ListAgentsResponseEnvelope, type ListConnectedAgentsEnvelope, type ListConnectedAgentsResponseEnvelope, type RemoveAgentEnvelope, type RemoveAgentResponseEnvelope, type HealthEnvelope, type HealthResponseEnvelope, type MetricsEnvelope, type MetricsResponseEnvelope, } from './types.js';
 export { MAX_FRAME_BYTES, HEADER_SIZE, LEGACY_HEADER_SIZE, type WireFormat, initMessagePack, hasMessagePack, encodeFrame, encodeFrameLegacy, FrameParser, } from './framing.js';
 //# sourceMappingURL=index.d.ts.map

package/packages/sdk/dist/protocol/types.d.ts

@@ -5,7 +5,7 @@
  * These types define the wire protocol for agent-to-agent communication.
  */
 export declare const PROTOCOL_VERSION = 1;
-export type MessageType = 'HELLO' | 'WELCOME' | 'SEND' | 'DELIVER' | 'ACK' | 'NACK' | 'PING' | 'PONG' | 'ERROR' | 'BUSY' | 'RESUME' | 'BYE' | 'STATE' | 'SYNC' | 'SYNC_SNAPSHOT' | 'SYNC_DELTA' | 'SUBSCRIBE' | 'UNSUBSCRIBE' | 'SHADOW_BIND' | 'SHADOW_UNBIND' | 'LOG' | 'CHANNEL_JOIN' | 'CHANNEL_LEAVE' | 'CHANNEL_MESSAGE' | 'CHANNEL_INFO' | 'CHANNEL_MEMBERS' | 'CHANNEL_TYPING' | 'SPAWN' | 'SPAWN_RESULT' | 'RELEASE' | 'RELEASE_RESULT' | 'STATUS' | 'STATUS_RESPONSE' | 'INBOX' | 'INBOX_RESPONSE' | 'LIST_AGENTS' | 'LIST_AGENTS_RESPONSE' | 'HEALTH' | 'HEALTH_RESPONSE' | 'METRICS' | 'METRICS_RESPONSE';
+export type MessageType = 'HELLO' | 'WELCOME' | 'SEND' | 'DELIVER' | 'ACK' | 'NACK' | 'PING' | 'PONG' | 'ERROR' | 'BUSY' | 'RESUME' | 'BYE' | 'STATE' | 'SYNC' | 'SYNC_SNAPSHOT' | 'SYNC_DELTA' | 'SUBSCRIBE' | 'UNSUBSCRIBE' | 'SHADOW_BIND' | 'SHADOW_UNBIND' | 'LOG' | 'CHANNEL_JOIN' | 'CHANNEL_LEAVE' | 'CHANNEL_MESSAGE' | 'CHANNEL_INFO' | 'CHANNEL_MEMBERS' | 'CHANNEL_TYPING' | 'SPAWN' | 'SPAWN_RESULT' | 'RELEASE' | 'RELEASE_RESULT' | 'STATUS' | 'STATUS_RESPONSE' | 'INBOX' | 'INBOX_RESPONSE' | 'LIST_AGENTS' | 'LIST_AGENTS_RESPONSE' | 'LIST_CONNECTED_AGENTS' | 'LIST_CONNECTED_AGENTS_RESPONSE' | 'REMOVE_AGENT' | 'REMOVE_AGENT_RESPONSE' | 'HEALTH' | 'HEALTH_RESPONSE' | 'METRICS' | 'METRICS_RESPONSE';
 export type PayloadKind = 'message' | 'action' | 'state' | 'thinking';
 /**
  * Base envelope structure for all protocol messages.
@@ -410,6 +410,36 @@ export interface AgentInfo {
 export interface ListAgentsResponsePayload {
     agents: AgentInfo[];
 }
+/**
+ * Payload for LIST_CONNECTED_AGENTS request.
+ * Returns only currently connected agents (not historical/registered agents).
+ */
+export interface ListConnectedAgentsPayload {
+    project?: string;
+}
+/**
+ * Response payload for LIST_CONNECTED_AGENTS request.
+ */
+export interface ListConnectedAgentsResponsePayload {
+    agents: AgentInfo[];
+}
+/**
+ * Payload for REMOVE_AGENT request.
+ * Removes an agent from the registry (sessions, agents.json).
+ */
+export interface RemoveAgentPayload {
+    name: string;
+    /** If true, also removes all messages from/to this agent */
+    removeMessages?: boolean;
+}
+/**
+ * Response payload for REMOVE_AGENT request.
+ */
+export interface RemoveAgentResponsePayload {
+    success: boolean;
+    removed: boolean;
+    message?: string;
+}
 /**
  * Payload for HEALTH request.
  */
@@ -519,6 +549,10 @@ export type InboxEnvelope = Envelope<InboxPayload>;
 export type InboxResponseEnvelope = Envelope<InboxResponsePayload>;
 export type ListAgentsEnvelope = Envelope<ListAgentsPayload>;
 export type ListAgentsResponseEnvelope = Envelope<ListAgentsResponsePayload>;
+export type ListConnectedAgentsEnvelope = Envelope<ListConnectedAgentsPayload>;
+export type ListConnectedAgentsResponseEnvelope = Envelope<ListConnectedAgentsResponsePayload>;
+export type RemoveAgentEnvelope = Envelope<RemoveAgentPayload>;
+export type RemoveAgentResponseEnvelope = Envelope<RemoveAgentResponsePayload>;
 export type HealthEnvelope = Envelope<HealthPayload>;
 export type HealthResponseEnvelope = Envelope<HealthResponsePayload>;
 export type MetricsEnvelope = Envelope<MetricsPayload>;

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/sdk",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "Lightweight SDK for agent-to-agent communication via Agent Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -55,7 +55,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@agent-relay/protocol": "2.0.20"
+    "@agent-relay/protocol": "2.0.22"
   },
   "engines": {
     "node": ">=18.0.0"

package/packages/spawner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/spawner",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "Agent spawning types and utilities for Agent Relay",
   "type": "module",
   "main": "dist/index.js",

package/packages/state/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/state",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "Agent state persistence for non-hook CLIs (Codex, Gemini, etc.)",
   "type": "module",
   "main": "dist/index.js",

package/packages/storage/dist/adapter.d.ts

@@ -96,6 +96,10 @@ export interface StorageAdapter {
     }>>;
     /** Get channels that an agent is a member of (based on stored membership events) */
     getChannelMembershipsForAgent?(memberName: string): Promise<string[]>;
+    /** Remove an agent from sessions table */
+    removeAgent?(agentName: string): Promise<void>;
+    /** Remove all messages from/to an agent */
+    removeMessagesForAgent?(agentName: string): Promise<void>;
 }
 /**
  * Storage configuration options.

package/packages/storage/dist/sqlite-adapter.d.ts

@@ -109,5 +109,15 @@ export declare class SqliteStorageAdapter implements StorageAdapter {
      * @returns List of channel names where the agent's latest action is not "leave"
      */
     getChannelMembershipsForAgent(memberName: string): Promise<string[]>;
+    /**
+     * Remove an agent from the sessions table.
+     * This is used to clean up stale agents from the registry.
+     */
+    removeAgent(agentName: string): Promise<void>;
+    /**
+     * Remove all messages from/to an agent.
+     * Use with caution - this permanently deletes message history.
+     */
+    removeMessagesForAgent(agentName: string): Promise<void>;
 }
 //# sourceMappingURL=sqlite-adapter.d.ts.map

package/packages/storage/dist/sqlite-adapter.js

@@ -750,5 +750,31 @@ export class SqliteStorageAdapter {
         const rows = stmt.all(memberName);
         return rows.map(row => row.channel);
     }
+    /**
+     * Remove an agent from the sessions table.
+     * This is used to clean up stale agents from the registry.
+     */
+    async removeAgent(agentName) {
+        if (!this.db) {
+            await this.init();
+        }
+        const stmt = this.db.prepare(`
+      DELETE FROM sessions WHERE agent_name = ?
+    `);
+        stmt.run(agentName);
+    }
+    /**
+     * Remove all messages from/to an agent.
+     * Use with caution - this permanently deletes message history.
+     */
+    async removeMessagesForAgent(agentName) {
+        if (!this.db) {
+            await this.init();
+        }
+        const stmt = this.db.prepare(`
+      DELETE FROM messages WHERE sender = ? OR recipient = ?
+    `);
+        stmt.run(agentName, agentName);
+    }
 }
 //# sourceMappingURL=sqlite-adapter.js.map

package/packages/storage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/storage",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "Storage adapters and interfaces for Relay message/session persistence",
   "type": "module",
   "main": "dist/index.js",
@@ -56,7 +56,7 @@
     }
   },
   "dependencies": {
-    "@agent-relay/protocol": "2.0.20"
+    "@agent-relay/protocol": "2.0.22"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/telemetry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/telemetry",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "Anonymous telemetry for Agent Relay usage analytics",
   "type": "module",
   "main": "dist/index.js",

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/trajectory",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "Trajectory integration utilities (trail/PDERO) for Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "2.0.20"
+    "@agent-relay/config": "2.0.22"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/user-directory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/user-directory",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "User directory service for agent-relay (per-user credential storage)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/resiliency": "2.0.20"
+    "@agent-relay/resiliency": "2.0.22"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/utils",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "Shared utilities for agent-relay: logging, name generation, command resolution, update checking",
   "type": "module",
   "main": "dist/index.js",

package/packages/wrapper/dist/relay-pty-orchestrator.js

@@ -19,6 +19,7 @@ import { spawn } from 'node:child_process';
 import { createConnection } from 'node:net';
 import { createHash } from 'node:crypto';
 import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
 import { existsSync, unlinkSync, mkdirSync, symlinkSync, lstatSync, rmSync, watch, readdirSync, readlinkSync, writeFileSync, appendFileSync } from 'node:fs';
 import { getProjectPaths } from '@agent-relay/config/project-namespace';
 import { fileURLToPath } from 'node:url';
@@ -140,17 +141,12 @@ export class RelayPtyOrchestrator extends BaseWrapper {
             this._legacyOutboxPath = `/tmp/relay-outbox/${config.name}`;
         }
         else {
-            // Local mode: use ~/.agent-relay paths directly (no symlinks needed)
+            // Local mode: use project paths directly (no symlinks needed)
             this._outboxPath = this._canonicalOutboxPath;
-            // Socket at {projectRoot}/.agent-relay/sockets/{agentName}.sock
-            let localSocketPath = join(projectPaths.dataDir, 'sockets', `${config.name}.sock`);
-            // If socket path is too long, fall back to /tmp/relay-local/{projectId}/sockets/
-            if (localSocketPath.length > MAX_SOCKET_PATH_LENGTH) {
-                const tmpSocketPath = `/tmp/relay-local/${projectPaths.projectId}/sockets/${config.name}.sock`;
-                console.warn(`[relay-pty-orchestrator:${config.name}] Socket path too long (${localSocketPath.length} chars); using /tmp fallback`);
-                localSocketPath = tmpSocketPath;
-            }
-            this.socketPath = localSocketPath;
+            // Socket path: use ~/.agent-relay/sockets/{projectId}/{agentName}.sock
+            // This keeps paths short (uses 12-char hashed projectId) while staying organized
+            // Example: /Users/foo/.agent-relay/sockets/abc123def456/MyAgent.sock (~65 chars)
+            this.socketPath = join(homedir(), '.agent-relay', 'sockets', projectPaths.projectId, `${config.name}.sock`);
             // Legacy path for backwards compat (older agents might still use /tmp/relay-outbox)
             // Even in local mode, we need this symlink for agents with stale instructions
             this._legacyOutboxPath = `/tmp/relay-outbox/${config.name}`;
@@ -651,7 +647,9 @@ export class RelayPtyOrchestrator extends BaseWrapper {
         // Wait for process to start
         await sleep(500);
         if (proc.exitCode !== null) {
-            throw new Error(`relay-pty exited immediately with code ${proc.exitCode}`);
+            // Include any captured stderr in the error for debugging
+            const stderrInfo = stderrBuffer ? `\nStderr: ${stderrBuffer.slice(0, 500)}` : '';
+            throw new Error(`relay-pty exited immediately with code ${proc.exitCode}${stderrInfo}`);
         }
         // Register for memory/CPU monitoring
         if (proc.pid) {

package/packages/wrapper/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/wrapper",
-  "version": "2.0.20",
+  "version": "2.0.22",
   "description": "CLI agent wrappers for Agent Relay - tmux, pty integration",
   "type": "module",
   "main": "dist/index.js",
@@ -30,11 +30,11 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@agent-relay/api-types": "2.0.20",
-    "@agent-relay/protocol": "2.0.20",
-    "@agent-relay/config": "2.0.20",
-    "@agent-relay/continuity": "2.0.20",
-    "@agent-relay/resiliency": "2.0.20"
+    "@agent-relay/api-types": "2.0.22",
+    "@agent-relay/protocol": "2.0.22",
+    "@agent-relay/config": "2.0.22",
+    "@agent-relay/continuity": "2.0.22",
+    "@agent-relay/resiliency": "2.0.22"
   },
   "devDependencies": {
     "typescript": "^5.9.3",