Skip to content

nanocoai/nanoclaw / .claude/skills/add-cursor

add-cursor

Flagged

Use Cursor (local Agent SDK) as a full agent provider — planning, tool orchestration, MCP tools, session resume — alongside or instead of Claude. Cursor-account sign-in or API key, held by the credential gateway. Per-group via `ncl groups config update --provider cursor`. Distinct from using Cursor as a cloud agent (those run on Cursor VMs and are not this provider).

payload/container/agent-runner/src/providers/cursor.factory.test.ts

View on GitHub
import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
import fs from 'fs';
import path from 'path';

import { AgentNotFoundError, CursorAgentError, type SDKMessage } from '@cursor/sdk';

import { MEMORY_SESSION_HOOK } from '../memory/session-hook.js';
import {
  CURSOR_API_KEY_PLACEHOLDER,
  CURSOR_DEFAULT_MODEL,
  CURSOR_DISALLOWED_TOOLS,
  CURSOR_MEMORY_HOOK_COMMAND,
  CursorProvider,
  createContentLengthFetch,
  cursorAgentApi,
  cursorExecutionPolicySection,
  cursorInferenceSection,
  cursorMemorySection,
  cursorRuntimeOwnership,
  extractAssistantText,
  mapMcpServers,
  toolProgressMessage,
  waitForRunWithActivity,
  writeCursorMemoryHooks,
} from './cursor.js';

let homeDir: string;
let agentDir: string;
let conversationsDir: string;
let previousHome: string | undefined;
let previousAgentDir: string | undefined;
let previousConversations: string | undefined;
let previousApiKey: string | undefined;
let previousNoProxy: string | undefined;
let previousLowerNoProxy: string | undefined;
let previousOwnership: boolean;

const TEST_ROOT = path.join(import.meta.dir, '..', '..', '.tmp-cursor-factory');

beforeEach(() => {
  fs.rmSync(TEST_ROOT, { recursive: true, force: true });
  fs.mkdirSync(TEST_ROOT, { recursive: true });
  homeDir = fs.mkdtempSync(path.join(TEST_ROOT, 'home-'));
  agentDir = fs.mkdtempSync(path.join(TEST_ROOT, 'agent-'));
  conversationsDir = fs.mkdtempSync(path.join(TEST_ROOT, 'conv-'));
  previousHome = process.env.HOME;
  previousAgentDir = process.env.NANOCLAW_AGENT_DIR;
  previousConversations = process.env.NANOCLAW_CONVERSATIONS_DIR;
  previousApiKey = process.env.CURSOR_API_KEY;
  previousNoProxy = process.env.NO_PROXY;
  previousLowerNoProxy = process.env.no_proxy;
  // Other test files in this process may have loaded the runtime contract,
  // which flips ownership; these tests exercise the provider's own (legacy)
  // path explicitly and restore whatever was set.
  previousOwnership = cursorRuntimeOwnership.contractOwnsHookFiles;
  cursorRuntimeOwnership.contractOwnsHookFiles = false;
  process.env.HOME = homeDir;
  process.env.NANOCLAW_AGENT_DIR = agentDir;
  process.env.NANOCLAW_CONVERSATIONS_DIR = conversationsDir;
  delete process.env.CURSOR_API_KEY;
  fs.mkdirSync(path.join(agentDir, 'memory', 'system'), { recursive: true });
  fs.writeFileSync(path.join(agentDir, 'memory', 'index.md'), 'factory-memory-sentinel\n');
  fs.writeFileSync(path.join(agentDir, 'memory', 'system', 'definition.md'), 'factory-definition\n');
});

afterEach(() => {
  cursorRuntimeOwnership.contractOwnsHookFiles = previousOwnership;
  if (previousHome === undefined) delete process.env.HOME;
  else process.env.HOME = previousHome;
  if (previousAgentDir === undefined) delete process.env.NANOCLAW_AGENT_DIR;
  else process.env.NANOCLAW_AGENT_DIR = previousAgentDir;
  if (previousConversations === undefined) delete process.env.NANOCLAW_CONVERSATIONS_DIR;
  else process.env.NANOCLAW_CONVERSATIONS_DIR = previousConversations;
  if (previousApiKey === undefined) delete process.env.CURSOR_API_KEY;
  else process.env.CURSOR_API_KEY = previousApiKey;
  if (previousNoProxy === undefined) delete process.env.NO_PROXY;
  else process.env.NO_PROXY = previousNoProxy;
  if (previousLowerNoProxy === undefined) delete process.env.no_proxy;
  else process.env.no_proxy = previousLowerNoProxy;
  fs.rmSync(TEST_ROOT, { recursive: true, force: true });
});

