@cursor/july 0.1.1 → 0.1.3

package/dist/internal/event-mapper.js

@@ -4,11 +4,19 @@
  * (`SessionEvent` payloads). One mapper instance covers one turn.
  */
 const CUSTOM_TOOLS_PROVIDER = "custom-user-tools";
+function asToolCallDelta(update) {
+    if (update.type !== "tool-call-delta") {
+        return undefined;
+    }
+    return update;
+}
 export class TurnEventMapper {
     constructor(emit) {
         this.emit = emit;
         this.textAccumulator = "";
         this.reasoningAccumulator = "";
+        /** Per-parent-call accumulators for nested subagent streams. */
+        this.nested = new Map();
     }
     /** Per-turn token usage summed across model steps. */
     get usage() {
@@ -52,49 +60,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": {
@@ -126,7 +96,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;
             }
         }
@@ -134,6 +110,128 @@ export class TurnEventMapper {
     /** Close out the turn: finalize any open assistant text block. */
     finish() {
         this.flushAssistantText("stop");
+        for (const parentCallId of this.nested.keys()) {
+            this.flushNestedAssistantText(parentCallId, "stop");
+        }
+    }
+    handleNestedTaskUpdate(parentCallId, update) {
+        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;
+            }
+        }
+    }
+    emitToolStarted(callId, toolCall, parentCallId) {
+        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,
+                },
+            });
+        }
+    }
+    emitToolCompleted(callId, toolCall, parentCallId) {
+        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 },
+            });
+        }
+    }
+    ensureNested(parentCallId) {
+        let acc = this.nested.get(parentCallId);
+        if (acc === undefined) {
+            acc = { text: "", reasoning: "" };
+            this.nested.set(parentCallId, acc);
+        }
+        return acc;
     }
     flushAssistantText(finishReason) {
         if (this.textAccumulator === "") {
@@ -147,6 +245,18 @@ export class TurnEventMapper {
             data: { text, finishReason },
         });
     }
+    flushNestedAssistantText(parentCallId, finishReason) {
+        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 },
+        });
+    }
 }
 /**
  * Human-meaningful tool identity for stream events. In-process tools calls

package/dist/internal/handleAgentServeTrigger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handleAgentServeTrigger.d.ts","sourceRoot":"","sources":["../../src/internal/handleAgentServeTrigger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,WAAW,6BAA6B;IAC5C,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,OAAO,EAAE,oBAAoB,CAAC;IAC9B,uEAAuE;IACvE,IAAI,EAAE,kBAAkB,CAAC;CAC1B;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,QAAQ,CAAC;IACf,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,6BAA6B,EAAE,CAAC;CAC1C;AAED,MAAM,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AAElE,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,6BAA6B,EAAE,CAAC;CAC1C;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,MAAM,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,KAAK,CAAC;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACpD,gBAAgB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,kBAAkB,CAAC;KAC7D,CAAC,CAAC;CACJ,GAAG,6BAA6B,EAAE,CAkBlC;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CAYlC"}
+{"version":3,"file":"handleAgentServeTrigger.d.ts","sourceRoot":"","sources":["../../src/internal/handleAgentServeTrigger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,WAAW,6BAA6B;IAC5C,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,OAAO,EAAE,oBAAoB,CAAC;IAC9B,uEAAuE;IACvE,IAAI,EAAE,kBAAkB,CAAC;CAC1B;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,QAAQ,CAAC;IACf,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,6BAA6B,EAAE,CAAC;CAC1C;AAED,MAAM,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AAElE,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,6BAA6B,EAAE,CAAC;CAC1C;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,MAAM,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,KAAK,CAAC;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACpD,gBAAgB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,kBAAkB,CAAC;KAC7D,CAAC,CAAC;CACJ,GAAG,6BAA6B,EAAE,CAgBlC;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CAYlC"}

package/dist/internal/handleAgentServeTrigger.js

@@ -26,19 +26,17 @@ import { dispatchGitHubWebhook, getGitHubChannelOptions, } from "../channels/git
 export function collectGitHubTriggerTargets(input) {
     const targets = [];
     for (const mount of input.mounts) {
-        const github = mount.channels.find((channel) => channel.id === "github");
-        if (github === undefined) {
-            continue;
-        }
-        const options = getGitHubChannelOptions(github.definition);
-        if (options === 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),
+            });
         }
-        targets.push({
-            slug: mount.slug,
-            options,
-            args: mount.buildHandlerArgs("github"),
-        });
     }
     return targets;
 }

package/dist/internal/host-platforms.d.ts

@@ -2,6 +2,7 @@
  * Host-side GitHub + Slack clients shared across tools, channel routes,
  * schedules, and channel packs — same injection pattern as MCP.
  */
