@cursor/july 0.1.40 → 0.1.41

package/dist/internal/discovery.js

@@ -120,11 +120,18 @@ export function loadAgentProjects(rootDir_1) {
             throw new Error(`No agent projects found directly under ${resolved}. Each agent should be a subdirectory with its own agent/ directory (or flat-layout markers).`);
         }
         const results = [];
+        // Storage namespaces (session mirror, host kv, durable-session ledger)
+        // key on the project NAME, not the mount slug — two co-hosted agents
+        // sharing a name would silently share sessions and coordination state.
+        const slugByName = new Map();
         for (const child of children) {
-            results.push({
-                slug: child.slug,
-                project: yield loadAgentProject(child.dir, options),
-            });
+            const project = yield loadAgentProject(child.dir, options);
+            const priorSlug = slugByName.get(project.name);
+            if (priorSlug !== undefined) {
+                throw new Error(`Duplicate agent name "${project.name}" under ${resolved}: agents "${priorSlug}" and "${child.slug}" both resolve to it (package.json "name", or the directory name when unset). Co-hosted agents must have distinct names — their storage and session namespaces key on the name.`);
+            }
+            slugByName.set(project.name, child.slug);
+            results.push({ slug: child.slug, project });
         }
         return results;
     });
@@ -306,6 +313,7 @@ function loadAgent(ctx, agentDir, options) {
             };
         const hosting = resolveHosting(ctx, agentDir, config === null || config === void 0 ? void 0 : config.hosting);
         const concurrency = resolveConcurrency(ctx, agentDir, config === null || config === void 0 ? void 0 : config.concurrency);