async function collect(provider: CursorProvider, input: { prompt: string; cwd: string; continuation?: string }) {
  const events = [];
  for await (const event of provider.query(input).events) events.push(event);
  return events;
}

function readHooks(file: string): { hooks: Record<string, Array<{ command: string }>>; [key: string]: unknown } {
  return JSON.parse(fs.readFileSync(file, 'utf-8'));
}

describe('configuration sections', () => {
  it('declares the fixed execution stance', () => {
    expect(cursorExecutionPolicySection()).toEqual({
      disallowedTools: ['askQuestion', 'await', 'task'],
      settingSources: ['project', 'user'],
      sandbox: { enabled: false },
    });
    expect(CURSOR_DISALLOWED_TOOLS).toEqual(['askQuestion', 'await', 'task']);
  });

  it('maps only the model onto the Cursor selection and defaults it', () => {
    expect(cursorInferenceSection({})).toEqual({ model: { id: CURSOR_DEFAULT_MODEL } });
    expect(cursorInferenceSection({ model: 'cursor-custom', effort: 'high', speed: 'fast' })).toEqual({
      model: { id: 'cursor-custom' },
    });
  });

  it('declares the memory hooks as a constant document', () => {
    expect(cursorMemorySection()).toEqual({
      version: 1,
      hooks: {
        sessionStart: [{ command: CURSOR_MEMORY_HOOK_COMMAND }],
        preCompact: [{ command: `${CURSOR_MEMORY_HOOK_COMMAND} --compact` }],
      },
    });
  });
});

