@dinoxx/dinox-cli 2.4.0 → 2.6.0

package/dist/gateway/runExecutor.js

@@ -1,10 +1,18 @@
+import os from 'node:os';
 import { AssistantProjection, projectPendingApprovals, toTranscriptMessage } from './assistantProjection.js';
-import { commitRunTerminal, enqueueRun, finishMergedRun, startQueuedRuns, withdrawQueuedRun, readCurrentTopicId, readSessionBinding, resolveTrustedResource, updateRunSnapshot, writeSessionBinding, } from './threadStore.js';
+import { CONTEXT_MESSAGE_LIMIT, withConversationContext } from './conversationContext.js';
+import { commitRunTerminal, enqueueRun, finishMergedRun, startQueuedRuns, withdrawQueuedRun, readAgentInstructions, readCurrentTopic, readSessionBinding, readTranscriptPage, resolveTrustedResource, updateRunSnapshot, waitForMessage, withGatewaySession, writeSessionBinding, } from './threadStore.js';
 import { readAgentConfig } from './protocol.js';
 const SNAPSHOT_PERSIST_INTERVAL_MS = 1_000;
 /** Turns waiting behind a thread's active one; more are refused as `busy`. */
 export const MAX_QUEUED_TURNS = 10;
 const APPROVAL_TIMEOUT_MS = 30 * 60 * 1000;
