agent-comms 8.15.8 → 8.15.10

package/src/core/agent-details.ts

@@ -0,0 +1,216 @@
+/**
+ * The details a trusted remote peer asks for over a session of its own (agent-comms#323): a hub session publishes only an agent's summary, so its working directory, rooms and tags list elsewhere as not shared. A bridge this machine has chosen to trust may ask for them with the agent-comms/agent-details verb, carried over the relay pairing the two already have so the hub relays bytes it cannot read; the answer is the same summary a direct peer reads from the advert.
+ */
+
+import type { ManageOutcome } from "wire-mesh-core/domain/mesh-session";
+import type { RoomVerbHandler } from "./room-router.js";
+import type { MeshTransport } from "./transport.js";
+import { detailsShared } from "./agent-registry.js";
+import {
+  JOIN_ROUTE_RETRY_MS,
+  JOIN_ROUTE_WAIT_MS,
+  NO_ROUTE_CODES,
+} from "./account-join.js";
+import { deviceIdToHex } from "wire-mesh-core/domain/device-id";
+import type { AgentIdentity } from "./types.js";
+import type { HostedRoomAdvert } from "./gossip-extensions.js";
+
+/** The params.verb a trusted peer's request is dispatched by, keyed per room-router's own convention like account-join's "account.join". */
+export const AGENT_DETAILS_VERB = "agent.details";
+
+/** The outer manage-command verb the request rides, which only satisfies manage-command.verb's own capability-verb grammar; the receiving side dispatches on AGENT_DETAILS_VERB, never this. */
+export const AGENT_DETAILS_CAPABILITY_VERB = "agent:details";
+
+/** One room as the details answer carries it: the hosted-room facts a direct peer's advert includes, description included. */
+export interface AgentDetailsRoom {
+  path: string;
+  name: string;
+  description: string;
+}
+
+/** The details a trusted peer gets that a hub session withholds: everything but the summary. */
+export interface AgentDetails {
+  cwd: string;
+  tags: readonly string[];
+  rooms: readonly AgentDetailsRoom[];
+}
+
+/** What the verb handler needs: this side's own current details (undefined while no agent is registered), and the trust boundary the requester is gated on. */
+export interface AgentDetailsDeps {
+  details: () => AgentDetails | undefined;
+  isTrusted: (deviceHex: string) => boolean;
+}
+
+/** Answers the agent.details verb: the full details for a requester this machine trusts by device id, an explicit refusal for anyone else, and no agent yet for a bridge that has not registered. The requester is whoever the transport actually authenticated: the device the end-to-end secure channel named for a relayed request (fromDevice, never an address a hub asserts), or the connection's own authenticated peer for a direct session (the handle's id, which every dispatch path builds from exactly that). */
+export function agentDetailsVerbHandler(
+  deps: Readonly<AgentDetailsDeps>,
+): RoomVerbHandler {
+  return async (request, handle) => {
+    const requesterHex =
+      request.fromDevice !== undefined
+        ? deviceIdToHex(request.fromDevice)
+        : handle.id;
+    if (!deps.isTrusted(requesterHex)) {
+      return { result: "error", code: "untrusted_requester" };
+    }
+    const details = deps.details();
+    if (details === undefined) {
+      return { result: "error", code: "no_agent" };
+    }
+    return {
+      result: "ok",
+      cwd: details.cwd,
+      tags: details.tags,
+      rooms: details.rooms,
+    };
+  };
+}
+
+/** Narrows an untrusted value into one AgentDetailsRoom. */
+function isAgentDetailsRoom(value: unknown): value is AgentDetailsRoom {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("path" in value) || typeof value.path !== "string") return false;
+  if (!("name" in value) || typeof value.name !== "string") return false;
+  if (!("description" in value) || typeof value.description !== "string") {
+    return false;
+  }
+  return true;
+}
+
+/** Narrows a manage outcome into the AgentDetails it carries: an ok outcome whose every field has the expected shape, and nothing else (a refusal, or an answer from a peer running something else). */
+export function parseAgentDetails(
+  outcome: Readonly<ManageOutcome>,
+): AgentDetails | undefined {
+  if (outcome.result !== "ok") return undefined;
+  if (typeof outcome.cwd !== "string") return undefined;
+  if (!Array.isArray(outcome.tags)) return undefined;
+  if (outcome.tags.some((tag) => typeof tag !== "string")) return undefined;
+  if (!Array.isArray(outcome.rooms)) return undefined;
+  const rooms: AgentDetailsRoom[] = [];
+  for (const room of outcome.rooms) {
+    if (!isAgentDetailsRoom(room)) return undefined;
+    rooms.push(room);
+  }
+  return { cwd: outcome.cwd, tags: outcome.tags, rooms };
+}
+
+/** The cache of details this side has asked trusted peers for: refreshed whenever a listing triggers a new fetch, and trimmed to the agents the last listing actually showed so a departed agent's entry does not linger. */
+export class AgentDetailsCache {
+  private readonly entries = new Map<string, AgentDetails>();
+
+  /** Records (or replaces) the details fetched for one agent. */
+  set(agentId: string, details: Readonly<AgentDetails>): void {
+    this.entries.set(agentId, { ...details, rooms: [...details.rooms] });
+  }
+
+  /** The cached details for one agent, if a fetch has completed. */
+  get(agentId: string): Readonly<AgentDetails> | undefined {
+    return this.entries.get(agentId);
+  }
+
+  /** Drops every entry whose agent the last listing did not include. */
+  retain(agentIds: ReadonlySet<string>): void {
+    for (const agentId of this.entries.keys()) {
+      if (!agentIds.has(agentId)) this.entries.delete(agentId);
+    }
+  }
+}
+
+/** This side's own details for a registered agent and its hosted rooms, the verb's answer body. */
+export function ownAgentDetailsOf(
+  agent: Readonly<Pick<AgentIdentity, "cwd" | "tags">>,
+  hostedRooms: readonly Readonly<HostedRoomAdvert>[],
+): AgentDetails {
+  return {
+    cwd: agent.cwd,
+    tags: agent.tags,
+    rooms: hostedRooms.map((room) => ({
+      path: room.path,
+      name: room.name,
+      description: room.description,
+    })),
+  };
+}
+
+/** What the exchange needs from the store: this side's own agent and hosted rooms for answers, the trust boundary both directions gate on, a way to send a request to a peer, and this side's own peer id. */
+export interface AgentDetailsExchangeDeps {
+  selfAgent: () => Readonly<Pick<AgentIdentity, "cwd" | "tags">> | undefined;
+  hostedRooms: () => readonly Readonly<HostedRoomAdvert>[];
+  isTrusted: (deviceHex: string) => boolean;
+  requireTransport: () => Readonly<Pick<MeshTransport, "sendRoomRequest">>;
+}
+
+/** Both halves of agent-comms#323 in one place: the verb a trusted peer's request is answered by, and the background fetch that fills this side's cache from peers this machine trusts. */
+export class AgentDetailsExchange {
+  private readonly cache = new AgentDetailsCache();
+
+  /** The registered verb handler, answering from this side's own agent and hosted rooms. */
+  readonly handler: RoomVerbHandler;
+
+  constructor(private readonly deps: Readonly<AgentDetailsExchangeDeps>) {
+    this.handler = agentDetailsVerbHandler({
+      details: () => {
+        const agent = deps.selfAgent();
+        return agent === undefined
+          ? undefined
+          : ownAgentDetailsOf(agent, deps.hostedRooms());
+      },
+      isTrusted: deps.isTrusted,
+    });
+  }
+
+  /** Asks every trusted remote agent whose details a hub session withholds for them, without waiting: answers land in the cache and show on the next listing, and an unreachable peer simply keeps its not-shared listing. selfPeerId is the asking side's own agent, excluded from the fetches. */
+  refresh(
+    agents: readonly Readonly<AgentIdentity>[],
+    selfPeerId: string,
+  ): void {
+    const shown = new Set<string>();
+    for (const agent of agents) {
+      shown.add(agent.id);
+      if (agent.id === selfPeerId) continue;
+      if (detailsShared(agent)) continue;
+      if (!this.deps.isTrusted(agent.id)) continue;
+      void this.fetch(agent.id);
+    }
+    this.cache.retain(shown);
+  }
+
+  /** The cached details for one remote agent, once its trusted peer has answered. */
+  cached(agentId: string): Readonly<AgentDetails> | undefined {
+    return this.cache.get(agentId);
+  }
+
+  /** One agent's fetch, retried while no route to it exists yet (a relay pairing takes a moment to come up) and settled by the first real answer either way. */
+  private async fetch(agentId: string): Promise<void> {
+    const deadline = Date.now() + JOIN_ROUTE_WAIT_MS;
+    for (;;) {
+      let outcome;
+      try {
+        outcome = await this.deps.requireTransport().sendRoomRequest(
+          agentId,
+          {
+            verb: AGENT_DETAILS_CAPABILITY_VERB,
+            params: { verb: AGENT_DETAILS_VERB },
+          },
+          { kind: "node" },
+        );
+      } catch {
+        // An unreachable peer is routine (it is listed from its last advert); its details stay not shared.
+        return;
+      }
+      const details = parseAgentDetails(outcome);
+      if (details !== undefined) {
+        this.cache.set(agentId, details);
+        return;
+      }
+      // A pairing still warming answers "timeout" before it answers the verb, so that outcome is retried within the window too: the listing refreshes on every call, and a details fetch is never worth more than the wait.
+      const transient =
+        outcome.result === "error" &&
+        (NO_ROUTE_CODES.has(outcome.code) || outcome.code === "timeout");
+      if (!transient || Date.now() >= deadline) return;
+      await new Promise<void>((resolve) => {
+        setTimeout(resolve, JOIN_ROUTE_RETRY_MS);
+      });
+    }
+  }
+}

