@cursor/bdk 0.2.1

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

@@ -0,0 +1 @@
+{"version":3,"file":"handleAgentServeTrigger.d.ts","sourceRoot":"","sources":["../../src/internal/handleAgentServeTrigger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAOxE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAwB,KAAK,6BAA6B,EAAE,MAAM,oBAAoB,CAAC;AAE9F,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;IACzC,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,6BAA6B,CAAC;CACnD;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,oBAAoB,CAAC;IAC9B,IAAI,EAAE,kBAAkB,CAAC;CAC1B;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,QAAQ,CAAC;IACf,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,6BAA6B,EAAE,CAAC;IACzC,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,6BAA6B,CAAC;CACnD;AAED,MAAM,MAAM,sBAAsB,GAAG,4BAA4B,GAAG,4BAA4B,CAAC;AAEjG,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;;;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,CAWlC"}

package/dist/internal/handleAgentServeTrigger.js

@@ -0,0 +1,199 @@
+/**
+ * Unified entry for dispatching agent-serve triggers from an external ingress
+ * (e.g. the Cursor backend GitHub webhook or Origin cursor-internal tap).
+ * Mirrors Automations' `handleAutomationTrigger`.
+ *
+ * Callers must authenticate the delivery before invoking this (the backend
+ * verifies GitHub HMAC at `/github_webhook` and Origin v1ed at the
+ * cursor-internal app). This fan-out does not re-check signatures — same
+ * trust model as Bugbot after `verifyGithubRequest`.
+ *
+ * Each agent's `onPullRequest` / `onComment` / … hooks decide whether to run.
+ */
+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 { dispatchGitHubWebhook, getGitHubChannelOptions, } from "../channels/github/github-channel.js";
+import { dispatchOriginWebhook, getOriginChannelOptions, originIngressExtractPayload, parseOriginWebhookEnvelope, } from "../channels/origin/origin-channel.js";
+import { bindLocalIngressSend } from "./local-ingress.js";
+/**
+ * Build fan-out targets from mounted agent projects that export a github
+ * channel created via {@link githubChannel}.
+ */
+export function collectGitHubTriggerTargets(input) {
+    const targets = [];
+    for (const mount of input.mounts) {
+        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),
+            });
+        }
+    }
+    return targets;
+}
+/**
+ * Build fan-out targets from mounted agent projects that export an origin
+ * channel created via {@link originChannel}.
+ */
+export function collectOriginTriggerTargets(input) {
+    const targets = [];
+    for (const mount of input.mounts) {
+        for (const channel of mount.channels) {
+            const options = getOriginChannelOptions(channel.definition);
+            if (options === undefined) {
+                continue;
+            }
+            targets.push({
+                slug: mount.slug,
+                options,
+                args: mount.buildHandlerArgs(channel.id),
+            });
+        }
+    }
+    return targets;
+}
+/**
+ * Dispatch an agent-serve trigger. GitHub and Origin webhook fan-out.
+ */
+export function handleAgentServeTrigger(event) {
+    return __awaiter(this, void 0, void 0, function* () {
+        switch (event.type) {
+            case "github":
+                return handleAgentServeGitHubTrigger(event);
+            case "origin":
+                return handleAgentServeOriginTrigger(event);
+            default: {
+                const _ = event;
+                throw new Error(`handleAgentServeTrigger: unknown event type: ${String(_)}`);
+            }
+        }
+    });
+}
+function handleAgentServeGitHubTrigger(event) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (event.eventName === "ping") {
+            return {
+                ok: true,
+                event: "ping",
+                targets: [],
+            };
+        }
+        let payload;
+        try {
+            payload = JSON.parse(event.bodyText);
+        }
+        catch (_a) {
+            return {
+                ok: false,
+                event: event.eventName,
+                targets: [
+                    {
+                        slug: "",
+                        status: 400,
+                        body: { ok: false, error: "invalid_json" },
+                    },
+                ],
+            };
+        }
+        const targets = [];
+        for (const target of event.targets) {
+            const args = event.eventName === null
+                ? target.args
+                : bindLocalIngressSend(target.args, Object.assign({ identity: target.options.continuation, kind: "github", eventType: event.eventName, payload }, (event.routeContinuation === undefined
+                    ? {}
+                    : { routeContinuation: event.routeContinuation })));
+            const response = yield dispatchGitHubWebhook({
+                options: target.options,
+                eventName: event.eventName,
+                payload,
+                deliveryId: event.deliveryId,
+                args,
+            });
+            targets.push(yield triggerTargetResult(target.slug, response));
+        }
+        return {
+            ok: true,
+            event: event.eventName,
+            targets,
+        };
+    });
+}
+function handleAgentServeOriginTrigger(event) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let payload;
+        try {
+            payload = JSON.parse(event.bodyText);
+        }
+        catch (_a) {
+            return {
+                ok: false,
+                event: null,
+                targets: [
+                    {
+                        slug: "",
+                        status: 400,
+                        body: { ok: false, error: "invalid_json" },
+                    },
+                ],
+            };
+        }
+        const envelope = parseOriginWebhookEnvelope(payload);
+        if (envelope === null) {
+            return {
+                ok: false,
+                event: null,
+                targets: [
+                    {
+                        slug: "",
+                        status: 400,
+                        body: { ok: false, error: "invalid_origin_payload" },
+                    },
+                ],
+            };
+        }
+        const targets = [];
+        for (const target of event.targets) {
+            const response = yield dispatchOriginWebhook({
+                options: target.options,
+                envelope,
+                args: bindLocalIngressSend(target.args, Object.assign({ identity: target.options.continuation, kind: "origin", eventType: envelope.event.type, payload: originIngressExtractPayload(envelope) }, (event.routeContinuation === undefined
+                    ? {}
+                    : { routeContinuation: event.routeContinuation }))),
+            });
+            targets.push(yield triggerTargetResult(target.slug, response));
+        }
+        return {
+            ok: true,
+            event: envelope.event.type,
+            targets,
+        };
+    });
+}
+function triggerTargetResult(slug, response) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let body;
+        try {
+            body = yield response.json();
+        }
+        catch (_a) {
+            body = { ok: false, error: "invalid_response_json" };
+        }
+        return {
+            slug,
+            status: response.status,
+            body,
+        };
+    });
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Author-facing durable file storage for {@link HostContext.files}.
+ *
+ * On Cursor-managed hosting the bytes live in the deployment's durable
+ * store; otherwise they land under `--state-root/files` on local disk, which
+ * is what makes `host.files` work self-hosted with no storage service at all.
+ *
+ * Everything that decides *which* bytes an author may reach lives here rather
+ * than in the sink: scope selection, path validation, and key minting through
+ * {@link fileKeys}. A sink only ever sees a fully-qualified opaque key, so an
+ * authored sink — including one a customer wrote against their own Dropbox —
+ * cannot be steered into another deployment's or another session's files.
+ */
+import { type FileSink } from "../files.js";
+import type { HostFilesApi } from "../types.js";
+export interface CreateHostFilesApiOptions {
+    agentName: string;
+    /** Local disk root for the default sink. Required unless `sink` is supplied. */
+    stateRoot?: string;
+    /** Explicit sink override (tests). Omitted → hosted store or local disk. */
+    sink?: FileSink;
+    /** Session bound for `scope: "session"` calls; prefer {@link HostFilesApi.forSession}. */
+    sessionId?: string;
+    /** Environment consulted when choosing the default sink (tests). */
+    env?: NodeJS.ProcessEnv;
+}
+/** Build the host file API for one agent process. */
+export declare function createHostFilesApi(options: CreateHostFilesApiOptions): HostFilesApi;
+//# sourceMappingURL=host-files.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"host-files.d.ts","sourceRoot":"","sources":["../../src/internal/host-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAGL,KAAK,QAAQ,EAId,MAAM,aAAa,CAAC;AAMrB,OAAO,KAAK,EAGV,YAAY,EAGb,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,qDAAqD;AACrD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,YAAY,CAOnF"}

