@cydm/happy-elves 0.1.0-beta.47 → 0.1.0-beta.49

package/apps/cli/dist/commands/turn.js

@@ -1,4 +1,4 @@
-import { CliError, ControllerClient, DEFAULT_COMMAND_TIMEOUT_MS, compactText, displayPath, ok, parseDurationMs, parsePermissionMode, printConciseEvents, readConfig, readPromptTextFile, rebuildTurnOutput, requirePositional, requireProjectedSession, requireString, structuredOutputForRunningTurn, structuredOutputForStoredTurn, structuredOutputForTurn, summarizeTurns, wantsJson, wantsVerbose, writeTurnOutput } from "./lib/index.js";
+import { CliError, ControllerClient, DEFAULT_COMMAND_TIMEOUT_MS, collectExactTurnEvents, compactText, displayPath, ok, parseDurationMs, parsePermissionMode, printConciseEvents, readConfig, readPromptTextFile, rebuildTurnOutput, requirePositional, requireProjectedSession, requireString, structuredOutputForRunningTurn, structuredOutputForStoredTurn, structuredOutputForTurn, summarizeTurns, wantsJson, wantsVerbose, writeTurnOutput } from "./lib/index.js";
 function formatTurnTimestamp(value) {
     return value === undefined ? "-" : new Date(value).toISOString();
 }
