@cursor/july 0.1.30 → 0.1.32

package/dist/files-backends/local-fs.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Local-disk file sink: one file per key under a directory you own.
+ *
+ * The default off Cursor-managed hosting. Paths are real, so the harness can
+ * open a file with its ordinary tools — that is why this reports
+ * `materialized` — and there are no etags, so `conflictDetection` is honestly
+ * false and concurrent writers are last-writer-wins.
+ */
+import { type FileSink } from "../files.js";
+export interface LocalFilesOptions {
+    /** Directory the sink owns. */
+    filesRoot: string;
+    /**
+     * Prefix trimmed off each key before building the on-disk path, so the tree
+     * reads `deployment/notes.md` instead of repeating the framework key root.
+     *
+     * Framework-supplied. Authors should omit it: the value has to match the
+     * internal key scheme exactly, and a near-miss would silently nest files
+     * under a redundant path instead of failing. Omitted, keys are stored
+     * verbatim, which is always correct and lets two agents share one root.
+     */
+    stripKeyPrefix?: string;
+}
+/**
+ * Default sink: one file per key under the state root, written atomically.
+ *
+ * Reports `materialized` because the paths are real — that is what lets the
+ * harness read a file with its ordinary tools — and reports no `etags`, so
+ * `host.files.capabilities.conflictDetection` is honestly false and concurrent
+ * writers are last-writer-wins.
+ */
+export declare function localFiles(options: LocalFilesOptions): FileSink;
+//# sourceMappingURL=local-fs.d.ts.map

package/dist/files-backends/local-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-fs.d.ts","sourceRoot":"","sources":["../../src/files-backends/local-fs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,OAAO,EAEL,KAAK,QAAQ,EAGd,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,QAAQ,CAmG/D"}

package/dist/files-backends/local-fs.js

