@cursor/july 0.1.7 → 0.1.9

package/dist/docs/assets/example-agents_index.md.CRqJlnIf.js

@@ -1,2 +0,0 @@
-import{_ as t,c as a,o as r,ag as i}from"./chunks/framework.CAZyNGu9.js";const m=JSON.parse('{"title":"Choose the right agentkit example","description":"Compare all eleven example agents by runtime, channels, tools, state, and the framework pattern each one teaches.","frontmatter":{"title":"Choose the right agentkit example","description":"Compare all eleven example agents by runtime, channels, tools, state, and the framework pattern each one teaches."},"headers":[],"relativePath":"example-agents/index.md","filePath":"example-agents/index.md"}'),o={name:"example-agents/index.md"};function s(n,e,l,d,h,c){return r(),a("div",null,[...e[0]||(e[0]=[i(`<h1 id="choose-the-right-agentkit-example" tabindex="-1">Choose the right agentkit example <a class="header-anchor" href="#choose-the-right-agentkit-example" aria-label="Permalink to &quot;Choose the right agentkit example&quot;">​</a></h1><p>The examples progress from one-channel assistants to durable, event-driven workflows. Start with the smallest agent for your use case. Each guide explains its request flow, framework features, verification path, and reusable design.</p><p>The source projects live under <a href="./../../examples/"><code>examples/</code></a>. Run the commands below from <code>packages/agent-serve</code>. See <a href="./../README.html#run-the-cli">Run the CLI</a> if the <code>agentkit</code> command isn&#39;t installed.</p><h2 id="compare-the-examples" tabindex="-1">Compare the examples <a class="header-anchor" href="#compare-the-examples" aria-label="Permalink to &quot;Compare the examples&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Agent</th><th>Runtime</th><th>Intake</th><th>Framework focus</th><th>What sets it apart</th></tr></thead><tbody><tr><td><a href="./weather-agent.html">Weather agent</a></td><td>Local</td><td>HTTP and two Slack transports</td><td>Tools, stdio MCP, approvals, skill, subagent, schedule, hook, A/B, and evals</td><td>It demonstrates the broad local-runtime surface in one domain.</td></tr><tr><td><a href="./slack-agent.html">Slack agent</a></td><td>Local</td><td>Account-linked Slack</td><td>Channel identity, threads, and suggested prompts</td><td>It reaches Slack without authored tools.</td></tr><tr><td><a href="./concierge.html">Concierge</a></td><td>Local</td><td>Built-in HTTP</td><td>Peer MCP and multi-agent serving</td><td>It delegates to a separate agent with its own tools, sessions, and context.</td></tr><tr><td><a href="./benny.html">Playbook router</a></td><td>Local with repo context</td><td>Two Slack transports</td><td>Channel watching, inherited skills, custom cwd, and an eval</td><td>An allowlisted Slack channel becomes an intake queue for repo playbooks.</td></tr><tr><td><a href="./bugbot.html">PR evidence reviewer</a></td><td>Local</td><td>Custom HTTP and Slack</td><td>Host tool, skill, seeded workspaces, and an eval</td><td>The model receives a prepared diff-first evidence tree instead of a checkout.</td></tr><tr><td><a href="./approval-buddy.html">Approval Buddy</a></td><td>Local</td><td>GitHub and Slack</td><td>Policy tools, two subagents, durable storage, and evals</td><td>Code decides whether a PR may be approved. Reviews stay informational.</td></tr><tr><td><a href="./security-reviewer.html">Security Reviewer</a></td><td>Local host pipeline</td><td>GitHub and chat</td><td>Staged tools, parallel SDK agents, progress UI, durable storage, A/B, and evals</td><td>Reviewers and triage overlap while the playground shows every stage.</td></tr><tr><td><a href="./fsd.html">Remote PR coordinator</a></td><td>Local coordinator and remote PR sessions</td><td>HTTP, GitHub, and Slack</td><td>Remote handoff, hooks, affinity, buffering, reminders, and workflow MCP</td><td>One remote conversation follows a PR across chat, webhooks, and timed wakes.</td></tr><tr><td><a href="./knowledge-base.html">Knowledge base</a></td><td>Local</td><td>Built-in HTTP chat</td><td>Durable host-side state, a conventions skill, a schedule, unit tests, and evals</td><td>People curate shared facts in chat, and fresh sessions retrieve them from markdown.</td></tr><tr><td><a href="./codebase-wiki.html">Codebase wiki</a></td><td>Local</td><td>GitHub and chat</td><td>Task-dispatch webhooks, seeded digests, a mapping skill, a schedule, and evals</td><td>Merged PRs accumulate into per-feature wiki pages with a daily digest.</td></tr><tr><td><a href="./codeowners-review.html">Codeowners review</a></td><td>Local</td><td>GitHub, chat, and fixtures</td><td>Ownership routing in code, playbook data files, parallel subagents, and evals</td><td>Each product area reviews with its own playbook, and verdicts aggregate mechanically.</td></tr></tbody></table><h2 id="pick-a-learning-path" tabindex="-1">Pick a learning path <a class="header-anchor" href="#pick-a-learning-path" aria-label="Permalink to &quot;Pick a learning path&quot;">​</a></h2><p>Use this order when you want to learn agentkit one capability at a time:</p><ol><li>Start with <a href="./weather-agent.html">Weather agent</a> to explore the filesystem conventions and local runtime.</li><li>Strip the project back to <a href="./slack-agent.html">Slack agent</a> to see the minimum channel surface.</li><li>Read <a href="./benny.html">Playbook router</a> when Slack should route requests into repo playbooks.</li><li>Add composition with <a href="./concierge.html">Concierge</a>.</li><li>Study <a href="./bugbot.html">PR evidence reviewer</a> before giving a model repository evidence.</li><li>Move policy into code with <a href="./approval-buddy.html">Approval Buddy</a>.</li><li>Compare <a href="./security-reviewer.html">Security Reviewer</a> and <a href="./fsd.html">Remote PR coordinator</a> for host-side versus remote PR work.</li><li>See parallel subagent delegation carry team judgment in <a href="./codeowners-review.html">Codeowners review</a>.</li><li>Curate team context through conversation with <a href="./knowledge-base.html">Knowledge base</a>, then let GitHub events maintain product documentation in <a href="./codebase-wiki.html">Codebase wiki</a>.</li></ol><h2 id="common-prerequisites" tabindex="-1">Common prerequisites <a class="header-anchor" href="#common-prerequisites" aria-label="Permalink to &quot;Common prerequisites&quot;">​</a></h2><p>All examples require:</p><ul><li>Node 22.13 or newer. Don&#39;t run agentkit under Bun.</li><li>Workspace dependencies installed.</li><li>An agent-runtime credential for model turns.</li></ul><p>Several examples need more:</p><ul><li>Account-linked Slack channels require a connected host account.</li><li>GitHub examples require access to the target repository. Codebase wiki and Codeowners review call the host <code>gh</code> CLI for PR data; the codeowners fixtures run without network.</li><li>Approval Buddy and Security Reviewer define custom durable session storage.</li><li>Remote PR coordinator starts remote agent sessions and needs access to its workflow backend.</li></ul><p>Each guide lists its own credentials, services, and side effects.</p><h2 id="validate-any-example" tabindex="-1">Validate any example <a class="header-anchor" href="#validate-any-example" aria-label="Permalink to &quot;Validate any example&quot;">​</a></h2><p>Discovery commands don&#39;t start a model turn:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p>Start one development server with <code>agentkit dev examples/&lt;name&gt;</code>. Concierge depends on Weather agent, so its guide creates an isolated two-project mount. Don&#39;t mount the whole examples directory to test one agent; several advanced examples subscribe to live GitHub events.</p><h2 id="read-by-framework-feature" tabindex="-1">Read by framework feature <a class="header-anchor" href="#read-by-framework-feature" aria-label="Permalink to &quot;Read by framework feature&quot;">​</a></h2><ul><li><a href="./../concepts.html">Concepts</a> explains filesystem discovery and runtime boundaries.</li><li><a href="./../reference/project-layout.html">Project layout</a> lists every authored folder.</li><li><a href="./../reference/tools.html">Tools</a>, <a href="./../reference/channels.html">channels</a>, and <a href="./../reference/connections.html">MCP connections</a> cover the core extension points.</li><li><a href="./../evals.html">Evals</a> and <a href="./../ab.html">live A/B metrics</a> cover measured iteration.</li><li><a href="./../deployment.html">Deployment</a> covers credentials, auth, storage, and hosting.</li></ul>`,20)])])}const u=t(o,[["render",s]]);export{m as __pageData,u as default};

