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

package/src/git/git-status.ts

@@ -0,0 +1,134 @@
+/**
+ * BEHAVIOR-2437: `/git status` — `git status --porcelain=v2 -z --branch`, parsed into the branch and
+ * the staged, unstaged, untracked (and, when present, conflicted) path sets.
+ *
+ * `-z` is what makes a path with a space, a quote, a newline or a non-ASCII character ONE element,
+ * and it is why a `2` (rename/copy) record is read as TWO NUL-terminated fields — `path`, then
+ * `origPath` — so the pair stays a pair.
+ */
+import { gitFailureMessage } from './git-process.js';
+
+import type { IGitProcessPort } from './git-process.js';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+export const GIT_STATUS_ARGS: readonly string[] = ['status', '--porcelain=v2', '-z', '--branch'];
+
+export interface IGitStatusSummary {
+  /** `branch.head`; `(detached)` when detached; `undefined` when git printed no branch header. */
+  branch: string | undefined;
+  /** `branch.oid` is `(initial)` on an unborn branch. */
+  unborn: boolean;
+  staged: readonly string[];
+  unstaged: readonly string[];
+  untracked: readonly string[];
+  conflicted: readonly string[];
+}
+
+const ORDINARY = /^1 (\S\S) \S+ \S+ \S+ \S+ \S+ \S+ ([^]*)$/;
+const RENAMED = /^2 (\S\S) \S+ \S+ \S+ \S+ \S+ \S+ \S+ ([^]*)$/;
+const UNMERGED = /^u \S\S \S+ \S+ \S+ \S+ \S+ \S+ \S+ \S+ ([^]*)$/;
+
+interface IStatusAccumulator {
+  branch: string | undefined;
+  unborn: boolean;
+  staged: string[];
+  unstaged: string[];
+  untracked: string[];
+  conflicted: string[];
+}
+
+function classify(acc: IStatusAccumulator, xy: string, display: string): void {
+  if (xy[0] !== '.') acc.staged.push(display);
+  if (xy[1] !== '.') acc.unstaged.push(display);
+}
+
+function readHeader(acc: IStatusAccumulator, record: string): void {
+  if (record.startsWith('# branch.head ')) acc.branch = record.slice('# branch.head '.length);
+  else if (record.startsWith('# branch.oid ')) {
+    acc.unborn = record.slice('# branch.oid '.length) === '(initial)';
+  }
+}
+
+/** Reads one record; returns how many EXTRA NUL-terminated fields it consumed (1 for a rename). */
+function readRecord(acc: IStatusAccumulator, record: string, next: string | undefined): number {
+  if (record.startsWith('# ')) {
+    readHeader(acc, record);
+    return 0;
+  }
+  if (record.startsWith('? ')) {
+    acc.untracked.push(record.slice(2));
+    return 0;
+  }
+  if (record.startsWith('1 ')) {
+    const match = ORDINARY.exec(record);
+    if (match) classify(acc, match[1] ?? '..', match[2] ?? '');
+    return 0;
+  }
+  if (record.startsWith('2 ')) {
+    // The original path is the NEXT NUL-terminated field.
+    const match = RENAMED.exec(record);
+    if (match) classify(acc, match[1] ?? '..', `${match[2] ?? ''} (from ${next ?? ''})`);
+    return 1;
+  }
+  if (record.startsWith('u ')) {
+    const match = UNMERGED.exec(record);
+    if (match) acc.conflicted.push(match[1] ?? '');
+  }
+  return 0;
+}
+
+export function parseStatusPorcelainV2(stdout: string): IGitStatusSummary {
+  const fields = stdout.split('\0');
+  const acc: IStatusAccumulator = {
+    branch: undefined,
+    unborn: false,
+    staged: [],
+    unstaged: [],
+    untracked: [],
+    conflicted: [],
+  };
+  for (let index = 0; index < fields.length; index += 1) {
+    const record = fields[index] ?? '';
+    if (record.length === 0) continue;
+    index += readRecord(acc, record, fields[index + 1]);
+  }
+  return acc;
+}
+
+function group(label: string, paths: readonly string[]): string {
+  return `${label} (${paths.length}):${paths.length > 0 ? ` ${paths.join(', ')}` : ''}`;
+}
+
+export function formatGitStatus(summary: IGitStatusSummary): string {
+  const head =
+    summary.branch === undefined
+      ? 'No branch information'
+      : summary.branch === '(detached)'
+        ? 'HEAD detached'
+        : `On branch ${summary.branch}${summary.unborn ? ' (no commits yet)' : ''}`;
+  const lines = [
+    head,
+    group('staged', summary.staged),
+    group('unstaged', summary.unstaged),
+    group('untracked', summary.untracked),
+  ];
+  if (summary.conflicted.length > 0) lines.push(group('conflicted', summary.conflicted));
+  return lines.join('\n');
+}
+
+export async function executeGitStatus(
+  port: IGitProcessPort,
+  cwd: string,
+): Promise<ICommandResult> {
+  const outcome = await port.run(GIT_STATUS_ARGS, { cwd });
+  const failure = gitFailureMessage('status', outcome);
+  if (failure !== undefined || outcome.kind !== 'exited') {
+    return { success: false, message: failure ?? 'git status failed' };
+  }
+  const summary = parseStatusPorcelainV2(outcome.stdout);
+  return {
+    success: true,
+    message: formatGitStatus(summary),
+    data: { git: 'status', ...summary },
+  };
+}

