@robota-sdk/agent-command 3.0.0-beta.79 → 3.0.0-beta.81

package/src/peers/__tests__/peers-command.test.ts

@@ -0,0 +1,241 @@
+/**
+ * PEER-004 (#1863) — `/peers` is the surface that makes local discovery observable.
+ *
+ * Discovery landed as two leaves — a guarded rendezvous directory and a registry whose liveness is
+ * settled by pid AND process start time — and measured on this tree before this command existed, no
+ * source outside those modules and their tests called either one. A discovery layer nobody can look
+ * at is one nobody can catch being wrong, so what these cases pin is the READING: what an operator
+ * is told, and in particular what they are told when the answer is "I could not determine".
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { executePeersCommand } from '../peers-command.js';
+
+import type { ICommandHostAdapterAccess, ICommandHostAdapters } from '@robota-sdk/agent-framework';
+
+type TPeerSummary = ReturnType<NonNullable<ICommandHostAdapters['localPeers']>['list']>[number];
+
+const OWN = 'session-self';
+
+function hostWithPeers(peers: readonly TPeerSummary[]): ICommandHostAdapterAccess {
+  return {
+    getCommandHostAdapters: () => ({
+      localPeers: { list: () => peers, ownSessionId: () => OWN },
+    }),
+  } as ICommandHostAdapterAccess;
+}
+
+describe('what the operator is told', () => {
+  it('lists another live session, and marks which row is this one', async () => {
+    const result = await executePeersCommand(
+      hostWithPeers([
+        { sessionId: OWN, liveness: 'alive' },
+        { sessionId: 'session-other', name: 'review', liveness: 'alive' },
+      ]),
+    );
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('session-other');
+    expect(result.message).toContain('review');
+    expect(result.message).toMatch(/session-self.*\(this session\)/);
+  });
+
+  it('says so plainly when this session is the only one', async () => {
+    // Not an empty list rendered as a header with nothing under it. "No other live session" is the
+    // answer, and it is different from "discovery is unavailable" below.
+    const result = await executePeersCommand(
+      hostWithPeers([{ sessionId: OWN, liveness: 'alive' }]),
+    );
+    expect(result.message).toContain('No other live session');
+    expect(result.success).toBe(true);
+  });
+
+  it('prints `unknown` liveness rather than rounding it to alive', async () => {
+    // A host that cannot read process start times answers `unknown` for every peer. A reader who is
+    // not told that would take a stale entry for a live session — which is the exact guess the
+    // registry refuses to make, and it must not be reintroduced by the surface that displays it.
+    const result = await executePeersCommand(
+      hostWithPeers([
+        { sessionId: OWN, liveness: 'alive' },
+        { sessionId: 'session-other', liveness: 'unknown' },
+      ]),
+    );
+    expect(result.message).toContain('liveness unknown');
+  });
+
+  it('shows observed activity and marks missing activity unknown', async () => {
+    const result = await executePeersCommand(
+      hostWithPeers([
+        { sessionId: OWN, liveness: 'alive', status: 'idle' },
+        { sessionId: 'busy', liveness: 'alive', status: 'working' },
+        { sessionId: 'waiting', liveness: 'alive', status: 'needs-input' },
+        { sessionId: 'unobserved', liveness: 'unknown', status: 'unknown' },
+      ]),
+    );
+    expect(result.message).toMatch(/busy.*working/);
+    expect(result.message).toMatch(/waiting.*needs input/);
+    expect(result.message).toMatch(/unobserved.*status unknown/);
+  });
+
+  it('shows how each peer is related by workspace (#3101 B2)', async () => {
+    const result = await executePeersCommand(
+      hostWithPeers([
+        { sessionId: OWN, liveness: 'alive', workspaceRelation: 'same-worktree' },
+        { sessionId: 'here', liveness: 'alive', workspaceRelation: 'same-worktree' },
+        { sessionId: 'sibling', liveness: 'alive', workspaceRelation: 'same-repo' },
+        { sessionId: 'elsewhere', liveness: 'alive', workspaceRelation: 'different-repo' },
+        { sessionId: 'plain', liveness: 'alive', workspaceRelation: 'unknown' },
+      ]),
+    );
+    expect(result.message).toMatch(/here.*same worktree/);
+    expect(result.message).toMatch(/sibling.*same repo/);
+    expect(result.message).toMatch(/elsewhere.*different repo/);
+    expect(result.message).toMatch(/plain.*workspace unknown/);
+  });
+
+  it('reads the workspace-judged listing when the host offers one', async () => {
+    const result = await executePeersCommand({
+      getCommandHostAdapters: () => ({
+        localPeers: {
+          list: () => [
+            { sessionId: OWN, liveness: 'alive' },
+            { sessionId: 'sibling', liveness: 'alive' },
+          ],
+          listWithWorkspace: async () => [
+            { sessionId: OWN, liveness: 'alive' },
+            { sessionId: 'sibling', liveness: 'alive', workspaceRelation: 'same-repo' },
+          ],
+          ownSessionId: () => OWN,
+        },
+      }),
+    } as ICommandHostAdapterAccess);
+    expect(result.message).toMatch(/sibling.*same repo/);
+  });
+
+  it('says a mismatched workspace claim was not believed', async () => {
+    const result = await executePeersCommand(
+      hostWithPeers([
+        { sessionId: OWN, liveness: 'alive' },
+        {
+          sessionId: 'liar',
+          liveness: 'alive',
+          workspaceRelation: 'unknown',
+          workspaceClaim: 'mismatched',
+        },
+      ]),
+    );
+    expect(result.message).toMatch(/liar.*workspace claim mismatched, not believed/);
+    expect(result.message).not.toMatch(/liar.*same (worktree|repo)/);
+  });
+
+  it('does not show a dead entry', async () => {
+    // A crashed session leaves its file behind. That is debris, not a peer, and offering it as one
+    // would make the operator address something that cannot answer.
+    const result = await executePeersCommand(
+      hostWithPeers([
+        { sessionId: OWN, liveness: 'alive' },
+        { sessionId: 'session-gone', liveness: 'dead' },
+      ]),
+    );
+    expect(result.message).not.toContain('session-gone');
+    expect(result.message).toContain('No other live session');
+  });
+});
+
+describe('when the host wires no discovery', () => {
+  it('says the feature is unavailable rather than reporting no peers', async () => {
+    // The two are different facts and the difference matters: "nobody is there" invites the operator
+    // to start a second session, and "this build cannot see them" does not.
+    const result = await executePeersCommand({
+      getCommandHostAdapters: () => ({}),
+    } as ICommandHostAdapterAccess);
+    expect(result.message).toContain('not available');
+    expect(result.message).not.toContain('No other live session');
+  });
+});
+
+describe('PEER-006 — /peers send', () => {
+  function hostWithSend(
+    send: (target: string, text: string) => Promise<{ state: string; reason?: string }>,
+  ): ICommandHostAdapterAccess {
+    return {
+      getCommandHostAdapters: () => ({
+        localPeers: {
+          list: () => [{ sessionId: 'other', liveness: 'alive' as const }],
+          ownSessionId: () => OWN,
+          send,
+        },
+      }),
+    } as unknown as ICommandHostAdapterAccess;
+  }
+
+  it('passes the whole message, not just its first word', async () => {
+    const calls: Array<[string, string]> = [];
+    await executePeersCommand(
+      hostWithSend(async (target, text) => {
+        calls.push([target, text]);
+        return { state: 'acknowledged' };
+      }),
+      'send other look at the failing test in cli.ts',
+    );
+
+    expect(calls).toEqual([['other', 'look at the failing test in cli.ts']]);
+  });
+
+  it('reports `pending` as waiting, never as delivered', async () => {
+    const result = await executePeersCommand(
+      hostWithSend(async () => ({ state: 'pending' })),
+      'send other hello',
+    );
+
+    // The operator has to be able to see the wait. "Delivered" here would hide a turn already
+    // running on the other side, which is the one thing they might want to act on.
+    expect(result.message).toContain('waiting');
+    expect(result.message).not.toContain('Delivered');
+    expect(result.success).toBe(true);
+  });
+
+  it('carries the refusal reason back to the operator', async () => {
+    const result = await executePeersCommand(
+      hostWithSend(async () => ({ state: 'refused', reason: 'no session ghost is announced' })),
+      'send ghost hello',
+    );
+
+    expect(result.message).toContain('no session ghost is announced');
+    expect(result.success).toBe(false);
+  });
+
+  it('explains what it needs when the message is missing', async () => {
+    const result = await executePeersCommand(
+      hostWithSend(async () => ({ state: 'acknowledged' })),
+      'send other',
+    );
+
+    expect(result.message).toContain('Usage: /peers send');
+    expect(result.success).toBe(false);
+  });
+
+  it('does not read a session id beginning with `send` as the subcommand', async () => {
+    // `startsWith('send')` would claim this as `/peers send`, leaving `er-1` as the target.
+    const result = await executePeersCommand(
+      hostWithSend(async () => ({ state: 'acknowledged' })),
+      'sender-1',
+    );
+
+    expect(result.message).toContain('Live sessions:');
+  });
+
+  it('says so when the host can discover peers but not address them', async () => {
+    const result = await executePeersCommand(
+      {
+        getCommandHostAdapters: () => ({
+          localPeers: { list: () => [], ownSessionId: () => OWN },
+        }),
+      } as ICommandHostAdapterAccess,
+      'send other hello',
+    );
+
+    expect(result.message).toContain('cannot address them');
+    expect(result.success).toBe(false);
+  });
+});

package/src/peers/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Only the module factory leaves this directory.
+ *
+ * `executePeersCommand`, `PeersCommandSource` and `createPeersCommandEntry` are how the module is
+ * BUILT, not how it is used: the command is registered by default, so nothing outside constructs one.
+ * Exporting them would have added four entries to this package's frozen undocumented-surface count —
+ * debt that may shrink and never grow — in exchange for a reach nobody asked for.
+ */
+export { createPeersCommandModule } from './peers-command-module.js';