describe('mapMcpServers / stream helpers', () => {
  it('sets Content-Length for byte bodies without buffering responses', async () => {
    let received: RequestInit | undefined;
    const response = new Response('streamed');
    const wrapped = createContentLengthFetch((async (_input, init) => {
      received = init;
      return response;
    }) as typeof fetch);

    const actual = await wrapped('https://api2.cursor.sh/rpc', {
      method: 'POST',
      body: new Uint8Array([1, 2]),
      headers: { 'content-type': 'application/proto' },
    });

    expect(new Headers(received?.headers).get('content-length')).toBe('2');
    expect(received?.body).toBeInstanceOf(Uint8Array);
    expect(actual).toBe(response);
  });

  it("keeps a Request's own headers when only the body is replaced", async () => {
    let received: RequestInit | undefined;
    const wrapped = createContentLengthFetch((async (_input, init) => {
      received = init;
      return new Response('{}');
    }) as typeof fetch);

    const request = new Request('https://api2.cursor.sh/rpc', {
      method: 'POST',
      headers: { authorization: 'Bearer cursor_placeholder_nanoclaw', 'content-type': 'application/json' },
    });
    await wrapped(request, { body: '{}' });

    const headers = new Headers(received?.headers);
    expect(headers.get('authorization')).toBe('Bearer cursor_placeholder_nanoclaw');
    expect(headers.get('content-type')).toBe('application/json');
    expect(headers.get('content-length')).toBe('2');
  });

  it('does not touch the proxy environment while wrapping requests', async () => {
    process.env.NO_PROXY = 'localhost';
    process.env.no_proxy = 'localhost';
    const observed: string[] = [];
    const wrapped = createContentLengthFetch((async () => {
      observed.push(process.env.NO_PROXY ?? '');
      return new Response('{}');
    }) as typeof fetch);

    await wrapped('https://api2.cursor.sh/auth/exchange_user_api_key', { method: 'POST', body: '{}' });
    await wrapped('https://api2.cursor.sh/aiserver.v1.DashboardService/GetUserPrivacyMode', {
      method: 'POST',
      body: new Uint8Array([0, 0, 0, 0, 0]),
    });

    expect(observed).toEqual(['localhost', 'localhost']);
    expect(process.env.NO_PROXY).toBe('localhost');
    expect(process.env.no_proxy).toBe('localhost');
  });

  it('maps NanoClaw stdio and HTTP MCP configs without dropping transport fields', () => {
    expect(
      mapMcpServers({
        nanoclaw: {
          command: 'bun',
          args: ['/app/src/mcp.ts'],
          env: { A: '1' },
          cwd: '/workspace/plugin',
        },
        remote: { type: 'http', url: 'https://mcp.example.test', headers: { Authorization: 'Bearer token' } },
      }),
    ).toEqual({
      nanoclaw: {
        type: 'stdio',
        command: 'bun',
        args: ['/app/src/mcp.ts'],
        env: { A: '1' },
        cwd: '/workspace/plugin',
      },
      remote: {
        type: 'http',
        url: 'https://mcp.example.test',
        headers: { Authorization: 'Bearer token' },
      },
    });
  });

  it('preserves MCP server names that overlap object prototype keys', () => {
    const mapped = mapMcpServers(
      JSON.parse('{"__proto__":{"command":"safe","args":[],"env":{}}}') as Record<
        string,
        { command: string; args: string[]; env: Record<string, string> }
      >,
    );
    expect(Object.hasOwn(mapped, '__proto__')).toBe(true);
    expect(mapped.__proto__).toEqual({ type: 'stdio', command: 'safe', args: [], env: {} });
  });

  it('extracts assistant text and tool progress from stream events', () => {
    const assistant: SDKMessage = {
      type: 'assistant',
      agent_id: 'agent-1',
      run_id: 'run-1',
      message: { role: 'assistant', content: [{ type: 'text', text: 'hello' }] },
    };
    const tool: SDKMessage = {
      type: 'tool_call',
      agent_id: 'agent-1',
      run_id: 'run-1',
      call_id: 'c1',
      name: 'shell',
      status: 'running',
    };
    expect(extractAssistantText(assistant)).toBe('hello');
    expect(toolProgressMessage(tool)).toBe('shell…');
  });

  it('keeps the poll-loop heartbeat alive while waiting without stream events', async () => {
    let finish!: (result: { id: string; status: 'finished'; result: string }) => void;
    const wait = new Promise<{ id: string; status: 'finished'; result: string }>((resolve) => {
      finish = resolve;
    });
    const events = waitForRunWithActivity({ wait: () => wait }, 1);

    expect(await events.next()).toEqual({ done: false, value: { type: 'activity' } });
    finish({ id: 'run-wait', status: 'finished', result: 'done' });
    expect(await events.next()).toEqual({
      done: true,
      value: { id: 'run-wait', status: 'finished', result: 'done' },
    });
  });
});

describe('memory hooks.json', () => {
  it('writes sessionStart / preCompact hooks under the project and $HOME', () => {
    writeCursorMemoryHooks();
    const projectHooks = readHooks(path.join(agentDir, '.cursor', 'hooks.json'));
    const homeHooks = readHooks(path.join(homeDir, '.cursor', 'hooks.json'));
    expect(projectHooks.hooks.sessionStart[0]?.command).toContain('cursor-hook.ts');
    expect(projectHooks.hooks.preCompact[0]?.command).toContain('--compact');
    expect(homeHooks).toEqual(projectHooks);
  });

  it('preserves unrelated Cursor hooks and does not duplicate NanoClaw hooks', () => {
    const projectCursorDir = path.join(agentDir, '.cursor');
    const homeCursorDir = path.join(homeDir, '.cursor');
    fs.mkdirSync(projectCursorDir, { recursive: true });
    fs.mkdirSync(homeCursorDir, { recursive: true });
    const existing = {
      version: 1,
      custom: { keep: true },
      hooks: {
        sessionStart: [{ command: 'bun custom-start.ts' }],
        stop: [{ command: 'bun custom-stop.ts' }],
      },
    };
    fs.writeFileSync(path.join(projectCursorDir, 'hooks.json'), JSON.stringify(existing));
    fs.writeFileSync(path.join(homeCursorDir, 'hooks.json'), JSON.stringify(existing));

    writeCursorMemoryHooks();
    writeCursorMemoryHooks();

    for (const file of [path.join(projectCursorDir, 'hooks.json'), path.join(homeCursorDir, 'hooks.json')]) {
      const doc = readHooks(file);
      expect(doc.custom).toEqual({ keep: true });
      expect(doc.hooks.stop).toEqual([{ command: 'bun custom-stop.ts' }]);
      expect(doc.hooks.sessionStart.map((hook) => hook.command)).toEqual([
        'bun custom-start.ts',
        'bun /app/src/providers/cursor-hook.ts',
      ]);
      expect(doc.hooks.preCompact).toEqual([{ command: 'bun /app/src/providers/cursor-hook.ts --compact' }]);
    }
  });

  it('leaves malformed Cursor hook documents unchanged', () => {
    const projectCursorDir = path.join(agentDir, '.cursor');
    fs.mkdirSync(projectCursorDir, { recursive: true });
    fs.writeFileSync(path.join(projectCursorDir, 'hooks.json'), '{broken');

    expect(() => writeCursorMemoryHooks()).not.toThrow();
    expect(fs.readFileSync(path.join(projectCursorDir, 'hooks.json'), 'utf-8')).toBe('{broken');
  });

  it('writes the hooks on registration only while the provider owns the files', () => {
    const projectHooks = path.join(agentDir, '.cursor', 'hooks.json');

    new CursorProvider().registerMemorySessionHook(MEMORY_SESSION_HOOK);
    expect(fs.existsSync(projectHooks)).toBe(true);

    fs.rmSync(projectHooks);
    cursorRuntimeOwnership.contractOwnsHookFiles = true;
    new CursorProvider().registerMemorySessionHook(MEMORY_SESSION_HOOK);
    expect(fs.existsSync(projectHooks)).toBe(false);
  });
});

