@cursor/july 0.1.19 → 0.1.21

package/src/internal/tool-call.test.ts

@@ -0,0 +1,458 @@
+import { existsSync } from "node:fs";
+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 { z } from "zod";
+import { httpChannel } from "../channels.js";
+import { defineTool } from "../tools.js";
+import {
+  type AgentProject,
+  DIRECT_TOOL_CALL_CHANNEL_ID,
+  type DiscoveredTool,
+  type ToolDefinition,
+} from "../types.js";
+import { toolInputJsonSchema } from "./json-schema.js";
+import type { AgentRunner } from "./sdk-runner.js";
+import { type AgentMount, startServer } from "./server.js";
+import {
+  SessionBusyError,
+  SessionEngine,
+  ToolInputError,
+  ToolNotDirectlyCallableError,
+  UnknownSessionError,
+  UnknownToolError,
+} from "./session-engine.js";
+import { buildTrajectory } from "./trajectory.js";
+
+const echoTool = defineTool({
+  description: "Echo a message back.",
+  inputSchema: z.object({ message: z.string() }),
+  execute: ({ message }, ctx) => ({
+    echoed: message,
+    channelId: ctx.session.channelId,
+    sessionId: ctx.session.id,
+    workspaceDir: ctx.workspaceDir,
+    toolCallId: ctx.toolCallId,
+    hasAgentsMd: existsSync(join(ctx.workspaceDir, "AGENTS.md")),
+  }),
+});
+
+const throwingTool = defineTool({
+  description: "Always throws.",
+  execute: () => {
+    throw new Error("boom");
+  },
+});
+
+const scriptTool = defineTool({
+  description: "Agent-side script tool.",
+  execution: "agent",
+  script: "#!/usr/bin/env bash\ncat\n",
+});
+
+function discovered(name: string, definition: ToolDefinition): DiscoveredTool {
+  return {
+    name,
+    description: definition.description,
+    inputSchema: toolInputJsonSchema(definition.inputSchema),
+    execution: definition.execution ?? "server",
+    needsApproval: definition.needsApproval !== undefined,
+    ...(definition.script === undefined ? {} : { script: definition.script }),
+    definition,
+  };
+}
+
+function testProject(rootDir: string): AgentProject {
+  return {
+    rootDir,
+    agentDir: join(rootDir, "agent"),
+    name: "tool-call-test",
+    agent: {
+      name: "tool-call-test",
+      runtime: "local",
+      instructions: "Test agent instructions.",
+      tools: [
+        discovered("echo", echoTool),
+        discovered("throws", throwingTool),
+        discovered("script_tool", scriptTool),
+      ],
+      skills: [],
+      connections: [],
+      subagents: [],
+      seedFiles: [],
+    },
+    httpChannel: httpChannel(),
+    channels: [],
+    schedules: [],
+    hooks: [],
+    abs: [],
+    diagnostics: [],
+  };
+}
+
+/** Runner that never runs a model turn — direct calls must not need one. */
+const noTurnRunner: AgentRunner = {
+  runTurn: () => {
+    throw new Error("runTurn must not be called for direct tool calls");
+  },
+};
+
+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-toolcall-"));
+  cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
+  return new SessionEngine({
+    project: testProject(stateRoot),
+    stateRoot,
+    runner: noTurnRunner,
+  });
+}
+
+describe("SessionEngine.callTool", () => {
+  it("runs a server tool deterministically with a scratch context", async () => {
+    const engine = await makeEngine();
+    const outcome = await engine.callTool("echo", { message: "hi" });
+    expect(outcome.isError).toBe(false);
+    expect(outcome.toolName).toBe("echo");
+    expect(outcome.callId).toMatch(/^tool_echo_[0-9a-f]{16}$/);
+    const result = outcome.result as Record<string, string | boolean>;
+    expect(result.echoed).toBe("hi");
+    expect(result.channelId).toBe(DIRECT_TOOL_CALL_CHANNEL_ID);
+    expect(result.workspaceDir).toContain(join("tool-calls", outcome.callId));
+    expect(result.toolCallId).toBe(outcome.callId);
+    // Scratch workspaces are materialized like a session workspace…
+    expect(result.hasAgentsMd).toBe(true);
+    // …and removed once the call returns.
+    expect(existsSync(result.workspaceDir as string)).toBe(false);
+    expect(outcome.sessionId).toBeUndefined();
+  });
+
+  it("validates input against the zod schema before executing", async () => {
+    const engine = await makeEngine();
+    await expect(engine.callTool("echo", { message: 42 })).rejects.toThrow(
+      ToolInputError
+    );
+  });
+
+  it("rejects unknown tools with the available server tools", async () => {
+    const engine = await makeEngine();
+    const error = await engine.callTool("nope").catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(UnknownToolError);
+    expect((error as UnknownToolError).availableToolNames).toEqual([
+      "echo",
+      "throws",
+    ]);
+  });
+
+  it("rejects agent-execution tools", async () => {
+    const engine = await makeEngine();
+    await expect(engine.callTool("script_tool", {})).rejects.toThrow(
+      ToolNotDirectlyCallableError
+    );
+  });
+
+  it("reports a throwing tool body with the model-path error envelope", async () => {
+    const engine = await makeEngine();
+    const outcome = await engine.callTool("throws");
+    expect(outcome.isError).toBe(true);
+    expect(outcome.result).toEqual({
+      content: [{ type: "text", text: 'Tool "throws" failed: boom' }],
+      isError: true,
+    });
+    expect(outcome.errorMessage).toBe('Tool "throws" failed: boom');
+  });
+
+  it("rejects unknown sessions", async () => {
+    const engine = await makeEngine();
+    await expect(
+      engine.callTool("echo", { message: "hi" }, { sessionId: "ses_missing" })
+    ).rejects.toThrow(UnknownSessionError);
+  });
+});
+
+describe("SessionEngine.callTool bound to a session", () => {
+  it("uses the session context and records the call on its event stream", async () => {
+    const engine = await makeEngine();
+    // Create a session record directly (no turn) so the runner stays unused.
+    const record = {
+      sessionId: "ses_toolcall_test",
+      channelId: "http",
+      mode: "chat" as const,
+      continuationKey: null,
+      auth: null,
+      turnCount: 0,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+    await engine.sessions.save(record);
+
+    const outcome = await engine.callTool(
+      "echo",
+      { message: "in-session" },
+      { sessionId: record.sessionId }
+    );
+    expect(outcome.isError).toBe(false);
+    expect(outcome.sessionId).toBe(record.sessionId);
+    const result = outcome.result as Record<string, string>;
+    expect(result.sessionId).toBe(record.sessionId);
+    expect(result.channelId).toBe("http");
+    expect(result.workspaceDir).toBe(
+      engine.sessions.workspaceDir(record.sessionId)
+    );
+    expect(result.hasAgentsMd).toBe(true);
+
+    const events = await engine.listEvents(record.sessionId);
+    const requested = events.find((e) => e.type === "actions.requested");
+    const resulted = events.find((e) => e.type === "action.result");
+    expect(requested?.turnId).toBe(outcome.callId);
+    expect(requested?.data).toEqual({
+      calls: [
+        {
+          callId: outcome.callId,
+          toolName: "echo",
+          args: { message: "in-session" },
+        },
+      ],
+    });
+    expect(resulted?.turnId).toBe(outcome.callId);
+    expect(resulted?.data).toMatchObject({
+      callId: outcome.callId,
+      toolName: "echo",
+      isError: false,
+    });
+
+    // The per-call turnId keeps direct calls visible in trajectories.
+    const trajectory = buildTrajectory(events);
+    const trajectoryCall = trajectory.turns
+      .flatMap((turn) => turn.toolCalls)
+      .find((call) => call.callId === outcome.callId);
+    expect(trajectoryCall).toMatchObject({ toolName: "echo", isError: false });
+  });
+
+  it("rejects direct calls while a model turn is running", async () => {
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-toolcall-"));
+    cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
+    let releaseTurn: () => void = () => {};
+    const gate = new Promise<void>((resolve) => {
+      releaseTurn = resolve;
+    });
+    const blockingRunner: AgentRunner = {
+      runTurn: async () => {
+        await gate;
+        return { status: "finished" as const, result: "done" };
+      },
+    };
+    const engine = new SessionEngine({
+      project: testProject(stateRoot),
+      stateRoot,
+      runner: blockingRunner,
+    });
+    cleanups.push(() => engine.close());
+
+    const session = await engine.send("http", "hold the session", {
+      auth: null,
+    });
+    await expect(
+      engine.callTool("echo", { message: "hi" }, { sessionId: session.id })
+    ).rejects.toThrow(SessionBusyError);
+    releaseTurn();
+    await session.waitForCompletion();
+  });
+});
+
+describe("POST /v1/tools/:toolName", () => {
+  async function startTestServer(): Promise<{ url: string }> {
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-toolhttp-"));
+    cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
+    const mounts: AgentMount[] = [
+      { slug: "", project: testProject(stateRoot) },
+    ];
+    const handle = await startServer(mounts, {
+      port: 0,
+      stateRoot,
+      playground: false,
+      schedules: false,
+      logger: () => {},
+    });
+    cleanups.push(() => handle.close());
+    return { url: handle.url };
+  }
+
+  it("calls a tool over HTTP and returns the normalized result", async () => {
+    const { url } = await startTestServer();
+    const response = await fetch(`${url}/v1/tools/echo`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ input: { message: "over http" } }),
+    });
+    expect(response.status).toBe(200);
+    const body = (await response.json()) as {
+      ok: boolean;
+      toolName: string;
+      isError: boolean;
+      result: { echoed: string };
+    };
+    expect(body.ok).toBe(true);
+    expect(body.toolName).toBe("echo");
+    expect(body.isError).toBe(false);
+    expect(body.result.echoed).toBe("over http");
+  });
+
+  it("returns 404 with available tools for unknown tools", async () => {
+    const { url } = await startTestServer();
+    const response = await fetch(`${url}/v1/tools/nope`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(response.status).toBe(404);
+    const body = (await response.json()) as {
+      error: string;
+      availableTools: string[];
+    };
+    expect(body.error).toBe("unknown_tool");
+    expect(body.availableTools).toEqual(["echo", "throws"]);
+  });
+
+  it("returns 400 on schema-invalid input", async () => {
+    const { url } = await startTestServer();
+    const response = await fetch(`${url}/v1/tools/echo`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ input: { message: 42 } }),
+    });
+    expect(response.status).toBe(400);
+    const body = (await response.json()) as { error: string };
+    expect(body.error).toBe("invalid_tool_input");
+  });
+
+  it("returns 400 for agent-execution tools", async () => {
+    const { url } = await startTestServer();
+    const response = await fetch(`${url}/v1/tools/script_tool`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(response.status).toBe(400);
+    const body = (await response.json()) as { error: string };
+    expect(body.error).toBe("tool_not_callable");
+  });
+
+  it("returns ok: false with the error envelope when the tool body throws", async () => {
+    const { url } = await startTestServer();
+    const response = await fetch(`${url}/v1/tools/throws`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(response.status).toBe(200);
+    const body = (await response.json()) as {
+      ok: boolean;
+      isError: boolean;
+      result: unknown;
+    };
+    expect(body.ok).toBe(false);
+    expect(body.isError).toBe(true);
+    expect(body.result).toEqual({
+      content: [{ type: "text", text: 'Tool "throws" failed: boom' }],
+      isError: true,
+    });
+  });
+
+  it("returns 400 for a malformed or missing JSON body", async () => {
+    const { url } = await startTestServer();
+    const malformed = await fetch(`${url}/v1/tools/echo`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: "{not json",
+    });
+    expect(malformed.status).toBe(400);
+    expect(((await malformed.json()) as { error: string }).error).toBe(
+      "invalid_request"
+    );
+
+    const nonObject = await fetch(`${url}/v1/tools/echo`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify([1, 2]),
+    });
+    expect(nonObject.status).toBe(400);
+  });
+
+  it("returns 400 for a non-string sessionId", async () => {
+    const { url } = await startTestServer();
+    const response = await fetch(`${url}/v1/tools/echo`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ input: { message: "hi" }, sessionId: 42 }),
+    });
+    expect(response.status).toBe(400);
+    expect(((await response.json()) as { error: string }).error).toBe(
+      "invalid_request"
+    );
+  });
+
+  it("returns 404 for an unknown sessionId", async () => {
+    const { url } = await startTestServer();
+    const response = await fetch(`${url}/v1/tools/echo`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        input: { message: "hi" },
+        sessionId: "ses_missing",
+      }),
+    });
+    expect(response.status).toBe(404);
+    const body = (await response.json()) as { error: string };
+    expect(body.error).toBe("session_not_found");
+  });
+});
+
+describe("multi-agent host /v1/health", () => {
+  it("exposes host liveness at /v1/health alongside per-slug health", async () => {
+    const stateRoot = await mkdtemp(join(tmpdir(), "agent-serve-multihealth-"));
+    cleanups.push(() => rm(stateRoot, { recursive: true, force: true }));
+    const mounts: AgentMount[] = [
+      { slug: "alpha", project: testProject(stateRoot) },
+      { slug: "beta", project: testProject(stateRoot) },
+    ];
+    const handle = await startServer(mounts, {
+      port: 0,
+      stateRoot,
+      playground: false,
+      schedules: false,
+      logger: () => {},
+    });
+    cleanups.push(() => handle.close());
+
+    const host = await fetch(`${handle.url}/v1/health`);
+    expect(host.status).toBe(200);
+    const hostBody = (await host.json()) as {
+      ok: boolean;
+      agents: Array<{ slug: string; name: string }>;
+    };
+    expect(hostBody.ok).toBe(true);
+    expect(hostBody.agents.map((a) => a.slug).sort()).toEqual([
+      "alpha",
+      "beta",
+    ]);
+
+    const alpha = await fetch(`${handle.url}/alpha/v1/health`);
+    expect(alpha.status).toBe(200);
+    expect(((await alpha.json()) as { ok: boolean }).ok).toBe(true);
+
+    // Corp ECS health uses wget --spider (HEAD). GET-only routes must still
+    // answer 200 with an empty body so the container check does not fail.
+    const head = await fetch(`${handle.url}/v1/health`, { method: "HEAD" });
+    expect(head.status).toBe(200);
+    expect(await head.text()).toBe("");
+  });
+});