package/src/peers/peers-command-module.ts

@@ -0,0 +1,47 @@
+import { executePeersCommand } from './peers-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createPeersCommandEntry(): ICommand {
+  return {
+    name: 'peers',
+    displayName: 'Peers',
+    description: 'List the other live sessions on this host, or send one a message',
+    source: 'peers',
+    // The model does not enumerate the operator's other sessions. Discovery is an operator-facing
+    // view of who is at the machine, which is a fact about the person and not about the task.
+    // User-only: sends messages into other sessions; crossing a session boundary is the user's call.
+    modelInvocable: false,
+  };
+}
+
+function createPeersSystemCommand(): ISystemCommand {
+  const entry = createPeersCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: (context, args) => executePeersCommand(context, args),
+  };
+}
+
+export class PeersCommandSource implements ICommandSource {
+  readonly name = 'peers';
+
+  getCommands(): ICommand[] {
+    return [createPeersCommandEntry()];
+  }
+}
+
+export function createPeersCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-peers',
+    commandSources: [new PeersCommandSource()],
+    systemCommands: [createPeersSystemCommand()],
+  };
+}

package/src/peers/peers-command.ts

@@ -0,0 +1,142 @@
+import type { ICommandHostAdapterAccess, ICommandHostAdapters } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+/** One row as the port hands it over. Derived, so it cannot drift from the adapter it reads. */
+type TPeerSummary = ReturnType<NonNullable<ICommandHostAdapters['localPeers']>['list']>[number];
+
+/**
+ * `/peers` (PEER-004, #1863) — which other live sessions this one can address.
+ *
+ * Discovery landed as a leaf (a guarded rendezvous directory, an entry per live session, liveness
+ * settled by pid AND process start time) and nothing called it: measured on this tree, no file
+ * outside the module and its tests referenced `announcePeer` or `openLocalPeerRendezvous`. This
+ * command is the surface that makes it observable, which is also what makes it falsifiable — a
+ * discovery layer nobody can look at is one nobody can catch being wrong.
+ *
+ * The command reads an injected adapter and touches no filesystem, for the same reason it never
+ * constructs a transport: the guarded directory, its permissions and the liveness rule are
+ * composition-root concerns and must have one owner.
+ */
+
+/** `dead` is not shown. An entry whose process is gone is debris, not a peer. */
+function addressable(peer: TPeerSummary): boolean {
+  return peer.liveness !== 'dead';
+}
+
+function describe(peer: TPeerSummary, ownSessionId: string): string {
+  const self = peer.sessionId === ownSessionId ? '  (this session)' : '';
+  // `unknown` is printed, never rounded to `alive`. A host that cannot read process start times
+  // answers `unknown` for every peer, and a reader who is not told that would take a stale entry for
+  // a live session.
+  const liveness = peer.liveness === 'unknown' ? '  liveness unknown' : '';
+  const status = peer.status === 'needs-input' ? 'needs input' : (peer.status ?? 'unknown');
+  return `  ${peer.sessionId}${peer.name ? `  ${peer.name}` : ''}  status ${status}${self ? '' : workspace(peer)}${liveness}${self}`;
+}
+
+/** The relation this session verified. A claim it could not confirm is named as such, not shown. */
+function workspace(peer: TPeerSummary): string {
+  if (peer.workspaceClaim === 'mismatched') return '  workspace claim mismatched, not believed';
+  switch (peer.workspaceRelation) {
+    case undefined:
+      return '';
+    case 'unknown':
+      return '  workspace unknown';
+    default:
+      return `  ${peer.workspaceRelation.replace('-', ' ')}`;
+  }
+}
+
+/**
+ * PEER-006 — `/peers send <session-id> <text>`.
+ *
+ * Split on the FIRST run of whitespace only: everything after the session id is the message, spaces
+ * and all. Splitting on every space would silently truncate any message with more than one word,
+ * which is nearly all of them.
+ */
+function parseSend(args: string): { target: string; text: string } | undefined {
+  const trimmed = args.trim();
+  const at = trimmed.search(/\s/);
+  if (at === -1) return undefined;
+  const text = trimmed.slice(at).trim();
+  if (text === '') return undefined;
+  return { target: trimmed.slice(0, at), text };
+}
+
+/** A state the sender can act on, rendered as a sentence rather than a status word. */
+function describeSend(result: { state: string; reason?: string }, target: string): ICommandResult {
+  const reason = result.reason !== undefined ? ` ${result.reason}` : '';
+  switch (result.state) {
+    case 'acknowledged':
+    case 'delivered':
+      return { message: `Delivered to ${target}.`, success: true };
+    case 'pending':
+      // NOT reported as delivered. The peer has it and has not run it — usually because a turn is
+      // already running there — and telling the operator it landed would hide a wait they can see.
+      return {
+        message: `${target} has the message; it is waiting behind work already running there.`,
+        success: true,
+      };
+    case 'duplicate':
+      return { message: `${target} had already seen that message.`, success: true };
+    default:
+      return { message: `Not delivered to ${target}.${reason}`, success: false };
+  }
+}
+
+async function executeSend(
+  adapter: NonNullable<ICommandHostAdapters['localPeers']>,
+  args: string,
+): Promise<ICommandResult> {
+  if (adapter.send === undefined) {
+    return {
+      message: 'This environment can discover other sessions but cannot address them.',
+      success: false,
+    };
+  }
+  const parsed = parseSend(args);
+  if (parsed === undefined) {
+    return {
+      message: 'Usage: /peers send <session-id> <message>. Run /peers for the session ids.',
+      success: false,
+    };
+  }
+  return describeSend(await adapter.send(parsed.target, parsed.text), parsed.target);
+}
+
+export async function executePeersCommand(
+  context: ICommandHostAdapterAccess,
+  args = '',
+): Promise<ICommandResult> {
+  const adapter = context.getCommandHostAdapters?.().localPeers;
+  if (!adapter) {
+    return { message: 'Local peer discovery is not available in this environment.', success: true };
+  }
+
+  // `send` must be a WHOLE word: `startsWith('send')` would also claim a session id beginning with
+  // those four letters, and a uuid that happens to start `send…` is not a subcommand.
+  const trimmed = args.trim();
+  const sendVerb = /^send(?=\s|$)/.exec(trimmed);
+  if (sendVerb !== null) return executeSend(adapter, trimmed.slice(sendVerb[0].length));
+
+  const own = adapter.ownSessionId();
+  // The workspace-judged listing when the host has one; it reads git, so only this view asks for it.
+  const peers = (
+    adapter.listWithWorkspace !== undefined ? await adapter.listWithWorkspace() : adapter.list()
+  ).filter(addressable);
+  const others = peers.filter((peer) => peer.sessionId !== own);
+
+  if (others.length === 0) {
+    return {
+      message:
+        'No other live session is announced. Start a second session on this host, as this user, ' +
+        'and it appears here.',
+      success: true,
+    };
+  }
+
+  const lines = peers.map((peer) => describe(peer, own));
+  return {
+    message: `Live sessions:\n${lines.join('\n')}\n\nSend to one: /peers send <session-id> <message>`,
+    success: true,
+  };
+}