@cursor/july 0.1.7 → 0.1.9

package/dist/internal/session-engine.js

@@ -30,6 +30,7 @@ import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { mergeABInstructions, resolveABMaxPlaygroundSessions, resolveABSplit, } from "../ab.js";
 import { slackThreadPermalink } from "../channels/slack/links.js";
+import { SlackAskDedupeStore, SlackNudgeStore, } from "../channels/slack/nudge-store.js";
 import { DIRECT_TOOL_CALL_CHANNEL_ID, isSymbolicConnectionTransport, } from "../types.js";
 import { ABCollector } from "./ab-collector.js";
 import { foldABStream } from "./ab-fold.js";
@@ -40,16 +41,17 @@ import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
 import { isDevMode } from "./dev-mode.js";
 import { EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
+import { createHostKvApi } from "./host-kv.js";
 import { createHostPlatforms } from "./host-platforms.js";
 import { formatContinuationToken, newContinuationKey, newSessionId, newToolCallId, } from "./ids.js";
 import { validateToolInput } from "./json-schema.js";
 import { McpHost } from "./mcp-host.js";
-import { buildIdentitySection, buildSessionContextBlock, SCHEDULE_CHANNEL_PREFIX, } from "./prompt-context.js";
+import { buildSessionContextBlock, SCHEDULE_CHANNEL_PREFIX, } from "./prompt-context.js";
 import { assertCloudCanHonorAccountServersFilters } from "./resolved-connections.js";
 import { SessionStore } from "./session-store.js";
 import { StorageCoordinator } from "./storage-coordinator.js";
 import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
-import { buildAgentToolsCatalog, materializeWorkspace, writeWorkspaceFiles, } from "./workspace.js";
+import { buildAgentsMdContent, isNestedInGitRepo, materializeWorkspace, writeWorkspaceFiles, } from "./workspace.js";
 export const HTTP_CHANNEL_ID = "http";
 export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
 export class SessionBusyError extends Error {
@@ -120,6 +122,16 @@ export class SessionEngine {
         this.turnAborts = new Map();
         /** Serializes turn admission per session (latest follow-up wins). */
         this.admissionChains = new Map();
+        /**
+         * Per-session coalesce queue for `admission: "coalesce"` (Slack). Drained
+         * into one follow-up turn when the active turn finishes without interrupt.
+         */
+        this.coalesceQueues = new Map();
+        /**
+         * Sessions whose turn lifecycle is draining coalesced follow-ups. Counts as
+         * busy so inbound coalesce admits enqueue instead of racing `clearCoalesced`.
+         */
+        this.coalesceDrains = new Map();
         this.lastOutcomes = new Map();
         this.updateChains = new Map();
         this.dispatchChains = new Map();
@@ -132,6 +144,8 @@ export class SessionEngine {
         this.runner = options.runner;
         this.logger = (_a = options.logger) !== null && _a !== void 0 ? _a : (() => { });
         this.sessions = new SessionStore(join(options.stateRoot, "sessions"));
+        this.nudgeStore = new SlackNudgeStore(join(options.stateRoot, "slack-nudges"));
+        this.askDedupe = new SlackAskDedupeStore(join(options.stateRoot, "slack-asks"));
         this.logs = new EventLogStore((sessionId) => this.sessions.eventFilePath(sessionId), (sessionId, error) => this.logger(`[agentkit] failed to persist events for ${sessionId}: ${describeError(error)}`));
         this.storage =
             options.project.storage === undefined
@@ -142,6 +156,7 @@ export class SessionEngine {
                     projectRoot: options.project.rootDir,
                     logger: this.logger,
                 });
+        this.kvApi = createHostKvApi(Object.assign({ agentName: options.project.name, stateRoot: options.stateRoot }, (this.storage === undefined ? {} : { storage: this.storage })));
         this.abCollector = new ABCollector(options.project.abs, this.logger, (sessionId) => __awaiter(this, void 0, void 0, function* () { return (yield this.logs.get(sessionId)).snapshot(0); }), 
         // Samples flow to the defineStorage `abs` table (no-op without one).
         { persistSample: (sample) => { var _a; return (_a = this.storage) === null || _a === void 0 ? void 0 : _a.abSample(sample); } });
@@ -171,13 +186,26 @@ export class SessionEngine {
             });
         }
     }
