@robota-sdk/agent-command 3.0.0-beta.100

package/src/memory/__tests__/memory-command-unavailable.test.ts

@@ -0,0 +1,63 @@
+/**
+ * #3282 §4c review finding: `/memory` in a served (GUI) session throws instead of answering, because
+ * `executeMemoryCommand` never caught what `context.getMemoryStore()` throws when the host composed no
+ * memory store (off by default, or unavailable on this host — `WorkspaceAuthorityRequiredError`). The
+ * uncaught rejection reaches the transport's `command` handler
+ * (`session-message-handler.ts`'s `.then(_, error => deliver({ type: 'protocol_error', ... }))`), which
+ * the GUI renders as a `protocol_error` toast — the "red toast" the audit found — instead of the same
+ * plain `command_result` every other unavailable-command case gets (mirrors `rewind-command.ts`'s
+ * `formatError`, which already catches `EditCheckpointsUnavailableError` the same way).
+ */
+import { describe, expect, it } from 'vitest';
+
+import { WorkspaceAuthorityRequiredError } from '@robota-sdk/agent-framework';
+
+import { executeMemoryCommand } from '../memory-command.js';
+
+import type { ICommandHostMemory, ICommandHostWorkspace } from '@robota-sdk/agent-framework';
+
+function contextWithUnavailableMemory(): ICommandHostMemory & ICommandHostWorkspace {
+  return {
+    getUsedMemoryReferences: () => [],
+    recordMemoryEvent: () => {},
+    getMemoryStore: () => {
+      throw new WorkspaceAuthorityRequiredError("Project memory isn't available for this folder.");
+    },
+    getCwd: () => '/workspace',
+    getCommandInvocationSource: () => 'user',
+  };
+}
+
+describe('executeMemoryCommand — unavailable memory store', () => {
+  it('answers list with a plain failure instead of rejecting', async () => {
+    const result = await executeMemoryCommand(contextWithUnavailableMemory(), 'list');
+    expect(result.success).toBe(false);
+    expect(result.message).toBe("Project memory isn't available for this folder.");
+  });
+
+  it('answers show, pending, used and add the same way — never a throw', async () => {
+    const context = contextWithUnavailableMemory();
+    for (const args of ['show', 'pending', 'used', 'add project topic some durable fact']) {
+      await expect(executeMemoryCommand(context, args)).resolves.toMatchObject({
+        success: false,
+        message: "Project memory isn't available for this folder.",
+      });
+    }
+  });
+
+  it('still lets an ordinary Error through as a plain failure, not a throw', async () => {
+    const context: ICommandHostMemory & ICommandHostWorkspace = {
+      getUsedMemoryReferences: () => [],
+      recordMemoryEvent: () => {},
+      getMemoryStore: () => {
+        throw new Error('unexpected store failure');
+      },
+      getCwd: () => '/workspace',
+      getCommandInvocationSource: () => 'user',
+    };
+    await expect(executeMemoryCommand(context, 'list')).resolves.toEqual({
+      success: false,
+      message: 'unexpected store failure',
+    });
+  });
+});

package/src/memory/index.ts

@@ -0,0 +1,6 @@
+export {
+  MemoryCommandSource,
+  createMemoryCommandEntry,
+  createMemoryCommandModule,
+} from './memory-command-module.js';
+export { executeMemoryCommand } from './memory-command.js';

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