@@ -0,0 +1,199 @@
+/**
+ * Local-disk file sink: one file per key under a directory you own.
+ *
+ * The default off Cursor-managed hosting. Paths are real, so the harness can
+ * open a file with its ordinary tools — that is why this reports
+ * `materialized` — and there are no etags, so `conflictDetection` is honestly
+ * false and concurrent writers are last-writer-wins.
+ */
+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());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncDelegator = (this && this.__asyncDelegator) || function (o) {
+    var i, p;
+    return i = {}, verb("next"), verb("throw", function (e) { throw e; }), verb("return"), i[Symbol.iterator] = function () { return this; }, i;
+    function verb(n, f) { i[n] = o[n] ? function (v) { return (p = !p) ? { value: __await(o[n](v)), done: false } : f ? f(v) : v; } : f; }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile, } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { FilePathRejectedError, } from "../files.js";
+/**
+ * Default sink: one file per key under the state root, written atomically.
+ *
+ * Reports `materialized` because the paths are real — that is what lets the
+ * harness read a file with its ordinary tools — and reports no `etags`, so
+ * `host.files.capabilities.conflictDetection` is honestly false and concurrent
+ * writers are last-writer-wins.
+ */
+export function localFiles(options) {
+    var _a;
+    const root = resolve(options.filesRoot);
+    const stripPrefix = (_a = options.stripKeyPrefix) !== null && _a !== void 0 ? _a : "";
+    const pathForKey = (key) => {
+        const rel = stripPrefix !== "" && key.startsWith(stripPrefix)
+            ? key.slice(stripPrefix.length)
+            : key;
+        const candidate = resolve(root, rel);
+        const within = relative(root, candidate);
+        if (within === "" || within === ".." || within.startsWith(`..${sep}`)) {
+            throw new FilePathRejectedError(`host.files key does not resolve under the state root: ${key}`);
+        }
+        return candidate;
+    };
+    const entryFor = (key, absPath) => __awaiter(this, void 0, void 0, function* () {
+        try {
+            const info = yield stat(absPath);
+            if (!info.isFile()) {
+                return undefined;
+            }
+            return { key, size: info.size, mtimeMs: info.mtimeMs };
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return undefined;
+            }
+            throw error;
+        }
+    });
+    return {
+        capabilities: { materialized: true },
+        materializedPath: (key) => pathForKey(key),
+        put(key, body) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const target = pathForKey(key);
+                yield mkdir(join(target, ".."), { recursive: true });
+                // Same-directory temp + rename: a reader either sees the previous value
+                // or the whole new one, never a half-written file.
+                const tmp = join(target, "..", `.tmp-${randomUUID()}`);
+                try {
+                    yield writeFile(tmp, body);
+                    yield rename(tmp, target);
+                }
+                catch (error) {
+                    yield rm(tmp, { force: true });
+                    throw error;
+                }
+            });
+        },
+        get(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                try {
+                    return { body: new Uint8Array(yield readFile(pathForKey(key))) };
+                }
+                catch (error) {
+                    const code = error.code;
+                    if (code === "ENOENT" || code === "EISDIR") {
+                        return undefined;
+                    }
+                    throw error;
+                }
+            });
+        },
+        delete(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield rm(pathForKey(key), { force: true });
+            });
+        },
+        stat(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return yield entryFor(key, pathForKey(key));
+            });
+        },
+        list(prefix) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a, e_1, _b, _c;
+                // Walk the deepest existing directory at or above the prefix, then keep
+                // the keys that actually start with it — `prefix` is a key prefix, not a
+                // directory, so `notes/sum` must match `notes/summary.md`.
+                const prefixPath = pathForKey(prefix);
+                const searchRoot = (yield isDirectory(prefixPath))
+                    ? prefixPath
+                    : join(prefixPath, "..");
+                const out = [];
+                try {
+                    for (var _d = true, _e = __asyncValues(walkFiles(searchRoot)), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+                        _c = _f.value;
+                        _d = false;
+                        const absPath = _c;
+                        const key = `${stripPrefix}${relative(root, absPath).split(sep).join("/")}`;
+                        if (!key.startsWith(prefix)) {
+                            continue;
+                        }
+                        const entry = yield entryFor(key, absPath);
+                        if (entry !== undefined) {
+                            out.push(entry);
+                        }
+                    }
+                }
+                catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                finally {
+                    try {
+                        if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+                    }
+                    finally { if (e_1) throw e_1.error; }
+                }
+                return out.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+            });
+        },
+    };
+}
+function isDirectory(absPath) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            return (yield stat(absPath)).isDirectory();
+        }
+        catch (_a) {
+            return false;
+        }
+    });
+}
+function walkFiles(dir) {
+    return __asyncGenerator(this, arguments, function* walkFiles_1() {
+        let entries;
+        try {
+            entries = yield __await(readdir(dir, { withFileTypes: true }));
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return yield __await(void 0);
+            }
+            throw error;
+        }
+        for (const entry of entries) {
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                yield __await(yield* __asyncDelegator(__asyncValues(walkFiles(abs))));
+            }
+            else if (entry.isFile() && !entry.name.startsWith(".tmp-")) {
+                yield yield __await(abs);
+            }
+        }
+    });
+}

