npm - @cursor/july - Versions diffs - 0.1.6 → 0.1.8 - Mend

@cursor/july 0.1.6 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (179) hide show

package/dist/bin/agent-serve.js +73 -19
package/dist/channels/slack/channel-watch.d.ts +6 -1
package/dist/channels/slack/channel-watch.d.ts.map +1 -1
package/dist/channels/slack/channel-watch.js +22 -1
package/dist/channels/slack/cursor-account.d.ts +4 -0
package/dist/channels/slack/cursor-account.d.ts.map +1 -1
package/dist/channels/slack/cursor-account.js +12 -2
package/dist/channels/slack/defaults.d.ts +10 -5
package/dist/channels/slack/defaults.d.ts.map +1 -1
package/dist/channels/slack/defaults.js +39 -17
package/dist/channels/slack/dispatch.d.ts +18 -0
package/dist/channels/slack/dispatch.d.ts.map +1 -1
package/dist/channels/slack/dispatch.js +141 -38
package/dist/channels/slack/inbound.d.ts +13 -3
package/dist/channels/slack/inbound.d.ts.map +1 -1
package/dist/channels/slack/inbound.js +17 -9
package/dist/channels/slack/index.d.ts +4 -0
package/dist/channels/slack/index.d.ts.map +1 -1
package/dist/channels/slack/index.js +4 -0
package/dist/channels/slack/live-delivery.d.ts.map +1 -1
package/dist/channels/slack/live-delivery.js +1 -0
package/dist/channels/slack/manifest.d.ts.map +1 -1
package/dist/channels/slack/manifest.js +3 -0
package/dist/channels/slack/nudge-carrier.d.ts +19 -0
package/dist/channels/slack/nudge-carrier.d.ts.map +1 -0
package/dist/channels/slack/nudge-carrier.js +166 -0
package/dist/channels/slack/nudge-store.d.ts +61 -0
package/dist/channels/slack/nudge-store.d.ts.map +1 -0
package/dist/channels/slack/nudge-store.js +266 -0
package/dist/channels/slack/slack-channel.d.ts.map +1 -1
package/dist/channels/slack/slack-channel.js +74 -25
package/dist/channels/slack/stop.d.ts +14 -0
package/dist/channels/slack/stop.d.ts.map +1 -0
package/dist/channels/slack/stop.js +22 -0
package/dist/channels/slack/thread-context.d.ts +81 -0
package/dist/channels/slack/thread-context.d.ts.map +1 -0
package/dist/channels/slack/thread-context.js +470 -0
package/dist/channels/slack/types.d.ts +27 -0
package/dist/channels/slack/types.d.ts.map +1 -1
package/dist/docs/404.html +2 -2
package/dist/docs/ab.html +4 -4
package/dist/docs/assets/{app.DMboGKUD.js → app.BP8mAVMW.js} +1 -1
package/dist/docs/assets/chunks/@localSearchIndexroot.DevOabKJ.js +1 -0
package/dist/docs/assets/chunks/{VPLocalSearchBox.DkEqEnJU.js → VPLocalSearchBox.1FXIZbz8.js} +1 -1
package/dist/docs/assets/chunks/{theme.ASugdMNm.js → theme.Dm1R02v9.js} +2 -2
package/dist/docs/assets/example-agents_index.md.CwtWu5ix.js +2 -0
package/dist/docs/assets/{example-agents_index.md.CRqJlnIf.lean.js → example-agents_index.md.CwtWu5ix.lean.js} +1 -1
package/dist/docs/assets/example-agents_oncall.md.BG_sUMly.js +10 -0
package/dist/docs/assets/example-agents_oncall.md.BG_sUMly.lean.js +1 -0
package/dist/docs/assets/{guides_slack.md.CCwqHvSV.js → guides_slack.md.FWale6Ip.js} +4 -3
package/dist/docs/assets/{guides_slack.md.CCwqHvSV.lean.js → guides_slack.md.FWale6Ip.lean.js} +1 -1
package/dist/docs/assets/{reference_sessions.md.DdjWabnN.js → reference_sessions.md.DLd6mvbv.js} +2 -2
package/dist/docs/assets/{reference_sessions.md.DdjWabnN.lean.js → reference_sessions.md.DLd6mvbv.lean.js} +1 -1
package/dist/docs/assets/{storage.md.CVnInNiN.js → storage.md.Cu3MwM2a.js} +3 -2
package/dist/docs/assets/{storage.md.CVnInNiN.lean.js → storage.md.Cu3MwM2a.lean.js} +1 -1
package/dist/docs/building-with-agents.html +4 -4
package/dist/docs/concepts.html +4 -4
package/dist/docs/deployment.html +4 -4
package/dist/docs/evals.html +4 -4
package/dist/docs/example-agents/approval-buddy.html +4 -4
package/dist/docs/example-agents/benny.html +5 -5
package/dist/docs/example-agents/bugbot.html +5 -5
package/dist/docs/example-agents/codebase-wiki.html +4 -4
package/dist/docs/example-agents/codeowners-review.html +4 -4
package/dist/docs/example-agents/concierge.html +4 -4
package/dist/docs/example-agents/fsd.html +4 -4
package/dist/docs/example-agents/index.html +6 -6
package/dist/docs/example-agents/knowledge-base.html +4 -4
package/dist/docs/example-agents/oncall.html +34 -0
package/dist/docs/example-agents/security-reviewer.html +4 -4
package/dist/docs/example-agents/slack-agent.html +4 -4
package/dist/docs/example-agents/weather-agent.html +4 -4
package/dist/docs/guides/agent-to-agent.html +4 -4
package/dist/docs/guides/cloud-runtime.html +4 -4
package/dist/docs/guides/github.html +4 -4
package/dist/docs/guides/human-in-the-loop.html +4 -4
package/dist/docs/guides/slack.html +7 -6
package/dist/docs/guides/webhooks.html +4 -4
package/dist/docs/hashmap.json +1 -1
package/dist/docs/hillclimbing.html +4 -4
package/dist/docs/index.html +4 -4
package/dist/docs/quickstart.html +4 -4
package/dist/docs/reference/agent-config.html +4 -4
package/dist/docs/reference/channels.html +4 -4
package/dist/docs/reference/cli.html +4 -4
package/dist/docs/reference/connections.html +4 -4
package/dist/docs/reference/hooks.html +4 -4
package/dist/docs/reference/http-api.html +4 -4
package/dist/docs/reference/instructions.html +4 -4
package/dist/docs/reference/playground.html +4 -4
package/dist/docs/reference/project-layout.html +4 -4
package/dist/docs/reference/schedules.html +4 -4
package/dist/docs/reference/sessions.html +5 -5
package/dist/docs/reference/skills.html +4 -4
package/dist/docs/reference/subagents.html +4 -4
package/dist/docs/reference/tools.html +4 -4
package/dist/docs/scaffolding-agents.html +4 -4
package/dist/docs/storage.html +7 -6
package/dist/docs/troubleshooting.html +4 -4
package/dist/evals.d.ts +2 -2
package/dist/internal/cli-ax.d.ts +23 -10
package/dist/internal/cli-ax.d.ts.map +1 -1
package/dist/internal/cli-ax.js +358 -55
package/dist/internal/cli-mcp.d.ts +64 -0
package/dist/internal/cli-mcp.d.ts.map +1 -0
package/dist/internal/cli-mcp.js +570 -0
package/dist/internal/distribution.d.ts.map +1 -1
package/dist/internal/distribution.js +2 -0
package/dist/internal/eval-run-store.d.ts +2 -0
package/dist/internal/eval-run-store.d.ts.map +1 -1
package/dist/internal/eval-run-store.js +4 -4
package/dist/internal/evals-client.d.ts +96 -0
package/dist/internal/evals-client.d.ts.map +1 -0
package/dist/internal/evals-client.js +262 -0
package/dist/internal/host-kv.d.ts +17 -0
package/dist/internal/host-kv.d.ts.map +1 -0
package/dist/internal/host-kv.js +77 -0
package/dist/internal/init-project.js +3 -3
package/dist/internal/server.d.ts.map +1 -1
package/dist/internal/server.js +19 -2
package/dist/internal/session-engine.d.ts +42 -7
package/dist/internal/session-engine.d.ts.map +1 -1
package/dist/internal/session-engine.js +247 -51
package/dist/internal/storage-coordinator.d.ts +18 -1
package/dist/internal/storage-coordinator.d.ts.map +1 -1
package/dist/internal/storage-coordinator.js +43 -0
package/dist/playground/assets/index-Bpr4Th4M.js +319 -0
package/dist/playground/index.html +1 -1
package/dist/storage-backends/file-kv.d.ts +42 -0
package/dist/storage-backends/file-kv.d.ts.map +1 -0
package/dist/storage-backends/file-kv.js +190 -0
package/dist/storage-backends/postgres-kv.d.ts +77 -0
package/dist/storage-backends/postgres-kv.d.ts.map +1 -0
package/dist/storage-backends/postgres-kv.js +180 -0
package/dist/storage.d.ts +10 -1
package/dist/storage.d.ts.map +1 -1
package/dist/storage.js +10 -1
package/dist/types.d.ts +79 -0
package/dist/types.d.ts.map +1 -1
package/docs/example-agents/index.md +14 -9
package/docs/example-agents/oncall.md +216 -0
package/docs/guides/slack.md +11 -2
package/docs/reference/sessions.md +13 -4
package/docs/storage.md +27 -0
package/package.json +15 -1
package/skills/framework-map/SKILL.md +6 -4
package/src/bin/agent-serve.ts +79 -18
package/src/channels/slack/channel-watch.ts +28 -1
package/src/channels/slack/cursor-account.ts +20 -0
package/src/channels/slack/defaults.ts +51 -20
package/src/channels/slack/dispatch.ts +215 -40
package/src/channels/slack/inbound.ts +30 -10
package/src/channels/slack/index.ts +4 -0
package/src/channels/slack/live-delivery.ts +1 -0
package/src/channels/slack/manifest.ts +3 -0
package/src/channels/slack/nudge-carrier.ts +182 -0
package/src/channels/slack/nudge-store.ts +308 -0
package/src/channels/slack/slack-channel.ts +106 -31
package/src/channels/slack/stop.ts +25 -0
package/src/channels/slack/thread-context.ts +572 -0
package/src/channels/slack/types.ts +27 -0
package/src/evals.ts +2 -2
package/src/internal/cli-ax.ts +466 -75
package/src/internal/cli-mcp.ts +708 -0
package/src/internal/distribution.ts +2 -0
package/src/internal/eval-run-store.ts +5 -0
package/src/internal/evals-client.ts +431 -0
package/src/internal/host-kv.ts +85 -0
package/src/internal/init-project.ts +3 -3
package/src/internal/server.ts +43 -0
package/src/internal/session-engine.ts +351 -50
package/src/internal/storage-coordinator.ts +41 -0
package/src/storage-backends/file-kv.ts +221 -0
package/src/storage-backends/postgres-kv.ts +248 -0
package/src/storage.ts +11 -1
package/src/types.ts +83 -0
package/dist/docs/assets/chunks/@localSearchIndexroot.O6eP7QZr.js +0 -1
package/dist/docs/assets/example-agents_index.md.CRqJlnIf.js +0 -2
package/dist/playground/assets/index-mux9aj5P.js +0 -319

