@borgee/agents-host 0.1.8 → 0.2.1

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

@@ -1,68 +1,469 @@
 import { randomUUID } from 'node:crypto';
 import spawn from 'cross-spawn';
+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));
+}
+function createDeferredTurn(prompt, options) {
+    let settled = false;
+    let resolvePromise;
+    let rejectPromise;
+    const promise = new Promise((resolve, reject) => {
+        resolvePromise = resolve;
+        rejectPromise = reject;
+    });
+    return {
+        prompt,
+        options,
+        promise,
+        resolve(value) {
+            if (settled)
+                return;
+            settled = true;
+            resolvePromise(value);
+        },
+        reject(error) {
+            if (settled)
+                return;
+            settled = true;
+            rejectPromise(normalizeError(error));
+        },
+    };
+}
+function asObject(value) {
+    return typeof value === 'object' && value !== null ? value : null;
+}
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function hasVisibleText(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function readTextBlocks(blocks) {
+    if (!Array.isArray(blocks)) {
+        return [];
+    }
+    const segments = [];
+    for (const entry of blocks) {
+        const block = asObject(entry);
+        if (!block)
+            continue;
+        if (block.type === 'text' && hasVisibleText(asString(block.text))) {
+            segments.push(asString(block.text));
+        }
+    }
+    return segments;
+}
+function extractTextDelta(event) {
+    if (event.type === 'content_block_delta') {
+        const delta = asObject(event.delta);
+        if (!delta)
+            return null;
+        const deltaType = asString(delta.type);
+        if (deltaType !== undefined && deltaType !== 'text_delta') {
+            return null;
+        }
+        return asString(delta.text) ?? null;
+    }
+    if (event.type === 'content_block_start') {
+        const block = asObject(event.content_block) ?? asObject(event.block);
+        if (!block || block.type !== 'text') {
+            return null;
+        }
+        return asString(block.text) ?? null;
+    }
+    return null;
+}
+function extractToolSummary(event) {
+    if (event.type === 'tool_use') {
+        const toolName = asString(event.name) ?? asString(event.tool_name);
+        return hasVisibleText(toolName) ? `Running ${toolName}…` : 'Running tool…';
+    }
+    if (event.type === 'content_block_start') {
+        const block = asObject(event.content_block) ?? asObject(event.block);
+        if (!block || block.type !== 'tool_use') {
+            return null;
+        }
+        const toolName = asString(block.name);
+        return hasVisibleText(toolName) ? `Running ${toolName}…` : 'Running tool…';
+    }
+    return null;
+}
+function extractFinalText(event) {
+    if (event.type === 'result') {
+        const result = asString(event.result);
+        if (result !== undefined) {
+            return result;
+        }
+    }
+    if (event.type === 'message' || event.type === 'assistant') {
+        const message = asObject(event.message) ?? event;
+        const joined = readTextBlocks(message.content).join('');
+        if (joined.length > 0) {
+            return joined;
+        }
+    }
+    return null;
+}
+class ClaudeStreamCollector {
+    onProgress;
+    publicText = '';
+    finalText = null;
+    lastPublished = null;
+    constructor(onProgress) {
+        this.onProgress = onProgress;
+    }
+    consume(event) {
+        const payload = event.type === 'stream_event' ? asObject(event.event) ?? event : event;
+        const textDelta = extractTextDelta(payload);
+        if (textDelta !== null) {
+            this.publicText += textDelta;
+            this.publish(this.publicText);
+        }
+        if (!hasVisibleText(this.publicText)) {
+            const toolSummary = extractToolSummary(payload);
+            if (toolSummary) {
+                this.publish(toolSummary);
+            }
+        }
+        const finalText = extractFinalText(event) ?? extractFinalText(payload);
+        if (finalText !== null) {
+            this.finalText = finalText;
+        }
+    }
+    getFinalText() {
+        const text = this.finalText ?? this.publicText;
+        return hasVisibleText(text) ? text : '';
+    }
+    publish(text) {
+        if (!this.onProgress || !hasVisibleText(text) || text === this.lastPublished) {
+            return;
+        }
+        this.lastPublished = text;
+        this.onProgress({ text });
+    }
+}
 /**
  * CLI client for the Claude Code CLI (`claude`) non-interactive mode, with
  * native per-channel session continuity.
  *
- * Verified CLI behavior (`claude --help`):
- * - `--session-id <uuid>` starts a *new* conversation pinned to that UUID.
- * - `-r/--resume <uuid>` resumes an *existing* conversation by session ID.
- * These are documented as distinct operations, so this client tracks which
- * channels have already started a session and switches from `--session-id`
- * (first turn) to `--resume` (every turn after) accordingly. No message
- * history is kept on our side — the CLI's own session storage is the single
- * source of truth for conversation memory.
+ * Claude session memory remains entirely inside the Claude CLI. This client
+ * only pins one native session id per Borgee channel and serializes turns per
+ * channel so `--resume` is never called concurrently for the same session.
  */
 export class ClaudeCliClient {
     command;
     args;
-    sessionIdsByChannel = new Map();
-    constructor(command, args) {
+    sessionStore;
+    resolveSessionStoreAgentId;
+    runtime;
+    channels = new Map();
+    persistedSessions = new Map();
+    loadedSessionStoreAgentId = null;
+    stopped = false;
+    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) {
+        if (this.stopped) {
+            throw new Error('Claude CLI backend stopped');
+        }
+        const state = this.getOrCreateChannelState(channelId);
+        const turn = createDeferredTurn(prompt, options);
+        state.queue.push(turn);
+        this.processChannelQueue(channelId, state);
+        return turn.promise;
     }
-    async generateReply(channelId, prompt) {
-        const existingSessionId = this.sessionIdsByChannel.get(channelId);
-        const sessionId = existingSessionId ?? randomUUID();
-        const sessionArgs = existingSessionId
-            ? ['--resume', sessionId]
-            : ['--session-id', sessionId];
-        const text = await this.run([...this.args, ...sessionArgs], prompt);
-        // Only remember the session once the CLI call actually succeeds, so a
-        // failed first turn doesn't leave us permanently trying to `--resume`
-        // a session that was never created.
-        this.sessionIdsByChannel.set(channelId, sessionId);
-        return text;
-    }
-    async run(args, prompt) {
+    async dispose() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        const stoppedError = new Error('Claude CLI backend stopped');
+        for (const state of this.channels.values()) {
+            state.activeTurn?.reject(stoppedError);
+            for (const queuedTurn of state.queue) {
+                queuedTurn.reject(stoppedError);
+            }
+            state.queue = [];
+            state.activeChild?.kill('SIGTERM');
+        }
+    }
+    getOrCreateChannelState(channelId) {
+        let state = this.channels.get(channelId);
+        if (!state) {
+            state = {
+                processing: false,
+                queue: [],
+                sessionHydrated: false,
+                sessionEstablished: false,
+            };
+            this.channels.set(channelId, state);
+        }
+        return state;
+    }
+    processChannelQueue(channelId, state) {
+        if (state.processing) {
+            return;
+        }
+        state.processing = true;
+        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(channelId, state, turn);
+                        turn.resolve(text);
+                    }
+                    catch (error) {
+                        turn.reject(error);
+                    }
+                    finally {
+                        state.activeTurn = undefined;
+                    }
+                }
+            }
+            finally {
+                state.processing = false;
+                if (state.queue.length > 0 && !this.stopped) {
+                    this.processChannelQueue(channelId, state);
+                }
+            }
+        })();
+    }
+    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];
+        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;
+    }
+    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) => {
-            const child = spawn(this.command, args, {
+            const child = this.runtime.spawn(this.command, args, {
                 stdio: ['pipe', 'pipe', 'pipe'],
             });
-            let stdout = '';
+            state.activeChild = child;
+            const collector = new ClaudeStreamCollector(options?.onProgress);
             let stderr = '';
+            let lineBuffer = '';
+            let settled = false;
+            const settleReject = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(normalizeError(error));
+            };
+            const settleResolve = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(value);
+            };
             child.stdout.setEncoding('utf8');
             child.stderr.setEncoding('utf8');
             child.stdout.on('data', (chunk) => {
-                stdout += chunk;
+                lineBuffer += chunk;
+                while (true) {
+                    const newlineIndex = lineBuffer.indexOf('\n');
+                    if (newlineIndex === -1) {
+                        break;
+                    }
+                    const line = lineBuffer.slice(0, newlineIndex).trim();
+                    lineBuffer = lineBuffer.slice(newlineIndex + 1);
+                    if (!line)
+                        continue;
+                    try {
+                        const event = JSON.parse(line);
+                        collector.consume(event);
+                    }
+                    catch (error) {
+                        settleReject(new Error(`Claude stream-json parse failed: ${normalizeError(error).message}`));
+                        child.kill('SIGTERM');
+                        return;
+                    }
+                }
             });
             child.stderr.on('data', (chunk) => {
                 stderr += chunk;
             });
-            child.on('error', (error) => {
-                reject(error);
+            child.once('error', (error) => {
+                settleReject(error);
             });
-            child.on('close', (code) => {
-                if (code !== 0) {
-                    reject(new Error(`Claude CLI failed with code ${code}: ${stderr.trim()}`));
-                    return;
+            child.once('close', (code) => {
+                if (state.activeChild === child) {
+                    state.activeChild = undefined;
+                }
+                if (lineBuffer.trim().length > 0 && !settled) {
+                    try {
+                        collector.consume(JSON.parse(lineBuffer.trim()));
+                        lineBuffer = '';
+                    }
+                    catch (error) {
+                        settleReject(new Error(`Claude stream-json parse failed: ${normalizeError(error).message}`));
+                        return;
+                    }
                 }
-                const text = stdout.trim();
-                if (!text) {
-                    reject(new Error('Claude CLI returned empty output'));
+                if (code !== 0) {
+                    settleReject(new Error(`Claude CLI failed with code ${code}: ${stderr.trim()}`));
                     return;
                 }
-                resolve(text);
+                settleResolve(collector.getFinalText());
             });
             child.stdin.write(prompt);
             child.stdin.end();

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

@@ -0,0 +1,14 @@
+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;
+}
+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>;
+}

package/dist/providers/claude/session-store.js

@@ -0,0 +1,103 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, unlink } from 'node:fs/promises';
+import { dirname } from 'node:path';
+async function syncDirectory(path) {
+    const directoryHandle = await open(path, 'r');
+    try {
+        await directoryHandle.sync();
+    }
+    finally {
+        await directoryHandle.close();
+    }
+}
+function normalizePersistedSessions(raw, filePath) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error(`invalid Claude session file: ${filePath}`);
+    }
+    const entries = Object.entries(raw);
+    const sessions = {};
+    for (const [channelId, sessionId] of entries) {
+        if (typeof sessionId !== 'string' || sessionId.trim().length === 0) {
+            throw new Error(`invalid Claude session file: ${filePath}`);
+        }
+        sessions[channelId] = sessionId;
+    }
+    return sessions;
+}
+export class FileClaudeChannelSessionStore {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async loadFromPath(filePath) {
+        let raw;
+        try {
+            raw = await readFile(filePath, 'utf8');
+        }
+        catch (error) {
+            throw error;
+        }
+        return normalizePersistedSessions(JSON.parse(raw), filePath);
+    }
+    async load(agentId) {
+        const filePath = this.options.resolvePath(agentId);
+        try {
+            return await this.loadFromPath(filePath);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+            return {};
+        }
+    }
+    async save(agentId, sessions) {
+        const filePath = this.options.resolvePath(agentId);
+        const parentPath = dirname(filePath);
+        await mkdir(parentPath, { recursive: true, mode: 0o700 });
+        const entries = Object.entries(sessions).sort(([left], [right]) => left.localeCompare(right));
+        if (entries.length === 0) {
+            try {
+                await unlink(filePath);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT') {
+                    throw error;
+                }
+                return;
+            }
+            await syncDirectory(parentPath);
+            return;
+        }
+        const temporaryPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+        let temporaryHandle;
+        try {
+            temporaryHandle = await open(temporaryPath, 'wx', 0o600);
+            await temporaryHandle.writeFile(JSON.stringify(Object.fromEntries(entries)), {
+                encoding: 'utf8',
+            });
+            await temporaryHandle.sync();
+            await temporaryHandle.close();
+            temporaryHandle = undefined;
+            await rename(temporaryPath, filePath);
+            await syncDirectory(parentPath);
+        }
+        catch (error) {
+            if (temporaryHandle) {
+                try {
+                    await temporaryHandle.close();
+                }
+                catch {
+                    // Preserve the original durability failure.
+                }
+            }
+            try {
+                await unlink(temporaryPath);
+            }
+            catch {
+                // Cleanup is best effort.
+            }
+            throw error;
+        }
+    }
+}

package/dist/providers/copilot/adapter.d.ts

@@ -1,9 +1,9 @@
 import type { ProviderAdapter } from '../provider-adapter.js';
-import type { ProviderInput, ProviderReply } from '../../types.js';
+import type { ProviderGenerateOptions, ProviderInput, ProviderReply } from '../../types.js';
 import { CopilotCliClient } from './cli-client.js';
 export declare class CopilotProviderAdapter implements ProviderAdapter {
     private readonly cli;
     constructor(cli: CopilotCliClient);
-    generateReply(input: ProviderInput): Promise<ProviderReply>;
+    generateReply(input: ProviderInput, options?: ProviderGenerateOptions): Promise<ProviderReply>;
     dispose(): Promise<void>;
 }

package/dist/providers/copilot/adapter.js

@@ -4,7 +4,7 @@ export class CopilotProviderAdapter {
     constructor(cli) {
         this.cli = cli;
     }
-    async generateReply(input) {
+    async generateReply(input, options) {
         const prompt = buildPrompt({
             agentName: input.agentName,
             provider: input.provider,
@@ -12,7 +12,9 @@ export class CopilotProviderAdapter {
             incomingAuthorId: input.incomingAuthorId,
             incomingContent: input.incomingContent,
         });
-        const text = await this.cli.generateReply(input.channelId, prompt);
+        const text = await this.cli.generateReply(input.channelId, prompt, {
+            onProgress: options?.onProgress,
+        });
         return { text };
     }
     async dispose() {