-    /** Shared host services (MCP / GitHub / Slack / reminders). */
+    /** Shared host services (MCP / GitHub / Slack / reminders / kv / Slack nudges). */
     get host() {
         return {
             mcp: this.mcpHost,
             github: this.platforms.github,
             slack: this.platforms.slack,
             reminders: this.reminderApi,
+            kv: this.kvApi,
+            slackNudges: this.slackNudgeHostApi(),
+        };
+    }
+    slackNudgeHostApi() {
+        return {
+            append: (input) => this.nudgeStore.append(input),
+            drainFormatted: (continuationKey) => this.nudgeStore.drainFormatted(continuationKey),
+            clear: (continuationKey) => this.nudgeStore.clear(continuationKey),
+            hasUndelivered: (continuationKey) => this.nudgeStore.hasUndelivered(continuationKey),
+            isDelivered: (continuationKey, sourceTs) => this.nudgeStore.isDelivered(continuationKey, sourceTs),
+            tryClaimAsk: (channelId, messageTs) => this.askDedupe.tryClaim(channelId, messageTs),
+            releaseAsk: (channelId, messageTs) => this.askDedupe.release(channelId, messageTs),
         };
     }
     /** Attach the serve-host reminder API (called from startServer). */
@@ -195,7 +223,7 @@ export class SessionEngine {
     send(channelId_1, message_1) {
         return __awaiter(this, arguments, void 0, function* (channelId, message, options = {}) {
             var _a;
-            var _b, _c, _d;
+            var _b, _c, _d, _e, _f;
             const auth = (_b = options.auth) !== null && _b !== void 0 ? _b : null;
             let existing = options.continuationToken === undefined
                 ? undefined
@@ -219,8 +247,10 @@ export class SessionEngine {
                 else if (options.workspaceFiles !== undefined) {
                     record = yield this.updateRecord(existing.sessionId, (current) => (Object.assign(Object.assign({}, current), { pendingWorkspaceFiles: options.workspaceFiles })));
                 }
-                yield this.startTurn(record.sessionId, message);
-                return this.channelSession(record.sessionId, record, false);
+                const coalesced = yield this.startTurn(record.sessionId, message, Object.assign({ admission: (_c = options.admission) !== null && _c !== void 0 ? _c : "preempt" }, (options.coalesceSourceTs === undefined
+                    ? {}
+                    : { sourceTs: options.coalesceSourceTs })));
+                return this.channelSession(record.sessionId, record, false, coalesced);
             }
             const now = new Date().toISOString();
             const channelState = this.initialChannelState(channelId, options.state);
@@ -228,9 +258,9 @@ export class SessionEngine {
             let record = {
                 sessionId: newSessionId(),
                 channelId,
-                mode: (_c = options.mode) !== null && _c !== void 0 ? _c : "chat",
+                mode: (_d = options.mode) !== null && _d !== void 0 ? _d : "chat",
                 purpose,
-                continuationKey: (_d = options.continuationToken) !== null && _d !== void 0 ? _d : newContinuationKey(),
+                continuationKey: (_e = options.continuationToken) !== null && _e !== void 0 ? _e : newContinuationKey(),
                 auth,
                 title: options.title,
                 channelState,
@@ -249,8 +279,20 @@ export class SessionEngine {
                 data: { channelId },
             });
             record = yield this.enrollABs(record);
-            yield this.startTurn(record.sessionId, message);
-            return this.channelSession(record.sessionId, record, true);
+            yield this.startTurn(record.sessionId, message, Object.assign({ admission: (_f = options.admission) !== null && _f !== void 0 ? _f : "preempt" }, (options.coalesceSourceTs === undefined
+                ? {}
+                : { sourceTs: options.coalesceSourceTs })));
+            return this.channelSession(record.sessionId, record, true, false);
+        });
+    }
+    /** Whether a continuation token already maps to a session on this channel. */
+    hasContinuationSession(channelId, continuationToken) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let existing = yield this.sessions.findByContinuation(channelId, continuationToken);
+            if (existing === undefined) {
+                existing = yield this.restoreSessionByContinuation(channelId, continuationToken);
+            }
+            return existing !== undefined;
         });
     }
     /**
@@ -377,27 +419,95 @@ export class SessionEngine {
     // Turn execution
     // ==========================================================================
     /**
-     * Admit a turn for `sessionId`. A follow-up that arrives while a turn is in
-     * flight preempts it: the running turn is cancelled and its SDK run marked
-     * terminal before the new turn starts. Admissions are serialized per session
-     * so a burst of follow-ups can't race two runs onto the same SDK agent — the
-     * last message wins. Resolves once the new turn has started (not finished).
+     * Admit a turn for `sessionId`.
+     *
+     * Default (`preempt`): a follow-up cancels the running turn and starts
+     * immediately (HTTP / MCP). With `admission: "coalesce"` (Slack), a busy
+     * session enqueues the message and returns without interrupting; the queue
+     * drains into one follow-up when the active turn finishes.
+     *
+     * Resolves to `true` when the message was coalesced (enqueued), `false`
+     * when a turn was started.
      */