package/dist/playground/index.html CHANGED Viewed

@@ -8,7 +8,7 @@
     />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>agent-serve playground</title>
-    <script type="module" crossorigin src="./assets/index-mux9aj5P.js"></script>
+    <script type="module" crossorigin src="./assets/index-Bpr4Th4M.js"></script>
     <link rel="stylesheet" crossorigin href="./assets/index-7GJIUFQj.css">
   </head>
   <body>

package/dist/storage-backends/file-kv.d.ts ADDED Viewed

@@ -0,0 +1,42 @@
+/**
+ * File-backed `defineStorage` helper: a file-per-key KV store plus
+ * file-backed `evals` / `abs` tables.
+ *
+ * Implements the whole `defineStorage` surface with zero external
+ * dependencies: the four KV methods against a flat directory of JSON files
+ * (one file per key, filename = URI-encoded key), eval runs as
+ * `eval-runs/<agent>/<runId>.json`, and A/B metrics as
+ * `ab/<agent>/samples.ndjson` (append-only) plus `ab/<agent>/snapshot.json`
+ * (latest aggregate). KV keys carry the agent name inside the framework
+ * key scheme, but the evals/abs tables have no such scheme — the agent
+ * subdirectory keeps agents sharing one storage `dir` from mixing or
+ * overwriting each other's history. Swap this for a real backend
+ * (Postgres, S3, …) in production; the contracts are identical.
+ *
+ * Layout notes:
+ * - KV filenames encode the full key (`encodeURIComponent(key) + ".json"`),
+ *   so `list(prefix)` is a readdir + decode + filter, returned in key
+ *   order as the contract requires.
+ * - `put` writes via tmp + rename: the framework serializes writes, but a
+ *   restore-path `get`/`list` can run concurrently and must never see a
+ *   torn file.
+ * - `get` distinguishes a definitive miss (ENOENT → `undefined`) from a
+ *   real failure (anything else throws) — on the lazy-restore path a
+ *   throw correctly fails the follow-up instead of forking the session.
+ */
+import type { StorageABTable, StorageConfig, StorageEvalsTable } from "../storage.js";
+export interface FileKvOptions {
+    /**
+     * Directory holding the storage files, relative to the agent project root
+     * (default `".agent-serve/kv"`). Absolute paths are used as-is.
+     */
+    dir?: string;
+}
+type FileKvMethods = Required<Pick<StorageConfig, "put" | "get" | "delete" | "list">> & {
+    evals: StorageEvalsTable;
+    abs: StorageABTable;
+};
+/** File-backed `defineStorage` methods, ready to spread into `defineStorage({...})`. */
+export declare function fileKv(options?: FileKvOptions): FileKvMethods;
+export {};
+//# sourceMappingURL=file-kv.d.ts.map

