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

package/src/effort/effort-command.ts

@@ -1,5 +1,5 @@
 import { MODEL_EFFORT_VALUES, selectAction } from '@robota-sdk/agent-core';
-import { parseModelEffort, resolveModelEffort } from '@robota-sdk/agent-framework';
+import { EFFORT_LEVEL_LABELS, parseModelEffort, resolveModelEffort } from '@robota-sdk/agent-framework';
 
 import type {
   ICommandHostAdapterAccess,
@@ -14,13 +14,27 @@ import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 
 const EFFORT_SELECTIONS: readonly TEffortSelection[] = ['auto', ...MODEL_EFFORT_VALUES];
 
+/**
+ * #3282 §2 — re-exported for callers already importing it from here; the canonical definition moved
+ * to `agent-framework` (`effort/effort-resolution.ts`) so headless `/goal` output (in that same
+ * package) can use the same labels without a circular dependency on `agent-command`.
+ */
+export { EFFORT_LEVEL_LABELS };
+
+/**
+ * Plain outcome text (#3282 §2), replacing the earlier `Model effort: requested=…, effective=…,
+ * source=…, disposition=…` internal-field dump. `not-applied` means the model has no matching native
+ * control at all — the earlier fields carried no information a person could act on for that case, so
+ * it gets its own plain sentence instead of a label.
+ */
 function formatEffortMessage(resolution: {
   requested: TEffortSelection;
-  effective: string;
-  source: string;
   disposition: string;
 }): string {
-  return `Model effort: requested=${resolution.requested}, effective=${resolution.effective}, source=${resolution.source}, disposition=${resolution.disposition}.`;
+  if (resolution.disposition === 'not-applied') {
+    return "This model doesn't support effort levels, so it will use its default.";
+  }
+  return `Effort: ${EFFORT_LEVEL_LABELS[resolution.requested]}`;
 }
 
 async function askForEffort(
@@ -32,7 +46,7 @@ async function askForEffort(
     selectAction(
       'effort',
       'Select model effort',
-      EFFORT_SELECTIONS.map((value) => ({ value, label: value })),
+      EFFORT_SELECTIONS.map((value) => ({ value, label: EFFORT_LEVEL_LABELS[value] })),
     ),
   );
   const selected = response.type === 'answer' ? response.values[0] : undefined;

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

@@ -0,0 +1,73 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { executeEventsCommand } from '../events-command.js';
+import { createEventsCommandModule } from '../events-command-module.js';
+
+import type { ICommandExternalEventsAdapter } from '@robota-sdk/agent-framework';
+
+function adapter(): ICommandExternalEventsAdapter & { revoke: ReturnType<typeof vi.fn> } {
+  return {
+    list: () => [
+      {
+        grantId: 'ci',
+        principal: 'client',
+        state: 'open',
+        counters: { accepted: 2, refused: { expired: 1 }, settled: { completed: 2 } },
+      },
+    ],
+    revoke: vi.fn((grantId: string) => (grantId === 'ci' ? 'revoked' : 'unknown-grant')),
+  };
+}
+
+const context = (externalEvents?: ICommandExternalEventsAdapter) => ({
+  getCommandHostAdapters: () => (externalEvents ? { externalEvents } : {}),
+});
+
+describe('/events command module', () => {
+  it('is user-only: never model-invocable, and palette metadata matches the executable', () => {
+    const module = createEventsCommandModule();
+    const palette = module.commandSources?.[0]?.getCommands()[0];
+    const executable = module.systemCommands?.[0];
+    expect(palette?.name).toBe('events');
+    expect(executable?.modelInvocable).toBe(false);
+    expect(palette?.modelInvocable).toBe(false);
+    expect(executable?.userInvocable).toBe(true);
+    expect(executable?.description).toBe(palette?.description);
+  });
+
+  it('tells the model what it does, what it returns, that it is user-only, and what to suggest', () => {
+    const description =
+      createEventsCommandModule().commandSources?.[0]?.getCommands()[0]?.description;
+    expect(description).toMatch(/external event grants/i);
+    expect(description).toMatch(/returns/i);
+    expect(description).toMatch(/user-only/i);
+    expect(description).toContain('`/events revoke <grant-id>`');
+  });
+});
+
+describe('/events', () => {
+  it('lists grants with their principal kind and counts', async () => {
+    const result = await executeEventsCommand(context(adapter()), '');
+    expect(result.success).toBe(true);
+    expect(result.message).toContain(
+      'ci  client  open  accepted 2; refused: expired 1; settled: completed 2',
+    );
+  });
+
+  it('revokes one grant by label and says when the label is unknown', async () => {
+    const events = adapter();
+    expect((await executeEventsCommand(context(events), 'revoke ci')).message).toMatch(
+      /Revoked external event grant ci/,
+    );
+    expect(events.revoke).toHaveBeenCalledWith('ci');
+    const unknown = await executeEventsCommand(context(events), 'revoke nope');
+    expect(unknown.success).toBe(false);
+    expect(unknown.message).toMatch(/no external event grant nope/);
+    expect((await executeEventsCommand(context(events), 'revoke')).success).toBe(false);
+  });
+
+  it('says how grants are given when the session holds none', async () => {
+    const result = await executeEventsCommand(context(), '');
+    expect(result.message).toMatch(/only when a session starts/);
+  });
+});

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

@@ -0,0 +1,49 @@
+import { executeEventsCommand } from './events-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createEventsCommandEntry(): ICommand {
+  return {
+    name: 'events',
+    displayName: 'Events',
+    description:
+      "List this session's external event grants (each grant's label, whether it pins a subject or a client, whether it is open or revoked, and its counts of accepted, refused and settled events), or revoke one with `/events revoke <grant-id>`. Returns the grants, or whether the revocation took effect. User-only: the model cannot run it; when the user wants to stop events from outside, suggest `/events revoke <grant-id>`.",
+    source: 'events',
+    argumentHint: '[revoke <grant-id>]',
+    // User-only: a grant is the owner's standing decision that someone outside may put turns into
+    // this session. Withdrawing it is the owner's call too, and listing it lives on the same command.
+    modelInvocable: false,
+  };
+}
+
+function createEventsSystemCommand(): ISystemCommand {
+  const entry = createEventsCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    ...(entry.argumentHint !== undefined ? { argumentHint: entry.argumentHint } : {}),
+    lifecycle: 'inline',
+    execute: (context, args) => executeEventsCommand(context, args),
+  };
+}
+
+export class EventsCommandSource implements ICommandSource {
+  readonly name = 'events';
+
+  getCommands(): ICommand[] {
+    return [createEventsCommandEntry()];
+  }
+}
+
+export function createEventsCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-events',
+    commandSources: [new EventsCommandSource()],
+    systemCommands: [createEventsSystemCommand()],
+  };
+}