package/dist/docs/assets/example-agents_index.md.CRqJlnIf.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as a,o as r,ag as i}from"./chunks/framework.CAZyNGu9.js";const m=JSON.parse('{"title":"Choose the right agentkit example","description":"Compare all eleven example agents by runtime, channels, tools, state, and the framework pattern each one teaches.","frontmatter":{"title":"Choose the right agentkit example","description":"Compare all eleven example agents by runtime, channels, tools, state, and the framework pattern each one teaches."},"headers":[],"relativePath":"example-agents/index.md","filePath":"example-agents/index.md"}'),o={name:"example-agents/index.md"};function s(n,e,l,d,h,c){return r(),a("div",null,[...e[0]||(e[0]=[i("",20)])])}const u=t(o,[["render",s]]);export{m as __pageData,u as default};

package/dist/internal/persistence-coordinator.d.ts

@@ -1,127 +0,0 @@
-/**
- * Runtime for `definePersistence` (`agent/persistence.ts`).
- *
- * The coordinator is the single funnel between the engine's hot paths and
- * the author's key-value sink. The sink is four functions (`put` / `get` /
- * `delete` / `list`); the coordinator owns everything else: it mints every
- * key from the versioned scheme ({@link persistenceKeys}), coalesces
- * session records and batches event chunks per turn (or debounce window),
- * serializes delivery on one bounded queue per agent, and isolates
- * failures — a throwing sink is logged and its write dropped; persistence
- * must never stall or fail a turn.
- *
- * Scaling shape: sessions, evals, and A/Bs all reduce to keyed puts on the
- * same queue, so one author-owned sink covers every domain, and new
- * domains are new key prefixes — not new config surface.
- */
-import type { ABSamplePersistence } from "../ab.js";
-import type { EvalRunPersistence } from "../evals.js";
-import { type PersistenceContext, type PersistenceDefinition, type ResolvedPersistencePolicy } from "../persistence.js";
-import type { SessionEvent, SessionRecord } from "../types.js";
-import type { ABSnapshot } from "./ab-snapshot.js";
-export interface PersistenceCoordinatorOptions {
-    definition: PersistenceDefinition;
-    agentName: string;
-    projectRoot: string;
-    logger: (line: string) => void;
-}
-export declare class PersistenceCoordinator {
-    readonly policy: ResolvedPersistencePolicy;
-    private readonly definition;
-    private readonly agentName;
-    private readonly projectRoot;
-    private readonly logger;
-    /** Per-session pending state (events + coalesced record). */
-    private readonly buffers;
-    /**
-     * Last continuation key written to the sink per session, so a token
-     * change emits a delete for the stale index entry alongside the new put.
-     */
-    private readonly continuationIndex;
-    /** Single delivery chain: writes reach the sink serialized, in order. */
-    private queue;
-    /** Ops on the queue not yet delivered (bounded by MAX_PENDING_OPS). */
-    private pending;
-    /** Ops dropped because the queue was full. */
-    private dropped;
-    private lastAbSnapshotAt;
-    private closed;
-    constructor(options: PersistenceCoordinatorOptions);
-    /** Durable session-record update (engine calls after every store save). */
-    sessionRecord(record: SessionRecord): void;
-    /** One appended session event (engine calls from its dispatch funnel). */
-    event(event: SessionEvent): void;
-    /**
-     * A boundary event's dispatch settled: channel/hook handlers ran and
-     * their record updates (channel state, continuation tokens) are
-     * buffered. This — not the append — is the turn-end flush point, so the
-     * persisted session record includes the boundary event's own handler
-     * mutations. Debounced batching intentionally ignores boundaries.
-     */
-    eventDispatched(event: SessionEvent): void;
-    /** Flush everything buffered for one session (ordered: events, record). */
-    flushSession(sessionId: string, reason?: PersistenceContext["reason"]): void;
-    /**
-     * Index maintenance for `continuation/{channelId}/{token}` → sessionId:
-     * put the current token, delete the previous one when it changed.
-     */
-    private continuationOps;
-    /** Whether the sink can serve the startup bulk restore (`list`). */
-    get canBulkRestore(): boolean;
-    /**
-     * Saved session records for this agent (startup restore). Errors are
-     * logged and read as "nothing saved" — a broken store must never block
-     * serve start.
-     */
-    listSessions(): Promise<SessionRecord[]>;
-    /**
-     * Saved event stream for one session: chunk values concatenated in key
-     * order (chunks are keyed by their first event's index, zero-padded, so
-     * ascending key order is append order). Errors read as an empty stream.
-     */
-    listSessionEvents(sessionId: string): Promise<SessionEvent[]>;
-    /**
-     * One saved session by channel continuation key (lazy restore). Unlike
-     * the startup reads, sink errors **propagate**: a failing store must
-     * fail the follow-up (which the caller can retry) rather than read as
-     * "unknown token" — that would mint a new session under the same
-     * continuation key and permanently shadow the real one on this host.
-     * A definitive miss (no index entry, or a write-only sink without
-     * `get`) resolves undefined.
-     */
-    getSessionByContinuation(channelId: string, continuationKey: string): Promise<SessionRecord | undefined>;
-    /**
-     * Adapter for {@link EvalRunPersistence} so the playground eval store
-     * can fall back to this sink when `evals.config.ts` sets no
-     * `persistRuns`.
-     */
-    asEvalRunPersistence(): EvalRunPersistence;
-    /**
-     * Adapter for {@link ABSamplePersistence} so the AB collector can fall
-     * back to this sink when `ab.config.ts` sets no `persistSamples`.
-     */
-    asABSamplePersistence(): ABSamplePersistence;
-    /**
-     * Refresh the persisted aggregate A/B snapshot, throttled to once per
-     * {@link AB_SNAPSHOT_MIN_INTERVAL_MS} (the playground recomputes the
-     * fold on every `GET /v1/abs` poll).
-     */
-    abSnapshot(snapshot: ABSnapshot): void;
-    /** Latest persisted aggregate A/B snapshot; errors read as absent. */
-    getLatestAbSnapshot(): Promise<ABSnapshot | undefined>;
-    /**
-     * Flush all buffers and drain the queue, giving the sink at most
-     * {@link CLOSE_DRAIN_TIMEOUT_MS} — a hung sink must not stall shutdown
-     * past the pod grace period. Called from engine close.
-     */
-    close(): Promise<void>;
-    /** Pending deliveries (exposed for tests and drain instrumentation). */
-    whenIdle(): Promise<void>;
-    private buffer;
-    private armDebounce;
-    /** `list` wrapper for the startup reads: missing hook or throw ⇒ empty. */
-    private tryList;
-    private enqueue;
-    private context;
-}
-//# sourceMappingURL=persistence-coordinator.d.ts.map

