@borgee/agents-host 0.2.0 → 0.2.2

package/README.md

@@ -315,13 +315,19 @@ Each Borgee channel is mapped 1:1 to a provider-native session while it stays
 active:
 
 - **Claude**: first turn for a channel uses `--session-id <uuid>`; every turn
-  after uses `-r/--resume <uuid>`.
+  after uses `-r/--resume <uuid>`. The host persists the channel→session map in
+  its state root, serializes cross-channel map rewrites, and retries once with a
+  fresh session immediately if Claude reports a stale `--resume` target.
 - **Copilot**: one persistent `copilot --acp` subprocess is shared by a single
   `AgentsHost`, with one ACP session per Borgee channel. Same-channel turns are
-  serialized; different channels keep isolated ACP sessions.
-
-There is no separate history store on our side. If a runner restarts, that
-agent's provider-side channel sessions start fresh.
+  serialized; different channels keep isolated ACP sessions. The host persists
+  the channel→ACP-session map in its state root and restores same-host
+  continuity with ACP `session/resume` when available, otherwise `session/load`
+  plus local replay cleanup on runtimes that advertise only load support.
+
+There is no separate transcript/history store on our side. Claude and Copilot
+only persist the native session ids they should try to resume later; cross-host
+continuity still does not exist in this runtime.
 
 ## Testing
 

package/dist/agents-host.d.ts

