fix(sessions): keep session results current during cold reads (#156121)

* fix(sessions): prepare projection reads before consumption

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>

* fix(sessions): close prepared read authorization gaps

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>

* fix(sessions): bind prepared PR reads to selection

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>

* fix(sessions): fence PR updates to current viewers

Recheck watcher membership after prepared reads, validate each recipient against its own target, and keep one revoked viewer from blocking other recipients. Exercise the four publication races and migrate archived test reads to explicit preparation.

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>

* fix(sessions): keep shared PR fetches reader-bound

Authorize shared pull-request fetches through any surviving prepared viewer, retain per-recipient publication guards, and update the current-main placement fixture contract.

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>

* test: await subagent and model catalog completion

Replace polling deadlines with owned completion joins and real FIFO or snapshot event signals. Preserve durable state, delivery, transcript, queue-depth, and model-scope assertions without widening timeouts.

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>

* test(gateway): await resumed subagent completion

Join the actual announcement and its owned root work before asserting resumed task completion. Preserve authorization, input custody, exact delivery counts, and cancellation-aware cleanup without extending polling deadlines.

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>

* fix(sessions): refresh retained worker schema admission

Await the existing coalesced schema-probe boundary before the next retained worker read. Preserve the synchronous scope API and keep the native connection while rejecting foreign unsupported schemas. Add deterministic registered-handler coverage and update the sibling scope fixture.

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>

* fix(gateway): reuse owned placement facts during materialization

Adopt a still-current completed read snapshot when its exact row becomes resident. Keep the existing batch lifetime, invalidation fences, and capacity limits. Cover valid reuse and invalidation before registration without weakening the registered burst assertions.

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>

* test(gateway): retain relay database cleanup in the host process

Route the real native-database relay fixture through the existing gateway database-worker fork owner. Preserve the fixture and production host-broker guard instead of running native retirement inside a Vitest thread.

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>

* fix(sessions): follow per-read schema admission

Retire the branch-only probe-turn import, wrapper, worker wait, and mock after upstream 57f912b5f7 removed turn-coalesced schema freshness. Keep the registered worker regression on a real retained connection and require foreign changes to be observed without advancing a scheduled turn.

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>

* test(agents): observe foreign maintenance startup

Await the foreign hook start signal while preserving its release gate. Keep caller-memory independence, task-list stability, call counts, and terminal-settlement assertions unchanged after async task admission.

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>

* fix(sessions): settle prepared read delivery lifetimes

Track successful PR snapshot delivery per viewer and bind forced-refresh
acknowledgments to the requesting generations joined by each shared load.
Settle inactive admissions and retire disconnected replacement generations
without reviving an earlier use of the same connection ID.

Present embedded history metadata inside its prepared consuming frame and
preserve the CI-details recovery response when a session or grant changes.
Add deterministic lifecycle regressions and join setup hydration before
asserting forced-refresh delivery.

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>

* fix(sessions): preserve cold group access and event publication

Authorize group defaults from committed sharing metadata and physical-store membership without warming archived rows. Preserve zero-argument publication while preparing exact event rows and ancestors.

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>

* fix(update): import npm pack step results from their owner

Repair the stale type-only import reported by the CI build, production/test typechecks, lint preparation and extension boundary jobs. Runtime update behavior is unchanged.

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>

---------

Co-authored-by: galiniliev <5711535+galiniliev@users.noreply.github.com>
This commit is contained in:
Galin Iliev 2026-09-24 17:18:03 -07:00 • committed by GitHub
parent 516b1f8c4a
commit 0bbad56fa8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
47 changed files with 2219 additions and 526 deletions

View file

@ -6,6 +6,7 @@ import {
replaceTranscriptEvents,
} from "../../config/sessions/session-accessor.js";
import type { ContextEngine } from "../../context-engine/types.js";
import { racePromiseWithAbortSignal } from "../../infra/abort-signal.js";
import { resetCommandQueueStateForTest } from "../../process/command-queue.test-support.js";
import { onSessionTranscriptUpdate } from "../../sessions/transcript-events.js";
import { createDeferredCore } from "../../shared/deferred.js";
@ -232,9 +233,9 @@ describe("context-engine maintenance transcript ownership", () => {
},
);
it.each(modes)(
it.for(modes)(
"does not coalesce or wait for foreign durable work with executionMode=%s",
async (executionMode) => {
async (executionMode, { signal }) => {
await withTranscriptOwners(async ({ memory, durable, params, target }) => {
const release = createDeferredCore();
const foreignStarted = createDeferredCore();
@ -252,7 +253,10 @@ describe("context-engine maintenance transcript ownership", () => {
});
let run: Promise<unknown> | undefined;
try {
await Promise.race([foreignStarted.promise, ...deferred]);
await racePromiseWithAbortSignal(
Promise.race([foreignStarted.promise, ...deferred]),
signal,
);
expect(foreignMaintain).toHaveBeenCalledOnce();
const tasksBefore = listTasksForOwnerKey(target.sessionKey);
const maintain = vi.fn(async () => ({

View file

@ -28,5 +28,5 @@ export { readChatHistoryPage } from "../../gateway/server-methods/chat-history-p
export { capArrayByJsonBytes } from "../../gateway/session-transcript-readers.js";
export { listProjectedSessions } from "../../gateway/session-utils-list.js";
export { loadGatewaySessionEntryReadOnly as loadSessionEntry } from "../../gateway/session-utils-store.js";
export { resolveSessionKeyFromResolveParams } from "../../gateway/sessions-resolve.js";
export { withPreparedSessionResolve } from "../../gateway/sessions-resolve.js";
export type { SessionsListResult } from "../../gateway/session-utils.types.js";

View file

@ -54,7 +54,13 @@ const runtime = vi.hoisted(() => ({
),
}));
vi.mock("./embedded-gateway-stub.runtime.js", () => runtime);
vi.mock("./embedded-gateway-stub.runtime.js", () => ({
...runtime,
withPreparedSessionResolve: async (
params: unknown,
consume: (result: import("../../gateway/sessions-resolve.js").SessionsResolveResult) => unknown,
) => consume(runtime.resolveSessionKeyFromResolveParams(params)),
}));
describe("embedded gateway stub", () => {
// The stub forwards this owner to the mocked shared operations without inspecting its rows.

View file

@ -74,21 +74,25 @@ async function handleSessionsList(params: Record<string, unknown>) {
async function handleSessionsResolve(params: Record<string, unknown>) {
const rt = await getRuntime();
const resolved = rt.resolveSessionKeyFromResolveParams({
projection: await borrowSessionRowProjection(),
client: null,
p: params as SessionsResolveParams,
});
if (!resolved.ok) {
throw new Error(resolved.error.message);
}
if ("missing" in resolved) {
return { ok: false };
}
if ("ambiguous" in resolved) {
return { ok: false, candidates: resolved.candidates };
}
return { ok: true, key: resolved.key, agentId: resolved.agentId };
return await rt.withPreparedSessionResolve(
{
projection: await borrowSessionRowProjection(),
client: null,
p: params as SessionsResolveParams,
},
(resolved) => {
if (!resolved.ok) {
throw new Error(resolved.error.message);
}
if ("missing" in resolved) {
return { ok: false };
}
if ("ambiguous" in resolved) {
return { ok: false, candidates: resolved.candidates };
}
return { ok: true, key: resolved.key, agentId: resolved.agentId };
},
);
}
async function handleSessionsSearch(params: Record<string, unknown>) {

View file

@ -0,0 +1,103 @@
import { expect, it, vi } from "vitest";
import { racePromiseWithAbortSignal } from "../../infra/abort-signal.js";
import * as nodeSqlite from "../../infra/node-sqlite.js";
import { closeOpenClawAgentDatabaseByPathAsync } from "../../state/openclaw-agent-db-lifecycle.js";
import { openOpenClawAgentDatabase } from "../../state/openclaw-agent-db.js";
import { withOpenClawTestState } from "../../test-utils/openclaw-test-state.js";
import { replaceSessionEntrySync } from "./session-accessor.js";
import type { SessionTranscriptWorkerInput } from "./session-transcript-worker.types.js";
const worker = vi.hoisted(() => ({
read: vi.fn<(input: SessionTranscriptWorkerInput) => Promise<unknown>>(),
close: vi.fn<(key?: string) => void>(),
}));
vi.mock("../../infra/worker-task-server.js", async (importOriginal) => ({
...(await importOriginal<typeof import("../../infra/worker-task-server.js")>()),
serveOwnedWorkerTasks(
handler: (input: unknown) => Promise<unknown>,
options: { closeResource: (key?: string) => void },
) {
worker.read.mockImplementation(handler);
worker.close.mockImplementation(options.closeResource);
},
}));
import "./session-transcript.worker.js";
it.for([
{ change: "newer schema", sql: "PRAGMA user_version = 999", error: /newer schema version/ },
{
change: "missing table",
sql: "DROP TABLE session_nodes",
error: /Session metadata unavailable.*table-missing/,
},
{
change: "ordinary commit",
sql: "UPDATE schema_meta SET updated_at = updated_at + 1 WHERE meta_key = 'primary'",
error: undefined,
},
])(
"revalidates a warm worker listing after a foreign $change",
async ({ sql, error }, { signal }) => {
await withOpenClawTestState({ scenario: "minimal" }, async (state) => {
const options = { agentId: "main", env: state.env };
const { path } = openOpenClawAgentDatabase(options);
const sessionKey = "agent:main:main";
replaceSessionEntrySync(
{ ...options, sessionKey },
{ sessionId: "retained-listing", updatedAt: 1 },
);
// The registered handler must use its real retained read-only scope, not a host writer.
await closeOpenClawAgentDatabaseByPathAsync(path);
const database = { agentId: "main", path };
const request: SessionTranscriptWorkerInput = {
kind: "session-entry-list",
database,
scope: { ...options, storePath: path, projection: "list" },
};
const expected = {
ok: true,
value: {
kind: "session-entry-list",
entries: [{ sessionKey, entry: { sessionId: "retained-listing" } }],
},
};
const opens = vi.spyOn(nodeSqlite, "openNodeSqliteDatabase");
const countOpens = () => opens.mock.calls.filter(([filename]) => filename === path).length;
// Foreign commits must be visible on the next read without a scheduled turn.
// Native SQLite and the retained reader remain real.
vi.useFakeTimers({ toFake: ["setImmediate"] });
let pending: Promise<unknown> | undefined;
try {
pending = worker.read(request);
await expect(racePromiseWithAbortSignal(pending, signal)).resolves.toMatchObject(expected);
expect(countOpens()).toBe(1);
// A raw native peer reproduces a different worker/process: no local schema publication.
const writer = new (nodeSqlite.requireNodeSqlite().DatabaseSync)(path);
try {
writer.exec(sql);
} finally {
writer.close();
}
pending = worker.read(request);
const result = await racePromiseWithAbortSignal(pending, signal);
if (error) {
expect(result).toMatchObject({
ok: false,
error: { kind: "read-error", message: expect.stringMatching(error) },
});
} else {
expect(result).toMatchObject(expected);
}
// Refresh the retained admission, rather than hiding the bug with a cold reader.
expect(countOpens()).toBe(1);
} finally {
vi.runOnlyPendingTimers();
await Promise.allSettled([pending]);
vi.useRealTimers();
vi.restoreAllMocks();
worker.close(JSON.stringify([{ path }]));
}
});
},
);

View file

@ -16,6 +16,7 @@ import {
captureStateDatabaseCoordinatorRuntime,
withStateDatabaseCoordinatorRuntimeDirectory,
} from "../infra/state-database-coordinator.js";
import { sessionChanges } from "../sessions/session-row-changes.js";
import { AsyncWorkScope } from "../shared/async-work-scope.js";
import { createDeferredCore } from "../shared/deferred.js";
import { closeOpenClawAgentDatabaseByPathAsync } from "../state/openclaw-agent-db.js";
@ -72,7 +73,11 @@ afterAll(async () => {
await sharedState?.cleanup();
});
async function createFixture(scope: OperatorScope, useDefaultLoader = false) {
async function createFixture(
scope: OperatorScope,
useDefaultLoader = false,
initialSessionPatch: Partial<SessionEntry> = {},
) {
const fixtureId = ++fixtureSequence;
const readerEmail = `guest-publication-reader-${fixtureId}@example.test`;
const profile = ensureProfileForEmail(readerEmail);
@ -111,7 +116,7 @@ async function createFixture(scope: OperatorScope, useDefaultLoader = false) {
},
);
};
await seed(sessionKey);
await seed(sessionKey, profile.id, initialSessionPatch);
const connections = createGatewayConnectionState({
bootId: "publication-read",
cfg,
@ -143,10 +148,10 @@ async function createFixture(scope: OperatorScope, useDefaultLoader = false) {
const subscriptions = createControlUiSessionPullRequestSubscriptions({
broadcastToConnIds: connections.broadcastToConnIds,
isConnectionActive: connections.isConnectionActive,
prepareRead: (connId, session) => {
prepareRead: async (connId, session) => {
const client = connections.clients.getByConnectionId(connId);
return client
? prepareControlUiSessionPrRead({
? await prepareControlUiSessionPrRead({
client,
...session,
getRuntimeConfig,
@ -249,10 +254,11 @@ async function withFixture(
scope: OperatorScope,
run: (fixture: Awaited<ReturnType<typeof createFixture>>) => Promise<void>,
isolated = false,
initialSessionPatch: Partial<SessionEntry> = {},
) {
if (isolated) {
return withOpenClawTestState({ scenario: "minimal" }, async () => {
const fixture = await createFixture(scope);
const fixture = await createFixture(scope, false, initialSessionPatch);
try {
await run(fixture);
} finally {
@ -270,7 +276,7 @@ async function withFixture(
let fixture: Awaited<ReturnType<typeof createFixture>> | undefined;
try {
await work.track(async () => {
fixture = await createFixture(scope);
fixture = await createFixture(scope, false, initialSessionPatch);
try {
await run(fixture);
} finally {
@ -304,6 +310,30 @@ function expectedFrame(key: string, value: ControlUiSessionPullRequests = snapsh
}
describe("registered session PR subscriptions", () => {
it("delivers an archived session that was cold at Gateway startup", async () => {
await withFixture(
"operator.read",
async (f) => {
const entered = createDeferredCore();
f.load.mockImplementationOnce(async () => {
entered.resolve();
return snapshot;
});
await f.subscribe();
await entered.promise;
await f.subscriptions.pollNow();
expect(f.load).toHaveBeenCalledWith(
{ sessionKey, agentId: "main" },
expect.any(AbortSignal),
expect.objectContaining({ assertCurrent: expect.any(Function) }),
);
expect(frames(f.socket)).toContainEqual(expectedFrame(sessionKey));
},
false,
{ archivedAt: 1 },
);
});
it.each(["operator.read", "operator.write", "operator.admin"] as const)(
"delivers the owned branch through the real broadcaster with %s",
async (scope) => {
@ -401,6 +431,8 @@ describe("registered session PR subscriptions", () => {
if (delayed) {
await f.subscriptions.replace(f.client.connId!, [sessionKey], new Set([sessionKey]));
await f.subscribe([sessionKey], peer.client);
// Admission precedes hydration; join the retained cell before measuring refresh delivery.
await f.subscriptions.replace(peer.client.connId!, [sessionKey]);
f.load.mockClear();
f.socket.send.mockClear();
peer.socket.send.mockClear();
@ -430,6 +462,10 @@ describe("registered session PR subscriptions", () => {
if (delayed) {
await vi.advanceTimersByTimeAsync(10_000);
await entered.promise;
expect(
frames(peer.socket),
"no refresh result before the held loader settles",
).toEqual([]);
}
held.resolve(snapshot);
await Promise.all([f.subscriptions.pollNow(), ...refreshes]);
@ -490,8 +526,62 @@ describe("registered session PR subscriptions", () => {
});
describe("registered session PR check details", () => {
it("reads archived check details after archive cache invalidation", async () => {
await withFixture(
"operator.read",
async (f) => {
const projection = getSessionRowProjection(f.context);
if (!projection) {
throw new Error("Missing session projection for archived PR checks");
}
expect(projection.snapshot({ agentId: "main", key: sessionKey }).row).toBeDefined();
sessionChanges.emit({ all: true, scope: "catalog" });
await projection.ensureMaterialized();
expect(
projection.capture({ agentId: "main", key: sessionKey })?.materialized,
).toBeUndefined();
const result: ControlUiSessionPullRequestCheckDetails = {
owner: "synthetic",
repo: "publication",
number: 1,
headSha: "a".repeat(40),
status: "ready",
rateLimited: false,
checks: [],
};
const load = vi.fn(async () => result);
const respond = vi.fn();
await handleGatewayRequest({
req: {
type: "req",
id: "archived-checks",
method: "controlUi.sessionPullRequests.checks",
params: {
sessionKey,
owner: result.owner,
repo: result.repo,
number: result.number,
headSha: result.headSha,
},
},
client: f.client,
context: f.context,
extraHandlers: createControlUiHandlers(undefined, undefined, load),
isWebchatConnect: () => false,
respond,
});
expect(load).toHaveBeenCalledOnce();
expect(respond).toHaveBeenCalledExactlyOnceWith(true, result, undefined);
},
false,
{ archivedAt: 1 },
);
});
it.each([
...readerChanges,
"selection",
"literal-global",
"literal-global-visibility",
"store closure",
@ -505,6 +595,12 @@ describe("registered session PR check details", () => {
if (change === "literal-global-visibility") {
await f.seed("global", f.profile.id, { sessionId: "separate-global-row" });
}
const replacementKey = `${key}:replacement`;
const projection = getSessionRowProjection(f.context);
if (change === "selection") {
await f.seed(replacementKey, f.other.id);
await projection?.ensureMaterialized();
}
const mutation =
change === "literal-global"
? "unchanged"
@ -559,6 +655,16 @@ describe("registered session PR check details", () => {
const source = loadGatewaySessionEntryReadOnly(key, { agentId: "main" }).readSource;
expect(source).toBeDefined();
await closeOpenClawAgentDatabaseByPathAsync(source!.path);
} else if (mutation === "selection") {
if (!projection) {
throw new Error("Missing session projection for selection replacement");
}
const capture = projection.capture.bind(projection);
const replacement = capture({ agentId: "main", key: replacementKey });
expect(replacement).toBeDefined();
vi.spyOn(projection, "capture").mockImplementation((query) =>
query.key === key ? replacement : capture(query),
);
} else {
await f.changeReader(mutation, key);
}
@ -567,7 +673,14 @@ describe("registered session PR check details", () => {
expect(respond).toHaveBeenCalledExactlyOnceWith(
mutation === "unchanged",
mutation === "unchanged" ? result : undefined,
mutation === "unchanged" ? undefined : expect.objectContaining({ code: "UNAVAILABLE" }),
mutation === "unchanged"
? undefined
: expect.objectContaining({
code: "UNAVAILABLE",
...(mutation === "store closure"
? {}
: { message: "Session changed; reopen CI details" }),
}),
);
} finally {
held.resolve(result);

View file

@ -16,6 +16,7 @@ import { READ_SCOPE } from "./operator-scopes.js";
import { isGatewayClientProfilePending } from "./server-methods/gateway-client-identity.js";
import type { GatewayClient } from "./server-methods/types.js";
import { resolveRequestedSessionAgentId } from "./session-request-agent.js";
import { withReadySessionRows, type SessionRowReadView } from "./session-row-prepared-read.js";
import type { SessionRowProjection } from "./session-row-projection.js";
import { createSessionListEntryFilter } from "./session-sharing.js";
import type { loadGatewaySessionEntryReadOnly } from "./session-utils-store.js";
@ -31,6 +32,7 @@ export type ControlUiSessionPrTarget = {
identity: string;
readSource: { agentId: string; path: string };
source: string | GitCheckoutContext | null;
assertCurrent?: () => void;
};
export type ControlUiSessionPrReadContext = {
@ -84,17 +86,17 @@ export function resolveControlUiSessionPrTarget(
};
}
export type ControlUiSessionPrRead = () => ControlUiSessionPrTarget | undefined;
export type ControlUiSessionPrRead = () => Promise<ControlUiSessionPrTarget | undefined>;
/** A watcher may follow a replaced target, but never a replacement person or access grant. */
export function prepareControlUiSessionPrRead(params: {
export async function prepareControlUiSessionPrRead(params: {
client: GatewayClient;
sessionKey: string;
agentId?: string;
getRuntimeConfig: () => OpenClawConfig;
getSessionRowProjection: () => SessionRowProjection | undefined;
isCurrentClient: () => boolean;
}): ControlUiSessionPrRead | undefined {
}): Promise<ControlUiSessionPrRead | undefined> {
const {
client,
sessionKey,
@ -112,7 +114,7 @@ export function prepareControlUiSessionPrRead(params: {
const access = client.internal?.operatorAccessAuthority;
const connectionSignal = client.connectionSignal;
let aliasRevision = -1;
const readCurrent = () => {
const captureCurrent = (projection: SessionRowProjection) => {
try {
const currentActor = resolveGatewayOperatorRoleActor(client);
if (
@ -154,8 +156,7 @@ export function prepareControlUiSessionPrRead(params: {
if (!requested.ok) {
return undefined;
}
const projection = getSessionRowProjection();
if (!projection) {
if (getSessionRowProjection() !== projection) {
return undefined;
}
const query = { key: sessionKey, agentId: requested.agentId };
@ -167,15 +168,25 @@ export function prepareControlUiSessionPrRead(params: {
) {
return undefined;
}
return { cfg, query, selected };
} catch {
return undefined;
}
};
const readPreparedCurrent = (
read: SessionRowReadView,
captured: NonNullable<ReturnType<typeof captureCurrent>>,
) => {
try {
// Authorize transient private rows before preparing presentation; resident rows reuse it.
const current = projection.describe(query, selected);
const current = read.describe(captured.query, captured.selected);
const storePath = current?.storeTarget.storePath;
if (!current || !storePath) {
return undefined;
}
return resolveControlUiSessionPrTarget(
{
cfg,
cfg: captured.cfg,
agentId: current.agentId,
canonicalKey: current.key,
storePath,
@ -188,5 +199,47 @@ export function prepareControlUiSessionPrRead(params: {
return undefined;
}
};
return readCurrent() ? readCurrent : undefined;
const readCurrent: ControlUiSessionPrRead = async () => {
try {
const projection = getSessionRowProjection();
if (!projection) {
return undefined;
}
const target = await withReadySessionRows(
projection,
(cfg) => {
const requested = resolveRequestedSessionAgentId(cfg, sessionKey, agentId);
return requested.ok ? [{ key: sessionKey, agentId: requested.agentId }] : [];
},
(read) => {
const captured = captureCurrent(projection);
if (!captured) {
return undefined;
}
const preparedTarget = readPreparedCurrent(read, captured);
return preparedTarget
? { target: preparedTarget, captured: captured.selected }
: undefined;
},
);
return target
? {
...target.target,
assertCurrent: () => {
const current = captureCurrent(projection);
if (
!current ||
current.selected !== target.captured ||
!projection.isCurrent(target.captured)
) {
throw new Error("Session pull-request target changed");
}
},
}
: undefined;
} catch {
return undefined;
}
};
return (await readCurrent()) ? readCurrent : undefined;
}

View file

@ -0,0 +1,617 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { createDeferred } from "../../test/helpers/promise.js";
import type { ControlUiSessionPullRequests } from "./control-ui-contract.js";
import type { ControlUiSessionPrTarget } from "./control-ui-session-pr-read.js";
import { createTestControlUiSessionPrSubscriptions } from "./control-ui-session-pr-subscriptions.test-support.js";
const CHANGED_EVENT = "controlUi.sessionPullRequests.changed";
const READY: ControlUiSessionPullRequests = { pullRequests: [], rateLimited: false };
let active: ReturnType<typeof createTestControlUiSessionPrSubscriptions> | undefined;
afterEach(async () => {
await active?.stop();
active = undefined;
vi.useRealTimers();
});
describe("recipient publication lifetimes", () => {
const target: ControlUiSessionPrTarget = {
params: { sessionKey: "shared", agentId: "main" },
identity: "shared",
readSource: { agentId: "main", path: "unused" },
source: null,
};
const changed: ControlUiSessionPullRequests = { ...READY, rateLimited: true };
const changedSessions = {
shared: { ...changed, status: "rate-limited" },
};
it("retries an unchanged snapshot missed during recipient preparation without duplicating delivery", async () => {
vi.useFakeTimers();
const entered = createDeferred();
const release = createDeferred();
let generation = 0;
let holdRecipient = false;
let snapshot = READY;
const broadcastToConnIds = vi.fn();
active = createTestControlUiSessionPrSubscriptions({
broadcastToConnIds,
load: async () => snapshot,
prepareRead: async (connId) => async () => {
const captured = generation;
const prepared = {
...target,
assertCurrent: () => {
if (captured !== generation) {
throw new Error("Prepared selection changed");
}
},
};
if (connId === "recipient" && holdRecipient) {
holdRecipient = false;
entered.resolve();
await release.promise;
}
return prepared;
},
});
await active.replace("first", ["shared"]);
await active.replace("recipient", ["shared"]);
broadcastToConnIds.mockClear();
broadcastToConnIds.mockImplementationOnce(() => {
holdRecipient = true;
});
snapshot = changed;
const poll = active.pollNow();
try {
await entered.promise;
generation++;
release.resolve();
await poll;
expect(broadcastToConnIds).toHaveBeenCalledExactlyOnceWith(
CHANGED_EVENT,
{ sessions: changedSessions },
new Set(["first"]),
{ sessionKeys: ["shared"], agentId: "main" },
);
await active.pollNow();
expect(broadcastToConnIds.mock.calls).toEqual(
["first", "recipient"].map((connId) => [
CHANGED_EVENT,
{ sessions: changedSessions },
new Set([connId]),
{ sessionKeys: ["shared"], agentId: "main" },
]),
);
await active.pollNow();
expect(broadcastToConnIds).toHaveBeenCalledTimes(2);
} finally {
release.resolve();
await poll;
}
});
it("acknowledges a forced result equal to the normal poll queued before it", async () => {
vi.useFakeTimers();
const normalEntered = createDeferred();
const normalRelease = createDeferred();
const forcedEntered = createDeferred();
const forcedRelease = createDeferred();
const admitted = createDeferred();
let holdNormal = false;
const broadcastToConnIds = vi.fn();
active = createTestControlUiSessionPrSubscriptions({
broadcastToConnIds,
load: async ({ refresh }) => {
if (refresh) {
forcedEntered.resolve();
await forcedRelease.promise;
return changed;
}
if (holdNormal) {
normalEntered.resolve();
await normalRelease.promise;
return changed;
}
return READY;
},
});
await active.replace("first", ["shared"]);
await active.replace("recipient", ["shared"]);
broadcastToConnIds.mockClear();
holdNormal = true;
const poll = active.pollNow();
await normalEntered.promise;
const refresh = active.replace("first", ["shared"], new Set(["shared"]), admitted.resolve);
try {
await admitted.promise;
normalRelease.resolve();
await forcedEntered.promise;
expect(broadcastToConnIds).toHaveBeenCalledTimes(2);
forcedRelease.resolve();
await Promise.all([poll, refresh]);
expect(broadcastToConnIds.mock.calls).toEqual(
["first", "recipient", "first"].map((connId) => [
CHANGED_EVENT,
{ sessions: changedSessions },
new Set([connId]),
{ sessionKeys: ["shared"], agentId: "main" },
]),
);
} finally {
normalRelease.resolve();
forcedRelease.resolve();
await Promise.all([poll, refresh]);
}
});
it("acknowledges a refresh admitted after that viewer received the in-flight result", async () => {
vi.useFakeTimers();
const entered = createDeferred();
const release = createDeferred();
const admitted = createDeferred();
let holdRecipient = false;
const load = vi.fn(async ({ refresh }: { refresh?: boolean }) => (refresh ? changed : READY));
const broadcastToConnIds = vi.fn();
active = createTestControlUiSessionPrSubscriptions({
broadcastToConnIds,
load,
prepareRead: async (connId) => async () => {
if (connId === "recipient" && holdRecipient) {
holdRecipient = false;
entered.resolve();
await release.promise;
}
return target;
},
});
await active.replace("first", ["shared"]);
await active.replace("recipient", ["shared"]);
broadcastToConnIds.mockClear();
load.mockClear();
broadcastToConnIds.mockImplementationOnce(() => {
holdRecipient = true;
});
const first = active.replace("first", ["shared"], new Set(["shared"]));
const operations = [first];
try {
await entered.promise;
operations.push(active.replace("first", ["shared"], new Set(["shared"]), admitted.resolve));
await admitted.promise;
await vi.advanceTimersByTimeAsync(0);
release.resolve();
await Promise.all(operations);
expect(load).toHaveBeenCalledTimes(1);
expect(broadcastToConnIds.mock.calls).toEqual(
["first", "recipient", "first"].map((connId) => [
CHANGED_EVENT,
{ sessions: changedSessions },
new Set([connId]),
{ sessionKeys: ["shared"], agentId: "main" },
]),
);
} finally {
release.resolve();
await Promise.all(operations);
}
});
it("keeps a pending replacement when its last old watch loses visibility", async () => {
vi.useFakeTimers();
const entered = createDeferred();
const release = createDeferred();
const retired = createDeferred();
let oldVisible = true;
const load = vi.fn(async ({ sessionKey }: { sessionKey: string }, signal?: AbortSignal) => {
if (sessionKey === "old") {
signal?.addEventListener("abort", () => retired.resolve(), { once: true });
}
return READY;
});
const broadcastToConnIds = vi.fn();
active = createTestControlUiSessionPrSubscriptions({
broadcastToConnIds,
load,
prepareRead: async (_connId, session) => {
if (session.sessionKey === "new") {
entered.resolve();
await release.promise;
}
return async () =>
session.sessionKey === "old" && !oldVisible
? undefined
: {
...target,
params: { ...target.params, sessionKey: session.sessionKey },
identity: session.sessionKey,
};
},
});
await active.replace("same", ["old"]);
broadcastToConnIds.mockClear();
const replacement = active.replace("same", ["new"]);
await entered.promise;
oldVisible = false;
const poll = active.pollNow();
try {
await retired.promise;
release.resolve();
await Promise.all([replacement, poll]);
expect(broadcastToConnIds).toHaveBeenCalledExactlyOnceWith(
CHANGED_EVENT,
{ sessions: { new: { ...READY, status: "ready" } } },
new Set(["same"]),
{ sessionKeys: ["new"], agentId: "main" },
);
} finally {
release.resolve();
await Promise.all([replacement, poll]);
}
});
it("does not let a superseded preparation overwrite a current refresh request", async () => {
vi.useFakeTimers();
const oldEntered = createDeferred();
const oldRelease = createDeferred();
const blockedEntered = createDeferred();
const blockedRelease = createDeferred();
const loadEntered = createDeferred();
const loadRelease = createDeferred();
let holdOld = false;
const load = vi.fn(async ({ refresh }: { refresh?: boolean }) => {
if (refresh) {
loadEntered.resolve();
await loadRelease.promise;
}
return READY;
});
const broadcastToConnIds = vi.fn();
active = createTestControlUiSessionPrSubscriptions({
broadcastToConnIds,
load,
prepareRead: async (_connId, session) => {
if (session.sessionKey === "blocked") {
blockedEntered.resolve();
await blockedRelease.promise;
}
return async () => {
if (holdOld) {
holdOld = false;
oldEntered.resolve();
await oldRelease.promise;
}
return target;
};
},
});
await active.replace("same", ["shared"]);
broadcastToConnIds.mockClear();
load.mockClear();
holdOld = true;
const old = active.replace("same", ["shared", "blocked"], new Set(["shared"]));
await oldEntered.promise;
const current = active.replace("same", ["shared"], new Set(["shared"]));
try {
await loadEntered.promise;
oldRelease.resolve();
await blockedEntered.promise;
loadRelease.resolve();
await current;
expect(broadcastToConnIds).toHaveBeenCalledExactlyOnceWith(
CHANGED_EVENT,
{ sessions: { shared: { ...READY, status: "ready" } } },
new Set(["same"]),
{ sessionKeys: ["shared"], agentId: "main" },
);
blockedRelease.resolve();
await old;
expect(load).toHaveBeenCalledTimes(1);
} finally {
oldRelease.resolve();
blockedRelease.resolve();
loadRelease.resolve();
await vi.advanceTimersByTimeAsync(10_000);
await Promise.all([old, current]);
}
});
it("does not revive a retired admission after its connection ID is reused", async () => {
vi.useFakeTimers();
const entered = createDeferred();
const held = createDeferred();
const load = vi.fn(async () => READY);
const broadcastToConnIds = vi.fn();
active = createTestControlUiSessionPrSubscriptions({
broadcastToConnIds,
load,
prepareRead: async (_connId, session) => {
if (session.sessionKey === "retired") {
entered.resolve();
await held.promise;
}
return async () => ({
...target,
params: { ...target.params, sessionKey: session.sessionKey },
identity: session.sessionKey,
});
},
});
const retired = active.replace("reused", ["retired"]);
try {
await entered.promise;
active.unsubscribe("reused");
await active.replace("reused", ["current"]);
held.resolve();
await retired;
expect(load).toHaveBeenCalledTimes(1);
expect(broadcastToConnIds).toHaveBeenCalledExactlyOnceWith(
CHANGED_EVENT,
{ sessions: { current: { ...READY, status: "ready" } } },
new Set(["reused"]),
{ sessionKeys: ["current"], agentId: "main" },
);
} finally {
held.resolve();
await retired;
}
});
it.each(["disconnect", "grant", "all"] as const)(
"keeps pending shared reads authorized by surviving viewers after %s retirement",
async (retirement) => {
vi.useFakeTimers();
const entered = createDeferred();
const held = createDeferred();
const connected = new Set(["survivor", "departing"]);
const access = { survivor: new AbortController(), departing: new AbortController() };
const broadcastToConnIds = vi.fn();
let holdLoad = false;
let authorized = false;
active = createTestControlUiSessionPrSubscriptions({
broadcastToConnIds,
isConnectionActive: (connId) => connected.has(connId),
prepareRead: async (connId) => {
const grant = connId === "survivor" ? access.survivor : access.departing;
const preparedTarget = {
...target,
assertCurrent: () => {
if (!connected.has(connId)) {
throw new Error("Connection retired");
}
grant.signal.throwIfAborted();
},
};
return async () =>
connected.has(connId) && !grant.signal.aborted ? preparedTarget : undefined;
},
load: async (_params, _signal, read) => {
if (!holdLoad) {
return READY;
}
entered.resolve();
await held.promise;
read.assertCurrent();
authorized = true;
return changed;
},
});
await active.replace("survivor", ["shared"]);
await active.replace("departing", ["shared"]);
broadcastToConnIds.mockClear();
holdLoad = true;
const poll = active.pollNow();
try {
await entered.promise;
if (retirement === "disconnect") {
connected.delete("departing");
active.unsubscribe("departing");
} else {
access.departing.abort(new Error("Grant retired"));
if (retirement === "all") {
access.survivor.abort(new Error("Grant retired"));
}
}
held.resolve();
await poll;
expect(authorized).toBe(retirement !== "all");
if (retirement === "all") {
expect(broadcastToConnIds).not.toHaveBeenCalled();
} else {
expect(broadcastToConnIds).toHaveBeenCalledExactlyOnceWith(
CHANGED_EVENT,
{ sessions: changedSessions },
new Set(["survivor"]),
{ sessionKeys: ["shared"], agentId: "main" },
);
}
} finally {
held.resolve();
await poll;
}
},
);
it("checks the recipient's prepared authority when another watcher joins before send", async () => {
vi.useFakeTimers();
const recipientEntered = createDeferred();
const recipientRead = createDeferred<ControlUiSessionPrTarget>();
const joiningEntered = createDeferred();
const joiningRead = createDeferred<ControlUiSessionPrTarget>();
const access = new AbortController();
const recipientTarget = { ...target, assertCurrent: () => access.signal.throwIfAborted() };
let holdRecipient = false;
let snapshot = READY;
const broadcastToConnIds = vi.fn();
active = createTestControlUiSessionPrSubscriptions({
broadcastToConnIds,
load: async () => snapshot,
prepareRead: async (connId) => () => {
if (connId === "joining") {
joiningEntered.resolve();
return joiningRead.promise;
}
if (connId === "recipient") {
if (holdRecipient) {
holdRecipient = false;
recipientEntered.resolve();
return recipientRead.promise;
}
return Promise.resolve(access.signal.aborted ? undefined : recipientTarget);
}
return Promise.resolve(target);
},
});
await active.replace("first", ["shared"]);
await active.replace("recipient", ["shared"]);
broadcastToConnIds.mockClear();
broadcastToConnIds.mockImplementationOnce(() => {
holdRecipient = true;
});
snapshot = changed;
const poll = active.pollNow();
const operations: Promise<unknown>[] = [poll];
try {
await recipientEntered.promise;
operations.push(active.replace("joining", ["shared"]));
await joiningEntered.promise;
access.abort(new Error("Recipient access retired"));
// The recipient finishes preparation first; admission then updates the shared
// target before the recipient's queued send can resume.
recipientRead.resolve(recipientTarget);
joiningRead.resolve(target);
await Promise.all(operations);
expect(broadcastToConnIds.mock.calls).toEqual(
["first", "joining"].map((connId) => [
CHANGED_EVENT,
{ sessions: changedSessions },
new Set([connId]),
{ sessionKeys: ["shared"], agentId: "main" },
]),
);
} finally {
recipientRead.resolve(recipientTarget);
joiningRead.resolve(target);
await Promise.allSettled(operations);
}
});
it.each(["pending", "prepared"] as const)(
"does not revive a removed watcher whose delivery read is %s",
async (boundary) => {
vi.useFakeTimers();
const entered = createDeferred();
const held = createDeferred<ControlUiSessionPrTarget>();
let holdRecipient = false;
let snapshot = READY;
let cacheSignal: AbortSignal | undefined;
const broadcastToConnIds = vi.fn();
active = createTestControlUiSessionPrSubscriptions({
broadcastToConnIds,
load: async (_params, signal) => {
cacheSignal = signal;
return snapshot;
},
prepareRead: async (connId) => () => {
if (connId === "removed" && holdRecipient) {
holdRecipient = false;
entered.resolve();
return held.promise;
}
return Promise.resolve(target);
},
});
await active.replace("first", ["shared"]);
await active.replace("removed", ["shared"]);
broadcastToConnIds.mockClear();
broadcastToConnIds.mockImplementationOnce(() => {
holdRecipient = true;
});
snapshot = changed;
const poll = active.pollNow();
try {
await entered.promise;
if (boundary === "pending") {
active.unsubscribe("removed");
}
held.resolve(target);
if (boundary === "prepared") {
// The owner's earlier promise reaction installs the prepared target;
// retire membership before the queued publication continuation runs.
await held.promise;
active.unsubscribe("removed");
}
await poll;
expect(broadcastToConnIds).toHaveBeenCalledExactlyOnceWith(
CHANGED_EVENT,
{ sessions: changedSessions },
new Set(["first"]),
{ sessionKeys: ["shared"], agentId: "main" },
);
active.unsubscribe("first");
expect(cacheSignal?.aborted).toBe(true);
} finally {
held.resolve(target);
await poll;
}
},
);
it("continues to later recipients after one prepared authority rejects the shared snapshot", async () => {
vi.useFakeTimers();
const entered = createDeferred();
const held = createDeferred<ControlUiSessionPrTarget>();
const access = new AbortController();
const rejectedTarget = { ...target, assertCurrent: () => access.signal.throwIfAborted() };
let holdRecipient = false;
let snapshot = READY;
const broadcastToConnIds = vi.fn();
active = createTestControlUiSessionPrSubscriptions({
broadcastToConnIds,
load: async () => snapshot,
prepareRead: async (connId) => () => {
if (connId === "rejected") {
if (holdRecipient) {
holdRecipient = false;
entered.resolve();
return held.promise;
}
return Promise.resolve(access.signal.aborted ? undefined : rejectedTarget);
}
return Promise.resolve(target);
},
});
for (const connId of ["first", "rejected", "last"]) {
await active.replace(connId, ["shared"]);
}
broadcastToConnIds.mockClear();
broadcastToConnIds.mockImplementationOnce(() => {
holdRecipient = true;
});
snapshot = changed;
const poll = active.pollNow();
try {
await entered.promise;
access.abort(new Error("Recipient access retired"));
held.resolve(rejectedTarget);
await poll;
expect(broadcastToConnIds.mock.calls).toEqual(
["first", "last"].map((connId) => [
CHANGED_EVENT,
{ sessions: changedSessions },
new Set([connId]),
{ sessionKeys: ["shared"], agentId: "main" },
]),
);
broadcastToConnIds.mockClear();
await active.pollNow();
expect(broadcastToConnIds).not.toHaveBeenCalled();
} finally {
held.resolve(rejectedTarget);
await poll;
}
});
});

View file

@ -8,7 +8,7 @@ export function createTestControlUiSessionPrSubscriptions(
deps: Omit<SubscriptionDeps, "prepareRead"> & Partial<Pick<SubscriptionDeps, "prepareRead">>,
) {
return createControlUiSessionPullRequestSubscriptions({
prepareRead: (_connId, session) => {
prepareRead: async (_connId, session) => {
const parsed = parseAgentSessionKey(session.sessionKey);
const target = {
params: {
@ -19,7 +19,7 @@ export function createTestControlUiSessionPrSubscriptions(
readSource: { agentId: session.agentId ?? parsed?.agentId ?? "main", path: "unused" },
source: null,
};
return () => target;
return async () => target;
},
...deps,
});

View file

@ -772,8 +772,10 @@ describe("control UI session PR subscriptions", () => {
isConnectionActive: () => false,
});
await active.replace("conn-closed", ["orphan"]);
const onAdmitted = vi.fn();
await active.replace("conn-closed", ["orphan"], undefined, onAdmitted);
expect(onAdmitted).toHaveBeenCalledTimes(1);
expect(load).not.toHaveBeenCalled();
expect(broadcastToConnIds).not.toHaveBeenCalled();
});

View file

@ -33,13 +33,14 @@ type LoadSessionPullRequests = (
type WatchedKeyState = {
connIds: Set<string>;
target: ControlUiSessionPrTarget;
watchLifetime: object;
sourceIdentity?: string;
// Retire cache pins with the shared key, without cancelling another watcher's load.
cacheLifetime: AbortController;
hash?: string;
snapshot?: ControlUiSessionPullRequestSnapshot;
refreshedAt?: number;
cancelRefresh?: () => void;
delivery?: Promise<void>;
};
type SubscriptionDeps = {
@ -47,7 +48,7 @@ type SubscriptionDeps = {
prepareRead: (
connId: string,
session: Pick<ControlUiSessionPullRequestsParams, "sessionKey" | "agentId">,
) => ControlUiSessionPrRead | undefined;
) => Promise<ControlUiSessionPrRead | undefined>;
isConnectionActive?: (connId: string) => boolean;
load?: LoadSessionPullRequests;
setTimer?: typeof globalThis.setTimeout;
@ -59,6 +60,7 @@ type ControlUiSessionPullRequestSubscriptions = {
connId: string,
sessionKeys: readonly string[],
refreshSessionKeys?: ReadonlySet<string>,
onAdmitted?: () => void,
) => Promise<void>;
unsubscribe: (connId: string) => void;
pollNow: () => Promise<void>;
@ -139,15 +141,21 @@ export function createControlUiSessionPullRequestSubscriptions(
type Watched = {
readCurrent: ControlUiSessionPrRead;
target: ControlUiSessionPrTarget;
delivered?: ControlUiSessionPullRequestSnapshot;
deliveredHash?: string;
delivery?: Promise<void>;
refreshPending?: object;
};
const subscriptions = new Map<string, Map<string, Watched>>();
const replacements = new Set<Promise<void>>();
const replacementGenerations = new Map<string, object>();
const pendingAdmissions = new Map<string, Set<() => boolean>>();
const keyStates = new Map<string, WatchedKeyState>();
const inflight = new Map<
string,
{
promise: Promise<ControlUiSessionPullRequestSnapshot>;
refresh: boolean;
refreshRequests: Map<Watched, object>;
state: WatchedKeyState;
demands: Set<() => boolean>;
}
@ -168,6 +176,21 @@ export function createControlUiSessionPullRequestSubscriptions(
const scope = new AsyncWorkScope();
let stopPromise: Promise<void> | undefined;
const retireKeyStateIfUnused = (sessionKey: string, state: WatchedKeyState | undefined) => {
if (
!state ||
state.connIds.size > 0 ||
[...(pendingAdmissions.get(sessionKey) ?? [])].some((isCurrent) => isCurrent())
) {
return;
}
state.cancelRefresh?.();
state.cacheLifetime.abort(null);
if (keyStates.get(sessionKey) === state) {
keyStates.delete(sessionKey);
}
};
const removeMemberships = (
connId: string,
previous: ReadonlyMap<string, unknown> | undefined,
@ -177,11 +200,7 @@ export function createControlUiSessionPullRequestSubscriptions(
if (!retained?.has(key)) {
const state = keyStates.get(key);
state?.connIds.delete(connId);
if (state?.connIds.size === 0) {
state.cancelRefresh?.();
state.cacheLifetime.abort(null);
keyStates.delete(key);
}
retireKeyStateIfUnused(key, state);
}
}
};
@ -198,6 +217,7 @@ export function createControlUiSessionPullRequestSubscriptions(
previous.sourceIdentity === undefined ||
previous.sourceIdentity === sourceIdentity)
) {
previous.target = target;
previous.sourceIdentity ??= sourceIdentity;
return previous;
}
@ -206,6 +226,7 @@ export function createControlUiSessionPullRequestSubscriptions(
const state: WatchedKeyState = {
connIds: new Set(previous?.connIds),
target,
watchLifetime: previous?.watchLifetime ?? {},
sourceIdentity,
cacheLifetime: new AbortController(),
};
@ -213,47 +234,55 @@ export function createControlUiSessionPullRequestSubscriptions(
return state;
};
const currentWatcher = (connId: string, sessionKey: string) => {
const currentWatcher = async (connId: string, sessionKey: string) => {
const watched = subscriptions.get(connId)?.get(sessionKey);
const target =
deps.isConnectionActive?.(connId) === false ? undefined : await watched?.readCurrent();
const subscription = subscriptions.get(connId);
const watched = subscription?.get(sessionKey);
const target = deps.isConnectionActive?.(connId) === false ? undefined : watched?.readCurrent();
if (!watched || !target) {
if (scope.isClosing || subscription?.get(sessionKey) !== watched) {
return undefined;
}
if (!watched || !target || deps.isConnectionActive?.(connId) === false) {
subscription?.delete(sessionKey);
const state = keyStates.get(sessionKey);
state?.connIds.delete(connId);
if (state?.connIds.size === 0) {
state.cancelRefresh?.();
state.cacheLifetime.abort(null);
keyStates.delete(sessionKey);
}
retireKeyStateIfUnused(sessionKey, state);
if (subscription?.size === 0) {
unsubscribe(connId);
// Pruning an old watch does not retire a newer replacement still preparing its keys.
subscriptions.delete(connId);
if (deps.isConnectionActive?.(connId) === false) {
replacementGenerations.delete(connId);
}
if (subscriptions.size === 0 && timer !== null) {
clearTimer(timer);
timer = null;
}
}
return undefined;
}
if (watched.target.identity !== target.identity) {
watched.target = target;
watched.delivered = undefined;
watched.deliveredHash = undefined;
}
watched.target = target;
stateForTarget(sessionKey, target).connIds.add(connId);
return watched;
return { watched, target };
};
const currentKeyState = (sessionKey: string) => {
const currentKeyState = async (sessionKey: string) => {
for (const connId of keyStates.get(sessionKey)?.connIds ?? []) {
currentWatcher(connId, sessionKey);
await currentWatcher(connId, sessionKey);
}
return keyStates.get(sessionKey);
};
const loadSnapshot = (
const loadSnapshot = async (
sessionKey: string,
isCurrent: () => boolean,
refresh = false,
refresh?: { watched: Watched; generation: object },
): Promise<ControlUiSessionPullRequestSnapshot> => {
const targetState = currentKeyState(sessionKey);
const targetState = await currentKeyState(sessionKey);
if (scope.isClosing || !targetState || !isCurrent()) {
return Promise.resolve(UNAVAILABLE_SNAPSHOT);
return UNAVAILABLE_SNAPSHOT;
}
return withSource(targetState.target, async (assertSourceCurrent, sourceIdentity) => {
const state = stateForTarget(sessionKey, targetState.target, sourceIdentity);
@ -261,17 +290,24 @@ export function createControlUiSessionPullRequestSubscriptions(
if (pending) {
if (pending.state === state && (!refresh || pending.refresh)) {
pending.demands.add(isCurrent);
if (refresh && refresh.watched.refreshPending === refresh.generation) {
pending.refreshRequests.set(refresh.watched, refresh.generation);
}
return pending.promise;
}
// Serialize a forced refresh behind an older normal load so that older
// poll results can never land after the refresh and revert its snapshot.
await pending.promise;
assertSourceCurrent();
return currentKeyState(sessionKey) === state && isCurrent()
return (await currentKeyState(sessionKey)) === state && isCurrent()
? loadSnapshot(sessionKey, isCurrent, refresh)
: UNAVAILABLE_SNAPSHOT;
}
const demands = new Set([isCurrent]);
const refreshRequests = new Map<Watched, object>();
if (refresh && refresh.watched.refreshPending === refresh.generation) {
refreshRequests.set(refresh.watched, refresh.generation);
}
const promise = scope
.track(async () => {
const delay = refresh
@ -296,14 +332,13 @@ export function createControlUiSessionPullRequestSubscriptions(
// watcher must not revive normal work retired while waiting for a slot.
if (
!Array.from(demands).some((current) => current()) ||
currentKeyState(sessionKey) !== state
(await currentKeyState(sessionKey)) !== state
) {
return UNAVAILABLE_SNAPSHOT;
}
if (refresh) {
state.refreshedAt = Date.now();
}
// Fresh result identity acknowledges forced loads even when the failure is unchanged.
const snapshot = await load(
{ ...state.target.params, ...(refresh ? { refresh: true } : {}) },
state.cacheLifetime.signal,
@ -315,25 +350,46 @@ export function createControlUiSessionPullRequestSubscriptions(
if (
scope.isClosing ||
!Array.from(demands).some((current) => current()) ||
currentKeyState(sessionKey) !== state
keyStates.get(sessionKey) !== state
) {
throw new Error("Session pull-request watchers changed");
}
// Shared work survives a departing viewer while another prepared reader
// still authorizes this exact source. Delivery keeps its per-viewer guard.
for (const connId of state.connIds) {
const watched = subscriptions.get(connId)?.get(sessionKey);
if (
!watched ||
watched.target.identity !== state.target.identity ||
deps.isConnectionActive?.(connId) === false
) {
continue;
}
try {
watched.target.assertCurrent?.();
return;
} catch {
// A different watcher may still own a current grant.
}
}
throw new Error("Session pull-request watchers changed");
},
},
)
.then(pushedSnapshot)
.catch(() => ({ ...UNAVAILABLE_SNAPSHOT }));
if (currentKeyState(sessionKey) === state) {
if ((await currentKeyState(sessionKey)) === state) {
assertSourceCurrent();
const hash = JSON.stringify(snapshot);
const changed = state.hash !== hash;
Object.assign(state, { hash, snapshot });
// Publish once at the shared owner, using the latest snapshot and watcher union.
if (changed) {
// A send can synchronously retire a watcher; delivery acknowledges this snapshot only.
push(new Set(state.connIds), sessionKey, state, snapshot, assertSourceCurrent);
}
state.snapshot = snapshot;
// Shared equality does not acknowledge recipients that missed publication.
await push(
new Set(state.connIds),
sessionKey,
state,
snapshot,
assertSourceCurrent,
refreshRequests,
);
}
return snapshot;
});
@ -344,7 +400,13 @@ export function createControlUiSessionPullRequestSubscriptions(
inflight.delete(sessionKey);
}
});
inflight.set(sessionKey, { promise, refresh, state, demands });
inflight.set(sessionKey, {
promise,
refresh: Boolean(refresh),
refreshRequests,
state,
demands,
});
return promise;
}).catch(() => UNAVAILABLE_SNAPSHOT);
};
@ -355,29 +417,84 @@ export function createControlUiSessionPullRequestSubscriptions(
state: WatchedKeyState,
snapshot: ControlUiSessionPullRequestSnapshot,
assertSourceCurrent: () => void,
) => {
refreshRequests?: ReadonlyMap<Watched, object>,
): Promise<void> => {
if (connIds.size === 0) {
return;
}
const sessions = Object.create(null) as ControlUiSessionPullRequestsChanged["sessions"];
sessions[sessionKey] = snapshot;
for (const connId of connIds) {
const watched = currentWatcher(connId, sessionKey);
if (!watched || keyStates.get(sessionKey) !== state) {
continue;
}
assertSourceCurrent();
// A socket callback can replace the session or retire another viewer synchronously.
deps.broadcastToConnIds(
CONTROL_UI_SESSION_PULL_REQUESTS_CHANGED_EVENT,
{ sessions },
new Set([connId]),
{ sessionKeys: [state.target.params.sessionKey], agentId: state.target.params.agentId },
);
if (subscriptions.get(connId)?.get(sessionKey) === watched) {
watched.delivered = snapshot;
}
return Promise.resolve();
}
const hash = JSON.stringify(snapshot);
// Equal data acknowledges only the exact refresh requests joined by this load.
const isDelivered = (watched: Watched) => {
const request = refreshRequests?.get(watched);
return (!request || watched.refreshPending !== request) && watched.deliveredHash === hash;
};
const previousStateDelivery = state.delivery ?? Promise.resolve();
const stateDelivery = previousStateDelivery
.then(async () => {
const sessions = Object.create(null) as ControlUiSessionPullRequestsChanged["sessions"];
sessions[sessionKey] = snapshot;
for (const connId of connIds) {
const watched = subscriptions.get(connId)?.get(sessionKey);
if (!watched || isDelivered(watched)) {
continue;
}
const previous = watched.delivery ?? Promise.resolve();
const delivery = previous
.then(async () => {
const current = await currentWatcher(connId, sessionKey);
if (
!current ||
scope.isClosing ||
current.watched !== watched ||
subscriptions.get(connId)?.get(sessionKey) !== watched ||
deps.isConnectionActive?.(connId) === false ||
keyStates.get(sessionKey) !== state ||
isDelivered(watched)
) {
return;
}
assertSourceCurrent();
try {
// The shared cache can carry another viewer's target after preparation yields.
current.target.assertCurrent?.();
} catch {
// Losing one recipient must not suppress the same snapshot for other viewers.
return;
}
const refreshRequest = refreshRequests?.get(watched);
// A socket callback can replace the session or retire another viewer synchronously.
deps.broadcastToConnIds(
CONTROL_UI_SESSION_PULL_REQUESTS_CHANGED_EVENT,
{ sessions },
new Set([connId]),
{
sessionKeys: [state.target.params.sessionKey],
agentId: state.target.params.agentId,
},
);
if (subscriptions.get(connId)?.get(sessionKey) === watched) {
watched.deliveredHash = hash;
if (refreshRequest && watched.refreshPending === refreshRequest) {
delete watched.refreshPending;
}
}
})
.finally(() => {
if (watched.delivery === delivery) {
delete watched.delivery;
}
});
watched.delivery = delivery;
await delivery;
}
})
.finally(() => {
if (state.delivery === stateDelivery) {
delete state.delivery;
}
});
state.delivery = stateDelivery;
return stateDelivery;
};
const schedulePoll = () => {
@ -398,11 +515,18 @@ export function createControlUiSessionPullRequestSubscriptions(
return scope.track(async () => {
// One union pass owns each key once; the loader retains its failure and
// rate-limit cache, so the poller never creates a second quota policy.
await Promise.all(
Array.from(keyStates.keys(), (sessionKey) =>
loadSnapshot(sessionKey, () => keyStates.has(sessionKey)),
await Promise.all([
Promise.allSettled(replacements),
Promise.all(
Array.from(keyStates, ([sessionKey, state]) => {
const watchLifetime = state.watchLifetime;
return loadSnapshot(
sessionKey,
() => keyStates.get(sessionKey)?.watchLifetime === watchLifetime,
);
}),
),
);
]);
});
};
@ -410,79 +534,168 @@ export function createControlUiSessionPullRequestSubscriptions(
connId: string,
sessionKeys: readonly string[],
refreshSessionKeys: ReadonlySet<string> = new Set(),
onAdmitted?: () => void,
) => {
let admitted = false;
const admit = () => {
if (!admitted) {
admitted = true;
onAdmitted?.();
}
};
if (scope.isClosing) {
admit();
return Promise.resolve();
}
return scope.track(async () => {
const normalizedConnId = connId.trim();
if (!normalizedConnId || deps.isConnectionActive?.(normalizedConnId) === false) {
return;
const normalizedConnId = connId.trim();
if (!normalizedConnId || deps.isConnectionActive?.(normalizedConnId) === false) {
unsubscribe(normalizedConnId);
admit();
return Promise.resolve();
}
// A fresh identity cannot revive retired work when a connection ID is reused.
const generation = {};
replacementGenerations.set(normalizedConnId, generation);
// Reserve retained-key intent in call order; an older preparation cannot overwrite it later.
for (const key of sessionKeys) {
const watched = subscriptions.get(normalizedConnId)?.get(key);
if (watched && refreshSessionKeys.has(key)) {
watched.refreshPending = generation;
}
const previousSubscription = subscriptions.get(normalizedConnId);
const subscription = new Map<string, Watched>();
for (const key of sessionKeys) {
const parsed = parseAgentSessionKey(key);
const session =
parsed?.rest === "global"
? { sessionKey: "global", agentId: parsed.agentId }
: { sessionKey: key };
const previous = previousSubscription?.get(key);
const readCurrent = previous?.readCurrent()
? previous.readCurrent
: deps.prepareRead(normalizedConnId, session);
const target = readCurrent?.();
if (!readCurrent || !target) {
continue;
}
subscription.set(
key,
previous?.target.identity === target.identity && readCurrent === previous.readCurrent
? previous
: { readCurrent, target },
);
}
const isCurrentReplacement = () =>
!scope.isClosing && replacementGenerations.get(normalizedConnId) === generation;
const replacement = scope.track(async () => {
const retainedKeys = new Set(sessionKeys.filter((key) => keyStates.has(key)));
for (const key of retainedKeys) {
const admissions = pendingAdmissions.get(key) ?? new Set<() => boolean>();
admissions.add(isCurrentReplacement);
pendingAdmissions.set(key, admissions);
}
if (subscription.size === 0) {
unsubscribe(normalizedConnId);
return;
}
subscriptions.set(normalizedConnId, subscription);
removeMemberships(normalizedConnId, previousSubscription, subscription);
// Publish the whole replacement before cached hydration can send synchronously.
for (const [key, watched] of subscription) {
stateForTarget(key, watched.target).connIds.add(normalizedConnId);
}
schedulePoll();
await Promise.all(
Array.from(subscription, async ([sessionKey, watched]) => {
const targetState = currentKeyState(sessionKey);
if (!targetState) {
return;
try {
const previousSubscription = subscriptions.get(normalizedConnId);
const subscription = new Map<string, Watched>();
for (const key of sessionKeys) {
const parsed = parseAgentSessionKey(key);
const session =
parsed?.rest === "global"
? { sessionKey: "global", agentId: parsed.agentId }
: { sessionKey: key };
const previous = previousSubscription?.get(key);
const readCurrent =
previous && (await previous.readCurrent())
? previous.readCurrent
: await deps.prepareRead(normalizedConnId, session);
const target = await readCurrent?.();
if (!readCurrent || !target) {
continue;
}
return withSource(targetState.target, async (assertSourceCurrent, sourceIdentity) => {
const state = stateForTarget(sessionKey, targetState.target, sourceIdentity);
const isCurrent = () =>
subscriptions.get(normalizedConnId)?.get(sessionKey) === watched;
const refresh = refreshSessionKeys.has(sessionKey);
const cached = refresh ? undefined : state.snapshot;
// A shared cached snapshot does not prove this connection received it.
if (cached) {
if (!watched.delivered) {
push(new Set([normalizedConnId]), sessionKey, state, cached, assertSourceCurrent);
}
const next =
previous?.target.identity === target.identity && readCurrent === previous.readCurrent
? previous
: { readCurrent, target };
if (next !== previous && refreshSessionKeys.has(key)) {
next.refreshPending = generation;
}
subscription.set(key, next);
}
const currentReplacement = isCurrentReplacement();
if (!currentReplacement) {
const current = subscriptions.get(normalizedConnId);
for (const [key, watched] of subscription) {
if (
!refreshSessionKeys.has(key) ||
current?.get(key) !== watched ||
watched.refreshPending !== generation
) {
subscription.delete(key);
}
}
}
if (subscription.size === 0) {
if (currentReplacement) {
unsubscribe(normalizedConnId);
}
admit();
return;
}
if (currentReplacement) {
subscriptions.set(normalizedConnId, subscription);
removeMemberships(normalizedConnId, previousSubscription, subscription);
// Publish the whole replacement before cached hydration can send synchronously.
for (const [key, watched] of subscription) {
stateForTarget(key, watched.target).connIds.add(normalizedConnId);
}
schedulePoll();
}
admit();
await Promise.all(
Array.from(subscription, async ([sessionKey, watched]) => {
const targetState = await currentKeyState(sessionKey);
if (!targetState) {
return;
}
const snapshot = await loadSnapshot(sessionKey, isCurrent, refresh);
assertSourceCurrent();
// A removed/re-added key has a new cell; retained keys still need their result.
if (isCurrent() && (refresh ? watched.delivered !== snapshot : !watched.delivered)) {
push(new Set([normalizedConnId]), sessionKey, state, snapshot, assertSourceCurrent);
}
}).catch(() => {});
}),
);
return withSource(targetState.target, async (assertSourceCurrent, sourceIdentity) => {
const state = stateForTarget(sessionKey, targetState.target, sourceIdentity);
const isCurrent = () =>
subscriptions.get(normalizedConnId)?.get(sessionKey) === watched;
const refresh = refreshSessionKeys.has(sessionKey);
const cached = refresh ? undefined : state.snapshot;
// A shared cached snapshot does not prove this connection received it.
if (cached) {
if (!watched.deliveredHash) {
await push(
new Set([normalizedConnId]),
sessionKey,
state,
cached,
assertSourceCurrent,
);
}
return;
}
const snapshot = await loadSnapshot(
sessionKey,
isCurrent,
refresh ? { watched, generation } : undefined,
);
assertSourceCurrent();
// A removed/re-added key has a new cell; retained keys still need their result.
if (
isCurrent() &&
(refresh ? watched.refreshPending === generation : !watched.deliveredHash)
) {
await push(
new Set([normalizedConnId]),
sessionKey,
state,
snapshot,
assertSourceCurrent,
refresh ? new Map([[watched, generation]]) : undefined,
);
}
}).catch(() => {});
}),
);
} finally {
admit();
for (const key of retainedKeys) {
const admissions = pendingAdmissions.get(key);
admissions?.delete(isCurrentReplacement);
if (admissions?.size === 0) {
pendingAdmissions.delete(key);
}
retireKeyStateIfUnused(key, keyStates.get(key));
}
}
});
replacements.add(replacement);
void replacement.then(
() => replacements.delete(replacement),
() => replacements.delete(replacement),
);
return replacement;
};
const unsubscribe = (connId: string) => {
@ -490,6 +703,7 @@ export function createControlUiSessionPullRequestSubscriptions(
if (!normalizedConnId) {
return;
}
replacementGenerations.delete(normalizedConnId);
removeMemberships(normalizedConnId, subscriptions.get(normalizedConnId));
subscriptions.delete(normalizedConnId);
if (subscriptions.size === 0 && timer !== null) {
@ -508,6 +722,8 @@ export function createControlUiSessionPullRequestSubscriptions(
timer = null;
}
subscriptions.clear();
replacementGenerations.clear();
replacements.clear();
for (const state of keyStates.values()) {
state.cancelRefresh?.();
state.cacheLifetime.abort(null);

View file

@ -160,12 +160,12 @@ export function createSessionPullRequestsFixture() {
};
return {
load,
prepareRead: (
prepareRead: async (
_connId: string,
session: Parameters<typeof loadControlUiSessionPullRequests>[0],
) => {
const params = seed(session);
return () =>
return async () =>
resolveControlUiSessionPrTarget(
loadGatewaySessionEntryReadOnly(params.sessionKey, { agentId: params.agentId }),
);

View file

@ -78,6 +78,7 @@ import type {
import { roundedChatSendTimingMs } from "./server-methods/chat-server-timing.js";
import { hasSessionChangeReceivers } from "./session-change-receivers.js";
import { buildGatewaySessionSnapshot } from "./session-event-payload.js";
import { withPreparedSessionEventRow } from "./session-event-prepared-row.js";
import {
isRestartRecoveryLifecycleEvent,
persistGatewaySessionLifecycleEvent,
@ -822,23 +823,20 @@ export function createAgentEventHandler({
void persistence
.then(
async () => {
if (projection) {
do {
await projection.ensureMaterialized();
} while (projection.needsMaterialization);
}
broadcastSessionChange();
await withPreparedSessionEventRow(
projection,
sessionKey,
sessionAgentId,
broadcastSessionChange,
);
},
async (err: unknown) => {
logError(
`gateway: terminal session persistence failed session=${formatForLog(sessionKey)} run=${formatForLog(evt.runId)} error=${formatForLog(err)}`,
);
if (projection) {
do {
await projection.ensureMaterialized();
} while (projection.needsMaterialization);
}
broadcastSessionChange(evt);
await withPreparedSessionEventRow(projection, sessionKey, sessionAgentId, () =>
broadcastSessionChange(evt),
);
},
)
.catch((error: unknown) => {
@ -1884,18 +1882,10 @@ export function createAgentEventHandler({
{ dropIfSlow: true },
);
const projection = getSessionRowProjection?.();
if (projection) {
void (async () => {
do {
await projection.ensureMaterialized();
} while (projection.needsMaterialization);
publish();
})().catch((error: unknown) =>
void withPreparedSessionEventRow(projection, sessionKey, sessionAgentId, publish).catch(
(error: unknown) =>
logError(`gateway: session snapshot publication failed: ${formatErrorMessage(error)}`),
);
} else {
publish();
}
);
}
}
};

View file

@ -335,10 +335,10 @@ export async function prepareGatewayLifecycle(params: {
runtimeState.controlUiSessionPullRequests = createControlUiSessionPullRequestSubscriptions({
broadcastToConnIds,
isConnectionActive,
prepareRead: (connId, session) => {
prepareRead: async (connId, session) => {
const client = clients.getByConnectionId(connId);
return client
? prepareControlUiSessionPrRead({
? await prepareControlUiSessionPrRead({
client,
...session,
getRuntimeConfig,

View file

@ -5,7 +5,7 @@ import {
validateChatStartupParams,
} from "../../../packages/gateway-protocol/src/index.js";
import { getSessionRowProjection } from "../session-row-projection-access.js";
import { resolveSessionKeyFromResolveParams } from "../sessions-resolve.js";
import { withPreparedSessionResolve } from "../sessions-resolve.js";
import type { GatewayRequestHandlerOptions } from "./types.js";
import { assertValidParams } from "./validation.js";
@ -51,22 +51,31 @@ export async function handleChatStartupRequest(
);
return;
}
const resolution = resolveSessionKeyFromResolveParams({
projection,
client: opts.client,
p: { shortId, slugHint, agentId, allowMissing: true },
});
if (!resolution.ok) {
opts.respond(false, undefined, resolution.error);
return;
}
if ("missing" in resolution || "ambiguous" in resolution) {
opts.respond(true, {
resolution: {
ok: false,
...("ambiguous" in resolution ? { candidates: resolution.candidates } : {}),
},
});
const resolution = await withPreparedSessionResolve(
{
projection,
client: opts.client,
p: { shortId, slugHint, agentId, allowMissing: true },
isCurrent: () => getSessionRowProjection(opts.context) === projection,
},
(resolved) => {
if (!resolved.ok) {
opts.respond(false, undefined, resolved.error);
return undefined;
}
if ("missing" in resolved || "ambiguous" in resolved) {
opts.respond(true, {
resolution: {
ok: false,
...("ambiguous" in resolved ? { candidates: resolved.candidates } : {}),
},
});
return undefined;
}
return resolved;
},
);
if (!resolution) {
return;
}
await handleHistory({

View file

@ -519,7 +519,17 @@ describe("controlUi.githubPreview", () => {
describe("controlUi.sessionPullRequests.subscribe", () => {
it("replaces the connection watch set", async () => {
const replace = vi.fn().mockResolvedValue(undefined);
const replace = vi.fn(
(
_connId: string,
_sessionKeys: readonly string[],
_refreshSessionKeys: ReadonlySet<string> | undefined,
onAdmitted: (() => void) | undefined,
) => {
onAdmitted?.();
return Promise.resolve();
},
);
const handlers = createControlUiHandlers(vi.fn());
const respond = vi.fn<RespondFn>();
@ -537,13 +547,28 @@ describe("controlUi.sessionPullRequests.subscribe", () => {
),
);
expect(replace).toHaveBeenCalledWith("conn-control-ui", ["agent:main:main", "agent:work:main"]);
expect(replace).toHaveBeenCalledWith(
"conn-control-ui",
["agent:main:main", "agent:work:main"],
undefined,
expect.any(Function),
);
expect(respond).toHaveBeenCalledWith(true, { subscribed: true }, undefined);
});
it("acknowledges a subscription before its cold snapshots finish loading", async () => {
const { promise: hydration, resolve: finishHydration } = createDeferred();
const replace = vi.fn(() => hydration);
const replace = vi.fn(
(
_connId: string,
_sessionKeys: readonly string[],
_refreshSessionKeys: ReadonlySet<string> | undefined,
onAdmitted: (() => void) | undefined,
) => {
onAdmitted?.();
return hydration;
},
);
const handlers = createControlUiHandlers(vi.fn());
const respond = vi.fn<RespondFn>();
@ -556,15 +581,31 @@ describe("controlUi.sessionPullRequests.subscribe", () => {
context: { controlUiSessionPullRequests: { replace } },
}),
);
await Promise.resolve();
expect(replace).toHaveBeenCalledWith("conn-control-ui", ["agent:main:cold"]);
expect(replace).toHaveBeenCalledWith(
"conn-control-ui",
["agent:main:cold"],
undefined,
expect.any(Function),
);
expect(respond).toHaveBeenCalledWith(true, { subscribed: true }, undefined);
finishHydration();
await request;
});
it("accepts an empty replace-set as unsubscribe", async () => {
const replace = vi.fn().mockResolvedValue(undefined);
const replace = vi.fn(
(
_connId: string,
_sessionKeys: readonly string[],
_refreshSessionKeys: ReadonlySet<string> | undefined,
onAdmitted: (() => void) | undefined,
) => {
onAdmitted?.();
return Promise.resolve();
},
);
const handlers = createControlUiHandlers(vi.fn());
const respond = vi.fn<RespondFn>();
@ -578,7 +619,7 @@ describe("controlUi.sessionPullRequests.subscribe", () => {
}),
);
expect(replace).toHaveBeenCalledWith("conn-control-ui", []);
expect(replace).toHaveBeenCalledWith("conn-control-ui", [], undefined, expect.any(Function));
expect(respond).toHaveBeenCalledWith(true, { subscribed: false }, undefined);
});

View file

@ -423,7 +423,7 @@ export function createControlUiHandlers(
}
try {
const reader = client
? prepareControlUiSessionPrRead({
? await prepareControlUiSessionPrRead({
client,
sessionKey: parsed.sessionKey,
getRuntimeConfig: context.getRuntimeConfig,
@ -435,19 +435,28 @@ export function createControlUiHandlers(
.has(client.connId) === true,
})
: undefined;
const currentBinding = () => {
const currentBinding = async () => {
if (!client) {
return resolveCheckDetailsSession(parsed.sessionKey, context, client);
}
return reader?.() ?? null;
return (await reader?.()) ?? null;
};
const binding = currentBinding();
const binding = await currentBinding();
if (!binding) {
throw new gitHubPublicApi.ControlUiGitHubError(404, "Session CI details unavailable");
}
const assertCurrent = () => {
const current = currentBinding();
if (signal?.aborted || current?.identity !== binding.identity) {
let identityCurrent = false;
try {
binding.assertCurrent?.();
identityCurrent = client
? true
: resolveCheckDetailsSession(parsed.sessionKey, context, client)?.identity ===
binding.identity;
} catch {
// The read owner reports retired selections and grants as assertion failures.
}
if (signal?.aborted || !identityCurrent) {
throw new gitHubPublicApi.ControlUiGitHubError(
409,
"Session changed; reopen CI details",
@ -482,7 +491,7 @@ export function createControlUiHandlers(
respond(false, undefined, errorShape(ErrorCodes.UNAVAILABLE, message));
}
},
"controlUi.sessionPullRequests.subscribe": ({ params, client, context, respond }) => {
"controlUi.sessionPullRequests.subscribe": async ({ params, client, context, respond }) => {
const parsed = parseControlUiSessionPullRequestsSubscribeParams(params);
if (!parsed) {
respond(
@ -505,11 +514,19 @@ export function createControlUiHandlers(
);
return;
}
if (parsed.refreshSessionKeys.length > 0) {
void subscriptions.replace(connId, parsed.sessionKeys, new Set(parsed.refreshSessionKeys));
} else {
void subscriptions.replace(connId, parsed.sessionKeys);
}
const admitted = new Promise<void>((resolve) => {
const replacement =
parsed.refreshSessionKeys.length > 0
? subscriptions.replace(
connId,
parsed.sessionKeys,
new Set(parsed.refreshSessionKeys),
resolve,
)
: subscriptions.replace(connId, parsed.sessionKeys, undefined, resolve);
void replacement.catch(() => {});
});
await admitted;
respond(true, { subscribed: parsed.sessionKeys.length > 0 }, undefined);
},
};

View file

@ -215,6 +215,7 @@ it("connect negotiates snapshots and preserves draft and saved-session catalog s
{ agentId: "alpha", shortId: "12345678", slugHint: "saved" },
]) {
const savedPublications: ModelsSnapshotEvent[] = [];
const savedPublication = createDeferred();
const saved = await connectGatewayClient({
url: `ws://127.0.0.1:${port}`,
token,
@ -227,38 +228,40 @@ it("connect negotiates snapshots and preserves draft and saved-session catalog s
onEvent(event) {
if (event.event === "models.snapshot") {
savedPublications.push(event.payload as ModelsSnapshotEvent);
savedPublication.resolve();
}
},
});
try {
await expect
.poll(() => savedPublications)
.toMatchObject([
{
scope: { agentId: "alpha", sessionKey },
catalog: {
models: [
{
id: "first",
provider: "fixture",
available: true,
manualSelectionAllowed: true,
},
{
id: "second",
provider: "fixture",
available: true,
manualSelectionAllowed: false,
},
],
accountSelection: {
kind: "shared",
authProfileId: "fixture:saved-account",
source: "user",
// hello-ok precedes worker-backed catalog publication; join that event
// instead of assuming preparation fits the polling matcher's deadline.
await savedPublication.promise;
expect(savedPublications).toMatchObject([
{
scope: { agentId: "alpha", sessionKey },
catalog: {
models: [
{
id: "first",
provider: "fixture",
available: true,
manualSelectionAllowed: true,
},
{
id: "second",
provider: "fixture",
available: true,
manualSelectionAllowed: false,
},
],
accountSelection: {
kind: "shared",
authProfileId: "fixture:saved-account",
source: "user",
},
},
]);
},
]);
expect(publications).toHaveLength(1);
expect(loadSessionEntry({ agentId: "alpha", sessionKey })?.modelOverride).toBe("second");
} finally {

View file

@ -6,6 +6,7 @@ import {
} from "../../config/sessions/session-accessor.js";
import { closeOpenClawAgentDatabasesForTest } from "../../state/openclaw-agent-db.js";
import { withOpenClawTestState } from "../../test-utils/openclaw-test-state.js";
import { withReadySessionRows } from "../session-row-prepared-read.js";
import { createSessionRowProjection } from "../session-row-projection.js";
import { sessionMutationHandlers } from "./sessions-mutations.js";
import type { GatewayClient, GatewayRequestContext, RespondFn } from "./types.js";
@ -162,12 +163,18 @@ describe("sessions.patch archive attribution", () => {
},
client("profile-ada", "Ada"),
);
await projection.ensureMaterialized();
expect(projection.snapshot({ key: canonicalKey, agentId: "main" }).row).toMatchObject({
archived: true,
archivedAt: expect.any(Number),
archivedBy: { type: "human", id: "profile-ada" },
});
const query = { key: canonicalKey, agentId: "main" };
await withReadySessionRows(
projection,
() => [query],
() => {
expect(projection.snapshot(query).row).toMatchObject({
archived: true,
archivedAt: expect.any(Number),
archivedBy: { type: "human", id: "profile-ada" },
});
},
);
} finally {
projection.dispose();
}

View file

@ -47,7 +47,7 @@ import {
type SessionsPreviewEntry,
type SessionsPreviewResult,
} from "../session-utils.js";
import { resolveSessionKeyFromResolveParams } from "../sessions-resolve.js";
import { withPreparedSessionResolve } from "../sessions-resolve.js";
import { gatewayClientSessionCreator } from "./gateway-client-identity.js";
import { withSessionListDiagnostics } from "./sessions-list-diagnostics.js";
import { sessionMaintenanceHandlers } from "./sessions-maintenance.js";
@ -428,7 +428,7 @@ export const sessionReadHandlers: GatewayRequestHandlers = {
},
);
},
"sessions.resolve": ({ params, respond, context, client }) => {
"sessions.resolve": async ({ params, respond, context, client }) => {
if (!assertValidParams(params, validateSessionsResolveParams, "sessions.resolve", respond)) {
return;
}
@ -436,24 +436,29 @@ export const sessionReadHandlers: GatewayRequestHandlers = {
if (!projection) {
throw new Error("Session projection is unavailable before Gateway startup completes");
}
const resolved = resolveSessionKeyFromResolveParams({
projection,
client,
p: params,
});
if (!resolved.ok) {
respond(false, undefined, resolved.error);
return;
}
if ("missing" in resolved) {
respond(true, { ok: false }, undefined);
return;
}
if ("ambiguous" in resolved) {
respond(true, { ok: false, candidates: resolved.candidates }, undefined);
return;
}
respond(true, resolved, undefined);
await withPreparedSessionResolve(
{
projection,
client,
p: params,
isCurrent: () => getSessionRowProjection(context) === projection,
},
(resolved) => {
if (!resolved.ok) {
respond(false, undefined, resolved.error);
return;
}
if ("missing" in resolved) {
respond(true, { ok: false }, undefined);
return;
}
if ("ambiguous" in resolved) {
respond(true, { ok: false, candidates: resolved.candidates }, undefined);
return;
}
respond(true, resolved, undefined);
},
);
},
...sessionByKeyReadHandlers,
...sessionMaintenanceHandlers,

View file

@ -7,6 +7,7 @@ import { searchSessionTranscripts } from "../../config/sessions/session-transcri
import type { SessionStoreTarget } from "../../config/sessions/targets.js";
import { runSynchronousWork } from "../../shared/synchronous-work.js";
import { filterSessionEntries } from "../session-list-filters.js";
import { withReadySessionRows } from "../session-row-prepared-read.js";
import { getSessionRowProjection } from "../session-row-projection-access.js";
import { prepareProjectedSessionList } from "../session-utils-list.js";
import type { GatewayClient, GatewayRequestContext } from "./types.js";
@ -55,6 +56,34 @@ export async function searchProjectedSessionTranscripts(params: {
return { stores, presentation };
};
const limit = params.limit ?? 10;
const sameSelection = (previous: ReturnType<typeof select>, current: ReturnType<typeof select>) =>
previous.stores.size === current.stores.size &&
[...previous.stores].every(([path, store]) => {
const next = current.stores.get(path);
return (
next !== undefined &&
store.target.agentId === next.target.agentId &&
store.rows.size === next.rows.size &&
[...store.rows].every(([key, row]) => next.rows.get(key)?.generation === row.generation)
);
});
const matchingHits = (
selected: ReturnType<typeof select>,
pages: Array<{ path: string; page: Awaited<ReturnType<typeof searchSessionTranscripts>> }>,
) =>
pages
.flatMap(({ path, page }) =>
page.hits.flatMap((hit) => {
const row = selected.stores.get(path)?.rows.get(hit.sessionKey);
return row ? [{ hit, row }] : [];
}),
)
.toSorted(
(left, right) =>
right.hit.score - left.hit.score ||
right.hit.timestamp - left.hit.timestamp ||
left.hit.messageId.localeCompare(right.hit.messageId),
);
for (let attempt = 0; attempt < 2; attempt++) {
do {
await projection.ensureMaterialized();
@ -84,55 +113,61 @@ export async function searchProjectedSessionTranscripts(params: {
// Reacquire viewer identity, roles, sharing, and presentation after the await.
// A changed scope invalidates the entire page, including counts and truncation.
const current = select();
if (
selected.stores.size !== current.stores.size ||
[...selected.stores].some(([path, store]) => {
const next = current.stores.get(path);
return (
!next ||
store.target.agentId !== next.target.agentId ||
store.rows.size !== next.rows.size ||
[...store.rows].some(([key, row]) => next.rows.get(key)?.generation !== row.generation)
);
})
) {
if (!sameSelection(selected, current)) {
continue;
}
const hits = pages
.flatMap(({ path, page }) =>
page.hits.flatMap((hit) => {
const row = current.stores.get(path)?.rows.get(hit.sessionKey);
return row ? [{ hit, row }] : [];
}),
)
.toSorted(
(left, right) =>
right.hit.score - left.hit.score ||
right.hit.timestamp - left.hit.timestamp ||
left.hit.messageId.localeCompare(right.hit.messageId),
);
const matches = hits.slice(0, limit);
const rows = new Set(matches.map((match) => match.row));
projection.setArchivePageSize(rows.size);
const sessions = [...rows].flatMap((target) => {
const record = projection.describe({ ...target, storePath: target.storeTarget.storePath });
const row = record && current.presentation.present(record);
return row ? [row] : [];
});
const archivedTranscriptsExcluded = pages.reduce(
(count, { page }) => count + (page.archivedTranscriptsExcluded ?? 0),
0,
const matchedRows = new Set(
matchingHits(current, pages)
.slice(0, limit)
.map(({ row }) => row),
);
params.onResult({
results: matches.map((match) => match.hit),
sessions,
...(pages.some(({ page }) => page.indexing) ? { indexing: true } : {}),
...(archivedTranscriptsExcluded ? { archivedTranscriptsExcluded } : {}),
...(hits.length > limit || pages.some(({ page }) => page.truncated)
? { truncated: true }
: {}),
});
return;
projection.setArchivePageSize(matchedRows.size);
const published = await withReadySessionRows(
projection,
() =>
[...matchedRows].map((row) => ({
agentId: row.agentId,
key: row.key,
storePath: row.storeTarget.storePath,
})),
(read) => {
if (getSessionRowProjection(params.context) !== projection) {
throw new Error("Session search owner changed while reading; retry the request");
}
const refreshed = select();
if (!sameSelection(selected, refreshed)) {
return false;
}
const hits = matchingHits(refreshed, pages);
const matches = hits.slice(0, limit);
const rows = new Set(matches.map((match) => match.row));
const sessions = [...rows].flatMap((target) => {
const record = read.describe({
...target,
storePath: target.storeTarget.storePath,
});
const row = record && refreshed.presentation.present(record);
return row ? [row] : [];
});
const archivedTranscriptsExcluded = pages.reduce(
(count, { page }) => count + (page.archivedTranscriptsExcluded ?? 0),
0,
);
params.onResult({
results: matches.map((match) => match.hit),
sessions,
...(pages.some(({ page }) => page.indexing) ? { indexing: true } : {}),
...(archivedTranscriptsExcluded ? { archivedTranscriptsExcluded } : {}),
...(hits.length > limit || pages.some(({ page }) => page.truncated)
? { truncated: true }
: {}),
});
return true;
},
);
if (published) {
return;
}
}
throw new Error("Session search scope changed while reading; retry the request");
}

View file

@ -447,3 +447,36 @@ test("search discards hits and page metadata when sharing is revoked during its
}
});
});
test("search materializes archived hits and rechecks visibility after exact preparation", async () => {
await withOpenClawTestState({ scenario: "minimal" }, async () => {
try {
const viewer = ensureProfileForEmail("archived-search@example.test").id;
const key = await seed("main", "archived-hit", "foreign", "needle", { archivedAt: 1 });
const context = requestContext({ agents: { list: [{ id: "main", default: true }] } });
const client = identifiedClient(viewer);
const params = { query: "needle", scope: { archived: "all" } };
expect(await search(context, client, params)).toMatchObject({
ok: true,
payload: { results: [{ sessionKey: key }], sessions: [{ key }] },
});
const projection = expectDefined(getSessionRowProjection(context), "search projection");
const prepare = projection.withPreparedExactRows.bind(projection);
vi.spyOn(projection, "withPreparedExactRows").mockImplementationOnce(
async (queries, consume, options) => {
await upsertSessionEntryCore(
{ agentId: "main", sessionKey: key },
{ visibility: "draft" },
);
return prepare(queries, consume, options);
},
);
expect(await search(context, client, params)).toMatchObject({
ok: true,
payload: { results: [], sessions: [] },
});
} finally {
await disposeSessionReadContexts();
}
});
});

View file

@ -240,6 +240,10 @@ describe("startGatewayEventSubscriptions", () => {
const projection = {
capture: () => current,
ensureMaterialized: () => prepared.promise,
withPreparedExactRows: async (_queries: unknown, consume: (read: unknown) => unknown) => {
await prepared.promise;
return { kind: "complete" as const, value: consume(undefined) };
},
isCurrent: (record: typeof original) => record === current,
snapshot: () => ({ row: current ? { key: "agent:main:queued", ...current } : null }),
} as unknown as SessionRowProjection;

View file

@ -0,0 +1,43 @@
import { expect, it, vi } from "vitest";
import { setRuntimeConfigSnapshot } from "../config/config.js";
import { replaceSessionEntrySync } from "../config/sessions/session-accessor.js";
import { withOpenClawTestState } from "../test-utils/openclaw-test-state.js";
import { withPreparedSessionEventRow } from "./session-event-prepared-row.js";
import { retainSessionListForegroundWork } from "./session-projection-work.js";
import { createSessionRowProjection } from "./session-row-projection.js";
it("publishes without forwarding the prepared view while exact rows and ancestors are ready", async () => {
await withOpenClawTestState({ scenario: "minimal" }, async () => {
const cfg = { agents: { list: [{ id: "main", default: true }] } };
setRuntimeConfigSnapshot(cfg);
const parentKey = "agent:main:event-parent";
const childKey = "agent:main:event-child";
replaceSessionEntrySync(
{ agentId: "main", sessionKey: parentKey },
{ sessionId: "parent", updatedAt: 1, archivedAt: 1 },
);
replaceSessionEntrySync(
{ agentId: "main", sessionKey: childKey },
{ sessionId: "child", updatedAt: 1, archivedAt: 1, spawnedBy: parentKey },
);
const release = retainSessionListForegroundWork();
const projection = await createSessionRowProjection({ cfg });
try {
await projection.ensureMaterialized();
expect(projection.materializedCount).toBe(0);
const publish = vi.fn((..._args: unknown[]) => {
const row = projection.describe({ key: childKey, agentId: "main" });
expect(row?.entry.sessionId).toBe("child");
expect(
row && projection.ancestorRows(row)?.map((ancestor) => ancestor.entry.sessionId),
).toEqual(["parent"]);
});
await withPreparedSessionEventRow(projection, childKey, "main", publish);
expect(publish).toHaveBeenCalledTimes(1);
expect(publish.mock.calls[0]?.length).toBe(0);
} finally {
projection.dispose();
release();
}
});
});

View file

@ -0,0 +1,34 @@
import { getRuntimeConfig } from "../config/io.js";
import { resolveSessionEventAgentScope } from "./session-request-agent.js";
import { withReadySessionRows } from "./session-row-prepared-read.js";
import type { SessionRowProjection } from "./session-row-projection.js";
export async function withPreparedSessionEventRow(
projection: SessionRowProjection | undefined,
sessionKey: string,
eventAgentId: string | undefined,
publish: () => void,
) {
if (!projection) {
publish();
return;
}
const routingAgentId = resolveSessionEventAgentScope(
getRuntimeConfig(),
sessionKey,
eventAgentId,
)?.[1];
if (routingAgentId) {
await withReadySessionRows(
projection,
() => [{ key: sessionKey, agentId: routingAgentId }],
() => publish(),
{ includeAncestors: true },
);
return;
}
do {
await projection.ensureMaterialized();
} while (projection.needsMaterialization);
publish();
}

View file

@ -1,7 +1,6 @@
import type { GatewayClient, GatewayRequestContext } from "./server-methods/types.js";
import { prepareProjectedSessionPresentation } from "./session-row-presentation.js";
import { getSessionRowProjection } from "./session-row-projection-access.js";
import { isGatewayAdmin } from "./session-sharing.js";
import { isGatewayAdmin, prepareProjectedSessionSharing } from "./session-sharing.js";
import { resolveSessionStoreAgentId } from "./session-store-key.js";
/** Keep shared group settings visible only where every member session is mutable. */
@ -24,7 +23,12 @@ export async function filterMutableSessionGroupRecords<T extends { name: string
await projection.prepareMembership();
} while (projection.needsMembershipPreparation());
const records = params.records();
const prepared = prepareProjectedSessionPresentation(projection, params.client);
const sharing = prepareProjectedSessionSharing({
cfg: projection.state.policyConfig,
client: params.client,
isMember: (target, identityId) =>
projection.hasMembership(target.storePath, target.storeKey, identityId),
});
const allowed = new Set(records.map((record) => record.name));
for (const [name, targetRefs] of projection.sessionGroupTargets()) {
if (!allowed.has(name)) {
@ -32,8 +36,8 @@ export async function filterMutableSessionGroupRecords<T extends { name: string
}
for (const ref of targetRefs) {
const agentId = resolveSessionStoreAgentId(projection.state.cfg, ref.sessionKey, ref.agentId);
const target = prepared.target({ agentId, key: ref.sessionKey });
if (!target || prepared.sharing.authorizeTarget(target)) {
const target = projection.sharingTarget({ agentId, key: ref.sessionKey });
if (!target || sharing.authorizeTarget(target)) {
allowed.delete(name);
break;
}

View file

@ -16,6 +16,7 @@ function placementReadView() {
},
describe: () => undefined,
readSource: () => undefined,
readMembership: () => undefined,
selectEntries: () => [],
present: () => {
throw new Error("Placement lifecycle does not present session rows");
@ -278,3 +279,60 @@ it("keeps resident preparation ahead of later exact demand in the accepted FIFO"
await Promise.all(accepted);
}
});
it.each([false, true])(
"reuses an owned exact snapshot when its row becomes resident (invalidated=%s)",
async (invalidated) => {
const { projection, query, lookup } = placementReadView();
const id = "materializing-exact-placement";
const materializing = createDeferredCore();
const releaseMaterialization = createDeferredCore();
const dispatched: string[][] = [];
let reconciling = false;
let rowsPrepared = false;
const owner = createSessionRowPlacementProjection(
{
async readProjection(ids) {
dispatched.push([...ids]);
return placementSnapshot(reconciling ? ids : []);
},
},
() => undefined,
);
const reading = owner.withPreparedRows(
projection,
() => true,
lookup,
() => [query(id)],
() => {
if (rowsPrepared) {
return undefined;
}
rowsPrepared = true;
materializing.resolve();
return releaseMaterialization.promise;
},
() => owner.getProjectionFacts(id)?.workspaceResultReconciling,
);
const settled = Promise.allSettled([reading]);
try {
await withTestTimeout(materializing.promise, 2_000, "Exact row preparation did not enter");
if (invalidated) {
reconciling = true;
owner.invalidate(id);
}
// Materialization publishes the resident row before exact preparation ends.
// A publication before registration must prevent adoption of the old lease.
owner.register(id);
await owner.prepare();
expect(dispatched).toEqual(invalidated ? [[id], [id]] : [[id]]);
releaseMaterialization.resolve();
expect(await reading).toEqual({ kind: "complete", value: invalidated });
expect(owner.getProjectionFacts(id)?.workspaceResultReconciling).toBe(invalidated);
} finally {
owner.dispose();
releaseMaterialization.resolve();
await settled;
}
},
);

View file

@ -12,6 +12,7 @@ export type SessionRowPreparationOptions = { includeAncestors?: boolean };
export type SessionRowReadView = {
describe(query: records.Lookup, captured?: records.Row): records.MaterializedRow | undefined;
readSource(row: records.MaterializedRow): CapturedSessionEntryReadSource | undefined;
readMembership(query: records.Lookup): ReadonlySet<string> | undefined;
present(
record: records.MaterializedRow,
options?: records.SnapshotOptions,
@ -131,6 +132,17 @@ function consumePreparedSessionRows<T>(
const row = privateRows.get(key);
return captured && !records.isCurrentGeneration(captured, row) ? undefined : row;
},
readMembership(query) {
assertActive();
const key = privateKey(query);
if (key) {
if (!privateRows.has(key)) {
throw new Error("Incognito session description was not prepared");
}
return privateRows.get(key)?.membership;
}
return owner.readMembership(query);
},
present(record, options) {
assertActive();
return owner.present(record, options);

View file

@ -59,12 +59,12 @@ export function prepareProjectedSessionPresentation(
client: client ?? null,
isMember: (value, identityId) =>
projection
.describe({
.readMembership({
agentId: value.agentId,
key: value.storeKey,
storePath: value.storePath,
})
?.membership.has(identityId) ?? false,
?.has(identityId) ?? false,
});
const profile = gatewayClientSessionCreator(client ?? null);
const profiles = rowContext.userProfileIdentityById;

View file

@ -16,7 +16,6 @@ export function createSessionRowProjectionArchive(params: {
enqueue: (id: string, change?: SessionRowChange) => void;
put: (row: records.Row) => void;
release: (id: string) => void;
prepare: (row: records.Row) => records.Row | undefined;
config: () => records.Inputs["cfg"];
context: () => Parameters<typeof records.readSessionRowLineage>[3];
referenced: NonNullable<Parameters<typeof records.readSessionRowLineage>[4]>;
@ -189,7 +188,7 @@ export function createSessionRowProjectionArchive(params: {
if (initial?.entry?.archivedAt === undefined) {
return initial;
}
const row = records.ready(initial) ? initial : params.prepare(initial);
const row = initial;
if (records.ready(row) && row.entry.archivedAt !== undefined) {
const id = records.identity(row);
materialized.delete(id);

View file

@ -148,7 +148,11 @@ async function withAcceptedSuffix(
try {
await projection.ensureMaterialized();
const query = { agentId: "main", key: keys[1]! };
const previous = projection.describe(query)!;
const previous = await withReadySessionRows(
projection,
() => [query],
(read) => read.describe(query)!,
);
const count = projection.materializedCount;
const releases: string[] = [];
const continuations: SharedArrayBuffer[] = [];
@ -945,7 +949,13 @@ it("demotes an accepted suffix without rendering it during the bulk drain", asyn
expect(isColdArchivedSessionRow(cold)).toBe(true);
expect(cold.pendingDatabaseFacts).toBeUndefined();
expect(projection.dirtyRowCount).toBe(0);
expect(projection.snapshot(query).row?.label).toBe("archived suffix");
await withReadySessionRows(
projection,
() => [query],
() => {
expect(projection.snapshot(query).row?.label).toBe("archived suffix");
},
);
});
});

View file

@ -13,6 +13,7 @@ import {
canRunSessionListBackgroundWork,
retainSessionListForegroundWork,
} from "./session-projection-work.js";
import { withReadySessionRows } from "./session-row-prepared-read.js";
import * as materialization from "./session-row-projection-materialize.js";
import * as databaseFactsRead from "./session-row-projection-read.js";
import * as records from "./session-row-projection-record.js";
@ -25,6 +26,17 @@ afterEach(() => vi.restoreAllMocks());
const { ready } = records;
type Projection = Awaited<ReturnType<typeof createSessionRowProjection>>;
type SnapshotQuery = Parameters<Projection["snapshot"]>[0];
function preparedSnapshot(projection: Projection, query: SnapshotQuery) {
return withReadySessionRows(
projection,
() => [query],
() => projection.snapshot(query),
);
}
it("keeps archived rows cold at hydration and across broad refreshes", async () => {
await withOpenClawTestState({ scenario: "minimal" }, async () => {
const cfg = { agents: { list: [{ id: "main", default: true }] } };
@ -209,7 +221,7 @@ it("promotes unarchived rows, demotes archived rows, and refreshes only requeste
sessionChanges.emit(target);
await projection.ensureMaterialized();
expect(projection.materializedCount).toBe(0);
expect(projection.snapshot({ agentId: "main", key }).row).toMatchObject({
expect((await preparedSnapshot(projection, { agentId: "main", key })).row).toMatchObject({
key,
archivedAt: 1,
});
@ -217,7 +229,9 @@ it("promotes unarchived rows, demotes archived rows, and refreshes only requeste
replaceSessionEntrySync(target, { ...entry, archivedAt: 1, label: "Updated archive" });
await projection.ensureMaterialized();
expect(projection.materializedCount).toBe(2);
expect(projection.snapshot({ agentId: "main", key }).row?.label).toBe("Updated archive");
expect((await preparedSnapshot(projection, { agentId: "main", key })).row?.label).toBe(
"Updated archive",
);
sessionChanges.emit({ all: true, scope: "catalog" });
await projection.ensureMaterialized();
@ -236,7 +250,9 @@ it("promotes unarchived rows, demotes archived rows, and refreshes only requeste
expect(projection.selectEntries().filter(ready)).toHaveLength(0);
await projection.ensureMaterialized();
expect(projection.materializedCount).toBe(3);
expect(projection.snapshot({ agentId: "main", key }).row?.archivedAt).toBe(2);
expect((await preparedSnapshot(projection, { agentId: "main", key })).row?.archivedAt).toBe(
2,
);
expect(projection.materializedCount).toBe(4);
} finally {
projection.dispose();
@ -277,7 +293,7 @@ it("bounds archived residency across pages and evicts the least recently read ro
expect(projection.selectEntries().filter(ready)).toHaveLength(100);
const query = { agentId: "main", key: "agent:main:archive-127" };
expect(projection.capture(query)?.materialized).toBeUndefined();
expect(projection.snapshot(query).row?.sessionId).toBe("archive-127");
expect((await preparedSnapshot(projection, query)).row?.sessionId).toBe("archive-127");
expect(projection.materializedCount).toBe(129);
expect(projection.selectEntries().filter(ready)).toHaveLength(100);
const pagePrepared = createDeferredCore();
@ -427,7 +443,7 @@ it("backfills only requested archives and discards enrichment after demotion", a
expect(backfill.mock.calls[0]?.[0].sessionKey).toBe("agent:main:live");
const query = { agentId: "main", key: "agent:main:archived" };
expect(projection.capture(query)?.materialized).toBeUndefined();
expect(projection.snapshot(query).row?.sessionId).toBe("archived");
expect((await preparedSnapshot(projection, query)).row?.sessionId).toBe("archived");
await vi.waitFor(() => expect(backfill).toHaveBeenCalledTimes(2));
sessionChanges.emit({ all: true, scope: "catalog" });
await projection.ensureMaterialized();
@ -510,7 +526,9 @@ it("expires archives read while a newer catalog is still loading", async () => {
try {
refresh = true;
sessionChanges.emit({ all: true, scope: "catalog" });
expect(projection.snapshot({ agentId: "main", key }).row?.contextTokens).toBe(8192);
expect(
(await preparedSnapshot(projection, { agentId: "main", key })).row?.contextTokens,
).toBe(8192);
expect(projection.materializedCount).toBe(1);
loading.resolve([{ ...catalog[0]!, contextWindow: 16384, contextTokens: 16384 }]);
await loading.promise;
@ -519,7 +537,9 @@ it("expires archives read while a newer catalog is still loading", async () => {
expect(projection.selectEntries().filter(ready)).toHaveLength(0);
await projection.ensureMaterialized();
expect(projection.materializedCount).toBe(1);
expect(projection.snapshot({ agentId: "main", key }).row?.contextTokens).toBe(16384);
expect(
(await preparedSnapshot(projection, { agentId: "main", key })).row?.contextTokens,
).toBe(16384);
expect(projection.materializedCount).toBe(2);
} finally {
loading.resolve(catalog);

View file

@ -159,6 +159,7 @@ export function createSessionRowProjectionFixture(params: {
),
describe,
readSource: () => undefined,
readMembership: (query) => describe(query)?.membership,
// This row-only fixture cannot certify the resident owner's complete ancestry graph.
ancestorRows: () => undefined,
setArchivePageSize: () => {},

View file

@ -145,14 +145,6 @@ export async function createSessionRowProjection(params: records.ProjectionOptio
backfill.remove(id);
dirty.delete(id);
},
prepare(row) {
metadata.prepare(epoch, cfg, matching, put, referenced);
const current = acquireEntry(row, readSessionRowEntry(row));
if (current && materialize(current)) {
backfill.enqueue(records.identity(current));
}
return current;
},
});
const markRelated = (row: records.Row, includeChildren = true) =>
archive.markRelated(row, indexes, includeChildren);
@ -633,6 +625,17 @@ export async function createSessionRowProjection(params: records.ProjectionOptio
return findSessionRowById(query, { disposed, lookup, matching });
},
describe,
readMembership(query: records.Lookup) {
if (disposed) {
return undefined;
}
const row = lookup(query);
if (row && isIncognitoSessionKey(row.key)) {
return describe(query)?.membership;
}
const members = row && membership.membership(row.storeTarget.storePath, row.key);
return members ? new Set(members) : undefined;
},
...createSessionRowAncestorReads({
state: () => ({ cfg, context: metadata.current }),
referenced,

View file

@ -1,8 +1,15 @@
import { expectDefined } from "@openclaw/normalization-core";
import { afterEach, describe, expect, it, vi } from "vitest";
import { trackSqliteStatementExecutions } from "../../test/helpers/sqlite-statement-execution-counter.js";
import {
observeHostDataSql,
trackSqliteStatementExecutions,
} from "../../test/helpers/sqlite-statement-execution-counter.js";
import { AgentSelectionRequiredError } from "../agents/agent-scope.js";
import { loadSessionEntry, upsertSessionEntryCore } from "../config/sessions/session-accessor.js";
import {
addSessionMember,
removeSessionMember,
} from "../config/sessions/session-sharing-store.native.js";
import * as workerAdmission from "../infra/sqlite-worker-operation-admission.js";
import {
closeOpenClawAgentDatabasesForTest,
@ -41,11 +48,13 @@ afterEach(async () => {
describe("session sharing group mutations", () => {
it.each([
{ retiredOwner: false, logicalAgent: "research", discoveryAgent: "main" },
{ retiredOwner: true, logicalAgent: "ops", discoveryAgent: "ops" },
{ retiredOwner: false, logicalAgent: "research", discoveryAgent: "main", archived: false },
{ retiredOwner: false, logicalAgent: "research", discoveryAgent: "main", archived: true },
{ retiredOwner: true, logicalAgent: "ops", discoveryAgent: "ops", archived: false },
{ retiredOwner: true, logicalAgent: "ops", discoveryAgent: "ops", archived: true },
])(
"preserves shared-store group selection and defaults access (retired physical owner=$retiredOwner)",
async ({ retiredOwner, logicalAgent, discoveryAgent }) => {
"preserves shared-store group selection and defaults access (retired physical owner=$retiredOwner, archived=$archived)",
async ({ retiredOwner, logicalAgent, discoveryAgent, archived }) => {
await withOpenClawTestState({ scenario: "minimal" }, async (state) => {
const storePath = state.statePath("shared.sqlite");
const cfg = {
@ -58,14 +67,13 @@ describe("session sharing group mutations", () => {
};
openOpenClawAgentDatabase({ agentId: "main", path: storePath });
const sessionKey = `agent:${logicalAgent}:group-member`;
await upsertSessionEntryCore(
{ agentId: logicalAgent, storePath, sessionKey },
{
sessionId: "research-group-member",
updatedAt: 1,
category: "Research",
},
);
const scope = { agentId: logicalAgent, storePath, sessionKey };
await upsertSessionEntryCore(scope, {
sessionId: "research-group-member",
updatedAt: 1,
category: "Research",
...(archived ? { archivedAt: 1 } : {}),
});
await putSessionGroups({ cfg, names: ["Research"] });
const viewer = client({ user: "viewer" });
const refs = new Map(readSessionGroupMembership(cfg, process.env).groups).get("Research");
@ -86,23 +94,50 @@ describe("session sharing group mutations", () => {
);
await projection.prepareMembership();
expect(projection.sessionGroupTargets().get("Research")).toEqual(refs);
const respond = vi.fn();
const defaults = sessionGroupHandlers["sessions.groups.defaults"]!({
params: {},
client: viewer,
context,
respond,
} as never);
const query = { agentId: logicalAgent, key: sessionKey };
const row = expectDefined(projection.capture(query), "shared-store projected row");
expect(row.storeTarget).toMatchObject({ agentId: "main", storePath });
expect(row.entry?.archivedAt).toBe(archived ? 1 : undefined);
expect(Boolean(row.materialized)).toBe(!archived);
const readDefaults = async (visible = true) => {
const respond = vi.fn();
const defaults = sessionGroupHandlers["sessions.groups.defaults"]!({
params: {},
client: viewer,
context,
respond,
} as never);
if (retiredOwner) {
await defaults;
expect(respond).toHaveBeenCalledExactlyOnceWith(
true,
{ defaults: visible ? [{ name: "Research" }] : [] },
undefined,
);
} else {
await expect(defaults).rejects.toThrow(AgentSelectionRequiredError);
expect(respond).not.toHaveBeenCalled();
}
if (archived) {
expect(projection.capture(query)?.materialized).toBeUndefined();
expect(projection.materializedCount).toBe(0);
}
};
await readDefaults();
const sql = observeHostDataSql();
try {
await readDefaults();
expect(sql.queries).toEqual([]);
} finally {
sql.restore();
}
if (retiredOwner) {
await defaults;
expect(respond).toHaveBeenCalledWith(
true,
{ defaults: [{ name: "Research" }] },
undefined,
);
} else {
await expect(defaults).rejects.toThrow(AgentSelectionRequiredError);
expect(respond).not.toHaveBeenCalled();
await upsertSessionEntryCore(scope, { visibility: "read-only" });
await readDefaults(false);
addSessionMember(scope, { identityId: "viewer", addedBy: "owner", addedAt: 1 });
await readDefaults();
removeSessionMember(scope, "viewer");
await readDefaults(false);
}
});
},

View file

@ -263,7 +263,9 @@ describe("session resolution metadata", () => {
});
await request();
const pending = request();
replaceSessionEntrySync(scope, { ...visible, visibility: "draft" });
queueMicrotask(() => {
replaceSessionEntrySync(scope, { ...visible, visibility: "draft" });
});
await pending;
await request();
@ -271,8 +273,7 @@ describe("session resolution metadata", () => {
const missing = [true, { ok: false }, undefined];
expect(publications).toHaveLength(3);
expect(publications[0]).toEqual({ visibility: "shared", response: found });
const raced = publications[1]!;
expect(raced.response).toEqual(raced.visibility === "shared" ? found : missing);
expect(publications[1]).toEqual({ visibility: "shared", response: found });
expect(publications[2]).toEqual({ visibility: "draft", response: missing });
});
});

View file

@ -19,7 +19,10 @@ import {
listProjectedSessions,
prepareSessionRowSelection,
} from "./session-utils-list.js";
import { resolveSessionKeyFromResolveParams } from "./sessions-resolve.js";
import {
resolveSessionKeyFromResolveParams,
withPreparedSessionResolve,
} from "./sessions-resolve.js";
afterEach(() => vi.restoreAllMocks());
@ -163,11 +166,14 @@ it.each(["exact", "broad"] as const)(
replaceSessionEntrySync(scope, entry);
const projection = await createSessionRowProjection({ cfg });
const resolve = (sessionId: string) =>
resolveSessionKeyFromResolveParams({
client: null,
projection,
p: { sessionId, allowMissing: true },
});
withPreparedSessionResolve(
{
client: null,
projection,
p: { sessionId, allowMissing: true },
},
(resolved) => resolved,
);
try {
await projection.ensureMaterialized();
const emit = sessionChanges.emit.bind(sessionChanges);
@ -197,9 +203,9 @@ it.each(["exact", "broad"] as const)(
} finally {
publicationSpy?.mockRestore();
}
expect(resolve("replacement-id")).toEqual({ ok: true, key, agentId: "main" });
expect(resolve(entry.sessionId)).toEqual({ ok: true, missing: true });
expect(resolve(key)).toEqual({ ok: true, key, agentId: "main" });
expect(await resolve("replacement-id")).toEqual({ ok: true, key, agentId: "main" });
expect(await resolve(entry.sessionId)).toEqual({ ok: true, missing: true });
expect(await resolve(key)).toEqual({ ok: true, key, agentId: "main" });
} finally {
projection.dispose();
}
@ -230,11 +236,14 @@ it.each(["global", "unknown"] as const)(
const client = sharingPolicyClient({ user: "viewer" });
const opts = { includeGlobal: true, includeUnknown: true };
const resolve = (sessionId: string) =>
resolveSessionKeyFromResolveParams({
client,
projection,
p: { ...opts, sessionId, allowMissing: true },
});
withPreparedSessionResolve(
{
client,
projection,
p: { ...opts, sessionId, allowMissing: true },
},
(resolved) => resolved,
);
try {
const listed = await listProjectedSessions({ projection, client, opts });
expect(listed.sessions).toMatchObject([
@ -247,24 +256,31 @@ it.each(["global", "unknown"] as const)(
projection.describe({ agentId: "main", key: sentinel, storePath: defaultPath })?.entry
.sessionId,
).toBe(shadow.sessionId);
expect(resolve(winner.sessionId)).toEqual({
expect(await resolve(winner.sessionId)).toEqual({
ok: true,
key: sentinel,
agentId: "main",
});
expect(resolve(shadow.sessionId)).toEqual({ ok: true, missing: true });
expect(await resolve(shadow.sessionId)).toEqual({ ok: true, missing: true });
for (const change of [{ archivedAt: 2 }, { visibility: "draft" as const }]) {
replaceSessionEntrySync(
{ agentId: "main", storePath: configuredPath, sessionKey: sentinel },
{ ...winner, ...change },
);
expect(resolve(winner.sessionId)).toEqual({ ok: true, missing: true });
expect(resolve(shadow.sessionId)).toEqual({ ok: true, missing: true });
expect(await resolve(winner.sessionId)).toEqual({ ok: true, missing: true });
expect(await resolve(shadow.sessionId)).toEqual({ ok: true, missing: true });
expect((await listProjectedSessions({ projection, client, opts })).sessions).toEqual([]);
expect(projection.describe({ agentId: "main", key: sentinel })?.entry.sessionId).toBe(
winner.sessionId,
);
await expect(
withPreparedSessionResolve(
{
client: null,
projection,
p: { key: sentinel, allowMissing: true },
},
() => projection.describe({ agentId: "main", key: sentinel })?.entry.sessionId,
),
).resolves.toBe(winner.sessionId);
}
} finally {
projection.dispose();
@ -278,7 +294,7 @@ it("resolves all selectors from one resident projection and sees committed label
replaceSessionEntrySync(scope, entry);
const projection = await createSessionRowProjection({ cfg });
const resolve = (p: SessionsResolveParams) =>
resolveSessionKeyFromResolveParams({ client: null, projection, p });
withPreparedSessionResolve({ client: null, projection, p }, (resolved) => resolved);
try {
await projection.ensureMaterialized();
const reads = observeMainThreadReads();
@ -290,15 +306,19 @@ it("resolves all selectors from one resident projection and sees committed label
{ shortId: "12345678" },
{ reference: { key } },
]) {
expect(resolve(p)).toMatchObject({ ok: true, key, agentId: "main" });
expect(await resolve(p)).toMatchObject({ ok: true, key, agentId: "main" });
}
reads.expectIdle();
} finally {
reads.restore();
}
replaceSessionEntrySync(scope, { ...entry, label: "Updated label" });
expect(resolve({ label: "Updated label" })).toEqual({ ok: true, key, agentId: "main" });
expect(resolve({ label: entry.label, allowMissing: true })).toEqual({
expect(await resolve({ label: "Updated label" })).toEqual({
ok: true,
key,
agentId: "main",
});
expect(await resolve({ label: entry.label, allowMissing: true })).toEqual({
ok: true,
missing: true,
});
@ -346,9 +366,9 @@ it("resolves authorized exact incognito keys without admitting them to discovery
const projection = await createSessionRowProjection({ cfg });
const client = sharingPolicyClient({ scopes: ["operator.admin"] });
const resolve = (p: SessionsResolveParams) =>
resolveSessionKeyFromResolveParams({ client, projection, p });
withPreparedSessionResolve({ client, projection, p }, (resolved) => resolved);
try {
expect(resolve({ key: incognitoKey })).toEqual({
expect(await resolve({ key: incognitoKey })).toEqual({
ok: true,
key: incognitoKey,
agentId: "main",
@ -358,7 +378,7 @@ it("resolves authorized exact incognito keys without admitting them to discovery
{ label: "Private" },
{ reference: { key: incognitoKey } },
]) {
expect(resolve({ ...selector, allowMissing: true })).toEqual({
expect(await resolve({ ...selector, allowMissing: true })).toEqual({
ok: true,
missing: true,
});
@ -376,3 +396,36 @@ it("resolves authorized exact incognito keys without admitting them to discovery
}
});
});
it("prepares a cold exact resolution and refuses consumption after its projection owner changes", async () => {
await withOpenClawTestState({ scenario: "minimal" }, async () => {
const archivedKey = "agent:main:archived-resolve";
replaceSessionEntrySync(
{ agentId: "main", sessionKey: archivedKey },
{ sessionId: "archived-resolve", updatedAt: 1, archivedAt: 1 },
);
const projection = await createSessionRowProjection({ cfg: {} });
const consume = vi.fn((result) => result);
try {
expect(projection.describe({ agentId: "main", key: archivedKey })).toBeUndefined();
await expect(
withPreparedSessionResolve({ projection, client: null, p: { key: archivedKey } }, consume),
).resolves.toMatchObject({ ok: true, key: archivedKey, agentId: "main" });
consume.mockClear();
await expect(
withPreparedSessionResolve(
{
projection,
client: null,
p: { key: archivedKey },
isCurrent: () => false,
},
consume,
),
).rejects.toThrow("Session projection changed");
expect(consume).not.toHaveBeenCalled();
} finally {
projection.dispose();
}
});
});

View file

@ -26,6 +26,7 @@ import { parseSessionLabel } from "../sessions/session-label.js";
import { hasOperatorBoundary } from "./operator-role-policy.js";
import type { GatewayClient } from "./server-methods/types.js";
import { resolveRequestedSessionAgentId } from "./session-request-agent.js";
import { withReadySessionRows } from "./session-row-prepared-read.js";
import { prepareProjectedSessionPresentation } from "./session-row-presentation.js";
import type { SessionRowProjection } from "./session-row-projection.js";
import { authorizeIncognitoSessionTarget } from "./session-sharing-policy.js";
@ -98,6 +99,38 @@ function sessionResolveCandidate(
};
}
/** Prepare durable facts, then resolve and consume against current caller state without a yield. */
export async function withPreparedSessionResolve<T>(
params: Parameters<typeof resolveSessionKeyFromResolveParams>[0] & { isCurrent?: () => boolean },
consume: (result: SessionsResolveResult) => T,
): Promise<T> {
const { projection, p } = params;
const key = normalizeOptionalString(p.key);
const assertCurrent = () => {
if (params.isCurrent?.() === false) {
throw new Error("Session projection changed while resolving the session; retry the request");
}
};
if (key) {
return withReadySessionRows(
projection,
(cfg) => {
const agent = resolveRequestedSessionAgentId(cfg, key, p.agentId);
return agent.ok ? [{ key, agentId: agent.agentId }] : [];
},
() => {
assertCurrent();
return consume(resolveSessionKeyFromResolveParams(params));
},
);
}
do {
await projection.ensureMaterialized();
assertCurrent();
} while (projection.needsMaterialization);
return consume(resolveSessionKeyFromResolveParams(params));
}
export function resolveSessionKeyFromResolveParams(params: {
client: GatewayClient | null;
projection: SessionRowProjection;

View file

@ -8,6 +8,15 @@ export type TalkConfigProjectionResponse = {
config?: { talk?: Record<string, unknown>; clientHints?: Record<string, unknown> };
};
export function createTalkConfig(apiKey: unknown): OpenClawConfig {
return {
talk: {
provider: "acme",
providers: { acme: { apiKey, voiceId: "stub-default-voice" } },
},
} as OpenClawConfig;
}
/** Runs public wire/privacy cases inside the owning handler suite's isolated harness. */
export function defineRealtimeConfigProjectionTests(
requestConfig: (

View file

@ -1,7 +1,5 @@
import { expectDefined } from "@openclaw/normalization-core";
/**
* Tests for talk gateway methods that coordinate speech and audio providers.
*/
/** Tests for talk gateway methods that coordinate speech and audio providers. */
import { afterEach, beforeEach, describe, expect, it, onTestFinished, vi } from "vitest";
import { ErrorCodes } from "../../../../packages/gateway-protocol/src/index.js";
import { createDeferred } from "../../../../test/helpers/promise.js";
@ -40,6 +38,7 @@ import { buildTalkRealtimeConfig } from "../session-config.js";
import { forgetLegacyVoiceBinding } from "./client-legacy-voice-bindings.js";
import { talkConfigAccentCases } from "./config-accent.test-support.js";
import {
createTalkConfig,
defineRealtimeConfigProjectionTests,
type TalkConfigProjectionResponse,
} from "./config-realtime.test-support.js";
@ -239,7 +238,10 @@ vi.mock("../../server-methods/chat-send-handler.js", () => ({
}));
vi.mock("../../sessions-resolve.js", () => ({
resolveSessionKeyFromResolveParams: mocks.resolveSessionKeyFromResolveParams,
withPreparedSessionResolve: async (
{ isCurrent: _isCurrent, ...params }: Record<string, unknown>,
consume: (result: unknown) => unknown,
) => consume(mocks.resolveSessionKeyFromResolveParams(params)),
}));
vi.mock("../relay/index.js", async (importOriginal) => {
@ -278,20 +280,6 @@ vi.mock("../transcription-relay.js", async (importOriginal) => {
};
});
function createTalkConfig(apiKey: unknown): OpenClawConfig {
return {
talk: {
provider: "acme",
providers: {
acme: {
apiKey,
voiceId: "stub-default-voice",
},
},
},
} as OpenClawConfig;
}
type TalkHandlerCallOptions = {
params: Record<string, unknown>;
respond: RespondFn;

View file

@ -27,7 +27,7 @@ import type { GatewayRequestHandlers, RespondFn } from "../../server-methods/typ
import { assertValidParams } from "../../server-methods/validation.js";
import { getSessionRowProjection } from "../../session-row-projection-access.js";
import { SessionMutationAuthorizationChangedError } from "../../session-sharing.js";
import { resolveSessionKeyFromResolveParams } from "../../sessions-resolve.js";
import { withPreparedSessionResolve } from "../../sessions-resolve.js";
import { formatForLog } from "../../ws-log.js";
import { resolveTalkAgentConsultAuthority } from "../client-gateway-control.js";
import { createTalkHandoff, getTalkHandoff, revokeTalkHandoff } from "../handoff.js";
@ -196,57 +196,62 @@ export const talkSessionHandlers: GatewayRequestHandlers = {
respondInvalidRequest(respond, "Session rows are initializing; try again");
return;
}
const resolvedSession = resolveSessionKeyFromResolveParams({
projection,
client,
p: {
key: target?.canonicalKey,
...(target ? { agentId: target.agentId } : {}),
...(spawnedBy ? { spawnedBy } : {}),
includeGlobal: true,
includeUnknown: true,
return await withPreparedSessionResolve(
{
projection,
client,
isCurrent: () => getSessionRowProjection(context) === projection,
p: {
key: target?.canonicalKey,
...(target ? { agentId: target.agentId } : {}),
...(spawnedBy ? { spawnedBy } : {}),
includeGlobal: true,
includeUnknown: true,
},
},
});
if (!resolvedSession.ok) {
respond(false, undefined, resolvedSession.error);
return;
}
if ("missing" in resolvedSession || "ambiguous" in resolvedSession) {
respondInvalidRequest(respond, `No session found: ${params.sessionKey}`);
return;
}
sessionMutationCommitGuard?.();
sessionMutationAuthorization?.assertCurrent();
const handoff = createTalkHandoff({
sessionKey: resolvedSession.key,
provider: normalizeOptionalString(params.provider),
model: normalizeOptionalString(params.model),
voice: normalizeOptionalString(params.voice),
mode,
transport,
brain,
ttlMs: params.ttlMs,
});
rememberUnifiedTalkSession(handoff.id, {
kind: "managed-room",
handoffId: handoff.id,
token: handoff.token,
roomId: handoff.roomId,
});
return respondOk(respond, {
sessionId: handoff.id,
provider: handoff.provider,
mode: handoff.mode,
transport: handoff.transport,
brain: handoff.brain,
handoffId: handoff.id,
roomId: handoff.roomId,
roomUrl: handoff.roomUrl,
token: handoff.token,
model: handoff.model,
voice: handoff.voice,
expiresAt: handoff.expiresAt,
});
(resolvedSession) => {
if (!resolvedSession.ok) {
respond(false, undefined, resolvedSession.error);
return;
}
if ("missing" in resolvedSession || "ambiguous" in resolvedSession) {
respondInvalidRequest(respond, `No session found: ${params.sessionKey}`);
return;
}
sessionMutationCommitGuard?.();
sessionMutationAuthorization?.assertCurrent();
const handoff = createTalkHandoff({
sessionKey: resolvedSession.key,
provider: normalizeOptionalString(params.provider),
model: normalizeOptionalString(params.model),
voice: normalizeOptionalString(params.voice),
mode,
transport,
brain,
ttlMs: params.ttlMs,
});
rememberUnifiedTalkSession(handoff.id, {
kind: "managed-room",
handoffId: handoff.id,
token: handoff.token,
roomId: handoff.roomId,
});
return respondOk(respond, {
sessionId: handoff.id,
provider: handoff.provider,
mode: handoff.mode,
transport: handoff.transport,
brain: handoff.brain,
handoffId: handoff.id,
roomId: handoff.roomId,
roomUrl: handoff.roomUrl,
token: handoff.token,
model: handoff.model,
voice: handoff.voice,
expiresAt: handoff.expiresAt,
});
},
);
}
const connId = client?.connId;

View file

@ -0,0 +1,91 @@
import { expect, it, vi, type Mock } from "vitest";
import type { EmbeddedTuiBackend } from "./embedded-backend.js";
export function registerEmbeddedHistoryProjectionTests(params: {
createBackend: () => EmbeddedTuiBackend;
loadSessionEntry: Mock;
describe: Mock;
present: Mock;
withPreparedExactRows: Mock;
buildSessionRow: Mock;
}) {
it("validates and presents history metadata within its prepared read frame", async () => {
const entry = { sessionId: "captured-session", lifecycleRevision: "captured-revision" };
const target = { key: "global", agentId: "work", storePath: "/tmp/physical.sqlite" };
params.loadSessionEntry.mockReturnValue({
cfg: {},
agentId: target.agentId,
canonicalKey: target.key,
storePath: "/tmp/logical.sqlite",
readSource: { path: target.storePath },
entry,
});
let active = false;
const row = {
get entry() {
expect(active, "history identity must be validated before the read expires").toBe(true);
return entry;
},
target,
};
const describe = vi.fn(() => row);
const present = vi.fn((current: typeof row) => {
expect(active, "history metadata must be presented before the read expires").toBe(true);
expect(current).toBe(row);
return { key: target.key, sessionId: current.entry.sessionId };
});
params.withPreparedExactRows.mockImplementationOnce(async (queries, consume) => {
expect(queries({})).toEqual([target]);
active = true;
try {
return { kind: "complete", value: consume({ describe, present }) };
} finally {
active = false;
}
});
const backend = params.createBackend();
backend.start();
try {
const result = await backend.loadHistory({ sessionKey: "global", agentId: "work" });
expect(result).toMatchObject({
sessionId: entry.sessionId,
sessionInfo: { key: target.key, sessionId: entry.sessionId },
});
expect(describe).toHaveBeenCalledExactlyOnceWith(target);
expect(present).toHaveBeenCalledExactlyOnceWith(row);
expect(params.present).not.toHaveBeenCalled();
expect(params.buildSessionRow).not.toHaveBeenCalled();
expect(active).toBe(false);
} finally {
await backend.stop();
}
});
it.each([
{ sessionId: "replacement-session", lifecycleRevision: "previous-revision" },
{ sessionId: "previous-session", lifecycleRevision: "replacement-revision" },
])("does not attach a replacement session row to captured history: %j", async (currentEntry) => {
params.loadSessionEntry.mockReturnValue({
cfg: {},
agentId: "main",
canonicalKey: "agent:main:main",
storePath: "/tmp/main.sqlite",
entry: { sessionId: "previous-session", lifecycleRevision: "previous-revision" },
});
params.describe.mockReturnValue({
entry: currentEntry,
target: { key: "agent:main:main" },
});
const backend = params.createBackend();
backend.start();
try {
const result = await backend.loadHistory({ sessionKey: "agent:main:main" });
expect(result.sessionId).toBe("previous-session");
expect(result.sessionInfo).toBeUndefined();
expect(params.present).not.toHaveBeenCalled();
expect(params.buildSessionRow).not.toHaveBeenCalled();
} finally {
await backend.stop();
}
});
}

View file

@ -20,13 +20,17 @@ import { AGENT_HARNESS_SESSION_KEY_RESERVED_MESSAGE } from "../sessions/agent-ha
import { notifyListeners } from "../shared/listeners.js";
import { withEnvAsync } from "../test-utils/env.js";
import { withOpenClawTestState } from "../test-utils/openclaw-test-state.js";
import { registerEmbeddedHistoryProjectionTests } from "./embedded-backend.history.test-support.js";
import type { EmbeddedTuiBackend as EmbeddedTuiBackendType } from "./embedded-backend.js";
import { registerEmbeddedBackendStreamTests } from "./embedded-backend.stream.test-support.js";
import {
registerEmbeddedModelCatalogTests,
withEmbeddedModelCatalogOwnerFixture,
} from "./embedded-model-catalog.test-support.js";
import { registerEmbeddedSessionReaderTests } from "./embedded-session-reader.test-support.js";
import {
createPreparedProjectionMethods,
registerEmbeddedSessionReaderTests,
} from "./embedded-session-reader.test-support.js";
import type { TuiModelChoice } from "./tui-backend.js";
type EmbeddedAgentResult = {
@ -65,10 +69,17 @@ const createGatewaySessionMock = vi.fn();
const listProjectedSessionsMock = vi.fn(
async (_options?: unknown): Promise<{ sessions: unknown[] }> => ({ sessions: [] }),
);
const preparedProjectionMethods = createPreparedProjectionMethods(() => sessionProjection);
const sessionProjection = {
...preparedProjectionMethods,
dispose: vi.fn(),
ensureMaterialized: vi.fn(async () => {}),
describe: vi.fn<(_target: unknown) => { entry: Record<string, unknown> } | undefined>(),
describe:
vi.fn<
(target: {
key: string;
}) => { entry: Record<string, unknown>; target: { key: string } } | undefined
>(),
snapshot: vi.fn<(_target: { key: string }) => { row: { key: string; sessionId: unknown } }>(),
};
const createSessionRowProjectionMock = vi.fn(async (_options?: unknown) => sessionProjection);
@ -458,10 +469,12 @@ describe("EmbeddedTuiBackend", () => {
sessionProjection.dispose.mockReset();
sessionProjection.ensureMaterialized.mockClear();
sessionProjection.describe.mockReset();
sessionProjection.describe.mockImplementation(() => {
sessionProjection.describe.mockImplementation((target) => {
const entry = loadSessionEntryMock.mock.results.at(-1)?.value?.entry;
return entry ? { entry } : undefined;
return entry ? { entry, target } : undefined;
});
sessionProjection.present.mockClear();
sessionProjection.withPreparedExactRows.mockClear();
sessionProjection.snapshot.mockReset();
sessionProjection.snapshot.mockImplementation(({ key }) => ({
row: { key, sessionId: loadSessionEntryMock.mock.results.at(-1)?.value?.entry?.sessionId },
@ -915,6 +928,15 @@ describe("EmbeddedTuiBackend", () => {
flushMicrotasks,
});
registerEmbeddedHistoryProjectionTests({
createBackend: () => new EmbeddedTuiBackend(),
loadSessionEntry: loadSessionEntryMock,
describe: sessionProjection.describe,
present: sessionProjection.present,
withPreparedExactRows: sessionProjection.withPreparedExactRows,
buildSessionRow: buildGatewaySessionRowMock,
});
it("rejects embedded session reads when the actual startup migration finds a legacy store", async () => {
await withOpenClawTestState({ scenario: "minimal" }, async (state) => {
const storePath = await state.writeText(
@ -1278,11 +1300,7 @@ describe("EmbeddedTuiBackend", () => {
expect(readChatHistoryPageMock).toHaveBeenCalledWith(
expect.objectContaining({ canonicalKey: "global", sessionAgentId: owner, entry }),
);
expect(sessionProjection.snapshot).toHaveBeenCalledWith({
key: "global",
agentId: owner,
storePath: `/tmp/openclaw-${owner}-sessions.json`,
});
expect(sessionProjection.present).toHaveBeenCalled();
expect(buildGatewaySessionRowMock).not.toHaveBeenCalled();
},
);
@ -1314,29 +1332,7 @@ describe("EmbeddedTuiBackend", () => {
skipTranscriptUsageFallback: true,
}),
);
expect(sessionProjection.snapshot).not.toHaveBeenCalled();
} finally {
await backend.stop();
}
});
it("does not attach a replacement session row to captured history", async () => {
loadSessionEntryMock.mockReturnValue({
cfg: {},
agentId: "main",
canonicalKey: "agent:main:main",
storePath: "/tmp/main.sqlite",
entry: { sessionId: "previous-session" },
});
sessionProjection.describe.mockReturnValue({ entry: { sessionId: "replacement-session" } });
const backend = new EmbeddedTuiBackend();
backend.start();
try {
const result = await backend.loadHistory({ sessionKey: "agent:main:main" });
expect(result.sessionId).toBe("previous-session");
expect(result.sessionInfo).toBeUndefined();
expect(sessionProjection.snapshot).not.toHaveBeenCalled();
expect(buildGatewaySessionRowMock).not.toHaveBeenCalled();
expect(sessionProjection.present).not.toHaveBeenCalled();
} finally {
await backend.stop();
}

View file

@ -139,7 +139,10 @@ import {
type QueuedSessionRun,
} from "./embedded-local-run.js";
import { EmbeddedPreparedModelRuntimeHost } from "./embedded-prepared-runtime.js";
import { createEmbeddedSessionReader } from "./embedded-session-reader.js";
import {
createEmbeddedSessionReader,
readEmbeddedHistorySessionInfo,
} from "./embedded-session-reader.js";
import type {
ChatSendOptions,
TuiAgentsList,
@ -573,17 +576,11 @@ export class EmbeddedTuiBackend implements TuiBackend {
const defaults = getSessionDefaults(cfg, undefined, { allowPluginNormalization: false });
const projection = await this.sessionProjection;
if (projection) {
do {
await projection.ensureMaterialized();
} while (projection.needsMaterialization);
}
const target = {
key: canonicalKey,
agentId: sessionAgentId,
storePath: readSource?.path ?? storePath,
};
const current = projection?.describe(target);
const sessionInfo =
entry && (entry.incognito || isIncognitoSessionKey(canonicalKey))
? buildGatewaySessionRow({
@ -597,11 +594,11 @@ export class EmbeddedTuiBackend implements TuiBackend {
lightweightListRow: true,
skipTranscriptUsageFallback: true,
})
: entry &&
current &&
current.entry.sessionId === sessionId &&
current.entry.lifecycleRevision === entry.lifecycleRevision
? (projection?.snapshot(target).row ?? undefined)
: entry && projection
? await readEmbeddedHistorySessionInfo(projection, target, {
sessionId,
lifecycleRevision: entry.lifecycleRevision,
})
: undefined;
const verboseLevel = entry?.verboseLevel ?? cfg.agents?.defaults?.verboseDefault;
if (sessionInfo) {

View file

@ -3,6 +3,22 @@ import { createDeferred as deferred } from "../../test/helpers/promise.js";
import { createEmbeddedCallGateway } from "../agents/tools/embedded-gateway-stub.js";
import type { EmbeddedTuiBackend } from "./embedded-backend.js";
export function createPreparedProjectionMethods(read: () => unknown) {
const methods = {
present: vi.fn((record: { entry: { sessionId?: unknown }; target: { key: string } }) => ({
key: record.target.key,
sessionId: record.entry.sessionId,
})),
withPreparedExactRows: vi.fn(
async (_queries: unknown, consume: (read: unknown) => unknown) => ({
kind: "complete" as const,
value: consume(read()),
}),
),
};
return methods;
}
export function registerEmbeddedSessionReaderTests<
Projection extends { dispose: () => void },
>(params: {

View file

@ -1,8 +1,30 @@
import type { SessionEntry } from "../config/sessions/types.js";
import { withReadySessionRows } from "../gateway/session-row-prepared-read.js";
import type * as records from "../gateway/session-row-projection-record.js";
import type { SessionRowProjection } from "../gateway/session-row-projection.js";
import { listProjectedSessions } from "../gateway/session-utils-list.js";
import { parseAgentSessionKey } from "../routing/session-key.js";
import type { TuiBackend } from "./tui-backend.js";
export function readEmbeddedHistorySessionInfo(
projection: SessionRowProjection,
target: records.Lookup,
identity: Pick<Partial<SessionEntry>, "sessionId" | "lifecycleRevision">,
) {
return withReadySessionRows(
projection,
() => [target],
(read) => {
const current = read.describe(target);
return current &&
current.entry.sessionId === identity.sessionId &&
current.entry.lifecycleRevision === identity.lifecycleRevision
? read.present(current)
: undefined;
},
);
}
export function createEmbeddedSessionReader(lifecycle: {
ready: () => Promise<void>;
projection: () => Promise<SessionRowProjection> | undefined;

View file

@ -191,6 +191,7 @@ export const gatewayDatabaseWorkerTestFiles = [
"src/gateway/setup-inference.first-signin.integration.test.ts",
"src/gateway/startup-local-cli-pairing.test.ts",
"src/gateway/talk/handlers/client-native-actions.test.ts",
"src/gateway/talk/relay/index.test.ts",
"src/gateway/test-helpers.acquisition.test.ts",
"src/gateway/tool-resolution.cron-capture.test.ts",
"src/gateway/tools-invoke-authorization.test.ts",