@dinoxx/dinox-cli 2.4.0 → 2.6.0

package/dist/daemon/supervisor.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A service manager that owns the daemon process. Without one, the daemon is a
+ * detached child of whatever ran the first `dino` command; when that was a
+ * coding agent, the agent's host may reap it together with the session and
+ * every gateway goes offline. Under launchd / systemd the daemon belongs to
+ * the login session instead, starts at login, and is restarted after a crash.
+ *
+ * Restart policy is "on failure" only: a clean exit (`dino daemon stop`, a
+ * version/account restart, exclusive DB access for `doctor`) leaves it
+ * stopped until the CLI starts it again through the manager.
+ */
+export type DaemonServiceKind = 'launchd' | 'systemd';
+export type DaemonServiceSpec = {
+    program: string;
+    args: string[];
+    env: Record<string, string>;
+    workingDirectory: string;
+    logPath: string;
+};
+export type ServiceCommandResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+export type ServiceCommandRunner = (command: string, args: string[]) => Promise<ServiceCommandResult>;
+export type DaemonService = {
+    readonly kind: DaemonServiceKind;
+    readonly label: string;
+    readonly definitionPath: string;
+    render(spec: DaemonServiceSpec): string;
+    isInstalled(): boolean;
+    /** Writes the definition and (re)loads it, which starts the daemon. */
+    install(spec: DaemonServiceSpec): Promise<void>;
+    /** Starts the installed daemon when it is not running. */
+    start(): Promise<void>;
+    /** Stops the daemon and removes the definition; false when nothing was installed. */
+    uninstall(): Promise<boolean>;
+};
+/** Set in the service definition so the daemon can report who supervises it. */
+export declare const DAEMON_SERVICE_ENV = "DINOX_DAEMON_SUPERVISOR";
+export declare const runServiceCommand: ServiceCommandRunner;
+/**
+ * One daemon per data directory (it owns that directory's socket), so a
+ * non-default `DINOX_DATA_DIR` gets its own service.
+ */
+export declare function daemonServiceLabel(env?: NodeJS.ProcessEnv): string;
+/** True when the installed definition differs from what this CLI would write. */
+export declare function serviceDefinitionIsStale(service: DaemonService, spec: DaemonServiceSpec): boolean;
+export declare function renderLaunchdPlist(label: string, spec: DaemonServiceSpec): string;
+export declare function renderSystemdUnit(spec: DaemonServiceSpec): string;
+export type DaemonServiceOptions = {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    uid?: number;
+    run?: ServiceCommandRunner;
+};
+/** The service manager for this platform, or null where none is supported (Windows). */
+export declare function getDaemonService(options?: DaemonServiceOptions): DaemonService | null;

package/dist/daemon/supervisor.js