+        const serving = resolveServing(ctx, agentDir, config === null || config === void 0 ? void 0 : config.serving);
         if (runtime === "cloud") {
             warnCloudRuntimeLimitations(ctx, agentDir, {
                 agentTools: tools.filter((tool) => tool.execution === "agent").length,
@@ -326,6 +334,7 @@ function loadAgent(ctx, agentDir, options) {
             local,
             hosting,
             concurrency,
+            serving,
             tools,
             skills,
             connections,
@@ -334,6 +343,22 @@ function loadAgent(ctx, agentDir, options) {
         };
     });
 }
+/**
+ * Validate the authored serving mode. An unrecognized value is an error
+ * diagnostic and falls back to undefined (resident) — a typo must not
+ * silently opt an agent into (or out of) ledger coordination.
+ */
+function resolveServing(ctx, agentDir, serving) {
+    if (serving === undefined || serving === "resident" || serving === "ledger") {
+        return serving;
+    }
+    ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message: `serving must be "resident" or "ledger"; got ${JSON.stringify(serving)}.`,
+    });
+    return undefined;
+}
 /** Absolute harness cwd parent, or undefined when unset / blank. */
 function resolveAgentCwd(ctx, authored) {
     if (authored === undefined) {
@@ -376,7 +401,7 @@ function resolveHosting(ctx, agentDir, hosting) {
             warn(`hosting.secretNames: ${nameError}`);
         }
         else if (isReservedSecretName(name)) {
-            warn(`hosting.secretNames: ${JSON.stringify(name)} is platform-managed (CURSOR_* / Cursor-hosted storage) and injected automatically; omit it from secretNames.`);
+            warn(`hosting.secretNames: ${JSON.stringify(name)} is platform-managed (CURSOR_* / reserved hosted-storage names); omit it from secretNames.`);
         }
     }
     return Object.assign(Object.assign({}, (hosting.egressDomains === undefined
@@ -1525,11 +1550,14 @@ export function projectInfo(project) {
         })), skills: agent.skills.map((skill) => ({
             name: skill.name,
             description: skill.description,
-        })), connections: agent.connections.map((connection) => ({
+        })), connections: agent.connections.map((connection) => { var _a; return ({
             name: connection.name,
             transport: connectionTransportLabel(connection.transport),
             hostOnly: connection.hostOnly,
-        })), subagents: agent.subagents.map((subagent) => ({
+            cursorAccountServers: "cursorAccount" in connection.transport
+                ? ((_a = connection.transport.servers) !== null && _a !== void 0 ? _a : "*")
+                : undefined,
+        }); }), subagents: agent.subagents.map((subagent) => ({
             name: subagent.name,
             description: subagent.description,
             model: subagent.model,

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

@@ -1 +1 @@
-{"version":3,"file":"distribution.d.ts","sourceRoot":"","sources":["../../src/internal/distribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,sEAAsE;AACtE,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,WAAW,cAAc,CAAC;AACvC,eAAO,MAAM,UAAU,EAAE,MAA2B,CAAC;AACrD,eAAO,MAAM,gBAAgB,EAAE,MAAiC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAA+B,CAAC;AAc/D;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAGhD;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,kEAAkE;AAClE,wBAAgB,cAAc,IAAI,MAAM,CAOvC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAC/C,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAuBzC,CAAC"}
+{"version":3,"file":"distribution.d.ts","sourceRoot":"","sources":["../../src/internal/distribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,sEAAsE;AACtE,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAE5D;;;GAGG;AACH,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,WAAW,cAAc,CAAC;AACvC,eAAO,MAAM,UAAU,EAAE,MAA2B,CAAC;AACrD,eAAO,MAAM,gBAAgB,EAAE,MAAiC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAA+B,CAAC;AAc/D;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAGhD;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,kEAAkE;AAClE,wBAAgB,cAAc,IAAI,MAAM,CAOvC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAC/C,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAyBzC,CAAC"}

package/dist/internal/distribution.js

@@ -92,8 +92,10 @@ export const AUTHORING_ENTRY_FILES = [
     ["evals/loaders", "evals/loaders.js"],
     ["ab", "ab.js"],
     ["artifacts", "artifacts.js"],
+    ["kv", "kv.js"],
+    ["kv/memory", "kv/memory-kv.js"],
+    ["ledger", "ledger.js"],
     ["storage", "storage.js"],
     ["storage/file-kv", "storage-backends/file-kv.js"],
-    ["storage/postgres-kv", "storage-backends/postgres-kv.js"],
     ["storage/cursor-hosted", "storage-backends/cursor-hosted.js"],
 ];

package/dist/internal/durable-session-store.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Durable-session store resolution.
+ *
+ * Two APIs, one backend: `defineStorage` is the **storage API** (agent
+ * state — session records, event chunks, author KV), and the session
+ * ledger is the **durable session API** (session identity, leases,
+ * fenced commits). The ledger consumes {@link SessionLedgerKv} — exactly
+ * the three CAS methods it uses, nothing more; this module adapts a
+ * storage backend's `cas` group into that interface, so a deployment's
+ * one authored backend serves both APIs by default.
+ *
+ * Calls go straight at the config's methods — NOT through the
+ * StorageCoordinator: the coordinator's queue is bounded, serialized, and
+ * at-most-once (mirror semantics), while ledger CAS calls are the
+ * correctness path and must observe their own results synchronously.
+ */
+import type { SessionLedgerKv } from "../ledger/session-ledger.js";
+import { type StorageConfig } from "../storage.js";
+export interface StorageCasKvArgs {
+    agentName: string;
+    projectRoot: string;
+}
+/**
+ * Adapt a storage backend's `cas` group into the ledger's KV interface.
+ * Throws when the backend does not implement `cas` — the caller turns
+ * that into the fail-fast startup error for `serving: "ledger"`. Every
+ * call carries a `reason: "coordination"` {@link StorageContext}.
+ */
+export declare function storageCasKv(config: StorageConfig, args: StorageCasKvArgs): SessionLedgerKv;
+/**
+ * The one place the ledger's physical namespace is minted:
+ * `agentkit/v1/<agent>/durable-session/` — the {@link STORAGE_KEY_ROOT}
+ * conventions with the agent segment encoded like every other
+ * caller-controlled segment. The ledger itself never sees this string;
+ * it speaks bare `session/…` / `ledger/…` keys against a handle that
+ * {@link namespacedKv} has already scoped.
+ */
+export declare function ledgerKeyPrefix(agentName: string): string;
+/**
+ * Scope a raw store handle under a namespace, prepending it to every
+ * key on the way in. Applied exactly once, where the engine constructs
+ * the ledger's store handle — the same conceptual boundary where
+ * `host.kv` gets its agent scoping. Internal: not part of the public kv
+ * interface, and callers (including the explicit `durableSessionStore`
+ * override) always supply the raw store — they never write prefixes.
+ */
+export declare function namespacedKv(store: SessionLedgerKv, namespace: string): SessionLedgerKv;
+//# sourceMappingURL=durable-session-store.d.ts.map

package/dist/internal/durable-session-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-session-store.d.ts","sourceRoot":"","sources":["../../src/internal/durable-session-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,gBAAgB,GACrB,eAAe,CAuBjB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,GAChB,eAAe,CAOjB"}

package/dist/internal/durable-session-store.js

@@ -0,0 +1,86 @@
+/**
+ * Durable-session store resolution.
+ *
+ * Two APIs, one backend: `defineStorage` is the **storage API** (agent
+ * state — session records, event chunks, author KV), and the session
+ * ledger is the **durable session API** (session identity, leases,
+ * fenced commits). The ledger consumes {@link SessionLedgerKv} — exactly
+ * the three CAS methods it uses, nothing more; this module adapts a
+ * storage backend's `cas` group into that interface, so a deployment's
+ * one authored backend serves both APIs by default.
+ *
+ * Calls go straight at the config's methods — NOT through the
+ * StorageCoordinator: the coordinator's queue is bounded, serialized, and
+ * at-most-once (mirror semantics), while ledger CAS calls are the
+ * correctness path and must observe their own results synchronously.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { keySegment, STORAGE_KEY_ROOT, } from "../storage.js";
+/**
+ * Adapt a storage backend's `cas` group into the ledger's KV interface.
+ * Throws when the backend does not implement `cas` — the caller turns
+ * that into the fail-fast startup error for `serving: "ledger"`. Every
+ * call carries a `reason: "coordination"` {@link StorageContext}.
+ */
+export function storageCasKv(config, args) {
+    const ctx = {
+        agentName: args.agentName,
+        projectRoot: args.projectRoot,
+        reason: "coordination",
+    };
+    const { cas } = config;
+    if (cas === undefined) {
+        throw new Error("storageCasKv: the storage backend does not implement the cas group (conditional writes)");
+    }
+    return {
+        getWithVersion(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return yield cas.getWithVersion(key, ctx);
+            });
+        },
+        putIfAbsent(key, value) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return yield cas.putIfAbsent(key, value, ctx);
+            });
+        },
+        putIfVersion(key, value, expectedVersion) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return yield cas.putIfVersion(key, value, expectedVersion, ctx);
+            });
+        },
+    };
+}
+/**
+ * The one place the ledger's physical namespace is minted:
+ * `agentkit/v1/<agent>/durable-session/` — the {@link STORAGE_KEY_ROOT}
+ * conventions with the agent segment encoded like every other
+ * caller-controlled segment. The ledger itself never sees this string;
+ * it speaks bare `session/…` / `ledger/…` keys against a handle that
+ * {@link namespacedKv} has already scoped.
+ */
+export function ledgerKeyPrefix(agentName) {
+    return `${STORAGE_KEY_ROOT}/${keySegment(agentName)}/durable-session/`;
+}
+/**
+ * Scope a raw store handle under a namespace, prepending it to every
+ * key on the way in. Applied exactly once, where the engine constructs
+ * the ledger's store handle — the same conceptual boundary where
+ * `host.kv` gets its agent scoping. Internal: not part of the public kv
+ * interface, and callers (including the explicit `durableSessionStore`
+ * override) always supply the raw store — they never write prefixes.
+ */
+export function namespacedKv(store, namespace) {
+    return {
+        getWithVersion: (key) => store.getWithVersion(namespace + key),
+        putIfAbsent: (key, value) => store.putIfAbsent(namespace + key, value),
+        putIfVersion: (key, value, expectedVersion) => store.putIfVersion(namespace + key, value, expectedVersion),
+    };
+}