package/dist/internal/persistence-coordinator.d.ts.map

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

package/dist/persistence.d.ts

@@ -1,184 +0,0 @@
-/**
- * Durable persistence plug-in for agent-serve.
- *
- * Author `agent/persistence.ts` with {@link definePersistence} to mirror the
- * framework's durable state into storage you own (a database, S3, a data
- * pipeline, …). Without it, state lives under `--state-root` on local disk
- * only (and eval/A/B history follows the narrower `persistRuns` /
- * `persistSamples` / `persistSnapshots` hooks).
- *
- * The sink is a plain key-value store — four functions, no schema:
- *
- * ```ts
- * import { definePersistence } from "@anysphere/agent-serve/persistence";
- *
- * export default definePersistence({
- *   put: (key, value) => db.upsert(key, value),
- *   get: (key) => db.get(key),
- *   delete: (key) => db.delete(key),
- *   list: (prefix) => db.listByPrefix(prefix), // [{ key, value }] in key order
- * });
- * ```
- *
- * The **framework mints every key** from a stable, versioned scheme (see
- * {@link persistenceKeys}) and decides **when** to call the sink: session
- * records and event chunks flush when a turn's handlers have settled,
- * reads happen at serve start (bulk restore), on continuation-token misses
- * (lazy restore), and at playground hydration. Authors do not schedule
- * reads or writes — the only timing knobs are {@link PersistencePolicy}'s
- * `debounceMs` (event write batching) and `restore` (startup hydration).
- *
- * Because keys are opaque strings to the sink, new kinds of durable state
- * (reminders, channel cursors, thread affinity, …) are new key prefixes —
- * existing sinks store them with no code changes.
- *
- * Delivery semantics: writes are **serialized** (one sink call in flight
- * per agent, in order), **bounded** (a sink that falls behind sheds writes
- * rather than growing memory), and **at-most-once** — a throwing `put` is
- * logged and dropped, never retried, and never fails a turn. The local
- * event log under `--state-root` remains the live source of truth; this
- * interface is the durable mirror.
- */
-import type { JsonValue } from "./types.js";
-/** One `{ key, value }` pair returned by {@link PersistenceConfig.list}. */
-export interface PersistenceEntry {
-    key: string;
-    value: JsonValue;
-}
-/** Context passed to every sink call. */
-export interface PersistenceContext {
-    /** Agent name (also baked into every key; see {@link persistenceKeys}). */
-    agentName: string;
-    /** Absolute agent project root (directory that contains `agent/`). */
-    projectRoot: string;
-    /**
-     * Why the framework is calling:
-     * - `"policy"` — a flush trigger fired (turn end, debounce, change)
-     * - `"shutdown"` — the serve process is draining; last chance to write
-     * - `"restore"` — serve start or a lazy restore; reads rebuilding state
-     */
-    reason: "policy" | "shutdown" | "restore";
-}
-export interface PersistencePolicy {
-    /**
-     * Batch event-chunk writes on a quiet-period timer instead of flushing
-     * once per turn. The debounce **spans turn boundaries** — a rapid
-     * multi-turn exchange becomes one write when the session goes quiet —
-     * so it is the right choice for chatty sessions where per-turn writes
-     * are too many. Unset (default): one event chunk per turn.
-     */
-    debounceMs?: number;
-    /**
-     * Guardrails for the **startup bulk restore**. Whatever `list` returns
-     * is filtered to these caps before anything is written to local disk, so
-     * a large store cannot blow up `--state-root` or stall serve start.
-     * Newest sessions (by `updatedAt`) win within each cap.
-     *
-     * `"off"` disables the startup restore entirely — sessions then restore
-     * one at a time as follow-ups actually arrive (lazy-only; recommended
-     * for high-traffic deployments).
-     */
-    restore?: PersistenceRestorePolicy | "off";
-}
-/** Caps applied to the startup bulk restore. See {@link PersistencePolicy.restore}. */
-export interface PersistenceRestorePolicy {
-    /** Max sessions materialized (default {@link PERSISTENCE_DEFAULT_RESTORE_MAX_SESSIONS}). */
-    maxSessions?: number;
-    /**
-     * Skip sessions whose `updatedAt` is older than this (default
-     * {@link PERSISTENCE_DEFAULT_RESTORE_MAX_AGE_MS}). Older sessions remain
-     * reachable lazily on their next follow-up.
-     */
-    maxAgeMs?: number;
-    /**
-     * Stop restoring once this many bytes of records + events have been
-     * written (default {@link PERSISTENCE_DEFAULT_RESTORE_MAX_TOTAL_BYTES}).
-     * Checked before each session is written, so one oversized stream
-     * cannot blow past the budget.
-     */
-    maxTotalBytes?: number;
-}
-export interface PersistenceConfig {
-    /** Optional label surfaced on `GET /v1/info` diagnostics. */
-    name?: string;
-    /** Timing knobs; see {@link PersistencePolicy}. */
-    policy?: PersistencePolicy;
-    /**
-     * Store one value under a key (upsert, last-write-wins). Called on the
-     * framework's schedule — never concurrently, always in order. Keep it
-     * fast or buffer internally: the delivery queue is bounded, so a sink
-     * that falls behind sustained traffic sheds writes (logged) instead of
-     * growing memory; it never stalls the agent loop.
-     */
-    put(key: string, value: JsonValue, ctx: PersistenceContext): void | Promise<void>;
-    /** Remove a key. Optional — without it, deletions are skipped. */
-    delete?(key: string, ctx: PersistenceContext): void | Promise<void>;
-    /**
-     * Point lookup. Optional — required for **lazy restore** (resolving a
-     * continuation token on a replacement host) and the A/B backfill.
-     * Return `undefined`/`null` only for a **definitive** miss: on the lazy
-     * restore path a throw propagates and fails the follow-up (retryable) —
-     * a store outage must not read as "unknown token", which would fork the
-     * conversation onto a new session.
-     */
-    get?(key: string, ctx: PersistenceContext): JsonValue | undefined | null | Promise<JsonValue | undefined | null>;
-    /**
-     * All entries under a key prefix, in ascending key order. Optional —
-     * required for the **startup bulk restore** (sessions + event streams)
-     * and playground eval history.
-     */
-    list?(prefix: string, ctx: PersistenceContext): PersistenceEntry[] | Promise<PersistenceEntry[]>;
-}
-export type PersistenceDefinition = PersistenceConfig & {
-    readonly __agentServe: "persistence";
-};
-/**
- * Author the project persistence sink (`agent/persistence.ts`, default
- * export). See the module doc for semantics and an example.
- */
-export declare function definePersistence(config: PersistenceConfig): PersistenceDefinition;
-/**
- * The framework-owned key scheme. Keys are a **stable, versioned contract**
- * (the `v1/` root): sinks may treat them as opaque strings, or route on
- * prefixes (e.g. event chunks to object storage, everything else to a
- * database). Channel ids and continuation tokens are the only segments
- * that may contain caller-controlled characters; they are URI-encoded.
- *
- * | Key | Value |
- * | --- | --- |
- * | `v1/{agent}/session/{sessionId}` | `SessionRecord` |
- * | `v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
- * | `v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
- * | `v1/{agent}/eval-run/{runId}` | `EvalRunSnapshot` |
- * | `v1/{agent}/ab-sample/{sessionId}/{at}` | `ABMetricSample` |
- * | `v1/{agent}/ab-snapshot` | latest aggregate `ABSnapshot` |
- */
-export declare const persistenceKeys: {
-    readonly session: (agent: string, sessionId: string) => string;
-    readonly sessionPrefix: (agent: string) => string;
-    readonly sessionEvents: (agent: string, sessionId: string, firstIndex: number) => string;
-    readonly sessionEventsPrefix: (agent: string, sessionId: string) => string;
-    readonly continuation: (agent: string, channelId: string, continuationKey: string) => string;
-    readonly evalRun: (agent: string, runId: string) => string;
-    readonly evalRunPrefix: (agent: string) => string;
-    readonly abSample: (agent: string, sessionId: string, at: string) => string;
-    readonly abSnapshot: (agent: string) => string;
-};
-export declare const PERSISTENCE_DEFAULT_RESTORE_MAX_SESSIONS = 1000;
-export declare const PERSISTENCE_DEFAULT_RESTORE_MAX_AGE_MS: number;
-export declare const PERSISTENCE_DEFAULT_RESTORE_MAX_TOTAL_BYTES = 1073741824;
-/** {@link PersistencePolicy} with defaults applied. */
-export interface ResolvedPersistencePolicy {
-    /** Event-chunk flush trigger: per turn, or debounced across turns. */
-    events: "turnEnd" | {
-        debounceMs: number;
-    };
-    restore: "off" | {
-        maxSessions: number;
-        maxAgeMs: number;
-        maxTotalBytes: number;
-    };
-}
-/** Apply {@link PersistencePolicy} defaults (exposed for tooling/tests). */
-export declare function resolvePersistencePolicy(policy: PersistencePolicy | undefined): ResolvedPersistencePolicy;
-//# sourceMappingURL=persistence.d.ts.map

package/dist/persistence.d.ts.map

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