@pellux/goodvibes-agent 0.1.0

package/src/input/commands/provider.ts

@@ -0,0 +1,363 @@
+/**
+ * /provider command handler.
+ *
+ * Implements the Provider Optimizer panel commands:
+ *
+ *   /provider route auto|manual  — Set optimizer routing mode
+ *   /provider explain-route      — Print current route explanation
+ *   /provider pin <provider:model> — Pin routing to a specific provider/model
+ *   /provider fallback test      — Simulate the fallback chain
+ *
+ * When the optimizer is disabled, commands report its status and
+ * explain-route still works (reads current model capabilities).
+ */
+
+import type { SlashCommand, CommandContext } from '../command-registry.ts';
+import type { RouteExplanation } from '@pellux/goodvibes-sdk/platform/providers';
+import type { FallbackTestResult, FallbackTransition } from '@pellux/goodvibes-sdk/platform/providers';
+import type { ProviderApiModelRecord } from '@pellux/goodvibes-sdk/platform/providers';
+import { requireProviderApi } from './runtime-services.ts';
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+function fmtBool(value: boolean): string {
+  return value ? 'yes' : 'no';
+}
+
+function fmtTs(epochMs: number): string {
+  return new Date(epochMs).toISOString().replace('T', ' ').slice(0, 19);
+}
+
+function requireProviderOptimizer(context: CommandContext) {
+  if (!context.provider.providerOptimizer) {
+    context.print('[provider] Provider optimizer is not wired into this runtime.');
+    return null;
+  }
+  return context.provider.providerOptimizer;
+}
+
+function fmtExplanation(expl: RouteExplanation, context: CommandContext): void {
+  const status = expl.accepted ? '[accepted]' : '[rejected]';
+  context.print(`  ${status} ${expl.providerId}/${expl.modelId}`);
+  context.print(`    ${expl.summary}`);
+  if (!expl.accepted && expl.rejections.length > 0) {
+    context.print('    Unmet requirements:');
+    for (const r of expl.rejections) {
+      context.print(
+        `      - ${r.code}: ${r.reason} (actual=${r.actual}, required=${r.required})`,
+      );
+    }
+  }
+  if (expl.accepted) {
+    const c = expl.capability;
+    context.print(
+      `    Capabilities: streaming=${fmtBool(c.streaming)}, tools=${fmtBool(c.toolCalling)}, ` +
+      `parallel=${fmtBool(c.parallelTools)}, json=${fmtBool(c.jsonMode)}, ` +
+      `reasoning=${fmtBool(c.reasoningControls)}`,
+    );
+    context.print(
+      `    Context=${c.maxContextTokens.toLocaleString()} tokens, ` +
+      `output=${c.maxOutputTokens.toLocaleString()} tokens, ` +
+      `timeout=${c.timeoutMs}ms, caching=${c.caching}`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// /provider route auto|manual
+// ---------------------------------------------------------------------------
+
+function handleRoute(
+  args: string[],
+  context: CommandContext,
+): void {
+  const optimizer = requireProviderOptimizer(context);
+  if (!optimizer) return;
+  const sub = args[0];
+
+  if (sub !== 'auto' && sub !== 'manual') {
+    context.print('[provider] Usage: /provider route auto|manual');
+    context.print(`  Current mode: ${optimizer.mode} (optimizer ${optimizer.enabled ? 'on' : 'off'})`);
+    return;
+  }
+
+  if (!optimizer.enabled) {
+    context.print(
+      '[provider] Optimizer is currently disabled. Enable it with the provider-optimizer feature flag.',
+    );
+    context.print(`  Routing mode set to: ${sub} (no-op until optimizer is enabled)`);
+  }
+
+  optimizer.setMode(sub);
+  context.print(`[provider] Routing mode → ${sub}`);
+
+  if (sub === 'auto') {
+    context.print(
+      '  Auto mode: optimizer selects the best capable provider for each request profile.',
+    );
+  } else {
+    context.print(
+      '  Manual mode: optimizer is advisory only; provider selection is caller-driven.',
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// /provider explain-route
+// ---------------------------------------------------------------------------
+
+async function handleExplainRoute(
+  _args: string[],
+  context: CommandContext,
+): Promise<void> {
+  const optimizer = requireProviderOptimizer(context);
+  if (!optimizer) return;
+  const providerApi = requireProviderApi(context);
+
+  let currentModel: ProviderApiModelRecord;
+  try {
+    currentModel = await providerApi.getCurrentModel();
+  } catch {
+    context.print('[provider] No current model selected.');
+    return;
+  }
+
+  context.print(
+    `[provider] Route explanation for current model: ${currentModel.providerId}/${currentModel.modelId}`,
+  );
+
+  // Always explain current route regardless of optimizer enabled state
+  const expl = optimizer.explainCurrentRoute();
+  fmtExplanation(expl, context);
+
+  // Show optimizer status
+  context.print(`
+  Optimizer: ${optimizer.enabled ? 'enabled' : 'disabled'}, mode=${optimizer.mode}`);
+  if (optimizer.pinnedTarget) {
+    context.print(
+      `  Pinned to: ${optimizer.pinnedTarget.providerId}/${optimizer.pinnedTarget.modelId}`,
+    );
+  }
+
+  // Show recent fallback transitions
+  const log = optimizer.fallbackLog;
+  if (log.length > 0) {
+    const recent = log.slice(-5); // last 5 transitions
+    context.print(`  Fallback log (last ${recent.length} of ${log.length}):`);
+    for (const t of recent) {
+      context.print(
+        `    ${fmtTs(t.ts)}  ${t.from} → ${t.to}  (${t.reason})`,
+      );
+    }
+  } else {
+    context.print('  Fallback log: empty');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// /provider pin <provider:model>
+// ---------------------------------------------------------------------------
+
+async function handlePin(
+  args: string[],
+  context: CommandContext,
+): Promise<void> {
+  const optimizer = requireProviderOptimizer(context);
+  if (!optimizer) return;
+  const target = args[0];
+
+  if (!target) {
+    // Show current pin status
+    if (optimizer.pinnedTarget) {
+      context.print(
+        `[provider] Currently pinned to: ${optimizer.pinnedTarget.providerId}/${optimizer.pinnedTarget.modelId}`,
+      );
+      context.print('  Use "/provider pin <provider:model>" to change, or "/provider route manual" to unpin.');
+    } else {
+      context.print('[provider] No pin active. Usage: /provider pin <provider:model>');
+      context.print('  Example: /provider pin anthropic:claude-opus-4-5');
+    }
+    return;
+  }
+
+  // Parse provider:model format
+  const colonIdx = target.indexOf(':');
+  if (colonIdx === -1) {
+    context.print(`[provider] Invalid format "${target}". Expected: <provider>:<model>`);
+    context.print('  Example: /provider pin anthropic:claude-opus-4-5');
+    return;
+  }
+
+  const providerId = target.slice(0, colonIdx);
+  const modelId = target.slice(colonIdx + 1);
+
+  if (!providerId || !modelId) {
+    context.print(`[provider] Invalid format "${target}". Both provider and model must be non-empty.`);
+    return;
+  }
+
+  // Validate that the model exists in registry
+  const providerApi = requireProviderApi(context);
+  const models = await providerApi.listModels();
+  const currentModel = await providerApi.getCurrentModel();
+  const match = models.find(
+    (m) => m.providerId === providerId && (m.modelId === modelId || m.registryKey === target),
+  ) ?? (
+    currentModel.providerId === providerId
+      && (currentModel.modelId === modelId || currentModel.registryKey === target)
+      ? currentModel
+      : undefined
+  );
+
+  if (!match) {
+    context.print(
+      `[provider] Model not found in registry: ${providerId}/${modelId}`,
+    );
+    context.print('  Use "/model" to see available models, or check the provider and model ID.');
+    return;
+  }
+
+  // Enable optimizer if it's off
+  if (!optimizer.enabled) {
+    optimizer.setEnabled(true);
+    context.print('⚠ Optimizer was disabled — enabling it for pin to take effect.');
+  }
+
+  optimizer.pin(match.providerId, match.modelId);
+  context.print(`[provider] Pinned → ${match.providerId}/${match.modelId}`);
+  context.print('  All routed requests will target this provider/model.');
+  context.print('  Unpin with: /provider route manual');
+}
+
+// ---------------------------------------------------------------------------
+// /provider fallback test
+// ---------------------------------------------------------------------------
+
+function handleFallbackTest(
+  args: string[],
+  context: CommandContext,
+): void {
+  const optimizer = requireProviderOptimizer(context);
+  if (!optimizer) return;
+  const sub = args[0];
+
+  if (sub !== 'test') {
+    context.print('[provider] Usage: /provider fallback test');
+    return;
+  }
+
+  context.print('[provider] Simulating fallback chain (empty request profile — no requirements)...');
+
+  const result: FallbackTestResult = optimizer.testFallback();
+
+  context.print(
+    `[provider] Fallback chain: ${result.viableCount} capable / ${result.totalCount} total providers`,
+  );
+
+  // Show first capable then rejected
+  const capable = result.chain.filter((n) => n.capable);
+  const rejected = result.chain.filter((n) => !n.capable);
+
+  if (capable.length > 0) {
+    context.print('  Capable providers (would succeed):');
+    for (const node of capable.slice(0, 10)) {
+      context.print(`    [${node.position}] ${node.providerId}/${node.modelId}`);
+    }
+    if (capable.length > 10) {
+      context.print(`    ... and ${capable.length - 10} more`);
+    }
+  } else {
+    context.print('  No capable providers found for this profile.');
+  }
+
+  if (rejected.length > 0) {
+    context.print(`  Rejected providers (${rejected.length}):`);
+    for (const node of rejected.slice(0, 5)) {
+      const reasons = !node.explanation.accepted
+        ? node.explanation.rejections.map((r) => r.code).join(', ')
+        : '';
+      context.print(
+        `    [${node.position}] ${node.providerId}/${node.modelId} — ${reasons || 'unknown'}`,
+      );
+    }
+    if (rejected.length > 5) {
+      context.print(`    ... and ${rejected.length - 5} more`);
+    }
+  }
+
+  // Show fallback log
+  const log = optimizer.fallbackLog;
+  if (log.length > 0) {
+    context.print(`  Logged transitions (${log.length} total):`);
+    const recent: readonly FallbackTransition[] = log.slice(-5);
+    for (const t of recent) {
+      context.print(
+        `    ${fmtTs(t.ts)}  ${t.from} → ${t.to}  (${t.reason})`,
+      );
+    }
+  } else {
+    context.print('  No fallback transitions logged this session.');
+  }
+
+  context.print(`  Test completed at: ${fmtTs(result.testedAt)}`);
+}
+
+// ---------------------------------------------------------------------------
+// Top-level command definition
+// ---------------------------------------------------------------------------
+
+/**
+ * providerCommand — The `/provider` slash command.
+ *
+ * Routes to subcommand handlers based on args[0].
+ */
+export const providerCommand: SlashCommand = {
+  name: 'provider-opt',
+  aliases: ['prov-opt'],
+  description: 'Manage provider routing optimizer (route, pin, explain, fallback).',
+  usage: '<subcommand> [args]',
+  argsHint: 'route|explain-route|pin|fallback',
+  handler: async (args: string[], context: CommandContext): Promise<void> => {
+    const [sub, ...rest] = args;
+
+    switch (sub) {
+      case 'route':
+        handleRoute(rest, context);
+        break;
+
+      case 'explain-route':
+      case 'explain':
+        await handleExplainRoute(rest, context);
+        break;
+
+      case 'pin':
+        await handlePin(rest, context);
+        break;
+
+      case 'fallback':
+        handleFallbackTest(rest, context);
+        break;
+
+      default: {
+        const optimizer = requireProviderOptimizer(context);
+        if (!optimizer) return;
+        const lines = [
+          'Usage: /provider <subcommand>',
+          '  route auto|manual              — Set optimizer routing mode',
+          '  explain-route                  — Show current route explanation',
+          '  pin <provider:model>           — Pin routing to specific provider/model',
+          '  fallback test                  — Simulate the full fallback chain',
+          '',
+          `  Optimizer: ${optimizer.enabled ? 'enabled' : 'disabled'}  mode=${optimizer.mode}`,
+        ];
+        if (optimizer.pinnedTarget) {
+          lines.push(`  Pinned: ${optimizer.pinnedTarget.providerId}/${optimizer.pinnedTarget.modelId}`);
+        }
+        context.print(lines.join('\n'));
+        break;
+      }
+    }
+  },
+};

package/src/input/commands/qrcode-runtime.ts

@@ -0,0 +1,20 @@
+import type { CommandRegistry } from '../command-registry.ts';
+import { openCommandPanel } from './runtime-services.ts';
+
+/**
+ * Register the /qrcode command.
+ *
+ * Opens the QR Code panel which displays a scannable QR code for
+ * companion app pairing, along with connection URL, token, and username.
+ */
+export function registerQrcodeRuntimeCommands(registry: CommandRegistry): void {
+  registry.register({
+    name: 'qrcode',
+    aliases: ['qr', 'pair'],
+    description: 'Open the QR code panel for companion app pairing',
+    usage: '',
+    handler(_args, ctx) {
+      openCommandPanel(ctx, 'qr-code');
+    },
+  });
+}

package/src/input/commands/quit-shared.ts

@@ -0,0 +1,162 @@
+import type { StatusResult } from 'simple-git';
+import { basename } from 'path';
+import type { CommandContext } from '../command-registry.ts';
+import { GitService } from '@pellux/goodvibes-sdk/platform/git';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+
+type GitLike = Pick<GitService, 'addAll' | 'status' | 'commit'>;
+
+export type GitChange = {
+  action: 'add' | 'update' | 'delete' | 'rename';
+  path: string;
+  from?: string;
+  to?: string;
+};
+
+type GitStatusLike = Pick<StatusResult, 'staged' | 'modified' | 'not_added' | 'deleted' | 'created' | 'renamed'> & {
+  isClean?: () => boolean;
+};
+
+export function collectGitChanges(status: GitStatusLike): GitChange[] {
+  const changes = new Map<string, GitChange>();
+
+  for (const rename of status.renamed ?? []) {
+    const to = rename.to || rename.from;
+    if (!to) continue;
+    changes.set(to, { action: 'rename', path: to, from: rename.from, to: rename.to });
+  }
+
+  for (const path of status.created ?? []) {
+    if (!changes.has(path)) changes.set(path, { action: 'add', path });
+  }
+
+  for (const path of status.not_added ?? []) {
+    if (!changes.has(path)) changes.set(path, { action: 'add', path });
+  }
+
+  for (const path of status.deleted ?? []) {
+    if (!changes.has(path)) changes.set(path, { action: 'delete', path });
+  }
+
+  for (const path of status.modified ?? []) {
+    if (!changes.has(path)) changes.set(path, { action: 'update', path });
+  }
+
+  for (const path of status.staged ?? []) {
+    if (!changes.has(path)) changes.set(path, { action: 'update', path });
+  }
+
+  return Array.from(changes.values()).sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function formatList(items: string[]): string {
+  if (items.length === 0) return '';
+  if (items.length === 1) return items[0]!;
+  if (items.length === 2) return `${items[0]} and ${items[1]}`;
+  return `${items.slice(0, -1).join(', ')}, and ${items[items.length - 1]}`;
+}
+
+function topLevelScope(path: string): string {
+  const normalized = path.replace(/\\/g, '/').replace(/^\.\/+/, '');
+  if (!normalized) return 'root';
+  const [first] = normalized.split('/');
+  return first && first.length > 0 ? first : 'root';
+}
+
+function summarizeScopes(changes: GitChange[]): string | null {
+  const scopes = Array.from(new Set(changes.map((change) => topLevelScope(change.path)).filter(Boolean)));
+  if (scopes.length === 0) return null;
+  if (scopes.length <= 3) {
+    return scopes.length === 1 ? `${scopes[0]} files` : `${formatList(scopes)} files`;
+  }
+  return `${changes.length} files`;
+}
+
+function shortPath(path: string): string {
+  return path.length > 42 ? basename(path) : path;
+}
+
+export function buildWriteQuitCommitMessage(changes: GitChange[]): string {
+  if (changes.length === 0) return 'Update working tree';
+
+  if (changes.length === 1) {
+    const [change] = changes;
+    if (!change) return 'Update working tree';
+    if (change.action === 'rename') {
+      return `Rename ${shortPath(change.from ?? change.path)} to ${shortPath(change.to ?? change.path)}`;
+    }
+    const verb = change.action === 'add'
+      ? 'Add'
+      : change.action === 'delete'
+        ? 'Delete'
+        : 'Update';
+    return `${verb} ${shortPath(change.path)}`;
+  }
+
+  const uniqueActions = Array.from(new Set(changes.map((change) => change.action)));
+  if (uniqueActions.length === 1) {
+    const [action] = uniqueActions;
+    const verb = action === 'add'
+      ? 'Add'
+      : action === 'delete'
+        ? 'Delete'
+        : action === 'rename'
+          ? 'Rename'
+          : 'Update';
+    const scopeLabel = summarizeScopes(changes);
+    if (scopeLabel) return `${verb} ${scopeLabel}`;
+    return `${verb} ${changes.length} files`;
+  }
+
+  const scopeLabel = summarizeScopes(changes);
+  if (scopeLabel) return `Update ${scopeLabel}`;
+  return `Update ${changes.length} files`;
+}
+
+export type ExecuteWriteQuitOptions = {
+  cwd?: string;
+  isGitRepo?: (cwd: string) => boolean;
+  getRepoRoot?: (cwd: string) => string | null;
+  gitFactory?: (cwd: string) => GitLike;
+};
+
+export async function executeWriteQuit(
+  ctx: Pick<CommandContext, 'print' | 'exit'> & {
+    workspace?: CommandContext['workspace'];
+  },
+  options: ExecuteWriteQuitOptions = {},
+): Promise<void> {
+  const cwd = options.cwd ?? ctx.workspace?.shellPaths?.workingDirectory;
+  if (!cwd) {
+    throw new Error('commandContext.workspace.shellPaths is required when executeWriteQuit() is called without an explicit cwd');
+  }
+  const isGitRepo = options.isGitRepo ?? ((dir: string) => GitService.isGitRepo(dir));
+  if (!isGitRepo(cwd)) {
+    ctx.exit();
+    return;
+  }
+
+  const repoRoot = options.getRepoRoot?.(cwd) ?? GitService.getRepoRoot(cwd) ?? cwd;
+  const git = options.gitFactory?.(repoRoot) ?? new GitService(repoRoot);
+
+  try {
+    ctx.print(`[wq] Staging changes in ${repoRoot}...`);
+    await git.addAll();
+    const status = await git.status();
+    if (status.isClean()) {
+      ctx.print('[wq] Working tree clean. Exiting without creating a commit.');
+      ctx.exit();
+      return;
+    }
+
+    const changes = collectGitChanges(status);
+    const message = buildWriteQuitCommitMessage(changes);
+    ctx.print(`[wq] Committing ${changes.length} change${changes.length === 1 ? '' : 's'}: ${message}`);
+    const result = await git.commit(message);
+    const shortHash = result.hash ? result.hash.slice(0, 7) : 'unknown';
+    ctx.print(`[wq] Commit complete: ${shortHash} ${message}`);
+    ctx.exit();
+  } catch (error) {
+    ctx.print(`[wq] Commit failed: ${summarizeError(error)}`);
+  }
+}

package/src/input/commands/recall-bundle.ts

@@ -0,0 +1,132 @@
+import { dirname } from 'node:path';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import type { CommandContext } from '../command-registry.ts';
+import type { MemoryBundle, MemorySearchFilter } from '@pellux/goodvibes-sdk/platform/state';
+import { VALID_CLASSES, VALID_SCOPES, isValidClass, isValidScope, resolveBundlePath } from './recall-shared.ts';
+import { requireShellPaths } from './runtime-services.ts';
+import { getMemoryApi } from './recall-query.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+
+export function handleRecallExport(args: string[], context: CommandContext): void {
+  const memory = getMemoryApi(context);
+  if (!memory) {
+    return;
+  }
+
+  const pathArg = args[0];
+  if (!pathArg) {
+    context.print('[recall] Usage: /recall export <path> [--scope <scope>] [--cls <class>]');
+    return;
+  }
+
+  const filter: MemorySearchFilter = {};
+  const scopeIdx = args.indexOf('--scope');
+  if (scopeIdx !== -1 && args[scopeIdx + 1]) {
+    const scope = args[scopeIdx + 1];
+    if (!isValidScope(scope)) {
+      context.print(`[recall] Unknown scope "${scope}". Valid: ${VALID_SCOPES.join(', ')}`);
+      return;
+    }
+    filter.scope = scope;
+  }
+
+  const clsIdx = args.indexOf('--cls');
+  if (clsIdx !== -1 && args[clsIdx + 1]) {
+    const cls = args[clsIdx + 1];
+    if (!isValidClass(cls)) {
+      context.print(`[recall] Unknown class "${cls}". Valid: ${VALID_CLASSES.join(', ')}`);
+      return;
+    }
+    filter.cls = cls;
+  }
+
+  const bundle = memory.exportBundle(filter);
+  const targetPath = resolveBundlePath(pathArg, requireShellPaths(context));
+  mkdirSync(dirname(targetPath), { recursive: true });
+  writeFileSync(targetPath, JSON.stringify(bundle, null, 2) + '\n', 'utf-8');
+  context.print(`[recall] Exported ${bundle.recordCount} record(s) and ${bundle.linkCount} link(s) to ${targetPath}`);
+}
+
+export async function handleRecallImport(args: string[], context: CommandContext): Promise<void> {
+  const memory = getMemoryApi(context);
+  if (!memory) {
+    return;
+  }
+
+  const pathArg = args[0];
+  if (!pathArg) {
+    context.print('[recall] Usage: /recall import <path>');
+    return;
+  }
+
+  const targetPath = resolveBundlePath(pathArg, requireShellPaths(context));
+  let bundle: MemoryBundle;
+  try {
+    bundle = JSON.parse(readFileSync(targetPath, 'utf-8')) as MemoryBundle;
+  } catch (error) {
+    context.print(`[recall] Failed to read memory bundle: ${summarizeError(error)}`);
+    return;
+  }
+
+  const result = await memory.importBundle(bundle);
+  context.print(`[recall] Imported bundle from ${targetPath}`);
+  context.print(`  Records: imported=${result.importedRecords} skipped=${result.skippedRecords}`);
+  context.print(`  Links:   imported=${result.importedLinks}`);
+}
+
+function inspectBundle(bundle: MemoryBundle): string {
+  return [
+    'Memory Handoff Review',
+    `  scope: ${bundle.scope}`,
+    `  records: ${bundle.recordCount}`,
+    `  links: ${bundle.linkCount}`,
+    `  exportedAt: ${new Date(bundle.exportedAt).toISOString()}`,
+  ].join('\n');
+}
+
+export function handleRecallHandoffExport(args: string[], context: CommandContext): void {
+  const memory = getMemoryApi(context);
+  if (!memory) {
+    return;
+  }
+  const pathArg = args[0];
+  if (!pathArg) {
+    context.print('[recall] Usage: /recall handoff-export <path> [--scope <scope>]');
+    return;
+  }
+  const scopeIdx = args.indexOf('--scope');
+  const scopeRaw = scopeIdx !== -1 ? args[scopeIdx + 1] : 'team';
+  if (!scopeRaw || !isValidScope(scopeRaw)) {
+    context.print(`[recall] Unknown scope "${scopeRaw ?? ''}". Valid: ${VALID_SCOPES.join(', ')}`);
+    return;
+  }
+  const bundle = memory.exportBundle({ scope: scopeRaw });
+  const targetPath = resolveBundlePath(pathArg, requireShellPaths(context));
+  mkdirSync(dirname(targetPath), { recursive: true });
+  writeFileSync(targetPath, JSON.stringify(bundle, null, 2) + '\n', 'utf-8');
+  context.print(`[recall] Exported ${scopeRaw} handoff bundle to ${targetPath}`);
+}
+
+export function handleRecallHandoffInspect(args: string[], context: CommandContext): void {
+  const pathArg = args[0];
+  if (!pathArg) {
+    context.print('[recall] Usage: /recall handoff-inspect <path>');
+    return;
+  }
+  const targetPath = resolveBundlePath(pathArg, requireShellPaths(context));
+  try {
+    const bundle = JSON.parse(readFileSync(targetPath, 'utf-8')) as MemoryBundle;
+    context.print(inspectBundle(bundle));
+  } catch (error) {
+    context.print(`[recall] Failed to inspect handoff bundle: ${summarizeError(error)}`);
+  }
+}
+
+export async function handleRecallHandoffImport(args: string[], context: CommandContext): Promise<void> {
+  const pathArg = args[0];
+  if (!pathArg) {
+    context.print('[recall] Usage: /recall handoff-import <path>');
+    return;
+  }
+  await handleRecallImport([pathArg], context);
+}