package/dist/internal/hosting.d.ts

@@ -14,7 +14,7 @@ export declare const MAX_SECRETS = 32;
 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. */
+/** Secret names the platform manages; user writes are rejected. */
 export declare const RESERVED_SECRET_NAME_PREFIX = "CURSOR_";
 /**
  * Additional platform-managed env names for Cursor-hosted durable storage

package/dist/internal/hosting.js

@@ -14,7 +14,7 @@ export const MAX_SECRETS = 32;
 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. */
+/** Secret names the platform manages; user writes are rejected. */
 export const RESERVED_SECRET_NAME_PREFIX = "CURSOR_";
 /**
  * Additional platform-managed env names for Cursor-hosted durable storage
@@ -73,7 +73,7 @@ export function validateSettableSecretName(name) {
         return nameError;
     }
     if (isReservedSecretName(name)) {
-        return `Secret name ${JSON.stringify(name)} is platform-managed; the platform injects CURSOR_* and Cursor-hosted storage values automatically.`;
+        return `Secret name ${JSON.stringify(name)} is platform-managed; user secrets cannot claim CURSOR_* or reserved hosted-storage names.`;
     }
     return undefined;
 }

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

@@ -52,6 +52,34 @@ export interface InstallScaffoldDependenciesResult {
  * `@cursor/july` immediately after `init`.
  */
 export declare function installScaffoldDependencies(rootDir: string, options?: InstallScaffoldDependenciesOptions): Promise<InstallScaffoldDependenciesResult>;