@@ -27,6 +27,7 @@ export declare class AgentsHost {
     private readonly progressChannelQueues;
     private readonly progressDrafts;
     private selfAgentId;
+    private selfAgentIdPromise;
     private started;
     private controlPlaneClosed;
     constructor(config: AgentsHostConfig, deps?: {
@@ -39,4 +40,5 @@ export declare class AgentsHost {
     private trackActiveTurn;
     private enqueueProgressChannelTurn;
     private ensureProgressDraft;
+    private ensureSelfAgentId;
 }

package/dist/agents-host.js

@@ -1,6 +1,13 @@
+import { chmod, mkdir } from 'node:fs/promises';
 import { SdkChatControlPlane } from './chat/sdk-chat-control-plane.js';
+import { createDurableCursorStore } from './durable-cursor-store.js';
 import { createProvider } from './providers/create-provider.js';
+const PRIVATE_STATE_ROOT_MODE = 0o700;
 const STREAM_PROGRESS_EDIT_THROTTLE_MS = 150;
+async function ensurePrivateStateRoot(path) {
+    await mkdir(path, { recursive: true, mode: PRIVATE_STATE_ROOT_MODE });
+    await chmod(path, PRIVATE_STATE_ROOT_MODE);
+}
 function hasVisibleText(value) {
     return value.trim().length > 0;
 }
@@ -128,29 +135,37 @@ export class AgentsHost {
     progressChannelQueues = new Map();
     progressDrafts = new Map();
     selfAgentId = null;
+    selfAgentIdPromise = null;
     started = false;
     controlPlaneClosed = false;
     constructor(config, deps) {
         this.config = config;
         this.provider = deps?.provider ?? createProvider({
             provider: config.agent.provider,
+            stateRootDir: config.stateRootDir,
+            resolveStableAgentId: () => this.selfAgentId ?? undefined,
             claudeCommand: config.claudeCommand,
             claudeArgs: config.claudeArgs,
             copilotCommand: config.copilotCommand,
             copilotArgs: config.copilotArgs,
             copilotSessionTtlMinutes: config.copilotSessionTtlMinutes,
         });
-        this.borgee = deps?.borgee ?? new SdkChatControlPlane(config.borgeeBaseUrl, config.agent.agentApiKey, undefined, 
-        // Lets the server know which runtime/provider actually connected
-        // (internal/bpp ConnectHandler → users.last_connected_plugin_id), so
-        // the web UI can show real state instead of a client-side guess.
-        `agents-host:${config.agent.provider}`);
+        this.borgee = deps?.borgee ?? new SdkChatControlPlane(config.borgeeBaseUrl, config.agent.agentApiKey, undefined, {
+            cursorStore: createDurableCursorStore({
+                stateRootDir: config.stateRootDir,
+            }),
+            // Lets the server know which runtime/provider actually connected
+            // (internal/bpp ConnectHandler → users.last_connected_plugin_id), so
+            // the web UI can show real state instead of a client-side guess.
+            pluginId: `agents-host:${config.agent.provider}`,
+        });
     }
     async start() {
         if (this.started)
             return;
         this.started = true;
         this.controlPlaneClosed = false;
+        await ensurePrivateStateRoot(this.config.stateRootDir);
         await this.borgee.connect((message) => {
             if (!this.started) {
                 return;
@@ -160,10 +175,9 @@ export class AgentsHost {
                 : this.handleMessage(message);
             this.trackActiveTurn(task);
         });
-        const me = await this.borgee.getMe();
-        this.selfAgentId = me.id;
+        const agentId = await this.ensureSelfAgentId();
         console.log('[agents-host] connected', {
-            agentId: me.id,
+            agentId,
             agentName: this.config.agent.agentName,
             provider: this.config.agent.provider,
         });
@@ -187,8 +201,9 @@ export class AgentsHost {
             agentName: this.config.agent.agentName,
             channelId: msg.channel_id,
         });
+        const selfAgentId = await this.ensureSelfAgentId();
         const authorId = String(msg.user_id ?? msg.sender_id ?? 'unknown');
-        if (this.selfAgentId && authorId === this.selfAgentId) {
+        if (authorId === selfAgentId) {
             return;
         }
         const content = String(msg.content ?? msg.body ?? '').trim();
@@ -276,4 +291,19 @@ export class AgentsHost {
         }
         return draft;
     }
+    async ensureSelfAgentId() {
+        if (this.selfAgentId) {
+            return this.selfAgentId;
+        }
+        if (!this.selfAgentIdPromise) {
+            this.selfAgentIdPromise = this.borgee.getMe().then((me) => {
+                this.selfAgentId = me.id;
+                return me.id;
+            }).catch((error) => {
+                this.selfAgentIdPromise = null;
+                throw error;
+            });
+        }
+        return this.selfAgentIdPromise;
+    }
 }

package/dist/chat/sdk-chat-control-plane.d.ts

@@ -3,6 +3,7 @@ import type { ChannelMessageEvent, MeResponseUser, PostedMessage } from '../type
 import type { ChatControlPlane } from './chat-control-plane.js';
 type PluginClientLike = Pick<BorgeePluginClient, 'agentId' | 'close' | 'connect' | 'deleteMessage' | 'editMessage' | 'getMe' | 'on' | 'sendMessage' | 'startTyping'>;
 type PluginClientFactory = (options: BorgeePluginOptions) => PluginClientLike;
+type SdkChatControlPlaneOptions = Pick<BorgeePluginOptions, 'cursorStore' | 'pluginId'>;
 /**
  * Thin adapter over `@borgee/plugin-sdk` (the same BPP/`/ws/plugin` SDK used by
  * the OpenClaw plugin) that implements the minimal `ChatControlPlane` surface
@@ -14,7 +15,7 @@ export declare class SdkChatControlPlane implements ChatControlPlane {
     private unsubscribe;
     private connected;
     private me;
-    constructor(baseUrl: string, apiKey: string, createClient?: PluginClientFactory, pluginId?: string);
+    constructor(baseUrl: string, apiKey: string, createClient?: PluginClientFactory, options?: SdkChatControlPlaneOptions);
     connect(onMessage: (message: ChannelMessageEvent) => void): Promise<void>;
     close(): Promise<void>;
     postMessage(channelId: string, content: string): Promise<PostedMessage>;

package/dist/chat/sdk-chat-control-plane.js

@@ -10,8 +10,8 @@ export class SdkChatControlPlane {
     unsubscribe = null;
     connected = false;
     me = null;
-    constructor(baseUrl, apiKey, createClient = createBorgeePlugin, pluginId) {
-        this.client = createClient({ baseUrl, apiKey, pluginId });
+    constructor(baseUrl, apiKey, createClient = createBorgeePlugin, options = {}) {
+        this.client = createClient({ baseUrl, apiKey, ...options });
     }
     async connect(onMessage) {
         this.unsubscribe = this.client.on('message', (event) => {

package/dist/config.js

@@ -1,3 +1,4 @@
+import { resolveSingleAgentStateRoot } from './state-paths.js';
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 export const MAX_COPILOT_SESSION_TTL_MINUTES = MAX_TIMER_DELAY_MS / 60_000;
 export const DEFAULT_COPILOT_SESSION_TTL_MINUTES = 2 * 24 * 60;
@@ -74,6 +75,7 @@ export function loadConfigFromEnv(env = process.env) {
     const provider = resolveProvider(envOr('RUNTIME_PROVIDER', 'claude', env), 'Unsupported RUNTIME_PROVIDER');
     return {
         borgeeBaseUrl: requireEnv('BORGEE_BASE_URL', env),
+        stateRootDir: resolveSingleAgentStateRoot(env),
         ...resolveProviderCommandConfig({
             claudeCommand: envOr('CLAUDE_COMMAND', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeCommand, env),
             claudeArgs: parseArgs(envOr('CLAUDE_ARGS', DEFAULT_PROVIDER_COMMAND_CONFIG.claudeArgs.join(' '), env)),

package/dist/durable-cursor-store.d.ts

@@ -0,0 +1,5 @@
+import { type CursorStore } from '@borgee/plugin-sdk';
+export interface DurableCursorStoreOptions {
+    stateRootDir: string;
+}
+export declare function createDurableCursorStore(options: DurableCursorStoreOptions): CursorStore;

package/dist/durable-cursor-store.js

@@ -0,0 +1,7 @@
+import { FileCursorStore } from '@borgee/plugin-sdk';
+import { resolveAgentCursorPath } from './state-paths.js';
+export function createDurableCursorStore(options) {
+    return new FileCursorStore({
+        resolvePath: (agentId) => resolveAgentCursorPath(options.stateRootDir, agentId),
+    });
+}

package/dist/local-config.js

@@ -3,6 +3,7 @@ import { randomUUID } from 'node:crypto';
 import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
 import { parseDocument, stringify } from 'yaml';
 import { optionalNonEmptyString, optionalStringArray, parseCopilotSessionTtlMinutesValue, requireNonEmptyString, resolveProvider, resolveProviderCommandConfig, } from './config.js';
+import { resolveLocalConfigAgentStateRoot } from './state-paths.js';
 const SUPPORTED_CONFIG_EXTENSIONS = new Set(['.json', '.yaml', '.yml']);
 export const DEFAULT_LOCAL_HOST_CONFIG_FILENAME = 'agents-host.yaml';
 export const DEFAULT_LOCAL_AGENTS_DIRNAME = 'agents';
@@ -131,6 +132,9 @@ function parseHostConfigFile(hostConfigPath, value) {
 function toGeneratedAgentConfigFilename(key) {
     return `${encodeURIComponent(key)}.yaml`;
 }
+function toCaseInsensitiveFilesystemIdentity(path) {
+    return path.toLowerCase();
+}
 function parseGenerateHostConfigFile(sourceLabel, value) {
     if (value.agentsDir !== undefined) {
         throw new Error(`Invalid generate-config host spec in ${sourceLabel}: agentsDir is not supported; generate-config always writes the canonical default layout`);
@@ -573,13 +577,14 @@ function renderAgentConfigYaml(agent) {
     }
     return stringify(config);
 }
-function buildManagedAgentSnapshot(host, sourcePath, agent) {
+function buildManagedAgentSnapshot(host, stateRootBaseDir, sourcePath, agent) {
     const providerConfig = resolveProviderCommandConfig({
         ...host.defaults,
         ...parseProviderCommandOverrides(agent, `agent config ${sourcePath}`),
     });
     const config = {
         borgeeBaseUrl: host.borgeeBaseUrl,
+        stateRootDir: resolveLocalConfigAgentStateRoot(stateRootBaseDir, agent.key),
         ...providerConfig,
         agent: {
             agentApiKey: agent.apiKey,
@@ -610,6 +615,7 @@ export async function loadLocalConfigSnapshot(hostConfigPath, deps = {}) {
         const resolvedHostConfigDir = dirname(resolvedHostConfigPath);
         const hostConfigRecord = await loadParsedDocument(fileSystem, resolvedHostConfigPath, 'host config');
         const hostConfig = parseHostConfigFile(absoluteHostConfigPath, hostConfigRecord);
+        const stateRootBaseDir = managedGeneration.managedRootPath ?? hostConfigDir;
         const agentsDir = toAgentsDir(absoluteHostConfigPath, hostConfig.agentsDir);
         const resolvedAgentsDir = resolve(fileSystem.realPath
             ? await fileSystem.realPath(toAgentsDir(resolvedHostConfigPath, hostConfig.agentsDir))
@@ -643,7 +649,7 @@ export async function loadLocalConfigSnapshot(hostConfigPath, deps = {}) {
             resolvedAgentsDir,
             agents: parsedAgents
                 .filter((entry) => entry.config.enabled !== false)
-                .map((entry) => buildManagedAgentSnapshot(hostConfig, entry.sourcePath, entry.config)),
+                .map((entry) => buildManagedAgentSnapshot(hostConfig, stateRootBaseDir, entry.sourcePath, entry.config)),
         };
     }
     finally {

package/dist/providers/claude/cli-client.d.ts

@@ -1,5 +1,6 @@
 import spawn from 'cross-spawn';
 import type { ProviderGenerateOptions } from '../../types.js';
+import type { ClaudeChannelSessionStore } from './session-store.js';
 interface ClaudeCliRuntime {
     spawn: typeof spawn;
 }
@@ -14,15 +15,30 @@ interface ClaudeCliRuntime {
 export declare class ClaudeCliClient {
     private readonly command;
     private readonly args;
+    private readonly sessionStore?;
+    private readonly resolveSessionStoreAgentId;
     private readonly runtime;
     private readonly channels;
+    private readonly persistedSessions;
+    private loadedSessionStoreAgentId;
     private stopped;
-    constructor(command: string, args: string[], runtimeOverrides?: Partial<ClaudeCliRuntime>);
+    private sessionStoreLoadPromise;
+    private sessionStoreWriteQueue;
+    constructor(command: string, args: string[], runtimeOverrides?: Partial<ClaudeCliRuntime>, sessionStore?: ClaudeChannelSessionStore | undefined, resolveSessionStoreAgentId?: () => string | undefined);
     generateReply(channelId: string, prompt: string, options?: ProviderGenerateOptions): Promise<string>;
     dispose(): Promise<void>;
     private getOrCreateChannelState;
     private processChannelQueue;
     private runTurn;
+    private runTurnAttempt;
+    private currentSessionStoreAgentId;
+    private ensureSessionStoreLoaded;
+    private hydrateChannelState;
+    private persistSession;
+    private persistSessionBestEffort;
+    private resetPersistedSession;
+    private resetPersistedSessionBestEffort;
+    private enqueueSessionStoreWrite;
     private run;
 }
 export {};

package/dist/providers/claude/cli-client.js

@@ -4,6 +4,10 @@ const DEFAULT_RUNTIME = {
     spawn,
 };
 const STREAM_JSON_ARGS = ['--verbose', '--output-format', 'stream-json', '--include-partial-messages'];
+function isStaleResumeFailure(error) {
+    const message = normalizeError(error).message.toLowerCase();
+    return message.includes('session not found') || message.includes('cannot resume');
+}
 function normalizeError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }
@@ -157,12 +161,20 @@ class ClaudeStreamCollector {
 export class ClaudeCliClient {
     command;
     args;
+    sessionStore;
+    resolveSessionStoreAgentId;
     runtime;
     channels = new Map();
+    persistedSessions = new Map();
+    loadedSessionStoreAgentId = null;
     stopped = false;
-    constructor(command, args, runtimeOverrides = {}) {
+    sessionStoreLoadPromise = null;
+    sessionStoreWriteQueue = Promise.resolve();
+    constructor(command, args, runtimeOverrides = {}, sessionStore, resolveSessionStoreAgentId = () => undefined) {
         this.command = command;
         this.args = args;
+        this.sessionStore = sessionStore;
+        this.resolveSessionStoreAgentId = resolveSessionStoreAgentId;
         this.runtime = { ...DEFAULT_RUNTIME, ...runtimeOverrides };
     }
     async generateReply(channelId, prompt, options) {
@@ -195,6 +207,7 @@ export class ClaudeCliClient {
             state = {
                 processing: false,
                 queue: [],
+                sessionHydrated: false,
                 sessionEstablished: false,
             };
             this.channels.set(channelId, state);
@@ -209,13 +222,26 @@ export class ClaudeCliClient {
         void (async () => {
             try {
                 while (!this.stopped) {
+                    const queuedTurn = state.queue[0];
+                    if (!queuedTurn) {
+                        return;
+                    }
+                    try {
+                        if (await this.ensureSessionStoreLoaded()) {
+                            this.hydrateChannelState(channelId, state);
+                        }
+                    }
+                    catch (error) {
+                        state.queue.shift()?.reject(error);
+                        continue;
+                    }
                     const turn = state.queue.shift();
                     if (!turn) {
                         return;
                     }
                     state.activeTurn = turn;
                     try {
-                        const text = await this.runTurn(state, turn);
+                        const text = await this.runTurn(channelId, state, turn);
                         turn.resolve(text);
                     }
                     catch (error) {
@@ -234,16 +260,138 @@ export class ClaudeCliClient {
             }
         })();
     }
-    async runTurn(state, turn) {
+    async runTurn(channelId, state, turn) {
+        return this.runTurnAttempt(channelId, state, turn, true);
+    }
+    async runTurnAttempt(channelId, state, turn, allowFreshRetryAfterStaleResume) {
         if (this.stopped) {
             throw new Error('Claude CLI backend stopped');
         }
         const sessionId = state.sessionEstablished ? state.sessionId : randomUUID();
         const sessionArgs = state.sessionEstablished ? ['--resume', sessionId] : ['--session-id', sessionId];
-        const text = await this.run(state, [...this.args, ...sessionArgs, ...STREAM_JSON_ARGS], turn.prompt, turn.options);
-        state.sessionId = sessionId;
+        try {
+            const text = await this.run(state, [...this.args, ...sessionArgs, ...STREAM_JSON_ARGS], turn.prompt, turn.options);
+            state.sessionId = sessionId;
+            state.sessionEstablished = true;
+            await this.persistSessionBestEffort(channelId, sessionId);
+            return text;
+        }
+        catch (error) {
+            if (state.sessionEstablished && isStaleResumeFailure(error)) {
+                await this.resetPersistedSessionBestEffort(channelId, state);
+                if (allowFreshRetryAfterStaleResume) {
+                    return this.runTurnAttempt(channelId, state, turn, false);
+                }
+            }
+            throw error;
+        }
+    }
+    currentSessionStoreAgentId() {
+        const agentId = this.resolveSessionStoreAgentId()?.trim();
+        return agentId && agentId.length > 0 ? agentId : null;
+    }
+    async ensureSessionStoreLoaded() {
+        if (!this.sessionStore) {
+            return true;
+        }
+        const agentId = this.currentSessionStoreAgentId();
+        if (!agentId) {
+            return false;
+        }
+        if (this.loadedSessionStoreAgentId && this.loadedSessionStoreAgentId !== agentId) {
+            this.loadedSessionStoreAgentId = null;
+            this.sessionStoreLoadPromise = null;
+            this.persistedSessions.clear();
+            for (const state of this.channels.values()) {
+                state.sessionHydrated = false;
+            }
+        }
+        if (!this.sessionStoreLoadPromise) {
+            this.sessionStoreLoadPromise = (async () => {
+                try {
+                    const stored = await this.sessionStore.load(agentId);
+                    this.persistedSessions.clear();
+                    for (const [channelId, sessionId] of Object.entries(stored)) {
+                        this.persistedSessions.set(channelId, sessionId);
+                    }
+                    this.loadedSessionStoreAgentId = agentId;
+                }
+                catch (error) {
+                    this.sessionStoreLoadPromise = null;
+                    throw error;
+                }
+            })();
+        }
+        await this.sessionStoreLoadPromise;
+        return true;
+    }
+    hydrateChannelState(channelId, state) {
+        if (state.sessionHydrated) {
+            return;
+        }
+        state.sessionHydrated = true;
+        const persistedSessionId = this.persistedSessions.get(channelId);
+        if (!persistedSessionId) {
+            return;
+        }
+        state.sessionId = persistedSessionId;
         state.sessionEstablished = true;
-        return text;
+    }
+    async persistSession(channelId, sessionId) {
+        if (!this.sessionStore || !this.loadedSessionStoreAgentId) {
+            return;
+        }
+        await this.enqueueSessionStoreWrite(async () => {
+            if (this.persistedSessions.get(channelId) === sessionId) {
+                return;
+            }
+            this.persistedSessions.set(channelId, sessionId);
+            await this.sessionStore.save(this.loadedSessionStoreAgentId, Object.fromEntries(this.persistedSessions));
+        });
+    }
+    async persistSessionBestEffort(channelId, sessionId) {
+        try {
+            await this.persistSession(channelId, sessionId);
+        }
+        catch (error) {
+            console.error('[agents-host] failed to persist Claude session map; keeping reply delivery', {
+                agentId: this.loadedSessionStoreAgentId,
+                channelId,
+                sessionId,
+                error,
+            });
+        }
+    }
+    async resetPersistedSession(channelId, state) {
+        state.sessionEstablished = false;
+        state.sessionId = undefined;
+        if (!this.sessionStore || !this.loadedSessionStoreAgentId) {
+            return;
+        }
+        await this.enqueueSessionStoreWrite(async () => {
+            if (!this.persistedSessions.has(channelId)) {
+                return;
+            }
+            this.persistedSessions.delete(channelId);
+            await this.sessionStore.save(this.loadedSessionStoreAgentId, Object.fromEntries(this.persistedSessions));
+        });
+    }
+    async resetPersistedSessionBestEffort(channelId, state) {
+        try {
+            await this.resetPersistedSession(channelId, state);
+        }
+        catch (error) {
+            console.error('[agents-host] failed to clear stale Claude session map; retrying in-memory only', {
+                agentId: this.loadedSessionStoreAgentId,
+                channelId,
+                error,
+            });
+        }
+    }
+    async enqueueSessionStoreWrite(writeOperation) {
+        const queuedWrite = this.sessionStoreWriteQueue.then(writeOperation);
+        this.sessionStoreWriteQueue = queuedWrite.catch(() => undefined);
+        await queuedWrite;
     }
     async run(state, args, prompt, options) {
         return new Promise((resolve, reject) => {

package/dist/providers/claude/session-store.d.ts

@@ -0,0 +1,37 @@
+export interface ClaudeChannelSessionStore {
+    load(agentId: string): Promise<Record<string, string>>;
+    save(agentId: string, sessions: Record<string, string>): Promise<void>;
+}
+export interface FileClaudeChannelSessionStoreOptions {
+    resolvePath(agentId: string): string;
+    fileSystem?: ClaudeSessionStoreFileSystem;
+    platform?: NodeJS.Platform;
+}
+interface ClaudeSessionStoreDirectoryHandle {
+    sync(): Promise<void>;
+    close(): Promise<void>;
+}
+interface ClaudeSessionStoreFileHandle extends ClaudeSessionStoreDirectoryHandle {
+    writeFile(data: string, options: {
+        encoding: BufferEncoding;
+    }): Promise<void>;
+}
+interface ClaudeSessionStoreFileSystem {
+    mkdir(path: string, options: {
+        recursive: true;
+        mode: number;
+    }): Promise<void>;
+    openDirectory(path: string): Promise<ClaudeSessionStoreDirectoryHandle>;
+    openFile(path: string, flags: string, mode: number): Promise<ClaudeSessionStoreFileHandle>;
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    rename(from: string, to: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+}
+export declare class FileClaudeChannelSessionStore implements ClaudeChannelSessionStore {
+    private readonly options;
+    constructor(options: FileClaudeChannelSessionStoreOptions);
+    private loadFromPath;
+    load(agentId: string): Promise<Record<string, string>>;
+    save(agentId: string, sessions: Record<string, string>): Promise<void>;
+}
+export {};