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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robota-sdk/agent-command",
-  "version": "3.0.0-beta.81",
+  "version": "3.0.0-beta.82",
   "description": "Consolidated command module implementations for Robota SDK CLI",
   "type": "module",
   "main": "dist/node/index.js",
@@ -35,12 +35,12 @@
     "src"
   ],
   "dependencies": {
-    "@robota-sdk/agent-core": "3.0.0-beta.81",
-    "@robota-sdk/agent-framework": "3.0.0-beta.81",
-    "@robota-sdk/agent-interface-execution": "3.0.0-beta.81",
-    "@robota-sdk/agent-interface-command": "3.0.0-beta.81",
-    "@robota-sdk/agent-preset": "3.0.0-beta.81",
-    "@robota-sdk/agent-interface-session": "3.0.0-beta.81"
+    "@robota-sdk/agent-core": "3.0.0-beta.82",
+    "@robota-sdk/agent-framework": "3.0.0-beta.82",
+    "@robota-sdk/agent-interface-command": "3.0.0-beta.82",
+    "@robota-sdk/agent-interface-execution": "3.0.0-beta.82",
+    "@robota-sdk/agent-interface-session": "3.0.0-beta.82",
+    "@robota-sdk/agent-preset": "3.0.0-beta.82"
   },
   "devDependencies": {
     "@types/node": "^22.19.21",
@@ -50,6 +50,11 @@
     "vitest": "^3.2.6"
   },
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/woojubb/robota.git",
+    "directory": "packages/agent-command"
+  },
   "publishConfig": {
     "access": "public"
   },

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