+export interface LinkCliOntoPathOptions {
+    stdio?: "inherit" | "pipe";
+    runner?: (args: {
+        command: string;
+        args: string[];
+        cwd: string;
+        stdio: "inherit" | "pipe";
+    }) => Promise<{
+        exitCode: number;
+        stderr: string;
+    }>;
+    /** Test seam — absolute path of the linked CLI when present. */
+    whichImpl?: (command: string) => string | undefined | Promise<string | undefined>;
+}
+export interface LinkCliOntoPathResult {
+    ok: boolean;
+    exitCode: number;
+    stderr: string;
+    /** Absolute path to the linked `agent-sdk` when it resolves on PATH. */
+    resolvedPath?: string;
+}
+/**
+ * Put `agent-sdk` on the user PATH by installing the already-downloaded
+ * project copy into the npm global prefix. `npx @cursor/july init` only
+ * runs the package; this is the install that makes bare `agent-sdk …`
+ * work afterward.
+ */
+export declare function linkCliOntoPath(rootDir: string, options?: LinkCliOntoPathOptions): Promise<LinkCliOntoPathResult>;
 export interface InitScaffoldSummaryOptions {
     /** Scaffolded project root (absolute). */
     rootDir: string;
@@ -70,6 +98,11 @@ export interface InitNextStepsOptions {
      * `login` (used for `--json` and when an interactive login attempt failed).
      */
     signedIn: boolean;
+    /**
+     * True when `agent-sdk` resolves on PATH after init linked the CLI.
+     * When false, next steps include a PATH export for `node_modules/.bin`.
+     */
+    cliOnPath: boolean;
     /** Override TTY color detection (tests / `--json` callers). */
     color?: boolean;
 }
@@ -101,6 +134,7 @@ export declare function initNextCommands(options: {
     rootDir: string;
     cwd: string;
     signedIn: boolean;
+    cliOnPath: boolean;
 }): string[];
 /**
  * Coding-agent setup guide printed by `agent-serve init`

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":"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"}
+{"version":3,"file":"init-project.d.ts","sourceRoot":"","sources":["../../src/internal/init-project.ts"],"names":[],"mappings":"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"}

package/dist/internal/init-project.js

@@ -11,6 +11,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { CLI_COMMAND_NAME, PACKAGE_NAME, packageVersion, } from "./distribution.js";
@@ -70,6 +71,7 @@ export function initProject(options) {
             description: `agent project: ${name}`,
             scripts: {
                 check: "tsc --noEmit",
+                dev: "agent-sdk dev",
             },
             dependencies: {
                 [PACKAGE_NAME]: `^${packageVersion()}`,
@@ -176,6 +178,117 @@ export function installScaffoldDependencies(rootDir_1) {
         };
     });
 }
+/**
+ * Put `agent-sdk` on the user PATH by installing the already-downloaded
+ * project copy into the npm global prefix. `npx @cursor/july init` only
+ * runs the package; this is the install that makes bare `agent-sdk …`
+ * work afterward.
+ */
+export function linkCliOntoPath(rootDir_1) {
+    return __awaiter(this, arguments, void 0, function* (rootDir, options = {}) {
+        var _a, _b, _c;
+        const packageDir = join(rootDir, "node_modules", PACKAGE_NAME);
+        if (!existsSync(packageDir)) {
+            return {
+                ok: false,
+                exitCode: 1,
+                stderr: `missing ${PACKAGE_NAME} under ${packageDir} (run npm install first)`,
+            };
+        }
+        const stdio = (_a = options.stdio) !== null && _a !== void 0 ? _a : "inherit";
+        const command = process.platform === "win32" ? "npm.cmd" : "npm";
+        const args = ["install", "--global", "--no-fund", "--no-audit", packageDir];
+        const runner = (_b = options.runner) !== null && _b !== void 0 ? _b : defaultNpmInstallRunner;
+        const result = yield runner({ command, args, cwd: rootDir, stdio });
+        if (result.exitCode !== 0) {
+            return {
+                ok: false,
+                exitCode: result.exitCode,
+                stderr: result.stderr,
+            };
+        }
+        const whichImpl = (_c = options.whichImpl) !== null && _c !== void 0 ? _c : resolveLinkedCli;
+        const resolvedPath = yield whichImpl(CLI_COMMAND_NAME);
+        return {
+            ok: resolvedPath !== undefined,
+            exitCode: 0,
+            stderr: resolvedPath === undefined
+                ? `${CLI_COMMAND_NAME} linked into the npm global prefix but is not on PATH; open a new shell or add that bin directory to PATH`
+                : "",
+            resolvedPath,
+        };
+    });
+}
+/** Prefer the npm-global bin; ignore an older `agent-sdk` earlier on PATH. */
+function resolveLinkedCli(commandName) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const prefix = yield npmGlobalPrefix();
+        if (prefix === undefined) {
+            return whichOnPath(commandName);
+        }
+        const binDir = process.platform === "win32" ? prefix : join(prefix, "bin");
+        const exts = process.platform === "win32"
+            ? ((_a = process.env.PATHEXT) !== null && _a !== void 0 ? _a : ".EXE;.CMD;.BAT").split(";").filter(Boolean)
+            : [""];
+        for (const ext of exts) {
+            const candidate = join(binDir, `${commandName}${ext}`);
+            if (!existsSync(candidate)) {
+                continue;
+            }
+            // Only claim PATH success when this linked bin is the first hit.
+            const onPath = whichOnPath(commandName);
+            return onPath === candidate ? candidate : undefined;
+        }
+        return undefined;
+    });
+}
+function npmGlobalPrefix() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const command = process.platform === "win32" ? "npm.cmd" : "npm";
+        return yield new Promise((resolvePromise) => {
+            var _a, _b;
+            const child = spawn(command, ["prefix", "-g"], {
+                stdio: ["ignore", "pipe", "ignore"],
+                env: process.env,
+            });
+            let out = "";
+            (_a = child.stdout) === null || _a === void 0 ? void 0 : _a.setEncoding("utf8");
+            (_b = child.stdout) === null || _b === void 0 ? void 0 : _b.on("data", (chunk) => {
+                out += chunk;
+            });
+            child.on("error", () => resolvePromise(undefined));
+            child.on("close", (code) => {
+                if (code !== 0) {
+                    resolvePromise(undefined);
+                    return;
+                }
+                const prefix = out.trim();
+                resolvePromise(prefix === "" ? undefined : prefix);
+            });
+        });
+    });
+}
+function whichOnPath(commandName) {
+    var _a, _b;
+    const pathEnv = (_a = process.env.PATH) !== null && _a !== void 0 ? _a : "";
+    const sep = process.platform === "win32" ? ";" : ":";
+    const exts = process.platform === "win32"
+        ? ((_b = process.env.PATHEXT) !== null && _b !== void 0 ? _b : ".EXE;.CMD;.BAT").split(";").filter(Boolean)
+        : [""];
+    for (const dir of pathEnv.split(sep)) {
+        if (dir === "") {
+            continue;
+        }
+        for (const ext of exts) {
+            const candidate = join(dir, `${commandName}${ext}`);
+            if (existsSync(candidate)) {
+                return candidate;
+            }
+        }
+    }
+    return undefined;
+}
 function defaultNpmInstallRunner(args) {
     return __awaiter(this, void 0, void 0, function* () {
         return yield new Promise((resolvePromise, reject) => {
@@ -286,6 +399,12 @@ function initNextStepEntries(options) {
     if (cd !== undefined) {
         steps.push({ command: cd });
     }
+    if (!options.cliOnPath) {
+        steps.push({
+            command: 'export PATH="$PWD/node_modules/.bin:$PATH"',
+            note: "use the project-local agent-sdk bin",
+        });
+    }
     if (!options.signedIn) {
         steps.push({
             command: `${CLI_COMMAND_NAME} login`,
@@ -313,10 +432,10 @@ export function printInitGuide() {
     process.stdout.write(`${CLI_COMMAND_NAME} — coding agent setup
 
 Scaffold a project, then open the playground:
-  ${CLI_COMMAND_NAME} init ./my-agent   # installs deps; signs you in when needed
+  npx ${PACKAGE_NAME} init ./my-agent   # installs deps + puts agent-sdk on PATH
   cd ./my-agent && ${CLI_COMMAND_NAME} dev
 
-Recommended loop once the project exists:
+Recommended loop once the project exists (from the project directory):
   1. Edit agent/ + tools under agent/tools/
   2. ${CLI_COMMAND_NAME} info --dir . --json
   3. ${CLI_COMMAND_NAME} run --dir . --message "..."

package/dist/internal/ledger-serving.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Ledger-mode serving seam (`serving: "ledger"` on `defineAgent`):
+ * coordination only, no inbox. Every engine `send` acquires the session
+ * lease before its turn runs and commits (head+1, lease released) after
+ * it completes, so cross-pod mutual exclusion, generation fencing, and
+ * the committed head sequence are real.
+ *
+ * **Durability trade-off (deliberate):** there is no durable mailbox.
+ * An event that arrives while the lease is held does NOT park in the
+ * store — the delivering pod waits *in-process*: local concurrent sends
+ * serialize on a per-session promise chain (no claim spinning), and a
+ * lease held by another pod is waited out with bounded claim retries. A
+ * crash therefore loses the in-flight event exactly as resident serving
+ * does. A dead pod's lease simply expires (~30s TTL); the next delivery
+ * claims at generation+1 — no janitor is needed because nothing is
+ * parked.
+ *
+ * Re-entrancy caveat (same shape as resident `waitForCompletion`): a
+ * send issued from *inside* a running turn against the same session
+ * chains behind that turn's serve, so awaiting its resolution from the
+ * turn would deadlock. Fire-and-forget such sends.
+ */
+import type { SessionLedger } from "../ledger/session-ledger.js";
+import type { ChannelSession, SendMessageOptions } from "../types.js";
+/** Wait between claim retries while another holder has the lease. */
+export declare const CLAIM_RETRY_DELAY_MS = 250;
+/**
+ * Give up waiting for the lease after this long — two full lease TTLs,
+ * so a dead holder's expiry (~30s) is always survived with margin.
+ */
+export declare const CLAIM_WAIT_TIMEOUT_MS: number;
+/** The `send` options a ledger delivery carries to the resident turn. */
+export type LedgerDeliverOptions = SendMessageOptions & {
+    mode?: "chat" | "task";
+};
+/** One delivery handed back to the engine's resident path. */
+export interface LedgerTurnRequest {
+    channelId: string;
+    continuationToken: string;
+    message: string;
+    options: LedgerDeliverOptions;
+}
+export interface LedgerServingOptions {
+    ledger: SessionLedger;
+    /**
+     * Run one delivery as a resident-path turn (the engine's `send` with
+     * the internal ledger-delivery flag). Must resolve once the turn is
+     * admitted; the pump awaits `waitForCompletion` itself.
+     */
+    deliverTurn: (request: LedgerTurnRequest) => Promise<ChannelSession>;
+    logger?: (line: string) => void;
+    /** Lease heartbeat cadence while the turn runs (default 10s). */
+    heartbeatIntervalMs?: number;
+    /** Claim retry cadence while the lease is held (default 250ms). */
+    claimRetryDelayMs?: number;
+    /** Give-up bound for lease waiting (default 2× lease TTL). */
+    claimWaitTimeoutMs?: number;
+    clock?: () => number;
+    /** Injectable wait (tests use short real delays; keep them tiny). */
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare class LedgerServing {
+    private readonly ledger;
+    private readonly deliverTurn;
+    private readonly logger;
+    private readonly heartbeatIntervalMs;
+    private readonly claimRetryDelayMs;
+    private readonly claimWaitTimeoutMs;
+    private readonly clock;
+    private readonly sleep;
+    /**
+     * Per-ledger-session in-process serialization: local concurrent sends
+     * queue here instead of spinning claim retries against our own lease.
+     */
+    private readonly chains;
+    constructor(options: LedgerServingOptions);
+    /** Settle every queued and in-flight delivery. */
+    close(): Promise<void>;
+    /**
+     * Ledger-mode `send`: resolve the session identity, wait for the
+     * lease (in-process queue first, then cross-pod claim retries), run
+     * the turn, commit. Resolves with the engine session handle after the
+     * commit released the lease.
+     */
+    deliver(channelId: string, message: string, options: LedgerDeliverOptions): Promise<ChannelSession>;
+    /** Chain a delivery behind the session's in-flight ones. */
+    private enqueue;
+    /** claim (waiting) → resident turn → commit-release. */
+    private serveOne;
+    /**
+     * Claim the lease, waiting out another holder with bounded retries.
+     * The common waits are short: our own pod's deliveries never reach
+     * here concurrently (the in-process chain serializes them), so a held
+     * lease means another pod is serving — usually for one turn — or died
+     * (expiry unblocks us at ~30s).
+     */
+    private claimWithWait;
+}
+/** Mint the lease holder id for this process. */
+export declare function newLedgerPodId(): string;
+//# sourceMappingURL=ledger-serving.d.ts.map

package/dist/internal/ledger-serving.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-serving.d.ts","sourceRoot":"","sources":["../../src/internal/ledger-serving.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAMjE,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGtE,qEAAqE;AACrE,eAAO,MAAM,oBAAoB,MAAM,CAAC;AACxC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAyB,CAAC;AAE9D,yEAAyE;AACzE,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GAAG;IACtD,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAEF,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,oBAAoB,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,WAAW,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACrE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB,qEAAqE;IACrE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAE9D,YAAY,OAAO,EAAE,oBAAoB,EAaxC;IAED,kDAAkD;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3B;IAED;;;;;OAKG;IACG,OAAO,CACX,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAazB;IAED,4DAA4D;IAC5D,OAAO,CAAC,OAAO;IAoBf,wDAAwD;YAC1C,QAAQ;IAsDtB;;;;;;OAMG;YACW,aAAa;CAiB5B;AAED,iDAAiD;AACjD,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}