package/src/internal/tool-result.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
+
+describe("normalizeToolResult", () => {
+  it("passes strings through", () => {
+    expect(normalizeToolResult("ok")).toBe("ok");
+  });
+
+  it("maps undefined to the empty result", () => {
+    expect(normalizeToolResult(undefined)).toBe("");
+  });
+
+  it("drops undefined object fields so Struct.fromJson cannot throw", () => {
+    const result = normalizeToolResult({
+      kept: 1,
+      dropped: undefined,
+      nested: [{ action: undefined, status: "OPEN" }],
+    } as never);
+    expect(result).toEqual({ kept: 1, nested: [{ status: "OPEN" }] });
+  });
+
+  it("keeps content envelopes intact", () => {
+    const envelope = {
+      content: [{ type: "text" as const, text: "hi" }],
+      isError: true,
+    };
+    expect(normalizeToolResult(envelope)).toEqual(envelope);
+  });
+});
+
+describe("toolCallErrorMessage", () => {
+  it("returns string results", () => {
+    expect(toolCallErrorMessage("boom")).toBe("boom");
+  });
+
+  it("joins text parts from an error envelope", () => {
+    expect(
+      toolCallErrorMessage({
+        content: [
+          { type: "text", text: "first" },
+          { type: "text", text: " second " },
+        ],
+        isError: true,
+      })
+    ).toBe("first\nsecond");
+  });
+
+  it("returns undefined for non-text results", () => {
+    expect(toolCallErrorMessage({ ok: true })).toBeUndefined();
+    expect(toolCallErrorMessage("")).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import type { SessionEvent } from "../types.js";
+import { buildTrajectory } from "./trajectory.js";
+
+function ev(
+  partial: Omit<SessionEvent, "index" | "sessionId" | "at"> & {
+    index?: number;
+  }
+): SessionEvent {
+  return {
+    index: partial.index ?? 0,
+    sessionId: "sess_1",
+    at: "2026-01-01T00:00:00.000Z",
+    ...partial,
+  } as SessionEvent;
+}
+
+describe("buildTrajectory approvals", () => {
+  it("records approvalDecision on the tool call", () => {
+    const traj = buildTrajectory([
+      ev({ type: "session.started", data: { channelId: "http" } }),
+      ev({
+        type: "message.received",
+        turnId: "turn_1",
+        data: { text: "alert ops about NYC" },
+      }),
+      ev({
+        type: "actions.requested",
+        turnId: "turn_1",
+        data: {
+          calls: [
+            {
+              callId: "call_1",
+              toolName: "post_weather_alert",
+              args: { city: "NYC" },
+            },
+          ],
+        },
+      }),
+      ev({
+        type: "action.approval_requested",
+        turnId: "turn_1",
+        data: {
+          callId: "call_1",
+          toolName: "post_weather_alert",
+          args: { city: "NYC" },
+        },
+      }),
+      ev({
+        type: "action.approval_resolved",
+        turnId: "turn_1",
+        data: {
+          callId: "call_1",
+          toolName: "post_weather_alert",
+          decision: "approve",
+        },
+      }),
+      ev({
+        type: "action.result",
+        turnId: "turn_1",
+        data: {
+          callId: "call_1",
+          toolName: "post_weather_alert",
+          output: { posted: true },
+          isError: false,
+        },
+      }),
+      ev({
+        type: "turn.completed",
+        turnId: "turn_1",
+        data: {},
+      }),
+    ]);
+
+    expect(traj.turns[0]?.toolCalls[0]).toMatchObject({
+      callId: "call_1",
+      toolName: "post_weather_alert",
+      approvalDecision: "approve",
+      isError: false,
+      output: { posted: true },
+    });
+  });
+});