-    startTurn(sessionId, message) {
+    startTurn(sessionId, message, options = {}) {
         var _a;
         const prior = (_a = this.admissionChains.get(sessionId)) !== null && _a !== void 0 ? _a : Promise.resolve();
         const admitted = prior
             .catch(() => { })
-            .then(() => this.admitTurn(sessionId, message));
+            .then(() => this.admitTurn(sessionId, message, options));
         this.admissionChains.set(sessionId, admitted.catch(() => { }));
         return admitted;
     }
-    admitTurn(sessionId, message) {
+    enqueueCoalesced(sessionId, item) {
+        var _a;
+        const queue = (_a = this.coalesceQueues.get(sessionId)) !== null && _a !== void 0 ? _a : [];
+        if (item.sourceTs !== undefined &&
+            queue.some((entry) => entry.sourceTs === item.sourceTs)) {
+            return;
+        }
+        queue.push(item);
+        this.coalesceQueues.set(sessionId, queue);
+    }
+    clearCoalesced(sessionId) {
+        this.coalesceQueues.delete(sessionId);
+    }
+    formatCoalescedFollowups(items) {
+        if (items.length === 1) {
+            return items[0].message;
+        }
+        const parts = [
+            "<slack_followups>",
+            `ANSWER-EACH: ${items.length} asks arrived while you were busy. Address each in order; keep replies compact.`,
+            "",
+        ];
+        for (let i = 0; i < items.length; i++) {
+            parts.push(`### Ask ${i + 1}`);
+            parts.push(items[i].message);
+            parts.push("");
+        }
+        parts.push("</slack_followups>");
+        return parts.join("\n").trimEnd();
+    }
+    drainCoalescedFollowups(sessionId) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const queued = (_a = this.coalesceQueues.get(sessionId)) !== null && _a !== void 0 ? _a : [];
+            if (queued.length === 0) {
+                return;
+            }
+            this.coalesceQueues.delete(sessionId);
+            const message = this.formatCoalescedFollowups(queued);
+            this.logger(`[session] coalesce drain starting follow-up (${queued.length}) ${sessionId}`);
+            yield this.startTurn(sessionId, message, {
+                admission: "preempt",
+                retainCoalesced: true,
+            });
+        });
+    }
+    admitTurn(sessionId_1, message_1) {
+        return __awaiter(this, arguments, void 0, function* (sessionId, message, options = {}) {
+            var _a;
+            const admission = (_a = options.admission) !== null && _a !== void 0 ? _a : "preempt";
+            if (admission === "coalesce" && this.isTurnRunning(sessionId)) {
+                this.enqueueCoalesced(sessionId, Object.assign({ message }, (options.sourceTs === undefined
+                    ? {}
+                    : { sourceTs: options.sourceTs })));
+                this.logger(`[session] coalesce enqueue ${sessionId}`);
+                return true;
+            }
             // Interrupt any turn in flight and wait for it to settle so the SDK run is
             // terminal before this turn's send (the follow-up also force-expires as a
-            // belt-and-suspenders — see buildTurnRequest).
-            yield this.interruptActiveTurn(sessionId);
+            // belt-and-suspenders — see buildTurnRequest). Drain-resume skips interrupt:
+            // the parent lifecycle already cleared activeTurns, and awaiting the in-
+            // flight coalesce drain here would deadlock on itself.
+            if (options.retainCoalesced !== true) {
+                yield this.interruptActiveTurn(sessionId);
+            }
+            // Preempt owns the conversation — drop stale coalesced asks. Coalesce
+            // admits and drain-resume keep the queue (retainCoalesced / coalesce path).
+            if (admission === "preempt" && options.retainCoalesced !== true) {
+                this.clearCoalesced(sessionId);
+            }
             this.pendingTurns.add(sessionId);
             try {
                 let record = yield this.updateRecord(sessionId, (current) => (Object.assign(Object.assign({}, current), { turnCount: current.turnCount + 1 })));
@@ -417,26 +527,51 @@ export class SessionEngine {
                 });
                 const abort = new AbortController();
                 this.turnAborts.set(sessionId, abort);
-                const turnPromise = this.executeTurn(record, turnId, message, isFirstTurn, abort.signal);
-                this.activeTurns.set(sessionId, turnPromise);
-                void turnPromise
-                    .then((outcome) => {
+                // Lifecycle promise includes post-turn coalesce drain so waiters and
+                // interrupt settle after follow-ups are admitted (not only executeTurn).
+                // Assigned before the async body runs so self-identity checks typecheck.
+                let lifecycle;
+                lifecycle = (() => __awaiter(this, void 0, void 0, function* () {
+                    let outcome;
+                    try {
+                        outcome = yield this.executeTurn(record, turnId, message, isFirstTurn, abort.signal);
+                    }
+                    catch (error) {
+                        outcome = {
+                            status: "error",
+                            errorMessage: describeError(error),
+                        };
+                    }
                     this.lastOutcomes.set(sessionId, outcome);
-                })
-                    .catch(() => { })
-                    .finally(() => {
-                    // Guard against clobbering a newer turn that already replaced us.
-                    if (this.activeTurns.get(sessionId) === turnPromise) {
+                    const wasCurrent = this.activeTurns.get(sessionId) === lifecycle;
+                    if (wasCurrent) {
                         this.activeTurns.delete(sessionId);
                     }
                     if (this.turnAborts.get(sessionId) === abort) {
                         this.turnAborts.delete(sessionId);
                     }
-                });
+                    if (wasCurrent && !abort.signal.aborted) {
+                        const drain = this.drainCoalescedFollowups(sessionId).catch((error) => {
+                            this.logger(`[session] coalesce drain failed for ${sessionId}: ${describeError(error)}`);
+                        });
+                        this.coalesceDrains.set(sessionId, drain);
+                        try {
+                            yield drain;
+                        }
+                        finally {
+                            if (this.coalesceDrains.get(sessionId) === drain) {
+                                this.coalesceDrains.delete(sessionId);
+                            }
+                        }
+                    }
+                    return outcome;
+                }))();
+                this.activeTurns.set(sessionId, lifecycle);
             }
             finally {
                 this.pendingTurns.delete(sessionId);
             }
+            return false;
         });
     }
     /**
@@ -452,19 +587,80 @@ export class SessionEngine {
             if (active !== undefined) {
                 yield active.catch(() => { });
             }
+            const drain = this.coalesceDrains.get(sessionId);
+            if (drain !== undefined) {
+                yield drain.catch(() => { });
+            }
         });
     }
     /**
      * Abort the in-flight turn without starting a follow-up. Returns whether
-     * a turn was active (or pending abort) when called.
+     * a turn was active (or pending abort) when called. Also clears any
+     * coalesced follow-ups queued behind the session.
      */
     interrupt(sessionId) {
         return __awaiter(this, void 0, void 0, function* () {
-            const hadWork = this.turnAborts.has(sessionId) || this.activeTurns.has(sessionId);
+            var _a;
+            var _b;
+            const hadWork = this.turnAborts.has(sessionId) ||
+                this.activeTurns.has(sessionId) ||
+                this.coalesceDrains.has(sessionId) ||
+                ((_b = (_a = this.coalesceQueues.get(sessionId)) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) > 0;
+            this.clearCoalesced(sessionId);
+            const record = yield this.sessions.get(sessionId);
+            const continuationKey = record === null || record === void 0 ? void 0 : record.continuationKey;
+            if (continuationKey !== undefined && continuationKey !== null) {
+                yield this.nudgeStore.clear(continuationKey);
+            }
             yield this.interruptActiveTurn(sessionId);
             return hadWork;
         });
     }
+    isContinuationBusy(channelId, continuationToken) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let existing = yield this.sessions.findByContinuation(channelId, continuationToken);
+            if (existing === undefined) {
+                existing = yield this.restoreSessionByContinuation(channelId, continuationToken);
+            }
+            if (existing === undefined) {
+                return false;
+            }
+            return this.isTurnRunning(existing.sessionId);
+        });
+    }
+    /**
+     * Last agent-posted Slack message ts for warm `<slack_thread_delta>`, from
+     * the session's channel state when present.
+     */
+    getContinuationLastBotMessageTs(channelId, continuationToken) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let existing = yield this.sessions.findByContinuation(channelId, continuationToken);
+            if (existing === undefined) {
+                existing = yield this.restoreSessionByContinuation(channelId, continuationToken);
+            }
+            if (existing === undefined) {
+                return undefined;
+            }
+            const state = existing.channelState;
+            if (state === null || state === undefined || typeof state !== "object") {
+                return undefined;
+            }
+            const ts = state.lastBotMessageTs;
+            return typeof ts === "string" && ts.trim() !== "" ? ts.trim() : undefined;
+        });
+    }
+    interruptContinuation(channelId, continuationToken) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let existing = yield this.sessions.findByContinuation(channelId, continuationToken);
+            if (existing === undefined) {
+                existing = yield this.restoreSessionByContinuation(channelId, continuationToken);
+            }
+            if (existing === undefined) {
+                return false;
+            }
+            return this.interrupt(existing.sessionId);
+        });
+    }
     /**
      * Local harness cwd for a session: per-send override, else
      * `<agent.local.cwd>/<sessionId>`, else the durable session workspace.
@@ -530,7 +726,15 @@ export class SessionEngine {
                         return rest;
                     });
                 }
-                const request = this.buildTurnRequest(record, agent, turnId, message, isFirstTurn, emit, (update) => __awaiter(this, void 0, void 0, function* () {
+                // The harness only loads the scaffolded AGENTS.md when the session
+                // workspace is its own project root. With a per-session cwd override
+                // (PR worktree) the scaffold lands elsewhere, and a workspace nested
+                // inside a git repo re-roots harness rules at that repo — in both
+                // cases deliver instructions inline on the first turn instead.
+                const instructionsInvisibleToHarness = isFirstTurn &&
+                    (record.workspaceOverride !== undefined ||
+                        (yield isNestedInGitRepo(harnessCwd)));
+                const request = this.buildTurnRequest(record, agent, turnId, message, isFirstTurn, instructionsInvisibleToHarness, emit, (update) => __awaiter(this, void 0, void 0, function* () {
                     mapper.handleUpdate(update);
                     // Yield so the HTTP NDJSON writer can flush tool start/result
                     // events while sibling parallel tools are still executing.
@@ -601,9 +805,8 @@ export class SessionEngine {
             return Object.assign(Object.assign(Object.assign({}, outcome), (finalResult === undefined ? {} : { result: finalResult })), (finalUsage === undefined ? {} : { usage: finalUsage }));
         });
     }
-    buildTurnRequest(record, agent, turnId, prompt, isFirstTurn, emit, onUpdate, signal) {
-        var _a, _b, _c;
-        var _d;
+    buildTurnRequest(record, agent, turnId, prompt, isFirstTurn, instructionsInvisibleToHarness, emit, onUpdate, signal) {
+        var _a, _b;
         // Per-session cloud attach (channel/tool handoff) forces cloud runtime
         // even when the agent defaults to local for chat server tools.
         const runtime = resolveSessionRuntime({
@@ -626,15 +829,22 @@ export class SessionEngine {
             });
             turnPrompt = `${contextBlock}\n\n${prompt}`;
         }
-        if (runtime === "cloud" && isFirstTurn) {
-            const preamble = [
-                (_d = (_c = agent.instructions) === null || _c === void 0 ? void 0 : _c.trim()) !== null && _d !== void 0 ? _d : "",
-                buildIdentitySection(agent),
-                buildAgentToolsCatalog(agent.tools, { includeScripts: true }),
-            ]
-                .filter((part) => part !== "")
-                .join("\n\n");
-            turnPrompt = `${preamble}\n\n${turnPrompt}`;
+        if (isFirstTurn) {
+            if (runtime === "cloud") {
+                // Cloud VMs have no materialized workspace: ship the full context,
+                // including agent tool script bodies.
+                const preamble = buildAgentsMdContent(agent, { includeScripts: true });
+                turnPrompt = `${preamble}\n\n${turnPrompt}`;
+            }
+            else if (instructionsInvisibleToHarness) {
+                // Local workspace whose AGENTS.md the harness will not load. With a
+                // per-session harness cwd override, agent tool scripts live only in
+                // the durable scaffold dir — embed bodies like cloud. Otherwise the
+                // catalog can reference on-disk paths under the harness cwd.
+                const includeScripts = record.workspaceOverride !== undefined;
+                const preamble = buildAgentsMdContent(agent, { includeScripts });
+                turnPrompt = `${preamble}\n\n${turnPrompt}`;
+            }
         }
         return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId }, (record.sdkAgentId === undefined
             ? {}
@@ -1128,15 +1338,20 @@ export class SessionEngine {
             var _a;
             // Drain admission first so pendingTurns → activeTurns is visible before we
             // decide the session is idle (reminders use this for queueBehindTurn).
-            const chain = this.admissionChains.get(sessionId);
-            if (chain !== undefined) {
-                yield chain.catch(() => { });
-            }
-            const active = this.activeTurns.get(sessionId);
-            if (active !== undefined) {
-                return active;
+            // The active lifecycle promise also awaits coalesce drain + the drained
+            // follow-up's admission, so Slack coalesced waiters see the resume turn.
+            for (;;) {
+                const chain = this.admissionChains.get(sessionId);
+                if (chain !== undefined) {
+                    yield chain.catch(() => { });
+                }
+                const active = this.activeTurns.get(sessionId);
+                if (active !== undefined) {
+                    yield active;
+                    continue;
+                }
+                return (_a = this.lastOutcomes.get(sessionId)) !== null && _a !== void 0 ? _a : { status: "finished" };
             }
-            return (_a = this.lastOutcomes.get(sessionId)) !== null && _a !== void 0 ? _a : { status: "finished" };
         });
     }
     /**
@@ -1275,25 +1490,20 @@ export class SessionEngine {
         });
     }
     isTurnRunning(sessionId) {
-        // Include the admit window (pendingTurns) so busy policies do not treat a
-        // turn that has been accepted but not yet marked active as idle.
-        return this.activeTurns.has(sessionId) || this.pendingTurns.has(sessionId);
+        // Include the admit window (pendingTurns) and coalesce drain so busy
+        // policies do not treat a turn that has finished executeTurn but not yet
+        // resumed queued follow-ups as idle (avoids clearCoalesced races).
+        return (this.activeTurns.has(sessionId) ||
+            this.pendingTurns.has(sessionId) ||
+            this.coalesceDrains.has(sessionId));
     }
     sessionInfo(record) {
         return Object.assign(Object.assign(Object.assign({ id: record.sessionId, channelId: record.channelId, mode: record.mode, purpose: record.purpose === "eval" ? "eval" : "live", auth: record.auth, continuationKey: record.continuationKey }, (record.abs === undefined ? {} : { abs: record.abs })), (record.title === undefined ? {} : { title: record.title })), (record.sdkAgentId === undefined
             ? {}
             : { sdkAgentId: record.sdkAgentId }));
     }
-    channelSession(sessionId, record, isNew) {
-        return {
-            id: sessionId,
-            continuationToken: record.continuationKey,
-            isNew,
-            info: this.sessionInfo(record),
-            getEventStream: (options) => { var _a; return this.eventStream(sessionId, (_a = options === null || options === void 0 ? void 0 : options.startIndex) !== null && _a !== void 0 ? _a : 0); },
-            waitForCompletion: () => this.waitForCompletion(sessionId),
-            setContinuationToken: (token) => this.setContinuationToken(sessionId, token),
-        };
+    channelSession(sessionId, record, isNew, coalesced = false) {
+        return Object.assign(Object.assign({ id: sessionId, continuationToken: record.continuationKey, isNew }, (coalesced ? { coalesced: true } : {})), { info: this.sessionInfo(record), getEventStream: (options) => { var _a; return this.eventStream(sessionId, (_a = options === null || options === void 0 ? void 0 : options.startIndex) !== null && _a !== void 0 ? _a : 0); }, waitForCompletion: () => this.waitForCompletion(sessionId), setContinuationToken: (token) => this.setContinuationToken(sessionId, token) });
     }
     resolveChannelId(channel) {
         if (typeof channel === "string") {

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

@@ -16,7 +16,7 @@
  */
 import type { ABMetricSample } from "../ab.js";
 import { type ResolvedStoragePolicy, type StorageContext, type StorageDefinition } from "../storage.js";