+/** The agent's instructions travel with a new session's first prompt; longer ones are cut. */
+const MAX_INSTRUCTIONS_CHARS = 8_000;
+/** How long a turn waits for the client's latest messages to sync to this machine. */
+export const CLIENT_TAIL_SYNC_TIMEOUT_MS = 5_000;
+/** Client tails that never synced, so later turns of their thread do not wait for them again. */
+const MAX_REMEMBERED_MISSING_TAILS = 200;
 export class QueueFullError extends Error {
     constructor() {
         super(`At most ${MAX_QUEUED_TURNS} messages can wait in one conversation`);
@@ -18,6 +26,20 @@ function statusForStop(stopReason) {
         return 'failed';
     return 'succeeded';
 }
+/** The user's instructions for the agent, as the start of a new session. */
+export function agentInstructionsPreamble(instructions) {
+    const text = instructions.trim();
+    if (!text)
+        return undefined;
+    const clipped = text.length > MAX_INSTRUCTIONS_CHARS ? `${text.slice(0, MAX_INSTRUCTIONS_CHARS)}…` : text;
+    return [
+        '<dinox_agent_instructions>',
+        'Instructions the user set for you in Dinox. Follow them throughout this conversation.',
+        '',
+        clipped.replaceAll('</dinox_agent_instructions>', '<\\/dinox_agent_instructions>'),
+        '</dinox_agent_instructions>',
+    ].join('\n');
+}
 function withErrorText(message, error) {
     return { ...message, metadata: { ...(message.metadata ?? {}), error } };
 }
@@ -27,6 +49,8 @@ function withErrorText(message, error) {
  * together as one turn (each keeps its own message; the reply follows the
  * last). The agent session is scoped to the thread's current topic: a "new
  * topic" marker in Dinox starts a fresh agent session, everything else continues it.
+ * The thread may have been answered by other agents meanwhile, so each turn
+ * also carries the messages this gateway's session has not seen.
  */
 export class GatewayRunExecutor {
     deps;
@@ -37,6 +61,7 @@ export class GatewayRunExecutor {
     queueIndex = 0;
     /** Accepts of one thread run one at a time, so two can never both start a turn. */
     acceptChains = new Map();
+    missingTails = new Set();
     constructor(deps) {
         this.deps = deps;
     }
@@ -144,7 +169,9 @@ export class GatewayRunExecutor {
         };
         this.activeByThread.set(request.threadId, active);
         this.activeRequests.set(request.threadId, request);
+        const releaseAwake = this.deps.keepAwake?.();
         void this.execute(request, active, emit, merged).finally(() => {
+            releaseAwake?.();
             if (this.activeByThread.get(request.threadId) === active) {
                 this.activeByThread.delete(request.threadId);
                 this.activeRequests.delete(request.threadId);
@@ -235,21 +262,32 @@ export class GatewayRunExecutor {
         };
         const awaitApproval = registerApproval;
         let errorText = null;
+        let nextBinding = null;
         try {
             publish(true);
-            const [topicId, binding] = await Promise.all([
-                readCurrentTopicId(db, active.threadId),
-                readSessionBinding(db, active.threadId),
+            const [topic, binding] = await Promise.all([
+                readCurrentTopic(db, active.threadId),
+                readSessionBinding(db, active.threadId, gateway.id),
             ]);
-            const sessionId = binding && binding.gatewayId === gateway.id && binding.topicId === topicId ? binding.sessionId : null;
+            const topicId = topic?.id ?? null;
+            const continued = binding?.topicId === topicId ? binding : null;
             const turns = [...merged, request];
-            const resources = (await Promise.all(turns.map((turn) => this.resolveResources(turn.userMessage)))).flat();
+            const [resources, context, instructions] = await Promise.all([
+                Promise.all(turns.map((turn) => this.resolveResources(turn.userMessage))).then((lists) => lists.flat()),
+                this.clientTailSynced(turns[0], active.controller.signal).then((synced) => this.unseenContext(active.threadId, turns[0].userMessage.id, topic?.createdAt ?? null, continued, synced)),
+                readAgentInstructions(db, active.threadId).catch(() => ''),
+            ]);
+            // A session keeps the directory it started in; changing the default only affects new ones.
+            const cwd = continued ? (continued.cwd ?? gateway.previousCwd ?? gateway.cwd ?? os.homedir()) : (gateway.cwd ?? os.homedir());
             // Validated on receipt; a malformed value never reaches here.
             const requestedConfig = readAgentConfig(request);
             const agentConfig = requestedConfig && requestedConfig !== 'invalid' ? requestedConfig : undefined;
+            const prompt = turns.map((turn) => turn.prompt.trim()).filter(Boolean).join('\n\n');
             const result = await adapter.runTurn({
-                sessionId,
-                prompt: turns.map((turn) => turn.prompt.trim()).filter(Boolean).join('\n\n'),
+                sessionId: continued?.sessionId ?? null,
+                cwd,
+                sessionPreamble: agentInstructionsPreamble(instructions),
+                prompt: withConversationContext(prompt, context, { canReadConversation: gateway.dinoxTools !== false }),
                 resources,
                 signal: active.controller.signal,
                 config: agentConfig,
@@ -263,9 +301,19 @@ export class GatewayRunExecutor {
                     publish(event.type === 'approval-request' || event.type === 'approval-resolved');
                 },
             });
-            if (result.sessionId !== sessionId) {
-                await writeSessionBinding(db, active.threadId, { sessionId: result.sessionId, topicId, gatewayId: gateway.id });
-            }
+            nextBinding = {
+                sessionId: result.sessionId,
+                topicId,
+                cwd,
+                lastSeenMessageId: context?.incomplete
+                    ? // Messages that had not synced yet sort before this turn: keep the mark so the
+                        // next turn still catches up on them (its own turns are left out by session).
+                        continued && continued.sessionId === result.sessionId && !continued.legacy
+                            ? continued.lastSeenMessageId
+                            : null
+                    : // Its own reply is the newest message the session has seen.
+                        request.assistantMessage.id,
+            };
             status = statusForStop(result.stopReason);
             errorText = result.error ?? null;
         }
@@ -287,15 +335,73 @@ export class GatewayRunExecutor {
                 userId: this.deps.userId,
                 userMessageId: request.userMessage.id,
                 status,
-                assistant: toTranscriptMessage(assistant),
+                assistant: nextBinding
+                    ? withGatewaySession(toTranscriptMessage(assistant), { gatewayId: gateway.id, sessionId: nextBinding.sessionId })
+                    : toTranscriptMessage(assistant),
                 errorText,
             });
         }
         catch (error) {
             log('commit run terminal failed', { runId: active.runId, error: String(error) });
         }
+        if (nextBinding) {
+            // After the commit, so the reply it marks as seen is in the transcript.
+            await writeSessionBinding(db, active.threadId, gateway.id, nextBinding).catch((error) => log('write session binding failed', { runId: active.runId, error: String(error) }));
+        }
         emit({ revision: projection.revision, status, assistant, pendingApprovals: [] });
     }
+    /**
+     * The client sends the last message it saw; a turn reads the transcript only
+     * once that message has synced here (its upload may still be in flight), or
+     * gives up after a short wait. A tail that never arrived is not waited for again.
+     */
+    async clientTailSynced(request, signal) {
+        const tailId = request.parentMessageId;
+        if (!tailId)
+            return true;
+        const key = `${request.threadId}:${tailId}`;
+        const synced = await waitForMessage(this.deps.db, tailId, {
+            timeoutMs: this.missingTails.has(key) ? 0 : (this.deps.clientTailSyncTimeoutMs ?? CLIENT_TAIL_SYNC_TIMEOUT_MS),
+            signal,
+        });
+        if (synced) {
+            this.missingTails.delete(key);
+        }
+        else {
+            if (this.missingTails.size >= MAX_REMEMBERED_MISSING_TAILS)
+                this.missingTails.clear();
+            this.missingTails.add(key);
+            this.deps.log('client messages not synced yet', { threadId: request.threadId, tailId });
+        }
+        return synced;
+    }
+    /**
+     * Messages before this turn that the session has not seen: the whole topic
+     * for a new session, those after the session's mark for a continued one,
+     * leaving out the turns the session answered itself. A session bound before
+     * seen messages were tracked is assumed to be up to date.
+     */
+    async unseenContext(threadId, turnMessageId, topicStartedAt, continued, synced) {
+        if (continued?.legacy)
+            return synced ? null : { threadId, messages: [], earlier: 0, incomplete: true };
+        try {
+            const page = await readTranscriptPage(this.deps.db, {
+                threadId,
+                since: topicStartedAt,
+                afterMessageId: continued?.lastSeenMessageId ?? null,
+                beforeMessageId: turnMessageId,
+                excludeSessionId: continued?.sessionId ?? null,
+                limit: CONTEXT_MESSAGE_LIMIT,
+            });
+            return { threadId, ...page, ...(synced ? {} : { incomplete: true }) };
+        }
+        catch (error) {
+            // Missing context degrades the answer; it must not fail the turn. Marked
+            // incomplete so the session's mark stays and the next turn retries.
+            this.deps.log('read conversation context failed', { threadId, error: String(error) });
+            return { threadId, messages: [], earlier: 0, incomplete: true };
+        }
+    }
     async resolveResources(message) {
         const resources = [];
         for (const part of message.parts) {

package/dist/gateway/service.d.ts

@@ -16,11 +16,15 @@ export declare class GatewayService {
     private readonly deps;
     private hosts;
     private readonly log;
+    private readonly keepAwake;
     constructor(deps: GatewayServiceDeps);
     start(): Promise<void>;
     stop(): Promise<void>;
     /** Re-reads the account's gateways (after add/remove) without restarting the daemon. */
     reload(): Promise<DeviceHostStatus[]>;
+    /** Saves a change made in the app, applies it to the running gateway and syncs the robot row. */
+    private updateSettings;
+    private robotRegistration;
     status(): DeviceHostStatus[];
 }
 export {};

package/dist/gateway/service.js

@@ -1,12 +1,22 @@
 import os from 'node:os';
 import { getPackageVersion } from '../utils/version.js';
+import { writeDaemonLogLine } from '../daemon/log.js';
 import { createGatewayAdapter } from './adapters/index.js';
-import { getMachineId, loadGateways } from './config.js';
+import { getMachineId, loadGateways, updateGatewaySettings } from './config.js';
 import { GatewayDeviceHost } from './deviceHost.js';
+import { KeepAwake } from './keepAwake.js';
 import { interruptOrphanedRuns, retireRemovedRobots, upsertRobot } from './threadStore.js';
-const defaultLog = (message, details) => {
-    process.stderr.write(`[dinox-gateway] ${message}${details ? ` ${JSON.stringify(details)}` : ''}\n`);
-};
+/** Settings the owner changes from the app; the running gateway picks them up without a restart. */
+const LIVE_SETTINGS = ['cwd', 'previousCwd', 'approval', 'paused', 'dinoxTools'];
+function applyLiveSettings(target, source) {
+    for (const key of LIVE_SETTINGS) {
+        if (source[key] === undefined)
+            delete target[key];
+        else
+            target[key] = source[key];
+    }
+}
+const defaultLog = (message, details) => writeDaemonLogLine('dinox-gateway', message, details);
 /**
  * Runs every enabled gateway inside the daemon: the daemon owns the PowerSync
  * database, so gateway writes share its connection and upload queue.
@@ -15,9 +25,11 @@ export class GatewayService {
     deps;
     hosts = [];
     log;
+    keepAwake;
     constructor(deps) {
         this.deps = deps;
         this.log = deps.log ?? defaultLog;
+        this.keepAwake = new KeepAwake(this.log);
     }
     async start() {
         const configured = await loadGateways(this.deps.userId);
@@ -40,17 +52,7 @@ export class GatewayService {
         if (interrupted > 0)
             this.log('marked runs from a previous host as interrupted', { count: interrupted });
         for (const gateway of gateways) {
-            await upsertRobot(this.deps.db, {
-                id: gateway.id,
-                userId: this.deps.userId,
-                name: gateway.name,
-                deviceId: gateway.deviceId,
-                agentType: gateway.kind,
-                cwd: gateway.cwd ?? null,
-                deviceName: os.hostname(),
-                machineId,
-                ...(gateway.agentId ? { agentId: gateway.agentId } : {}),
-            }).catch((error) => this.log('register robot failed', { gateway: gateway.name, error: String(error) }));
+            await upsertRobot(this.deps.db, this.robotRegistration(gateway, machineId)).catch((error) => this.log('register robot failed', { gateway: gateway.name, error: String(error) }));
             const host = new GatewayDeviceHost({
                 gateway,
                 db: this.deps.db,
@@ -60,6 +62,8 @@ export class GatewayService {
                 appVersion: getPackageVersion(),
                 log: (message, details) => this.log(message, { gateway: gateway.name, ...details }),
                 credentialsUrl: this.deps.credentialsUrl,
+                updateSettings: (change) => this.updateSettings(gateway, machineId, change),
+                keepAwake: () => this.keepAwake.acquire(),
             });
             host.start();
             this.hosts.push(host);
@@ -69,6 +73,7 @@ export class GatewayService {
         const hosts = this.hosts;
         this.hosts = [];
         await Promise.allSettled(hosts.map((host) => host.stop()));
+        this.keepAwake.dispose();
     }
     /** Re-reads the account's gateways (after add/remove) without restarting the daemon. */
     async reload() {
@@ -76,6 +81,30 @@ export class GatewayService {
         await this.start();
         return this.status();
     }
+    /** Saves a change made in the app, applies it to the running gateway and syncs the robot row. */
+    async updateSettings(gateway, machineId, change) {
+        const updated = await updateGatewaySettings(this.deps.userId, gateway.id, change);
+        applyLiveSettings(gateway, updated);
+        await upsertRobot(this.deps.db, this.robotRegistration(gateway, machineId)).catch((error) => this.log('sync robot settings failed', { gateway: gateway.name, error: String(error) }));
+    }
+    robotRegistration(gateway, machineId) {
+        return {
+            id: gateway.id,
+            userId: this.deps.userId,
+            name: gateway.name,
+            deviceId: gateway.deviceId,
+            agentType: gateway.kind,
+            cwd: gateway.cwd ?? null,
+            deviceName: os.hostname(),
+            machineId,
+            ...(gateway.agentId ? { agentId: gateway.agentId } : {}),
+            settings: {
+                approval: gateway.approval ?? 'ask',
+                paused: gateway.paused === true,
+                dinoxTools: gateway.dinoxTools !== false,
+            },
+        };
+    }
     status() {
         return this.hosts.map((host) => host.status());
     }

package/dist/gateway/threadStore.d.ts

@@ -105,20 +105,78 @@ export declare function withdrawQueuedRun(db: AbstractPowerSyncDatabase, input:
 }): Promise<ChatUIMessage>;
 /** Runs left non-terminal by a previous process can never finish; mark them interrupted. */
 export declare function interruptOrphanedRuns(db: Tx, userId: string): Promise<number>;
-/** Agent session bound to a thread, scoped to the thread's current topic. */
+/**
+ * One gateway's agent session on a thread, scoped to the thread's topic when it
+ * started. The thread can switch agents, so every gateway keeps its own session
+ * and remembers the last transcript message it saw.
+ */
 export type GatewaySessionBinding = {
     sessionId: string;
     topicId: string | null;
-    gatewayId: string;
+    /** Newest transcript message the session has seen; null when it has seen nothing of the topic yet. */
+    lastSeenMessageId: string | null;
+    /** Directory the session works in; absent for bindings written before it was recorded. */
+    cwd?: string;
+    /** Written before seen messages were tracked: the session is assumed to be up to date. */
+    legacy?: true;
 };
-export declare function readSessionBinding(db: Tx, threadId: string): Promise<GatewaySessionBinding | null>;
-export declare function writeSessionBinding(db: Tx, threadId: string, binding: GatewaySessionBinding): Promise<void>;
+export declare function readSessionBinding(db: Tx, threadId: string, gatewayId: string): Promise<GatewaySessionBinding | null>;
+/** Replaces this gateway's binding and keeps every other gateway's. */
+export declare function writeSessionBinding(db: AbstractPowerSyncDatabase, threadId: string, gatewayId: string, binding: GatewaySessionBinding): Promise<void>;
+/** Directories this gateway's sessions worked in, most recently used first. */
+export declare function readRecentSessionFolders(db: Tx, gatewayId: string, limit?: number): Promise<string[]>;
+/** The instructions the user wrote for the thread's agent (`c_project.agent_md`); empty when none. */
+export declare function readAgentInstructions(db: Tx, threadId: string): Promise<string>;
 /**
  * The thread's current topic: the latest "new topic" marker the app wrote
  * (`entry_type = 'internal'`, `meta_data.kind = 'context_reset'`). A new topic
- * starts a fresh agent session.
+ * starts a fresh agent session; like the app, it covers rows written after the marker.
+ */
+export declare function readCurrentTopic(db: Tx, threadId: string): Promise<{
+    id: string;
+    createdAt: string | null;
+} | null>;
+/** Marks a reply with the agent session that wrote it (`metadata.gateway`). */
+export declare function withGatewaySession(message: ChatUIMessage, gateway: {
+    gatewayId: string;
+    sessionId: string;
+}): ChatUIMessage;
+/**
+ * Waits until a message exists in the local replica (deleted or not), e.g. the
+ * last message the client saw before sending a turn. False when it has not
+ * synced within the timeout or the wait was aborted.
  */
-export declare function readCurrentTopicId(db: Tx, threadId: string): Promise<string | null>;
+export declare function waitForMessage(db: Tx, messageId: string, options: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<boolean>;
+/** A transcript message reduced to what another agent needs: who said what. */
+export type TranscriptMessage = {
+    id: string;
+    role: 'user' | 'assistant';
+    /** The answering agent's name; null for the user or an unknown agent. */
+    speaker: string | null;
+    text: string;
+    createdAt: string | null;
+};
+/**
+ * The newest transcript messages in a window, oldest first, with how many
+ * matching messages lie before the page. Bounds are exclusive: `since` is a
+ * topic start (by `created_at`, as the app scopes topics), `afterMessageId` and
+ * `beforeMessageId` are transcript positions; an id that no longer exists is no bound.
+ */
+export declare function readTranscriptPage(db: Tx, input: {
+    threadId: string;
+    since?: string | null;
+    afterMessageId?: string | null;
+    beforeMessageId?: string | null;
+    /** Leaves out the turns this agent session answered itself (its replies and their prompts). */
+    excludeSessionId?: string | null;
+    limit: number;
+}): Promise<{
+    messages: TranscriptMessage[];
+    earlier: number;
+}>;
 /** File parts resolve only to resources this user owns with an https storage URL. */
 export declare function resolveTrustedResource(db: Tx, input: {
     resourceId: string;
@@ -141,6 +199,13 @@ export type RobotRegistration = {
     /** Marks the robot as hosted by this installation, for reconciliation. */
     machineId: string;
     agentId?: string;
+    /** Owner-facing settings, synced so the app can show them while the computer is offline. */
+    settings?: RobotSettings;
+};
+export type RobotSettings = {
+    approval: 'ask' | 'auto_read';
+    paused: boolean;
+    dinoxTools: boolean;
 };
 export declare function upsertRobot(db: Tx, input: RobotRegistration): Promise<void>;
 /**

package/dist/gateway/threadStore.js

@@ -319,38 +319,199 @@ export async function interruptOrphanedRuns(db, userId) {
     }
     return rows.length;
 }
-export async function readSessionBinding(db, threadId) {
-    const row = await db.getOptional('SELECT robot_session_id FROM c_thread WHERE id = ? LIMIT 1', [threadId]);
-    const parsed = parseJson(row?.robot_session_id);
-    if (parsed?.v !== 1 || typeof parsed.sessionId !== 'string' || typeof parsed.gatewayId !== 'string')
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function toBinding(value, legacy = false) {
+    if (!isRecord(value) || typeof value.sessionId !== 'string' || !value.sessionId)
         return null;
     return {
-        sessionId: parsed.sessionId,
-        topicId: typeof parsed.topicId === 'string' ? parsed.topicId : null,
-        gatewayId: parsed.gatewayId,
+        sessionId: value.sessionId,
+        topicId: typeof value.topicId === 'string' ? value.topicId : null,
+        lastSeenMessageId: typeof value.lastSeenMessageId === 'string' ? value.lastSeenMessageId : null,
+        ...(typeof value.cwd === 'string' && value.cwd ? { cwd: value.cwd } : {}),
+        ...(legacy ? { legacy: true } : {}),
     };
 }
-export async function writeSessionBinding(db, threadId, binding) {
-    await db.execute('UPDATE c_thread SET robot_session_id = ?, updated_at = ? WHERE id = ?', [
-        safeJson({ v: 1, ...binding }),
-        new Date().toISOString(),
-        threadId,
-    ]);
+/** `c_thread.robot_session_id`: v2 keeps a binding per gateway; v1 held a single one. */
+function parseBindings(raw) {
+    const parsed = parseJson(raw);
+    const bindings = {};
+    if (parsed?.v === 1 && typeof parsed.gatewayId === 'string') {
+        const binding = toBinding(parsed, true);
+        if (binding)
+            bindings[parsed.gatewayId] = binding;
+    }
+    else if (parsed?.v === 2 && isRecord(parsed.sessions)) {
+        for (const [gatewayId, value] of Object.entries(parsed.sessions)) {
+            const binding = toBinding(value);
+            if (binding)
+                bindings[gatewayId] = binding;
+        }
+    }
+    return bindings;
+}
+async function readBindings(db, threadId) {
+    const row = await db.getOptional('SELECT robot_session_id FROM c_thread WHERE id = ? LIMIT 1', [threadId]);
+    return parseBindings(row?.robot_session_id);
+}
+export async function readSessionBinding(db, threadId, gatewayId) {
+    return (await readBindings(db, threadId))[gatewayId] ?? null;
+}
+/** Replaces this gateway's binding and keeps every other gateway's. */
+export async function writeSessionBinding(db, threadId, gatewayId, binding) {
+    const { legacy: _legacy, ...stored } = binding;
+    await withPowerSyncWriteTransaction(db, async (tx) => {
+        const sessions = { ...(await readBindings(tx, threadId)), [gatewayId]: stored };
+        await tx.execute('UPDATE c_thread SET robot_session_id = ?, updated_at = ? WHERE id = ?', [
+            safeJson({ v: 2, sessions }),
+            new Date().toISOString(),
+            threadId,
+        ]);
+    });
+}
+/** Directories this gateway's sessions worked in, most recently used first. */
+export async function readRecentSessionFolders(db, gatewayId, limit = 8) {
+    const rows = await db.getAll(`SELECT robot_session_id FROM c_thread
+     WHERE robot_session_id LIKE ? AND (is_del IS NULL OR is_del = 0)
+     ORDER BY updated_at DESC LIMIT 200`, [`%${gatewayId}%`]);
+    const folders = [];
+    for (const row of rows) {
+        const cwd = parseBindings(row.robot_session_id)[gatewayId]?.cwd;
+        if (cwd && !folders.includes(cwd))
+            folders.push(cwd);
+        if (folders.length >= limit)
+            break;
+    }
+    return folders;
+}
+/** The instructions the user wrote for the thread's agent (`c_project.agent_md`); empty when none. */
+export async function readAgentInstructions(db, threadId) {
+    const row = await db.getOptional(`SELECT p.agent_md FROM c_thread t JOIN c_project p ON p.id = t.project_id
+     WHERE t.id = ? AND (p.is_del IS NULL OR p.is_del = 0) LIMIT 1`, [threadId]);
+    return row?.agent_md?.trim() ?? '';
 }
 /**
  * The thread's current topic: the latest "new topic" marker the app wrote
  * (`entry_type = 'internal'`, `meta_data.kind = 'context_reset'`). A new topic
- * starts a fresh agent session.
+ * starts a fresh agent session; like the app, it covers rows written after the marker.
  */
-export async function readCurrentTopicId(db, threadId) {
-    const rows = await db.getAll(`SELECT id, meta_data FROM c_chat_message
+export async function readCurrentTopic(db, threadId) {
+    // Other markers (e.g. agent switches) share the entry type, so filter by kind in SQL.
+    const row = await db.getOptional(`SELECT id, created_at FROM c_chat_message
      WHERE type = ? AND source_id = ? AND entry_type = ? AND deleted_at IS NULL
-     ORDER BY julianday(created_at) DESC, id DESC LIMIT 20`, [THREAD_CHAT_TYPE, threadId, CONTEXT_RESET_ENTRY_TYPE]);
-    for (const row of rows) {
-        if (parseJson(row.meta_data)?.kind === 'context_reset')
-            return row.id;
+       AND json_extract(meta_data, '$.kind') = 'context_reset'
+     ORDER BY julianday(created_at) DESC, id DESC LIMIT 1`, [THREAD_CHAT_TYPE, threadId, CONTEXT_RESET_ENTRY_TYPE]);
+    return row ? { id: row.id, createdAt: row.created_at } : null;
+}
+/** Marks a reply with the agent session that wrote it (`metadata.gateway`). */
+export function withGatewaySession(message, gateway) {
+    return {
+        ...message,
+        metadata: { ...(message.metadata ?? {}), gateway: { id: gateway.gatewayId, sessionId: gateway.sessionId } },
+    };
+}
+const TAIL_POLL_INTERVAL_MS = 250;
+/**
+ * Waits until a message exists in the local replica (deleted or not), e.g. the
+ * last message the client saw before sending a turn. False when it has not
+ * synced within the timeout or the wait was aborted.
+ */
+export async function waitForMessage(db, messageId, options) {
+    const deadline = Date.now() + options.timeoutMs;
+    for (;;) {
+        const row = await db.getOptional('SELECT id FROM c_chat_message WHERE id = ? LIMIT 1', [messageId]);
+        if (row)
+            return true;
+        if (options.signal?.aborted || Date.now() >= deadline)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, TAIL_POLL_INTERVAL_MS));
+    }
+}
+function messageText(message) {
+    const lines = [];
+    for (const part of message?.parts ?? []) {
+        if (part.type === 'text' && typeof part.text === 'string' && part.text.trim())
+            lines.push(part.text.trim());
+        if (part.type === 'file') {
+            const name = part.filename;
+            lines.push(`[attachment: ${typeof name === 'string' && name ? name : String(part.mediaType ?? 'file')}]`);
+        }
     }
-    return null;
+    return lines.join('\n\n');
+}
+/**
+ * The newest transcript messages in a window, oldest first, with how many
+ * matching messages lie before the page. Bounds are exclusive: `since` is a
+ * topic start (by `created_at`, as the app scopes topics), `afterMessageId` and
+ * `beforeMessageId` are transcript positions; an id that no longer exists is no bound.
+ */
+export async function readTranscriptPage(db, input) {
+    const since = input.since ?? null;
+    const after = input.afterMessageId ?? null;
+    const before = input.beforeMessageId ?? null;
+    const ownSession = input.excludeSessionId ?? null;
+    const where = `type = ? AND source_id = ? AND deleted_at IS NULL AND ${MESSAGE_ENTRY_FILTER}
+     AND role IN ('user', 'assistant')
+     AND (? IS NULL OR julianday(created_at) > julianday(?))
+     AND order_index > COALESCE((SELECT order_index FROM c_chat_message WHERE id = ?), order_index - 1)
+     AND order_index < COALESCE((SELECT order_index FROM c_chat_message WHERE id = ?), order_index + 1)
+     AND (? IS NULL OR NOT (
+       COALESCE(json_extract(content, '$.metadata.gateway.sessionId'), '') = ?
+       OR id IN (SELECT parent_id FROM c_chat_message
+                 WHERE type = ? AND source_id = ? AND parent_id IS NOT NULL
+                   AND json_extract(content, '$.metadata.gateway.sessionId') = ?)
+     ))`;
+    const params = [
+        THREAD_CHAT_TYPE,
+        input.threadId,
+        MESSAGE_ENTRY_TYPE,
+        LEGACY_MESSAGE_ENTRY_TYPE,
+        since,
+        since,
+        after,
+        before,
+        ownSession,
+        ownSession,
+        THREAD_CHAT_TYPE,
+        input.threadId,
+        ownSession,
+    ];
+    const [rows, total] = await Promise.all([
+        db.getAll(`SELECT id, role, content, responser_id, created_at FROM c_chat_message WHERE ${where}
+       ORDER BY order_index DESC, created_at DESC, id DESC LIMIT ?`, [...params, input.limit]),
+        db.getOptional(`SELECT COUNT(*) AS count FROM c_chat_message WHERE ${where}`, params),
+    ]);
+    const parsed = rows.reverse().map((row) => {
+        const message = parseJson(row.content);
+        const responserId = message?.metadata?.responserId;
+        return {
+            row,
+            responserId: row.role === 'assistant' ? (typeof responserId === 'string' && responserId) || row.responser_id || null : null,
+            text: messageText(message),
+        };
+    });
+    const names = await readAgentNames(db, parsed.map((item) => item.responserId).filter((id) => Boolean(id)));
+    return {
+        messages: parsed
+            .filter((item) => item.text)
+            .map(({ row, responserId, text }) => ({
+            id: row.id,
+            role: row.role,
+            speaker: responserId ? (names.get(responserId) ?? null) : null,
+            text,
+            createdAt: row.created_at,
+        })),
+        earlier: Math.max(0, Number(total?.count ?? 0) - rows.length),
+    };
+}
+/** Agent (`c_project`) display names by id; unnamed agents are left out. */
+async function readAgentNames(db, ids) {
+    const unique = [...new Set(ids)];
+    if (unique.length === 0)
+        return new Map();
+    const rows = await db.getAll(`SELECT id, name FROM c_project WHERE id IN (${unique.map(() => '?').join(', ')})`, unique);
+    return new Map(rows.filter((row) => row.name?.trim()).map((row) => [row.id, row.name.trim()]));
 }
 /** File parts resolve only to resources this user owns with an https storage URL. */
 export async function resolveTrustedResource(db, input) {
@@ -361,7 +522,13 @@ export async function resolveTrustedResource(db, input) {
     return { url: row.storage_url, name: row.name ?? 'attachment', mediaType: row.mime_type };
 }
 function robotMetaData(input) {
-    return JSON.stringify({ gateway: { machineId: input.machineId, ...(input.agentId ? { agentId: input.agentId } : {}) } });
+    return JSON.stringify({
+        gateway: {
+            machineId: input.machineId,
+            ...(input.agentId ? { agentId: input.agentId } : {}),
+            ...(input.settings ? { settings: input.settings } : {}),
+        },
+    });
 }
 export async function upsertRobot(db, input) {
     const now = new Date().toISOString();