package/src/git/index.ts

@@ -0,0 +1,17 @@
+export {
+  createGitProcess,
+  gitEnvironment,
+  type ICreateGitProcessOptions,
+  type IGitProcessPort,
+  type IGitProcessRunOptions,
+  type TGitProcessFailureReason,
+  type TGitProcessOutcome,
+} from './git-process.js';
+export {
+  createGitCommandEntry,
+  createGitCommandModule,
+  executeGitCommand,
+  GitCommandSource,
+  type IGitCommandModuleOptions,
+  type TGitCommandContext,
+} from './git-command-module.js';

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

@@ -2,8 +2,11 @@ import { describe, it, expect, vi } from 'vitest';
 
 import { executeGoalCommand } from '../goal-command.js';
 
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
-import type { IGoalState } from '@robota-sdk/agent-interface-transport';
+import type { IGoalState } from '@robota-sdk/agent-interface-session';
+import {
+  createTestCommandHost,
+  type ICreateTestCommandHostOptions,
+} from '@robota-sdk/agent-framework/testing';
 
 function goal(overrides: Partial<IGoalState> = {}): IGoalState {
   return {
@@ -18,8 +21,10 @@ function goal(overrides: Partial<IGoalState> = {}): IGoalState {
   };
 }
 
-function host(overrides: Partial<ICommandHostContext> = {}): ICommandHostContext {
-  return overrides as unknown as ICommandHostContext;
+function host(overrides: ICreateTestCommandHostOptions['overrides'] = {}) {
+  // ARCH-029: the partial is now an OVERRIDE over a conformant host, not a cast that turns the
+  // check off. A fixture that names three members no longer claims to satisfy 46.
+  return createTestCommandHost({ overrides });
 }
 
 describe('executeGoalCommand', () => {

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

@@ -5,7 +5,7 @@
 import { executeGoalCommand, GOAL_COMMAND_DESCRIPTION } from './goal-command.js';
 
 import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
-import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
 
 export function createGoalCommandEntry(): ICommand {
   return {
@@ -13,6 +13,7 @@ export function createGoalCommandEntry(): ICommand {
     displayName: 'Autonomous Goal',
     description: GOAL_COMMAND_DESCRIPTION,
     source: 'goal',
+    // User-only: assigning an autonomous goal widens what the agent pursues without asking; the user sets it.
     modelInvocable: false,
   };
 }

package/src/goal/goal-command.ts

@@ -4,8 +4,9 @@
  * command host context; all loop logic lives in agent-framework.
  */
 
-import type { ICommandHostContext } from '@robota-sdk/agent-framework';
-import type { ICommandResult, IGoalState } from '@robota-sdk/agent-interface-transport';
+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';
 
 export const GOAL_COMMAND_DESCRIPTION =
   'Assign an autonomous goal the agent pursues across turns until satisfied.';
@@ -27,7 +28,7 @@ function formatGoalState(goal: IGoalState): string {
 }
 
 export async function executeGoalCommand(
-  context: ICommandHostContext,
+  context: ICommandHostGoal,
   args: string,
 ): Promise<ICommandResult> {
   const trimmed = args.trim();
@@ -38,23 +39,19 @@ export async function executeGoalCommand(
   }
 
   if (verb === 'status') {
-    const goal = context.getGoalState?.() ?? null;
+    const goal = context.getGoalState();
     return goal
       ? { message: formatGoalState(goal), success: true, data: { status: goal.status } }
       : { message: 'No goal is set.', success: true };
   }
 
   if (verb === 'cancel' || verb === 'stop') {
-    const stopped = context.cancelGoal?.() ?? null;
+    const stopped = context.cancelGoal();
     return stopped
       ? { message: `Goal cancelled: ${stopped.objective}`, success: true }
       : { message: 'No active goal to cancel.', success: false };
   }
 
-  if (!context.setGoal) {
-    return { message: 'Goal pursuit is not available in this session.', success: false };
-  }
-
   let goal: IGoalState;
   try {
     goal = await context.setGoal(trimmed);

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

@@ -0,0 +1,218 @@
+/**
+ * `/handoff` (HANDOFF-001, issue #1864) — the consent, and the sentence the operator needs.
+ *
+ * Two properties are asserted on nearly every path, because they are what the command is for:
+ *
+ *   the prompt names what will be LOST before it asks, and
+ *   every outcome says where the session is now.
+ *
+ * A hand-off is irreversible from the source's side. A confirmation that did not mention the
+ * uncommitted work is not consent to lose it, and an outcome that did not say where the session
+ * went leaves the operator not knowing which computer to walk to.
+ */
+
+import type {
+  ICommandHostAdapters,
+  IHandoffProgress,
+  IHandoffStaysBehind,
+} from '@robota-sdk/agent-framework';
+import type { IActionRequest, TActionResponse } from '@robota-sdk/agent-core';
+import { describe, expect, it, vi } from 'vitest';
+
+import { executeHandoffCommand } from '../handoff-command.js';
+
+const HERE: IHandoffProgress = { state: 'offered', stillMine: true };
+
+interface IHarness {
+  readonly destinations?: readonly { readonly deviceId: string; readonly name?: string }[];
+  readonly staysBehind?: IHandoffStaysBehind;
+  readonly transfer?: (
+    deviceId: string,
+    onProgress?: (progress: IHandoffProgress) => void,
+  ) => Promise<IHandoffProgress>;
+  readonly answer?: TActionResponse;
+  /** Omitted entirely when the host has no interactive renderer — that is a case, not a default. */
+  readonly interactive?: boolean;
+  readonly adapter?: boolean;
+}
+
+function host(harness: IHarness = {}) {
+  const asked: IActionRequest[] = [];
+  const adapters: ICommandHostAdapters =
+    harness.adapter === false
+      ? {}
+      : {
+          handoff: {
+            destinations: async () => harness.destinations ?? [{ deviceId: 'laptop' }],
+            staysBehind: async () =>
+              harness.staysBehind ?? { uncommittedChanges: false, subprocesses: 0 },
+            transfer:
+              harness.transfer ??
+              (async (_id, onProgress) => {
+                onProgress?.({ state: 'sending', stillMine: true });
+                return { state: 'done', stillMine: false };
+              }),
+            status: () => HERE,
+          },
+        };
+  return {
+    asked,
+    context: {
+      getCommandHostAdapters: () => adapters,
+      getUserInteraction:
+        harness.interactive === false
+          ? () => undefined
+          : () => ({
+              ask: async (request: IActionRequest): Promise<TActionResponse> => {
+                asked.push(request);
+                return harness.answer ?? { type: 'answer', values: ['move'] };
+              },
+            }),
+    },
+  };
+}
+
+describe('the consent names what will be lost, before it asks', () => {
+  it('says the uncommitted work and the running processes stay behind', async () => {
+    const { asked, context } = host({
+      staysBehind: { uncommittedChanges: true, subprocesses: 3 },
+    });
+    await executeHandoffCommand(context, 'laptop');
+
+    expect(asked).toHaveLength(1);
+    const description = asked[0]?.description ?? '';
+    expect(description).toContain('uncommitted changes');
+    expect(description).toContain('3 running process');
+    // The credential line is unconditional: it is true on every hand-off, and it is the one that
+    // explains why the other machine may refuse at the last step.
+    expect(description).toContain('credentials are never transferred');
+  });
+
+  it('omits what does not apply, so the prompt is not a standing warning nobody reads', async () => {
+    const { asked, context } = host({
+      staysBehind: { uncommittedChanges: false, subprocesses: 0 },
+    });
+    await executeHandoffCommand(context, 'laptop');
+
+    const description = asked[0]?.description ?? '';
+    expect(description).not.toContain('uncommitted changes');
+    expect(description).not.toContain('running process');
+    expect(description).toContain('credentials are never transferred');
+  });
+
+  it('does not transfer when the operator declines', async () => {
+    const transfer = vi.fn();
+    const { context } = host({ answer: { type: 'answer', values: ['stay'] }, transfer });
+    const result = await executeHandoffCommand(context, 'laptop');
+
+    expect(transfer).not.toHaveBeenCalled();
+    expect(result.message).toContain('still on this machine');
+  });
+
+  it('treats a dismissed prompt as a decline, never as a yes', async () => {
+    const transfer = vi.fn();
+    const { context } = host({ answer: { type: 'cancelled' }, transfer });
+    const result = await executeHandoffCommand(context, 'laptop');
+
+    expect(transfer).not.toHaveBeenCalled();
+    expect(result.message).toContain('still on this machine');
+  });
+
+  it('refuses when no human is attached, rather than proceeding unasked', async () => {
+    const transfer = vi.fn();
+    const { context } = host({ interactive: false, transfer });
+    const result = await executeHandoffCommand(context, 'laptop');
+
+    expect(result.success).toBe(false);
+    expect(transfer).not.toHaveBeenCalled();
+    expect(result.message).toContain('needs a person to confirm');
+    expect(result.message).toContain('still on this machine');
+  });
+});
+
+describe('every outcome says where the session is now', () => {
+  it('says the destination owns it when the transfer completes', async () => {
+    const { context } = host({
+      transfer: async () => ({ state: 'done', stillMine: false }),
+    });
+    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');
+  });
+
+  it('says the session is still here when the transfer stops, and why', async () => {
+    const { context } = host({
+      transfer: async () => ({
+        state: 'stopped',
+        reason: 'the destination resolved no provider credential',
+        stillMine: true,
+      }),
+    });
+    const result = await executeHandoffCommand(context, 'laptop');
+
+    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');
+  });
+
+  it('names the waiting phase as safe to leave, since that is when it looks stuck', async () => {
+    const { context } = host({
+      transfer: async (_id, onProgress) => {
+        onProgress?.({ state: 'awaiting-confirmation', stillMine: true });
+        return { state: 'done', stillMine: false };
+      },
+    });
+    const result = await executeHandoffCommand(context, 'laptop');
+
+    expect(result.message).toContain('this machine keeps it');
+  });
+});
+
+describe('what it refuses before asking anything', () => {
+  it('says a host with no carrier cannot move a session', async () => {
+    const { asked, context } = host({ adapter: false });
+    const result = await executeHandoffCommand(context, 'laptop');
+
+    expect(result.success).toBe(false);
+    expect(asked).toHaveLength(0);
+    expect(result.message).toContain('no hand-off carrier');
+    expect(result.message).toContain('still here');
+  });
+
+  it('refuses a destination that is not reachable, and lists the ones that are', async () => {
+    const { asked, context } = host({
+      destinations: [{ deviceId: 'laptop', name: 'Work laptop' }],
+    });
+    const result = await executeHandoffCommand(context, 'tablet');
+
+    expect(result.success).toBe(false);
+    expect(asked).toHaveLength(0);
+    expect(result.message).toContain("No reachable machine is called 'tablet'");
+    expect(result.message).toContain('Work laptop');
+    expect(result.message).toContain('still on this machine');
+  });
+
+  it('lists the destinations when called with no argument', async () => {
+    const { asked, context } = host({
+      destinations: [{ deviceId: 'laptop' }, { deviceId: 'tablet' }],
+    });
+    const result = await executeHandoffCommand(context, '');
+
+    expect(asked).toHaveLength(0);
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('laptop');
+    expect(result.message).toContain('tablet');
+  });
+
+  it('says so plainly when nothing is reachable', async () => {
+    const { context } = host({ destinations: [] });
+    const result = await executeHandoffCommand(context, '');
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain('No other machine is reachable');
+    expect(result.message).toContain('still on this machine');
+  });
+});

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

@@ -0,0 +1,48 @@
+import { executeHandoffCommand } from './handoff-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createHandoffCommandEntry(): ICommand {
+  return {
+    name: 'handoff',
+    displayName: 'Hand off',
+    description: 'Move this session to another machine, after confirming what stays behind',
+    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.
+    modelInvocable: false,
+  };
+}
+
+function createHandoffSystemCommand(): ISystemCommand {
+  const entry = createHandoffCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: (context, args) => executeHandoffCommand(context, args),
+  };
+}
+
+export class HandoffCommandSource implements ICommandSource {
+  readonly name = 'handoff';
+
+  getCommands(): ICommand[] {
+    return [createHandoffCommandEntry()];
+  }
+}
+
+export function createHandoffCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-handoff',
+    commandSources: [new HandoffCommandSource()],
+    systemCommands: [createHandoffSystemCommand()],
+  };
+}