package/src/events/events-command.ts

@@ -0,0 +1,69 @@
+import type {
+  ICommandExternalEventGrant,
+  ICommandHostAdapterAccess,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+const GRANT_ID = /^[a-zA-Z0-9_-]{1,64}$/u;
+
+function counts(values: Readonly<Partial<Record<string, number>>>): string {
+  const entries = Object.entries(values).filter(([, count]) => (count ?? 0) > 0);
+  return entries.length === 0
+    ? 'none'
+    : entries.map(([key, count]) => `${key} ${count}`).join(', ');
+}
+
+/** Label, principal kind, state and counts. The principal itself is never shown. */
+function describe(grant: ICommandExternalEventGrant): string {
+  const { counters } = grant;
+  return (
+    `  ${grant.grantId}  ${grant.principal}  ${grant.state}  accepted ${counters.accepted}; ` +
+    `refused: ${counts(counters.refused)}; settled: ${counts(counters.settled)}`
+  );
+}
+
+/**
+ * `/events` — this session's external-event grants, and `/events revoke <grant-id>` to withdraw one.
+ * Grants are given only when the session starts; nothing here creates one.
+ */
+export async function executeEventsCommand(
+  context: ICommandHostAdapterAccess,
+  args = '',
+): Promise<ICommandResult> {
+  const adapter = context.getCommandHostAdapters?.().externalEvents;
+  if (!adapter) {
+    return {
+      message:
+        'This session holds no external event grant. Grants are given only when a session starts.',
+      success: true,
+    };
+  }
+  const [verb, grantId, extra] = args
+    .trim()
+    .split(/\s+/u)
+    .filter((word) => word !== '');
+  if (verb === undefined) {
+    const grants = adapter.list();
+    return {
+      message:
+        grants.length === 0
+          ? 'This session holds no external event grant.'
+          : `External event grants:\n${grants.map(describe).join('\n')}\n\nWithdraw one: /events revoke <grant-id>`,
+      success: true,
+    };
+  }
+  if (
+    verb !== 'revoke' ||
+    grantId === undefined ||
+    extra !== undefined ||
+    !GRANT_ID.test(grantId)
+  ) {
+    return { message: 'Usage: /events  |  /events revoke <grant-id>', success: false };
+  }
+  return adapter.revoke(grantId) === 'revoked'
+    ? {
+        message: `Revoked external event grant ${grantId}. Later events for it are refused.`,
+        success: true,
+      }
+    : { message: `This session holds no external event grant ${grantId}.`, success: false };
+}

package/src/events/index.ts

@@ -0,0 +1,2 @@
+/** Only the module factory leaves this directory; the command is registered by default. */
+export { createEventsCommandModule } from './events-command-module.js';

package/src/git/__tests__/fake-git-port.ts

@@ -1,5 +1,12 @@
-/** A scripted `IGitProcessPort`: answers by argv, records every call, throws on an unscripted one. */
-import type { IGitProcessPort, TGitProcessOutcome } from '../git-process.js';
+/**
+ * A scripted `IGitProcessPort`: answers by argv, records every call, throws on an unscripted one.
+ *
+ * The port and outcome types moved to `@robota-sdk/agent-framework` with the git process module
+ * (#3282 §4c); this double stays here (duplicated, not imported cross-package) because it is a tiny,
+ * self-contained test fixture, the same call `agent-framework`'s own `git/__tests__/fake-git-port.ts`
+ * makes for its side.
+ */
+import type { IGitProcessPort, TGitProcessOutcome } from '@robota-sdk/agent-framework';
 
 export interface IFakeGitPort extends IGitProcessPort {
   readonly calls: readonly (readonly string[])[];

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

@@ -1,5 +1,9 @@
 /** BEHAVIOR-2437 TC-05 — registration, the descriptor, and the verb parse through the real session. */
-import { afterEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, afterEach, describe, expect, it } from 'vitest';
 
 import { scriptedSession, type ScriptedSessionHarness } from '@robota-sdk/agent-framework/testing';
 
@@ -35,7 +39,11 @@ const providerSettingsAdapter: IProviderCommandSettingsAdapter = {
   readTargetSettings: () => ({}) as TProviderSettingsDocument,
   writeTargetSettings: () => undefined,
 };
-const BASE_OPTIONS = { cwd: '/tmp', userLocalStorageRoot: '/tmp/robota-test', providerDefinitions, providerSettingsAdapter } as const;
+/** User-local storage lives in a private per-run directory, never a fixed name under /tmp. */
+const USER_LOCAL_STORAGE_ROOT = mkdtempSync(join(tmpdir(), 'robota-test-'));
+afterAll(() => rmSync(USER_LOCAL_STORAGE_ROOT, { recursive: true, force: true }));
+
+const BASE_OPTIONS = { cwd: '/tmp', userLocalStorageRoot: USER_LOCAL_STORAGE_ROOT, providerDefinitions, providerSettingsAdapter } as const;
 
 const STATUS_FIXTURE = '# branch.head main\0? scratch.log\0';
 

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

@@ -5,15 +5,14 @@
  * on the user path (`SystemCommandExecutor.executeCommand` calls `execute` directly).
  */
 import { executeGitCommit } from './git-commit.js';
-import { executeGitDiff } from './git-diff.js';
-import { createGitProcess } from './git-process.js';
-import { executeGitStatus } from './git-status.js';
 
-import type { IGitProcessPort } from './git-process.js';
+import { createGitProcess, executeGitDiff, executeGitStatus } from '@robota-sdk/agent-framework';
+
 import type {
   ICommandHostUserInteraction,
   ICommandHostWorkspace,
   ICommandModule,
+  IGitProcessPort,
   ISystemCommand,
 } from '@robota-sdk/agent-framework';
 import type { ICommand, ICommandResult, ICommandSource } from '@robota-sdk/agent-interface-command';

package/src/git/git-commit.ts

@@ -9,10 +9,13 @@
  */
 import { confirmAction, isConfirmed, textAction } from '@robota-sdk/agent-core';
 
-import { gitFailureMessage } from './git-process.js';
-import { parseStatusPorcelainV2, GIT_STATUS_ARGS } from './git-status.js';
+import {
+  gitFailureMessage,
+  parseStatusPorcelainV2,
+  GIT_STATUS_ARGS,
+} from '@robota-sdk/agent-framework';
 
-import type { IGitProcessPort } from './git-process.js';
+import type { IGitProcessPort } from '@robota-sdk/agent-framework';
 import type { IUserInteraction } from '@robota-sdk/agent-core';
 import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 

package/src/git/index.ts

@@ -1,3 +1,6 @@
+// The git process port and the status/diff readers moved to `@robota-sdk/agent-framework` (#3282
+// §4c) so the Project panel's session-level reads and this command run through the exact same
+// functions; re-exported here so an existing `from '@robota-sdk/agent-command'` import keeps working.
 export {
   createGitProcess,
   gitEnvironment,
@@ -6,7 +9,7 @@ export {
   type IGitProcessRunOptions,
   type TGitProcessFailureReason,
   type TGitProcessOutcome,
-} from './git-process.js';
+} from '@robota-sdk/agent-framework';
 export {
   createGitCommandEntry,
   createGitCommandModule,

package/src/goal/goal-command.ts

@@ -4,6 +4,8 @@
  * command host context; all loop logic lives in agent-framework.
  */
 
+import { isGoalCancelVerb } from '@robota-sdk/agent-framework';
+
 import type { ICommandHostGoal } from '@robota-sdk/agent-framework';
 import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 import type { IGoalState } from '@robota-sdk/agent-interface-session';
@@ -45,7 +47,7 @@ export async function executeGoalCommand(
       : { message: 'No goal is set.', success: true };
   }
 
-  if (verb === 'cancel' || verb === 'stop') {
+  if (isGoalCancelVerb(trimmed)) {
     const stopped = context.cancelGoal();
     return stopped
       ? { message: `Goal cancelled: ${stopped.objective}`, success: true }

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

@@ -17,7 +17,8 @@ describe('/handoff command module', () => {
   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).toContain('/handoff <session-or-device-id>');
+    expect(description).toMatch(/linked over the device mesh/);
     expect(description).toMatch(/user-only/i);
     expect(description).toContain('saved, not started');
   });

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

@@ -8,7 +8,7 @@ export function createHandoffCommandEntry(): ICommand {
     name: 'handoff',
     displayName: 'Hand off',
     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>`.',
+      "Push this conversation to another running Robota session of the same user on this machine, or to another of the user's devices linked over the device mesh, 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 and devices it could go to. User-only: the model cannot run it; when the user wants to continue this work in another session or on another device, suggest they run `/handoff <session-or-device-id>`.",
     source: 'handoff',
     // 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.

package/src/handoff/handoff-command.ts

@@ -47,8 +47,8 @@ function usage(): ICommandResult {
     success: true,
     message: [
       'Usage:',
-      '  /handoff               list where this session could move to',
-      '  /handoff <session-id>  move it there, after confirming what stays behind',
+      '  /handoff                         list where this session could move to',
+      '  /handoff <session-or-device-id>  move it there, after confirming what stays behind',
     ].join('\n'),
   };
 }

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

@@ -55,12 +55,14 @@ function createCommandHostContext() {
           displayName: 'Help',
           description: 'Show available commands',
           modelInvocable: true,
+          runner: 'runtime',
         },
         {
           name: 'provider',
           displayName: 'Provider Setup',
           description: 'Manage provider profiles',
           modelInvocable: true,
+          runner: 'runtime',
         },
         // SEC-008: `plugin` installs and enables code, so it is NOT model-invocable — the fixture says
         // what the real command says rather than the value that happened to compile.
@@ -69,6 +71,7 @@ function createCommandHostContext() {
           displayName: 'Plugins',
           description: 'Manage plugins',
           modelInvocable: false,
+          runner: 'runtime',
         },
       ],
       listEditCheckpoints: () => [],

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

@@ -86,6 +86,7 @@ describe('formatCommandHelpMessage — example field', () => {
         description: 'Compress context window',
         example: '/compact Summarize the current context',
         modelInvocable: true,
+        runner: 'runtime',
       },
     ]);
 
@@ -102,6 +103,7 @@ describe('formatCommandHelpMessage — example field', () => {
         description: 'Manage provider profiles',
         example: '/provider switch production',
         modelInvocable: true,
+        runner: 'runtime',
       },
     ]);
 
@@ -117,6 +119,7 @@ describe('formatCommandHelpMessage — example field', () => {
         displayName: 'Help',
         description: 'Show available commands',
         modelInvocable: true,
+        runner: 'runtime',
       },
     ]);
 

package/src/index.ts

@@ -79,8 +79,11 @@ export {
   type IDeviceListEntry,
   type IDevicesCommandPort,
   type IDevicesInitResult,
+  type IDevicesAddResult,
+  type IDevicesJoinResult,
   type IDevicesRecoverResult,
   type IDevicesRevokeResult,
+  type IDevicesMeshStatus,
   type IDevicesView,
   type TDevicesOutcome,
   type TDevicesRefusal,
@@ -120,6 +123,12 @@ export {
 } from './mcp-activation/mcp-model-notice.js';
 export type { TMCPUserAction, TMCPUserActionSurface } from './mcp-activation/mcp-model-notice.js';
 export * from './mode/index.js';
+export {
+  createModelCommandEntry,
+  createModelCommandModule,
+  ModelCommandSource,
+} from './model/model-command-module.js';
+export { executeModelCommand } from './model/model-command.js';
 export {
   createSandboxCommandModule,
   executeSandboxCommand,
@@ -146,4 +155,9 @@ export * from './session/index.js';
 export * from './settings/index.js';
 export * from './skills/index.js';
 export * from './statusline/index.js';
+export {
+  createTerminalClientCommands,
+  type ITerminalClientCommand,
+  type ITerminalClientCommandOptions,
+} from './terminal-client/index.js';
 export * from './user-local/index.js';

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

@@ -21,13 +21,23 @@ export function createKeybindingsCommandEntry(): ICommand {
     source: 'keybindings',
     // User-only: UI preference.
     modelInvocable: false,
+    // Key bindings belong to the terminal the user sits at, so that terminal runs it, even when
+    // attached.
+    runner: 'client',
+    surfaces: ['terminal'],
   };
 }
 
-async function executeKeybindingsCommand(
-  file: IKeybindingsFilePort,
+// A host without a terminal (the desktop app's sidecar) still answers, so the command is never
+// "unknown" there — it says where key bindings live instead.
+const KEYBINDINGS_UNAVAILABLE =
+  'Key bindings belong to the robota terminal, and this surface has none. Run /keybindings in the robota terminal.';
+
+export async function executeKeybindingsCommand(
+  file: IKeybindingsFilePort | undefined,
   context: ICommandHostTerminalHandoff & ICommandHostWorkspace,
 ): Promise<ICommandResult> {
+  if (!file) return { success: false, message: KEYBINDINGS_UNAVAILABLE };
   if (!context.canHandoffTerminal()) {
     return { success: false, message: 'Keybindings editor is unavailable here.' };
   }
@@ -54,7 +64,9 @@ export class KeybindingsCommandSource implements ICommandSource {
   }
 }
 
-export function createKeybindingsCommandModule(file: IKeybindingsFilePort): ICommandModule {
+export function createKeybindingsCommandModule(
+  file: IKeybindingsFilePort | undefined,
+): ICommandModule {
   const entry = createKeybindingsCommandEntry();
   const command: ISystemCommand = {
     name: entry.name,
@@ -63,6 +75,8 @@ export function createKeybindingsCommandModule(file: IKeybindingsFilePort): ICom
     requiresPermission: false,
     userInvocable: true,
     modelInvocable: false,
+    runner: entry.runner,
+    surfaces: entry.surfaces,
     lifecycle: 'inline',
     execute: (context) => executeKeybindingsCommand(file, context),
   };