@@ -0,0 +1,253 @@
+import crypto from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getDataDir } from '../config/paths.js';
+import { DinoxError } from '../utils/errors.js';
+/** Set in the service definition so the daemon can report who supervises it. */
+export const DAEMON_SERVICE_ENV = 'DINOX_DAEMON_SUPERVISOR';
+const DEFAULT_LABEL = 'com.dinox.cli.daemon';
+const COMMAND_TIMEOUT_MS = 15_000;
+const LAUNCHD_BOOTSTRAP_ATTEMPTS = 5;
+const LAUNCHD_BOOTSTRAP_RETRY_MS = 300;
+export const runServiceCommand = (command, args) => new Promise((resolve) => {
+    execFile(command, args, { timeout: COMMAND_TIMEOUT_MS, encoding: 'utf8' }, (error, stdout, stderr) => {
+        const code = error ? (typeof error.code === 'number' ? error.code : 1) : 0;
+        resolve({ code, stdout: stdout ?? '', stderr: stderr ?? (error ? String(error.message) : '') });
+    });
+});
+/**
+ * One daemon per data directory (it owns that directory's socket), so a
+ * non-default `DINOX_DATA_DIR` gets its own service.
+ */
+export function daemonServiceLabel(env = process.env) {
+    if (!env.DINOX_DATA_DIR)
+        return DEFAULT_LABEL;
+    const hash = crypto.createHash('sha256').update(getDataDir(), 'utf8').digest('hex').slice(0, 8);
+    return `${DEFAULT_LABEL}.${hash}`;
+}
+function failed(kind, step, result) {
+    const output = (result.stderr || result.stdout).trim();
+    return new DinoxError(`${kind} ${step} failed${output ? `: ${output}` : ''}`, {
+        code: 'DAEMON_SERVICE_FAILED',
+        details: { service: kind, step, exitCode: result.code },
+    });
+}
+function writeDefinition(definitionPath, content) {
+    mkdirSync(path.dirname(definitionPath), { recursive: true });
+    writeFileSync(definitionPath, content, { mode: 0o644 });
+}
+function readDefinition(definitionPath) {
+    try {
+        return readFileSync(definitionPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** True when the installed definition differs from what this CLI would write. */
+export function serviceDefinitionIsStale(service, spec) {
+    return readDefinition(service.definitionPath) !== service.render(spec);
+}
+// ---------------------------------------------------------------- launchd
+function xmlEscape(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+export function renderLaunchdPlist(label, spec) {
+    const string = (value) => `<string>${xmlEscape(value)}</string>`;
+    const args = [spec.program, ...spec.args].map((arg) => `\t\t${string(arg)}`).join('\n');
+    const env = Object.keys(spec.env)
+        .sort()
+        .map((name) => `\t\t<key>${xmlEscape(name)}</key>\n\t\t${string(spec.env[name])}`)
+        .join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+\t<key>Label</key>
+\t${string(label)}
+\t<key>ProgramArguments</key>
+\t<array>
+${args}
+\t</array>
+\t<key>EnvironmentVariables</key>
+\t<dict>
+${env}
+\t</dict>
+\t<key>WorkingDirectory</key>
+\t${string(spec.workingDirectory)}
+\t<key>RunAtLoad</key>
+\t<true/>
+\t<key>KeepAlive</key>
+\t<dict>
+\t\t<key>SuccessfulExit</key>
+\t\t<false/>
+\t</dict>
+\t<key>ThrottleInterval</key>
+\t<integer>30</integer>
+\t<key>StandardOutPath</key>
+\t${string(spec.logPath)}
+\t<key>StandardErrorPath</key>
+\t${string(spec.logPath)}
+</dict>
+</plist>
+`;
+}
+class LaunchdService {
+    label;
+    run;
+    kind = 'launchd';
+    definitionPath;
+    domain;
+    target;
+    constructor(label, run, homeDir, uid) {
+        this.label = label;
+        this.run = run;
+        this.definitionPath = path.join(homeDir, 'Library', 'LaunchAgents', `${label}.plist`);
+        this.domain = `gui/${uid}`;
+        this.target = `${this.domain}/${label}`;
+    }
+    render(spec) {
+        return renderLaunchdPlist(this.label, spec);
+    }
+    isInstalled() {
+        return existsSync(this.definitionPath);
+    }
+    async isLoaded() {
+        return (await this.run('launchctl', ['print', this.target])).code === 0;
+    }
+    async bootstrap() {
+        // bootout returns before launchd has fully released the label, so a
+        // bootstrap right after it can fail transiently.
+        let result = null;
+        for (let attempt = 0; attempt < LAUNCHD_BOOTSTRAP_ATTEMPTS; attempt += 1) {
+            result = await this.run('launchctl', ['bootstrap', this.domain, this.definitionPath]);
+            if (result.code === 0)
+                return;
+            await new Promise((resolve) => setTimeout(resolve, LAUNCHD_BOOTSTRAP_RETRY_MS));
+        }
+        throw failed(this.kind, 'bootstrap', result);
+    }
+    async install(spec) {
+        if (await this.isLoaded())
+            await this.run('launchctl', ['bootout', this.target]);
+        writeDefinition(this.definitionPath, this.render(spec));
+        await this.bootstrap();
+    }
+    async start() {
+        if (!(await this.isLoaded())) {
+            await this.bootstrap();
+            return;
+        }
+        const result = await this.run('launchctl', ['kickstart', this.target]);
+        if (result.code !== 0)
+            throw failed(this.kind, 'kickstart', result);
+    }
+    async uninstall() {
+        const installed = this.isInstalled();
+        if (await this.isLoaded()) {
+            const result = await this.run('launchctl', ['bootout', this.target]);
+            if (result.code !== 0 && (await this.isLoaded()))
+                throw failed(this.kind, 'bootout', result);
+        }
+        if (installed)
+            unlinkSync(this.definitionPath);
+        return installed;
+    }
+}
+// ---------------------------------------------------------------- systemd
+/** Quotes one word for a systemd command line or assignment value. */
+function systemdQuote(value) {
+    const escaped = value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/%/g, '%%')
+        .replace(/\$/g, '$$$$')
+        .replace(/\n/g, '\\n');
+    return `"${escaped}"`;
+}
+export function renderSystemdUnit(spec) {
+    const execStart = [spec.program, ...spec.args].map(systemdQuote).join(' ');
+    const env = Object.keys(spec.env)
+        .sort()
+        .map((name) => `Environment=${systemdQuote(`${name}=${spec.env[name]}`)}`)
+        .join('\n');
+    return `[Unit]
+Description=Dinox CLI daemon
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${execStart}
+WorkingDirectory=${spec.workingDirectory.replace(/%/g, '%%')}
+${env}
+Restart=on-failure
+RestartSec=30
+StandardOutput=append:${spec.logPath}
+StandardError=append:${spec.logPath}
+
+[Install]
+WantedBy=default.target
+`;
+}
+class SystemdService {
+    label;
+    run;
+    kind = 'systemd';
+    definitionPath;
+    unit;
+    constructor(label, run, configHome) {
+        this.label = label;
+        this.run = run;
+        this.unit = `${label}.service`;
+        this.definitionPath = path.join(configHome, 'systemd', 'user', this.unit);
+    }
+    render(spec) {
+        return renderSystemdUnit(spec);
+    }
+    isInstalled() {
+        return existsSync(this.definitionPath);
+    }
+    async systemctl(step, ...args) {
+        const result = await this.run('systemctl', ['--user', ...args]);
+        if (result.code !== 0)
+            throw failed(this.kind, step, result);
+    }
+    async install(spec) {
+        writeDefinition(this.definitionPath, this.render(spec));
+        await this.systemctl('daemon-reload', 'daemon-reload');
+        await this.systemctl('enable', 'enable', this.unit);
+        await this.systemctl('restart', 'restart', this.unit);
+    }
+    async start() {
+        await this.systemctl('start', 'start', this.unit);
+    }
+    async uninstall() {
+        if (!this.isInstalled())
+            return false;
+        await this.run('systemctl', ['--user', 'disable', '--now', this.unit]);
+        unlinkSync(this.definitionPath);
+        await this.run('systemctl', ['--user', 'daemon-reload']);
+        return true;
+    }
+}
+/** The service manager for this platform, or null where none is supported (Windows). */
+export function getDaemonService(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const homeDir = options.homeDir ?? os.homedir();
+    const run = options.run ?? runServiceCommand;
+    const label = daemonServiceLabel(env);
+    if (platform === 'darwin') {
+        return new LaunchdService(label, run, homeDir, options.uid ?? process.getuid?.() ?? 0);
+    }
+    if (platform === 'linux') {
+        return new SystemdService(label, run, env.XDG_CONFIG_HOME || path.join(homeDir, '.config'));
+    }
+    return null;
+}

package/dist/daemon/types.d.ts

@@ -42,6 +42,8 @@ export type DaemonPingResult = {
     runtimeConfigFingerprint: string | null;
     /** True only for daemons using the current authenticated local protocol. */
     authenticated: boolean;
+    /** Service manager that owns the process; null or absent (older daemons) when unmanaged. */
+    supervisor?: 'launchd' | 'systemd' | null;
 };
 /** Kept only for old scripts that pass --port; the daemon transport is socket-based. */
 export declare const DEFAULT_DAEMON_PORT = 45678;

package/dist/gateway/adapters/acp.d.ts

@@ -1,8 +1,9 @@
-import { type McpServer, type SessionConfigOption } from '@agentclientprotocol/sdk';
+import { type McpServer, type SessionConfigOption, type ToolKind } from '@agentclientprotocol/sdk';
 import type { GatewayAdapter, GatewayAdapterInfo, GatewayConfigOption, GatewayDefinition, GatewayTurnInput, GatewayTurnResult } from '../types.js';
 type Logger = (message: string, details?: Record<string, unknown>) => void;
 /** Select options only; boolean toggles have no use in the app yet. */
 export declare function normalizeConfigOptions(options: SessionConfigOption[] | null | undefined): GatewayConfigOption[];
+export declare function isReadOnlyToolKind(kind: ToolKind | null | undefined): boolean;
 /**
  * Drives any Agent Client Protocol agent over stdio (`hermes acp`, `openclaw acp`,
  * `claude-code-acp`, `codex-acp`, `pi-acp`, ...). One long-lived process per
@@ -10,9 +11,10 @@ export declare function normalizeConfigOptions(options: SessionConfigOption[] |
  * each turn sends only the new prompt.
  */
 export declare class AcpGatewayAdapter implements GatewayAdapter {
+    /** Live: settings changed from the app (approval, Dinox tools) apply to the next request. */
     private readonly gateway;
     private readonly log;
-    /** MCP servers offered to every session, e.g. the Dinox knowledge tools. */
+    /** MCP servers offered to sessions as they are created or loaded, e.g. the Dinox knowledge tools. */
     private readonly mcpServers;
     readonly kind: "acp";
     private process;
@@ -20,13 +22,16 @@ export declare class AcpGatewayAdapter implements GatewayAdapter {
     private readonly turns;
     /** The latest settings any session reported: the agent-wide choices the app lists. */
     private catalog;
-    constructor(gateway: GatewayDefinition, log?: Logger, 
-    /** MCP servers offered to every session, e.g. the Dinox knowledge tools. */
-    mcpServers?: McpServer[]);
+    constructor(
+    /** Live: settings changed from the app (approval, Dinox tools) apply to the next request. */
+    gateway: GatewayDefinition, log?: Logger, 
+    /** MCP servers offered to sessions as they are created or loaded, e.g. the Dinox knowledge tools. */
+    mcpServers?: () => McpServer[]);
     info(): GatewayAdapterInfo;
     runTurn(input: GatewayTurnInput): Promise<GatewayTurnResult>;
     describeConfig(): Promise<GatewayConfigOption[]>;
     dispose(): Promise<void>;
+    /** Continues the session (loading it in `cwd` when this process has not seen it) or starts one there. */
     private resolveSession;
     /**
      * Brings the session to the requested settings before its turn. Entries the

package/dist/gateway/adapters/acp.js

@@ -52,6 +52,11 @@ export function normalizeConfigOptions(options) {
     }
     return normalized;
 }
+/** Tool kinds that only look at things; `auto_read` lets them run without asking. */
+const READ_ONLY_TOOL_KINDS = new Set(['read', 'search', 'think']);
+export function isReadOnlyToolKind(kind) {
+    return kind != null && READ_ONLY_TOOL_KINDS.has(kind);
+}
 function pickOption(options, approved) {
     const preferred = approved ? ['allow_once', 'allow_always'] : ['reject_once', 'reject_always'];
     for (const kind of preferred) {
@@ -77,9 +82,11 @@ export class AcpGatewayAdapter {
     turns = new Map();
     /** The latest settings any session reported: the agent-wide choices the app lists. */
     catalog = null;
-    constructor(gateway, log = () => { }, 
-    /** MCP servers offered to every session, e.g. the Dinox knowledge tools. */
-    mcpServers = []) {
+    constructor(
+    /** Live: settings changed from the app (approval, Dinox tools) apply to the next request. */
+    gateway, log = () => { }, 
+    /** MCP servers offered to sessions as they are created or loaded, e.g. the Dinox knowledge tools. */
+    mcpServers = () => []) {
         this.gateway = gateway;
         this.log = log;
         this.mcpServers = mcpServers;
@@ -90,7 +97,7 @@ export class AcpGatewayAdapter {
     }
     async runTurn(input) {
         const agent = await this.ensureProcess();
-        const sessionId = await this.resolveSession(agent, input.sessionId);
+        const { sessionId, created } = await this.resolveSession(agent, input.sessionId, input.cwd);
         await this.applyConfig(agent, sessionId, input.config);
         this.turns.set(sessionId, { onEvent: input.onEvent, awaitApproval: input.awaitApproval });
         const onAbort = () => {
@@ -98,7 +105,8 @@ export class AcpGatewayAdapter {
         };
         input.signal.addEventListener('abort', onAbort, { once: true });
         try {
-            const prompt = [{ type: 'text', text: input.prompt }];
+            const text = created && input.sessionPreamble ? `${input.sessionPreamble}\n\n${input.prompt}` : input.prompt;
+            const prompt = [{ type: 'text', text }];
             for (const resource of input.resources) {
                 prompt.push({ type: 'resource_link', uri: resource.uri, name: resource.name, mimeType: resource.mediaType ?? null });
             }
@@ -121,9 +129,13 @@ export class AcpGatewayAdapter {
         const agent = await this.ensureProcess();
         if (this.catalog)
             return this.catalog;
-        // No session yet: open one only to read the agent's choices. It never runs a turn.
+        // No session yet: open one only to read the agent's choices. It never runs a turn,
+        // so close it where the agent allows, or it shows up in the user's session list.
         const created = await agent.connection.newSession({ cwd: this.gateway.cwd ?? os.homedir(), mcpServers: [] });
         this.rememberConfig(agent, created.sessionId, created.configOptions);
+        if (agent.init.agentCapabilities?.sessionCapabilities?.close) {
+            await agent.connection.closeSession({ sessionId: created.sessionId }).catch((error) => this.log('closing the settings session failed', { error: String(error) }));
+        }
         return this.catalog ?? [];
     }
     async dispose() {
@@ -135,26 +147,26 @@ export class AcpGatewayAdapter {
         agent.child.stdin.end();
         agent.child.kill('SIGTERM');
     }
-    async resolveSession(agent, sessionId) {
-        const cwd = this.gateway.cwd ?? os.homedir();
+    /** Continues the session (loading it in `cwd` when this process has not seen it) or starts one there. */
+    async resolveSession(agent, sessionId, cwd) {
         if (sessionId && agent.liveSessions.has(sessionId))
-            return sessionId;
+            return { sessionId, created: false };
         if (sessionId && agent.init.agentCapabilities?.loadSession) {
             try {
                 // No turn is registered yet, so the history the agent replays is ignored.
-                const loaded = await agent.connection.loadSession({ sessionId, cwd, mcpServers: this.mcpServers });
+                const loaded = await agent.connection.loadSession({ sessionId, cwd, mcpServers: this.mcpServers() });
                 agent.liveSessions.add(sessionId);
                 this.rememberConfig(agent, sessionId, loaded.configOptions);
-                return sessionId;
+                return { sessionId, created: false };
             }
             catch (error) {
                 this.log('session/load failed; starting a new session', { sessionId, error: String(error) });
             }
         }
-        const created = await agent.connection.newSession({ cwd, mcpServers: this.mcpServers });
+        const created = await agent.connection.newSession({ cwd, mcpServers: this.mcpServers() });
         agent.liveSessions.add(created.sessionId);
         this.rememberConfig(agent, created.sessionId, created.configOptions);
-        return created.sessionId;
+        return { sessionId: created.sessionId, created: true };
     }
     /**
      * Brings the session to the requested settings before its turn. Entries the
@@ -269,6 +281,11 @@ export class AcpGatewayAdapter {
         const turn = this.turns.get(params.sessionId);
         if (!turn)
             return { outcome: { outcome: 'cancelled' } };
+        if (this.gateway.approval === 'auto_read' && isReadOnlyToolKind(params.toolCall.kind)) {
+            const option = pickOption(params.options, true);
+            if (option)
+                return { outcome: { outcome: 'selected', optionId: option.optionId } };
+        }
         const approvalId = `acp-${generateId()}`;
         turn.onEvent({
             type: 'approval-request',

package/dist/gateway/adapters/index.js

@@ -21,8 +21,9 @@ export function dinoxMcpServerConfig() {
 export function createGatewayAdapter(gateway, log) {
     switch (gateway.kind) {
         case 'acp': {
-            const dinoxTools = gateway.dinoxTools === false ? null : dinoxMcpServerConfig();
-            return new AcpGatewayAdapter(gateway, log, dinoxTools ? [dinoxTools] : []);
+            const dinoxTools = dinoxMcpServerConfig();
+            // Read per session, so turning the Dinox tools off applies to the next new conversation.
+            return new AcpGatewayAdapter(gateway, log, () => (gateway.dinoxTools !== false && dinoxTools ? [dinoxTools] : []));
         }
         case 'echo':
             return new EchoGatewayAdapter();

package/dist/gateway/config.d.ts

@@ -1,4 +1,4 @@
-import type { GatewayDefinition, GatewayKind } from './types.js';
+import type { GatewayApprovalMode, GatewayDefinition, GatewayKind } from './types.js';
 /** Gateways belong to an account: each one registers a robot for that user. */
 export declare function getGatewaysFilePath(userId: string): string;
 /**
@@ -46,5 +46,15 @@ export declare function adoptDetectedAgent(userId: string, agent: {
     gateway: GatewayDefinition;
     change: 'added' | 'updated' | 'unchanged';
 }>;
+/** What the owner may change from the app; never commands, arguments or environment. */
+export type GatewaySettingsPatch = {
+    /** An absolute directory already checked by the caller. */
+    cwd?: string;
+    approval?: GatewayApprovalMode;
+    paused?: boolean;
+    dinoxTools?: boolean;
+};
+/** Applies a settings change to one gateway and saves it; returns the updated definition. */
+export declare function updateGatewaySettings(userId: string, gatewayId: string, patch: GatewaySettingsPatch): Promise<GatewayDefinition>;
 export declare function findGateway(gateways: GatewayDefinition[], ref: string): GatewayDefinition | undefined;
 export declare function removeGateway(userId: string, ref: string): Promise<GatewayDefinition>;

package/dist/gateway/config.js

@@ -1,5 +1,6 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import { getConfigDir, normalizeUserPathSegment } from '../config/paths.js';
 import { DinoxError } from '../utils/errors.js';
@@ -119,9 +120,12 @@ function parseGateway(value) {
         ...(typeof raw.command === 'string' ? { command: raw.command } : {}),
         ...(Array.isArray(raw.args) ? { args: raw.args.filter((arg) => typeof arg === 'string') } : {}),
         ...(typeof raw.cwd === 'string' ? { cwd: raw.cwd } : {}),
+        ...(typeof raw.previousCwd === 'string' ? { previousCwd: raw.previousCwd } : {}),
         ...(env ? { env } : {}),
         enabled: raw.enabled !== false,
         ...(raw.dinoxTools === false ? { dinoxTools: false } : {}),
+        ...(raw.approval === 'auto_read' ? { approval: 'auto_read' } : {}),
+        ...(raw.paused === true ? { paused: true } : {}),
         createdAt: typeof raw.createdAt === 'string' ? raw.createdAt : new Date(0).toISOString(),
     };
 }
@@ -239,6 +243,40 @@ export async function adoptDetectedAgent(userId, agent) {
     });
     return { gateway, change: 'added' };
 }
+/** Applies a settings change to one gateway and saves it; returns the updated definition. */
+export async function updateGatewaySettings(userId, gatewayId, patch) {
+    const gateways = await loadGateways(userId);
+    const existing = gateways.find((gateway) => gateway.id === gatewayId);
+    if (!existing) {
+        throw new DinoxError(`Gateway not found: ${gatewayId}`, { code: 'NOT_FOUND' });
+    }
+    const updated = { ...existing };
+    if (patch.cwd !== undefined && patch.cwd !== existing.cwd) {
+        // Sessions bound before they recorded a directory started in the old default.
+        updated.previousCwd = existing.previousCwd ?? existing.cwd ?? os.homedir();
+        updated.cwd = patch.cwd;
+    }
+    if (patch.approval !== undefined) {
+        if (patch.approval === 'ask')
+            delete updated.approval;
+        else
+            updated.approval = patch.approval;
+    }
+    if (patch.paused !== undefined) {
+        if (patch.paused)
+            updated.paused = true;
+        else
+            delete updated.paused;
+    }
+    if (patch.dinoxTools !== undefined) {
+        if (patch.dinoxTools)
+            delete updated.dinoxTools;
+        else
+            updated.dinoxTools = false;
+    }
+    await saveGateways(userId, gateways.map((gateway) => (gateway.id === gatewayId ? updated : gateway)));
+    return updated;
+}
 export function findGateway(gateways, ref) {
     return gateways.find((gateway) => gateway.id === ref || gateway.name === ref || gateway.deviceId === ref);
 }

package/dist/gateway/conversationContext.d.ts

@@ -0,0 +1,44 @@
+import type { AbstractPowerSyncDatabase } from '@powersync/common';
+import { type TranscriptMessage } from './threadStore.js';
+/**
+ * Catch-up context for an agent session. A Dinox thread can switch agents
+ * mid-conversation, and each agent keeps only its own session, so before a
+ * turn the gateway hands the agent the transcript messages its session has not
+ * seen. Only recent messages travel with the prompt; the agent can read the
+ * rest with the `read_conversation` Dinox tool (pull on demand, like a handoff
+ * brief plus a link rather than a full transcript dump).
+ */
+/** Messages read for one catch-up; anything older is only counted. */
+export declare const CONTEXT_MESSAGE_LIMIT = 20;
+export type ConversationContext = {
+    threadId: string;
+    /** Unseen messages, oldest first. */
+    messages: TranscriptMessage[];
+    /** Unseen messages older than `messages`. */
+    earlier: number;
+    /** The latest messages could not be loaded here (not synced yet, or the read failed). */
+    incomplete?: boolean;
+};
+/**
+ * Prefixes the turn's prompt with the unseen messages, newest kept first
+ * within the size budget. Returns the prompt unchanged when there is nothing
+ * to catch up on.
+ */
+export declare function withConversationContext(prompt: string, context: ConversationContext | null, options: {
+    canReadConversation: boolean;
+}): string;
+export type ReadConversationParams = {
+    threadId: string;
+    beforeMessageId?: string;
+    limit?: number;
+};
+export declare const READ_CONVERSATION_MAX_LIMIT = 50;
+/**
+ * A page of one of the user's conversations for the `read_conversation` tool:
+ * the newest messages before `beforeMessageId`, oldest first. Page back by
+ * passing the first returned id as the next `beforeMessageId`.
+ */
+export declare function readConversation(db: AbstractPowerSyncDatabase, userId: string, params: ReadConversationParams): Promise<{
+    messages: TranscriptMessage[];
+    hasMore: boolean;
+} | null>;