package/dist/files.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The internal sink contract behind `ctx.host.files` — durable, file-shaped
+ * state that must outlive the engine process.
+ *
+ * Deliberately **not a filesystem**: no file descriptors, no seeking, no
+ * rename, no directories as first-class objects, and no POSIX errno contract
+ * — a sink that is an HTTP API can implement all of it. The framework
+ * **mints every key** from a stable, versioned scheme (see {@link fileKeys});
+ * sinks see opaque strings and never learn which deployment or session a key
+ * belongs to, which is what keeps one deployment's files unreachable from
+ * another's.
+ *
+ * Internal for now: the authored plug-in surface (`agent/files.ts` with a
+ * `defineFiles`, mirroring `defineStorage`) is deliberately deferred so this
+ * ships as exactly the hosted connector plus the local default. When it
+ * lands, {@link FileSink} is the contract authored sinks implement.
+ *
+ * Delivery semantics differ from {@link import("./storage.js").defineStorage}
+ * on purpose. Storage is a fire-and-forget mirror of framework state, so a
+ * throwing `put` is logged and dropped. Files are author data the next turn
+ * may depend on, so {@link HostFilesApi} writes are **awaited and surface
+ * their failure** — an author who writes evidence and then delegates has to
+ * know the write did not land.
+ */
+/** One entry returned by {@link FileSink.list}. */
+export interface FileSinkEntry {
+    /** Framework-minted key, as passed to {@link FileSink.put}. */
+    key: string;
+    size: number;
+    /** Last-modified epoch ms, when the sink tracks one. */
+    mtimeMs?: number;
+    /** Opaque version tag; required for `ifMatch` to be usable. */
+    etag?: string;
+}
+/** One stored value plus the version it was read at. */
+export interface FileSinkBody {
+    body: Uint8Array;
+    etag?: string;
+}
+/** Outcome of {@link FileSink.put}. */
+export interface FileSinkPutResult {
+    /** Version tag after the write, when the sink issues one. */
+    etag?: string;
+}
+/**
+ * What a sink can do beyond the four required calls. Absent flags are false,
+ * so the narrowest possible sink — four functions over an HTTP API — is valid
+ * and the framework degrades visibly rather than assuming.
+ */
+export interface FileSinkCapabilities {
+    /**
+     * `put` honors `ifMatch` and rejects a stale write. Required for
+     * {@link HostFilesApi} to report `conflictDetection`.
+     */
+    etags?: boolean;
+    /**
+     * The sink keeps a local copy at {@link FileSink.materializedPath} that the
+     * harness can read with ordinary file tools.
+     */
+    materialized?: boolean;
+    /** Largest value the sink accepts, in bytes. */
+    maxBytes?: number;
+}
+/**
+ * The pluggable file store. Keys are framework-minted opaque strings; a sink
+ * may treat them as flat keys or split on `/` to build a hierarchy.
+ */
+export interface FileSink {
+    /**
+     * Write or replace one value. When `ifMatch` is set and the sink reports
+     * {@link FileSinkCapabilities.etags}, the write must fail unless the stored
+     * version matches — throw {@link FileConflictError} to say so precisely.
+     * `ifMatch: null` means "must not already exist".
+     */
+    put(key: string, body: Uint8Array, options?: {
+        ifMatch?: string | null;
+    }): Promise<FileSinkPutResult | void>;
+    /** Read one value. Miss → `undefined`. */
+    get(key: string): Promise<FileSinkBody | Uint8Array | undefined>;
+    /** Remove one key. No-op when missing. */
+    delete(key: string): Promise<void>;
+    /** Entries whose key starts with `prefix`, in key order. */
+    list(prefix: string): Promise<FileSinkEntry[]>;
+    /** Per-key metadata without transferring the body. Optional; `list` is the fallback. */
+    stat?(key: string): Promise<FileSinkEntry | undefined>;
+    /**
+     * Absolute path of the sink's local copy of `key`, or `undefined` when it
+     * keeps none. Only consulted when
+     * {@link FileSinkCapabilities.materialized} is set.
+     */
+    materializedPath?(key: string): string | undefined;
+    capabilities?: FileSinkCapabilities;
+}
+/**
+ * The framework-owned file key scheme, a stable versioned contract under
+ * {@link STORAGE_KEY_ROOT}. Sinks may treat these as opaque, or route on
+ * prefixes.
+ *
+ * | Key | Holds |
+ * | --- | --- |
+ * | `agentkit/v1/{agent}/files/deployment/{path}` | Deployment-scoped file, shared by every session and surviving redeploys |
+ * | `agentkit/v1/{agent}/files/deployment/{partition}/{path}` | Deployment-scoped file under an author partition (a PR, a customer, a branch) |
+ * | `agentkit/v1/{agent}/files/sessions/{sessionId}/{path}` | Session-scoped file |
+ *
+ * Scoping lives here, above the sink, so a sink cannot be handed a key for a
+ * deployment or session other than its own.
+ */
+export declare const fileKeys: {
+    readonly deployment: (agent: string, path: string) => string;
+    readonly deploymentPartition: (agent: string, partition: string, path: string) => string;
+    readonly session: (agent: string, sessionId: string, path: string) => string;
+    readonly deploymentPrefix: (agent: string) => string;
+    readonly sessionPrefix: (agent: string, sessionId: string) => string;
+};
+/** Errors raised by the file surface. Thrown by sinks and by the framework. */
+export declare class FileConflictError extends Error {
+    readonly key: string;
+    constructor(key: string, options?: {
+        cause?: unknown;
+        storedEtag?: string;
+    });
+    storedEtag?: string;
+}
+/** A path the framework refuses to mint a key for. */
+export declare class FilePathRejectedError extends Error {
+    constructor(message: string);
+}
+/** A session-scoped call with no session in scope. */
+export declare class FileSessionRequiredError extends Error {
+    constructor(message: string);
+}
+/** A value larger than the sink accepts. */
+export declare class FileTooLargeError extends Error {
+    readonly key: string;
+    readonly size: number;
+    readonly maxBytes: number;
+    constructor(key: string, size: number, maxBytes: number);
+}
+//# sourceMappingURL=files.d.ts.map

