@borgee/agents-host 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# @borgee/agents-host
+
+Minimal local runtime host: connects a local **Claude Code CLI** (`claude`) or
+**GitHub Copilot CLI** (`copilot`) process to a single Borgee agent over
+[`@borgee/plugin-sdk`](../../sdk/plugin-ts) — the same BPP (`/ws/plugin`)
+protocol the official OpenClaw plugin uses.
+
+## What this is (and isn't)
+
+This package is intentionally the *smallest* slice that proves the full loop:
+
+```
+Borgee channel message
+  → /ws/plugin (BPP)
+  → @borgee/plugin-sdk
+  → AgentsHost.handleMessage
+  → local `claude`/`copilot` CLI subprocess
+  → BPP reply
+  → Borgee channel
+```
+
+**In scope:** one agent per process, mention-only gating (with a DM bypass),
+per-channel conversation memory via each CLI's own native session resume
+(Claude `--resume`, Copilot `--session-id`), and dispatching to a local CLI
+provider.
+
+**Out of scope** (see the larger `feat/multi-agent-runtime-host` work for
+these): remote command execution / shell dispatch, node provisioning,
+multi-agent discovery/sync, systemd service install, and scheduled/periodic
+prompts. To run several agents, run several processes with different
+`BORGEE_AGENT_API_KEY` values.
+
+## Setup
+
+1. In the Borgee web UI, create an Agent and reveal its API key.
+2. Install the Claude Code CLI (`claude`) or GitHub Copilot CLI (`copilot`)
+   locally and make sure it works standalone.
+3. Run this package with the environment variables below.
+
+```bash
+BORGEE_BASE_URL=https://your-borgee-server \
+BORGEE_AGENT_API_KEY=bgr_xxxxxxxx \
+BORGEE_AGENT_NAME="My Agent" \
+RUNTIME_PROVIDER=claude \
+pnpm --filter @borgee/agents-host dev
+```
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `BORGEE_BASE_URL` | yes | — | Borgee server base URL (e.g. `https://borgee.example.com`) |
+| `BORGEE_AGENT_API_KEY` | yes | — | The agent's API key, revealed from the web UI |
+| `BORGEE_AGENT_NAME` | no | `Assistant` | Display name used for mention matching and prompts |
+| `RUNTIME_PROVIDER` | no | `claude` | `claude` or `copilot` |
+| `CLAUDE_COMMAND` / `CLAUDE_ARGS` | no | `claude` / `--print` | Local Claude CLI command + args |
+| `COPILOT_COMMAND` / `COPILOT_ARGS` | no | `copilot` / `-s --no-color --allow-all-tools --output-format text` | Local Copilot CLI command + args |
+| `RESPOND_ON_MENTION_ONLY` | no | `true` | If `true`, only replies in non-DM channels when @mentioned; DMs always get a reply |
+
+## Conversation memory
+
+Each Borgee channel is mapped 1:1 to a native CLI session, keyed by a
+generated UUID kept in memory for the process's lifetime:
+
+- **Claude**: first turn for a channel uses `--session-id <uuid>`; every
+  turn after uses `-r/--resume <uuid>` (Claude treats these as distinct
+  operations).
+- **Copilot**: every turn uses `--session-id=<uuid>` — Copilot's CLI treats
+  that flag as create-or-resume for the same UUID.
+
+There is no separate history/context store on our side; if the runtime host
+process restarts, each channel starts a fresh CLI session (no session-id
+persistence across restarts in this minimal version).
+
+## Running
+
+```bash
+pnpm --filter @borgee/agents-host dev     # tsx, no build step
+pnpm --filter @borgee/agents-host build   # tsc -> dist/
+pnpm --filter @borgee/agents-host start   # node dist/index.js
+```
+
+There is no systemd/service installer here — run it as a plain foreground
+process (or wrap it with your own process manager) and stop it with
+`Ctrl+C`/`SIGTERM`.
+
+## Testing
+
+```bash
+pnpm --filter @borgee/agents-host test
+```

package/dist/agents-host.d.ts

