@cursor/july 0.1.20 → 0.1.21

package/src/internal/approvals.integration.test.ts

@@ -0,0 +1,383 @@
+/**
+ * Integration: mock AgentRunner parks on needsApproval; resolve unblocks.
+ */
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { httpChannel } from "../channels.js";
+import { defineTool } from "../tools.js";
+import type { AgentProject, RunnerTurnRequest, ToolContext } from "../types.js";
+import type { AgentRunner } from "./sdk-runner.js";
+import { SessionAuthError, SessionEngine } from "./session-engine.js";
+
+function makeHitlProject(executeFlag: { called: boolean }): AgentProject {
+  const definition = defineTool({
+    description: "A risky tool that needs approval",
+    needsApproval: true,
+    async execute(input: { note?: string }, _ctx: ToolContext) {
+      executeFlag.called = true;
+      return { ok: true, note: input.note ?? "" };
+    },
+  });
+
+  return {
+    rootDir: "/tmp/hitl-fixture",
+    agentDir: "/tmp/hitl-fixture/agent",
+    name: "hitl-fixture",
+    agent: {
+      name: "hitl-fixture",
+      runtime: "local",
+      tools: [
+        {
+          name: "risky_action",
+          description: definition.description,
+          execution: "server",
+          needsApproval: true,
+          inputSchema: {
+            type: "object",
+            properties: { note: { type: "string" } },
+            additionalProperties: false,
+          },
+          definition,
+        },
+      ],
+      skills: [],
+      connections: [],
+      subagents: [],
+      seedFiles: [],
+    },
+    httpChannel: httpChannel(),
+    channels: [],
+    schedules: [],
+    hooks: [],
+    abs: [],
+    diagnostics: [],
+  };
+}
+
+describe("human-in-the-loop approvals (integration)", () => {
+  let stateRoot: string | undefined;
+
+  afterEach(async () => {
+    if (stateRoot !== undefined) {
+      await rm(stateRoot, { recursive: true, force: true });
+      stateRoot = undefined;
+    }
+  });
+
+  it("parks risky_action until approve, then finishes the turn", async () => {
+    stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-hitl-"));
+    const executeFlag = { called: false };
+    const project = makeHitlProject(executeFlag);
+
+    const runner: AgentRunner = {
+      async runTurn(request: RunnerTurnRequest) {
+        const tool = request.customTools.risky_action;
+        if (tool === undefined) {
+          throw new Error("risky_action not registered");
+        }
+        const result = await tool.execute(
+          { note: "ship it" },
+          { toolCallId: "call_alert_1" }
+        );
+        expect(result).toMatchObject({ ok: true, note: "ship it" });
+        return {
+          status: "finished",
+          result: "done",
+        };
+      },
+    };
+
+    const engine = new SessionEngine({
+      project,
+      stateRoot,
+      runner,
+    });
+
+    const auth = {
+      authenticator: "local-dev",
+      principalId: "loopback",
+      principalType: "user" as const,
+    };
+
+    const sessionPromise = engine.send("http", "please run risky action", {
+      auth,
+    });
+
+    let callId: string | undefined;
+    let sessionId: string | undefined;
+    for (let i = 0; i < 100; i++) {
+      const sessions = await engine.sessions.list();
+      if (sessions.length > 0) {
+        sessionId = sessions[0]!.sessionId;
+        const pending = await engine.listPendingApprovals(sessionId);
+        if (pending.length > 0) {
+          callId = pending[0]!.callId;
+          break;
+        }
+      }
+      await new Promise((r) => setTimeout(r, 20));
+    }
+
+    expect(sessionId).toBeDefined();
+    expect(callId).toBe("call_alert_1");
+    expect(executeFlag.called).toBe(false);
+
+    await engine.resolveApproval(sessionId!, callId!, "approve", auth);
+
+    const session = await sessionPromise;
+    await session.waitForCompletion();
+
+    expect(executeFlag.called).toBe(true);
+
+    const events = await engine.listEvents(session.id);
+    const types = events.map((e) => e.type);
+    expect(types).toContain("action.approval_requested");
+    expect(types).toContain("action.approval_resolved");
+    expect(types).toContain("session.waiting");
+
+    await engine.close();
+  });
+
+  it("rejects approval resolution from a different principal", async () => {
+    stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-hitl-"));
+    const executeFlag = { called: false };
+    const project = makeHitlProject(executeFlag);
+
+    const runner: AgentRunner = {
+      async runTurn(request: RunnerTurnRequest) {
+        const tool = request.customTools.risky_action;
+        if (tool === undefined) {
+          throw new Error("risky_action not registered");
+        }
+        await tool.execute({ note: "ship it" }, { toolCallId: "call_alert_2" });
+        return { status: "finished", result: "done" };
+      },
+    };
+
+    const engine = new SessionEngine({
+      project,
+      stateRoot,
+      runner,
+    });
+
+    const ownerAuth = {
+      authenticator: "local-dev",
+      principalId: "owner",
+      principalType: "user" as const,
+    };
+    const otherAuth = {
+      authenticator: "local-dev",
+      principalId: "other",
+      principalType: "user" as const,
+    };
+
+    void engine.send("http", "please run risky action", { auth: ownerAuth });
+
+    let callId: string | undefined;
+    let sessionId: string | undefined;
+    for (let i = 0; i < 100; i++) {
+      const sessions = await engine.sessions.list();
+      if (sessions.length > 0) {
+        sessionId = sessions[0]!.sessionId;
+        const pending = await engine.listPendingApprovals(sessionId);
+        if (pending.length > 0) {
+          callId = pending[0]!.callId;
+          break;
+        }
+      }
+      await new Promise((r) => setTimeout(r, 20));
+    }
+
+    expect(sessionId).toBeDefined();
+    expect(callId).toBeDefined();
+
+    await expect(
+      engine.resolveApproval(sessionId!, callId!, "approve", otherAuth)
+    ).rejects.toThrow(SessionAuthError);
+
+    // Deny as owner so the parked turn can finish before close().
+    await engine.resolveApproval(sessionId!, callId!, "deny", ownerAuth);
+    await engine.close();
+  });
+
+  it("asSessionOwner bridge lets a non-owner resolve Slack-owned approvals", async () => {
+    stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-hitl-"));
+    const executeFlag = { called: false };
+    const project = makeHitlProject(executeFlag);
+
+    const runner: AgentRunner = {
+      async runTurn(request: RunnerTurnRequest) {
+        const tool = request.customTools.risky_action;
+        if (tool === undefined) {
+          throw new Error("risky_action not registered");
+        }
+        await tool.execute({ note: "bridge" }, { toolCallId: "call_bridge_1" });
+        return { status: "finished", result: "done" };
+      },
+    };
+
+    const engine = new SessionEngine({
+      project,
+      stateRoot,
+      runner,
+    });
+
+    const slackAuth = {
+      authenticator: "slack",
+      principalId: "slack:T:C:123.456",
+      principalType: "user" as const,
+      attributes: {
+        channel_id: "C",
+        thread_ts: "123.456",
+        user_id: "U_OWNER",
+      },
+    };
+    const playgroundAuth = {
+      authenticator: "allow-all",
+      principalId: "anonymous",
+      principalType: "user" as const,
+    };
+
+    const sessionPromise = engine.send("http", "please run risky action", {
+      auth: slackAuth,
+    });
+
+    let callId: string | undefined;
+    let sessionId: string | undefined;
+    for (let i = 0; i < 100; i++) {
+      const sessions = await engine.sessions.list();
+      if (sessions.length > 0) {
+        sessionId = sessions[0]!.sessionId;
+        const pending = await engine.listPendingApprovals(sessionId);
+        if (pending.length > 0) {
+          callId = pending[0]!.callId;
+          break;
+        }
+      }
+      await new Promise((r) => setTimeout(r, 20));
+    }
+
+    expect(sessionId).toBeDefined();
+    expect(callId).toBeDefined();
+
+    await expect(
+      engine.resolveApproval(sessionId!, callId!, "approve", playgroundAuth)
+    ).rejects.toThrow(SessionAuthError);
+
+    await engine.resolveApproval(
+      sessionId!,
+      callId!,
+      "approve",
+      playgroundAuth,
+      { asSessionOwner: true }
+    );
+
+    const session = await sessionPromise;
+    await session.waitForCompletion();
+
+    expect(executeFlag.called).toBe(true);
+
+    const events = await engine.listEvents(session.id);
+    const resolved = events.find((e) => e.type === "action.approval_resolved");
+    expect(resolved?.type).toBe("action.approval_resolved");
+    if (resolved?.type === "action.approval_resolved") {
+      expect(resolved.data.by).toBe("anonymous");
+      expect(resolved.data.decision).toBe("approve");
+    }
+
+    await engine.close();
+  });
+
+  it("parks when needsApproval predicate returns true (input-only)", async () => {
+    stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-hitl-"));
+    const executeFlag = { called: false };
+    const definition = defineTool({
+      description: "Conditional risky tool",
+      needsApproval: (input: { urgent?: boolean }) => input.urgent === true,
+      async execute(_input: { urgent?: boolean }, _ctx: ToolContext) {
+        executeFlag.called = true;
+        return { ok: true };
+      },
+    });
+    const project: AgentProject = {
+      rootDir: "/tmp/hitl-fixture",
+      agentDir: "/tmp/hitl-fixture/agent",
+      name: "hitl-fixture",
+      agent: {
+        name: "hitl-fixture",
+        runtime: "local",
+        tools: [
+          {
+            name: "conditional_risky",
+            description: definition.description,
+            execution: "server",
+            needsApproval: true,
+            inputSchema: {
+              type: "object",
+              properties: { urgent: { type: "boolean" } },
+              additionalProperties: false,
+            },
+            definition,
+          },
+        ],
+        skills: [],
+        connections: [],
+        subagents: [],
+        seedFiles: [],
+      },
+      httpChannel: httpChannel(),
+      channels: [],
+      schedules: [],
+      hooks: [],
+      abs: [],
+      diagnostics: [],
+    };
+
+    const runner: AgentRunner = {
+      async runTurn(request: RunnerTurnRequest) {
+        const tool = request.customTools.conditional_risky;
+        if (tool === undefined) {
+          throw new Error("conditional_risky not registered");
+        }
+        await tool.execute({ urgent: true }, { toolCallId: "call_pred_1" });
+        return { status: "finished", result: "done" };
+      },
+    };
+
+    const engine = new SessionEngine({ project, stateRoot, runner });
+    const auth = {
+      authenticator: "local-dev",
+      principalId: "loopback",
+      principalType: "user" as const,
+    };
+
+    const sessionPromise = engine.send("http", "urgent action", { auth });
+
+    let callId: string | undefined;
+    let sessionId: string | undefined;
+    for (let i = 0; i < 100; i++) {
+      const sessions = await engine.sessions.list();
+      if (sessions.length > 0) {
+        sessionId = sessions[0]!.sessionId;
+        const pending = await engine.listPendingApprovals(sessionId);
+        if (pending.length > 0) {
+          callId = pending[0]!.callId;
+          break;
+        }
+      }
+      await new Promise((r) => setTimeout(r, 20));
+    }
+
+    expect(callId).toBe("call_pred_1");
+    expect(executeFlag.called).toBe(false);
+
+    await engine.resolveApproval(sessionId!, callId!, "approve", auth);
+    const session = await sessionPromise;
+    await session.waitForCompletion();
+    expect(executeFlag.called).toBe(true);
+    await engine.close();
+  });
+});