package/dist/storage-backends/file-kv.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"file-kv.d.ts","sourceRoot":"","sources":["../../src/storage-backends/file-kv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAeH,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAGb,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAGvB,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,KAAK,aAAa,GAAG,QAAQ,CAC3B,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,CACvD,GAAG;IACF,KAAK,EAAE,iBAAiB,CAAC;IACzB,GAAG,EAAE,cAAc,CAAC;CACrB,CAAC;AAEF,wFAAwF;AACxF,wBAAgB,MAAM,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,aAAa,CA+I7D"}

package/dist/storage-backends/file-kv.js ADDED Viewed

@@ -0,0 +1,190 @@
+/**
+ * File-backed `defineStorage` helper: a file-per-key KV store plus
+ * file-backed `evals` / `abs` tables.
+ *
+ * Implements the whole `defineStorage` surface with zero external
+ * dependencies: the four KV methods against a flat directory of JSON files
+ * (one file per key, filename = URI-encoded key), eval runs as
+ * `eval-runs/<agent>/<runId>.json`, and A/B metrics as
+ * `ab/<agent>/samples.ndjson` (append-only) plus `ab/<agent>/snapshot.json`
+ * (latest aggregate). KV keys carry the agent name inside the framework
+ * key scheme, but the evals/abs tables have no such scheme — the agent
+ * subdirectory keeps agents sharing one storage `dir` from mixing or
+ * overwriting each other's history. Swap this for a real backend
+ * (Postgres, S3, …) in production; the contracts are identical.
+ *
+ * Layout notes:
+ * - KV filenames encode the full key (`encodeURIComponent(key) + ".json"`),
+ *   so `list(prefix)` is a readdir + decode + filter, returned in key
+ *   order as the contract requires.
+ * - `put` writes via tmp + rename: the framework serializes writes, but a
+ *   restore-path `get`/`list` can run concurrently and must never see a
+ *   torn file.
+ * - `get` distinguishes a definitive miss (ENOENT → `undefined`) from a
+ *   real failure (anything else throws) — on the lazy-restore path a
+ *   throw correctly fails the follow-up instead of forking the session.
+ */
+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 { appendFile, mkdir, readdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { join } from "node:path";
+/** File-backed `defineStorage` methods, ready to spread into `defineStorage({...})`. */
+export function fileKv(options) {
+    const resolveDir = (ctx) => { var _a; return join(ctx.projectRoot, (_a = options === null || options === void 0 ? void 0 : options.dir) !== null && _a !== void 0 ? _a : ".agent-serve/kv"); };
+    // The evals/abs tables are scoped per agent (KV keys already carry the
+    // agent name via the framework key scheme).
+    const evalRunsDir = (ctx) => join(resolveDir(ctx), "eval-runs", encodeURIComponent(ctx.agentName));
+    const abDir = (ctx) => join(resolveDir(ctx), "ab", encodeURIComponent(ctx.agentName));
+    const filePath = (ctx, key) => join(resolveDir(ctx), `${encodeURIComponent(key)}.json`);
+    const readKey = (ctx, key) => __awaiter(this, void 0, void 0, function* () {
+        try {
+            return JSON.parse(yield readFile(filePath(ctx, key), "utf8"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return undefined; // definitive miss — key was never written
+            }
+            throw error; // real failure: let lazy restore fail the follow-up
+        }
+    });
+    return {
+        put(key, value, ctx) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield writeJsonAtomic({
+                    dir: resolveDir(ctx),
+                    fileName: `${encodeURIComponent(key)}.json`,
+                    value,
+                });
+            });
+        },
+        get(key, ctx) {
+            return readKey(ctx, key);
+        },
+        delete(key, ctx) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield rm(filePath(ctx, key), { force: true });
+            });
+        },
+        list(prefix, ctx) {
+            return __awaiter(this, void 0, void 0, function* () {
+                let names;
+                try {
+                    names = yield readdir(resolveDir(ctx));
+                }
+                catch (error) {
+                    if (error.code === "ENOENT") {
+                        return []; // nothing stored yet
+                    }
+                    throw error;
+                }
+                const keys = names
+                    .filter((name) => name.endsWith(".json"))
+                    .map((name) => decodeURIComponent(name.slice(0, -".json".length)))
+                    .filter((key) => key.startsWith(prefix))
+                    .sort();
+                const entries = [];
+                for (const key of keys) {
+                    const value = yield readKey(ctx, key);
+                    if (value !== undefined) {
+                        entries.push({ key, value });
+                    }
+                }
+                return entries;
+            });
+        },
+        // Playground eval batches: one JSON file per run under eval-runs/<agent>/.
+        evals: {
+            put(run, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield writeJsonAtomic({
+                        dir: evalRunsDir(ctx),
+                        fileName: `${encodeURIComponent(run.runId)}.json`,
+                        value: run,
+                    });
+                });
+            },
+            delete(runId, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield rm(join(evalRunsDir(ctx), `${encodeURIComponent(runId)}.json`), {
+                        force: true,
+                    });
+                });
+            },
+            list(ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    const dir = evalRunsDir(ctx);
+                    let names;
+                    try {
+                        names = yield readdir(dir);
+                    }
+                    catch (error) {
+                        if (error.code === "ENOENT") {
+                            return [];
+                        }
+                        throw error;
+                    }
+                    const runs = [];
+                    for (const name of names.filter((n) => n.endsWith(".json")).sort()) {
+                        // One unreadable/corrupt file must not wipe the whole history:
+                        // hydrate treats a throwing list() as "nothing saved".
+                        try {
+                            runs.push(JSON.parse(yield readFile(join(dir, name), "utf8")));
+                        }
+                        catch (_a) { }
+                    }
+                    return runs;
+                });
+            },
+        },
+        // A/B metrics: append-only sample log + latest aggregate snapshot,
+        // both under ab/<agent>/.
+        abs: {
+            putSample(sample, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    const dir = abDir(ctx);
+                    yield mkdir(dir, { recursive: true });
+                    yield appendFile(join(dir, "samples.ndjson"), `${JSON.stringify(sample)}\n`, "utf8");
+                });
+            },
+            putSnapshot(snapshot, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield writeJsonAtomic({
+                        dir: abDir(ctx),
+                        fileName: "snapshot.json",
+                        value: snapshot,
+                    });
+                });
+            },
+            getSnapshot(ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    try {
+                        return JSON.parse(yield readFile(join(abDir(ctx), "snapshot.json"), "utf8"));
+                    }
+                    catch (error) {
+                        if (error.code === "ENOENT") {
+                            return undefined;
+                        }
+                        throw error;
+                    }
+                });
+            },
+        },
+    };
+}
+/** tmp + rename write so concurrent readers never see a torn file. */
+function writeJsonAtomic(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield mkdir(args.dir, { recursive: true });
+        const tmp = join(args.dir, `.tmp-${randomUUID()}`);
+        yield writeFile(tmp, JSON.stringify(args.value), "utf8");
+        yield rename(tmp, join(args.dir, args.fileName));
+    });
+}

package/dist/storage-backends/postgres-kv.d.ts ADDED Viewed

@@ -0,0 +1,77 @@
+/**
+ * Postgres `defineStorage` helper on the agent-serve tables
+ * (backend/packages/prisma-bugbot):
+ *
+ *   agent_serve_kv(deployment_id, key, value JSONB, updated_at)
+ *     PRIMARY KEY (deployment_id, key)
+ *   agent_serve_eval_runs(deployment_id, agent, run_id, run JSONB, updated_at)
+ *     PRIMARY KEY (deployment_id, agent, run_id)
+ *   agent_serve_ab(deployment_id, agent, kind, ref, value JSONB, updated_at)
+ *     PRIMARY KEY (deployment_id, agent, kind, ref)
+ *
+ * `postgresStorage` implements the whole `defineStorage` surface as plain
+ * SQL: the four KV methods against the last-write-wins `agent_serve_kv`
+ * table (sessions, event chunks, continuations, reminders), the `evals`
+ * table against `agent_serve_eval_runs` (one row per playground eval
+ * batch), and the `abs` table against `agent_serve_ab` (`kind = 'sample'`
+ * rows per metric sample plus one `kind = 'snapshot'` row holding the
+ * latest aggregate).
+ *
+ * - KV `put` upserts on the primary key (LWW matches the framework contract).
+ * - KV `list` is a prefix range scan on the PK btree (`key >= p AND key < p||…`
+ *   spelled as LIKE with escaped wildcards, ordered by key).
+ * - `get` returning no row is a definitive miss (`undefined`); a connection
+ *   error throws, so lazy restore fails the follow-up instead of forking
+ *   the session.
+ *
+ * Connection comes from `BUGBOTDB_URL` — the repo-wide convention for the
+ * bugbot Postgres database, whose Prisma package owns these tables' schema
+ * and migrations; locally it falls back to the dev bugbot DB. Non-local
+ * URLs enable TLS (`ssl.rejectUnauthorized`) because PlanetScale requires
+ * SSL even when the vault URL omits `sslmode`.
+ * `deploymentId` scopes rows per deployment (`AGENT_SERVE_DEPLOYMENT_ID`);
+ * the local default keeps dev runs of different checkouts from colliding
+ * only by agent name.
+ *
+ * Callers must pass `Pool` from their own `import { Pool } from "pg"`.
+ * This module must not import `pg` itself: Node resolves modules from
+ * *this* file's directory tree, so a `pg` dep declared only on the
+ * consuming agent package would never be found after a hosted install.
+ */
+import type { StorageABTable, StorageConfig, StorageEvalsTable } from "../storage.js";
+/** Minimal `pg.Pool` surface used here (avoids importing `pg` from this path). */
+export interface PostgresQueryable {
+    query<T extends Record<string, unknown> = Record<string, unknown>>(text: string, values?: readonly unknown[]): Promise<{
+        rows: T[];
+    }>;
+}
+/** `pg.Pool` constructor supplied by the consuming example package. */
+export type PostgresPoolConstructor = new (config?: {
+    connectionString?: string;
+    max?: number;
+    ssl?: boolean | {
+        rejectUnauthorized?: boolean;
+    };
+}) => PostgresQueryable;
+export interface PostgresStorageOptions {
+    /**
+     * Pass `Pool` from `import { Pool } from "pg"` in the example that declares
+     * the `pg` dependency (hosted installs put it in that package's
+     * `node_modules` only).
+     */
+    Pool: PostgresPoolConstructor;
+    /** Postgres connection string (default: env, then local bugbot dev DB). */
+    databaseUrl?: string;
+    /** Value for the tables' deployment_id column (default: env or "local-dev"). */
+    deploymentId?: string;
+}
+type PostgresStorageMethods = Required<Pick<StorageConfig, "put" | "get" | "delete" | "list">> & {
+    evals: StorageEvalsTable;
+    abs: StorageABTable;
+};
+/** True for local bugbot/dev URLs that do not speak TLS. */
+export declare function isLocalPostgresUrl(connectionString: string): boolean;
+/** Postgres-backed `defineStorage` methods, ready to spread into `defineStorage({...})`. */
+export declare function postgresStorage(options: PostgresStorageOptions): PostgresStorageMethods;
+export {};
+//# sourceMappingURL=postgres-kv.d.ts.map