@@ -0,0 +1,46 @@
+import type { ChatControlPlane } from './chat/chat-control-plane.js';
+import type { ProviderAdapter } from './providers/provider-adapter.js';
+import type { AgentsHostConfig } from './types.js';
+/**
+ * Minimal single-agent agents host: connects one local Claude/Copilot CLI
+ * to exactly one Borgee agent over `@borgee/plugin-sdk` (BPP / `/ws/plugin`).
+ *
+ * Conversation memory is handled entirely by each provider's native
+ * per-channel CLI session (Claude `--resume`, Copilot `--session-id`) — see
+ * the cli-client.ts file under each provider's folder. This class does not
+ * keep any message history itself.
+ *
+ * Out of scope by design (see README): execution/remote-command dispatch,
+ * node provisioning, multi-agent discovery, systemd install, and scheduled
+ * (periodic) prompts. Running several agents means running several
+ * processes, each with its own `BORGEE_AGENT_API_KEY`.
+ */
+export declare class AgentsHost {
+    private readonly config;
+    private readonly provider;
+    private readonly borgee;
+    private selfAgentId;
+    private started;
+    constructor(config: AgentsHostConfig, deps?: {
+        borgee?: ChatControlPlane;
+        provider?: ProviderAdapter;
+    });
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private handleMessage;
+    /**
+     * Whether `msg` mentions this agent: either via the SDK's structured
+     * mention event kind, or a plain-text substring match on the configured
+     * agent name.
+     */
+    isLikelyMention(message: {
+        type?: string;
+    }, content: string): boolean;
+    /**
+     * Channel-type check, based solely on the `channel_type` hint the SDK
+     * derives from the inbound BPP event. There is no REST fallback here (that
+     * would require the excluded control-plane SDK) — an absent hint is
+     * treated as "not a DM".
+     */
+    private isDirectMessage;
+}

package/dist/agents-host.js

