Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
/**
* One live agent session: the fold machine, the realtime rows that feed it,
* and the REST calls that act on it, behind one object with one event stream.
*
* Framework-free. A surface acquires the session for the ids it shows and
* releases it on unmount; every surface showing the same session shares one
* instance, so the log is fetched once, folded once, and speculated once.
*
* Speculation lives in the machine, not here. `issue` folds an action the
* moment it is sent and the machine promotes it when the log confirms it,
* rebases it when a foreign row lands first, and drops it if this class
* retracts it. Listeners only ever see fold events; whether a message is
* still on the wire is a field on the message, never a second channel.
*
* A session opened before is folded twice: first from the raw log the
* GraphQL cache holds from its last open, so the surface has a transcript
* while the fetch is on the wire, then from the fetched log, which the
* machine reconciles by row id. The exchange writes the fetched log back;
* rows the socket delivers after it are appended to the cached copy here.
*/
import { analytics } from '@app/lib/analytics';
import {
AgentFoldWorkerUnavailable,
closeSession,
type FoldInput,
pushSession,
readSession,
type SessionFoldSnapshot,
} from '@core/agent-fold/client';
import { fireAndForget } from '@core/util/fireAndForget';
import {
AgentSessionLogUnavailable,
canFollowAgentSessionLog,
forgetAgentSessionLog,
type SessionLogWatch,
watchAgentSessionLog,
} from '@queries/agent-session/log';
import { subscribeSocketSessionStarted } from '@queries/agent-session/queue-sync';
import type { AgentSessionLogEvent } from '@queries/agent-session/realtime-protocol';
import { subscribeAgentSessionUpdated } from '@queries/agent-session/session-metadata-sync';
import type {
FoldedStreamEvent,
TurnState,
} from '@service-agent-fold/generated/types';
import { agentHarnessServiceClient } from '@service-agent-harness/client';
import type {
AgentAction,
AgentSessionResponse,
ControlRequest,
SessionBot,
} from '@service-agent-harness/generated/schemas';
import { subscribeGraphqlSoupReconnected } from '@service-storage/graphql-soup';
import { CombinedError } from '@urql/core';
import { err, ok, type Result } from 'neverthrow';
import { v7 as uuidv7 } from 'uuid';
import {
type LoadFailure,
SessionLoadTrace,
traceAcquire,
transcriptSize,
} from './load-telemetry';
import { frameDelivery, PromptTrace } from './prompt-telemetry';
import { createdRecently, forgetSessionCreated } from './recently-created';
import { publishSessionTurn } from './session-turn';
export type AgentSessionListener = (events: FoldedStreamEvent[]) => void;
/** The session row and the bot it runs as, once the load resolved. */
export type AgentSessionRecord = {
session: AgentSessionResponse;
bot: SessionBot;
};
export type IssueResult = Awaited<
ReturnType<typeof agentHarnessServiceClient.control>
>;
/**
* The load was abandoned because every surface holding the session let go
* before it finished.
*
* Its own type because it is not a fault: a row that scrolls out of the list
* mid-fetch is ordinary, and a caller that cannot tell it apart from a failed
* fetch either reports a phantom error or hides a real one.
*/
export class AgentSessionReleased extends Error {
constructor(readonly sessionId: string) {
super(`agent session released: ${sessionId}`);
this.name = 'AgentSessionReleased';
}
}
/**
* The harness answered 401/403: the viewer is not a participant of this
* session. Retrying cannot help, and the surface should say so rather than
* report a connectivity problem.
*/
export class AgentSessionAccessDenied extends Error {
constructor(readonly sessionId: string) {
super(`agent session is not accessible to this user: ${sessionId}`);
this.name = 'AgentSessionAccessDenied';
}
}
/**
* The harness refused a session this tab had just created.
*
* Its own type because it is not the refusal it looks like: a create is
* answered before everything it wrote is readable, and the first read of a
* brand-new session can arrive inside that gap. Retrying is the right
* response, which is exactly what {@link AgentSessionAccessDenied} says it
* is not - so the two cannot share a type.
*/
export class AgentSessionNotReady extends Error {
constructor(readonly sessionId: string) {
super(`agent session is not readable yet: ${sessionId}`);
this.name = 'AgentSessionNotReady';
}
}
/** The log query answered that the viewer cannot see this session. */
const inaccessible = (error: unknown) =>
error instanceof AgentSessionLogUnavailable &&
error.reason === 'inaccessible';
/** Why the log query failed, for the load span. */
function logFailure(error: unknown): LoadFailure {
const cause = error instanceof Error ? error.cause : undefined;
if (cause instanceof CombinedError) {
return cause.networkError ? 'log_network' : 'log_graphql';
}
return cause === undefined ? 'log_fetch' : 'log_unreadable';
}
const accessDenied = (errors: { code: string }[]) =>
errors.some(
(error) => error.code === 'UNAUTHORIZED' || error.code === 'FORBIDDEN'
);
/**
* No session behind this id. The harness answers it apart from a refusal, so
* a read that has overtaken its own create can be told from one that is not
* this viewer's at all.
*/
const missing = (errors: { code: string }[]) =>
errors.some((error) => error.code === 'NOT_FOUND');
/**
* Whether this action takes the turn, rather than riding alongside one. ACP
* runs a prompt at a time, so these are the ones the harness queues; mirrors
* `AgentAction::occupies_turn` in `agent_runtime_protocol`.
*/
function occupiesTurn(action: AgentAction): boolean {
return action.type === 'prompt' || action.type === 'compact';
}
const RESYNC_RETRY_DELAYS_MS = [1_000, 3_000, 10_000];
/**
* Waits before re-reading a session this tab created and was refused.
*
* Front-loaded: the gap being waited out is usually milliseconds, so the
* first retry lands inside a frame or two and nobody sees anything. The tail
* is there for a create whose writes take unusually long to become readable;
* past the last one, a refusal is reported as a failed load - with a Retry -
* rather than retried forever against a session that may really be gone.
*/
const CREATE_SETTLE_RETRY_DELAYS_MS = [150, 400, 1_000, 2_500, 5_000];
export class AgentSession {
private static readonly open = new Map<string, AgentSession>();
/**
* The shared instance for `id`, created on first acquisition. Every
* acquisition needs a matching {@link release}; the last one closes the
* machine and drops the subscriptions. `hold` keeps a session open for a
* later view without being one, so it is not traced as an open.
*/
static acquire(id: string, purpose: 'view' | 'hold' = 'view'): AgentSession {
const open = AgentSession.open.get(id);
const session = open ?? new AgentSession(id);
AgentSession.open.set(id, session);
session.references += 1;
if (purpose === 'hold') return session;
traceAcquire(id, open === undefined, session.references);
// A surface opening a session that is already folded waits for nothing;
// its render is measured from now, not from the load long ago.
if (session.loaded) {
session.trace = new SessionLoadTrace(id);
session.trace.end('reused');
}
return session;
}
/** The open instance for `id`, for a caller that only wants to act on it. */
static get(id: string): AgentSession | undefined {
return AgentSession.open.get(id);
}
/**
* Realtime ingress over the connection gateway: a run of persisted rows
* in log order, addressed by session. The socket dispatch and the replay
* driver both call this; a session nobody has open ignores it, and so
* does one following its log over GraphQL, which hears the same rows
* there. The run reaches the machine as one push, so a flush of many
* frames costs one worker round trip.
*/
static ingest(event: AgentSessionLogEvent): void {
const session = AgentSession.open.get(event.agentSessionId);
if (!session || session.followed) return;
fireAndForget(
session.enqueueAll(
event.entries.map((row) => ({ kind: 'confirmed', row }))
),
'agent-session'
);
}
readonly id: string;
private references = 0;
private closed = false;
/** The fetched snapshot has been folded; inputs no longer wait for it. */
private ready = false;
/**
* The fetched log has been folded. Before this the machine may hold the
* cached log, shown but frozen: live rows wait in `buffered` and fold
* after the fetched snapshot, which cannot have lost them.
*/
private settled = false;
/**
* Live rows come from the GraphQL log subscription rather than the
* gateway. Decided once, when the session opens: the client either
* carries subscriptions or it does not.
*/
private readonly followed = canFollowAgentSessionLog();
/**
* The log query in flight for the current load: cached copy, then
* fetched; and, when followed, the subscription delivering live rows.
*/
private watch: SessionLogWatch;
/** The session row, fetched alongside the log and shared by warm and load. */
private sessionRow: Promise<
Awaited<ReturnType<typeof agentHarnessServiceClient.get>>
>;
/** Inputs that arrived before the snapshot, in order. */
private buffered: FoldInput[] = [];
private readonly listeners = new Set<AgentSessionListener>();
private readonly unsubscribeSocket: () => void;
private readonly unsubscribeUpdated: () => void;
private readonly unsubscribeReconnected: () => void;
/** The refetch in flight; it loops while another is requested. */
private syncRun?: Promise<void>;
private resyncRequested = false;
private resyncRetry = 0;
private resyncTimer?: ReturnType<typeof setTimeout>;
/**
* Serializes worker pushes so inputs reach the machine in the order this
* class saw them, even though each push is its own await.
*/
private chain: Promise<void> = Promise.resolve();
private warming: Promise<AgentSessionRecord | undefined>;
private loading: Promise<AgentSessionRecord>;
private loadFailed = false;
/** The span for the attempt in flight, ended by whatever settles it. */
private trace: SessionLoadTrace;
/**
* The fold's turn state, tracked off the same events listeners see. What
* {@link issue} reads to know whether an action will reach the runtime or
* wait in the server's queue.
*/
private turn: TurnState = 'idle';
/** Prompts issued here still waiting for their first output. */
private readonly prompts = new Set<PromptTrace>();
/** The fetched log is folded and live rows go straight in. */
get loaded(): boolean {
return this.ready && !this.loadFailed;
}
private setTurn(turn: TurnState | undefined): void {
const next = turn ?? 'idle';
this.turn = next;
publishSessionTurn(this.id, next);
}
private constructor(id: string) {
this.id = id;
// Subscribed before the fetch so no row between the two is lost: rows
// that arrive during the load are buffered and folded after the snapshot.
this.unsubscribeSocket = subscribeSocketSessionStarted(() => {
fireAndForget(this.resync(), 'agent-session');
});
this.unsubscribeUpdated = subscribeAgentSessionUpdated((event) => {
if (event.agentSessionId === this.id)
fireAndForget(this.resync(), 'agent-session');
});
// The subscription survives a reconnect, but not the rows published
// while the socket was down.
this.unsubscribeReconnected = this.followed
? subscribeGraphqlSoupReconnected(() =>
fireAndForget(this.resync(), 'agent-session')
)
: () => undefined;
this.trace = new SessionLoadTrace(id);
this.watch = this.openWatch();
this.sessionRow = agentHarnessServiceClient.get(id);
this.warming = this.startWarm();
this.loading = this.startLoad();
// A surface rendering the cached log has not called `load` yet when a
// fast failure lands, and an unobserved rejection is reported as
// unhandled. The failure still reaches every caller of `load`.
this.loading.catch(() => undefined);
}
/**
* The log query for a load, following the session when the client can:
* each run the subscription delivers folds like a gateway run would, and
* a gap in it is a reason to refetch.
*/
private openWatch(): SessionLogWatch {
return watchAgentSessionLog(
this.id,
'cache-and-network',
this.followed
? {
rows: (rows) => {
fireAndForget(
this.enqueueAll(
rows.map((row) => ({ kind: 'confirmed', row }))
),
'agent-session'
);
},
gap: () => fireAndForget(this.resync(), 'agent-session'),
}
: undefined
);
}
/**
* The session as the GraphQL cache last saw it, folded from the cached
* log: what a surface can render while {@link load} is on the wire.
* Resolves to nothing when there is no cached log, or when the fetched
* one landed first. Never fails: a cache that cannot be read is a miss.
*/
warm(): Promise<AgentSessionRecord | undefined> {
return this.warming;
}
/**
* The load: the session row and the log, fetched and folded. Resolves to
* the same record for every caller; a load that failed is re-run by the
* next call, which is how a surface's Retry works.
*/
load(): Promise<AgentSessionRecord> {
if (this.loadFailed) {
this.loadFailed = false;
this.trace = new SessionLoadTrace(this.id);
this.reissueReads();
this.loading = this.startLoad();
}
return this.loading;
}
/**
* Start the row and log reads again, for an attempt that is being made
* afresh. The old watch is stopped first: its rows belong to a load that
* is no longer the one in flight.
*/
/**
* Read the session row again, for a surface reopening a session that was
* held open since an earlier view: the fold is current, the row may not
* be. A refusal forgets the cached log, as a load's does.
*/
async readRow(): Promise<Result<AgentSessionResponse, 'denied' | 'failed'>> {
const row = await agentHarnessServiceClient.get(this.id);
if (row.isOk()) return ok(row.value);
if (!accessDenied(row.error)) return err('failed');
this.forgetCached();
return err('denied');
}
private reissueReads(): void {
this.watch.stop();
this.watch = this.openWatch();
this.sessionRow = agentHarnessServiceClient.get(this.id);
}
/**
* Do something to the agent. The action is folded before the harness
* answers, so its effect is visible at once: a prompt as a pending bubble,
* a stop as a pending Stopped line, a model change as a pending control.
* The harness's answer settles it: accepted under the same id, the
* confirmed row promotes it in place; accepted under another id, the
* speculation is reissued under that one; refused, it is retracted.
*
* An action the server will queue rather than run is not speculated at all
* - see {@link reaches} - so a waiting prompt shows in the queue and
* nowhere else.
*
* `userId` is the caller, so the pending bubble is attributed exactly as
* the confirmed row will be. A prompt is traced until its first output,
* under `trace` when the caller started one earlier.
*/
async issue(
action: AgentAction,
options: { userId?: string; trace?: PromptTrace } = {}
): Promise<IssueResult> {
const actionId = uuidv7();
const trace =
action.type === 'prompt'
? (options.trace ?? new PromptTrace(this.id, { newSession: false }))
: undefined;
const speculated = this.reaches(action);
if (speculated) {
// A prompt we just folded opens a turn, so the next one belongs in the
// queue. Recorded here rather than waited for: `turn` otherwise only
// moves when the worker answers, and two prompts sent inside that
// window would both speculate - the second one showing a bubble the
// server's `queued` then takes away again.
if (occupiesTurn(action)) this.setTurn('starting');
fireAndForget(
this.enqueue({
kind: 'speculated',
actionId,
action,
userId: options.userId,
}),
'agent-session'
);
}
// The harness adopts the id the client speculated under; the response
// names the id it was accepted under and `issue` reconciles the two.
const request: ControlRequest = { ...action, actionId };
const result = trace
? await this.sendPrompt(trace, actionId, request)
: await agentHarnessServiceClient.control(this.id, request);
if (!speculated) return result;
if (result.isErr()) {
fireAndForget(
this.enqueue({ kind: 'retracted', actionId }),
'agent-session'
);
return result;
}
// Queued after all: the turn opened between the check and the POST. The
// harness logs the row only when the queue dispatches it, so holding the
// speculation would show an open turn for the whole wait.
if (result.value.status === 'queued') {
fireAndForget(
this.enqueue({ kind: 'retracted', actionId }),
'agent-session'
);
return result;
}
// A stop is a notification and carries no id on the wire, so the log
// confirms it by content whatever id the harness accepted it under.
const accepted = result.value.actionId;
if (accepted !== actionId && action.type !== 'stop') {
fireAndForget(
this.enqueueAll([
{ kind: 'retracted', actionId },
{
kind: 'speculated',
actionId: accepted,
action,
userId: options.userId,
},
]),
'agent-session'
);
}
return result;
}
/**
* Post a prompt inside its trace, and watch the fold for its output.
* Watched from before the POST: the confirmed row can reach the socket
* before the POST's answer does.
*/
private async sendPrompt(
trace: PromptTrace,
actionId: string,
request: ControlRequest
): Promise<IssueResult> {
trace.expect(actionId);
this.prompts.add(trace);
try {
const result = await trace.run(() =>
agentHarnessServiceClient.control(this.id, request)
);
if (result.isErr()) {
trace.end(
'failed',
new Error(result.error.map((error) => error.message).join(' '))
);
} else {
const queued = result.value.status === 'queued';
trace.accepted(result.value.actionId, queued);
const attachments =
request.type === 'prompt' ? (request.attachments?.length ?? 0) : 0;
fireAndForget(
this.trackPromptSent(trace, queued, attachments),
'agent-session'
);
}
return result;
} catch (error) {
trace.end('failed', error);
throw error;
} finally {
// Released while the POST was out: nothing will observe the turn.
if (this.closed) trace.end('released');
if (trace.ended) this.prompts.delete(trace);
}
}
/**
* Count an accepted prompt as an AI message, with the files it carries as
* `attachmentCount`, as the retired AI chat reported its messages, so AI
* engagement keeps one definition across both.
*/
private async trackPromptSent(
trace: PromptTrace,
queued: boolean,
attachmentCount: number
): Promise<void> {
const row = await this.sessionRow;
analytics.track('ai_message_sent', {
surface: 'agent',
agentSessionId: this.id,
agentId: row.isOk() ? row.value.botId : undefined,
newSession: trace.newSession,
submitSurface: trace.submitSurface,
queued,
attachmentCount,
});
}
/**
* Show an action the server already holds as if it had dispatched. Nothing
* is sent: the server queued this action earlier under `actionId`, and the
* caller has just done the thing that makes it dispatch next - stopped the
* running turn. The dispatched row arrives under the same id and promotes
* the speculation in place; `retract` takes it back if the queue says the
* action is still waiting after all.
*/
expect(
actionId: string,
action: AgentAction,
options: { userId?: string } = {}
): void {
if (occupiesTurn(action)) this.setTurn('starting');
fireAndForget(
this.enqueue({
kind: 'speculated',
actionId,
action,
userId: options.userId,
}),
'agent-session'
);
}
/**
* Show a prompt another request already delivered - the create that opened
* this session can carry its first one - and trace it to its first output.
* Nothing is sent: the delivery named `actionId`, so the confirmed row
* promotes this speculation in place, or, having landed first, makes it a
* no-op.
*/
adoptPrompt(
actionId: string,
action: AgentAction,
options: { userId?: string; trace: PromptTrace }
): void {
this.expect(actionId, action, { userId: options.userId });
if (this.closed) {
options.trace.end('released');
return;
}
this.prompts.add(options.trace);
}
/** Take back a speculation the log will not confirm. Unknown ids are a no-op. */
retract(actionId: string): void {
fireAndForget(
this.enqueue({ kind: 'retracted', actionId }),
'agent-session'
);
}
/**
* Where the turn stands as this class knows it right now: the fold's last
* report, or `starting` from the moment {@link issue} or {@link expect}
* folded a prompt - ahead of the fold's own answer by the worker round
* trip. What a caller reads to decide whether an action posted now would
* reach a turn the server has opened; the listener-fed metadata lags by
* that round trip, and two actions inside it would both read the old state.
*/
currentTurn(): TurnState {
return this.turn;
}
/**
* Whether this action reaches the runtime now, rather than waiting in the
* server's queue.
*
* ACP runs one prompt at a time, so the harness queues a prompt or a
* compact issued while a turn is open and logs nothing until it dispatches.
* Speculating one anyway would show it twice - a sent-looking bubble in the
* transcript *and* the queue row that says it is waiting - and then take
* the bubble away again. Everything else (a stop, a model change, an
* answer) rides alongside the running turn and is folded at once.
*
* A disconnected runtime is not an open turn: the prompt wakes the sandbox,
* which is exactly the wait worth showing.
*/
private reaches(action: AgentAction): boolean {
if (!occupiesTurn(action)) return true;
return (
this.turn !== 'starting' &&
this.turn !== 'running' &&
this.turn !== 'stopping' &&
this.turn !== 'blocked'
);
}
/** Fold events, in order. The only way anything about the fold is observed. */
subscribe(listener: AgentSessionListener): () => void {
this.listeners.add(listener);
return () => {
this.listeners.delete(listener);
};
}
/**
* Everything the machine holds right now, for a listener that joined late.
* Ordered after every input pushed so far, so a caller that subscribes
* first and reads second misses nothing and double-applies nothing worse
* than a message it already holds.
*/
snapshot(): Promise<SessionFoldSnapshot> {
return this.chain.then(() => readSession(this.id));
}
/** Observe mounted answer DOM only while this tab awaits that prompt's paint. */
observeRenderedText(
turn: number,
element: HTMLElement
): (() => void) | undefined {
const stops = [...this.prompts].flatMap((prompt) => {
const stop = prompt.observeRenderedText(turn, element);
return stop ? [stop] : [];
});
if (stops.length === 0) return;
return () => {
for (const stop of stops) stop();
};
}
release(): void {
this.references -= 1;
if (this.references > 0) return;
if (AgentSession.open.get(this.id) === this)
AgentSession.open.delete(this.id);
this.closed = true;
// Ended here rather than where the load notices: a fetch that never
// answers never reaches that check, and an unended span never reports.
this.trace.end('released');
for (const prompt of this.prompts) prompt.end('released');
this.prompts.clear();
this.listeners.clear();
this.unsubscribeSocket();
this.unsubscribeUpdated();
this.unsubscribeReconnected();
clearTimeout(this.resyncTimer);
this.watch.stop();
closeSession(this.id);
}
private async startWarm(): Promise<AgentSessionRecord | undefined> {
const readStartedAt = performance.now();
// The cached log carries no session row, so the (small) row fetch is
// part of warming: the transcript can show only inside a session.
const [cached, session] = await Promise.all([
this.watch.cached.then((cached) => {
this.trace.cacheRead(
readStartedAt,
cached && { rows: cached.rows.length },
this.watch.cacheMiss()
);
return cached;
}),
this.sessionRow,
]);
// `settled` is set in the same tick as the fetched snapshot's push, so
// checking it here and pushing below cannot interleave with that push:
// a cached log never replaces a fetched one.
if (!cached || session.isErr() || this.closed || this.settled) {
return undefined;
}
const foldStartedAt = performance.now();
// `ready` stays false: live rows keep waiting for the fetched snapshot.
await this.apply([{ kind: 'snapshot', rows: cached.rows }]);
if (this.closed) return undefined;
this.trace.stage('cache_fold', foldStartedAt);
this.setTurn((await readSession(this.id)).metadata.turn);
return { session: session.value, bot: cached.bot };
}
/** A surface put this session's transcript on screen. */
rendered(
kind: 'cached' | 'fetched',
messages: SessionFoldSnapshot['messages']
): void {
this.trace.rendered(kind, transcriptSize(messages));
}
private startLoad(): Promise<AgentSessionRecord> {
return this.fetchFoldAndSettle().then(
(record) => {
this.trace.end('loaded');
return record;
},
(error: unknown) => {
this.loadFailed = true;
this.trace.end(
error instanceof AgentSessionReleased ? 'released' : 'failed',
error
);
throw error;
}
);
}
/**
* The load, waiting out a create that has not finished becoming readable.
*
* Only {@link AgentSessionNotReady} is retried, and only for a session this
* tab created: every other failure is reported on the first attempt, as
* before. Each attempt re-reads from scratch, because the refused answers
* are already settled promises.
*/
private async fetchFoldAndSettle(): Promise<AgentSessionRecord> {
for (let attempt = 0; ; attempt += 1) {
try {
const record = await this.fetchAndFold();
// Readable: a refusal after this is a real one.
forgetSessionCreated(this.id);
return record;
} catch (error: unknown) {
const delay = CREATE_SETTLE_RETRY_DELAYS_MS[attempt];
if (
delay === undefined ||
this.closed ||
!(error instanceof AgentSessionNotReady)
) {
throw error;
}
await new Promise((resolve) => setTimeout(resolve, delay));
if (this.closed) throw new AgentSessionReleased(this.id);
this.trace.retriedBeforeReady(attempt + 1);
this.reissueReads();
}
}
}
/**
* How a refusal should be reported.
*
* A session this tab created seconds ago is far likelier to be mid-create
* than not ours, and is retried. Anything else is a refusal in earnest, and
* its cached transcript must not be shown to this viewer again.
*/
private refused(): Error {
if (createdRecently(this.id)) {
this.trace.failing('not_ready');
return new AgentSessionNotReady(this.id);
}
this.forgetCached();
this.trace.failing('access_denied');
return new AgentSessionAccessDenied(this.id);
}
private async fetchAndFold(): Promise<AgentSessionRecord> {
const fetchStartedAt = performance.now();
const [session, log] = await Promise.all([
this.sessionRow.then((session) => {
this.trace.stage('session_fetch', fetchStartedAt);
return session;
}),
this.watch.fetched.then(
(log) => ({ ok: true as const, log }),
(error: unknown) => ({ ok: false as const, error })
),
]);
// Released mid-fetch: the stopped watch answers with a failure that is
// not one.
if (this.closed) throw new AgentSessionReleased(this.id);
if (session.isErr()) {
if (accessDenied(session.error)) throw this.refused();
// The harness knows of no such session. For one this tab just created
// that is the create still landing, and worth another read; otherwise
// it is gone, and the surface should offer a retry rather than claim
// the viewer was refused.
if (missing(session.error) && createdRecently(this.id)) {
this.trace.failing('not_ready');
throw new AgentSessionNotReady(this.id);
}
this.trace.failing('session_fetch');
throw new Error(`agent session could not be fetched: ${this.id}`);
}
if (!log.ok) {
if (inaccessible(log.error)) throw this.refused();
this.trace.failing(logFailure(log.error));
throw new Error(`agent session log could not be fetched: ${this.id}`, {
cause: log.error,
});
}
this.trace.fetched(fetchStartedAt, log.log.rows.length);
const foldStartedAt = performance.now();
this.settled = true;
try {
await this.apply([{ kind: 'snapshot', rows: log.log.rows }]);
// Inputs can keep arriving while each push is in flight; drain until a
// check finds nothing, then flip ready so the next one goes straight in.
await this.drainBuffered();
this.trace.folded(foldStartedAt);
this.setTurn((await readSession(this.id)).metadata.turn);
} catch (error) {
this.trace.failing(
error instanceof AgentFoldWorkerUnavailable
? 'worker_unavailable'
: 'fold'
);
throw error;
}
if (this.resyncRequested) fireAndForget(this.resync(), 'agent-session');
return { session: session.value, bot: log.log.bot };
}
/** The viewer was refused: nothing cached may render for them again. */
private forgetCached(): void {
this.warming = Promise.resolve(undefined);
void forgetAgentSessionLog(this.id).catch((error: unknown) => {
console.warn('[agent-session] cached log could not be removed', error);
});
}
/**
* Refetch the log and fold it, resolving once a fetch that started after
* this call has been folded. For a caller that has waited on a row the
* live feed should have delivered: the log itself settles the question.
* A failed fetch resolves too, leaving the fold as it was.
*/
refresh(): Promise<void> {
return this.resync();
}
/**
* A reopened socket is a new socket session: rows may have been missed
* while it was down. Refetch, and let the machine reconcile the overlap
* and settle any speculation the log confirmed meanwhile.
*/
private resync(retrying = false): Promise<void> {
if (this.closed) return Promise.resolve();
if (!retrying) {
clearTimeout(this.resyncTimer);
this.resyncRetry = 0;
}
this.resyncRequested = true;
// The run in flight fetches again before it ends.
if (this.syncRun) return this.syncRun;
if (!this.ready) return this.afterLoad();
this.syncRun = this.runResync();
return this.syncRun;
}
/** The load in flight starts a run after its snapshot; a failed one never does. */
private async afterLoad(): Promise<void> {
try {
await this.loading;
} catch {
return;
}
await this.syncRun;
}
private async runResync(): Promise<void> {
this.ready = false;
let failed = false;
try {
do {
this.resyncRequested = false;
let log: Awaited<SessionLogWatch['fetched']> | undefined;
try {
log = await watchAgentSessionLog(this.id, 'network-only').fetched;
} catch (error: unknown) {
failed = !inaccessible(error);
}
if (this.closed) return;
if (log) {
await this.apply([{ kind: 'snapshot', rows: log.rows }]);
this.resyncRetry = 0;
}
} while (this.resyncRequested);
} catch (error: unknown) {
failed = true;
console.warn('[agent-session] log could not be refreshed', error);
} finally {
// A snapshot may predate frames received during its fetch. Replay those
// frames after it, retaining speculation and the fold's overlap deduping.
await this.drainBuffered();
this.syncRun = undefined;
if (!this.closed && this.resyncRequested) {
await this.resync(true);
} else if (!this.closed && failed) {
const delay = RESYNC_RETRY_DELAYS_MS[this.resyncRetry++];
if (delay !== undefined)
this.resyncTimer = setTimeout(
() => fireAndForget(this.resync(true), 'agent-session'),
delay
);
}
}
}
private async drainBuffered(): Promise<void> {
while (!this.closed && this.buffered.length > 0) {
const inputs = this.buffered;
this.buffered = [];
await this.apply(inputs);
}
// No await between observing an empty buffer and accepting live inputs.
if (!this.closed) this.ready = true;
}
private enqueue(input: FoldInput): Promise<void> {
return this.enqueueAll([input]);
}
private enqueueAll(inputs: FoldInput[]): Promise<void> {
if (inputs.length === 0) return Promise.resolve();
if (!this.ready) {
this.buffered.push(...inputs);
return Promise.resolve();
}
return this.apply(inputs);
}
private apply(inputs: FoldInput[]): Promise<void> {
// Taken now, not after the chain: waiting for earlier pushes is part of
// what a prompt's fold stage costs.
const pushed = inputs.flatMap((input) =>
input.kind === 'confirmed' ? [input.row] : []
);
const snapshot = inputs.find((input) => input.kind === 'snapshot');
const delivery =
pushed.length > 0
? frameDelivery('socket', pushed)
: snapshot && frameDelivery('snapshot', snapshot.rows);
const run = this.chain.then(async () => {
if (this.closed) return;
const events = await pushSession(this.id, inputs);
if (this.closed || events.length === 0) return;
const metadata = events.findLast((event) => event.kind === 'metadata');
if (metadata) this.setTurn(metadata.metadata.turn);
for (const prompt of this.prompts) {
prompt.observe(events, delivery);
if (prompt.ended) this.prompts.delete(prompt);
}
const projectionStartedAt = performance.now();
for (const listener of this.listeners) listener(events);
if (snapshot) {
this.trace.projected(
projectionStartedAt,
events.reduce(
(count, event) =>
count +
(event.kind === 'metadata'
? 0
: event.kind === 'replace'
? event.messages.length
: 1),
0
)
);
}
});
// A failed push must not poison the chain for every input after it.
this.chain = run.catch((error: unknown) => {
console.error('[agent-session] fold input could not be applied', error);
});
return this.chain;
}
}