package/src/core/agent-list-format.ts

@@ -0,0 +1,97 @@
+/**
+ * The list_agents listing's formatting, split out of tool.ts to keep that file under the repo's max-lines cap: the table, the per-agent describe block with rooms and versions, and the machine grouping.
+ */
+
+import type { Namer } from "./naming.js";
+import { detailsShared } from "./agent-registry.js";
+import { groupAgentsByMachine } from "./machine-list-groups.js";
+import { agentTable, type AgentTableRow } from "./agent-table.js";
+import {
+  formatListedAgentVersions,
+  type VersionReportStore,
+} from "./version-report-actions.js";
+import type { CommsResult } from "./tool.js";
+import type { AgentIdentity } from "./types.js";
+import type { AgentDetailsExchange } from "./agent-details.js";
+
+/** What the renderer needs beyond the agents themselves: who is asking, their namer, and the store's optional reads (versions, machines, and the agent-details exchange's cache). */
+export interface AgentListFormatStore extends Readonly<
+  Pick<
+    VersionReportStore,
+    | "getPeerAgentCommsVersion"
+    | "getPeerWireMeshCoreVersion"
+    | "getPeerCcPeerVersion"
+  >
+> {
+  getCcPeerVersion?: (() => string | undefined) | undefined;
+  getMachineId?: (() => string | undefined) | undefined;
+  listAgentMachines?: (() => Promise<Map<string, string>>) | undefined;
+  agentDetailsExchange?: Readonly<Pick<AgentDetailsExchange, "cached">>;
+}
+
+/** Renders the whole listing. A trusted remote agent's fetched details (agent-comms#323) stand in for the ones a hub session withholds; a fetch that has not come back yet keeps its not-shared listing until the next call. */
+export async function renderAgentList(
+  agents: readonly Readonly<AgentIdentity>[],
+  opts: Readonly<{
+    selfId: string;
+    namer: Namer;
+    store: Readonly<AgentListFormatStore>;
+  }>,
+): Promise<CommsResult> {
+  const homedir = process.env.HOME ?? "";
+  const abbreviateCwd = (cwd: string): string =>
+    homedir && cwd.startsWith(homedir) ? `~${cwd.slice(homedir.length)}` : cwd;
+
+  // The full id is printed in its own column, so the name column carries the names alone.
+  const rowOf = (a: Readonly<AgentIdentity>): AgentTableRow => {
+    const asked = opts.store.agentDetailsExchange?.cached(a.id);
+    const shared = detailsShared(a) || asked !== undefined;
+    return {
+      id: a.id,
+      name: opts.namer(a.id, { selfName: a.name, besideFullId: true }),
+      harness: a.harness,
+      status: a.status,
+      visibility: a.visibility,
+      cwd: `${shared ? abbreviateCwd(asked?.cwd ?? a.cwd) : "(not shared)"}${a.id === opts.selfId ? " (you)" : ""}`,
+    };
+  };
+  const table = agentTable(agents.map(rowOf));
+  const describe = (a: Readonly<AgentIdentity>): string => {
+    const isSelf = a.id === opts.selfId;
+    const asked = opts.store.agentDetailsExchange?.cached(a.id);
+    const shared = detailsShared(a) || asked !== undefined;
+    const roomPaths =
+      asked === undefined ? a.subscribedRooms : asked.rooms.map((r) => r.path);
+    const rooms = !shared
+      ? "not shared"
+      : roomPaths.length > 0
+        ? roomPaths.join(", ")
+        : "none";
+    const versions = formatListedAgentVersions(
+      opts.store,
+      a.id,
+      isSelf,
+      opts.store.getCcPeerVersion,
+    );
+    return `${table.line(rowOf(a))}\n        Rooms: ${rooms}\n        Versions: ${versions}`;
+  };
+  const machines = await opts.store.listAgentMachines?.();
+  const groups = groupAgentsByMachine(
+    agents,
+    machines,
+    opts.store.getMachineId?.(),
+    opts.namer,
+  );
+  const body = groups
+    .map((group) => {
+      const rows = group.agents.map((a) => `  ${describe(a)}`);
+      return group.heading === undefined
+        ? rows.join("\n")
+        : [`  ${group.heading}`, ...rows].join("\n");
+    })
+    .join("\n");
+  return {
+    content: `Agents:\n  ${table.header}\n${body}`,
+    isError: false,
+  };
+}

