@cursor/july 0.1.1 → 0.1.3

package/src/internal/event-mapper.ts

@@ -4,11 +4,63 @@
  * (`SessionEvent` payloads). One mapper instance covers one turn.
  */
 
-import type { InteractionUpdate, ToolCall } from "@cursor/sdk";
+import type {
+  InteractionUpdate as SdkInteractionUpdate,
+  ToolCall,
+} from "@cursor/sdk";
 import type { SessionEventPayload, TurnUsage } from "../types.js";
 
 const CUSTOM_TOOLS_PROVIDER = "custom-user-tools";
 
+/**
+ * Nested interaction updates from a task/subagent tool-call-delta.
+ * Mirrored locally so agent-serve typechecks against published `@cursor/sdk`
+ * versions that do not yet export `NestedTaskUpdate` / `tool-call-delta`.
+ */
+type NestedTaskUpdate =
+  | { type: "text-delta"; text: string }
+  | { type: "thinking-delta"; text: string }
+  | { type: "thinking-completed"; thinkingDurationMs: number }
+  | {
+      type: "tool-call-started";
+      callId: string;
+      toolCall: ToolCall;
+      modelCallId: string;
+    }
+  | {
+      type: "tool-call-completed";
+      callId: string;
+      toolCall: ToolCall;
+      modelCallId: string;
+    }
+  | {
+      type: "partial-tool-call";
+      callId: string;
+      toolCall: ToolCall;
+      modelCallId: string;
+    }
+  | { type: "step-started"; stepId: number }
+  | { type: "step-completed"; stepId: number; stepDurationMs: number };
+
+type ToolCallDeltaUpdate = {
+  type: "tool-call-delta";
+  callId: string;
+  modelCallId: string;
+  taskUpdate: NestedTaskUpdate;
+};
+
+/** SDK updates plus nested task deltas once the SDK exposes them. */
+type InteractionUpdate = SdkInteractionUpdate | ToolCallDeltaUpdate;
+
+function asToolCallDelta(
+  update: InteractionUpdate
+): ToolCallDeltaUpdate | undefined {
+  if ((update as { type: string }).type !== "tool-call-delta") {
+    return undefined;
+  }
+  return update as ToolCallDeltaUpdate;
+}
+
 export interface ToolCallDescription {
   toolName: string;
   args?: unknown;
@@ -20,12 +72,19 @@ export interface ToolResultDescription {
   isError: boolean;
 }
 
+interface NestedAccumulators {
+  text: string;
+  reasoning: string;
+}
+
 export class TurnEventMapper {
   private textAccumulator = "";
   private reasoningAccumulator = "";
   private usageTotal: TurnUsage | undefined;
   private lastAssistantText: string | undefined;
   private summaryTitle: string | undefined;
+  /** Per-parent-call accumulators for nested subagent streams. */
+  private readonly nested = new Map<string, NestedAccumulators>();
 
   constructor(private readonly emit: (payload: SessionEventPayload) => void) {}
 
@@ -74,49 +133,11 @@ export class TurnEventMapper {
       }
       case "tool-call-started": {
         this.flushAssistantText("tool_call");
-        const description = describeToolCall(update.toolCall);
-        this.emit({
-          type: "actions.requested",
-          data: {
-            calls: [
-              {
-                callId: update.callId,
-                toolName: description.toolName,
-                args: description.args,
-              },
-            ],
-          },
-        });
-        if (description.subagent !== undefined) {
-          this.emit({
-            type: "subagent.called",
-            data: {
-              callId: update.callId,
-              name: description.subagent.name,
-              description: description.subagent.description,
-            },
-          });
-        }
+        this.emitToolStarted(update.callId, update.toolCall);
         return;
       }
       case "tool-call-completed": {
-        const description = describeToolCall(update.toolCall);
-        const result = describeToolResult(update.toolCall);
-        this.emit({
-          type: "action.result",
-          data: {
-            callId: update.callId,
-            toolName: description.toolName,
-            output: result.output,
-            isError: result.isError,
-          },
-        });
-        if (description.subagent !== undefined) {
-          this.emit({
-            type: "subagent.completed",
-            data: { callId: update.callId, name: description.subagent.name },
-          });
-        }
+        this.emitToolCompleted(update.callId, update.toolCall);
         return;
       }
       case "step-started": {
@@ -148,7 +169,13 @@ export class TurnEventMapper {
       case "shell-output-delta":
         return;
       default: {
-        // Future harness update types are ignored rather than fatal.
+        // Nested task/subagent progress (tool-call-delta) — accepted via
+        // structural check so we typecheck against older published SDKs.
+        const delta = asToolCallDelta(update);
+        if (delta !== undefined) {
+          this.handleNestedTaskUpdate(delta.callId, delta.taskUpdate);
+          return;
+        }
         return;
       }
     }
@@ -157,6 +184,143 @@ export class TurnEventMapper {
   /** Close out the turn: finalize any open assistant text block. */
   finish(): void {
     this.flushAssistantText("stop");
+    for (const parentCallId of this.nested.keys()) {
+      this.flushNestedAssistantText(parentCallId, "stop");
+    }
+  }
+
+  private handleNestedTaskUpdate(
+    parentCallId: string,
+    update: NestedTaskUpdate
+  ): void {
+    switch (update.type) {
+      case "text-delta": {
+        const acc = this.ensureNested(parentCallId);
+        acc.text += update.text;
+        this.emit({
+          type: "message.appended",
+          data: {
+            delta: update.text,
+            text: acc.text,
+            parentCallId,
+          },
+        });
+        return;
+      }
+      case "thinking-delta": {
+        const acc = this.ensureNested(parentCallId);
+        acc.reasoning += update.text;
+        this.emit({
+          type: "reasoning.appended",
+          data: {
+            delta: update.text,
+            text: acc.reasoning,
+            parentCallId,
+          },
+        });
+        return;
+      }
+      case "thinking-completed": {
+        const acc = this.nested.get(parentCallId);
+        if (acc !== undefined && acc.reasoning !== "") {
+          acc.reasoning = "";
+        }
+        this.emit({
+          type: "reasoning.completed",
+          data: {
+            durationMs: update.thinkingDurationMs,
+            parentCallId,
+          },
+        });
+        return;
+      }
+      case "tool-call-started": {
+        this.flushNestedAssistantText(parentCallId, "tool_call");
+        this.emitToolStarted(update.callId, update.toolCall, parentCallId);
+        return;
+      }
+      case "tool-call-completed": {
+        this.emitToolCompleted(update.callId, update.toolCall, parentCallId);
+        return;
+      }
+      case "partial-tool-call":
+      case "step-started":
+      case "step-completed":
+        return;
+      default: {
+        return;
+      }
+    }
+  }
+
+  private emitToolStarted(
+    callId: string,
+    toolCall: ToolCall,
+    parentCallId?: string
+  ): void {
+    const description = describeToolCall(toolCall);
+    this.emit({
+      type: "actions.requested",
+      data: {
+        calls: [
+          {
+            callId,
+            toolName: description.toolName,
+            args: description.args,
+            parentCallId,
+          },
+        ],
+        parentCallId,
+      },
+    });
+    // Subagent bookends only fire for the top-level task tool, not nested
+    // tools inside a subagent (nested subagents aren't supported).
+    if (description.subagent !== undefined && parentCallId === undefined) {
+      this.emit({
+        type: "subagent.called",
+        data: {
+          callId,
+          name: description.subagent.name,
+          description: description.subagent.description,
+        },
+      });
+    }
+  }
+
+  private emitToolCompleted(
+    callId: string,
+    toolCall: ToolCall,
+    parentCallId?: string
+  ): void {
+    const description = describeToolCall(toolCall);
+    const result = describeToolResult(toolCall);
+    this.emit({
+      type: "action.result",
+      data: {
+        callId,
+        toolName: description.toolName,
+        output: result.output,
+        isError: result.isError,
+        parentCallId,
+      },
+    });
+    if (description.subagent !== undefined && parentCallId === undefined) {
+      this.flushNestedAssistantText(callId, "stop");
+      this.nested.delete(callId);
+      this.emit({
+        type: "subagent.completed",
+        data: { callId, name: description.subagent.name },
+      });
+    }
+  }
+
+  private ensureNested(parentCallId: string): NestedAccumulators {
+    let acc = this.nested.get(parentCallId);
+    if (acc === undefined) {
+      acc = { text: "", reasoning: "" };
+      this.nested.set(parentCallId, acc);
+    }
+    return acc;
   }
 
   private flushAssistantText(finishReason: "stop" | "tool_call"): void {
@@ -171,6 +335,22 @@ export class TurnEventMapper {
       data: { text, finishReason },
     });
   }
+
+  private flushNestedAssistantText(
+    parentCallId: string,
+    finishReason: "stop" | "tool_call"
+  ): void {
+    const acc = this.nested.get(parentCallId);
+    if (acc === undefined || acc.text === "") {
+      return;
+    }
+    const text = acc.text;
+    acc.text = "";
+    this.emit({
+      type: "message.completed",
+      data: { text, finishReason, parentCallId },
+    });
+  }
 }
 
 /**

package/src/internal/handleAgentServeTrigger.ts

@@ -62,19 +62,17 @@ export function collectGitHubTriggerTargets(input: {
 }): AgentServeGitHubTriggerTarget[] {
   const targets: AgentServeGitHubTriggerTarget[] = [];
   for (const mount of input.mounts) {
-    const github = mount.channels.find((channel) => channel.id === "github");
-    if (github === undefined) {
-      continue;
+    for (const channel of mount.channels) {
+      const options = getGitHubChannelOptions(channel.definition);
+      if (options === undefined) {
+        continue;
+      }
+      targets.push({
+        slug: mount.slug,
+        options,
+        args: mount.buildHandlerArgs(channel.id),
+      });
     }
-    const options = getGitHubChannelOptions(github.definition);
-    if (options === undefined) {
-      continue;
-    }
-    targets.push({
-      slug: mount.slug,
-      options,
-      args: mount.buildHandlerArgs("github"),
-    });
   }
   return targets;
 }

package/src/internal/host-platforms.ts

@@ -12,6 +12,7 @@ import {
   resolveGitHubInstallationId,
   tryResolveGhAuthToken,
 } from "../channels/github/auth.js";
+import type { GitHubChannelCredentials } from "../channels/github/types.js";
 import { tryResolveBotToken } from "../channels/slack/credentials.js";
 import type { HostGitHubClient, HostSlackClient } from "../types.js";
 
@@ -25,21 +26,34 @@ export interface HostPlatforms {
  * `app` = GitHub App installation token (preferred in production).
  * `env` / `gh` = local PAT / CLI fallbacks when App creds are unset.
  */
-export type HostGitHubAuthSource = "app" | "env" | "gh" | "unavailable";
+export type HostGitHubAuthSource =
+  | "app"
+  | "cursor-account"
+  | "env"
+  | "gh"
+  | "unavailable";
+
+export interface HostPlatformsOptions {
+  githubCredentials?: GitHubChannelCredentials;
+}
 
 /**
  * Build host platforms from ambient credentials. Prefer App installation
  * auth when configured; otherwise fall back to PAT / `gh auth` for local
  * testing. Webhook-scoped calls should still prefer `ctx.github`.
  */
-export function createHostPlatforms(): HostPlatforms {
+export function createHostPlatforms(
+  options: HostPlatformsOptions = {}
+): HostPlatforms {
   let octokitPromise: ReturnType<HostGitHubClient["getOctokit"]> | undefined;
   let slackPromise: ReturnType<HostSlackClient["getClient"]> | undefined;
 
   return {
     github: {
       getOctokit: () => {
-        octokitPromise ??= createGitHubOctokit({});
+        octokitPromise ??= createGitHubOctokit({
+          credentials: options.githubCredentials,
+        });
         return octokitPromise;
       },
     },
@@ -95,8 +109,9 @@ export async function resolveHostGitHubAuthSource(): Promise<HostGitHubAuthSourc
 export async function warmupHostGitHubAuth(options: {
   logger: (line: string) => void;
   github?: HostGitHubClient;
+  authSource?: HostGitHubAuthSource;
 }): Promise<HostGitHubAuthSource> {
-  const source = await resolveHostGitHubAuthSource();
+  const source = options.authSource ?? (await resolveHostGitHubAuthSource());
   if (source === "unavailable") {
     options.logger(
       "[agent-serve] GitHub auth: unavailable (set GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY + GITHUB_APP_INSTALLATION_ID, or GITHUB_TOKEN / GH_TOKEN, or run `gh auth login`)"
@@ -118,13 +133,15 @@ export async function warmupHostGitHubAuth(options: {
   }
 
   const label =
-    source === "app"
-      ? exportedGhToken
-        ? "GitHub App installation token (also exported as GH_TOKEN for gh CLI)"
-        : "GitHub App installation token"
-      : source === "env"
-        ? "GITHUB_TOKEN/GH_TOKEN"
-        : "gh auth token";
+    source === "cursor-account"
+      ? "Cursor account repo-scoped credential (also exported as GH_TOKEN for gh CLI)"
+      : source === "app"
+        ? exportedGhToken
+          ? "GitHub App installation token (also exported as GH_TOKEN for gh CLI)"
+          : "GitHub App installation token"
+        : source === "env"
+          ? "GITHUB_TOKEN/GH_TOKEN"
+          : "gh auth token";
   if (options.github === undefined) {
     options.logger(`[agent-serve] GitHub auth: ${label}`);
     return source;

package/src/internal/hosting.ts

@@ -0,0 +1,77 @@
+/**
+ * Client-side mirrors of the Agent Serve hosting validation rules
+ * (backend/server/src/agentServe/agentServeShared.ts). Shared by discovery
+ * (`hosting` block diagnostics on `agentkit validate`) and the deploy /
+ * secrets CLI verbs (actionable errors before any network call). The
+ * backend stays authoritative — these exist so mistakes fail fast and
+ * locally with the same grammar the server enforces.
+ */
+
+/** `hosting.egressDomains` cap (backend caps the deploy body at 20). */
+export const MAX_EGRESS_DOMAINS = 20;
+/** Max secrets per deployment. */
+export const MAX_SECRETS = 32;
+/** Max secret value size in bytes. */
+export const MAX_SECRET_VALUE_BYTES = 4096;
+/** Max secret name length. */
+export const MAX_SECRET_NAME_LENGTH = 64;
+/** Secret names the platform injects; user writes are rejected. */
+export const RESERVED_SECRET_NAME_PREFIX = "CURSOR_";
+
+const SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+
+// Lowercase hostname with >=2 labels, an alphabetic TLD, and at most one
+// leading `*.` wildcard. Labels: alphanumeric with interior hyphens.
+const EGRESS_DOMAIN_PATTERN =
+  /^(\*\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]+$/;
+
+/** Returns a human error message, or undefined when the domain is valid. */
+export function validateEgressDomain(domain: string): string | undefined {
+  if (EGRESS_DOMAIN_PATTERN.test(domain)) {
+    return undefined;
+  }
+  return `Invalid egress domain ${JSON.stringify(domain)}: use a lowercase hostname with at least two labels and an alphabetic TLD (e.g. "api.example.com"), optionally with a single leading "*." wildcard.`;
+}
+
+/**
+ * Returns a human error message, or undefined when the name is a valid
+ * secret name. Grammar only — reserved names are checked separately so the
+ * manifest's declarative `secretNames` can mention them with a softer
+ * diagnostic than the hard write-time rejection.
+ */
+export function validateSecretName(name: string): string | undefined {
+  if (name.length > MAX_SECRET_NAME_LENGTH) {
+    return `Secret name ${JSON.stringify(name)} is too long (max ${MAX_SECRET_NAME_LENGTH} characters).`;
+  }
+  if (!SECRET_NAME_PATTERN.test(name)) {
+    return `Invalid secret name ${JSON.stringify(name)}: use UPPER_SNAKE_CASE starting with a letter (${SECRET_NAME_PATTERN}).`;
+  }
+  return undefined;
+}
+
+/** True when the platform reserves this name (`CURSOR_*`); writes are rejected. */
+export function isReservedSecretName(name: string): boolean {
+  return name.startsWith(RESERVED_SECRET_NAME_PREFIX);
+}
+
+/**
+ * Human error for a secret name a user is trying to write or delete:
+ * grammar plus the reserved `CURSOR_*` prefix.
+ */
+export function validateSettableSecretName(name: string): string | undefined {
+  const nameError = validateSecretName(name);
+  if (nameError !== undefined) {
+    return nameError;
+  }
+  if (isReservedSecretName(name)) {
+    return `Secret name ${JSON.stringify(name)} is platform-reserved (CURSOR_*); the platform injects those values automatically.`;
+  }
+  return undefined;
+}
+
+const CURSOR_EVENT_REPO_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+
+/** `owner/name` — mirrors the backend's cursor-event repo grammar. */
+export function isValidCursorEventRepo(repo: string): boolean {
+  return CURSOR_EVENT_REPO_PATTERN.test(repo) && !repo.includes("..");
+}