@@ -0,0 +1,77 @@
+import {
+  MEMORY_COMMAND_ARGUMENT_HINT,
+  MEMORY_COMMAND_DESCRIPTION,
+  buildMemoryCommandSubcommands,
+} from '@robota-sdk/agent-framework';
+
+import { executeMemoryCommand } from './memory-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+/**
+ * Model-invocable: remembering and recalling project conventions is the model's own work. The
+ * subcommand flags (in `buildMemoryCommandSubcommands`) keep `approve`/`reject` user-only, because
+ * pending candidates exist so the user reviews what the model proposed to remember, and the command
+ * refuses the model's `add` in plan mode, which writes nothing.
+ */
+const MEMORY_COMMAND_MODEL_DESCRIPTION =
+  'Read and write this project’s durable memory. Use `list` or `show [topic]` to look up stored ' +
+  'conventions, preferences or references before asking the user again; `add <type> <topic> <text>` ' +
+  'to save a durable preference, project convention, feedback item or reference worth reusing ' +
+  'across sessions (never secrets, credentials or transient facts); `pending` to see candidates ' +
+  'awaiting the user’s review; `used` to report which memory items informed this turn. Bare lists ' +
+  'topics. In plan mode `add` is refused: save after plan mode ends. Returns the requested topics ' +
+  'or entries, or a confirmation of what was saved. Approving ' +
+  'or rejecting a pending candidate is the user’s review: suggest `/memory approve <id>` or ' +
+  '`/memory reject <id>`. Correcting or forgetting saved knowledge is also user-only: ' +
+  'suggest `/memory correct <type> <topic> <text>` to replace every entry in a topic or ' +
+  '`/memory forget <topic>` to remove it from active recall. These operations block automatic ' +
+  'restoration of that topic; historical transcripts and backups remain.';
+
+export function createMemoryCommandEntry(): ICommand {
+  return {
+    name: 'memory',
+    displayName: 'Memory',
+    description: MEMORY_COMMAND_DESCRIPTION,
+    modelDescription: MEMORY_COMMAND_MODEL_DESCRIPTION,
+    source: 'memory',
+    argumentHint: MEMORY_COMMAND_ARGUMENT_HINT,
+    modelInvocable: true,
+    safety: 'write',
+    subcommands: buildMemoryCommandSubcommands(),
+  };
+}
+
+function createMemorySystemCommand(): ISystemCommand {
+  const entry = createMemoryCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    ...(entry.modelDescription !== undefined ? { modelDescription: entry.modelDescription } : {}),
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: true,
+    argumentHint: entry.argumentHint,
+    safety: entry.safety,
+    subcommands: entry.subcommands,
+    execute: executeMemoryCommand,
+  };
+}
+
+export class MemoryCommandSource implements ICommandSource {
+  readonly name = 'memory';
+
+  getCommands(): ICommand[] {
+    return [createMemoryCommandEntry()];
+  }
+}
+
+export function createMemoryCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-memory',
+    commandSources: [new MemoryCommandSource()],
+    systemCommands: [createMemorySystemCommand()],
+  };
+}

package/src/memory/memory-command.ts