package/dist/storage-backends/postgres-kv.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"postgres-kv.d.ts","sourceRoot":"","sources":["../../src/storage-backends/postgres-kv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAEb,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAGvB,kFAAkF;AAClF,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAC1B,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,CAAC,CAAC;CAC3B;AAED,uEAAuE;AACvE,MAAM,MAAM,uBAAuB,GAAG,KAAK,MAAM,CAAC,EAAE;IAClD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,GAAG;QAAE,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAClD,KAAK,iBAAiB,CAAC;AAExB,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,IAAI,EAAE,uBAAuB,CAAC;IAC9B,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,KAAK,sBAAsB,GAAG,QAAQ,CACpC,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC,CACvD,GAAG;IACF,KAAK,EAAE,iBAAiB,CAAC;IACzB,GAAG,EAAE,cAAc,CAAC;CACrB,CAAC;AAEF,4DAA4D;AAC5D,wBAAgB,kBAAkB,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAYpE;AAED,4FAA4F;AAC5F,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,sBAAsB,CA4HxB"}

package/dist/storage-backends/postgres-kv.js ADDED Viewed

@@ -0,0 +1,180 @@
+/**
+ * Postgres `defineStorage` helper on the agent-serve tables
+ * (backend/packages/prisma-bugbot):
+ *
+ *   agent_serve_kv(deployment_id, key, value JSONB, updated_at)
+ *     PRIMARY KEY (deployment_id, key)
+ *   agent_serve_eval_runs(deployment_id, agent, run_id, run JSONB, updated_at)
+ *     PRIMARY KEY (deployment_id, agent, run_id)
+ *   agent_serve_ab(deployment_id, agent, kind, ref, value JSONB, updated_at)
+ *     PRIMARY KEY (deployment_id, agent, kind, ref)
+ *
+ * `postgresStorage` implements the whole `defineStorage` surface as plain
+ * SQL: the four KV methods against the last-write-wins `agent_serve_kv`
+ * table (sessions, event chunks, continuations, reminders), the `evals`
+ * table against `agent_serve_eval_runs` (one row per playground eval
+ * batch), and the `abs` table against `agent_serve_ab` (`kind = 'sample'`
+ * rows per metric sample plus one `kind = 'snapshot'` row holding the
+ * latest aggregate).
+ *
+ * - KV `put` upserts on the primary key (LWW matches the framework contract).
+ * - KV `list` is a prefix range scan on the PK btree (`key >= p AND key < p||…`
+ *   spelled as LIKE with escaped wildcards, ordered by key).
+ * - `get` returning no row is a definitive miss (`undefined`); a connection
+ *   error throws, so lazy restore fails the follow-up instead of forking
+ *   the session.
+ *
+ * Connection comes from `BUGBOTDB_URL` — the repo-wide convention for the
+ * bugbot Postgres database, whose Prisma package owns these tables' schema
+ * and migrations; locally it falls back to the dev bugbot DB. Non-local
+ * URLs enable TLS (`ssl.rejectUnauthorized`) because PlanetScale requires
+ * SSL even when the vault URL omits `sslmode`.
+ * `deploymentId` scopes rows per deployment (`AGENT_SERVE_DEPLOYMENT_ID`);
+ * the local default keeps dev runs of different checkouts from colliding
+ * only by agent name.
+ *
+ * Callers must pass `Pool` from their own `import { Pool } from "pg"`.
+ * This module must not import `pg` itself: Node resolves modules from
+ * *this* file's directory tree, so a `pg` dep declared only on the
+ * consuming agent package would never be found after a hosted install.
+ */
+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());
+    });
+};
+/** True for local bugbot/dev URLs that do not speak TLS. */
+export function isLocalPostgresUrl(connectionString) {
+    try {
+        const host = new URL(connectionString).hostname.toLowerCase();
+        return (host === "localhost" ||
+            host === "127.0.0.1" ||
+            host === "::1" ||
+            host === "[::1]");
+    }
+    catch (_a) {
+        return /@(localhost|127\.0\.0\.1|\[::1\])([:/]|$)/i.test(connectionString);
+    }
+}
+/** Postgres-backed `defineStorage` methods, ready to spread into `defineStorage({...})`. */
+export function postgresStorage(options) {
+    var _a, _b, _c, _d;
+    const connectionString = (_b = (_a = options.databaseUrl) !== null && _a !== void 0 ? _a : process.env.BUGBOTDB_URL) !== null && _b !== void 0 ? _b : "postgresql://prisma:prisma@localhost:5432/bugbot";
+    // Prod Bugbot is PlanetScale Postgres: TLS is required and the vault
+    // `BUGBOTDB_URL` often omits `sslmode`. Without an explicit `ssl` option,
+    // `pg` opens plaintext and PlanetScale rejects with "SSL connection is
+    // required" — sessions stay in-memory. Skip TLS only for local hosts.
+    const pool = new options.Pool(Object.assign({ connectionString,
+        // Small fixed pool per agent, mirroring the backend's connection_limit
+        // clamp on BUGBOTDB_URL consumers (backend/server/src/prisma.ts).
+        max: 3 }, (isLocalPostgresUrl(connectionString)
+        ? {}
+        : { ssl: { rejectUnauthorized: true } })));
+    const deploymentId = (_d = (_c = options.deploymentId) !== null && _c !== void 0 ? _c : process.env.AGENT_SERVE_DEPLOYMENT_ID) !== null && _d !== void 0 ? _d : "local-dev";
+    return {
+        put(key, value) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield pool.query(`INSERT INTO agent_serve_kv (deployment_id, key, value, updated_at)
+         VALUES ($1, $2, $3::jsonb, now())
+         ON CONFLICT ON CONSTRAINT pk_agent_serve_kv
+         DO UPDATE SET value = EXCLUDED.value, updated_at = now()`, [deploymentId, key, JSON.stringify(value)]);
+            });
+        },
+        get(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const result = yield pool.query(`SELECT value FROM agent_serve_kv
+         WHERE deployment_id = $1 AND key = $2`, [deploymentId, key]);
+                return (_a = result.rows[0]) === null || _a === void 0 ? void 0 : _a.value; // no row ⇒ definitive miss
+            });
+        },
+        delete(key) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield pool.query(`DELETE FROM agent_serve_kv WHERE deployment_id = $1 AND key = $2`, [deploymentId, key]);
+            });
+        },
+        list(prefix) {
+            return __awaiter(this, void 0, void 0, function* () {
+                // Escape LIKE wildcards in the prefix so keys containing % or _
+                // (URI-encoded segments cannot, but be safe) match literally.
+                const escaped = prefix.replace(/([\\%_])/g, "\\$1");
+                const result = yield pool.query(`SELECT key, value FROM agent_serve_kv
+         WHERE deployment_id = $1 AND key LIKE $2 ESCAPE '\\'
+         ORDER BY key ASC`, [deploymentId, `${escaped}%`]);
+                return result.rows;
+            });
+        },
+        // Playground eval batches → agent_serve_eval_runs (one row per run).
+        evals: {
+            put(run, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield pool.query(`INSERT INTO agent_serve_eval_runs (deployment_id, agent, run_id, run, updated_at)
+           VALUES ($1, $2, $3, $4::jsonb, now())
+           ON CONFLICT ON CONSTRAINT pk_agent_serve_eval_runs
+           DO UPDATE SET run = EXCLUDED.run, updated_at = now()`, [deploymentId, ctx.agentName, run.runId, JSON.stringify(run)]);
+                });
+            },
+            delete(runId, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield pool.query(`DELETE FROM agent_serve_eval_runs
+           WHERE deployment_id = $1 AND agent = $2 AND run_id = $3`, [deploymentId, ctx.agentName, runId]);
+                });
+            },
+            list(ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    const result = yield pool.query(`SELECT run FROM agent_serve_eval_runs
+           WHERE deployment_id = $1 AND agent = $2`, [deploymentId, ctx.agentName]);
+                    return result.rows.map((row) => row.run);
+                });
+            },
+        },
+        // A/B metrics → agent_serve_ab: sample rows plus one snapshot row.
+        abs: {
+            putSample(sample, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield upsertAbRow(pool, {
+                        deploymentId,
+                        agent: ctx.agentName,
+                        kind: "sample",
+                        // One boundary event emits a sample per enrolled experiment with
+                        // the same sessionId/at — the experiment must be in the row key
+                        // or those samples overwrite each other.
+                        ref: `${sample.experiment}/${sample.sessionId}/${sample.at}`,
+                        value: sample,
+                    });
+                });
+            },
+            putSnapshot(snapshot, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield upsertAbRow(pool, {
+                        deploymentId,
+                        agent: ctx.agentName,
+                        kind: "snapshot",
+                        ref: "",
+                        value: snapshot,
+                    });
+                });
+            },
+            getSnapshot(ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    const result = yield pool.query(`SELECT value FROM agent_serve_ab
+           WHERE deployment_id = $1 AND agent = $2 AND kind = 'snapshot' AND ref = ''`, [deploymentId, ctx.agentName]);
+                    return (_a = result.rows[0]) === null || _a === void 0 ? void 0 : _a.value;
+                });
+            },
+        },
+    };
+}
+function upsertAbRow(pool, row) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield pool.query(`INSERT INTO agent_serve_ab (deployment_id, agent, kind, ref, value, updated_at)
+     VALUES ($1, $2, $3, $4, $5::jsonb, now())
+     ON CONFLICT ON CONSTRAINT pk_agent_serve_ab
+     DO UPDATE SET value = EXCLUDED.value, updated_at = now()`, [row.deploymentId, row.agent, row.kind, row.ref, JSON.stringify(row.value)]);
+    });
+}

package/dist/storage.d.ts CHANGED Viewed

@@ -33,7 +33,9 @@
  *
  * Because keys are opaque strings to the sink, new kinds of durable state
  * (channel cursors, thread affinity, …) are new key prefixes — existing
- * sinks store them with no code changes.
+ * sinks store them with no code changes. Authors can also store their own
+ * JSON under `agentkit/v1/{agent}/kv/…` via {@link HostContext.kv}; the
+ * framework still mints the full key from the author-supplied segment.
  *
  * Delivery semantics: writes are **serialized** (one sink call in flight
  * per agent, in order), **bounded** (a sink that falls behind sheds writes
@@ -205,6 +207,7 @@ export declare const STORAGE_KEY_ROOT: "agentkit/v1";
  * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
  * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
  * | `agentkit/v1/{agent}/reminder/{reminderId}` | `ReminderRecord` |
+ * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via {@link HostContext.kv} |
  *
  * Eval-run and A/B history do not flow through this KV scheme — they have
  * dedicated tables ({@link StorageConfig.evals} / {@link StorageConfig.abs}).
@@ -217,6 +220,12 @@ export declare const storageKeys: {
     readonly continuation: (agent: string, channelId: string, continuationKey: string) => string;
     readonly reminder: (agent: string, reminderId: string) => string;
     readonly reminderPrefix: (agent: string) => string;
+    /**
+     * Author-facing opaque JSON (see {@link HostContext.kv}). `key` is
+     * URI-encoded / digested like other caller-controlled segments.
+     */
+    readonly kv: (agent: string, key: string) => string;
+    readonly kvPrefix: (agent: string) => string;
 };
 /**
  * Max bytes a caller-controlled key segment may occupy after URI-encoding.

package/dist/storage.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA~~;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG~~;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAM5C,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;CAC3C;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,oBAAoB,GAAG,KAAK,CAAC;CACxC;AAED,mFAAmF;AACnF,MAAM,WAAW,oBAAoB;IACnC,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,GAAG,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,gEAAgE;IAChE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,+EAA+E;IAC/E,IAAI,CAAC,GAAG,EAAE,cAAc,GAAG,eAAe,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CAC3E;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,4EAA4E;IAC5E,WAAW,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,6EAA6E;IAC7E,WAAW,CAAC,CACV,GAAG,EAAE,cAAc,GAClB,UAAU,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;CAC3E;AAED,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB;;;OAGG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B;;;OAGG;IACH,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,kEAAkE;IAClE,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE;;;;;;;OAOG;IACH,GAAG,CAAC,CACF,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,cAAc,GAClB,SAAS,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;IACxE;;;;OAIG;IACH,IAAI,CAAC,CACH,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,cAAc,GAClB,YAAY,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAC7C;AAED,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG;IAC9C,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;CAClC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,iBAAiB,CAuCtE;AAMD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAG,aAAsB,CAAC;AAEvD~~;;;;;;;;;;;;;;;;;;;;;GAqBG~~;AACH,eAAO,MAAM,WAAW;aACtB,OAAO,UAAU,MAAM,aAAa,MAAM,KAAG,MAAM;aAEnD,aAAa,UAAU,MAAM,KAAG,MAAM;aAEtC,aAAa,UACJ,MAAM,aACF,MAAM,cACL,MAAM,KACjB,MAAM;aAET,mBAAmB,UAAU,MAAM,aAAa,MAAM,KAAG,MAAM;aAE/D,YAAY,UACH,MAAM,aACF,MAAM,mBACA,MAAM,KACtB,MAAM;aAET,QAAQ,UAAU,MAAM,cAAc,MAAM,KAAG,MAAM;aAErD,cAAc,UAAU,MAAM,KAAG,MAAM;~~CAE/B~~,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAoBzC,eAAO,MAAM,oCAAoC,OAAQ,CAAC;AAC1D,eAAO,MAAM,kCAAkC,EAAE,MAA8B,CAAC;AAChF,eAAO,MAAM,uCAAuC,aAAgB,CAAC;AAErE,mDAAmD;AACnD,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,MAAM,EAAE,SAAS,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,OAAO,EACH,KAAK,GACL;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CACtE;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,aAAa,GAAG,SAAS,GAChC,qBAAqB,CA8BvB"}
1	+ {"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/dist/storage.js CHANGED Viewed

@@ -33,7 +33,9 @@
  *
  * Because keys are opaque strings to the sink, new kinds of durable state
  * (channel cursors, thread affinity, …) are new key prefixes — existing
- * sinks store them with no code changes.
+ * sinks store them with no code changes. Authors can also store their own
+ * JSON under `agentkit/v1/{agent}/kv/…` via {@link HostContext.kv}; the
+ * framework still mints the full key from the author-supplied segment.
  *
  * Delivery semantics: writes are **serialized** (one sink call in flight
  * per agent, in order), **bounded** (a sink that falls behind sheds writes
@@ -106,6 +108,7 @@ export const STORAGE_KEY_ROOT = "agentkit/v1";
  * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
  * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
  * | `agentkit/v1/{agent}/reminder/{reminderId}` | `ReminderRecord` |
+ * | `agentkit/v1/{agent}/kv/{key}` | Author JSON via {@link HostContext.kv} |
  *
  * Eval-run and A/B history do not flow through this KV scheme — they have
  * dedicated tables ({@link StorageConfig.evals} / {@link StorageConfig.abs}).
@@ -118,6 +121,12 @@ export const storageKeys = {
     continuation: (agent, channelId, continuationKey) => `${STORAGE_KEY_ROOT}/${agent}/continuation/${keySegment(channelId)}/${keySegment(continuationKey)}`,
     reminder: (agent, reminderId) => `${STORAGE_KEY_ROOT}/${agent}/reminder/${reminderId}`,
     reminderPrefix: (agent) => `${STORAGE_KEY_ROOT}/${agent}/reminder/`,
+    /**
+     * Author-facing opaque JSON (see {@link HostContext.kv}). `key` is
+     * URI-encoded / digested like other caller-controlled segments.
+     */
+    kv: (agent, key) => `${STORAGE_KEY_ROOT}/${agent}/kv/${keySegment(key)}`,
+    kvPrefix: (agent) => `${STORAGE_KEY_ROOT}/${agent}/kv/`,
 };
 /**
  * Max bytes a caller-controlled key segment may occupy after URI-encoding.