package/dist/files.d.ts.map

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

package/dist/files.js

@@ -0,0 +1,89 @@
+/**
+ * The internal sink contract behind `ctx.host.files` — durable, file-shaped
+ * state that must outlive the engine process.
+ *
+ * Deliberately **not a filesystem**: no file descriptors, no seeking, no
+ * rename, no directories as first-class objects, and no POSIX errno contract
+ * — a sink that is an HTTP API can implement all of it. The framework
+ * **mints every key** from a stable, versioned scheme (see {@link fileKeys});
+ * sinks see opaque strings and never learn which deployment or session a key
+ * belongs to, which is what keeps one deployment's files unreachable from
+ * another's.
+ *
+ * Internal for now: the authored plug-in surface (`agent/files.ts` with a
+ * `defineFiles`, mirroring `defineStorage`) is deliberately deferred so this
+ * ships as exactly the hosted connector plus the local default. When it
+ * lands, {@link FileSink} is the contract authored sinks implement.
+ *
+ * Delivery semantics differ from {@link import("./storage.js").defineStorage}
+ * on purpose. Storage is a fire-and-forget mirror of framework state, so a
+ * throwing `put` is logged and dropped. Files are author data the next turn
+ * may depend on, so {@link HostFilesApi} writes are **awaited and surface
+ * their failure** — an author who writes evidence and then delegates has to
+ * know the write did not land.
+ */
+import { STORAGE_KEY_ROOT } from "./storage.js";
+// ============================================================================
+// Key scheme
+// ============================================================================
+/**
+ * The framework-owned file key scheme, a stable versioned contract under
+ * {@link STORAGE_KEY_ROOT}. Sinks may treat these as opaque, or route on
+ * prefixes.
+ *
+ * | Key | Holds |
+ * | --- | --- |
+ * | `agentkit/v1/{agent}/files/deployment/{path}` | Deployment-scoped file, shared by every session and surviving redeploys |
+ * | `agentkit/v1/{agent}/files/deployment/{partition}/{path}` | Deployment-scoped file under an author partition (a PR, a customer, a branch) |
+ * | `agentkit/v1/{agent}/files/sessions/{sessionId}/{path}` | Session-scoped file |
+ *
+ * Scoping lives here, above the sink, so a sink cannot be handed a key for a
+ * deployment or session other than its own.
+ */
+export const fileKeys = {
+    deployment: (agent, path) => `${STORAGE_KEY_ROOT}/${agent}/files/deployment/${path}`,
+    deploymentPartition: (agent, partition, path) => `${STORAGE_KEY_ROOT}/${agent}/files/deployment/${partition}/${path}`,
+    session: (agent, sessionId, path) => `${STORAGE_KEY_ROOT}/${agent}/files/sessions/${sessionId}/${path}`,
+    deploymentPrefix: (agent) => `${STORAGE_KEY_ROOT}/${agent}/files/deployment/`,
+    sessionPrefix: (agent, sessionId) => `${STORAGE_KEY_ROOT}/${agent}/files/sessions/${sessionId}/`,
+};
+/** Errors raised by the file surface. Thrown by sinks and by the framework. */
+export class FileConflictError extends Error {
+    constructor(key, options) {
+        super(`host.files write for "${key}" lost a race with another writer${(options === null || options === void 0 ? void 0 : options.storedEtag) === undefined
+            ? ""
+            : ` (stored version ${options.storedEtag})`}`);
+        this.key = key;
+        this.name = "FileConflictError";
+        if ((options === null || options === void 0 ? void 0 : options.cause) !== undefined) {
+            this.cause = options.cause;
+        }
+        if ((options === null || options === void 0 ? void 0 : options.storedEtag) !== undefined) {
+            this.storedEtag = options.storedEtag;
+        }
+    }
+}
+/** A path the framework refuses to mint a key for. */
+export class FilePathRejectedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FilePathRejectedError";
+    }
+}
+/** A session-scoped call with no session in scope. */
+export class FileSessionRequiredError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FileSessionRequiredError";
+    }
+}
+/** A value larger than the sink accepts. */
+export class FileTooLargeError extends Error {
+    constructor(key, size, maxBytes) {
+        super(`host.files value for "${key}" is ${size} bytes, over the sink's ${maxBytes}-byte limit`);
+        this.key = key;
+        this.size = size;
+        this.maxBytes = maxBytes;
+        this.name = "FileTooLargeError";
+    }
+}