@@ -0,0 +1,326 @@
+import {
+  MEMORY_COMMAND_USAGE,
+  approvePendingMemoryCandidate,
+  createCommandMemoryStores,
+  hasSensitiveCommandMemoryContent,
+  isCommandMemoryType,
+  listCommandUsedMemoryReferences,
+  recordCommandMemoryEvent,
+} from '@robota-sdk/agent-framework';
+
+import type {
+  IAppendMemoryInput,
+  ICommandHostAdapterAccess,
+  ICommandHostMemory,
+  ICommandHostSessionAccess,
+  ICommandHostWorkspace,
+  IMemoryStore,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+import type { IMemoryEvent } from '@robota-sdk/agent-interface-session';
+
+const SUBCOMMAND_INDEX = 0;
+const TYPE_INDEX = 1;
+const TOPIC_INDEX = 2;
+const TEXT_START_INDEX = 3;
+
+function usage(): ICommandResult {
+  return {
+    message: MEMORY_COMMAND_USAGE,
+    success: false,
+  };
+}
+
+function formatError(error: Error | string): ICommandResult {
+  return {
+    message: error instanceof Error ? error.message : String(error),
+    success: false,
+  };
+}
+
+/**
+ * `context.getMemoryStore()` throws `WorkspaceAuthorityRequiredError` when the host composed no
+ * memory store — off by default, or unavailable on this host (mirrors `EditCheckpointsUnavailableError`
+ * for `/rewind`, `rewind-command.ts`'s `formatError`). Uncaught, that throw reaches the GUI as a raw
+ * `protocol_error` (a red toast) instead of the SAME plain `command_result` every other unavailable-
+ * command case gets — this is the one call in the command that can throw before any subcommand branch
+ * runs, so it is guarded once, here, rather than in each branch below.
+ */
+function getMemoryStoreOrError(
+  context: ICommandHostMemory,
+): { ok: true; store: IMemoryStore } | { ok: false; result: ICommandResult } {
+  try {
+    return { ok: true, store: createCommandMemoryStores(context) };
+  } catch (error) {
+    return { ok: false, result: formatError(error instanceof Error ? error : String(error)) };
+  }
+}
+
+async function formatList(store: IMemoryStore): Promise<ICommandResult> {
+  const summary = await store.list();
+  const topics =
+    summary.topics.length > 0
+      ? summary.topics.map((topic) => `- ${topic.name}: ${topic.path}`).join('\n')
+      : '(none)';
+
+  return {
+    message: [
+      `Memory index: ${summary.indexPath}`,
+      `Topics directory: ${summary.topicsPath}`,
+      'Topics:',
+      topics,
+    ].join('\n'),
+    success: true,
+    data: {
+      indexPath: summary.indexPath,
+      topicsPath: summary.topicsPath,
+      topicCount: summary.topics.length,
+    },
+  };
+}
+
+async function formatShow(store: IMemoryStore, topic?: string): Promise<ICommandResult> {
+  if (!topic || topic === 'index') {
+    const memory = await store.loadStartupMemory();
+    return {
+      message: memory.content || '(empty memory index)',
+      success: true,
+      data: {
+        path: memory.path,
+        lineCount: memory.lineCount,
+        truncated: memory.truncated,
+      },
+    };
+  }
+
+  const content = await store.readTopic(topic);
+  return {
+    message: content || `(empty memory topic: ${topic})`,
+    success: true,
+    data: { topic },
+  };
+}
+
+function parseAdd(args: readonly string[]): IAppendMemoryInput | undefined {
+  const type = args[TYPE_INDEX];
+  const topic = args[TOPIC_INDEX];
+  const text = args.slice(TEXT_START_INDEX).join(' ').trim();
+
+  if (!type || !isCommandMemoryType(type) || !topic || text.length === 0) return undefined;
+  return { type, topic, text };
+}
+
+async function formatPending(store: IMemoryStore): Promise<ICommandResult> {
+  const records = await store.listPending('pending');
+  const lines =
+    records.length > 0
+      ? records.map(
+          (record) =>
+            `- ${record.id} ${record.type}/${record.topic} confidence=${record.confidence}: ${record.text}`,
+        )
+      : ['(no pending memory candidates)'];
+
+  return {
+    message: ['Pending memory candidates:', ...lines].join('\n'),
+    success: true,
+    data: { count: records.length },
+  };
+}
+
+function recordEvent(context: ICommandHostMemory, event: Omit<IMemoryEvent, 'at'>): void {
+  recordCommandMemoryEvent(context, event);
+}
+
+async function approvePending(
+  context: ICommandHostMemory,
+  store: IMemoryStore,
+  id: string | undefined,
+): Promise<ICommandResult> {
+  if (!id) return usage();
+  try {
+    const { record, saved } = await approvePendingMemoryCandidate(store, id);
+    recordEvent(context, {
+      type: 'memory_candidate_approved',
+      candidateId: record.id,
+      topic: record.topic,
+      reason: 'approved-by-user',
+    });
+    recordEvent(context, {
+      type: 'memory_candidate_saved',
+      candidateId: record.id,
+      topic: record.topic,
+      reason: saved.deduplicated ? 'deduplicated' : 'approved-and-saved',
+    });
+    return {
+      message: saved.deduplicated
+        ? `Saved memory candidate ${id} was already present in ${saved.topicPath}`
+        : `Saved memory candidate ${id} to ${saved.topicPath}`,
+      success: true,
+      data: {
+        id,
+        status: record.status,
+        topic: saved.topic,
+        topicPath: saved.topicPath,
+        deduplicated: saved.deduplicated,
+      },
+    };
+  } catch (error) {
+    return formatError(error instanceof Error ? error : String(error));
+  }
+}
+
+async function rejectPending(
+  context: ICommandHostMemory,
+  store: IMemoryStore,
+  id: string | undefined,
+): Promise<ICommandResult> {
+  if (!id) return usage();
+  try {
+    const record = await store.markPending(id, 'rejected', 'rejected-by-user');
+    recordEvent(context, {
+      type: 'memory_candidate_rejected',
+      candidateId: record.id,
+      topic: record.topic,
+      reason: 'rejected-by-user',
+    });
+    return {
+      message: `Rejected memory candidate ${id}`,
+      success: true,
+      data: { id, status: record.status },
+    };
+  } catch (error) {
+    return formatError(error instanceof Error ? error : String(error));
+  }
+}
+
+function formatUsed(context: ICommandHostMemory): ICommandResult {
+  const references = listCommandUsedMemoryReferences(context);
+  const lines =
+    references.length > 0
+      ? references.map((reference) => {
+          const suffix = reference.truncated ? ' truncated=true' : '';
+          return `- ${reference.topic} score=${reference.score}${suffix}: ${reference.path}`;
+        })
+      : ['(no memory used in current turn)'];
+
+  return {
+    message: ['Used memory references:', ...lines].join('\n'),
+    success: true,
+    data: { count: references.length, references: [...references] },
+  };
+}
+
+/** The host's view of the session's permission mode, when it has one. */
+type TMemoryCommandModeAccess = ICommandHostAdapterAccess &
+  Partial<Pick<ICommandHostSessionAccess, 'getSession'>>;
+
+function isPlanMode(context: TMemoryCommandModeAccess): boolean {
+  const adapter = context.getCommandHostAdapters?.().permissionMode;
+  const mode = adapter?.getPermissionMode() ?? context.getSession?.().getPermissionMode();
+  return mode === 'plan';
+}
+
+export async function executeMemoryCommand(
+  context: ICommandHostMemory & ICommandHostWorkspace & TMemoryCommandModeAccess,
+  rawArgs: string,
+): Promise<ICommandResult> {
+  const args = rawArgs.trim().split(/\s+/).filter(Boolean);
+  const subcommand = args[SUBCOMMAND_INDEX] ?? 'list';
+  const source = context.getCommandInvocationSource();
+  if (
+    (subcommand === 'correct' || subcommand === 'forget') &&
+    source !== 'user' && source !== 'remote'
+  ) {
+    return {
+      success: false,
+      message:
+        'Memory correction and forgetting: only the user can run /memory correct or /memory forget.',
+    };
+  }
+  // SELFHOST-008 P1R: the single injected durable-memory port (or fs default) — authoritative for all
+  // `/memory` operations, so a surface that swaps the store is honored here too (no split-brain).
+  const resolved = getMemoryStoreOrError(context);
+  if (!resolved.ok) return resolved.result;
+  const store = resolved.store;
+
+  if (subcommand === 'correct' || subcommand === 'forget') {
+    try {
+      if (subcommand === 'correct') {
+        const input = parseAdd(args);
+        if (!input) return usage();
+        if (hasSensitiveCommandMemoryContent(input.text))
+          return { success: false, message: 'Refusing to save sensitive memory content.' };
+        if (!store.replaceTopic)
+          return {
+            success: false,
+            message: 'This memory backend does not support topic correction.',
+          };
+        const result = await store.replaceTopic(input);
+        return {
+          success: true,
+          message: `Replaced all active memory in ${result.topicPath}. Automatic additions to this topic now require user correction. Historical transcripts and backups remain.`,
+          data: { ...result },
+        };
+      }
+      if (!args[TYPE_INDEX] || args.length !== 2) return usage();
+      if (!store.forgetTopic)
+        return {
+          success: false,
+          message: 'This memory backend does not support forgetting topics.',
+        };
+      const result = await store.forgetTopic(args[TYPE_INDEX]);
+      return {
+        success: true,
+        message: `Forgot active memory topic ${result.topic}. Source topic removed; automatic restoration is blocked. Historical transcripts and backups remain.`,
+        data: { ...result },
+      };
+    } catch (error) {
+      return formatError(error instanceof Error ? error : String(error));
+    }
+  }
+
+  if (subcommand === 'list') return formatList(store);
+  if (subcommand === 'show') return formatShow(store, args[TYPE_INDEX]);
+  if (subcommand === 'pending') return formatPending(store);
+  if (subcommand === 'approve') return approvePending(context, store, args[TYPE_INDEX]);
+  if (subcommand === 'reject') return rejectPending(context, store, args[TYPE_INDEX]);
+  if (subcommand === 'used') return formatUsed(context);
+  if (subcommand === 'add') {
+    // Plan mode changes nothing, and saved memory is read back into every later session. The user
+    // can still save by hand; the model waits until plan mode ends.
+    if (context.getCommandInvocationSource() === 'model' && isPlanMode(context)) {
+      return {
+        message: 'Plan mode saves no memory. Save it after plan mode ends.',
+        success: false,
+      };
+    }
+    const input = parseAdd(args);
+    if (!input) return usage();
+    if (hasSensitiveCommandMemoryContent(input.text)) {
+      return {
+        message: 'Refusing to save sensitive memory content.',
+        success: false,
+      };
+    }
+    let result;
+    try {
+      result = await store.append(input);
+    } catch (error) {
+      return formatError(error instanceof Error ? error : String(error));
+    }
+    return {
+      message: result.deduplicated
+        ? `${input.type} memory already exists in ${result.topicPath}`
+        : `Saved ${input.type} memory to ${result.topicPath}`,
+      success: true,
+      data: {
+        indexPath: result.indexPath,
+        topicPath: result.topicPath,
+        topic: result.topic,
+        deduplicated: result.deduplicated,
+      },
+    };
+  }
+
+  return usage();
+}