-import type { SessionEvent, SessionRecord } from "../types.js";
+import type { JsonValue, SessionEvent, SessionRecord } from "../types.js";
 import type { ABSnapshot } from "./ab-snapshot.js";
 import type { EvalRunStorage } from "./eval-run-store.js";
 import { type ReminderRecord } from "./reminder-store.js";
@@ -106,6 +106,23 @@ export declare class StorageCoordinator {
      * disk). Errors read as empty — same posture as session bulk restore.
      */
     listReminders(): Promise<ReminderRecord[]>;
+    /**
+     * Whether the sink can serve awaited author reads/writes (`get` is
+     * required — `put` is always present on {@link StorageConfig}).
+     */
+    get supportsAuthorKv(): boolean;
+    /**
+     * Awaited author KV read. Unlike framework session mirrors, this awaits
+     * the sink and propagates errors — handlers need read-after-write.
+     */
+    kvGet(authorKey: string): Promise<JsonValue | undefined>;
+    /**
+     * Awaited author KV write. Goes straight to the sink (not the
+     * at-most-once delivery queue) so callers observe durable success/failure.
+     */
+    kvPut(authorKey: string, value: JsonValue): Promise<void>;
+    /** Awaited author KV delete. No-op when the sink omits `delete`. */
+    kvDelete(authorKey: string): Promise<void>;
     /**
      * Adapter over the sink's dedicated `evals` table for the playground
      * eval-run store. Undefined when the table is not configured — eval

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

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

package/dist/internal/storage-coordinator.js

@@ -292,6 +292,49 @@ export class StorageCoordinator {
         });
     }
     // ==========================================================================
+    // Author KV ({@link HostContext.kv})
+    // ==========================================================================
+    /**
+     * Whether the sink can serve awaited author reads/writes (`get` is
+     * required — `put` is always present on {@link StorageConfig}).
+     */
+    get supportsAuthorKv() {
+        return this.definition.get !== undefined;
+    }
+    /**
+     * Awaited author KV read. Unlike framework session mirrors, this awaits
+     * the sink and propagates errors — handlers need read-after-write.
+     */
+    kvGet(authorKey) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const get = this.definition.get;
+            if (get === undefined) {
+                throw new Error("storage get is not configured");
+            }
+            const key = storageKeys.kv(this.agentName, authorKey);
+            // Preserve stored JSON `null` (distinct from a missing key).
+            return yield get(key, this.context("restore"));
+        });
+    }
+    /**
+     * Awaited author KV write. Goes straight to the sink (not the
+     * at-most-once delivery queue) so callers observe durable success/failure.
+     */
+    kvPut(authorKey, value) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const key = storageKeys.kv(this.agentName, authorKey);
+            yield this.definition.put(key, value, this.context("policy"));
+        });
+    }
+    /** Awaited author KV delete. No-op when the sink omits `delete`. */
+    kvDelete(authorKey) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const key = storageKeys.kv(this.agentName, authorKey);
+            yield (_b = (_a = this.definition).delete) === null || _b === void 0 ? void 0 : _b.call(_a, key, this.context("policy"));
+        });
+    }
+    // ==========================================================================
     // Evals (dedicated `evals` table)
     // ==========================================================================
     /**

package/dist/internal/workspace.d.ts

@@ -38,6 +38,25 @@ export declare function withIdentityPreamble(name: string, instructions: string
 export declare function buildAgentToolsCatalog(tools: DiscoveredTool[], options?: {
     includeScripts: boolean;
 }): string;
+/**
+ * The full AGENTS.md-equivalent context for an agent: instructions, identity
+ * section, and the agent-side tool catalog. Written to the session workspace
+ * as `AGENTS.md`, and inlined into the first turn's prompt when the harness
+ * cannot discover that file (cloud runtime, or a local workspace the harness
+ * will not treat as the project root — see {@link isNestedInGitRepo}).
+ */
+export declare function buildAgentsMdContent(agent: ResolvedAgent, options: {
+    includeScripts: boolean;
+}): string;
+/**
+ * True when `dir` sits strictly inside a git repository (a `.git` exists in
+ * an ancestor directory but not in `dir` itself). The Cursor harness resolves
+ * its project root by walking up to the nearest git root, so a nested session
+ * workspace loses its own `AGENTS.md` / `.cursor` scaffold: the enclosing
+ * repo's rules load instead, and the (necessarily gitignored) workspace files
+ * are skipped by nested rule discovery.
+ */
+export declare function isNestedInGitRepo(dir: string): Promise<boolean>;
 export declare function materializeWorkspace(options: MaterializeWorkspaceOptions): Promise<void>;
 /**
  * Generate the SKILL.md the harness reads: `name` + `description`

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

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;CACf;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA6CR;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAqCf;AAmDD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;CACf;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA6CR;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAAE,GACnC,MAAM,CAUR;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcrE;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAmDD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAMf"}