package/dist/internal/ab-collector.js

@@ -103,7 +103,7 @@ export class ABCollector {
                         experiment: experiment.name,
                         variant,
                     }, (key, error) => {
-                        this.logger(`[agentkit] ab "${experiment.name}" derive.${key} threw: ${describeError(error)}`);
+                        this.logger(`[agent-sdk] ab "${experiment.name}" derive.${key} threw: ${describeError(error)}`);
                     });
                 }
                 if (!options.emitSamples) {
@@ -118,7 +118,7 @@ export class ABCollector {
                         yield def.onSample(sample);
                     }
                     catch (error) {
-                        this.logger(`[agentkit] ab "${experiment.name}" onSample threw: ${describeError(error)}`);
+                        this.logger(`[agent-sdk] ab "${experiment.name}" onSample threw: ${describeError(error)}`);
                     }
                     (_b = this.persistSample) === null || _b === void 0 ? void 0 : _b.call(this, sample);
                 }

package/dist/internal/ab-fold.js

@@ -113,7 +113,7 @@ export function applyABDerive(state, events, experiments, sessionInfo, agentName
             const ctx = collectContext(experiment.name, variant, sessionInfo, agentName);
             for (const event of events) {
                 yield applyDeriveForEvent(accum.metrics.custom, def.derive, event, ctx, (key, error) => {
-                    logger(`[agentkit] ab "${experiment.name}" derive.${key} threw: ${describeError(error)}`);
+                    logger(`[agent-sdk] ab "${experiment.name}" derive.${key} threw: ${describeError(error)}`);
                 });
             }
         }

package/dist/internal/cli-ax.d.ts

