@cursor/july 0.1.1 → 0.1.3

package/src/types.ts

@@ -11,6 +11,7 @@
 import type { InteractionUpdate, SDKCustomTool } from "@cursor/sdk";
 import type { z } from "zod";
 import type { ABConfigFile } from "./ab.js";
+import type { StorageDefinition } from "./storage.js";
 
 // ============================================================================
 // JSON
@@ -43,7 +44,8 @@ export type DefinitionKind =
   | "reminder"
   | "hook"
   | "eval"
-  | "ab";
+  | "ab"
+  | "storage";
 
 export interface BrandedDefinition<K extends DefinitionKind> {
   readonly __agentServe: K;
@@ -186,6 +188,34 @@ export interface AgentConfig {
    * {@link cloud}.
    */
   local?: AgentLocalOptions;
+  /**
+   * Managed-hosting declarations (`agentkit deploy` onto Cursor's
+   * agent-serve hosting). The manifest is the source of truth: deploy reads
+   * it and sends it with the deployment request. Ignored by local serving.
+   */
+  hosting?: AgentHostingOptions;
+}
+
+/**
+ * Managed-hosting block on {@link AgentConfig.hosting}.
+ */
+export interface AgentHostingOptions {
+  /**
+   * Domains the deployed engine pod may reach (egress allowlist), e.g.
+   * `"api.example.com"` or `"*.example.com"` (single leading wildcard).
+   * Lowercase hostnames with at least two labels and an alphabetic TLD;
+   * max 20. `agentkit deploy` sends these as `egressAllowedDomains`
+   * (unioned with any `--allow-domain` flags). Only valid on repo-backed
+   * deployments.
+   */
+  egressDomains?: string[];
+  /**
+   * Secret names this agent expects at runtime (declarative documentation;
+   * values are never authored in files). `agentkit deploy` warns when a
+   * declared name is not set on the deployment — set values with
+   * `agentkit secrets set <slug> NAME`.
+   */
+  secretNames?: string[];
 }
 
 /**
@@ -558,6 +588,11 @@ export interface ActionCall {
   callId: string;
   toolName: string;
   args?: unknown;
+  /**
+   * When set, this tool call belongs to a nested subagent turn whose
+   * parent `task` tool call id is `parentCallId`.
+   */
+  parentCallId?: string;
 }
 
 /** Human decision for a parked {@link ToolConfig.needsApproval} tool call. */
@@ -592,14 +627,30 @@ export type SessionEventPayload =
   | { type: "turn.started"; data: Record<string, never> }
   | { type: "step.started"; data: { stepId: number } }
   | { type: "step.completed"; data: { stepId: number; durationMs: number } }
-  | { type: "reasoning.appended"; data: { delta: string; text: string } }
-  | { type: "reasoning.completed"; data: { durationMs?: number } }
-  | { type: "message.appended"; data: { delta: string; text: string } }
+  | {
+      type: "reasoning.appended";
+      data: { delta: string; text: string; parentCallId?: string };
+    }
+  | {
+      type: "reasoning.completed";
+      data: { durationMs?: number; parentCallId?: string };
+    }
+  | {
+      type: "message.appended";
+      data: { delta: string; text: string; parentCallId?: string };
+    }
   | {
       type: "message.completed";
-      data: { text: string; finishReason: "stop" | "tool_call" };
+      data: {
+        text: string;
+        finishReason: "stop" | "tool_call";
+        parentCallId?: string;
+      };
+    }
+  | {
+      type: "actions.requested";
+      data: { calls: ActionCall[]; parentCallId?: string };
     }
-  | { type: "actions.requested"; data: { calls: ActionCall[] } }
   | {
       /**
        * A server tool with {@link ToolConfig.needsApproval} is parked until
@@ -611,6 +662,7 @@ export type SessionEventPayload =
         callId: string;
         toolName: string;
         args?: unknown;
+        parentCallId?: string;
       };
     }
   | {
@@ -620,6 +672,7 @@ export type SessionEventPayload =
         toolName: string;
         decision: ApprovalDecision;
         by?: string;
+        parentCallId?: string;
       };
     }
   | {
@@ -629,6 +682,7 @@ export type SessionEventPayload =
         toolName: string;
         output?: unknown;
         isError: boolean;
+        parentCallId?: string;
       };
     }
   | {
@@ -1521,7 +1575,10 @@ export interface ResolvedAgent {
   name: string;
   description?: string;
   model?: ModelSetting;
-  /** Composed system prompt (instructions.md / instructions.ts / agent.ts). */
+  /**
+   * Composed system prompt: identity preamble from {@link name}, then
+   * authored `instructions.md` / `.ts` / dir (or inline `agent.ts`).
+   */
   instructions?: string;
   /** Execution runtime. Root agents default to `"local"`. */
   runtime: AgentRuntime;
@@ -1532,6 +1589,8 @@ export interface ResolvedAgent {
    * (`cwd` is absolute — relative paths resolved against the project root).
    */
   local?: AgentLocalOptions;
+  /** Managed-hosting declarations from {@link AgentConfig.hosting}. */
+  hosting?: AgentHostingOptions;
   tools: DiscoveredTool[];
   skills: DiscoveredSkill[];
   connections: DiscoveredConnection[];
@@ -1556,6 +1615,8 @@ export interface AgentProject {
   abs: DiscoveredAB[];
   /** Optional `agent/ab.config.ts` (`defineABConfig`). */
   abConfig?: ABConfigFile;
+  /** Optional `agent/storage.ts` (`defineStorage`). */
+  storage?: StorageDefinition;
   diagnostics: Diagnostic[];
 }
 
@@ -1579,6 +1640,8 @@ export interface AgentProjectInfo {
   cloud?: AgentCloudPublicInfo;
   /** Local harness options when authored (`cwd` absolute). */
   local?: { cwd?: string };
+  /** Managed-hosting declarations when authored (egress allowlist, expected secrets). */
+  hosting?: { egressDomains?: string[]; secretNames?: string[] };
   /**
    * The agent's own MCP surface (mounted at `<base>/v1/mcp`): other agents
    * and MCP clients delegate to this agent through these tools.
@@ -1613,12 +1676,14 @@ export interface AgentProjectInfo {
   hooks: string[];
   /** Live A/B experiment names (`defineAB` under `agent/ab`). */
   abs: string[];
-  /** Playground fold / persistence meta from `agent/ab.config.ts`. */
+  /** Playground fold / durable-sink meta from `agent/ab.config.ts`. */
   abConfig?: {
     maxPlaygroundSessions?: number;
     durableSamples: boolean;
     durableSnapshots: boolean;
   };
+  /** Project storage sink from `agent/storage.ts`, when authored. */
+  storage?: { name?: string };
   diagnostics: Diagnostic[];
 }
 
@@ -1738,6 +1803,15 @@ export interface ServeOptions {
    * {@link authToken}. Authored `auth` arrays still win.
    */
   allowAnonymous?: boolean;
+  /**
+   * Allow {@link allowAnonymous} together with
+   * `githubChannel({ cursorAccount })`. Without this opt-in, `serve` refuses
+   * to start because every admitted anonymous caller could drive sessions
+   * that hold the signed-in account's repo-scoped GitHub credential. Set it
+   * only when the network boundary already authenticates callers (e.g. an
+   * SSO/Okta proxy in front of the host).
+   */
+  allowAnonymousCursorGithub?: boolean;
   /**
    * Public base URL where this server is reachable from outside the host
    * (e.g. `https://agents.example.com`). Used to resolve peer