+import type { GitHubChannelCredentials } from "../channels/github/types.js";
 import type { HostGitHubClient, HostSlackClient } from "../types.js";
 export interface HostPlatforms {
     github: HostGitHubClient;
@@ -12,13 +13,16 @@ 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 declare function createHostPlatforms(): HostPlatforms;
+export declare function createHostPlatforms(options?: HostPlatformsOptions): HostPlatforms;
 /**
  * Detect ambient host GitHub auth without throwing.
  * Order matches {@link createGitHubOctokit}: App installation, then
@@ -36,5 +40,6 @@ export declare function resolveHostGitHubAuthSource(): Promise<HostGitHubAuthSou
 export declare function warmupHostGitHubAuth(options: {
     logger: (line: string) => void;
     github?: HostGitHubClient;
+    authSource?: HostGitHubAuthSource;
 }): Promise<HostGitHubAuthSource>;
 //# sourceMappingURL=host-platforms.d.ts.map

package/dist/internal/host-platforms.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-platforms.d.ts","sourceRoot":"","sources":["../../src/internal/host-platforms.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAErE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,eAAe,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,KAAK,GAAG,IAAI,GAAG,aAAa,CAAC;AAExE;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CA4BnD;AAED;;;;GAIG;AACH,wBAAsB,2BAA2B,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAejF;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA8ChC"}
+{"version":3,"file":"host-platforms.d.ts","sourceRoot":"","sources":["../../src/internal/host-platforms.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAE5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAErE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,eAAe,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAC5B,KAAK,GACL,gBAAgB,GAChB,KAAK,GACL,IAAI,GACJ,aAAa,CAAC;AAElB,MAAM,WAAW,oBAAoB;IACnC,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;CAC9C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,oBAAyB,GACjC,aAAa,CA8Bf;AAED;;;;GAIG;AACH,wBAAsB,2BAA2B,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAejF;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,UAAU,CAAC,EAAE,oBAAoB,CAAC;CACnC,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAgDhC"}

package/dist/internal/host-platforms.js

@@ -20,13 +20,15 @@ import { tryResolveBotToken } from "../channels/slack/credentials.js";
  * auth when configured; otherwise fall back to PAT / `gh auth` for local
  * testing. Webhook-scoped calls should still prefer `ctx.github`.
  */
-export function createHostPlatforms() {
+export function createHostPlatforms(options = {}) {
     let octokitPromise;
     let slackPromise;
     return {
         github: {
             getOctokit: () => {
-                octokitPromise !== null && octokitPromise !== void 0 ? octokitPromise : (octokitPromise = createGitHubOctokit({}));
+                octokitPromise !== null && octokitPromise !== void 0 ? octokitPromise : (octokitPromise = createGitHubOctokit({
+                    credentials: options.githubCredentials,
+                }));
                 return octokitPromise;
             },
         },
@@ -76,7 +78,8 @@ export function resolveHostGitHubAuthSource() {
  */
 export function warmupHostGitHubAuth(options) {
     return __awaiter(this, void 0, void 0, function* () {
-        const source = yield resolveHostGitHubAuthSource();
+        var _a;
+        const source = (_a = options.authSource) !== null && _a !== void 0 ? _a : (yield 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`)");
             return source;
@@ -90,13 +93,15 @@ export function warmupHostGitHubAuth(options) {
                 options.logger(`[agent-serve] GitHub auth: failed to export GH_TOKEN for gh CLI: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
-        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";
+        const label = 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/dist/internal/hosting.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 declare const MAX_EGRESS_DOMAINS = 20;
+/** Max secrets per deployment. */
+export declare const MAX_SECRETS = 32;
+/** Max secret value size in bytes. */
+export declare const MAX_SECRET_VALUE_BYTES = 4096;
+/** Max secret name length. */
+export declare const MAX_SECRET_NAME_LENGTH = 64;
+/** Secret names the platform injects; user writes are rejected. */
+export declare const RESERVED_SECRET_NAME_PREFIX = "CURSOR_";
+/** Returns a human error message, or undefined when the domain is valid. */
+export declare function validateEgressDomain(domain: string): string | undefined;
+/**
+ * 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 declare function validateSecretName(name: string): string | undefined;
+/** True when the platform reserves this name (`CURSOR_*`); writes are rejected. */
+export declare function isReservedSecretName(name: string): boolean;
+/**
+ * Human error for a secret name a user is trying to write or delete:
+ * grammar plus the reserved `CURSOR_*` prefix.
+ */
+export declare function validateSettableSecretName(name: string): string | undefined;
+/** `owner/name` — mirrors the backend's cursor-event repo grammar. */
+export declare function isValidCursorEventRepo(repo: string): boolean;
+//# sourceMappingURL=hosting.d.ts.map

package/dist/internal/hosting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosting.d.ts","sourceRoot":"","sources":["../../src/internal/hosting.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,kCAAkC;AAClC,eAAO,MAAM,WAAW,KAAK,CAAC;AAC9B,sCAAsC;AACtC,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,8BAA8B;AAC9B,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,mEAAmE;AACnE,eAAO,MAAM,2BAA2B,YAAY,CAAC;AASrD,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKvE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQnE;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAS3E;AAID,sEAAsE;AACtE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D"}

package/dist/internal/hosting.js

@@ -0,0 +1,67 @@
+/**
+ * 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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    return CURSOR_EVENT_REPO_PATTERN.test(repo) && !repo.includes("..");
+}

package/dist/internal/init-project.d.ts

@@ -9,11 +9,98 @@ export interface InitProjectOptions {
     /** Model id override written into agent.ts. */
     model?: string;
 }
+export type InitFileAction = "create" | "exist";
+export interface InitFileEntry {
+    path: string;
+    action: InitFileAction;
+}
 export interface InitProjectResult {
     rootDir: string;
-    files: string[];
+    /** Scaffold files in write order, with create/exist for each. */
+    files: InitFileEntry[];
+    /** Paths newly written. */
+    created: string[];
+    /** Paths left alone because they already existed. */
+    skipped: string[];
 }
 export declare function initProject(options: InitProjectOptions): Promise<InitProjectResult>;
+export interface InstallScaffoldDependenciesOptions {
+    /**
+     * `inherit` streams npm output to the terminal (human `init`);
+     * `pipe` captures it ( `--json` / tests).
+     */
+    stdio?: "inherit" | "pipe";
+    /** Test seam — replaces the real `npm install` spawn. */
+    runner?: (args: {
+        command: string;
+        args: string[];
+        cwd: string;
+        stdio: "inherit" | "pipe";
+    }) => Promise<{
+        exitCode: number;
+        stderr: string;
+    }>;
+}
+export interface InstallScaffoldDependenciesResult {
+    ok: boolean;
+    exitCode: number;
+    stderr: string;
+}
+/**
+ * Install the scaffold's npm dependencies so `dev` / `run` can resolve
+ * `@cursor/july` immediately after `init`.
+ */
+export declare function installScaffoldDependencies(rootDir: string, options?: InstallScaffoldDependenciesOptions): Promise<InstallScaffoldDependenciesResult>;
+export interface InitScaffoldSummaryOptions {
+    /** Scaffolded project root (absolute). */
+    rootDir: string;
+    /** Scaffold files in write order (`create` / `exist`). */
+    files: InitFileEntry[];
+    /** Override TTY color detection (tests / `--json` callers). */
+    color?: boolean;
+}
+export interface InitNextStepsOptions {
+    /** Scaffolded project root (absolute). */
+    rootDir: string;
+    /** Directory the command ran from. */
+    cwd: string;
+    /**
+     * True when a Cursor credential resolves. When false, next steps include
+     * `login` (used for `--json` and when an interactive login attempt failed).
+     */
+    signedIn: boolean;
+    /** Override TTY color detection (tests / `--json` callers). */
+    color?: boolean;
+}
+export type InitSummaryOptions = InitScaffoldSummaryOptions & InitNextStepsOptions;
+/**
+ * Created/skipped files plus the project path. Printed before an interactive
+ * login so the scaffold is visible while the browser flow runs.
+ */
+export declare function formatInitScaffoldSummary(options: InitScaffoldSummaryOptions): string;
+/**
+ * Numbered next steps after scaffold (and after login when init ran it).
+ * Includes `cd` when init did not already run inside the project.
+ */
+export declare function formatInitNextSteps(options: InitNextStepsOptions): string;
+/**
+ * Full human-readable scaffold summary (scaffold + next steps).
+ */
+export declare function formatInitSummary(options: InitSummaryOptions): string;
+/**
+ * `cd` into the scaffold when init did not already run inside it. Relative
+ * when the target sits under the invoking directory, absolute otherwise.
+ */
+export declare function formatCdCommand(cwd: string, rootDir: string): string | undefined;
+/**
+ * Next-step commands for the `--json` scaffold summary (login omitted when
+ * the host already has a Cursor credential).
+ */
+export declare function initNextCommands(options: {
+    rootDir: string;
+    cwd: string;
+    signedIn: boolean;
+}): string[];
 /**
  * Coding-agent setup guide printed by `agent-serve init`
  * with no target directory (does not scaffold).

package/dist/internal/init-project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-project.d.ts","sourceRoot":"","sources":["../../src/internal/init-project.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAUD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CA+E5B;AAuBD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAqBrC"}
+{"version":3,"file":"init-project.d.ts","sourceRoot":"","sources":["../../src/internal/init-project.ts"],"names":[],"mappings":"AAAA;;GAEG;AAiBH,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,qDAAqD;IACrD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AA2BD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAgH5B;AAWD,MAAM,WAAW,kCAAkC;IACjD;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,yDAAyD;IACzD,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;KAC3B,KAAK,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,iCAAiC;IAChD,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kCAAuC,GAC/C,OAAO,CAAC,iCAAiC,CAAC,CAW5C;AAkDD,MAAM,WAAW,0BAA0B;IACzC,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,kBAAkB,GAAG,0BAA0B,GACzD,oBAAoB,CAAC;AAMvB;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,MAAM,CAkBR;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAgBzE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAErE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,SAAS,CAQpB;AAwBD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,OAAO,CAAC;CACnB,GAAG,MAAM,EAAE,CAEX;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAsBrC"}