@@ -201,8 +201,8 @@ export declare function cmdSession(sessionId: string | undefined, options: AxCli
  * With a session id: per-turn token usage + estimated cost for that session.
  * Without one: one row per session (all sessions on the target) plus a
  * total row. `--json` prints the underlying report(s); text is the default.
- * Costs are the engine's recorded estimates on `turn.completed` events
- * (see `model-pricing.ts`); turns persisted before cost tracking simply
+ * Costs are recorded on `turn.completed` via `POST /v1/models/estimate-cost`
+ * (billed usage when available). Turns persisted before cost tracking simply
  * count as unpriced.
  */
 export declare function cmdCost(sessionId: string | undefined, options: AxCliOptions): Promise<number>;

package/dist/internal/cli-ax.js

@@ -1420,8 +1420,8 @@ const COST_FETCH_CONCURRENCY = 4;
  * With a session id: per-turn token usage + estimated cost for that session.
  * Without one: one row per session (all sessions on the target) plus a
  * total row. `--json` prints the underlying report(s); text is the default.
- * Costs are the engine's recorded estimates on `turn.completed` events
- * (see `model-pricing.ts`); turns persisted before cost tracking simply
+ * Costs are recorded on `turn.completed` via `POST /v1/models/estimate-cost`
+ * (billed usage when available). Turns persisted before cost tracking simply
  * count as unpriced.
  */
 export function cmdCost(sessionId, options) {

package/dist/internal/cli-deploy.d.ts

@@ -1,5 +1,5 @@
 /**
- * `agentkit deploy | deployments | deployment | stop | rotate-token |
+ * `agent-sdk deploy | deployments | deployment | stop | rotate-token |
  * rotate-pod-credential | secrets set|list|unset` — Heroku-style deploys
  * onto Cursor's managed agent-serve hosting.
  *

package/dist/internal/cli-deploy.d.ts.map

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

package/dist/internal/cli-deploy.js

@@ -1,5 +1,5 @@
 /**
- * `agentkit deploy | deployments | deployment | stop | rotate-token |
+ * `agent-sdk deploy | deployments | deployment | stop | rotate-token |
  * rotate-pod-credential | secrets set|list|unset` — Heroku-style deploys
  * onto Cursor's managed agent-serve hosting.
  *
@@ -360,7 +360,7 @@ function deployOne(ctx, options, target, extras) {
         var _a, _b, _c, _d, _e, _f, _g;
         const { dir, slug } = target;
         // Fill --repo/--ref/--path from the local git checkout when omitted so
-        // `agentkit deploy` inside an agent directory is enough. Only probe git
+        // `agent-sdk deploy` inside an agent directory is enough. Only probe git
         // for real agent projects (avoids ambient monorepo remotes when someone
         // deploys a bare --slug). Explicit flags always win.
         const isAgent = yield isAgentProjectDir(dir);
@@ -676,6 +676,11 @@ export function cmdDeploymentStatus(slug, options) {
             detail.serviceAccountId !== null) {
             lines.push(`  service account: ${detail.serviceAccountId}`);
         }
+        if (detail.agentStoreSourceId !== undefined) {
+            // The durable file store's address: GET /v0/agent-serve-files/<id> lists
+            // it, and the pod sees it as AGENT_SERVE_STORE_SOURCE_ID.
+            lines.push(`  file store:  ${detail.agentStoreSourceId}`);
+        }
         if (detail.egressAllowedDomains !== undefined &&
             detail.egressAllowedDomains.length > 0) {
             lines.push(`  egress:      ${detail.egressAllowedDomains.join(", ")}`);

package/dist/internal/cli-docs.d.ts

@@ -1,5 +1,5 @@
 /**
- * `agentkit docs` / `npx @cursor/july docs` — serve the shipped VitePress
+ * `agent-sdk docs` / `npx @cursor/july docs` — serve the shipped VitePress
  * site on loopback and open it in a browser. Does not start an agent host.
  */
 import { createServer } from "node:http";

package/dist/internal/cli-docs.js

@@ -1,5 +1,5 @@
 /**
- * `agentkit docs` / `npx @cursor/july docs` — serve the shipped VitePress
+ * `agent-sdk docs` / `npx @cursor/july docs` — serve the shipped VitePress
  * site on loopback and open it in a browser. Does not start an agent host.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {