@cursor/july 0.1.32 → 0.1.34

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 (186) hide show
  1. package/README.md +1 -1
  2. package/dist/artifacts.d.ts.map +1 -1
  3. package/dist/artifacts.js +0 -5
  4. package/dist/bin/agent-serve.d.ts +1 -0
  5. package/dist/bin/agent-serve.d.ts.map +1 -1
  6. package/dist/bin/agent-serve.js +32 -2
  7. package/dist/channels/github/types.d.ts +10 -7
  8. package/dist/channels/github/types.d.ts.map +1 -1
  9. package/dist/docs/404.html +2 -2
  10. package/dist/docs/ab.html +3 -3
  11. package/dist/docs/assets/{app.C2aVczmo.js → app.FPupl4SP.js} +1 -1
  12. package/dist/docs/assets/chunks/@localSearchIndexroot.WoYunhnT.js +1 -0
  13. package/dist/docs/assets/chunks/{VPLocalSearchBox.DLEzetbD.js → VPLocalSearchBox.Cd182Cu0.js} +1 -1
  14. package/dist/docs/assets/chunks/{theme.BkOH1oMp.js → theme.BEM3Okcd.js} +2 -2
  15. package/dist/docs/assets/{example-agents_weather-agent.md.Dmrcphhl.js → example-agents_weather-agent.md.BADkPqxQ.js} +6 -4
  16. package/dist/docs/assets/example-agents_weather-agent.md.BADkPqxQ.lean.js +1 -0
  17. package/dist/docs/assets/guides_cloud-runtime.md.CDJGvVC4.js +9 -0
  18. package/dist/docs/assets/guides_cloud-runtime.md.CDJGvVC4.lean.js +1 -0
  19. package/dist/docs/building-with-agents.html +3 -3
  20. package/dist/docs/concepts.html +3 -3
  21. package/dist/docs/deployment.html +3 -3
  22. package/dist/docs/evals.html +3 -3
  23. package/dist/docs/example-agents/approval-buddy.html +3 -3
  24. package/dist/docs/example-agents/benny.html +3 -3
  25. package/dist/docs/example-agents/bugbot.html +3 -3
  26. package/dist/docs/example-agents/codebase-wiki.html +3 -3
  27. package/dist/docs/example-agents/codeowners-review.html +3 -3
  28. package/dist/docs/example-agents/concierge.html +3 -3
  29. package/dist/docs/example-agents/fsd.html +3 -3
  30. package/dist/docs/example-agents/index.html +3 -3
  31. package/dist/docs/example-agents/knowledge-base.html +3 -3
  32. package/dist/docs/example-agents/oncall.html +3 -3
  33. package/dist/docs/example-agents/security-reviewer.html +3 -3
  34. package/dist/docs/example-agents/slack-agent.html +3 -3
  35. package/dist/docs/example-agents/weather-agent.html +10 -8
  36. package/dist/docs/guides/agent-to-agent.html +3 -3
  37. package/dist/docs/guides/cloud-runtime.html +5 -5
  38. package/dist/docs/guides/github.html +3 -3
  39. package/dist/docs/guides/human-in-the-loop.html +3 -3
  40. package/dist/docs/guides/mcp-oauth.html +3 -3
  41. package/dist/docs/guides/slack.html +3 -3
  42. package/dist/docs/guides/webhooks.html +3 -3
  43. package/dist/docs/hashmap.json +1 -1
  44. package/dist/docs/hillclimbing.html +3 -3
  45. package/dist/docs/index.html +3 -3
  46. package/dist/docs/quickstart.html +3 -3
  47. package/dist/docs/reference/agent-config.html +3 -3
  48. package/dist/docs/reference/channels.html +3 -3
  49. package/dist/docs/reference/cli.html +3 -3
  50. package/dist/docs/reference/connections.html +3 -3
  51. package/dist/docs/reference/hooks.html +3 -3
  52. package/dist/docs/reference/http-api.html +3 -3
  53. package/dist/docs/reference/instructions.html +3 -3
  54. package/dist/docs/reference/playground.html +3 -3
  55. package/dist/docs/reference/project-layout.html +3 -3
  56. package/dist/docs/reference/prompt.html +3 -3
  57. package/dist/docs/reference/schedules.html +3 -3
  58. package/dist/docs/reference/sessions.html +3 -3
  59. package/dist/docs/reference/skills.html +3 -3
  60. package/dist/docs/reference/subagents.html +3 -3
  61. package/dist/docs/reference/tools.html +3 -3
  62. package/dist/docs/scaffolding-agents.html +3 -3
  63. package/dist/docs/storage.html +3 -3
  64. package/dist/docs/troubleshooting.html +3 -3
  65. package/dist/files-backends/agent-store-presigned-url.d.ts.map +1 -1
  66. package/dist/files-backends/agent-store-presigned-url.js +19 -810
  67. package/dist/files.d.ts +20 -0
  68. package/dist/files.d.ts.map +1 -1
  69. package/dist/files.js +20 -0
  70. package/dist/index.d.ts +2 -2
  71. package/dist/index.d.ts.map +1 -1
  72. package/dist/index.js +2 -2
  73. package/dist/internal/artifacts-store.d.ts +14 -6
  74. package/dist/internal/artifacts-store.d.ts.map +1 -1
  75. package/dist/internal/artifacts-store.js +160 -16
  76. package/dist/internal/cli-convert-automation.d.ts +39 -0
  77. package/dist/internal/cli-convert-automation.d.ts.map +1 -0
  78. package/dist/internal/cli-convert-automation.js +280 -0
  79. package/dist/internal/cli-deploy.d.ts +2 -0
  80. package/dist/internal/cli-deploy.d.ts.map +1 -1
  81. package/dist/internal/cli-deploy.js +1 -1
  82. package/dist/internal/cli-mcp-oauth.d.ts +23 -0
  83. package/dist/internal/cli-mcp-oauth.d.ts.map +1 -1
  84. package/dist/internal/cli-mcp-oauth.js +57 -33
  85. package/dist/internal/convert-automation/convert-workflow.d.ts +10 -0
  86. package/dist/internal/convert-automation/convert-workflow.d.ts.map +1 -0
  87. package/dist/internal/convert-automation/convert-workflow.js +998 -0
  88. package/dist/internal/convert-automation/index.d.ts +3 -0
  89. package/dist/internal/convert-automation/index.d.ts.map +1 -0
  90. package/dist/internal/convert-automation/index.js +1 -0
  91. package/dist/internal/convert-automation/slug.d.ts +11 -0
  92. package/dist/internal/convert-automation/slug.d.ts.map +1 -0
  93. package/dist/internal/convert-automation/slug.js +36 -0
  94. package/dist/internal/convert-automation/types.d.ts +191 -0
  95. package/dist/internal/convert-automation/types.d.ts.map +1 -0
  96. package/dist/internal/convert-automation/types.js +13 -0
  97. package/dist/internal/cursor-relay-core.d.ts +12 -0
  98. package/dist/internal/cursor-relay-core.d.ts.map +1 -1
  99. package/dist/internal/cursor-relay-core.js +42 -8
  100. package/dist/internal/deploy-client.d.ts +31 -0
  101. package/dist/internal/deploy-client.d.ts.map +1 -1
  102. package/dist/internal/deploy-client.js +48 -0
  103. package/dist/internal/discovery.d.ts.map +1 -1
  104. package/dist/internal/discovery.js +3 -32
  105. package/dist/internal/init-project.d.ts +1 -0
  106. package/dist/internal/init-project.d.ts.map +1 -1
  107. package/dist/internal/init-project.js +1 -1
  108. package/dist/internal/mcp-endpoint.d.ts +6 -0
  109. package/dist/internal/mcp-endpoint.d.ts.map +1 -1
  110. package/dist/internal/mcp-endpoint.js +168 -0
  111. package/dist/internal/resolved-connections.d.ts +15 -0
  112. package/dist/internal/resolved-connections.d.ts.map +1 -1
  113. package/dist/internal/resolved-connections.js +12 -5
  114. package/dist/internal/review-comments.d.ts +9 -1
  115. package/dist/internal/review-comments.d.ts.map +1 -1
  116. package/dist/internal/review-comments.js +76 -0
  117. package/dist/internal/server.d.ts.map +1 -1
  118. package/dist/internal/server.js +83 -8
  119. package/dist/internal/session-engine.d.ts +56 -3
  120. package/dist/internal/session-engine.d.ts.map +1 -1
  121. package/dist/internal/session-engine.js +252 -83
  122. package/dist/internal/storage-coordinator.d.ts +0 -15
  123. package/dist/internal/storage-coordinator.d.ts.map +1 -1
  124. package/dist/internal/storage-coordinator.js +0 -52
  125. package/dist/internal/workspace.d.ts +10 -5
  126. package/dist/internal/workspace.d.ts.map +1 -1
  127. package/dist/internal/workspace.js +13 -0
  128. package/dist/memory.d.ts +22 -6
  129. package/dist/memory.d.ts.map +1 -1
  130. package/dist/memory.js +100 -8
  131. package/dist/playground/assets/index-CDDWw0YX.js +85 -0
  132. package/dist/playground/assets/index-MVuNTd8v.css +1 -0
  133. package/dist/playground/index.html +2 -2
  134. package/dist/storage.d.ts +0 -4
  135. package/dist/storage.d.ts.map +1 -1
  136. package/dist/storage.js +0 -4
  137. package/dist/types.d.ts +18 -0
  138. package/dist/types.d.ts.map +1 -1
  139. package/docs/example-agents/weather-agent.md +29 -11
  140. package/docs/guides/cloud-runtime.md +6 -4
  141. package/package.json +3 -22
  142. package/src/artifacts.ts +0 -6
  143. package/src/bin/agent-serve.ts +36 -2
  144. package/src/channels/github/types.ts +10 -7
  145. package/src/files-backends/agent-store-presigned-url.ts +7 -5
  146. package/src/files.ts +27 -0
  147. package/src/index.ts +6 -1
  148. package/src/internal/artifacts-store.ts +185 -22
  149. package/src/internal/cli-convert-automation.ts +352 -0
  150. package/src/internal/cli-deploy.ts +1 -1
  151. package/src/internal/cli-mcp-oauth.ts +69 -31
  152. package/src/internal/convert-automation/convert-workflow.ts +1422 -0
  153. package/src/internal/convert-automation/index.ts +10 -0
  154. package/src/internal/convert-automation/slug.ts +38 -0
  155. package/src/internal/convert-automation/types.ts +199 -0
  156. package/src/internal/cursor-relay-core.ts +62 -3
  157. package/src/internal/deploy-client.ts +78 -0
  158. package/src/internal/discovery.ts +3 -37
  159. package/src/internal/init-project.ts +1 -1
  160. package/src/internal/mcp-endpoint.ts +243 -0
  161. package/src/internal/resolved-connections.ts +32 -6
  162. package/src/internal/review-comments.ts +102 -2
  163. package/src/internal/server.ts +108 -2
  164. package/src/internal/session-engine.ts +329 -99
  165. package/src/internal/storage-coordinator.ts +0 -62
  166. package/src/internal/workspace.ts +19 -5
  167. package/src/memory.ts +126 -10
  168. package/src/storage.ts +0 -6
  169. package/src/types.ts +15 -0
  170. package/dist/channels/slack/post-update-delivery.d.ts +0 -85
  171. package/dist/channels/slack/post-update-delivery.d.ts.map +0 -1
  172. package/dist/docs/assets/chunks/@localSearchIndexroot.xgMnlUSO.js +0 -1
  173. package/dist/docs/assets/example-agents_weather-agent.md.Dmrcphhl.lean.js +0 -1
  174. package/dist/docs/assets/guides_cloud-runtime.md.BZ2GA7Es.js +0 -9
  175. package/dist/docs/assets/guides_cloud-runtime.md.BZ2GA7Es.lean.js +0 -1
  176. package/dist/internal/json-dir-store.d.ts +0 -32
  177. package/dist/internal/json-dir-store.d.ts.map +0 -1
  178. package/dist/internal/persistence-coordinator.d.ts +0 -127
  179. package/dist/internal/persistence-coordinator.d.ts.map +0 -1
  180. package/dist/multi-tenant.d.ts +0 -80
  181. package/dist/multi-tenant.d.ts.map +0 -1
  182. package/dist/multi-tenant.js +0 -69
  183. package/dist/persistence.d.ts +0 -184
  184. package/dist/persistence.d.ts.map +0 -1
  185. package/dist/playground/assets/index-50PKeJlG.css +0 -1
  186. package/dist/playground/assets/index-C0f2Wl1q.js +0 -85
@@ -1 +0,0 @@
1
- import{_ as s,c as a,o as t,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace tools, MCP, channels, approvals, skills, subagents, schedules, hooks, A/B metrics, and evals through one local agent.","frontmatter":{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace tools, MCP, channels, approvals, skills, subagents, schedules, hooks, A/B metrics, and evals through one local agent."},"headers":[],"relativePath":"example-agents/weather-agent.md","filePath":"example-agents/weather-agent.md"}'),n={name:"example-agents/weather-agent.md"};function h(o,e,l,r,p,d){return t(),a("div",null,[...e[0]||(e[0]=[i("",79)])])}const u=s(n,[["render",h]]);export{k as __pageData,u as default};
@@ -1,9 +0,0 @@
1
- import{_ as t,c as s,o as a,ag as o}from"./chunks/framework.CAZyNGu9.js";const p=JSON.parse('{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up.","frontmatter":{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up."},"headers":[],"relativePath":"guides/cloud-runtime.md","filePath":"guides/cloud-runtime.md"}'),n={name:"guides/cloud-runtime.md"};function i(r,e,d,l,c,h){return a(),s("div",null,[...e[0]||(e[0]=[o(`<h1 id="cloud-runtime" tabindex="-1">Cloud runtime <a class="header-anchor" href="#cloud-runtime" aria-label="Permalink to &quot;Cloud runtime&quot;">​</a></h1><p>By default, turns execute on the Cursor SDK&#39;s local harness, on the same machine as the server. Set <code>runtime: &quot;cloud&quot;</code> and turns execute on Cursor cloud agents instead. They&#39;re ephemeral VMs that carry a repo checkout, run <code>gh</code>, <code>git</code>, and tests for real, and scale past what one host&#39;s disk and CPU can do. The serve host keeps handling routing, host preparation, sessions, and bookkeeping.</p><p>A canonical use is a PR driver whose triage runs on cloud VMs. The patterns in this guide come from running one against real PR traffic.</p><h2 id="when-to-switch" tabindex="-1">When to switch <a class="header-anchor" href="#when-to-switch" aria-label="Permalink to &quot;When to switch&quot;">​</a></h2><p>A guideline from running PR agents at scale: per-PR worktrees on the serve host don&#39;t scale to hundreds of engineers opening PRs. When the job needs a repo checkout at scale, use cloud. The signals:</p><ul><li>The agent must run repo commands (tests, builds, <code>git</code>) against many different refs concurrently.</li><li>Turns are long and heavy, and you don&#39;t want them competing with the server for resources.</li><li>The work product is a PR or branch the VM can push, not a local file.</li></ul><p>Stay local when the agent is conversational, tool-driven against APIs, or works over host-prepared evidence. Local turns are cheaper, start faster, and support the full authored surface.</p><h2 id="configure-it" tabindex="-1">Configure it <a class="header-anchor" href="#configure-it" aria-label="Permalink to &quot;Configure it&quot;">​</a></h2><p>Cloud runtime is two fields on the agent config.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
2
- <span class="line"></span>
3
- <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
4
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> runtime: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cloud&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
5
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cloud: {</span></span>
6
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> repos: [{ url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://github.com/org/repo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, startingRef: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;main&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }],</span></span>
7
- <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // env / envVars / … forwarded to the Cursor SDK</span></span>
8
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
9
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The host must be signed in (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>).</p><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Cloud agents run against the Cursor backend under the signed-in account, and every wake spends real cloud-agent budget. Decide explicitly what may trigger one.</p></div><h2 id="what-changes-on-cloud" tabindex="-1">What changes on cloud <a class="header-anchor" href="#what-changes-on-cloud" aria-label="Permalink to &quot;What changes on cloud&quot;">​</a></h2><p>Cloud turns run on a VM without your authored files, so the runtime mapping shifts:</p><table tabindex="0"><thead><tr><th>Folder or file</th><th>Local runtime</th><th>Cloud runtime</th></tr></thead><tbody><tr><td><code>instructions.*</code></td><td><code>AGENTS.md</code> in the session workspace</td><td>prepended to the first prompt</td></tr><tr><td>Server tools (<code>execution: &quot;server&quot;</code>)</td><td>in-process SDK custom tools</td><td>not available</td></tr><tr><td>Agent tools (<code>execution: &quot;agent&quot;</code>)</td><td>scripts in the session workspace</td><td>catalog + script bodies on the first prompt</td></tr><tr><td><code>skills/*</code></td><td><code>.cursor/skills/</code> in the workspace</td><td>only if present in the cloud repo</td></tr><tr><td><code>mcp-connections/*.ts</code></td><td>SDK <code>mcpServers</code></td><td>SDK <code>mcpServers</code> (peers need <code>--public-url</code>)</td></tr><tr><td><code>sandbox/workspace/**</code></td><td>seeded into the session workspace</td><td>ignored</td></tr><tr><td>Tool approvals (<code>needsApproval</code>)</td><td>supported</td><td>not supported</td></tr></tbody></table><p><code>agent-sdk validate</code> warns when <code>runtime: &quot;cloud&quot;</code> is combined with local-only capabilities. Those warnings match this table.</p><p>Two more behaviors are cloud-specific. Sessions persist a separate SDK agent id (<code>bc-…</code>), emitted on the stream as <code>agent.bound</code> with a URL to the cloud conversation. Cloud ids are minted during the first send. And peer MCP connections resolve to <code>--public-url</code> for cloud turns, because a VM cannot reach the host&#39;s loopback; without one, peers are omitted from cloud turns and the server warns at startup.</p><h2 id="hybrid-local-agent-cloud-sessions" tabindex="-1">Hybrid: local agent, cloud sessions <a class="header-anchor" href="#hybrid-local-agent-cloud-sessions" aria-label="Permalink to &quot;Hybrid: local agent, cloud sessions&quot;">​</a></h2><p>A local-runtime agent can still open cloud-attached sessions per send. Channel handlers may pass a <code>cloud</code> block (repos pinned to a PR ref, say) in <code>send</code> options, and Slack handlers may return <code>cloud</code> from a mention hook. A PR driver works this way: chat stays local, and the <code>drive</code> flow attaches the PR to a cloud VM. The agent-level <code>cloud</code> config is the base that per-session options merge over.</p><h2 id="patterns-that-hold-up" tabindex="-1">Patterns that hold up <a class="header-anchor" href="#patterns-that-hold-up" aria-label="Permalink to &quot;Patterns that hold up&quot;">​</a></h2><p>These come from running a PR driver against real PR traffic:</p><ul><li>One cloud agent per unit of work (per PR, say). Store the <code>bc-…</code> id keyed by the work unit (an affinity store written from an <code>agent.bound</code> hook) so webhook wakes resume the same conversation instead of booting a fresh VM per event.</li><li>Stable continuation keys (<code>pr:owner/repo#N</code>) so every wake lands on the same session within a channel.</li><li>Keep the host deterministic: fetch briefs and metadata on the host, send the VM a compact prompt, and let the VM re-read source of truth with its own <code>gh</code> and <code>git</code> instead of trusting payload snapshots.</li><li>Limit exposure: add repository allowlists on webhook channels, because every wake spends the account&#39;s budget.</li></ul><h2 id="verify-cloud-agents" tabindex="-1">Verify cloud agents <a class="header-anchor" href="#verify-cloud-agents" aria-label="Permalink to &quot;Verify cloud agents&quot;">​</a></h2><p><code>agent-sdk run</code> and <code>eval</code> work unchanged. The trajectory records the same event vocabulary plus <code>agent.bound</code> with the cloud URL, so you can open the cloud conversation for any session. Cloud turns take minutes. Pass generous <code>--timeout-ms</code> values, and keep curl timeouts long when driving channels directly.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./../reference/agent-config.html">Agent config</a>: the <code>runtime</code> and <code>cloud</code> fields precisely</li><li><a href="./github.html">GitHub guide</a>: the webhook patterns that pair with cloud triage</li></ul>`,27)])])}const g=t(n,[["render",i]]);export{p as __pageData,g as default};
@@ -1 +0,0 @@
1
- import{_ as t,c as s,o as a,ag as o}from"./chunks/framework.CAZyNGu9.js";const p=JSON.parse('{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up.","frontmatter":{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up."},"headers":[],"relativePath":"guides/cloud-runtime.md","filePath":"guides/cloud-runtime.md"}'),n={name:"guides/cloud-runtime.md"};function i(r,e,d,l,c,h){return a(),s("div",null,[...e[0]||(e[0]=[o("",27)])])}const g=t(n,[["render",i]]);export{p as __pageData,g as default};
@@ -1,32 +0,0 @@
1
- /**
2
- * Small filesystem helpers for one-JSON-file-per-id persistence under a
3
- * project-relative directory (eval run snapshots, A/B aggregate snapshots).
4
- */
5
- export declare function assertNonEmptyDir(dir: string, fnName: string): string;
6
- /** Resolve `dir` against `projectRoot` when relative. */
7
- export declare function resolveProjectRelativeDir(args: {
8
- dir: string;
9
- projectRoot: string;
10
- }): string;
11
- /** List `*.json` basenames in `root` (any order). Missing dir → []. */
12
- export declare function listJsonBasenames(root: string): Promise<string[]>;
13
- /**
14
- * Read and JSON.parse every `*.json` file under `root`. Missing dir → [].
15
- * Unreadable or corrupt files are skipped so one bad snapshot cannot wipe
16
- * the rest of the history.
17
- */
18
- export declare function readJsonDir<T>(root: string, options?: {
19
- sortBasenames?: "asc" | "desc";
20
- }): Promise<T[]>;
21
- /** Atomically write JSON under `root`/`fileName` (temp file + rename). */
22
- export declare function writeJsonFile(args: {
23
- root: string;
24
- fileName: string;
25
- value: unknown;
26
- }): Promise<void>;
27
- /** Best-effort delete; ignores missing files. */
28
- export declare function deleteFileInDir(args: {
29
- root: string;
30
- fileName: string;
31
- }): Promise<void>;
32
- //# sourceMappingURL=json-dir-store.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"json-dir-store.d.ts","sourceRoot":"","sources":["../../src/internal/json-dir-store.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED,yDAAyD;AACzD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,CAET;AAWD,uEAAuE;AACvE,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAWvE;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;CAAE,GAC3C,OAAO,CAAC,CAAC,EAAE,CAAC,CAiBd;AAED,0EAA0E;AAC1E,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB;AAED,iDAAiD;AACjD,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhB"}
@@ -1,127 +0,0 @@
1
- /**
2
- * Runtime for `definePersistence` (`agent/persistence.ts`).
3
- *
4
- * The coordinator is the single funnel between the engine's hot paths and
5
- * the author's key-value sink. The sink is four functions (`put` / `get` /
6
- * `delete` / `list`); the coordinator owns everything else: it mints every
7
- * key from the versioned scheme ({@link persistenceKeys}), coalesces
8
- * session records and batches event chunks per turn (or debounce window),
9
- * serializes delivery on one bounded queue per agent, and isolates
10
- * failures — a throwing sink is logged and its write dropped; persistence
11
- * must never stall or fail a turn.
12
- *
13
- * Scaling shape: sessions, evals, and A/Bs all reduce to keyed puts on the
14
- * same queue, so one author-owned sink covers every domain, and new
15
- * domains are new key prefixes — not new config surface.
16
- */
17
- import type { ABSamplePersistence } from "../ab.js";
18
- import type { EvalRunPersistence } from "../evals.js";
19
- import { type PersistenceContext, type PersistenceDefinition, type ResolvedPersistencePolicy } from "../persistence.js";
20
- import type { SessionEvent, SessionRecord } from "../types.js";
21
- import type { ABSnapshot } from "./ab-snapshot.js";
22
- export interface PersistenceCoordinatorOptions {
23
- definition: PersistenceDefinition;
24
- agentName: string;
25
- projectRoot: string;
26
- logger: (line: string) => void;
27
- }
28
- export declare class PersistenceCoordinator {
29
- readonly policy: ResolvedPersistencePolicy;
30
- private readonly definition;
31
- private readonly agentName;
32
- private readonly projectRoot;
33
- private readonly logger;
34
- /** Per-session pending state (events + coalesced record). */
35
- private readonly buffers;
36
- /**
37
- * Last continuation key written to the sink per session, so a token
38
- * change emits a delete for the stale index entry alongside the new put.
39
- */
40
- private readonly continuationIndex;
41
- /** Single delivery chain: writes reach the sink serialized, in order. */
42
- private queue;
43
- /** Ops on the queue not yet delivered (bounded by MAX_PENDING_OPS). */
44
- private pending;
45
- /** Ops dropped because the queue was full. */
46
- private dropped;
47
- private lastAbSnapshotAt;
48
- private closed;
49
- constructor(options: PersistenceCoordinatorOptions);
50
- /** Durable session-record update (engine calls after every store save). */
51
- sessionRecord(record: SessionRecord): void;
52
- /** One appended session event (engine calls from its dispatch funnel). */
53
- event(event: SessionEvent): void;
54
- /**
55
- * A boundary event's dispatch settled: channel/hook handlers ran and
56
- * their record updates (channel state, continuation tokens) are
57
- * buffered. This — not the append — is the turn-end flush point, so the
58
- * persisted session record includes the boundary event's own handler
59
- * mutations. Debounced batching intentionally ignores boundaries.
60
- */
61
- eventDispatched(event: SessionEvent): void;
62
- /** Flush everything buffered for one session (ordered: events, record). */
63
- flushSession(sessionId: string, reason?: PersistenceContext["reason"]): void;
64
- /**
65
- * Index maintenance for `continuation/{channelId}/{token}` → sessionId:
66
- * put the current token, delete the previous one when it changed.
67
- */
68
- private continuationOps;
69
- /** Whether the sink can serve the startup bulk restore (`list`). */
70
- get canBulkRestore(): boolean;
71
- /**
72
- * Saved session records for this agent (startup restore). Errors are
73
- * logged and read as "nothing saved" — a broken store must never block
74
- * serve start.
75
- */
76
- listSessions(): Promise<SessionRecord[]>;
77
- /**
78
- * Saved event stream for one session: chunk values concatenated in key
79
- * order (chunks are keyed by their first event's index, zero-padded, so
80
- * ascending key order is append order). Errors read as an empty stream.
81
- */
82
- listSessionEvents(sessionId: string): Promise<SessionEvent[]>;
83
- /**
84
- * One saved session by channel continuation key (lazy restore). Unlike
85
- * the startup reads, sink errors **propagate**: a failing store must
86
- * fail the follow-up (which the caller can retry) rather than read as
87
- * "unknown token" — that would mint a new session under the same
88
- * continuation key and permanently shadow the real one on this host.
89
- * A definitive miss (no index entry, or a write-only sink without
90
- * `get`) resolves undefined.
91
- */
92
- getSessionByContinuation(channelId: string, continuationKey: string): Promise<SessionRecord | undefined>;
93
- /**
94
- * Adapter for {@link EvalRunPersistence} so the playground eval store
95
- * can fall back to this sink when `evals.config.ts` sets no
96
- * `persistRuns`.
97
- */
98
- asEvalRunPersistence(): EvalRunPersistence;
99
- /**
100
- * Adapter for {@link ABSamplePersistence} so the AB collector can fall
101
- * back to this sink when `ab.config.ts` sets no `persistSamples`.
102
- */
103
- asABSamplePersistence(): ABSamplePersistence;
104
- /**
105
- * Refresh the persisted aggregate A/B snapshot, throttled to once per
106
- * {@link AB_SNAPSHOT_MIN_INTERVAL_MS} (the playground recomputes the
107
- * fold on every `GET /v1/abs` poll).
108
- */
109
- abSnapshot(snapshot: ABSnapshot): void;
110
- /** Latest persisted aggregate A/B snapshot; errors read as absent. */
111
- getLatestAbSnapshot(): Promise<ABSnapshot | undefined>;
112
- /**
113
- * Flush all buffers and drain the queue, giving the sink at most
114
- * {@link CLOSE_DRAIN_TIMEOUT_MS} — a hung sink must not stall shutdown
115
- * past the pod grace period. Called from engine close.
116
- */
117
- close(): Promise<void>;
118
- /** Pending deliveries (exposed for tests and drain instrumentation). */
119
- whenIdle(): Promise<void>;
120
- private buffer;
121
- private armDebounce;
122
- /** `list` wrapper for the startup reads: missing hook or throw ⇒ empty. */
123
- private tryList;
124
- private enqueue;
125
- private context;
126
- }
127
- //# sourceMappingURL=persistence-coordinator.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"persistence-coordinator.d.ts","sourceRoot":"","sources":["../../src/internal/persistence-coordinator.ts"],"names":[],"mappings":"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"}
@@ -1,80 +0,0 @@
1
- /**
2
- * Multi-customer managed-agent bindings for agentkit.
3
- *
4
- * Control plane checks the Statsig gate {@link MULTI_TENANT_ENABLED_GATE}
5
- * before attaching bindings to a wake. Engines never call Statsig; they
6
- * only react when a {@link TenantWakeContext} / binding list is present.
7
- * Gate off ⇒ callers pass `multiTenant: false` and keep legacy allowlists.
8
- */
9
- /** Statsig gate id — must match `FLAGS.multi_tenant_enabled`. */
10
- export declare const MULTI_TENANT_ENABLED_GATE: "multi_tenant_enabled";
11
- /**
12
- * Per-customer binding for a catalog (managed) agentkit agent.
13
- * Prompts / tools / MCP are overlays on the fixed agent image.
14
- */
15
- export interface ManagedAgentBinding {
16
- bindingId: string;
17
- /** Catalog agent id (e.g. `security-reviewer`). */
18
- agentId: string;
19
- teamId: number;
20
- /** `owner/name` repos this customer enabled. */
21
- repos: readonly string[];
22
- prompts?: {
23
- /** Appended to base system instructions; does not replace them. */
24
- overlay?: string;
25
- /** Injected as the wake / task brief. */
26
- task?: string;
27
- };
28
- tools?: {
29
- /** When set, only these tool names are admitted for the wake. */
30
- enable?: readonly string[];
31
- };
32
- mcp?: readonly {
33
- id: string;
34
- url: string;
35
- secretRef?: string;
36
- }[];
37
- policy?: {
38
- model?: string;
39
- effort?: string;
40
- [key: string]: unknown;
41
- };
42
- }
43
- /** Request-scoped tenant bag attached to a managed-agent wake. */
44
- export interface TenantWakeContext {
45
- binding: ManagedAgentBinding;
46
- }
47
- export declare function normalizeRepoFullName(repo: string): string;
48
- export declare function bindingAllowsRepo(binding: ManagedAgentBinding, repoFullName: string): boolean;
49
- export declare function findBindingForRepo(bindings: readonly ManagedAgentBinding[], agentId: string, repoFullName: string): ManagedAgentBinding | undefined;
50
- export type RepositoryAdmission = {
51
- admitted: true;
52
- binding?: ManagedAgentBinding;
53
- } | {
54
- admitted: false;
55
- };
56
- /**
57
- * Admit a repository for a managed agent.
58
- * - `multiTenant: true` → matching binding required (fail closed).
59
- * - `multiTenant: false` → legacy static allowlist only.
60
- */
61
- export declare function admitRepository(args: {
62
- multiTenant: boolean;
63
- agentId: string;
64
- repoFullName: string;
65
- bindings: readonly ManagedAgentBinding[];
66
- legacyAllowlist: readonly string[];
67
- }): RepositoryAdmission;
68
- /** Tools with no `enable` list stay admitted (compat with unconfigured bindings). */
69
- export declare function isToolAdmitted(binding: ManagedAgentBinding | undefined, toolName: string): boolean;
70
- /**
71
- * Author-KV key scoped to a customer team under the existing `kv/` scheme:
72
- * `agentkit/v1/{agent}/kv/t/{teamId}/{key}`.
73
- */
74
- export declare function tenantKvKey(agent: string, teamId: number, key: string): string;
75
- /**
76
- * Prefix for listing author-KV keys for one customer team.
77
- * Matches the URI-encoded form produced by {@link tenantKvKey}.
78
- */
79
- export declare function tenantKvPrefix(agent: string, teamId: number): string;
80
- //# sourceMappingURL=multi-tenant.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"multi-tenant.d.ts","sourceRoot":"","sources":["../src/multi-tenant.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,iEAAiE;AACjE,eAAO,MAAM,yBAAyB,EAAG,sBAA+B,CAAC;AAEzE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,OAAO,CAAC,EAAE;QACR,mEAAmE;QACnE,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,yCAAyC;QACzC,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,KAAK,CAAC,EAAE;QACN,iEAAiE;QACjE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAC5B,CAAC;IACF,GAAG,CAAC,EAAE,SAAS;QACb,EAAE,EAAE,MAAM,CAAC;QACX,GAAG,EAAE,MAAM,CAAC;QACZ,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,EAAE,CAAC;IACJ,MAAM,CAAC,EAAE;QACP,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAED,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,mBAAmB,EAC5B,YAAY,EAAE,MAAM,GACnB,OAAO,CAGT;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,EACxC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GACnB,mBAAmB,GAAG,SAAS,CAIjC;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,mBAAmB,CAAA;CAAE,GACjD;IAAE,QAAQ,EAAE,KAAK,CAAA;CAAE,CAAC;AAExB;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACzC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GAAG,mBAAmB,CAiBtB;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAC5B,OAAO,EAAE,mBAAmB,GAAG,SAAS,EACxC,QAAQ,EAAE,MAAM,GACf,OAAO,CAMT;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACV,MAAM,CAKR;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKpE"}
@@ -1,69 +0,0 @@
1
- /**
2
- * Multi-customer managed-agent bindings for agentkit.
3
- *
4
- * Control plane checks the Statsig gate {@link MULTI_TENANT_ENABLED_GATE}
5
- * before attaching bindings to a wake. Engines never call Statsig; they
6
- * only react when a {@link TenantWakeContext} / binding list is present.
7
- * Gate off ⇒ callers pass `multiTenant: false` and keep legacy allowlists.
8
- */
9
- import { STORAGE_KEY_ROOT, storageKeys } from "./storage.js";
10
- /** Statsig gate id — must match `FLAGS.multi_tenant_enabled`. */
11
- export const MULTI_TENANT_ENABLED_GATE = "multi_tenant_enabled";
12
- export function normalizeRepoFullName(repo) {
13
- return repo.trim().toLowerCase();
14
- }
15
- export function bindingAllowsRepo(binding, repoFullName) {
16
- const needle = normalizeRepoFullName(repoFullName);
17
- return binding.repos.some((r) => normalizeRepoFullName(r) === needle);
18
- }
19
- export function findBindingForRepo(bindings, agentId, repoFullName) {
20
- return bindings.find((b) => b.agentId === agentId && bindingAllowsRepo(b, repoFullName));
21
- }
22
- /**
23
- * Admit a repository for a managed agent.
24
- * - `multiTenant: true` → matching binding required (fail closed).
25
- * - `multiTenant: false` → legacy static allowlist only.
26
- */
27
- export function admitRepository(args) {
28
- if (args.multiTenant) {
29
- const binding = findBindingForRepo(args.bindings, args.agentId, args.repoFullName);
30
- if (binding === undefined) {
31
- return { admitted: false };
32
- }
33
- return { admitted: true, binding };
34
- }
35
- const needle = normalizeRepoFullName(args.repoFullName);
36
- if (!args.legacyAllowlist.some((r) => normalizeRepoFullName(r) === needle)) {
37
- return { admitted: false };
38
- }
39
- return { admitted: true };
40
- }
41
- /** Tools with no `enable` list stay admitted (compat with unconfigured bindings). */
42
- export function isToolAdmitted(binding, toolName) {
43
- var _a;
44
- const enable = (_a = binding === null || binding === void 0 ? void 0 : binding.tools) === null || _a === void 0 ? void 0 : _a.enable;
45
- if (enable === undefined) {
46
- return true;
47
- }
48
- return enable.includes(toolName);
49
- }
50
- /**
51
- * Author-KV key scoped to a customer team under the existing `kv/` scheme:
52
- * `agentkit/v1/{agent}/kv/t/{teamId}/{key}`.
53
- */
54
- export function tenantKvKey(agent, teamId, key) {
55
- if (!Number.isInteger(teamId) || teamId < 0) {
56
- throw new Error(`invalid teamId for tenant storage: ${String(teamId)}`);
57
- }
58
- return storageKeys.kv(agent, `t/${teamId}/${key}`);
59
- }
60
- /**
61
- * Prefix for listing author-KV keys for one customer team.
62
- * Matches the URI-encoded form produced by {@link tenantKvKey}.
63
- */
64
- export function tenantKvPrefix(agent, teamId) {
65
- if (!Number.isInteger(teamId) || teamId < 0) {
66
- throw new Error(`invalid teamId for tenant storage: ${String(teamId)}`);
67
- }
68
- return `${STORAGE_KEY_ROOT}/${agent}/kv/${encodeURIComponent(`t/${teamId}/`)}`;
69
- }
@@ -1,184 +0,0 @@
1
- /**
2
- * Durable persistence plug-in for agent-serve.
3
- *
4
- * Author `agent/persistence.ts` with {@link definePersistence} to mirror the
5
- * framework's durable state into storage you own (a database, S3, a data
6
- * pipeline, …). Without it, state lives under `--state-root` on local disk
7
- * only (and eval/A/B history follows the narrower `persistRuns` /
8
- * `persistSamples` / `persistSnapshots` hooks).
9
- *
10
- * The sink is a plain key-value store — four functions, no schema:
11
- *
12
- * ```ts
13
- * import { definePersistence } from "@anysphere/agent-serve/persistence";
14
- *
15
- * export default definePersistence({
16
- * put: (key, value) => db.upsert(key, value),
17
- * get: (key) => db.get(key),
18
- * delete: (key) => db.delete(key),
19
- * list: (prefix) => db.listByPrefix(prefix), // [{ key, value }] in key order
20
- * });
21
- * ```
22
- *
23
- * The **framework mints every key** from a stable, versioned scheme (see
24
- * {@link persistenceKeys}) and decides **when** to call the sink: session
25
- * records and event chunks flush when a turn's handlers have settled,
26
- * reads happen at serve start (bulk restore), on continuation-token misses
27
- * (lazy restore), and at playground hydration. Authors do not schedule
28
- * reads or writes — the only timing knobs are {@link PersistencePolicy}'s
29
- * `debounceMs` (event write batching) and `restore` (startup hydration).
30
- *
31
- * Because keys are opaque strings to the sink, new kinds of durable state
32
- * (reminders, channel cursors, thread affinity, …) are new key prefixes —
33
- * existing sinks store them with no code changes.
34
- *
35
- * Delivery semantics: writes are **serialized** (one sink call in flight
36
- * per agent, in order), **bounded** (a sink that falls behind sheds writes
37
- * rather than growing memory), and **at-most-once** — a throwing `put` is
38
- * logged and dropped, never retried, and never fails a turn. The local
39
- * event log under `--state-root` remains the live source of truth; this
40
- * interface is the durable mirror.
41
- */
42
- import type { JsonValue } from "./types.js";
43
- /** One `{ key, value }` pair returned by {@link PersistenceConfig.list}. */
44
- export interface PersistenceEntry {
45
- key: string;
46
- value: JsonValue;
47
- }
48
- /** Context passed to every sink call. */
49
- export interface PersistenceContext {
50
- /** Agent name (also baked into every key; see {@link persistenceKeys}). */
51
- agentName: string;
52
- /** Absolute agent project root (directory that contains `agent/`). */
53
- projectRoot: string;
54
- /**
55
- * Why the framework is calling:
56
- * - `"policy"` — a flush trigger fired (turn end, debounce, change)
57
- * - `"shutdown"` — the serve process is draining; last chance to write
58
- * - `"restore"` — serve start or a lazy restore; reads rebuilding state
59
- */
60
- reason: "policy" | "shutdown" | "restore";
61
- }
62
- export interface PersistencePolicy {
63
- /**
64
- * Batch event-chunk writes on a quiet-period timer instead of flushing
65
- * once per turn. The debounce **spans turn boundaries** — a rapid
66
- * multi-turn exchange becomes one write when the session goes quiet —
67
- * so it is the right choice for chatty sessions where per-turn writes
68
- * are too many. Unset (default): one event chunk per turn.
69
- */
70
- debounceMs?: number;
71
- /**
72
- * Guardrails for the **startup bulk restore**. Whatever `list` returns
73
- * is filtered to these caps before anything is written to local disk, so
74
- * a large store cannot blow up `--state-root` or stall serve start.
75
- * Newest sessions (by `updatedAt`) win within each cap.
76
- *
77
- * `"off"` disables the startup restore entirely — sessions then restore
78
- * one at a time as follow-ups actually arrive (lazy-only; recommended
79
- * for high-traffic deployments).
80
- */
81
- restore?: PersistenceRestorePolicy | "off";
82
- }
83
- /** Caps applied to the startup bulk restore. See {@link PersistencePolicy.restore}. */
84
- export interface PersistenceRestorePolicy {
85
- /** Max sessions materialized (default {@link PERSISTENCE_DEFAULT_RESTORE_MAX_SESSIONS}). */
86
- maxSessions?: number;
87
- /**
88
- * Skip sessions whose `updatedAt` is older than this (default
89
- * {@link PERSISTENCE_DEFAULT_RESTORE_MAX_AGE_MS}). Older sessions remain
90
- * reachable lazily on their next follow-up.
91
- */
92
- maxAgeMs?: number;
93
- /**
94
- * Stop restoring once this many bytes of records + events have been
95
- * written (default {@link PERSISTENCE_DEFAULT_RESTORE_MAX_TOTAL_BYTES}).
96
- * Checked before each session is written, so one oversized stream
97
- * cannot blow past the budget.
98
- */
99
- maxTotalBytes?: number;
100
- }
101
- export interface PersistenceConfig {
102
- /** Optional label surfaced on `GET /v1/info` diagnostics. */
103
- name?: string;
104
- /** Timing knobs; see {@link PersistencePolicy}. */
105
- policy?: PersistencePolicy;
106
- /**
107
- * Store one value under a key (upsert, last-write-wins). Called on the
108
- * framework's schedule — never concurrently, always in order. Keep it
109
- * fast or buffer internally: the delivery queue is bounded, so a sink
110
- * that falls behind sustained traffic sheds writes (logged) instead of
111
- * growing memory; it never stalls the agent loop.
112
- */
113
- put(key: string, value: JsonValue, ctx: PersistenceContext): void | Promise<void>;
114
- /** Remove a key. Optional — without it, deletions are skipped. */
115
- delete?(key: string, ctx: PersistenceContext): void | Promise<void>;
116
- /**
117
- * Point lookup. Optional — required for **lazy restore** (resolving a
118
- * continuation token on a replacement host) and the A/B backfill.
119
- * Return `undefined`/`null` only for a **definitive** miss: on the lazy
120
- * restore path a throw propagates and fails the follow-up (retryable) —
121
- * a store outage must not read as "unknown token", which would fork the
122
- * conversation onto a new session.
123
- */
124
- get?(key: string, ctx: PersistenceContext): JsonValue | undefined | null | Promise<JsonValue | undefined | null>;
125
- /**
126
- * All entries under a key prefix, in ascending key order. Optional —
127
- * required for the **startup bulk restore** (sessions + event streams)
128
- * and playground eval history.
129
- */
130
- list?(prefix: string, ctx: PersistenceContext): PersistenceEntry[] | Promise<PersistenceEntry[]>;
131
- }
132
- export type PersistenceDefinition = PersistenceConfig & {
133
- readonly __agentServe: "persistence";
134
- };
135
- /**
136
- * Author the project persistence sink (`agent/persistence.ts`, default
137
- * export). See the module doc for semantics and an example.
138
- */
139
- export declare function definePersistence(config: PersistenceConfig): PersistenceDefinition;
140
- /**
141
- * The framework-owned key scheme. Keys are a **stable, versioned contract**
142
- * (the `v1/` root): sinks may treat them as opaque strings, or route on
143
- * prefixes (e.g. event chunks to object storage, everything else to a
144
- * database). Channel ids and continuation tokens are the only segments
145
- * that may contain caller-controlled characters; they are URI-encoded.
146
- *
147
- * | Key | Value |
148
- * | --- | --- |
149
- * | `v1/{agent}/session/{sessionId}` | `SessionRecord` |
150
- * | `v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
151
- * | `v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
152
- * | `v1/{agent}/eval-run/{runId}` | `EvalRunSnapshot` |
153
- * | `v1/{agent}/ab-sample/{sessionId}/{at}` | `ABMetricSample` |
154
- * | `v1/{agent}/ab-snapshot` | latest aggregate `ABSnapshot` |
155
- */
156
- export declare const persistenceKeys: {
157
- readonly session: (agent: string, sessionId: string) => string;
158
- readonly sessionPrefix: (agent: string) => string;
159
- readonly sessionEvents: (agent: string, sessionId: string, firstIndex: number) => string;
160
- readonly sessionEventsPrefix: (agent: string, sessionId: string) => string;
161
- readonly continuation: (agent: string, channelId: string, continuationKey: string) => string;
162
- readonly evalRun: (agent: string, runId: string) => string;
163
- readonly evalRunPrefix: (agent: string) => string;
164
- readonly abSample: (agent: string, sessionId: string, at: string) => string;
165
- readonly abSnapshot: (agent: string) => string;
166
- };
167
- export declare const PERSISTENCE_DEFAULT_RESTORE_MAX_SESSIONS = 1000;
168
- export declare const PERSISTENCE_DEFAULT_RESTORE_MAX_AGE_MS: number;
169
- export declare const PERSISTENCE_DEFAULT_RESTORE_MAX_TOTAL_BYTES = 1073741824;
170
- /** {@link PersistencePolicy} with defaults applied. */
171
- export interface ResolvedPersistencePolicy {
172
- /** Event-chunk flush trigger: per turn, or debounced across turns. */
173
- events: "turnEnd" | {
174
- debounceMs: number;
175
- };
176
- restore: "off" | {
177
- maxSessions: number;
178
- maxAgeMs: number;
179
- maxTotalBytes: number;
180
- };
181
- }
182
- /** Apply {@link PersistencePolicy} defaults (exposed for tooling/tests). */
183
- export declare function resolvePersistencePolicy(policy: PersistencePolicy | undefined): ResolvedPersistencePolicy;
184
- //# sourceMappingURL=persistence.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"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"}