package/src/core/agent-registry.ts

@@ -0,0 +1,282 @@
+/**
+ * AgentRegistry — the agent-identity half of CommsStore: the per-(harness, cwd) identity cache readIdentity/writeIdentity uses to recognise a restarted bridge as the same agent, and the register/get/update/list/offline lifecycle around an AgentIdentity record itself. Split out of mesh-store.ts to reduce it under the repo's max-lines cap.
+ */
+
+import { parseDisplayName } from "./display-name.js";
+import { CommsError, requireAgentName } from "./store.js";
+import type { DeliveryEngine } from "./delivery-engine.js";
+import type { MeshTransport } from "./transport.js";
+import type { ReceivedAgentSelfAdvert } from "./gossip-extensions.js";
+import { AgentStatus } from "./types.js";
+import type { AgentIdentity, Visibility } from "./types.js";
+
+/** snapshot-seconds is epoch seconds (mesh-session.ts's own `Math.floor(clock.now() / 1000)`); presenceStatusFor compares it against Date.now(), which is milliseconds. */
+const MS_PER_SECOND = 1000;
+
+/** The state and collaborators AgentRegistry needs from MeshStore. agents/identityCache are direct references into MeshStore's own fields; startedAt is a readonly value copied once; deliveryEngine is the already-constructed instance, narrowed to what agent-lifecycle bookkeeping ever needs. */
+export interface AgentRegistryDeps {
+  agents: Map<string, AgentIdentity>;
+  identityCache: Map<string, { id: string }>;
+  startedAt: string;
+  getPeerId: () => string;
+  requireTransport: () => MeshTransport;
+  /** How old a gossip-discovered device's own last-heard advert (its snapshot-seconds) may be before listDiscoverableAgents stops trusting whatever presence value it last carried and reports it offline instead (agent-comms#301). Defaults to DEFAULT_PRESENCE_STALE_AFTER_MS; MeshStore threads its own presenceStaleAfterMs constructor option through here. */
+  presenceStaleAfterMs: number;
+  deliveryEngine: Pick<
+    DeliveryEngine,
+    | "bump"
+    | "broadcastPatch"
+    | "notifyRoomsOfStatus"
+    | "notifyRoomsOfNameChange"
+  >;
+}
+
+/** Narrows an untrusted gossiped value (WireMeshTransport.listKnownDevices' own advert["agent/self"], self-asserted by whichever peer advertised it) into an AgentSelfAdvert -- a malformed or non-conforming entry is silently skipped rather than treated as an error, the same convention room-lifecycle.ts's own isHostedRoomAdvert already established for the identical class of gossip consumption. */
+function isAgentSelfAdvert(value: unknown): value is ReceivedAgentSelfAdvert {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("name" in value) || typeof value.name !== "string") return false;
+  // The name is the agent's self-asserted name, held to the rules it was registered under (requireAgentName); one parseDisplayName would not keep as it is did not come from a conforming peer and could carry a terminal control sequence.
+  if (parseDisplayName(value.name) !== value.name) return false;
+  if (!("harness" in value) || typeof value.harness !== "string") return false;
+  if ("membership" in value && typeof value.membership !== "string")
+    return false;
+  if ("machine" in value && typeof value.machine !== "string") return false;
+  if ("machineName" in value && typeof value.machineName !== "string")
+    return false;
+  if ("principalName" in value && typeof value.principalName !== "string")
+    return false;
+  if ("cwd" in value && typeof value.cwd !== "string") return false;
+  if ("pid" in value && typeof value.pid !== "number") return false;
+  if ("startedAt" in value && typeof value.startedAt !== "string") return false;
+  if ("tags" in value && !Array.isArray(value.tags)) return false;
+  if ("subscribedRooms" in value && !Array.isArray(value.subscribedRooms))
+    return false;
+  return true;
+}
+
+export class AgentRegistry {
+  constructor(private readonly deps: AgentRegistryDeps) {}
+
+  // -----------------------------------------------------------------------
+  // CommsStore — Identity
+  // -----------------------------------------------------------------------
+
+  async readIdentity(
+    harness: string,
+    cwd: string,
+  ): Promise<{ id: string } | undefined> {
+    await Promise.resolve();
+    return this.deps.identityCache.get(`${harness}--${cwd}`);
+  }
+
+  async writeIdentity(harness: string, cwd: string, id: string): Promise<void> {
+    await Promise.resolve();
+    this.deps.identityCache.set(`${harness}--${cwd}`, { id });
+  }
+
+  // -----------------------------------------------------------------------
+  // CommsStore — Agent registry
+  // -----------------------------------------------------------------------
+
+  async registerAgent(opts: {
+    name: string;
+    harness: string;
+    cwd: string;
+    pid: number;
+    visibility: Visibility;
+    tags: string[];
+  }): Promise<AgentIdentity> {
+    const name = requireAgentName(opts.name);
+    const existing = await this.readIdentity(opts.harness, opts.cwd);
+    if (existing) {
+      return this.updateAgent(existing.id, {
+        name,
+        visibility: opts.visibility,
+        tags: opts.tags,
+        status: "active",
+        pid: opts.pid,
+      });
+    }
+
+    const id = this.deps.getPeerId();
+    const agent: AgentIdentity = {
+      id,
+      version: 1,
+      name,
+      harness: opts.harness,
+      cwd: opts.cwd,
+      pid: opts.pid,
+      startedAt: this.deps.startedAt,
+      visibility: opts.visibility,
+      status: "active",
+      tags: opts.tags,
+      subscribedRooms: [],
+    };
+
+    this.deps.agents.set(id, agent);
+    await this.writeIdentity(opts.harness, opts.cwd, id);
+    await this.deps.deliveryEngine.broadcastPatch({
+      type: "agent_upsert",
+      agent,
+    });
+    return agent;
+  }
+
+  /** Resolves an agent by id, falling back to a gossip-discovered device (see listDiscoverableAgents' own doc) not otherwise locally known -- the same merge listAgents already applies to its returned array, but for a single lookup rather than the whole list. This is what lets a caller resolve a remote, hub-learned agent (agent-comms#155) that will never appear in deps.agents at all, since nothing replicates full agent records cross-machine the way a local peer's agent_upsert broadcast does. */
+  async getAgent(id: string): Promise<AgentIdentity | undefined> {
+    await Promise.resolve();
+    const known = this.deps.agents.get(id);
+    if (known !== undefined) return known;
+    const discovered = this.listDiscoverableAgents().find(
+      (candidate) => candidate.deviceId === id,
+    );
+    return discovered === undefined
+      ? undefined
+      : AgentRegistry.synthesiseDiscoveredAgent(discovered);
+  }
+
+  async updateAgent(
+    id: string,
+    patch: Partial<
+      Pick<AgentIdentity, "name" | "visibility" | "status" | "tags" | "pid">
+    >,
+  ): Promise<AgentIdentity> {
+    const agent = this.deps.agents.get(id);
+    if (!agent)
+      throw new CommsError(`Agent ${id} not found`, "AGENT_NOT_FOUND");
+
+    const name =
+      patch.name === undefined ? undefined : requireAgentName(patch.name);
+    const oldStatus = agent.status;
+    const oldName = agent.name;
+    const updatedAgent: AgentIdentity = {
+      ...agent,
+      ...patch,
+      ...(name === undefined ? {} : { name }),
+    };
+    this.deps.deliveryEngine.bump(updatedAgent);
+    this.deps.agents.set(id, updatedAgent);
+    await this.deps.deliveryEngine.broadcastPatch({
+      type: "agent_upsert",
+      agent: updatedAgent,
+    });
+
+    if (name !== undefined && name !== oldName) {
+      await this.deps.deliveryEngine.notifyRoomsOfNameChange(id, oldName, name);
+    }
+
+    if (patch.status && patch.status !== oldStatus) {
+      await this.deps.deliveryEngine.notifyRoomsOfStatus(id, patch.status);
+    }
+
+    return updatedAgent;
+  }
+
+  async listAgents(requesterId: string): Promise<AgentIdentity[]> {
+    await Promise.resolve();
+    const result: AgentIdentity[] = [];
+    for (const agent of this.deps.agents.values()) {
+      if (agent.visibility === "ghost" && agent.id !== requesterId) continue;
+      result.push(agent);
+    }
+    for (const discovered of this.listDiscoverableAgents()) {
+      if (this.deps.agents.has(discovered.deviceId)) continue;
+      result.push(AgentRegistry.synthesiseDiscoveredAgent(discovered));
+    }
+    return result;
+  }
+
+  /** Builds the placeholder-shaped AgentIdentity a gossip-discovered device (never locally registered) is represented as -- shared by listAgents' own array merge and getAgent's single-lookup fallback, so both resolve an identical shape for the identical discovered device. */
+  private static synthesiseDiscoveredAgent(discovered: {
+    deviceId: string;
+    advert: ReceivedAgentSelfAdvert;
+    status: AgentStatus | undefined;
+  }): AgentIdentity {
+    // A sender that reached this side through a hub shares only its summary, so the details it withheld stay empty here. An empty cwd is what marks an agent whose details are not shared (see detailsShared); a local agent always has one.
+    return {
+      id: discovered.deviceId,
+      version: 0,
+      name: discovered.advert.name,
+      harness: discovered.advert.harness,
+      cwd: discovered.advert.cwd ?? "",
+      pid: discovered.advert.pid ?? 0,
+      startedAt: discovered.advert.startedAt ?? "",
+      visibility: "visible",
+      status: discovered.status ?? "active",
+      tags: discovered.advert.tags ?? [],
+      subscribedRooms: discovered.advert.subscribedRooms ?? [],
+    };
+  }
+
+  /**
+   * Every agent this store has heard gossiped by another device but never registered or otherwise locally recorded -- the read half of P3.8's eventual agent register/update/offline retirement (agent-comms#48), mirroring listRooms' own room-discovery merge (#138). Never merged into this.deps.agents: a gossip hint is not the same as a real registration, and this store has nothing else authoritative to report for it. Only ever an agent that gossiped itself as "visible" (MeshStore's own selfAgentAdvert getter never advertises a hidden or ghost agent this way), so no ghost-filtering is needed here the way listAgents' own local-agent check needs.
+   *
+   * A gossip-discovered device is never told its own advert has gone stale (agent-comms#301): nothing on the hub relays a lost connection to anyone but the two peers that held it, so the only signal this side has at all is whether the device's own last advert is still recent. A device whose snapshot-seconds is older than deps.presenceStaleAfterMs is reported offline regardless of whatever presence value that stale advert carried -- trusting a heartbeat that stopped arriving minutes ago is worse than reporting the honest "we don't know" that offline actually means here.
+   */
+  private listDiscoverableAgents(): readonly {
+    deviceId: string;
+    advert: ReceivedAgentSelfAdvert;
+    status: AgentStatus | undefined;
+  }[] {
+    const transport = this.deps.requireTransport();
+    if (transport.listKnownDevices === undefined) return [];
+    const result: {
+      deviceId: string;
+      advert: ReceivedAgentSelfAdvert;
+      status: AgentStatus | undefined;
+    }[] = [];
+    const now = Date.now();
+    for (const { deviceId, advert } of transport.listKnownDevices()) {
+      const candidate = advert["agent/self"];
+      if (!isAgentSelfAdvert(candidate)) continue;
+      result.push({
+        deviceId,
+        advert: candidate,
+        status: this.presenceStatusFor(advert, now),
+      });
+    }
+    return result;
+  }
+
+  /** The status listDiscoverableAgents reports for one gossip-discovered device's own advert: offline once its snapshot-seconds is older than deps.presenceStaleAfterMs, whatever presence/status it last carried; the gossiped presence/status value when the advert is still fresh and carries one; undefined when it's fresh but never gossiped presence at all, leaving synthesiseDiscoveredAgent's own `?? "active"` to report the same "reachable, no status opinion" default this had before agent-comms#301. snapshot-seconds missing or not a finite number (an advert this malformed should not reach here in practice, since every real self-advert is signed and schema-validated before this side ever merges it, but advert itself is an untrusted `Record<string, unknown>` as far as this function's own types are concerned) leaves staleness unjudged rather than guessed at either extreme. */
+  private presenceStatusFor(
+    advert: Readonly<Record<string, unknown>>,
+    now: number,
+  ): AgentStatus | undefined {
+    const snapshotSeconds = advert["snapshot-seconds"];
+    if (
+      typeof snapshotSeconds === "number" &&
+      Number.isFinite(snapshotSeconds)
+    ) {
+      const ageMs = now - snapshotSeconds * MS_PER_SECOND;
+      if (ageMs > this.deps.presenceStaleAfterMs) return "offline";
+    }
+    const status = advert["presence/status"];
+    return AgentStatus.is(status) ? status : undefined;
+  }
+
+  async setAgentOffline(id: string): Promise<void> {
+    const agent = this.deps.agents.get(id);
+    if (!agent) return;
+    if (agent.status === "offline") return;
+
+    // Only the owning store should broadcast the status change. Other stores learn about it via the agent_offline mesh patch.
+    const isOwner = id === this.deps.getPeerId();
+    agent.status = "offline";
+    this.deps.deliveryEngine.bump(agent);
+    this.deps.agents.set(id, agent);
+
+    if (isOwner) {
+      await this.deps.deliveryEngine.notifyRoomsOfStatus(id, "offline");
+      await this.deps.deliveryEngine.broadcastPatch({
+        type: "agent_offline",
+        agentId: id,
+      });
+    }
+  }
+}
+
+/** Whether an agent's working directory, rooms and the rest were shared with this side. A gossip-discovered agent that reached us through a hub shares none of them, and is recorded with an empty cwd. */
+export function detailsShared(agent: Readonly<AgentIdentity>): boolean {
+  return agent.cwd !== "";
+}