@@ -0,0 +1,117 @@
+import { SdkChatControlPlane } from './chat/sdk-chat-control-plane.js';
+import { createProvider } from './providers/create-provider.js';
+/**
+ * Minimal single-agent agents host: connects one local Claude/Copilot CLI
+ * to exactly one Borgee agent over `@borgee/plugin-sdk` (BPP / `/ws/plugin`).
+ *
+ * Conversation memory is handled entirely by each provider's native
+ * per-channel CLI session (Claude `--resume`, Copilot `--session-id`) — see
+ * the cli-client.ts file under each provider's folder. This class does not
+ * keep any message history itself.
+ *
+ * Out of scope by design (see README): execution/remote-command dispatch,
+ * node provisioning, multi-agent discovery, systemd install, and scheduled
+ * (periodic) prompts. Running several agents means running several
+ * processes, each with its own `BORGEE_AGENT_API_KEY`.
+ */
+export class AgentsHost {
+    config;
+    provider;
+    borgee;
+    selfAgentId = null;
+    started = false;
+    constructor(config, deps) {
+        this.config = config;
+        this.provider = deps?.provider ?? createProvider({
+            provider: config.agent.provider,
+            claudeCommand: config.claudeCommand,
+            claudeArgs: config.claudeArgs,
+            copilotCommand: config.copilotCommand,
+            copilotArgs: config.copilotArgs,
+        });
+        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}`);
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        await this.borgee.connect((message) => {
+            void this.handleMessage(message);
+        });
+        const me = await this.borgee.getMe();
+        this.selfAgentId = me.id;
+        console.log('[agents-host] connected', {
+            agentId: me.id,
+            agentName: this.config.agent.agentName,
+            provider: this.config.agent.provider,
+        });
+    }
+    async stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        await this.borgee.close();
+    }
+    async handleMessage(msg) {
+        console.log('[agents-host] received message', {
+            eventType: msg.type,
+            provider: this.config.agent.provider,
+            agentName: this.config.agent.agentName,
+            channelId: msg.channel_id,
+        });
+        const authorId = String(msg.user_id ?? msg.sender_id ?? 'unknown');
+        if (this.selfAgentId && authorId === this.selfAgentId) {
+            return;
+        }
+        const content = String(msg.content ?? msg.body ?? '').trim();
+        if (!content)
+            return;
+        const isDm = this.isDirectMessage(msg.channel_type);
+        if (this.config.agent.respondOnMentionOnly && !isDm) {
+            if (!this.isLikelyMention(msg, content))
+                return;
+        }
+        try {
+            const reply = await this.provider.generateReply({
+                agentName: this.config.agent.agentName,
+                provider: this.config.agent.provider,
+                channelId: msg.channel_id,
+                incomingAuthorId: authorId,
+                incomingContent: content,
+            });
+            await this.borgee.postMessage(msg.channel_id, reply.text);
+        }
+        catch (error) {
+            console.error('[agents-host] failed to generate or send reply:', {
+                provider: this.config.agent.provider,
+                agentName: this.config.agent.agentName,
+                error,
+            });
+        }
+    }
+    /**
+     * Whether `msg` mentions this agent: either via the SDK's structured
+     * mention event kind, or a plain-text substring match on the configured
+     * agent name.
+     */
+    isLikelyMention(message, content) {
+        if (message.type === 'mention') {
+            return true;
+        }
+        return this.config.agent.agentName.trim().length > 0
+            && content.toLowerCase().includes(this.config.agent.agentName.toLowerCase());
+    }
+    /**
+     * Channel-type check, based solely on the `channel_type` hint the SDK
+     * derives from the inbound BPP event. There is no REST fallback here (that
+     * would require the excluded control-plane SDK) — an absent hint is
+     * treated as "not a DM".
+     */
+    isDirectMessage(hintedType) {
+        return hintedType === 'dm';
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { ChannelMessageEvent, MeResponseUser } from '../types.js';
+export interface ChatControlPlane {
+    connect(onMessage: (message: ChannelMessageEvent) => void): Promise<void>;
+    close(): Promise<void>;
+    postMessage(channelId: string, content: string): Promise<void>;
+    getMe(): Promise<MeResponseUser>;
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,23 @@
+import { type BorgeePluginClient, type BorgeePluginOptions, type InboundMessageEvent } from '@borgee/plugin-sdk';
+import type { ChannelMessageEvent, MeResponseUser } from '../types.js';
+import type { ChatControlPlane } from './chat-control-plane.js';
+type PluginClientLike = Pick<BorgeePluginClient, 'close' | 'connect' | 'getMe' | 'on' | 'sendMessage'>;
+type PluginClientFactory = (options: BorgeePluginOptions) => PluginClientLike;
+/**
+ * Thin adapter over `@borgee/plugin-sdk` (the same BPP/`/ws/plugin` SDK used by
+ * the OpenClaw plugin) that implements the minimal `ChatControlPlane` surface
+ * this runtime host needs: connect, receive messages, and post replies.
+ */
+export declare class SdkChatControlPlane implements ChatControlPlane {
+    private readonly client;
+    private pendingMessages;
+    private unsubscribe;
+    private connected;
+    constructor(baseUrl: string, apiKey: string, createClient?: PluginClientFactory, pluginId?: string);
+    connect(onMessage: (message: ChannelMessageEvent) => void): Promise<void>;
+    close(): Promise<void>;
+    postMessage(channelId: string, content: string): Promise<void>;
+    getMe(): Promise<MeResponseUser>;
+}
+export declare function mapInboundToChannelMessage(event: InboundMessageEvent): ChannelMessageEvent;
+export {};

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

@@ -0,0 +1,71 @@
+import { createBorgeePlugin, } from '@borgee/plugin-sdk';
+/**
+ * Thin adapter over `@borgee/plugin-sdk` (the same BPP/`/ws/plugin` SDK used by
+ * the OpenClaw plugin) that implements the minimal `ChatControlPlane` surface
+ * this runtime host needs: connect, receive messages, and post replies.
+ */
+export class SdkChatControlPlane {
+    client;
+    pendingMessages = [];
+    unsubscribe = null;
+    connected = false;
+    constructor(baseUrl, apiKey, createClient = createBorgeePlugin, pluginId) {
+        this.client = createClient({ baseUrl, apiKey, pluginId });
+    }
+    async connect(onMessage) {
+        this.unsubscribe = this.client.on('message', (event) => {
+            const message = mapInboundToChannelMessage(event);
+            if (!this.connected) {
+                this.pendingMessages.push(message);
+                return;
+            }
+            onMessage(message);
+        });
+        try {
+            await this.client.connect();
+            this.connected = true;
+            for (const message of this.pendingMessages) {
+                onMessage(message);
+            }
+            this.pendingMessages = [];
+        }
+        catch (error) {
+            this.unsubscribe?.();
+            this.unsubscribe = null;
+            this.pendingMessages = [];
+            throw error;
+        }
+    }
+    async close() {
+        this.connected = false;
+        this.pendingMessages = [];
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        await this.client.close();
+    }
+    async postMessage(channelId, content) {
+        await this.client.sendMessage({ channelId, body: content });
+    }
+    async getMe() {
+        const me = await this.client.getMe();
+        return {
+            id: me.id,
+            display_name: me.displayName,
+            role: me.kind,
+        };
+    }
+}
+export function mapInboundToChannelMessage(event) {
+    return {
+        type: event.kind,
+        channel_id: event.channelId,
+        channel_type: event.channelType,
+        message_id: event.message?.id ?? event.messageId,
+        user_id: event.message?.authorId ?? event.reaction?.userId,
+        sender_id: event.message?.authorId ?? event.reaction?.userId,
+        content: event.message?.body,
+        body: event.message?.body,
+        content_type: event.message?.contentType,
+        created_at: event.createdAt,
+    };
+}

package/dist/cli-args.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Maps `agents-host start` CLI flags to the env vars `config.ts` reads.
+ * Keeping this as a plain lookup table (rather than duplicating
+ * `loadConfigFromEnv`'s parsing logic) means the CLI and the plain
+ * env-var entry point (`index.ts`) always agree on defaults/validation.
+ */
+export declare const CLI_FLAG_TO_ENV: Record<string, string>;
+export interface ParsedStartArgs {
+    serverUrl: string;
+    apiKey: string;
+    env: Record<string, string>;
+}
+export declare class CliUsageError extends Error {
+}
+/**
+ * Parses `start <serverUrl> <apiKey> [--flag value ...]` (the argv slice
+ * after the `start` command word). Throws `CliUsageError` with a
+ * human-readable message on any usage problem instead of exiting the
+ * process, so callers (and tests) can decide how to report it.
+ */
+export declare function parseStartArgs(argv: string[]): ParsedStartArgs;
+export declare const USAGE = "Usage: agents-host start <serverUrl> <apiKey> [options]\n\nOptions:\n  --name <name>                 Display name (default: Assistant)\n  --provider <claude|copilot>   Runtime provider (default: claude)\n  --claude-command <cmd>        Local Claude CLI command (default: claude)\n  --claude-args <args>          Local Claude CLI args (default: --print)\n  --copilot-command <cmd>       Local Copilot CLI command (default: copilot)\n  --copilot-args <args>         Local Copilot CLI args\n  --mention-only <true|false>   Reply only when @mentioned outside DMs (default: true)\n\nExample:\n  agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot\n";

package/dist/cli-args.js

@@ -0,0 +1,68 @@
+/**
+ * Maps `agents-host start` CLI flags to the env vars `config.ts` reads.
+ * Keeping this as a plain lookup table (rather than duplicating
+ * `loadConfigFromEnv`'s parsing logic) means the CLI and the plain
+ * env-var entry point (`index.ts`) always agree on defaults/validation.
+ */
+export const CLI_FLAG_TO_ENV = {
+    name: 'BORGEE_AGENT_NAME',
+    provider: 'RUNTIME_PROVIDER',
+    'claude-command': 'CLAUDE_COMMAND',
+    'claude-args': 'CLAUDE_ARGS',
+    'copilot-command': 'COPILOT_COMMAND',
+    'copilot-args': 'COPILOT_ARGS',
+    'mention-only': 'RESPOND_ON_MENTION_ONLY',
+};
+export class CliUsageError extends Error {
+}
+/**
+ * Parses `start <serverUrl> <apiKey> [--flag value ...]` (the argv slice
+ * after the `start` command word). Throws `CliUsageError` with a
+ * human-readable message on any usage problem instead of exiting the
+ * process, so callers (and tests) can decide how to report it.
+ */
+export function parseStartArgs(argv) {
+    const positionals = [];
+    const env = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith('--')) {
+            const flag = arg.slice(2);
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new CliUsageError(`Missing value for --${flag}`);
+            }
+            const envKey = CLI_FLAG_TO_ENV[flag];
+            if (!envKey) {
+                throw new CliUsageError(`Unknown option: --${flag}`);
+            }
+            env[envKey] = value;
+            i++;
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    const [serverUrl, apiKey, ...extra] = positionals;
+    if (!serverUrl)
+        throw new CliUsageError('Missing <serverUrl>');
+    if (!apiKey)
+        throw new CliUsageError('Missing <apiKey>');
+    if (extra.length > 0)
+        throw new CliUsageError(`Unexpected argument: ${extra[0]}`);
+    return { serverUrl, apiKey, env };
+}
+export const USAGE = `Usage: agents-host start <serverUrl> <apiKey> [options]
+
+Options:
+  --name <name>                 Display name (default: Assistant)
+  --provider <claude|copilot>   Runtime provider (default: claude)
+  --claude-command <cmd>        Local Claude CLI command (default: claude)
+  --claude-args <args>          Local Claude CLI args (default: --print)
+  --copilot-command <cmd>       Local Copilot CLI command (default: copilot)
+  --copilot-args <args>         Local Copilot CLI args
+  --mention-only <true|false>   Reply only when @mentioned outside DMs (default: true)
+
+Example:
+  agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot
+`;

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { CliUsageError, parseStartArgs, USAGE } from './cli-args.js';
+import { runMain } from './run.js';
+function fail(message) {
+    if (message)
+        console.error(`[agents-host] ${message}`);
+    console.error(USAGE);
+    process.exit(message ? 1 : 0);
+}
+const [command, ...rest] = process.argv.slice(2);
+if (command === undefined || command === '--help' || command === '-h') {
+    fail();
+}
+if (command !== 'start') {
+    fail(`Unknown command: ${command}`);
+}
+try {
+    const { serverUrl, apiKey, env } = parseStartArgs(rest);
+    process.env.BORGEE_BASE_URL = serverUrl;
+    process.env.BORGEE_AGENT_API_KEY = apiKey;
+    for (const [key, value] of Object.entries(env)) {
+        process.env[key] = value;
+    }
+}
+catch (error) {
+    if (error instanceof CliUsageError) {
+        fail(error.message);
+    }
+    throw error;
+}
+runMain().catch((error) => {
+    console.error('[agents-host] fatal error:', error);
+    process.exitCode = 1;
+});

package/dist/config.d.ts

@@ -0,0 +1,7 @@
+import type { AgentsHostConfig } from './types.js';
+/**
+ * Loads agents-host configuration from environment variables. This process
+ * hosts exactly one Borgee agent (`BORGEE_AGENT_API_KEY`) — to run more
+ * agents, run more processes with different env vars.
+ */
+export declare function loadConfigFromEnv(): AgentsHostConfig;

package/dist/config.js

@@ -0,0 +1,46 @@
+function requireEnv(name) {
+    const value = process.env[name];
+    if (!value || value.trim().length === 0) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value.trim();
+}
+function envOr(name, fallback) {
+    const value = process.env[name];
+    return value && value.trim().length > 0 ? value.trim() : fallback;
+}
+function envBoolOr(name, fallback) {
+    const value = process.env[name];
+    if (value === undefined || value.trim().length === 0)
+        return fallback;
+    return ['1', 'true', 'yes', 'on'].includes(value.trim().toLowerCase());
+}
+function parseArgs(value) {
+    return value.trim().length > 0 ? value.trim().split(/\s+/) : [];
+}
+function resolveProvider() {
+    const raw = envOr('RUNTIME_PROVIDER', 'claude').toLowerCase();
+    if (raw === 'claude' || raw === 'copilot')
+        return raw;
+    throw new Error(`Unsupported RUNTIME_PROVIDER: ${raw} (expected "claude" or "copilot")`);
+}
+/**
+ * Loads agents-host configuration from environment variables. This process
+ * hosts exactly one Borgee agent (`BORGEE_AGENT_API_KEY`) — to run more
+ * agents, run more processes with different env vars.
+ */
+export function loadConfigFromEnv() {
+    return {
+        borgeeBaseUrl: requireEnv('BORGEE_BASE_URL'),
+        claudeCommand: envOr('CLAUDE_COMMAND', 'claude'),
+        claudeArgs: parseArgs(envOr('CLAUDE_ARGS', '--print')),
+        copilotCommand: envOr('COPILOT_COMMAND', 'copilot'),
+        copilotArgs: parseArgs(envOr('COPILOT_ARGS', '-s --no-color --allow-all-tools --output-format text')),
+        agent: {
+            agentApiKey: requireEnv('BORGEE_AGENT_API_KEY'),
+            agentName: envOr('BORGEE_AGENT_NAME', 'Assistant'),
+            respondOnMentionOnly: envBoolOr('RESPOND_ON_MENTION_ONLY', true),
+            provider: resolveProvider(),
+        },
+    };
+}

package/dist/context/prompt.d.ts

@@ -0,0 +1,15 @@
+import type { ProviderKind } from '../types.js';
+/**
+ * Builds the per-turn prompt. Conversation memory is intentionally NOT
+ * assembled here: each provider's CLI client resumes a native per-channel
+ * session (Claude `--resume`, Copilot `--session-id`), so the CLI itself
+ * already has the prior turns. This only needs to carry the agent's
+ * identity/instructions plus the new incoming message.
+ */
+export declare function buildPrompt(params: {
+    agentName: string;
+    provider: ProviderKind;
+    channelId: string;
+    incomingAuthorId: string;
+    incomingContent: string;
+}): string;

package/dist/context/prompt.js

@@ -0,0 +1,24 @@
+function providerLabel(provider) {
+    return provider === 'copilot' ? 'GitHub Copilot' : 'Claude';
+}
+/**
+ * Builds the per-turn prompt. Conversation memory is intentionally NOT
+ * assembled here: each provider's CLI client resumes a native per-channel
+ * session (Claude `--resume`, Copilot `--session-id`), so the CLI itself
+ * already has the prior turns. This only needs to carry the agent's
+ * identity/instructions plus the new incoming message.
+ */
+export function buildPrompt(params) {
+    return [
+        `You are ${params.agentName}, a helpful AI teammate inside Borgee.`,
+        `Your current backend provider is ${providerLabel(params.provider)} (${params.provider}).`,
+        'You are replying inside a shared collaboration channel.',
+        'Be concise, helpful, and honest about uncertainty.',
+        'Do not claim to have performed actions you did not actually perform.',
+        `If the user asks who you are, what powers you, or which backend/provider you use, mention that you are currently running on ${providerLabel(params.provider)}.`,
+        `Channel: ${params.channelId}`,
+        '',
+        `New message from ${params.incomingAuthorId}:`,
+        params.incomingContent,
+    ].join('\n');
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,9 @@
+import { runMain } from './run.js';
+// Plain env-var entry point (`pnpm dev` / `pnpm start`). For the CLI entry
+// point that accepts `agents-host start <serverUrl> <apiKey> ...`, see
+// cli.ts, which sets the equivalent env vars from argv and delegates to the
+// same runMain().
+runMain().catch((error) => {
+    console.error('[agents-host] fatal error:', error);
+    process.exitCode = 1;
+});

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

@@ -0,0 +1,8 @@
+import type { ProviderAdapter } from '../provider-adapter.js';
+import type { ProviderInput, ProviderReply } from '../../types.js';
+import { ClaudeCliClient } from './cli-client.js';
+export declare class ClaudeProviderAdapter implements ProviderAdapter {
+    private readonly cli;
+    constructor(cli: ClaudeCliClient);
+    generateReply(input: ProviderInput): Promise<ProviderReply>;
+}

package/dist/providers/claude/adapter.js

@@ -0,0 +1,18 @@
+import { buildPrompt } from '../../context/prompt.js';
+export class ClaudeProviderAdapter {
+    cli;
+    constructor(cli) {
+        this.cli = cli;
+    }
+    async generateReply(input) {
+        const prompt = buildPrompt({
+            agentName: input.agentName,
+            provider: input.provider,
+            channelId: input.channelId,
+            incomingAuthorId: input.incomingAuthorId,
+            incomingContent: input.incomingContent,
+        });
+        const text = await this.cli.generateReply(input.channelId, prompt);
+        return { text };
+    }
+}

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

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+export declare class ClaudeCliClient {
+    private readonly command;
+    private readonly args;
+    private readonly sessionIdsByChannel;
+    constructor(command: string, args: string[]);
+    generateReply(channelId: string, prompt: string): Promise<string>;
+    private run;
+}

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

@@ -0,0 +1,71 @@
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+/**
+ * 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.
+ */
+export class ClaudeCliClient {
+    command;
+    args;
+    sessionIdsByChannel = new Map();
+    constructor(command, args) {
+        this.command = command;
+        this.args = args;
+    }
+    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) {
+        return new Promise((resolve, reject) => {
+            const child = spawn(this.command, args, {
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            child.stdout.setEncoding('utf8');
+            child.stderr.setEncoding('utf8');
+            child.stdout.on('data', (chunk) => {
+                stdout += chunk;
+            });
+            child.stderr.on('data', (chunk) => {
+                stderr += chunk;
+            });
+            child.on('error', (error) => {
+                reject(error);
+            });
+            child.on('close', (code) => {
+                if (code !== 0) {
+                    reject(new Error(`Claude CLI failed with code ${code}: ${stderr.trim()}`));
+                    return;
+                }
+                const text = stdout.trim();
+                if (!text) {
+                    reject(new Error('Claude CLI returned empty output'));
+                    return;
+                }
+                resolve(text);
+            });
+            child.stdin.write(prompt);
+            child.stdin.end();
+        });
+    }
+}

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

@@ -0,0 +1,8 @@
+import type { ProviderAdapter } from '../provider-adapter.js';
+import type { 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>;
+}

package/dist/providers/copilot/adapter.js

@@ -0,0 +1,18 @@
+import { buildPrompt } from '../../context/prompt.js';
+export class CopilotProviderAdapter {
+    cli;
+    constructor(cli) {
+        this.cli = cli;
+    }
+    async generateReply(input) {
+        const prompt = buildPrompt({
+            agentName: input.agentName,
+            provider: input.provider,
+            channelId: input.channelId,
+            incomingAuthorId: input.incomingAuthorId,
+            incomingContent: input.incomingContent,
+        });
+        const text = await this.cli.generateReply(input.channelId, prompt);
+        return { text };
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * CLI client for the GitHub Copilot CLI (`copilot`) non-interactive mode,
+ * with native per-channel session continuity.
+ *
+ * Unlike the Claude CLI, Copilot's non-interactive mode takes the prompt as
+ * a `-p/--prompt` argument rather than reading it from stdin, so the prompt
+ * is appended to the configured base args on every invocation instead of
+ * being written to the child process's stdin.
+ *
+ * Verified CLI behavior (`copilot --help` + empirical check): `--session-id
+ * <uuid>` both *creates* a new session pinned to that UUID (first call) and
+ * *resumes* it (subsequent calls with the same UUID) — one flag covers both
+ * cases, unlike Claude's `--session-id`/`--resume` split. No message history
+ * is kept on our side — the CLI's own session storage is the single source
+ * of truth for conversation memory.
+ */
+export declare class CopilotCliClient {
+    private readonly command;
+    private readonly args;
+    private readonly sessionIdsByChannel;
+    constructor(command: string, args: string[]);
+    generateReply(channelId: string, prompt: string): Promise<string>;
+    private run;
+}

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

@@ -0,0 +1,65 @@
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+/**
+ * CLI client for the GitHub Copilot CLI (`copilot`) non-interactive mode,
+ * with native per-channel session continuity.
+ *
+ * Unlike the Claude CLI, Copilot's non-interactive mode takes the prompt as
+ * a `-p/--prompt` argument rather than reading it from stdin, so the prompt
+ * is appended to the configured base args on every invocation instead of
+ * being written to the child process's stdin.
+ *
+ * Verified CLI behavior (`copilot --help` + empirical check): `--session-id
+ * <uuid>` both *creates* a new session pinned to that UUID (first call) and
+ * *resumes* it (subsequent calls with the same UUID) — one flag covers both
+ * cases, unlike Claude's `--session-id`/`--resume` split. No message history
+ * is kept on our side — the CLI's own session storage is the single source
+ * of truth for conversation memory.
+ */
+export class CopilotCliClient {
+    command;
+    args;
+    sessionIdsByChannel = new Map();
+    constructor(command, args) {
+        this.command = command;
+        this.args = args;
+    }
+    async generateReply(channelId, prompt) {
+        const sessionId = this.sessionIdsByChannel.get(channelId) ?? randomUUID();
+        const text = await this.run([...this.args, `--session-id=${sessionId}`, '-p', prompt]);
+        this.sessionIdsByChannel.set(channelId, sessionId);
+        return text;
+    }
+    async run(args) {
+        return new Promise((resolve, reject) => {
+            const child = spawn(this.command, args, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            child.stdout.setEncoding('utf8');
+            child.stderr.setEncoding('utf8');
+            child.stdout.on('data', (chunk) => {
+                stdout += chunk;
+            });
+            child.stderr.on('data', (chunk) => {
+                stderr += chunk;
+            });
+            child.on('error', (error) => {
+                reject(error);
+            });
+            child.on('close', (code) => {
+                if (code !== 0) {
+                    reject(new Error(`Copilot CLI failed with code ${code}: ${stderr.trim()}`));
+                    return;
+                }
+                const text = stdout.trim();
+                if (!text) {
+                    reject(new Error('Copilot CLI returned empty output'));
+                    return;
+                }
+                resolve(text);
+            });
+        });
+    }
+}

package/dist/providers/create-provider.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderAdapter } from './provider-adapter.js';
+import type { ProviderRuntimeConfig } from '../types.js';
+export declare function createProvider(config: ProviderRuntimeConfig): ProviderAdapter;

package/dist/providers/create-provider.js

@@ -0,0 +1,18 @@
+import { ClaudeCliClient } from './claude/cli-client.js';
+import { ClaudeProviderAdapter } from './claude/adapter.js';
+import { CopilotCliClient } from './copilot/cli-client.js';
+import { CopilotProviderAdapter } from './copilot/adapter.js';
+export function createProvider(config) {
+    switch (config.provider) {
+        case 'claude': {
+            const cli = new ClaudeCliClient(config.claudeCommand, config.claudeArgs);
+            return new ClaudeProviderAdapter(cli);
+        }
+        case 'copilot': {
+            const cli = new CopilotCliClient(config.copilotCommand, config.copilotArgs);
+            return new CopilotProviderAdapter(cli);
+        }
+        default:
+            throw new Error(`Unsupported provider: ${String(config.provider)}`);
+    }
+}

package/dist/providers/provider-adapter.d.ts

@@ -0,0 +1,4 @@
+import type { ProviderInput, ProviderReply } from '../types.js';
+export interface ProviderAdapter {
+    generateReply(input: ProviderInput): Promise<ProviderReply>;
+}

package/dist/providers/provider-adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/run.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Loads config from the environment, starts an `AgentsHost`, and wires up
+ * graceful shutdown on SIGINT/SIGTERM. Shared by the plain env-var entry
+ * point (`index.ts`) and the CLI entry point (`cli.ts`), which sets the
+ * relevant env vars from argv before delegating here.
+ */
+export declare function runMain(): Promise<void>;

package/dist/run.js

@@ -0,0 +1,22 @@
+import { loadConfigFromEnv } from './config.js';
+import { AgentsHost } from './agents-host.js';
+/**
+ * Loads config from the environment, starts an `AgentsHost`, and wires up
+ * graceful shutdown on SIGINT/SIGTERM. Shared by the plain env-var entry
+ * point (`index.ts`) and the CLI entry point (`cli.ts`), which sets the
+ * relevant env vars from argv before delegating here.
+ */
+export async function runMain() {
+    const config = loadConfigFromEnv();
+    const host = new AgentsHost(config);
+    const shutdown = (signal) => {
+        console.log(`[agents-host] received ${signal}, shutting down`);
+        host
+            .stop()
+            .catch((error) => console.error('[agents-host] error during shutdown:', error))
+            .finally(() => process.exit(0));
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    await host.start();
+}

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+export type ProviderKind = 'claude' | 'copilot';
+export interface ProviderCommandConfig {
+    claudeCommand: string;
+    claudeArgs: string[];
+    copilotCommand: string;
+    copilotArgs: string[];
+}
+export interface ProviderRuntimeConfig extends ProviderCommandConfig {
+    provider: ProviderKind;
+}
+/**
+ * Single hosted-agent configuration. The minimal agents host supports exactly
+ * one Borgee agent per process — running multiple agents means running
+ * multiple processes with different env vars (see README).
+ */
+export interface HostedAgentConfig {
+    agentApiKey: string;
+    agentName: string;
+    respondOnMentionOnly: boolean;
+    provider: ProviderKind;
+}
+export interface AgentsHostConfig extends ProviderCommandConfig {
+    borgeeBaseUrl: string;
+    agent: HostedAgentConfig;
+}
+export interface ChannelMessageEvent {
+    type?: string;
+    channel_id: string;
+    channel_type?: string;
+    message_id?: string;
+    user_id?: string;
+    sender_id?: string;
+    content?: string;
+    body?: string;
+    content_type?: string;
+    created_at?: number;
+    [key: string]: unknown;
+}
+export interface MeResponseUser {
+    id: string;
+    display_name?: string;
+    role?: string;
+}
+export interface ProviderInput {
+    agentName: string;
+    provider: ProviderKind;
+    channelId: string;
+    incomingAuthorId: string;
+    incomingContent: string;
+}
+export interface ProviderReply {
+    text: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@borgee/agents-host",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "description": "Minimal local agents host: connects a local Claude/Copilot CLI to a Borgee agent over @borgee/plugin-sdk",
+  "bin": {
+    "agents-host": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codetreker/borgee.git",
+    "directory": "packages/runtimes/agents-host"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@borgee/plugin-sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "predev": "pnpm --filter @borgee/plugin-sdk build",
+    "dev": "tsx src/index.ts",
+    "precli": "pnpm --filter @borgee/plugin-sdk build",
+    "cli": "tsx src/cli.ts",
+    "prestart": "pnpm --filter @borgee/plugin-sdk build",
+    "start": "node dist/index.js",
+    "prebuild": "pnpm --filter @borgee/plugin-sdk build",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "pretest": "pnpm --filter @borgee/plugin-sdk build",
+    "test": "vitest run"
+  }
+}