package/src/internal/authored-loaders.test.ts

@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { AUTHORING_ENTRY_FILES } from "./distribution.js";
+
+describe("AUTHORING_ENTRY_FILES", () => {
+  it("mirrors the package exports map (the runtime alias hooks derive their targets from it)", () => {
+    const pkg = JSON.parse(
+      readFileSync(new URL("../../package.json", import.meta.url), "utf8")
+    ) as {
+      exports: Record<string, string | { import?: string }>;
+    };
+    const fromExports = Object.entries(pkg.exports)
+      .filter(
+        ([exportPath, conditions]) =>
+          typeof conditions !== "string" && exportPath !== "./package.json"
+      )
+      .map(([exportPath, conditions]) => {
+        const subpath =
+          exportPath === "." ? "" : exportPath.replace(/^\.\//, "");
+        const importTarget = (conditions as { import?: string }).import;
+        expect(
+          importTarget,
+          `exports["${exportPath}"] must have an import condition`
+        ).toBeDefined();
+        return [subpath, importTarget?.replace(/^\.\/dist\//, "")];
+      });
+    expect(AUTHORING_ENTRY_FILES.map((entry) => [...entry])).toEqual(
+      fromExports
+    );
+  });
+});

package/src/internal/builtin-tools/reminders.test.ts

@@ -0,0 +1,201 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { httpChannel } from "../../channels.js";
+import type { AgentProject, ReminderInfo, SessionRecord } from "../../types.js";
+import { ReminderRunner } from "../reminder-runner.js";
+import { SessionEngine } from "../session-engine.js";
+import { builtinTools } from "./index.js";
+
+function testProject(rootDir: string): AgentProject {
+  return {
+    rootDir,
+    agentDir: join(rootDir, "agent"),
+    name: "builtin-reminders-test",
+    agent: {
+      name: "builtin-reminders-test",
+      runtime: "local",
+      instructions: "Test agent instructions.",
+      tools: builtinTools({ reminders: true }),
+      skills: [],
+      connections: [],
+      subagents: [],
+      seedFiles: [],
+    },
+    httpChannel: httpChannel(),
+    channels: [],
+    schedules: [],
+    hooks: [],
+    abs: [],
+    diagnostics: [],
+  };
+}
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  while (cleanups.length > 0) {
+    await cleanups.pop()?.();
+  }
+});
+
+async function makeEngine(): Promise<SessionEngine> {
+  const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-builtin-rem-"));
+  cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
+  const engine = new SessionEngine({
+    project: testProject(stateRoot),
+    stateRoot,
+    runner: {
+      runTurn: () => {
+        throw new Error("no model turns in this test");
+      },
+    },
+  });
+  engine.setReminders(new ReminderRunner(engine));
+  return engine;
+}
+
+async function saveSession(
+  engine: SessionEngine,
+  sessionId: string,
+  continuationKey: string | null
+): Promise<void> {
+  const record: SessionRecord = {
+    sessionId,
+    channelId: "http",
+    mode: "chat",
+    continuationKey,
+    auth: null,
+    turnCount: 0,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+  await engine.sessions.save(record);
+}
+
+describe("built-in reminder tools", () => {
+  it("creates, lists, and cancels a reminder bound to the conversation", async () => {
+    const engine = await makeEngine();
+    await saveSession(engine, "ses_a", "conv:a");
+
+    const created = await engine.callTool(
+      "reminders_create",
+      {
+        prompt: "Re-check CI.",
+        every: "30m",
+        until: "Cancel once CI is green.",
+      },
+      { sessionId: "ses_a" }
+    );
+    expect(created.isError).toBe(false);
+    const reminder = created.result as { reminderId: string; until: string };
+    expect(reminder.reminderId).toMatch(/^rem_/);
+    expect(reminder.until).toBe("Cancel once CI is green.");
+
+    const listed = await engine.callTool(
+      "reminders_list",
+      {},
+      { sessionId: "ses_a" }
+    );
+    const list = listed.result as { reminders: Array<{ reminderId: string }> };
+    expect(list.reminders.map((r) => r.reminderId)).toEqual([
+      reminder.reminderId,
+    ]);
+
+    const cancelled = await engine.callTool(
+      "reminders_cancel",
+      { id: reminder.reminderId },
+      { sessionId: "ses_a" }
+    );
+    expect(cancelled.isError).toBe(false);
+    expect(cancelled.result).toEqual({
+      reminderId: reminder.reminderId,
+      status: "cancelled",
+    });
+
+    const after = await engine.callTool(
+      "reminders_list",
+      {},
+      { sessionId: "ses_a" }
+    );
+    expect((after.result as { reminders: unknown[] }).reminders).toEqual([]);
+  });
+
+  it("refuses to cancel another conversation's reminder", async () => {
+    const engine = await makeEngine();
+    await saveSession(engine, "ses_a", "conv:a");
+    await saveSession(engine, "ses_b", "conv:b");
+
+    const created = await engine.callTool(
+      "reminders_create",
+      { prompt: "wake", delay: "5m" },
+      { sessionId: "ses_a" }
+    );
+    const { reminderId } = created.result as { reminderId: string };
+
+    const foreign = await engine.callTool(
+      "reminders_cancel",
+      { id: reminderId },
+      { sessionId: "ses_b" }
+    );
+    expect(foreign.isError).toBe(true);
+    expect(foreign.errorMessage).toContain("in this conversation");
+
+    const mine = await engine.host.reminders?.list({ status: "armed" });
+    expect((mine as ReminderInfo[]).map((r) => r.id)).toEqual([reminderId]);
+  });
+
+  it("keeps reminders addressed across HTTP continuation rotation", async () => {
+    const engine = await makeEngine();
+    await saveSession(engine, "ses_a", "conv:a");
+
+    const created = await engine.callTool(
+      "reminders_create",
+      { prompt: "wake", delay: "5m" },
+      { sessionId: "ses_a" }
+    );
+    const { reminderId } = created.result as { reminderId: string };
+
+    // The built-in HTTP channel rotates the token after every follow-up.
+    await engine.setContinuationToken("ses_a", "conv:rotated");
+
+    const listed = await engine.callTool(
+      "reminders_list",
+      {},
+      { sessionId: "ses_a" }
+    );
+    const list = listed.result as { reminders: Array<{ reminderId: string }> };
+    expect(list.reminders.map((r) => r.reminderId)).toEqual([reminderId]);
+
+    // Fire path must still resolve the session (no session_gone disarm).
+    const dispatched = await engine.host.reminders?.dispatch(reminderId);
+    expect(dispatched).toMatchObject({ outcome: "fired", reason: "delivered" });
+  });
+
+  it("rejects sub-minute recurring reminders", async () => {
+    const engine = await makeEngine();
+    await saveSession(engine, "ses_a", "conv:a");
+
+    const outcome = await engine.callTool(
+      "reminders_create",
+      { prompt: "wake", every: "5s" },
+      { sessionId: "ses_a" }
+    );
+    expect(outcome.isError).toBe(true);
+    expect(outcome.errorMessage).toContain('every >= "1m"');
+  });
+
+  it("rejects creates from sessions without a continuation key", async () => {
+    const engine = await makeEngine();
+    await saveSession(engine, "ses_nokey", null);
+
+    const outcome = await engine.callTool(
+      "reminders_create",
+      { prompt: "wake", delay: "5m" },
+      { sessionId: "ses_nokey" }
+    );
+    expect(outcome.isError).toBe(true);
+    expect(outcome.errorMessage).toContain("followable");
+  });
+});