package/src/core/agent-table.ts

@@ -0,0 +1,58 @@
+/**
+ * list_agents' aligned table (agent-comms#345). Every column but the last is as wide as its widest cell, header included, so the columns stay lined up under the header whatever the names are: a petname beside a quoted self name can be far longer than a bare registered name used to be, and a fixed width let one long name push every later column out of line.
+ */
+
+/** One agent's cells, in column order. cwd is last and so never padded. */
+export interface AgentTableRow {
+  id: string;
+  name: string;
+  harness: string;
+  status: string;
+  visibility: string;
+  cwd: string;
+}
+
+const HEADER: Readonly<AgentTableRow> = {
+  id: "ID",
+  name: "Name",
+  harness: "Harness",
+  status: "Status",
+  visibility: "Visibility",
+  cwd: "CWD",
+};
+
+/** Every column but cwd, in display order. */
+const PADDED_COLUMNS = [
+  "id",
+  "name",
+  "harness",
+  "status",
+  "visibility",
+] as const;
+
+type PaddedColumn = (typeof PADDED_COLUMNS)[number];
+
+/** Between two columns: wider than the single space inside a cell such as a petname followed by a quoted self name, so a column boundary always reads as one. */
+const COLUMN_GAP = "  ";
+
+/** The table over rows: its header line, and the line for any one of rows, each aligned against every row and the header. */
+export function agentTable(rows: readonly Readonly<AgentTableRow>[]): {
+  header: string;
+  line: (row: Readonly<AgentTableRow>) => string;
+} {
+  const widthOf = (column: PaddedColumn): number =>
+    Math.max(...[HEADER, ...rows].map((row) => row[column].length));
+  const widths: Readonly<Record<PaddedColumn, number>> = {
+    id: widthOf("id"),
+    name: widthOf("name"),
+    harness: widthOf("harness"),
+    status: widthOf("status"),
+    visibility: widthOf("visibility"),
+  };
+  const line = (row: Readonly<AgentTableRow>): string =>
+    [
+      ...PADDED_COLUMNS.map((column) => row[column].padEnd(widths[column])),
+      row.cwd,
+    ].join(COLUMN_GAP);
+  return { header: line(HEADER), line };
+}