@@ -46,6 +46,9 @@ function compactTurn(turn) {
 async function readTurnSummary(client, sessionId, turnId) {
     return summarizeTurns(await client.history(sessionId, 1000)).find((turn) => turn.turnId === turnId);
 }
+async function readExactTurnSummary(client, sessionId, turnId) {
+    return summarizeTurns(await collectExactTurnEvents(client, sessionId, turnId, 1000)).find((turn) => turn.turnId === turnId);
+}
 async function resolveTurnOrCheckpointId(client, sessionId, turnOrCheckpointId) {
     const turn = await readTurnSummary(client, sessionId, turnOrCheckpointId);
     return turn?.checkpointId ?? turn?.runtimeTurnId ?? turnOrCheckpointId;
@@ -53,7 +56,7 @@ async function resolveTurnOrCheckpointId(client, sessionId, turnOrCheckpointId)
 async function waitForTurn(client, sessionId, turnId, timeoutMs) {
     const startedAt = Date.now();
     while (true) {
-        const summary = await readTurnSummary(client, sessionId, turnId);
+        const summary = await readExactTurnSummary(client, sessionId, turnId);
         if (summary && summary.status !== "running")
             return summary;
         if (Date.now() - startedAt >= timeoutMs) {

package/apps/daemon/dist/session/directory.d.ts

@@ -1,4 +1,8 @@
 import type { MachineCommand } from "../../../../packages/shared/dist/index.js";
 import type { DaemonConfig, DirectoryListResult } from "../types.js";
+export declare function availableWindowsDriveRoots(options?: {
+    platform?: NodeJS.Platform;
+    access?: (target: string) => Promise<unknown>;
+}): Promise<string[]>;
 export declare function buildDirectoryList(config: DaemonConfig, requestedPath?: string): Promise<DirectoryListResult>;
 export declare function handleListDirectory(ws: WebSocket, config: DaemonConfig, command: MachineCommand): Promise<void>;

package/apps/daemon/dist/session/directory.js

@@ -5,6 +5,7 @@ import { claimCommandRequest, sendCommandResponse } from "../relay/send.js";
 import { isUncPath, workspaceRealRoots } from "./workspace-paths.js";
 const directoryEntryLimit = 500;
 const directoryStatConcurrency = 16;
+const windowsDriveLetters = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
 async function findRepoRoot(startPath) {
     let current = startPath;
     while (true) {
@@ -40,12 +41,38 @@ async function directoryRoots(workspaceRoots, currentPath) {
     for (const root of workspaceRoots)
         await add(root);
     await add(os.homedir(), "home");
-    await add(path.parse(currentPath).root);
+    const currentRoot = path.parse(currentPath).root;
+    await add(currentRoot, filesystemRootName(currentRoot));
     const homeRoot = path.parse(os.homedir()).root;
-    if (homeRoot !== path.parse(currentPath).root)
-        await add(homeRoot);
+    if (homeRoot !== currentRoot)
+        await add(homeRoot, filesystemRootName(homeRoot));
+    for (const driveRoot of await availableWindowsDriveRoots())
+        await add(driveRoot, filesystemRootName(driveRoot));
     return roots;
 }
+export async function availableWindowsDriveRoots(options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== "win32")
+        return [];
+    const access = options.access ?? ((target) => fs.access(target));
+    const roots = await Promise.all([...windowsDriveLetters].map(async (letter) => {
+        const root = `${letter}:\\`;
+        try {
+            await access(root);
+            return root;
+        }
+        catch {
+            return undefined;
+        }
+    }));
+    return roots.filter((root) => Boolean(root));
+}
+function filesystemRootName(root) {
+    const match = /^([A-Za-z]:)[\\/]*$/u.exec(root);
+    if (match)
+        return match[1];
+    return root;
+}
 export async function buildDirectoryList(config, requestedPath) {
     if (requestedPath && isUncPath(requestedPath)) {
         throw Object.assign(new Error("UNC paths are not supported for directory browsing."), { code: "DIRECTORY_UNSUPPORTED_PATH" });

package/apps/daemon/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cydm/happy-elves-daemon",
-  "version": "0.1.0-beta.47",
+  "version": "0.1.0-beta.49",
   "private": true,
   "type": "module"
 }

package/apps/relay/dist/connections.d.ts

@@ -10,6 +10,7 @@ export type PendingCommandContext = {
     cwd?: string;
     machineId: string;
     name?: string;
+    promptHash?: string;
     recipientDeviceId?: string;
     requestId: string;
     runtimeSessionId?: string;

package/apps/relay/dist/controller-handlers.js

@@ -172,6 +172,7 @@ export function handleControllerMessage(context, connection, message) {
         markCommandPending(connection.accountId, sessionRow.machine_id, message.requestId, {
             action: "session.run",
             blocksSessionTurn: true,
+            promptHash: message.promptHash,
             recipientDeviceId: connection.deviceId ?? undefined,
             sessionId: sessionRow.id,
             turnId: message.turnId,
@@ -729,7 +730,7 @@ function controllerMessageCommandContext(message, targetMachineId) {
         case "controller:createSession":
             return { action: "session.create", agent: message.agent, cwd: message.cwd, machineId: message.machineId, name: message.name };
         case "controller:prompt":
-            return { action: "session.run", machineId: targetMachineId, sessionId: message.sessionId, turnId: message.turnId };
+            return { action: "session.run", machineId: targetMachineId, promptHash: message.promptHash, sessionId: message.sessionId, turnId: message.turnId };
         case "controller:cancel":
             return { action: "session.cancel", machineId: targetMachineId, sessionId: message.sessionId, turnId: message.turnId };
         case "controller:resume":
@@ -790,6 +791,8 @@ function pendingCommandMatchesMessage(pending, expected) {
         return false;
     if (!matchesDefined(pending.name, expected.name))
         return false;
+    if (!matchesDefined(pending.promptHash, expected.promptHash))
+        return false;
     if (!matchesDefined(pending.runtimeSessionId, expected.runtimeSessionId))
         return false;
     if (!commandSessionMatches(pending, expected))

package/apps/relay/dist/http-routes.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { encryptedEnvelopeSchema, pairingCode, randomId, } from "../../../packages/shared/dist/index.js";
-import { controllerDeviceSchema, controllerInviteClaimSchema, controllerInviteCreateSchema, deviceRevokeSchema, pairingClaimSchema, pairingStartSchema, scopedTokenCreateSchema, scopedTokenRevokeSchema, sessionHeadAdvanceSchema, sessionEventsQuerySchema, } from "./http-schemas.js";
+import { controllerDeviceSchema, controllerInviteClaimSchema, controllerInviteCreateSchema, deviceRevokeSchema, pairingClaimSchema, pairingStartSchema, scopedTokenCreateSchema, scopedTokenRevokeSchema, sessionHeadAdvanceSchema, sessionMetadataUpdateSchema, sessionEventsQuerySchema, } from "./http-schemas.js";
 import { HttpError } from "./errors.js";
 import { sessionEventLogicalMessageKey, sessionEventLogicalSeq, sessionEventLogicalSeqValue, sessionEventLogicalTime, sessionEventLogicalTimeValue, visibleSessionEventWhere, } from "./event-visibility.js";
 import { encodePairingCode, isPairingCodeMatch, tokenDigest } from "./security.js";
@@ -360,6 +360,37 @@ export function registerHttpRoutes(app, context, controllerInviteTtlMs) {
             ...(rewriteFenced ? { reason: "rewrite-fenced" } : {}),
         };
     });
+    app.patch("/api/sessions/:sessionId/metadata", async (request) => {
+        const token = context.requireFullControllerToken(request.headers.authorization);
+        const params = z.object({ sessionId: z.string().min(1) }).parse(request.params);
+        const body = sessionMetadataUpdateSchema.parse(request.body);
+        const session = context.db
+            .prepare("SELECT * FROM sessions WHERE account_id = ? AND id = ?")
+            .get(token.account_id, params.sessionId);
+        if (!session)
+            throw new HttpError(404, "SESSION_NOT_FOUND", "Session not found");
+        const ts = context.now();
+        const result = body.expectedUpdatedAt === undefined
+            ? context.db.prepare(`UPDATE sessions
+         SET encrypted_metadata = ?,
+             updated_at = ?
+         WHERE account_id = ? AND id = ?`).run(JSON.stringify(body.encryptedMetadata), ts, token.account_id, params.sessionId)
+            : context.db.prepare(`UPDATE sessions
+         SET encrypted_metadata = ?,
+             updated_at = ?
+         WHERE account_id = ? AND id = ? AND updated_at = ?`).run(JSON.stringify(body.encryptedMetadata), ts, token.account_id, params.sessionId, body.expectedUpdatedAt);
+        if (result.changes === 0) {
+            throw new HttpError(409, "SESSION_METADATA_CONFLICT", "Session metadata changed; retry with the latest session");
+        }
+        const row = context.db
+            .prepare("SELECT * FROM sessions WHERE account_id = ? AND id = ?")
+            .get(token.account_id, params.sessionId);
+        if (!row)
+            throw new HttpError(404, "SESSION_NOT_FOUND", "Session not found");
+        const snapshot = context.sessionSnapshot(row);
+        context.broadcastControllers(token.account_id, { type: "server:session", session: snapshot });
+        return { session: snapshot };
+    });
     app.get("/api/devices", async (request) => {
         const token = context.requireFullControllerToken(request.headers.authorization);
         const rows = context.db

package/apps/relay/dist/http-schemas.d.ts

@@ -69,3 +69,19 @@ export declare const sessionHeadAdvanceSchema: z.ZodObject<{
         occurredAt: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+export declare const sessionMetadataUpdateSchema: z.ZodObject<{
+    encryptedMetadata: z.ZodObject<{
+        v: z.ZodLiteral<1>;
+        alg: z.ZodLiteral<"A256GCM">;
+        scope: z.ZodString;
+        key: z.ZodObject<{
+            nonce: z.ZodString;
+            ciphertext: z.ZodString;
+        }, z.core.$strip>;
+        data: z.ZodObject<{
+            nonce: z.ZodString;
+            ciphertext: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    expectedUpdatedAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;

package/apps/relay/dist/http-schemas.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { encryptedEnvelopeSchema } from "../../../packages/shared/dist/index.js";
 export const pairingStartSchema = z.object({
     deviceId: z.string().min(1),
     deviceName: z.string().min(1),
@@ -67,3 +68,7 @@ export const sessionHeadAdvanceSchema = z.object({
         occurredAt: z.number().int().optional(),
     }),
 });
+export const sessionMetadataUpdateSchema = z.object({
+    encryptedMetadata: encryptedEnvelopeSchema,
+    expectedUpdatedAt: z.number().int().positive().optional(),
+});

package/apps/relay/dist/relay-context.js

@@ -286,6 +286,7 @@ export function createRelayContext(options) {
             ...(pending.cwd !== undefined ? { cwd: pending.cwd } : {}),
             machineId: pending.machineId,
             ...(pending.name !== undefined ? { name: pending.name } : {}),
+            ...(pending.promptHash !== undefined ? { promptHash: pending.promptHash } : {}),
             ...(pending.runtimeSessionId !== undefined ? { runtimeSessionId: pending.runtimeSessionId } : {}),
             ...(pending.sessionId !== undefined ? { sessionId: pending.sessionId } : {}),
             ...(pending.shell !== undefined ? { shell: pending.shell } : {}),
@@ -319,6 +320,7 @@ export function createRelayContext(options) {
                 ...(typeof parsed.cwd === "string" ? { cwd: parsed.cwd } : {}),
                 machineId: parsed.machineId,
                 ...(typeof parsed.name === "string" ? { name: parsed.name } : {}),
+                ...(typeof parsed.promptHash === "string" ? { promptHash: parsed.promptHash } : {}),
                 requestId: "",
                 ...(typeof parsed.runtimeSessionId === "string" ? { runtimeSessionId: parsed.runtimeSessionId } : {}),
                 ...(typeof parsed.sessionId === "string" ? { sessionId: parsed.sessionId } : {}),

package/apps/relay/dist/session-projection-reducer.js

@@ -338,7 +338,7 @@ function handleTurnDone(context, connection, message, acknowledgeMachineMessage)
             sessionId: message.sessionId,
             machineId: connection.machineId,
             requestTurnId: message.turnId,
-            runtimeTurnId: message.lastTurnId ?? message.currentHead,
+            runtimeTurnId: message.lastTurnId,
         });
     }
     const runtimeTurnId = message.lastTurnId ?? message.currentHead ?? message.turnId;

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@cydm/happy-elves",
-  "version": "0.1.0-beta.47",
+  "version": "0.1.0-beta.49",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@cydm/happy-elves",
-      "version": "0.1.0-beta.47",
+      "version": "0.1.0-beta.49",
       "license": "Apache-2.0",
       "dependencies": {
         "@fastify/cors": "11.2.0",
@@ -1021,9 +1021,9 @@
       }
     },
     "node_modules/fast-uri": {
-      "version": "3.1.2",
-      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.2.tgz",
-      "integrity": "sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ==",
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.3.tgz",
+      "integrity": "sha512-i70LwGWUduXqzicKXWshooq+sWL1K3WUU5rKZNG/0i3a1OSoX3HqhH5WbWwTmqWfor4urUakGPiRQcleRZTwOg==",
       "funding": [
         {
           "type": "github",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cydm/happy-elves",
-  "version": "0.1.0-beta.47",
+  "version": "0.1.0-beta.49",
   "description": "Remote controller for local coding agents with hosted or self-hosted relay support.",
   "type": "module",
   "bin": {

package/packages/client/dist/client.d.ts

@@ -2,6 +2,9 @@ import { type DirectoryListing, type EncryptedSessionEvent, type HistoricalSessi
 import { sendCommand } from "./transport.js";
 import { type ControllerLiveOptions, type ControllerLiveProjection } from "./live.js";
 import type { AddControllerDeviceInput, AddControllerDeviceResult, CancelInput, CollectInput, CommandResult, ControllerClientConfig, ControllerInviteClaimInput, ControllerInviteClaimResult, ControllerInviteCreateInput, ControllerInviteCreateResult, ControllerSnapshot, CreateScopedTokenInput, CreateSessionInput, DecodedSessionEvent, DecodedSessionEventsPage, DeviceListResponse, DirectoryInput, FilePreviewInput, ForkInput, HistoricalSessionListPage, HistoricalSessionsInput, ImportHistoricalSessionInput, MachineMetadata, MachineDevExecInput, MachineDevExecResponse, MachineDiagnosticsResponse, RepairSessionHeadInput, RepairSessionHeadResult, RunOptions, ScopedTokenInfo, ScopedTokenSelf, SessionFilter, SessionMetadata, WaitInput } from "./types.js";
+type UpdateSessionMetadataOptions = {
+    expectedUpdatedAt?: number;
+};
 export declare class ControllerClient {
     readonly config: ControllerClientConfig;
     constructor(config: ControllerClientConfig);
@@ -30,6 +33,7 @@ export declare class ControllerClient {
     }>;
     listSessions(filter?: SessionFilter): Promise<SessionSnapshot[]>;
     getSession(sessionId: string): Promise<SessionSnapshot | undefined>;
+    updateSessionMetadata(sessionId: string, metadata: SessionMetadata, options?: UpdateSessionMetadataOptions): Promise<SessionSnapshot>;
     history(sessionId: string, limit?: number): Promise<DecodedSessionEvent[]>;
     createSession(input: CreateSessionInput): Promise<CommandResult>;
     collect(sessionId: string, input?: CollectInput): Promise<DecodedSessionEvent[]>;
@@ -62,3 +66,4 @@ export declare class ControllerClient {
     private mergeReplayedTurnEvents;
     private sessionEvents;
 }
+export {};

package/packages/client/dist/client.js

@@ -1,12 +1,12 @@
 import { decryptJson, encryptJson, normalizeSessionName, parseServerMessage, randomId, } from "../../shared/dist/index.js";
 import { addControllerDevice, claimControllerInvite, createControllerInvite, createPairingCode, createScopedToken, listDevices, listScopedTokens, revokeDevice, revokeScopedToken, tokenSelf, } from "./account.js";
 import { ControllerClientError, ControllerCommandError } from "./errors.js";
-import { authenticatedJson, normalizeRelayUrl, readRelayJson, relayHttpError } from "./http.js";
+import { authenticatedJson, normalizeRelayUrl, readRelayJson, relayFetch, relayHttpError } from "./http.js";
 import { parseRepairSessionHeadResult, parseSessionEventsResponse, } from "./parsers.js";
 import { sendAndWaitForDirectoryListing, sendAndWaitForFilePreview, sendAndWaitForHistoricalSessions, sendAndWaitForMachineDevExecResult, sendAndWaitForMachineDiagnostics, sendCommand, } from "./transport.js";
 import { ControllerLiveProjectionImpl } from "./live.js";
 import { DEFAULT_SESSION_CREATE_WAIT_MS, } from "./types.js";
-import { isWaitCondition, matchesWaitCondition, parseEventCursor, parseEventLimit, parsePositiveDuration, requireNonEmpty, sleep, } from "./validation.js";
+import { isWaitCondition, matchesWaitCondition, parseEventCursor, parseEventLimit, parsePositiveDuration, parseSinceEventCursor, requireNonEmpty, sleep, } from "./validation.js";
 const DEFAULT_RUN_SETTLEMENT_WAIT_MS = 15_000;
 const DEFAULT_BLOCKING_RUN_WAIT_MS = 30 * 60 * 1000;
 function runSettlementTimeoutMs(options) {
@@ -16,6 +16,17 @@ function runSettlementTimeoutMs(options) {
         return options.runtimeTimeoutMs + DEFAULT_RUN_SETTLEMENT_WAIT_MS;
     return DEFAULT_BLOCKING_RUN_WAIT_MS;
 }
+function parseSessionMetadataUpdateResult(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new ControllerClientError("Session metadata response is invalid", "RELAY_RESPONSE_INVALID");
+    }
+    const session = value.session;
+    const message = parseServerMessage({ type: "server:session", session });
+    if (message.type !== "server:session") {
+        throw new ControllerClientError("Session metadata response is invalid", "RELAY_RESPONSE_INVALID");
+    }
+    return message.session;
+}
 export class ControllerClient {
     config;
     constructor(config) {
@@ -27,9 +38,9 @@ export class ControllerClient {
         };
     }
     async snapshot() {
-        const response = await fetch(`${this.config.relayUrl}/api/bootstrap`, {
+        const response = await relayFetch(`${this.config.relayUrl}/api/bootstrap`, {
             headers: { authorization: `Bearer ${this.config.controllerToken}` },
-        });
+        }, "Could not reach relay");
         if (!response.ok) {
             throw await relayHttpError(response, "Bootstrap failed");
         }
@@ -99,6 +110,19 @@ export class ControllerClient {
         const checkedSessionId = requireNonEmpty(sessionId, "sessionId");
         return (await this.snapshot()).sessions.find((session) => session.id === checkedSessionId);
     }
+    async updateSessionMetadata(sessionId, metadata, options = {}) {
+        const checkedSessionId = requireNonEmpty(sessionId, "sessionId");
+        const requestId = randomId("req");
+        const encryptedMetadata = await encryptJson(this.config.accountSecret, `session:metadata:${checkedSessionId}:${requestId}`, metadata);
+        return await authenticatedJson(this.config, `/api/sessions/${encodeURIComponent(checkedSessionId)}/metadata`, {
+            method: "PATCH",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                encryptedMetadata,
+                ...(options.expectedUpdatedAt === undefined ? {} : { expectedUpdatedAt: options.expectedUpdatedAt }),
+            }),
+        }, parseSessionMetadataUpdateResult);
+    }
     async history(sessionId, limit = 20) {
         const checkedSessionId = requireNonEmpty(sessionId, "sessionId");
         const { events } = await this.sessionEvents(checkedSessionId, { limit: parseEventLimit(limit) });
@@ -142,7 +166,7 @@ export class ControllerClient {
         const checkedSessionId = requireNonEmpty(sessionId, "sessionId");
         const before = parseEventCursor(input.before);
         const beforeCursor = input.beforeCursor;
-        const since = parseEventCursor(input.since);
+        const since = parseSinceEventCursor(input.since);
         const limit = parseEventLimit(input.limit);
         const turnId = input.turnId === undefined ? undefined : requireNonEmpty(input.turnId, "turnId");
         if (before !== undefined && beforeCursor !== undefined) {
@@ -154,6 +178,9 @@ export class ControllerClient {
         if (turnId !== undefined && (before !== undefined || beforeCursor !== undefined)) {
             throw new ControllerClientError("turnId cannot be combined with before cursors", "INVALID_ARGUMENT");
         }
+        if (turnId === undefined && typeof since === "string") {
+            throw new ControllerClientError("Logical since cursor requires turnId", "INVALID_ARGUMENT");
+        }
         const page = await this.sessionEvents(checkedSessionId, { before, beforeCursor, since, limit, turnId });
         const requestedLimit = limit ?? 20;
         const hasMoreBefore = page.hasMoreBefore ?? (since === undefined && page.events.length >= requestedLimit);
@@ -374,8 +401,8 @@ export class ControllerClient {
     async run(sessionId, text, options = {}) {
         const checkedSessionId = requireNonEmpty(sessionId, "sessionId");
         const promptText = requireNonEmpty(text, "text");
-        const requestId = randomId("req");
-        const turnId = randomId("turn");
+        const requestId = options.requestId === undefined ? randomId("req") : requireNonEmpty(options.requestId, "requestId");
+        const turnId = options.turnId === undefined ? randomId("turn") : requireNonEmpty(options.turnId, "turnId");
         const wait = options.wait ?? true;
         const timeoutMs = wait ? options.waitTimeoutMs : options.ackTimeoutMs;
         const result = await this.sendCommand({
@@ -387,6 +414,7 @@ export class ControllerClient {
                 type: "user_prompt",
                 text: promptText,
             }),
+            ...(options.promptHash === undefined ? {} : { promptHash: requireNonEmpty(options.promptHash, "promptHash") }),
             permissionMode: options.permissionMode ?? "approve-reads",
             timeoutMs: options.runtimeTimeoutMs,
         }, wait, timeoutMs);

package/packages/client/dist/http.d.ts

@@ -2,6 +2,7 @@ import { ControllerClientError } from "./errors.js";
 import type { ControllerClientConfig } from "./types.js";
 export declare function normalizeRelayUrl(value: string): string;
 export declare function wsUrl(relayUrl: string): string;
+export declare function relayFetch(input: string, init?: RequestInit, fallback?: string): Promise<Response>;
 export declare function relayHttpError(response: Response, fallback: string): Promise<ControllerClientError>;
 export declare function readRelayJson(response: Response, fallback: string): Promise<unknown>;
 export declare function authenticatedJson<T>(config: ControllerClientConfig, pathname: string, init: RequestInit, parse: (value: unknown) => T): Promise<T>;

package/packages/client/dist/http.js

@@ -24,6 +24,18 @@ export function wsUrl(relayUrl) {
     url.search = "";
     return url.toString();
 }
+function networkErrorMessage(error) {
+    const message = error instanceof Error && error.message ? error.message : String(error);
+    return message.replace(/(https?:\/\/)([^/@\s]+)@/gu, "$1");
+}
+export async function relayFetch(input, init = {}, fallback = "Could not reach relay") {
+    try {
+        return await fetch(input, init);
+    }
+    catch (error) {
+        throw new ControllerClientError(`${fallback}: ${networkErrorMessage(error)}`, "RELAY_UNREACHABLE");
+    }
+}
 export async function relayHttpError(response, fallback) {
     const text = await response.text();
     try {
@@ -60,20 +72,20 @@ export async function authenticatedJson(config, pathname, init, parse) {
     }
 }
 export async function authenticatedJsonRaw(config, pathname, init) {
-    const response = await fetch(`${config.relayUrl}${pathname}`, {
+    const response = await relayFetch(`${config.relayUrl}${pathname}`, {
         ...init,
         headers: {
             ...init.headers,
             authorization: `Bearer ${config.controllerToken}`,
         },
-    });
+    }, "Could not reach relay");
     if (!response.ok) {
         throw await relayHttpError(response, `${pathname} failed`);
     }
     return await readRelayJson(response, `${pathname} response is not valid JSON`);
 }
 export async function publicJsonRaw(config, pathname, init) {
-    const response = await fetch(`${config.relayUrl}${pathname}`, init);
+    const response = await relayFetch(`${config.relayUrl}${pathname}`, init, "Could not reach relay");
     if (!response.ok) {
         throw await relayHttpError(response, `${pathname} failed`);
     }

package/packages/client/dist/live-session-state.d.ts

@@ -0,0 +1,15 @@
+import type { DecodedSessionEvent, SessionMetadata } from "./types.js";
+import type { SessionSnapshot } from "../../shared/dist/index.js";
+export declare function isAuthoritativeSessionModel(session: SessionSnapshot | undefined): boolean;
+export declare function selectedSessionHistoryHead(session: SessionSnapshot): string;
+export declare function selectedSessionProjectionHead(session: SessionSnapshot): string;
+export declare function hasVisibleTranscriptPayload(event: DecodedSessionEvent): boolean;
+export declare function isSelectedSessionHeadMaterialized(session: SessionSnapshot, events: readonly DecodedSessionEvent[]): boolean;
+export declare function oldestEventIdForSession(events: readonly DecodedSessionEvent[], sessionId: string): number | undefined;
+export declare function newestEventIdForSession(events: readonly DecodedSessionEvent[], sessionId: string): number;
+export declare function sessionEventCount(events: readonly DecodedSessionEvent[], sessionId: string): number;
+export declare function sessionHasHistoricalBackfillEvents(events: readonly DecodedSessionEvent[], sessionId: string): boolean;
+export declare function sessionHasMissingHistoricalPrefix(session: SessionSnapshot | undefined, events: readonly DecodedSessionEvent[]): boolean;
+export declare function runtimeHistoricalBackfillCanContinue(metadata: SessionMetadata | undefined, hasMissingHistoricalPrefix: boolean): boolean;
+export declare function runtimeHistoricalBackfillKnown(metadata: SessionMetadata | undefined): boolean;
+export declare function runtimeHistoricalBackfillCompleted(metadata: SessionMetadata | undefined): boolean;

package/packages/client/dist/live-session-state.js

@@ -0,0 +1,60 @@
+import { oldestSessionEventId } from "./session-event-order.js";
+export function isAuthoritativeSessionModel(session) {
+    return session?.historyModel === "authoritative-linear";
+}
+export function selectedSessionHistoryHead(session) {
+    return [session.currentHead ?? "", session.lastTurnId ?? "", session.status, String(session.updatedAt)].join(":");
+}
+export function selectedSessionProjectionHead(session) {
+    return [session.currentHead ?? "", session.lastTurnId ?? ""].join(":");
+}
+export function hasVisibleTranscriptPayload(event) {
+    const type = event.decoded?.type;
+    return type === "user_prompt" || type === "text_delta" || type === "tool_call";
+}
+export function isSelectedSessionHeadMaterialized(session, events) {
+    const currentHead = session.currentHead || session.lastTurnId;
+    if (!currentHead)
+        return true;
+    const localEvents = events.filter((event) => event.sessionId === session.id);
+    const eventIdMatch = /^event:(\d+)$/.exec(currentHead);
+    if (eventIdMatch)
+        return localEvents.some((event) => event.id === Number(eventIdMatch[1]));
+    return localEvents.some((event) => event.turnId === currentHead ||
+        (event.decoded?.type === "done" && (event.decoded.currentHead === currentHead || event.decoded.lastTurnId === currentHead)));
+}
+export function oldestEventIdForSession(events, sessionId) {
+    return oldestSessionEventId(events, sessionId);
+}
+export function newestEventIdForSession(events, sessionId) {
+    return Math.max(0, ...events.filter((event) => event.sessionId === sessionId).map((event) => event.id));
+}
+export function sessionEventCount(events, sessionId) {
+    return events.filter((event) => event.sessionId === sessionId).length;
+}
+export function sessionHasHistoricalBackfillEvents(events, sessionId) {
+    return events.some((event) => event.sessionId === sessionId && event.messageId?.startsWith("hist_"));
+}
+export function sessionHasMissingHistoricalPrefix(session, events) {
+    if (!session?.currentHead && !session?.lastTurnId)
+        return false;
+    const turnSeqs = events
+        .filter((event) => event.sessionId === session.id && event.messageId?.startsWith("hist_") && typeof event.turnSeq === "number")
+        .map((event) => event.turnSeq);
+    return turnSeqs.length > 0 && Math.min(...turnSeqs) > 0;
+}
+export function runtimeHistoricalBackfillCanContinue(metadata, hasMissingHistoricalPrefix) {
+    const status = metadata?.historicalBackfillStatus ?? metadata?.historicalBackfill;
+    return status === "partial" || metadata?.truncatedHistoricalBackfill === true || hasMissingHistoricalPrefix;
+}
+export function runtimeHistoricalBackfillKnown(metadata) {
+    return Boolean(metadata &&
+        (metadata.historicalBackfillStatus !== undefined ||
+            metadata.historicalBackfill !== undefined ||
+            metadata.historicalBackfillCursor !== undefined ||
+            metadata.truncatedHistoricalBackfill !== undefined));
+}
+export function runtimeHistoricalBackfillCompleted(metadata) {
+    const status = metadata?.historicalBackfillStatus ?? metadata?.historicalBackfill;
+    return status === "completed" || metadata?.historicalBackfillCursor === 0;
+}

package/packages/client/dist/live-state.d.ts

@@ -0,0 +1,8 @@
+import type { ControllerLiveState } from "./live-types.js";
+export declare function cloneLiveState(state: ControllerLiveState): ControllerLiveState;
+export declare function upsertById<T extends {
+    id: string;
+}>(items: readonly T[], next: T): T[];
+export declare function sleep(ms: number): Promise<void>;
+export declare function nonEmptyLiveString(value: string, label: string): string;
+export declare function errorMessage(error: unknown): string;

package/packages/client/dist/live-state.js

@@ -0,0 +1,33 @@
+import { ControllerClientError } from "./errors.js";
+export function cloneLiveState(state) {
+    return {
+        ...state,
+        events: [...state.events],
+        machineMetadata: { ...state.machineMetadata },
+        machines: [...state.machines],
+        sessionMetadata: { ...state.sessionMetadata },
+        sessionPages: Object.fromEntries(Object.entries(state.sessionPages).map(([key, value]) => [key, { ...value }])),
+        sessions: [...state.sessions],
+    };
+}
+export function upsertById(items, next) {
+    const copy = [...items];
+    const index = copy.findIndex((item) => item.id === next.id);
+    if (index >= 0)
+        copy[index] = next;
+    else
+        copy.unshift(next);
+    return copy;
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function nonEmptyLiveString(value, label) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new ControllerClientError(`${label} must be a non-empty string`, "INVALID_ARGUMENT");
+    return trimmed;
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}