@@ -195,7 +195,7 @@ export async function executeDevicesCommand(
     case 'join':
       return {
         success: false,
-        message: `\`/devices ${verb}\` is not available yet: enrolling another device needs the device connection, which is not built yet.`,
+        message: `\`/devices ${verb}\` is not available yet: enrolling another device over the device connection is not built yet.`,
       };
     default:
       return { success: false, message: `Unknown argument "${verb}". ${USAGE}` };

package/src/handoff/__tests__/handoff-command-module.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+
+import { createHandoffCommandModule } from '../handoff-command-module.js';
+
+describe('/handoff command module', () => {
+  it('is user-only: never model-invocable, and palette metadata matches the executable', () => {
+    const module = createHandoffCommandModule();
+    const palette = module.commandSources?.[0]?.getCommands()[0];
+    const executable = module.systemCommands?.[0];
+    expect(executable?.modelInvocable).toBe(false);
+    expect(palette?.modelInvocable).toBe(false);
+    expect(executable?.userInvocable).toBe(true);
+    expect(palette?.userInvocable).toBe(true);
+    expect(executable?.description).toBe(palette?.description);
+  });
+
+  it('tells the model what it does and which command to suggest, since it cannot run it', () => {
+    const description =
+      createHandoffCommandModule().commandSources?.[0]?.getCommands()[0]?.description;
+    expect(description).toContain('/handoff <session-id>');
+    expect(description).toMatch(/user-only/i);
+    expect(description).toContain('saved, not started');
+  });
+});

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

@@ -138,8 +138,8 @@ describe('every outcome says where the session is now', () => {
     const result = await executeHandoffCommand(context, 'laptop');
 
     expect(result.success).toBe(true);
-    expect(result.message).toContain('laptop is running this session now');
-    expect(result.message).toContain('read-only');
+    expect(result.message).toContain('laptop saved this session and has not started it');
+    expect(result.message).toContain('this one ends');
   });
 
   it('says the session is still here when the transfer stops, and why', async () => {
@@ -155,7 +155,7 @@ describe('every outcome says where the session is now', () => {
     expect(result.success).toBe(false);
     expect(result.message).toContain('no provider credential');
     expect(result.message).toContain('still on this machine');
-    expect(result.message).not.toContain('read-only');
+    expect(result.message).not.toContain('this one ends');
   });
 
   it('names the waiting phase as safe to leave, since that is when it looks stuck', async () => {

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

@@ -7,13 +7,14 @@ export function createHandoffCommandEntry(): ICommand {
   return {
     name: 'handoff',
     displayName: 'Hand off',
-    description: 'Move this session to another machine, after confirming what stays behind',
+    description:
+      'Push this conversation to another running Robota session of the same user on this machine, after the operator confirms what stays behind (uncommitted changes, running processes; credentials never travel). The receiving operator must also accept; the session arrives saved, not started, and this one ends once it is saved there. With no argument it lists the sessions it could go to. User-only: the model cannot run it; when the user wants to continue this work in another session, suggest they run `/handoff <session-id>`.',
     source: 'handoff',
-    // The model does not decide to give this session away. A hand-off moves AUTHORITY over the
-    // operator's work to a different computer — it is a decision about where the person is sitting,
-    // which is a fact about them and not about the task.
-    // User-only: moves the session to another machine; the user decides where it lives.
+    // User-only: a hand-off moves authority over the operator's work to another place, a decision
+    // about where the person is, not about the task.
     modelInvocable: false,
+    userInvocable: true,
+    argumentHint: '[session-id]',
   };
 }
 

package/src/handoff/handoff-command.ts

@@ -33,7 +33,7 @@ type THandoffHost = ICommandHostAdapterAccess & Partial<ICommandHostUserInteract
 function whereIsIt(progress: IHandoffProgress): string {
   return progress.stillMine
     ? 'This session is still on this machine, and still yours to use.'
-    : 'This session now belongs to the destination. This copy is read-only.';
+    : 'This session now belongs to the destination, and this one ends.';
 }
 
 function describeDestinations(
@@ -47,8 +47,8 @@ function usage(): ICommandResult {
     success: true,
     message: [
       'Usage:',
-      '  /handoff              list the machines this session could move to',
-      '  /handoff <device-id>  move it there, after confirming what stays behind',
+      '  /handoff               list where this session could move to',
+      '  /handoff <session-id>  move it there, after confirming what stays behind',
     ].join('\n'),
   };
 }
@@ -153,7 +153,7 @@ export async function executeHandoffCommand(
     message: [
       ...progressLines,
       final.state === 'done'
-        ? `Hand-off complete. ${target} is running this session now.`
+        ? `Hand-off complete. ${target} saved this session and has not started it; resume it there.`
         : `Hand-off stopped: ${final.reason ?? 'no reason was reported'}.`,
       whereIsIt(final),
     ].join('\n'),

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

@@ -239,3 +239,83 @@ describe('PEER-006 — /peers send', () => {
     expect(result.success).toBe(false);
   });
 });
+
+describe('/peers send-file', () => {
+  type TPrepareFile = NonNullable<NonNullable<ICommandHostAdapters['localPeers']>['prepareFile']>;
+
+  function hostWithFiles(prepareFile: TPrepareFile): ICommandHostAdapterAccess {
+    return {
+      getCwd: () => '/work',
+      getCommandHostAdapters: () => ({
+        localPeers: {
+          list: () => [{ sessionId: 'other', liveness: 'alive' as const }],
+          ownSessionId: () => OWN,
+          prepareFile,
+        },
+      }),
+    } as unknown as ICommandHostAdapterAccess;
+  }
+
+  it('sends the named file as the operator, spaces in the path and all', async () => {
+    const calls: unknown[] = [];
+    const result = await executePeersCommand(
+      hostWithFiles(async (target, path, options) => {
+        calls.push([target, path, options]);
+        return {
+          ok: true,
+          file: {
+            path: '/work/my notes.txt',
+            size: 5,
+            sha256: 'e'.repeat(64),
+            send: async () => ({ state: 'delivered' }),
+          },
+        };
+      }),
+      'send-file other my notes.txt',
+    );
+
+    expect(calls).toEqual([['other', 'my notes.txt', { origin: 'operator', cwd: '/work' }]]);
+    expect(result.success).toBe(true);
+    expect(result.message).toContain(`5 bytes, sha256 ${'e'.repeat(64)}`);
+  });
+
+  it('carries a refusal back to the operator', async () => {
+    const result = await executePeersCommand(
+      hostWithFiles(async () => ({
+        ok: true,
+        file: {
+          path: '/work/a.txt',
+          size: 1,
+          sha256: 'e'.repeat(64),
+          send: async () => ({ state: 'refused', reason: 'the receiving side did not accept it' }),
+        },
+      })),
+      'send-file other a.txt',
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('did not accept it');
+  });
+
+  it('says what it needs when the path is missing', async () => {
+    const result = await executePeersCommand(
+      hostWithFiles(async () => ({ ok: false, reason: 'unused' })),
+      'send-file other',
+    );
+    expect(result.message).toContain('Usage: /peers send-file');
+    expect(result.success).toBe(false);
+  });
+
+  it('says so when the host cannot send files', async () => {
+    const result = await executePeersCommand(
+      {
+        getCommandHostAdapters: () => ({
+          localPeers: { list: () => [], ownSessionId: () => OWN },
+        }),
+      } as ICommandHostAdapterAccess,
+      'send-file other a.txt',
+    );
+    expect(result.message).toContain('cannot send files');
+    expect(result.success).toBe(false);
+  });
+});

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

@@ -7,11 +7,13 @@ export function createPeersCommandEntry(): ICommand {
   return {
     name: 'peers',
     displayName: 'Peers',
-    description: 'List the other live sessions on this host, or send one a message',
+    description:
+      'List the other live sessions on this host, send one a message, or send one a copy of a file',
     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.
+    // User-only: sends messages and files into other sessions; crossing a session boundary is the
+    // user's call. The model sends a file only through `peer_send_file`, which asks every time.
     modelInvocable: false,
   };
 }

package/src/peers/peers-command.ts

@@ -103,8 +103,47 @@ async function executeSend(
   return describeSend(await adapter.send(parsed.target, parsed.text), parsed.target);
 }
 
+/**
+ * `/peers send-file <session-id> <path>` — the operator sends a copy of a file.
+ *
+ * The operator typed the path, so any regular file they can read may go, including one outside the
+ * workspace or one that looks like it holds secrets: this is the one way to send those. Everything
+ * after the session id is the path, spaces and all.
+ */
+async function executeSendFile(
+  adapter: NonNullable<ICommandHostAdapters['localPeers']>,
+  args: string,
+  cwd: string,
+): Promise<ICommandResult> {
+  if (adapter.prepareFile === undefined) {
+    return { message: 'This environment cannot send files to other sessions.', success: false };
+  }
+  const parsed = parseSend(args);
+  if (parsed === undefined) {
+    return {
+      message: 'Usage: /peers send-file <session-id> <path>. Run /peers for the session ids.',
+      success: false,
+    };
+  }
+  const prepared = await adapter.prepareFile(parsed.target, parsed.text, {
+    origin: 'operator',
+    cwd,
+  });
+  if (!prepared.ok) return { message: `Not sent: ${prepared.reason}`, success: false };
+  const { file } = prepared;
+  const result = await file.send();
+  if (result.state === 'delivered' || result.state === 'acknowledged') {
+    return {
+      message: `Sent ${file.path} to ${parsed.target}: ${file.size} bytes, sha256 ${file.sha256}.`,
+      success: true,
+    };
+  }
+  const reason = result.reason !== undefined ? ` ${result.reason}` : '';
+  return { message: `${file.path} was not sent to ${parsed.target}.${reason}`, success: false };
+}
+
 export async function executePeersCommand(
-  context: ICommandHostAdapterAccess,
+  context: ICommandHostAdapterAccess & { getCwd?(): string },
   args = '',
 ): Promise<ICommandResult> {
   const adapter = context.getCommandHostAdapters?.().localPeers;
@@ -115,6 +154,14 @@ export async function executePeersCommand(
   // `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 sendFileVerb = /^send-file(?=\s|$)/.exec(trimmed);
+  if (sendFileVerb !== null) {
+    return executeSendFile(
+      adapter,
+      trimmed.slice(sendFileVerb[0].length),
+      context.getCwd?.() ?? '',
+    );
+  }
   const sendVerb = /^send(?=\s|$)/.exec(trimmed);
   if (sendVerb !== null) return executeSend(adapter, trimmed.slice(sendVerb[0].length));
 
@@ -136,7 +183,9 @@ export async function executePeersCommand(
 
   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>`,
+    message:
+      `Live sessions:\n${lines.join('\n')}\n\nSend to one: /peers send <session-id> <message>` +
+      '\nSend a file: /peers send-file <session-id> <path>',
     success: true,
   };
 }