package/dist/internal/host-files.js

@@ -0,0 +1,274 @@
+/**
+ * Author-facing durable file storage for {@link HostContext.files}.
+ *
+ * On Cursor-managed hosting the bytes live in the deployment's durable
+ * store; otherwise they land under `--state-root/files` on local disk, which
+ * is what makes `host.files` work self-hosted with no storage service at all.
+ *
+ * Everything that decides *which* bytes an author may reach lives here rather
+ * than in the sink: scope selection, path validation, and key minting through
+ * {@link fileKeys}. A sink only ever sees a fully-qualified opaque key, so an
+ * authored sink — including one a customer wrote against their own Dropbox —
+ * cannot be steered into another deployment's or another session's files.
+ */
+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 { join, normalize, sep } from "node:path";
+import { FilePathRejectedError, FileSessionRequiredError, FileTooLargeError, fileKeys, } from "../files.js";
+import { cursorHostedFiles, isCursorHostedFilesAvailable, } from "../files-backends/cursor-hosted.js";
+import { localFiles } from "../files-backends/local-fs.js";
+/** Build the host file API for one agent process. */
+export function createHostFilesApi(options) {
+    var _a;
+    const sink = (_a = options.sink) !== null && _a !== void 0 ? _a : createDefaultSink(options);
+    return createBoundHostFilesApi(Object.assign({ agentName: options.agentName, sink }, (options.sessionId === undefined ? {} : { sessionId: options.sessionId })));
+}
+/**
+ * Pick the default sink.
+ *
+ * On Cursor-managed hosting the durable store is the only correct answer —
+ * falling back to pod-local disk there would accept writes that vanish with
+ * the pod, which is the failure this surface exists to remove. Off hosting,
+ * local disk keeps `serve --dev`, replay, fixtures, and evals working with no
+ * storage service. This is the gate all six hosted agents write by hand in
+ * their `agent/storage.ts`; resolving it here means authors do not repeat it.
+ */
+function createDefaultSink(options) {
+    var _a;
+    if (isCursorHostedFilesAvailable((_a = options.env) !== null && _a !== void 0 ? _a : process.env)) {
+        return cursorHostedFiles();
+    }
+    if (options.stateRoot === undefined) {
+        throw new Error("createHostFilesApi needs a stateRoot for the default local-disk sink, or an explicit sink");
+    }
+    return localFiles({
+        filesRoot: join(options.stateRoot, "files"),
+        stripKeyPrefix: localKeyPrefix(options.agentName),
+    });
+}
+/** On-disk layout drops the framework key prefix so paths stay navigable. */
+function localKeyPrefix(agentName) {
+    return fileKeys.deploymentPrefix(agentName).replace(/deployment\/$/, "");
+}
+function createBoundHostFilesApi(state) {
+    var _a;
+    const sinkCaps = (_a = state.sink.capabilities) !== null && _a !== void 0 ? _a : {};
+    const capabilities = Object.assign({ conflictDetection: sinkCaps.etags === true, materialized: sinkCaps.materialized === true && typeof state.sink.materializedPath === "function" }, (sinkCaps.maxBytes === undefined ? {} : { maxBytes: sinkCaps.maxBytes }));
+    const keyFor = (path, scope) => mintKey(state, path, scope);
+    const api = {
+        capabilities,
+        forSession(sessionId) {
+            const trimmed = sessionId.trim();
+            if (trimmed === "") {
+                throw new FileSessionRequiredError("host.files.forSession requires a non-empty session id");
+            }
+            return createBoundHostFilesApi(Object.assign(Object.assign({}, state), { sessionId: trimmed }));
+        },
+        read(path, options) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const bytes = yield api.readBytes(path, options);
+                return bytes === undefined
+                    ? undefined
+                    : Buffer.from(bytes).toString((_a = options === null || options === void 0 ? void 0 : options.encoding) !== null && _a !== void 0 ? _a : "utf8");
+            });
+        },
+        readBytes(path, options) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const found = yield state.sink.get(keyFor(path, options === null || options === void 0 ? void 0 : options.scope));
+                if (found === undefined) {
+                    return undefined;
+                }
+                return found instanceof Uint8Array ? found : found.body;
+            });
+        },
+        write(path, data, options) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const key = keyFor(path, options === null || options === void 0 ? void 0 : options.scope);
+                const body = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data);
+                const maxBytes = capabilities.maxBytes;
+                if (maxBytes !== undefined && body.byteLength > maxBytes) {
+                    throw new FileTooLargeError(key, body.byteLength, maxBytes);
+                }
+                yield state.sink.put(key, body, (options === null || options === void 0 ? void 0 : options.ifMatch) === undefined ? undefined : { ifMatch: options.ifMatch });
+            });
+        },
+        remove(path, options) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield state.sink.delete(keyFor(path, options === null || options === void 0 ? void 0 : options.scope));
+            });
+        },
+        exists(path, options) {
+            return __awaiter(this, void 0, void 0, function* () {
+                return (yield api.stat(path, options)) !== undefined;
+            });
+        },
+        stat(path, options) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const key = keyFor(path, options === null || options === void 0 ? void 0 : options.scope);
+                const entry = yield statKey(state.sink, key);
+                if (entry === undefined) {
+                    return undefined;
+                }
+                return Object.assign(Object.assign({ size: entry.size }, (entry.mtimeMs === undefined ? {} : { mtimeMs: entry.mtimeMs })), (entry.etag === undefined ? {} : { etag: entry.etag }));
+            });
+        },
+        list(prefix, options) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const scopePrefix = mintPrefix(state, options === null || options === void 0 ? void 0 : options.scope);
+                const rel = prefix === undefined ? "" : normalizeRelPath(prefix, true);
+                const entries = yield state.sink.list(`${scopePrefix}${rel}`);
+                const out = [];
+                for (const entry of entries) {
+                    if (!entry.key.startsWith(scopePrefix)) {
+                        // A sink that widens the prefix must not leak keys from another
+                        // scope through a listing.
+                        continue;
+                    }
+                    out.push(Object.assign({ path: entry.key.slice(scopePrefix.length), size: entry.size }, (entry.mtimeMs === undefined ? {} : { mtimeMs: entry.mtimeMs })));
+                }
+                return out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+            });
+        },
+        materializedPath(path, options) {
+            var _a, _b;
+            if (!capabilities.materialized) {
+                return undefined;
+            }
+            return (_b = (_a = state.sink).materializedPath) === null || _b === void 0 ? void 0 : _b.call(_a, keyFor(path, options === null || options === void 0 ? void 0 : options.scope));
+        },
+    };
+    return api;
+}
+function statKey(sink, key) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (typeof sink.stat === "function") {
+            return yield sink.stat(key);
+        }
+        const entries = yield sink.list(key);
+        return entries.find(entry => entry.key === key);
+    });
+}
+// ============================================================================
+// Key minting
+// ============================================================================
+function mintKey(state, path, scope) {
+    const rel = normalizeRelPath(path, false);
+    const resolved = resolveScope(state, scope);
+    if (resolved.kind === "session") {
+        return fileKeys.session(state.agentName, resolved.sessionId, rel);
+    }
+    return resolved.partition === undefined
+        ? fileKeys.deployment(state.agentName, rel)
+        : fileKeys.deploymentPartition(state.agentName, resolved.partition, rel);
+}
+function mintPrefix(state, scope) {
+    const resolved = resolveScope(state, scope);
+    if (resolved.kind === "session") {
+        return fileKeys.sessionPrefix(state.agentName, resolved.sessionId);
+    }
+    const base = fileKeys.deploymentPrefix(state.agentName);
+    return resolved.partition === undefined ? base : `${base}${resolved.partition}/`;
+}
+function resolveScope(state, scope) {
+    var _a;
+    if (scope === "deployment") {
+        return { kind: "deployment" };
+    }
+    if (scope !== undefined && typeof scope === "object") {
+        if (scope.kind === "deployment") {
+            return scope.partition === undefined
+                ? { kind: "deployment" }
+                : { kind: "deployment", partition: segment(scope.partition) };
+        }
+        const explicit = (_a = scope.sessionId) !== null && _a !== void 0 ? _a : state.sessionId;
+        return { kind: "session", sessionId: requireSession(explicit) };
+    }
+    // Default and explicit `"session"` both bind to the caller's own session, so
+    // a relative path can never be re-read as another session's.
+    return { kind: "session", sessionId: requireSession(state.sessionId) };
+}
+function requireSession(sessionId) {
+    if (sessionId === undefined || sessionId.trim() === "") {
+        throw new FileSessionRequiredError("host.files needs a session in scope: call forSession(sessionId), pass { scope: { kind: 'session', sessionId } }, or use { scope: 'deployment' }");
+    }
+    return segment(sessionId);
+}
+/**
+ * Normalize an author path into key-relative form. Rejects traversal, NUL,
+ * backslashes, trailing slashes, and the `.cursor*` prefix the Agent Store
+ * reserves for Cursor-managed content — refusing here turns an opaque failure
+ * deep in a sink (or a 400 from the hosted API, which accepts each path in
+ * exactly one spelling) into one the author can act on, and keeps the rule
+ * identical across sinks.
+ */
+function normalizeRelPath(path, allowEmpty) {
+    if (typeof path !== "string") {
+        throw new FilePathRejectedError("host.files path must be a string");
+    }
+    const trimmed = path.trim().replace(/^\/+/, "");
+    if (trimmed === "") {
+        if (allowEmpty) {
+            return "";
+        }
+        throw new FilePathRejectedError("host.files path must be non-empty");
+    }
+    if (trimmed.includes("\0")) {
+        throw new FilePathRejectedError(`host.files path is not allowed: ${path}`);
+    }
+    // A backslash is a separator on Windows and a literal on POSIX, so a key
+    // minted from one would name different objects on different hosts — and the
+    // hosted API refuses it. Same rule as `segment()` below.
+    if (trimmed.includes("\\")) {
+        throw new FilePathRejectedError(`host.files path is not allowed: ${path}`);
+    }
+    // On an object path, a trailing slash would mint a key ending in "/" — an
+    // empty "directory marker" object, never what an author writing a file
+    // meant, and refused by the hosted API. A listing prefix (`allowEmpty`) is
+    // a different thing: there a trailing slash legitimately scopes to a
+    // directory's contents.
+    if (!allowEmpty && trimmed.endsWith("/")) {
+        throw new FilePathRejectedError(`host.files path is not allowed: ${path}`);
+    }
+    const normalized = normalize(trimmed).split(sep).join("/");
+    if (normalized === ".." ||
+        normalized === "." ||
+        normalized.startsWith("../") ||
+        normalized.includes("/../") ||
+        normalized.endsWith("/..")) {
+        throw new FilePathRejectedError(`host.files path is not allowed: ${path}`);
+    }
+    for (const part of normalized.split("/")) {
+        if (isReservedSegment(part)) {
+            throw new FilePathRejectedError(`host.files path segment "${part}" is reserved for Cursor-managed content: ${path}`);
+        }
+    }
+    return normalized;
+}
+/** One key segment (session id, partition): no separators, no traversal. */
+function segment(value) {
+    const trimmed = value.trim();
+    if (trimmed === "" ||
+        trimmed === "." ||
+        trimmed === ".." ||
+        trimmed.includes("/") ||
+        trimmed.includes("\\") ||
+        trimmed.includes("\0")) {
+        throw new FilePathRejectedError(`host.files key segment is not allowed: ${value}`);
+    }
+    if (isReservedSegment(trimmed)) {
+        throw new FilePathRejectedError(`host.files key segment "${trimmed}" is reserved for Cursor-managed content`);
+    }
+    return trimmed;
+}
+/** Mirrors the server's reserved-prefix rule (`AGENT_STORE_RESERVED_CURSOR_PATH_PREFIX`). */
+function isReservedSegment(value) {
+    return value.toLowerCase().startsWith(".cursor");
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Author-facing durable JSON KV for {@link HostContext.kv}.
+ *
+ * When `defineStorage` is authored and exposes `get`, values live in that
+ * sink under {@link storageKeys.kv}. Otherwise they land as one JSON file
+ * per key under `--state-root/kv` (local dogfood / no durable plug-in).
+ */
+import type { HostKvApi } from "../types.js";
+import type { AuthorKvStore } from "./storage-roles.js";
+export interface CreateHostKvApiOptions {
+    agentName: string;
+    stateRoot: string;
+    /**
+     * Author KV backend. Narrowed to {@link AuthorKvStore} so this path cannot
+     * reach framework session state, which is headed somewhere else entirely.
+     */
+    storage?: AuthorKvStore;
+}
+/** Build the host KV API for one agent process. */
+export declare function createHostKvApi(options: CreateHostKvApiOptions): HostKvApi;
+//# sourceMappingURL=host-kv.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"host-kv.d.ts","sourceRoot":"","sources":["../../src/internal/host-kv.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,mDAAmD;AACnD,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,SAAS,CAa1E"}

package/dist/internal/host-kv.js

@@ -0,0 +1,77 @@
+/**
+ * Author-facing durable JSON KV for {@link HostContext.kv}.
+ *
+ * When `defineStorage` is authored and exposes `get`, values live in that
+ * sink under {@link storageKeys.kv}. Otherwise they land as one JSON file
+ * per key under `--state-root/kv` (local dogfood / no durable plug-in).
+ */
+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 { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { storageKeys } from "../storage.js";
+/** Build the host KV API for one agent process. */
+export function createHostKvApi(options) {
+    const storage = options.storage;
+    if ((storage === null || storage === void 0 ? void 0 : storage.supportsAuthorKv) === true) {
+        return {
+            get: key => storage.kvGet(normalizeAuthorKey(key)),
+            put: (key, value) => storage.kvPut(normalizeAuthorKey(key), value),
+            delete: key => storage.kvDelete(normalizeAuthorKey(key)),
+        };
+    }
+    return createFilesystemKvApi({
+        agentName: options.agentName,
+        stateRoot: options.stateRoot,
+    });
+}
+function createFilesystemKvApi(options) {
+    const dir = join(options.stateRoot, "kv");
+    const filePath = (authorKey) => join(dir, `${encodeURIComponent(storageKeys.kv(options.agentName, authorKey))}.json`);
+    return {
+        get(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const authorKey = normalizeAuthorKey(key);
+                try {
+                    return JSON.parse(yield readFile(filePath(authorKey), "utf8"));
+                }
+                catch (error) {
+                    if (error.code === "ENOENT") {
+                        return undefined;
+                    }
+                    throw error;
+                }
+            });
+        },
+        put(key, value) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const authorKey = normalizeAuthorKey(key);
+                yield mkdir(dir, { recursive: true });
+                const target = filePath(authorKey);
+                const tmp = join(dir, `.tmp-${randomUUID()}`);
+                yield writeFile(tmp, JSON.stringify(value), "utf8");
+                yield rename(tmp, target);
+            });
+        },
+        delete(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const authorKey = normalizeAuthorKey(key);
+                yield rm(filePath(authorKey), { force: true });
+            });
+        },
+    };
+}
+function normalizeAuthorKey(key) {
+    if (typeof key !== "string" || key.trim() === "") {
+        throw new Error("host.kv key must be a non-empty string");
+    }
+    return key;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Author-facing OpenTelemetry surface for {@link HostContext.otel}.
+ *
+ * Always present on `ctx.host`. Counters and histograms no-op when no meter
+ * is running. `setAttributes` still tags open turn/tool spans when a
+ * collector is attached. `forSession` is engine-only so a tool cannot
+ * retarget another conversation's tags.
+ */
+import type { Meter } from "@opentelemetry/api";
+import type { HostOtelApi } from "../types.js";
+import type { OtelCollector } from "./otel/collector.js";
+export interface CreateHostOtelApiOptions {
+    agentName: string;
+    meter?: Meter;
+    collector?: OtelCollector;
+    /** Session bound for join tags; prefer {@link HostOtelSessionApi.forSession}. */
+    sessionId?: string;
+}
+/** Engine-only binding. Not part of the public {@link HostOtelApi}. */
+export interface HostOtelSessionApi extends HostOtelApi {
+    forSession(sessionId: string): HostOtelSessionApi;
+}
+/** Build the host OpenTelemetry API for one agent process. */
+export declare function createHostOtelApi(options: CreateHostOtelApiOptions): HostOtelSessionApi;
+//# sourceMappingURL=host-otel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"host-otel.d.ts","sourceRoot":"","sources":["../../src/internal/host-otel.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAsB,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,aAAa,CAAC;AAGnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAsBzD,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,CAAC;CACnD;AAsBD,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,kBAAkB,CAYvF"}