@cursor/july 0.1.76 → 0.1.78

package/dist/docs/assets/storage.md.D8NQ389l.lean.js

@@ -1 +0,0 @@
-import{_ as s,c as t,o as a,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse(`{"title":"Storage","description":"Point the Agent SDK's durable storage at a backend you own with defineStorage.","frontmatter":{"title":"Storage","description":"Point the Agent SDK's durable storage at a backend you own with defineStorage."},"headers":[],"relativePath":"storage.md","filePath":"storage.md"}`),n={name:"storage.md"};function o(r,e,d,l,h,p){return a(),t("div",null,[...e[0]||(e[0]=[i("",41)])])}const g=s(n,[["render",o]]);export{k as __pageData,g as default};

package/dist/internal/durable-session-store.d.ts

@@ -1,60 +0,0 @@
-/**
- * Durable-session store resolution.
- *
- * Two APIs, one backend: `defineStorage` is the **storage API** (agent
- * state — session records, event chunks, author KV), and the session
- * ledger is the **durable session API** (session identity, mailboxes,
- * leases, fenced commits). The ledger consumes {@link SessionLedgerKv} —
- * the full CAS-capable KV surface, since the inbox reads/sweeps mailbox
- * payload blobs (`get`/`put`/`delete`) and scans by prefix (`listKeys`)
- * on top of the CAS trio; this module adapts a storage backend's methods
- * into that interface, so a deployment's one authored backend serves
- * both APIs by default.
- *
- * Calls go straight at the config's methods — NOT through the
- * StorageCoordinator: the coordinator's queue is bounded, serialized, and
- * at-most-once (mirror semantics), while ledger CAS calls are the
- * correctness path and must observe their own results synchronously.
- */
-import type { SessionLedgerKv } from "../ledger/session-ledger.js";
-import { type StorageConfig } from "../storage.js";
-export interface StorageCasKvArgs {
-    agentName: string;
-    projectRoot: string;
-}
-/**
- * The one place the ledger's physical namespace is minted: the per-agent
- * prefix for ledger state, following the {@link storageKeys} convention
- * (`<root>/<agent>/<family>/…`) so a store shared by several ledger-mode
- * agents (one fileKv dir, one hosted deployment) never mixes their
- * sessions, leases, or mailboxes — and so each agent's janitor
- * prefix-scan only ever sees its own ledgers. The extra
- * `durable-session` segment keeps the ledger's `session/` family out of
- * `storageKeys.sessionPrefix` scans (storage restore lists
- * `<root>/<agent>/session/`). The ledger itself never sees this string:
- * it speaks bare `session/…` / `ledger/…` / `mailbox/…` keys against a
- * handle that {@link namespacedKv} has already scoped.
- */
-export declare function ledgerKeyPrefix(agentName: string): string;
-/**
- * Adapt a storage backend into the ledger's KV interface. Throws when
- * the backend does not implement the `cas` group, or omits `get` /
- * `delete` (optional for resident-only sinks, but the ledger reads and
- * sweeps mailbox payload blobs through the same store) — the caller
- * turns that into the fail-fast startup error for `serving: "ledger"`.
- * Every call carries a `reason: "coordination"` {@link StorageContext}.
- */
-export declare function storageCasKv(config: StorageConfig, args: StorageCasKvArgs): SessionLedgerKv;
-/**
- * Scope a raw store handle under a namespace: every key going in gets it
- * prepended, and `listKeys` results come back with it **stripped**, so a
- * caller that lists and then reads/deletes the returned keys stays fully
- * prefix-free (the janitor scan and the orphan sweep do exactly that).
- * Applied exactly once, where the engine constructs the ledger's store
- * handle — the same conceptual boundary where `host.kv` gets its agent
- * scoping. Internal: not part of the public kv interface, and callers
- * (including the explicit `durableSessionStore` override) always supply
- * the raw store — they never write prefixes.
- */
-export declare function namespacedKv(store: SessionLedgerKv, namespace: string): SessionLedgerKv;
-//# sourceMappingURL=durable-session-store.d.ts.map

package/dist/internal/durable-session-store.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"durable-session-store.d.ts","sourceRoot":"","sources":["../../src/internal/durable-session-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAC;AAGvB,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,gBAAgB,GACrB,eAAe,CA0CjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,GAChB,eAAe,CAcjB"}

package/dist/internal/durable-session-store.js

@@ -1,131 +0,0 @@
-/**
- * Durable-session store resolution.
- *
- * Two APIs, one backend: `defineStorage` is the **storage API** (agent
- * state — session records, event chunks, author KV), and the session
- * ledger is the **durable session API** (session identity, mailboxes,
- * leases, fenced commits). The ledger consumes {@link SessionLedgerKv} —
- * the full CAS-capable KV surface, since the inbox reads/sweeps mailbox
- * payload blobs (`get`/`put`/`delete`) and scans by prefix (`listKeys`)
- * on top of the CAS trio; this module adapts a storage backend's methods
- * into that interface, so a deployment's one authored backend serves
- * both APIs by default.
- *
- * Calls go straight at the config's methods — NOT through the
- * StorageCoordinator: the coordinator's queue is bounded, serialized, and
- * at-most-once (mirror semantics), while ledger CAS calls are the
- * correctness path and must observe their own results synchronously.
- */
-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 { keySegment, STORAGE_KEY_ROOT, } from "../storage.js";
-/**
- * The one place the ledger's physical namespace is minted: the per-agent
- * prefix for ledger state, following the {@link storageKeys} convention
- * (`<root>/<agent>/<family>/…`) so a store shared by several ledger-mode
- * agents (one fileKv dir, one hosted deployment) never mixes their
- * sessions, leases, or mailboxes — and so each agent's janitor
- * prefix-scan only ever sees its own ledgers. The extra
- * `durable-session` segment keeps the ledger's `session/` family out of
- * `storageKeys.sessionPrefix` scans (storage restore lists
- * `<root>/<agent>/session/`). The ledger itself never sees this string:
- * it speaks bare `session/…` / `ledger/…` / `mailbox/…` keys against a
- * handle that {@link namespacedKv} has already scoped.
- */
-export function ledgerKeyPrefix(agentName) {
-    return `${STORAGE_KEY_ROOT}/${keySegment(agentName)}/durable-session/`;
-}
-/**
- * Adapt a storage backend into the ledger's KV interface. Throws when
- * the backend does not implement the `cas` group, or omits `get` /
- * `delete` (optional for resident-only sinks, but the ledger reads and
- * sweeps mailbox payload blobs through the same store) — the caller
- * turns that into the fail-fast startup error for `serving: "ledger"`.
- * Every call carries a `reason: "coordination"` {@link StorageContext}.
- */
-export function storageCasKv(config, args) {
-    const ctx = {
-        agentName: args.agentName,
-        projectRoot: args.projectRoot,
-        reason: "coordination",
-    };
-    const { cas } = config;
-    if (cas === undefined) {
-        throw new Error("storageCasKv: the storage backend does not implement the cas group (conditional writes)");
-    }
-    const get = config.get;
-    const remove = config.delete;
-    if (get === undefined || remove === undefined) {
-        throw new Error("storageCasKv: the storage backend must implement get and delete (the session ledger reads and sweeps payload blobs through the same store)");
-    }
-    return {
-        get(key) {
-            return __awaiter(this, void 0, void 0, function* () {
-                var _a;
-                return (_a = (yield get(key, ctx))) !== null && _a !== void 0 ? _a : undefined;
-            });
-        },
-        put(key, value) {
-            return __awaiter(this, void 0, void 0, function* () {
-                yield config.put(key, value, ctx);
-            });
-        },
-        delete(key) {
-            return __awaiter(this, void 0, void 0, function* () {
-                yield remove(key, ctx);
-            });
-        },
-        getWithVersion(key) {
-            return __awaiter(this, void 0, void 0, function* () {
-                return yield cas.getWithVersion(key, ctx);
-            });
-        },
-        putIfAbsent(key, value) {
-            return __awaiter(this, void 0, void 0, function* () {
-                return yield cas.putIfAbsent(key, value, ctx);
-            });
-        },
-        putIfVersion(key, value, expectedVersion) {
-            return __awaiter(this, void 0, void 0, function* () {
-                return yield cas.putIfVersion(key, value, expectedVersion, ctx);
-            });
-        },
-        listKeys(prefix) {
-            return __awaiter(this, void 0, void 0, function* () {
-                return yield cas.listKeys(prefix, ctx);
-            });
-        },
-    };
-}
-/**
- * Scope a raw store handle under a namespace: every key going in gets it
- * prepended, and `listKeys` results come back with it **stripped**, so a
- * caller that lists and then reads/deletes the returned keys stays fully
- * prefix-free (the janitor scan and the orphan sweep do exactly that).
- * Applied exactly once, where the engine constructs the ledger's store
- * handle — the same conceptual boundary where `host.kv` gets its agent
- * scoping. Internal: not part of the public kv interface, and callers
- * (including the explicit `durableSessionStore` override) always supply
- * the raw store — they never write prefixes.
- */
-export function namespacedKv(store, namespace) {
-    return {
-        get: (key) => store.get(namespace + key),
-        put: (key, value) => store.put(namespace + key, value),
-        delete: (key) => store.delete(namespace + key),
-        getWithVersion: (key) => store.getWithVersion(namespace + key),
-        putIfAbsent: (key, value) => store.putIfAbsent(namespace + key, value),
-        putIfVersion: (key, value, expectedVersion) => store.putIfVersion(namespace + key, value, expectedVersion),
-        listKeys: (prefix) => __awaiter(this, void 0, void 0, function* () {
-            const keys = yield store.listKeys(namespace + prefix);
-            return keys.map((key) => key.slice(namespace.length));
-        }),
-    };
-}

package/dist/internal/ledger-serving.d.ts

@@ -1,169 +0,0 @@
-/**
- * Ledger-mode serving seam (`serving: "ledger"` on `defineAgent`): an event
- * pump that routes every engine `send` through the KV session ledger
- * instead of starting turns directly.
- *
- * Delivery: ensureSession (continuation key, as today) → principal gate
- * (an existing session rejects a sender that is not its principal BEFORE
- * anything is parked; mirrors the resident `samePrincipal` check) →
- * appendEvent (payload + CAS — the source ack point moves after this) →
- * claim → drain → run the drained turns through the resident engine path →
- * commit (heartbeats while turns run) → repeat while the commit reports
- * pending. A deliver that finds the lease held walks away (the holder's
- * commit sees the append); the janitor recovers sessions whose holder
- * died. A foreign-principal envelope that reaches the mailbox anyway is
- * consumed and committed away at drain (warn log), never replayed.
- *
- * v1 scope: the mailbox envelope carries `message`, `auth`, `title`,
- * `state`, `mode`, `purpose`, and the isolation-relevant per-send
- * overrides `workspaceDir` and `cloud` — the two options
- * `resolveSessionRuntime` and harness-cwd selection read. Dropping
- * those is a sandbox escape, not a feature gap: without them a drained
- * GitHub/Slack turn falls back to the local runtime with the default
- * harness cwd, so untrusted channel content drives tools on the serve
- * host instead of the cloud VM / channel worktree. `coalesceSourceTs`
- * (when present) is used as the drain-ordering `sourceTs`. Deferred
- * (documented, not silently faked — deliver logs a warning naming what
- * it dropped): `workspaceFiles` and per-turn `images` (content
- * injection, and their base64 payloads can blow the mailbox blob past
- * hosted KV value caps), `sdkAgentId` seeding, and `admission`
- * semantics (both `"preempt"` and Slack `"coalesce"` nudge bookkeeping
- * — ledger draining already serializes turns, but nothing is
- * interrupted or coalesced through the mailbox).
- */
-import type { SessionLedger } from "../ledger/session-ledger.js";
-import type { AgentCloudOptions, AuthContext, ChannelSession, JsonValue, SendMessageOptions, SessionPurpose } from "../types.js";
-/** The JSON payload stored in `mailbox/<sessionId>/<eventId>`. */
-export interface LedgerDeliveryEnvelope {
-    channelId: string;
-    continuationToken: string;
-    message: string;
-    auth: AuthContext | null;
-    title?: string;
-    state?: JsonValue;
-    mode?: "chat" | "task";
-    purpose?: SessionPurpose;
-    /**
-     * Isolation-relevant per-send overrides, reapplied on the resident
-     * send at drain. Absent on envelopes parked by earlier builds — the
-     * drain then behaves as those builds did (agent-default runtime/cwd).
-     */
-    workspaceDir?: string;
-    cloud?: AgentCloudOptions;
-}
-/** The `send` options the envelope can carry through the mailbox. */
-export type LedgerDeliverOptions = SendMessageOptions & {
-    mode?: "chat" | "task";
-};
-export interface LedgerServingOptions {
-    ledger: SessionLedger;
-    /**
-     * Run one drained event as a resident-path turn (the engine's `send`
-     * with the internal `fromLedgerPump` flag). Must resolve once the turn
-     * is admitted; the pump awaits `waitForCompletion` itself.
-     */
-    deliverTurn: (envelope: LedgerDeliveryEnvelope) => Promise<ChannelSession>;
-    /** Engine continuation lookup (local index + lazy storage restore). */
-    findSession: (channelId: string, continuationToken: string) => Promise<ChannelSession | undefined>;
-    logger?: (line: string) => void;
-    /** Lease heartbeat cadence while turns run (default 10s). */
-    heartbeatIntervalMs?: number;
-    /** Janitor scan cadence (default `DEFAULT_JANITOR_INTERVAL_MS`). */
-    janitorIntervalMs?: number;
-    clock?: () => number;
-}
-export declare class LedgerServing {
-    private readonly ledger;
-    private readonly deliverTurn;
-    private readonly findSession;
-    private readonly logger;
-    private readonly heartbeatIntervalMs;
-    private readonly clock;
-    private readonly janitor;
-    /** One pump per ledger session — the in-process face of the lease. */
-    private readonly pumps;
-    /** Fire-and-forget re-pump checks, awaited on close. */
-    private readonly background;
-    constructor(options: LedgerServingOptions);
-    /** Start the janitor loop (recovers expired-lease sessions). */
-    start(): void;
-    /** Stop the janitor and settle in-flight pumps and re-pump checks. */
-    close(): Promise<void>;
-    /**
-     * Ledger-mode `send`: append the message to the session mailbox, then
-     * serve pending events (or walk away if another holder is already
-     * serving them). Resolves with the engine session handle once one
-     * exists — the ack point is the durable append, not turn completion —
-     * so HTTP create/follow-up can return a session id while the holder is
-     * still in flight. When this process wins the claim, the pump keeps
-     * draining in the background; callers that need the turn to finish use
-     * `waitForCompletion` (and the lease releases on the pump's commit).
-     * When another holder is serving the session and no engine session
-     * exists on this pod, the delivery is still a success — the event is
-     * durably parked and the holder's commit (or the janitor) drains it —
-     * so the resolved handle is a parked stand-in carrying the durable
-     * session identity.
-     */
-    deliver(channelId: string, message: string, options: LedgerDeliverOptions): Promise<ChannelSession>;
-    /**
-     * The stand-in handle for a delivery whose event is parked while
-     * another holder serves the session: real durable identity, no local
-     * turn. `waitForCompletion` resolves immediately — the parked event's
-     * turn runs on the holder, so there is nothing local to await (the
-     * same contract as a coalesced send, whose outcome is not its own
-     * message's turn). The event stream and re-keying live wherever the
-     * turn runs, so both fail loudly here.
-     */
-    private parkedSession;
-    /**
-     * Return a handle as soon as the engine session exists, without waiting
-     * for the pump to commit. If the pump settles without creating a
-     * session (walk-away, or a throw before admit), surface that: rethrow
-     * a failed claimant turn, otherwise the parked stand-in.
-     */
-    private resolveDeliverHandle;
-    /**
-     * Drain ordering: prefer the real source time over this pod's receipt
-     * time. `coalesceSourceTs` is a Slack-style seconds string
-     * (`"1712345678.000100"`); normalize sub-epoch-ms values to ms so they
-     * stay comparable with the `Date.now()` fallback.
-     */
-    private resolveSourceTs;
-    /**
-     * One warning per delivery naming the send options the mailbox does not
-     * replay — better a loud line than an author silently losing images or
-     * admission semantics on a ledger-mode agent.
-     */
-    private warnOnDroppedOptions;
-    /**
-     * Serve a session's pending events. When a pump is already running the
-     * caller walks away (the holder's commit re-reads pending) — except
-     * that the holder's *final* commit may have released before this
-     * append landed, so a re-check is chained behind it. Deliver never
-     * awaits this promise for its full lifetime: awaiting a new pump would
-     * block HTTP until the turn committed, and awaiting a running pump
-     * would deadlock a send issued from inside one of its turns.
-     */
-    private servePending;
-    /** Claim-or-defer entry used after an append and after a pump settles. */
-    private runPump;
-    /** Janitor hand-off: the claim already happened, just run the turns. */
-    private serveClaimed;
-    /**
-     * Re-pump after the previous holder settled, covering the release window
-     * where an append landed after that holder's final commit.
-     */
-    private repumpIfPending;
-    /** Register a pump in the per-session map for its lifetime. */
-    private track;
-    /**
-     * The drain → turn → commit loop for a held lease. Heartbeats extend the
-     * lease while turns run; a fenced heartbeat (or fenced commit) means a
-     * new holder took over — discard without committing; the new holder
-     * re-drains (at-least-once actuation, exactly-once ledger apply).
-     */
-    private runClaimedTurns;
-}
-/** Mint the lease holder id for this process. */
-export declare function newLedgerPodId(): string;
-//# sourceMappingURL=ledger-serving.d.ts.map

package/dist/internal/ledger-serving.d.ts.map

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