describe('CursorProvider', () => {
  it('requires the shared memory hook before starting a query', () => {
    expect(() => new CursorProvider({}).query({ prompt: 'hello', cwd: agentDir })).toThrow(/not registered/);
  });

  it('treats AgentNotFoundError as an invalid session', () => {
    const provider = new CursorProvider();
    expect(provider.isSessionInvalid(new AgentNotFoundError('missing'))).toBe(true);
    expect(provider.isSessionInvalid(new Error('no conversation'))).toBe(true);
    expect(provider.isSessionInvalid(new Error('model not found'))).toBe(false);
    expect(provider.isSessionInvalid(new Error('rate limited'))).toBe(false);
  });

  it('archives completed exchanges through the shared per-thread plan', () => {
    const provider = new CursorProvider({ assistantName: 'Cursor' });
    provider.onExchangeComplete?.({ prompt: 'hi', result: 'hello', continuation: 'agent-1', status: 'completed' });
    provider.onExchangeComplete?.({ prompt: 'again', result: 'twice', continuation: 'agent-1', status: 'completed' });
    const files = fs.readdirSync(conversationsDir).filter((f) => f.endsWith('.md'));
    expect(files).toHaveLength(1);
    expect(files[0]).toMatch(/^\d{4}-\d{2}-\d{2}-cursor-agent-1\.md$/);
    const body = fs.readFileSync(path.join(conversationsDir, files[0]!), 'utf-8');
    expect(body).toContain('Provider: cursor');
    expect(body).toContain('**User**: hi');
    expect(body).toContain('**Assistant**: hello');
    expect(body).toContain('**User**: again');
  });

  it('creates, streams, and waits — yielding init/activity/result', async () => {
    const original = { ...cursorAgentApi };
    process.env.CURSOR_API_KEY = 'must_not_reach_cursor_sdk';
    cursorAgentApi.create = async (options) => {
      expect(options.apiKey).toBe(CURSOR_API_KEY_PLACEHOLDER);
      expect(options.model).toEqual({ id: 'composer-2.5' });
      expect(options.disallowedTools).toEqual(['askQuestion', 'await', 'task']);
      expect(options.local?.sandboxOptions).toEqual({ enabled: false });
      return {
        agentId: 'agent-created',
        send: async () => ({
          supports: (op: string) => op === 'stream' || op === 'wait' || op === 'cancel',
          stream: async function* () {
            yield {
              type: 'assistant',
              agent_id: 'agent-created',
              run_id: 'run-1',
              message: { role: 'assistant', content: [{ type: 'text', text: 'ok' }] },
            } satisfies SDKMessage;
          },
          wait: async () => ({ id: 'run-1', status: 'finished' as const, result: 'ok' }),
          cancel: async () => {},
        }),
        close: () => {},
      } as never;
    };
    try {
      const provider = new CursorProvider();
      provider.registerMemorySessionHook(MEMORY_SESSION_HOOK);
      const events = await collect(provider, { prompt: 'hi', cwd: agentDir });
      expect(events[0]).toEqual({ type: 'init', continuation: 'agent-created' });
      expect(events.some((e) => e.type === 'activity')).toBe(true);
      expect(events.at(-1)).toEqual({ type: 'result', text: 'ok' });
    } finally {
      cursorAgentApi.create = original.create;
      cursorAgentApi.resume = original.resume;
    }
  });

  it('consumes core-resolved configuration as-is when a contract core hands it over', async () => {
    const original = { ...cursorAgentApi };
    let received: Record<string, unknown> | undefined;
    cursorAgentApi.create = async (options) => {
      received = options as unknown as Record<string, unknown>;
      return {
        agentId: 'agent-configured',
        send: async () => ({
          supports: (op: string) => op === 'wait',
          wait: async () => ({ id: 'run-configured', status: 'finished' as const, result: 'done' }),
          cancel: async () => {},
        }),
        close: () => {},
      } as never;
    };
    try {
      const provider = new CursorProvider(
        // Options that would resolve differently are ignored in favour of the resolved configuration.
        { model: 'ignored-model', mcpServers: { ignored: { command: 'ignored' } } },
        {
          executionPolicy: { disallowedTools: ['await'], settingSources: ['project'], sandbox: { enabled: false } },
          inference: { model: { id: 'resolved-model' } },
          mcpServers: { resolved: { type: 'stdio', command: 'bun', args: [], env: {} } },
        },
      );
      provider.registerMemorySessionHook(MEMORY_SESSION_HOOK);
      await collect(provider, { prompt: 'configured', cwd: agentDir });
      expect(received?.model).toEqual({ id: 'resolved-model' });
      expect(received?.disallowedTools).toEqual(['await']);
      expect(received?.mcpServers).toEqual({ resolved: { type: 'stdio', command: 'bun', args: [], env: {} } });
      expect((received?.local as { settingSources: string[] }).settingSources).toEqual(['project']);
    } finally {
      cursorAgentApi.create = original.create;
      cursorAgentApi.resume = original.resume;
    }
  });

  it('resumes an existing agent, processes pushed follow-ups, and prepends system instructions to each', async () => {
    const original = { ...cursorAgentApi };
    const sent: string[] = [];
    cursorAgentApi.resume = async (id) => {
      expect(id).toBe('agent-resume');
      return {
        agentId: id,
        send: async (prompt: string) => {
          sent.push(prompt);
          return {
            supports: (op: string) => op === 'wait',
            wait: async () => ({ id: 'run-2', status: 'finished' as const, result: 'resumed' }),
            cancel: async () => {},
          };
        },
        close: () => {},
      } as never;
    };
    try {
      const provider = new CursorProvider();
      provider.registerMemorySessionHook(MEMORY_SESSION_HOOK);
      const query = provider.query({
        prompt: 'follow-up',
        cwd: agentDir,
        continuation: 'agent-resume',
        systemContext: { instructions: 'Be brief.' },
      });
      query.push('follow-up while active');
      query.end();
      const events = [];
      for await (const event of query.events) events.push(event);
      expect(sent[0]).toContain('Be brief.');
      expect(sent[0]).not.toContain('factory-memory-sentinel');
      expect(sent[0]).toContain('follow-up');
      expect(sent[1]).toBe('Be brief.\n\nfollow-up while active');
      expect(sent[1]).not.toContain('factory-memory-sentinel');
      expect(events[0]).toEqual({ type: 'init', continuation: 'agent-resume' });
      expect(events.filter((event) => event.type === 'result')).toHaveLength(2);
      expect(events.at(-1)).toEqual({ type: 'result', text: 'resumed' });
    } finally {
      cursorAgentApi.create = original.create;
      cursorAgentApi.resume = original.resume;
    }
  });

  it('passes custom model, name, directories, MCP servers, and instructions on create', async () => {
    const original = { ...cursorAgentApi };
    let sent = '';
    cursorAgentApi.create = async (options) => {
      expect(options.name).toBe('Buildbot');
      expect(options.model).toEqual({ id: 'cursor-custom' });
      expect(options.local?.cwd).toBe(agentDir);
      expect(options.local?.dirs).toEqual(['/workspace/shared', '/workspace/docs']);
      expect(options.local?.settingSources).toEqual(['project', 'user']);
      expect(options.mcpServers).toEqual({
        first: { type: 'stdio', command: 'bun', args: ['one.ts'], env: { TOKEN: 'placeholder' } },
        second: { type: 'stdio', command: 'node', args: ['two.js'], env: {} },
      });
      return {
        agentId: 'agent-options',
        send: async (prompt: string) => {
          sent = prompt;
          return {
            supports: (op: string) => op === 'wait',
            wait: async () => ({ id: 'run-options', status: 'finished' as const, result: 'done' }),
            cancel: async () => {},
          };
        },
        close: () => {},
      } as never;
    };
    try {
      const provider = new CursorProvider({
        assistantName: 'Buildbot',
        model: 'cursor-custom',
        additionalDirectories: ['/workspace/shared', '/workspace/docs'],
        mcpServers: {
          first: { command: 'bun', args: ['one.ts'], env: { TOKEN: 'placeholder' } },
          second: { command: 'node', args: ['two.js'], env: {} },
        },
      });
      provider.registerMemorySessionHook(MEMORY_SESSION_HOOK);
      const events = await collect(provider, {
        prompt: 'build it',
        cwd: agentDir,
        systemContext: { instructions: 'Use the configured MCP tools.' },
      });
      expect(sent).toContain('Use the configured MCP tools.');
      expect(sent).toContain('factory-memory-sentinel');
      expect(sent).toContain('build it');
      expect(sent.startsWith('Use the configured MCP tools.')).toBe(true);
      expect(sent.endsWith('build it')).toBe(true);
      expect(events.at(-1)).toEqual({ type: 'result', text: 'done' });
    } finally {
      cursorAgentApi.create = original.create;
      cursorAgentApi.resume = original.resume;
    }
  });

  it('accepts a corrective push after yielding a result', async () => {
    const original = { ...cursorAgentApi };
    const sent: string[] = [];
    cursorAgentApi.create = async () =>
      ({
        agentId: 'agent-corrective-push',
        send: async (prompt: string) => {
          sent.push(prompt);
          return {
            supports: (op: string) => op === 'wait',
            wait: async () => ({
              id: `run-${sent.length}`,
              status: 'finished' as const,
              result: `result-${sent.length}`,
            }),
            cancel: async () => {},
          };
        },
        close: () => {},
      }) as never;
    try {
      const provider = new CursorProvider();
      provider.registerMemorySessionHook(MEMORY_SESSION_HOOK);
      const query = provider.query({ prompt: 'initial', cwd: agentDir });
      const iterator = query.events[Symbol.asyncIterator]();
      expect((await iterator.next()).value).toEqual({ type: 'init', continuation: 'agent-corrective-push' });
      expect((await iterator.next()).value).toEqual({ type: 'activity' });
      expect((await iterator.next()).value).toEqual({ type: 'result', text: 'result-1' });

      query.push('wrap the answer');

      expect((await iterator.next()).value).toEqual({ type: 'activity' });
      expect((await iterator.next()).value).toEqual({ type: 'result', text: 'result-2' });
      expect(await iterator.next()).toEqual({ done: true, value: undefined });
      expect(sent[0]).toContain('factory-memory-sentinel');
      expect(sent[0]).toContain('initial');
      expect(sent[1]).toBe('wrap the answer');
    } finally {
      cursorAgentApi.create = original.create;
      cursorAgentApi.resume = original.resume;
    }
  });

  it('recovers a resumed agent whose persisted run was left active by a crash', async () => {
    const original = { ...cursorAgentApi };
    const sends: Array<{ prompt: string; force?: boolean }> = [];
    cursorAgentApi.resume = async () =>
      ({
        agentId: 'agent-stale-run',
        send: async (prompt: string, options?: { local?: { force?: boolean } }) => {
          sends.push({ prompt, force: options?.local?.force });
          if (sends.length === 1) throw new Error('Agent agent-stale-run already has active run');
          return {
            supports: (op: string) => op === 'wait',
            wait: async () => ({ id: 'run-recovered', status: 'finished' as const, result: 'recovered' }),
            cancel: async () => {},
          };
        },
        close: () => {},
      }) as never;
    try {
      const provider = new CursorProvider();
      provider.registerMemorySessionHook(MEMORY_SESSION_HOOK);
      const events = await collect(provider, {
        prompt: 'continue',
        cwd: agentDir,
        continuation: 'agent-stale-run',
      });
      expect(sends).toHaveLength(2);
      expect(sends[0]?.force).toBeUndefined();
      expect(sends[1]?.force).toBe(true);
      expect(sends[0]?.prompt).not.toContain('factory-memory-sentinel');
      expect(sends[0]?.prompt).toContain('continue');
      expect(sends[1]?.prompt).toBe(sends[0]?.prompt);
      expect(events.at(-1)).toEqual({ type: 'result', text: 'recovered' });
    } finally {
      cursorAgentApi.create = original.create;
      cursorAgentApi.resume = original.resume;
    }
  });

  it('propagates an invalid continuation so the poll loop can clear it', async () => {
    const original = { ...cursorAgentApi };
    cursorAgentApi.resume = async () => {
      throw new AgentNotFoundError('missing');
    };
    try {
      const provider = new CursorProvider();
      provider.registerMemorySessionHook(MEMORY_SESSION_HOOK);
      await expect(
        collect(provider, {
          prompt: 'continue',
          cwd: agentDir,
          continuation: 'agent-missing',
        }),
      ).rejects.toBeInstanceOf(AgentNotFoundError);
    } finally {
      cursorAgentApi.create = original.create;
      cursorAgentApi.resume = original.resume;
    }
  });

  it('maps every terminal run state and falls back to streamed assistant text', async () => {
    const original = { ...cursorAgentApi };
    const cases = [
      {
        result: { id: 'run-finished', status: 'finished' as const },
        streamText: 'stream fallback',
        expected: { type: 'result', text: 'stream fallback' },
      },
      {
        result: { id: 'run-error', status: 'error' as const, result: 'partial', error: { message: 'model failed' } },
        streamText: 'streamed',
        expected: { type: 'result', text: 'partial', isError: true, error: 'model failed' },
      },
      {
        // Model text never becomes the channel notice: it may hold scratchpad.
        result: { id: 'run-error-bare', status: 'error' as const, result: '<internal>draft</internal>' },
        streamText: '',
        expected: { type: 'result', text: '<internal>draft</internal>', isError: true, error: 'Cursor run failed' },
      },
      {
        result: { id: 'run-cancelled', status: 'cancelled' as const },
        streamText: '',
        expected: { type: 'result', text: null, isError: true, error: 'Cancelled' },
      },
    ];
    try {
      for (const testCase of cases) {
        let closed = 0;
        cursorAgentApi.create = async () =>
          ({
            agentId: `agent-${testCase.result.id}`,
            send: async () => ({
              supports: (op: string) => op === 'stream' || op === 'wait',
              stream: async function* () {
                if (testCase.streamText) {
                  yield {
                    type: 'assistant',
                    agent_id: 'agent',
                    run_id: testCase.result.id,
                    message: { role: 'assistant', content: [{ type: 'text', text: testCase.streamText }] },
                  } satisfies SDKMessage;
                }
              },
              wait: async () => testCase.result,
              cancel: async () => {},
            }),
            close: () => {
              closed += 1;
            },
          }) as never;
        const provider = new CursorProvider();
        provider.registerMemorySessionHook(MEMORY_SESSION_HOOK);
        const events = await collect(provider, { prompt: 'state', cwd: agentDir });
        expect(events.at(-1)).toEqual(testCase.expected);
        if (testCase.result.status === 'cancelled') {
          expect(events).toContainEqual({ type: 'error', message: 'Cancelled', retryable: false });
        }
        expect(closed).toBe(1);
      }
    } finally {
      cursorAgentApi.create = original.create;
      cursorAgentApi.resume = original.resume;
    }
  });

  it('closes the agent after send, stream, and wait failures', async () => {
    const original = { ...cursorAgentApi };
    try {
      for (const stage of ['send', 'stream', 'wait'] as const) {
        let closed = 0;
        cursorAgentApi.create = async () =>
          ({
            agentId: `agent-${stage}`,
            send: async () => {
              if (stage === 'send') throw new Error('send exploded');
              return {
                supports: (op: string) => op === 'wait' || (stage === 'stream' && op === 'stream'),
                stream: async function* () {
                  throw new Error('stream exploded');
                },
                wait: async () => {
                  if (stage === 'wait') throw new Error('wait exploded');
                  return { id: 'unused', status: 'finished' as const };
                },
                cancel: async () => {},
              };
            },
            close: () => {
              closed += 1;
            },
          }) as never;
        const provider = new CursorProvider();
        provider.registerMemorySessionHook(MEMORY_SESSION_HOOK);
        const events = await collect(provider, { prompt: stage, cwd: agentDir });
        expect(events).toContainEqual({ type: 'error', message: `${stage} exploded`, retryable: false });
        expect(events.at(-1)).toEqual({ type: 'result', text: null, isError: true, error: `${stage} exploded` });
        expect(closed).toBe(1);
      }
    } finally {
      cursorAgentApi.create = original.create;
      cursorAgentApi.resume = original.resume;
    }
  });

  it('aborts safely while agent creation is pending', async () => {
    const original = { ...cursorAgentApi };
    let resolveCreate!: (agent: unknown) => void;
    let closed = 0;
    cursorAgentApi.create = (() =>
      new Promise((resolve) => {
        resolveCreate = resolve;
      })) as typeof cursorAgentApi.create;
    try {
      const provider = new CursorProvider();
      provider.registerMemorySessionHook(MEMORY_SESSION_HOOK);
      const query = provider.query({ prompt: 'abort', cwd: agentDir });
      const iterator = query.events[Symbol.asyncIterator]();
      const pending = iterator.next();
      query.abort();
      resolveCreate({
        agentId: 'agent-aborted',
        send: async () => {
          throw new Error('must not send');
        },
        close: () => {
          closed += 1;
        },
      });
      expect(await pending).toEqual({ done: true, value: undefined });
      expect(closed).toBe(1);
    } finally {
      cursorAgentApi.create = original.create;
      cursorAgentApi.resume = original.resume;
    }
  });

  it('cancels exactly once when aborted while send is pending and swallows cancellation failure', async () => {
    const original = { ...cursorAgentApi };
    let resolveSend!: (run: unknown) => void;
    let cancelCalls = 0;
    let closed = 0;
    cursorAgentApi.create = async () =>
      ({
        agentId: 'agent-abort-send',
        send: () =>
          new Promise((resolve) => {
            resolveSend = resolve;
          }),
        close: () => {
          closed += 1;
        },
      }) as never;
    try {
      const provider = new CursorProvider();
      provider.registerMemorySessionHook(MEMORY_SESSION_HOOK);
      const query = provider.query({ prompt: 'abort', cwd: agentDir });
      const iterator = query.events[Symbol.asyncIterator]();
      expect(await iterator.next()).toEqual({
        done: false,
        value: { type: 'init', continuation: 'agent-abort-send' },
      });
      expect(await iterator.next()).toEqual({ done: false, value: { type: 'activity' } });
      const pending = iterator.next();
      query.abort();
      resolveSend({
        supports: (op: string) => op === 'cancel',
        cancel: async () => {
          cancelCalls += 1;
          throw new Error('cancel exploded');
        },
      });
      expect(await pending).toEqual({ done: true, value: undefined });
      expect(cancelCalls).toBe(1);
      expect(closed).toBe(1);
    } finally {
      cursorAgentApi.create = original.create;
      cursorAgentApi.resume = original.resume;
    }
  });

  it('maps CursorAgentError retryability onto provider error events', async () => {
    const original = { ...cursorAgentApi };
    cursorAgentApi.create = async () => {
      throw new CursorAgentError('upstream blip', { isRetryable: true, code: 'network' });
    };
    try {
      const provider = new CursorProvider();
      provider.registerMemorySessionHook(MEMORY_SESSION_HOOK);
      const events = await collect(provider, { prompt: 'hi', cwd: agentDir });
      expect(events).toContainEqual({
        type: 'error',
        message: 'upstream blip',
        retryable: true,
        classification: 'network',
      });
      expect(events.at(-1)).toEqual({ type: 'result', text: null, isError: true, error: 'upstream blip' });
    } finally {
      cursorAgentApi.create = original.create;
      cursorAgentApi.resume = original.resume;
    }
  });
});
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall