@cursor/july 0.1.62 → 0.1.73

package/src/types.ts

@@ -347,9 +347,13 @@ export interface AgentLocalOptions {
   /**
    * Default local harness cwd parent. Absolute, or relative to the agent
    * project root. Each session uses `<cwd>/<sessionId>` unless a per-send
-   * {@link SendMessageOptions.workspaceDir} overrides it. Prefer a path
-   * outside large monorepos so Cursor `project` settings do not inherit
-   * ambient `AGENTS.md` / `.cursor` rules.
+   * {@link SendMessageOptions.workspaceDir} overrides it.
+   *
+   * When omitted, a project nested in another git repo (a monorepo package)
+   * defaults to `~/.cache/agent-serve/<dir>` so Cursor does not load the
+   * enclosing checkout's AGENTS.md, rules, skills, or MCP servers. A
+   * standalone git root keeps the in-project session workspace. Point this
+   * at a checkout when the agent must inherit that tree.
    */
   cwd?: string;
   /**
@@ -428,7 +432,17 @@ export type ToolResultValue =
  */
 export type ToolExecuteResult =
   | ToolResultValue
-  | { content: ToolResultContent[]; isError?: boolean };
+  | {
+      content: ToolResultContent[];
+      isError?: boolean;
+      /**
+       * Structured result for tools that declare an `outputSchema`: MCP
+       * clients require `structuredContent` on calls to schema-declaring
+       * tools. Plain-object returns get it filled in automatically; the
+       * envelope form (needed for images or `isError`) sets it here.
+       */
+      structuredContent?: JsonObject;
+    };
 
 /** Repo-agnostic GitHub client on the agent-serve host. */
 export interface HostGitHubClient {
@@ -456,6 +470,7 @@ export interface HostMcpToolInfo {
   name: string;
   description?: string;
   inputSchema?: JsonObject;
+  outputSchema?: JsonObject;
 }
 
 export interface HostMcpCallResult {
@@ -514,9 +529,11 @@ export interface HostContext {
    */
   reminders?: ReminderHostApi;
   /**
-   * Slack ask-dedupe / optional nudge helpers. Always present on a live
-   * {@link SessionEngine} host. Mid-turn nudge inject is not used; busy
-   * Slack follow-ups coalesce and drain at turn boundaries.
+   * Slack ask-dedupe / nudge helpers. Always present on a live
+   * {@link SessionEngine} host. A busy Slack thread's follow-ups queue here
+   * and reach the running agent at its next tool boundary, via the workspace
+   * carrier hook; whatever the carrier does not reach in time still drains
+   * into the boundary turn, deduped by source ts.
    */
   slackNudges?: SlackNudgeHostApi;
   /**
@@ -859,6 +876,13 @@ export interface ToolConfig<TInput> {
    * JSON object.
    */
   inputSchema?: z.ZodType<TInput> | JsonSchemaObject;
+  /**
+   * JSON Schema for the tool's structured output (`Tool.outputSchema` from
+   * the MCP spec), as a zod schema (converted, never validated against) or a
+   * plain JSON Schema object. Advertised when declared and omitted
+   * otherwise — results are not validated against it.
+   */
+  outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   /**
    * When true (or when the predicate returns true), the host parks the
    * in-flight tool call until a human approves or denies via
@@ -887,6 +911,7 @@ export interface ToolDefinition extends BrandedDefinition<"tool"> {
   readonly description: string;
   readonly execution?: ToolExecution;
   readonly inputSchema?: z.ZodTypeAny | JsonSchemaObject;
+  readonly outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   readonly needsApproval?: ToolNeedsApproval<never>;
   readonly execute?: (
     input: never,
@@ -1034,6 +1059,8 @@ export function isSymbolicConnectionTransport(
 export type InlineStdioToolConfig = {
   description: string;
   inputSchema?: z.ZodTypeAny | JsonSchemaObject;
+  /** Output JSON Schema (zod converted, never validated); advertised when declared. */
+  outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   execute: (input: JsonObject) => unknown | Promise<unknown>;
 };
 
@@ -1078,6 +1105,76 @@ export type ConnectionConfig = (
    * cloud-native account connectors provisioned by the platform.
    */
   hostOnly?: boolean;
+  /**
+   * Per-session auth: called at turn-build time with the session's
+   * {@link SessionInfo}, returning headers merged over the transport's
+   * static `headers` for that session's use of this connection. This is
+   * how a multi-tenant agent injects the caller's identity — it derives
+   * who the session is for host-side and mints a tenant-scoped
+   * credential; the model never sees a tenant parameter and can never
+   * choose the tenant.
+   *
+   * Derive the identity from durable session facts — `session.auth`,
+   * `session.id`, or your channel's own session state. Do **not** key it
+   * off `session.continuationKey`: the HTTP channel rotates the
+   * continuation key after every accepted follow-up, so a tenant mapping
+   * keyed on it silently breaks mid-conversation. (Channels that mint
+   * stable, parseable tokens by design are the exception.)
+   *
+   * Works attached or advertised. Advertised connections
+   * ({@link advertiseTools}) open per-operation clients with the
+   * evaluated headers. Attached connections ride the turn's SDK
+   * `mcpServers`, passed on every send rather than pinned on the cached
+   * per-session agent handle, so every turn — follow-ups, reminder
+   * wakes — runs on headers evaluated for that turn. The cost: when any
+   * attached connection has `auth`, *all* of the agent's attached
+   * connections are configured per send, so the harness opens fresh MCP
+   * clients for them each turn (stdio servers respawn per turn — avoid
+   * pairing an auth'd connection with a stateful stdio server), and
+   * workspace prewarm omits auth'd connections rather than attaching
+   * them without an identity.
+   *
+   * HTTP/SSE transports only, not combinable with `oauth: true`
+   * (discovery rejects both). A callback that throws fails the turn: a
+   * turn never silently runs without the connection's identity. Cloud
+   * turns are refused (cloud-runtime agents fail discovery). `host.mcp`
+   * calls from server tools keep the static headers only.
+   */
+  auth?: ConnectionAuthProvider;
+  /**
+   * Advertise this connection's tools by name instead of leaving them
+   * behind the MCP meta-tools: at turn-build time the engine lists the
+   * connection's tools and synthesizes a named 1:1 passthrough server
+   * tool per entry — the server's own names, descriptions, and live
+   * schemas — merged into the authored `agent/tools/` catalog. The raw
+   * connection is then not attached to the model (it stays available on
+   * `host.mcp`), so each tool appears exactly once.
+   *
+   * Fail-closed: a `listTools` failure, an invalid tool name, or a name
+   * collision (with an authored tool or another advertised connection)
+   * fails the turn — a turn never silently runs with a shrunken toolset.
+   * Local runtime only, like all server tools: a `runtime: "cloud"` agent
+   * fails discovery, and hybrid per-send cloud sessions refuse the turn.
+   * Not combinable with {@link hostOnly} (advertising puts the tools in
+   * the model's toolset; hostOnly means off the model — discovery rejects
+   * the pair). The listing runs once per turn; point this at endpoints
+   * that can answer `tools/list` cheaply.
+   */
+  advertiseTools?: boolean;
+};
+
+/**
+ * Per-session connection auth on {@link ConnectionConfig.auth}: session →
+ * headers merged over the transport's static headers for that session's
+ * turns. See the field docs for the fail-closed semantics.
+ */
+export type ConnectionAuthProvider = (
+  session: SessionInfo
+) => ConnectionAuthResult | Promise<ConnectionAuthResult>;
+
+/** What a {@link ConnectionAuthProvider} returns. */
+export type ConnectionAuthResult = {
+  headers: Record<string, string>;
 };
 
 /** True when the connection authors tools instead of a spawn/URL/peer. */
@@ -1271,7 +1368,27 @@ export type SessionEventPayload =
       type: "turn.completed";
       data: { result?: string; usage?: TurnUsage; cost?: TurnCost };
     }
+  | {
+      /**
+       * The harness accepted the turn and named the run. Emitted once the
+       * send lands, so a channel can show the request id while the turn is
+       * still going rather than after it. Quote it verbatim when correlating
+       * with backend logs — never abbreviated.
+       */
+      type: "turn.bound";
+      data: { requestId: string };
+    }
   | { type: "turn.failed"; data: { message: string } }
+  | {
+      /**
+       * A Slack follow-up queued mid-turn reached the running agent: the
+       * workspace carrier moved it from `pending/` to `delivered/` at a tool
+       * boundary. Channels use this to reposition a live progress message
+       * below the follow-up, which Slack cannot do any other way.
+       */
+      type: "nudge.delivered";
+      data: Record<string, never>;
+    }
   | { type: "session.waiting"; data: Record<string, never> }
   | { type: "session.completed"; data: Record<string, never> }
   | { type: "session.failed"; data: { message: string } };
@@ -2356,6 +2473,8 @@ export interface DiscoveredTool {
   description: string;
   /** JSON Schema advertised to the model. */
   inputSchema: JsonSchemaObject;
+  /** Output JSON Schema, advertised only when the tool declares one. */
+  outputSchema?: JsonSchemaObject;
   /** Where the tool body runs. Defaults to `"server"`. */
   execution: ToolExecution;
   /**
@@ -2388,6 +2507,10 @@ export interface DiscoveredConnection {
   transport: ConnectionTransport;
   description?: string;
   hostOnly?: boolean;
+  /** Per-session auth from {@link ConnectionConfig.auth} (http/sse only). */
+  auth?: ConnectionAuthProvider;
+  /** Advertise-by-name from {@link ConnectionConfig.advertiseTools}. */
+  advertiseTools?: boolean;
 }
 
 export interface DiscoveredChannel {
@@ -2533,6 +2656,7 @@ export interface AgentProjectInfo {
     name: string;
     transport: string;
     hostOnly?: boolean;
+    advertiseTools?: boolean;
     /**
      * Present only for `cursorAccount` connections: the connector-name
      * allowlist, or `"*"` for every connected server. Structured twin of the
@@ -2624,10 +2748,28 @@ export interface RunnerTurnRequest {
   customTools: Record<string, SDKCustomTool>;
   /** MCP servers from `agent/mcp-connections/`. */
   mcpServers: Record<string, ConnectionTransport>;
+  /**
+   * Configure {@link mcpServers} on every send instead of once on the
+   * cached SDK agent handle. Set when an attached connection has
+   * per-session `auth`: its headers are re-evaluated at turn-build time,
+   * and a handle-pinned copy would keep the first turn's credentials until
+   * the handle recycles. The SDK builds the send's MCP session from exactly
+   * this set (fresh clients each turn — stdio servers respawn per turn),
+   * and the create/resume/prewarm options carry no `mcpServers` at all, so
+   * the local executor cache key stays stable while credentials rotate.
+   * Local runtime only; cloud turns with such connections are refused.
+   */
+  perSendMcpServers?: boolean;
   subagents: RunnerSubagent[];
   onUpdate: (update: RunnerUpdate) => void | Promise<void>;
   /** Called once the SDK agent is open so the engine can persist its id. */
   onSdkAgentId?: (sdkAgentId: string) => void | Promise<void>;
+  /**
+   * Called once the harness names the run, before it produces anything.
+   * Surfaces the request id while the turn is still running rather than at
+   * its end.
+   */
+  onRequestId?: (requestId: string) => void | Promise<void>;
   /**
    * Abort the in-flight run when signalled. The engine aborts this when a
    * follow-up message preempts the current turn; the runner maps it to

package/templates/agentic-owners/agent/agent.ts

@@ -1,3 +1,5 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { defineAgent } from "@cursor/july";
 
 export default defineAgent({
@@ -11,5 +13,6 @@ export default defineAgent({
   tools: ["read", "grep", "glob", "ls"],
   local: {
     sandbox: true,
+    cwd: join(homedir(), ".cache", "agent-serve", "agentic-owners"),
   },
 });

package/templates/demo/agent/agent.ts

@@ -1,3 +1,5 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { defineAgent } from "@cursor/july";
 
 export default defineAgent({
@@ -11,5 +13,6 @@ export default defineAgent({
   tools: ["read", "grep"],
   local: {
     sandbox: true,
+    cwd: join(homedir(), ".cache", "agent-serve", "demo"),
   },
 });

package/templates/pr-autofixer/agent/lib/drive-schemas.ts

@@ -1,6 +1,9 @@
 import { z } from "zod";
 
-export const driveStartBodySchema = z.object({
+export const driveStartBodySchema: z.ZodObject<{
+  pr: z.ZodString;
+  hint: z.ZodOptional<z.ZodString>;
+}> = z.object({
   pr: z
     .string()
     .describe(

package/templates/security-reviewer/agent/agent.ts

@@ -1,3 +1,5 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { defineAgent } from "@cursor/july";
 
 export default defineAgent({
@@ -11,5 +13,6 @@ export default defineAgent({
   tools: ["read", "grep"],
   local: {
     sandbox: true,
+    cwd: join(homedir(), ".cache", "agent-serve", "security-reviewer"),
   },
 });

package/templates/triage/agent/agent.ts

@@ -1,3 +1,5 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { defineAgent } from "@cursor/july";
 
 export default defineAgent({
@@ -11,5 +13,6 @@ export default defineAgent({
   tools: ["read", "grep", "glob", "ls"],
   local: {
     sandbox: true,
+    cwd: join(homedir(), ".cache", "agent-serve", "triage"),
   },
 });