@borgee/agents-host 0.2.2 → 0.2.28

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

@@ -1,10 +1,21 @@
-import type { ChannelMessageEvent, MeResponseUser, PostedMessage } from '../types.js';
+import type { ChannelSummary, ChannelHistoryEntry, ChannelMessageEvent, CreateTaskInput, DirectoryUser, MeResponseUser, PostMessageInput, PostedMessage, ReadChannelHistoryInput, Task, UpdateTaskInput } from '../types.js';
 export interface ChatControlPlane {
     connect(onMessage: (message: ChannelMessageEvent) => void): Promise<void>;
     close(): Promise<void>;
-    postMessage(channelId: string, content: string): Promise<PostedMessage>;
+    postMessage(input: PostMessageInput): Promise<PostedMessage>;
     editMessage(messageId: string, content: string): Promise<void>;
     deleteMessage(messageId: string): Promise<void>;
     startTyping(channelId: string): () => void;
     getMe(): Promise<MeResponseUser>;
+    listUsers(): Promise<DirectoryUser[]>;
+    listChannels(): Promise<ChannelSummary[]>;
+    readChannelHistory(input: ReadChannelHistoryInput): Promise<ChannelHistoryEntry[]>;
+    createTask(input: CreateTaskInput): Promise<Task>;
+    listTasks(input: {
+        channelId: string;
+    }): Promise<Task[]>;
+    getTask(input: {
+        taskId: string;
+    }): Promise<Task>;
+    updateTask(input: UpdateTaskInput): Promise<Task>;
 }

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

@@ -1,7 +1,7 @@
 import { type BorgeePluginClient, type BorgeePluginOptions, type InboundMessageEvent } from '@borgee/plugin-sdk';
-import type { ChannelMessageEvent, MeResponseUser, PostedMessage } from '../types.js';
+import type { ChannelSummary, ChannelHistoryEntry, ChannelMessageEvent, CreateTaskInput, DirectoryUser, MeResponseUser, PostMessageInput, PostedMessage, ReadChannelHistoryInput, Task, UpdateTaskInput } from '../types.js';
 import type { ChatControlPlane } from './chat-control-plane.js';
-type PluginClientLike = Pick<BorgeePluginClient, 'agentId' | 'close' | 'connect' | 'deleteMessage' | 'editMessage' | 'getMe' | 'on' | 'sendMessage' | 'startTyping'>;
+type PluginClientLike = Pick<BorgeePluginClient, 'agentId' | 'close' | 'connect' | 'createTask' | 'deleteMessage' | 'editMessage' | 'getMe' | 'getTask' | 'listChannels' | 'listTasks' | 'listUsers' | 'on' | 'readHistory' | 'sendMessage' | 'startTyping' | 'updateTask'>;
 type PluginClientFactory = (options: BorgeePluginOptions) => PluginClientLike;
 type SdkChatControlPlaneOptions = Pick<BorgeePluginOptions, 'cursorStore' | 'pluginId'>;
 /**
@@ -18,11 +18,22 @@ export declare class SdkChatControlPlane implements ChatControlPlane {
     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>;
+    postMessage(input: PostMessageInput): Promise<PostedMessage>;
     editMessage(messageId: string, content: string): Promise<void>;
     deleteMessage(messageId: string): Promise<void>;
     startTyping(channelId: string): () => void;
     getMe(): Promise<MeResponseUser>;
+    listUsers(): Promise<DirectoryUser[]>;
+    readChannelHistory(input: ReadChannelHistoryInput): Promise<ChannelHistoryEntry[]>;
+    listChannels(): Promise<ChannelSummary[]>;
+    createTask(input: CreateTaskInput): Promise<Task>;
+    listTasks(input: {
+        channelId: string;
+    }): Promise<Task[]>;
+    getTask(input: {
+        taskId: string;
+    }): Promise<Task>;
+    updateTask(input: UpdateTaskInput): Promise<Task>;
 }
 export declare function mapInboundToChannelMessage(event: InboundMessageEvent): ChannelMessageEvent;
 export {};

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

@@ -47,8 +47,12 @@ export class SdkChatControlPlane {
         this.unsubscribe = null;
         await this.client.close();
     }
-    async postMessage(channelId, content) {
-        const sent = await this.client.sendMessage({ channelId, body: content });
+    async postMessage(input) {
+        const sent = await this.client.sendMessage({
+            channelId: input.channelId,
+            body: input.body,
+            replyToId: input.replyToId,
+        });
         return { messageId: sent.messageId };
     }
     async editMessage(messageId, content) {
@@ -72,10 +76,58 @@ export class SdkChatControlPlane {
         };
         return this.me;
     }
+    async listUsers() {
+        const users = await this.client.listUsers();
+        return users.map((user) => ({
+            id: user.id,
+            display_name: user.displayName,
+            kind: user.kind,
+        }));
+    }
+    async readChannelHistory(input) {
+        const messages = await this.client.readHistory({
+            channelId: input.channelId,
+            before: input.before,
+            after: input.after,
+            limit: input.limit,
+        });
+        return messages.map((message) => ({
+            id: message.id,
+            channelId: message.channelId,
+            authorId: message.authorId,
+            body: message.body,
+            contentType: message.contentType,
+            type: message.type,
+            replyToId: message.replyToId,
+            createdAt: message.createdAt,
+            editedAt: message.editedAt,
+        }));
+    }
+    async listChannels() {
+        const channels = await this.client.listChannels();
+        return channels.map((channel) => ({
+            id: channel.id,
+            name: channel.name,
+            kind: channel.kind,
+        }));
+    }
+    async createTask(input) {
+        return this.client.createTask(input);
+    }
+    async listTasks(input) {
+        return this.client.listTasks(input);
+    }
+    async getTask(input) {
+        return this.client.getTask(input);
+    }
+    async updateTask(input) {
+        return this.client.updateTask(input);
+    }
 }
 export function mapInboundToChannelMessage(event) {
     return {
         type: event.kind,
+        ...(event.message?.type != null ? { message_type: event.message.type } : {}),
         channel_id: event.channelId,
         channel_type: event.channelType,
         message_id: event.message?.id ?? event.messageId,

package/dist/cli-args.d.ts

@@ -1,8 +1,9 @@
 /**
- * Maps single-agent `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 env-var entry
- * point (`index.ts`) always agree on defaults/validation.
+ * Maps `agents-host start` / `agents-host start-managed` agent 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
+ * standalone env-var entry point (`index.ts`) always agree on
+ * defaults/validation.
  */
 export declare const CLI_FLAG_TO_ENV: Record<string, string>;
 export type ParsedStartArgs = ParsedSingleAgentStartArgs | ParsedLocalConfigStartArgs;
@@ -10,11 +11,18 @@ export interface ParsedSingleAgentStartArgs {
     mode: 'single-agent';
     serverUrl: string;
     apiKey: string;
+    debug: boolean;
+    env: Record<string, string>;
+}
+export interface ParsedManagedStartArgs {
+    serverUrl: string;
+    apiKey?: string;
     env: Record<string, string>;
 }
 export interface ParsedLocalConfigStartArgs {
     mode: 'local-config';
     configPath: string;
+    debug: boolean;
 }
 export interface ParsedValidateArgs {
     configPath: string;
@@ -35,11 +43,44 @@ export interface ParsedGenerateConfigFromStdinArgs {
     input: 'stdin';
 }
 export type ParsedGenerateConfigArgs = ParsedGenerateConfigFromArgvArgs | ParsedGenerateConfigFromStdinArgs;
+export interface ParsedDaemonArgs {
+    rootPath: string;
+    debug: boolean;
+}
+export interface ParsedLogArgs {
+    serverUrl: string;
+    lines: number;
+    follow: boolean;
+    pathOnly: boolean;
+}
+export interface ParsedDescribeManagedArgs {
+    serverUrl: string;
+}
+export interface ParsedCleanupManagedArgs {
+    serverUrl: string;
+    purge: boolean;
+}
+export interface ParsedApplyManagedFromArgvArgs {
+    serverUrl: string;
+    input: 'argv';
+    specJson: string;
+}
+export interface ParsedApplyManagedFromStdinArgs {
+    serverUrl: string;
+    input: 'stdin';
+}
+export type ParsedApplyManagedArgs = ParsedApplyManagedFromArgvArgs | ParsedApplyManagedFromStdinArgs;
 export declare class CliUsageError extends Error {
 }
 export declare function parseStartArgs(argv: string[]): ParsedStartArgs;
+export declare function parseManagedStartArgs(argv: string[]): ParsedManagedStartArgs;
 export declare function parseValidateArgs(argv: string[]): ParsedValidateArgs;
 export declare function parseDescribeArgs(argv: string[]): ParsedDescribeArgs;
 export declare function parsePrintLayoutArgs(argv: string[]): ParsedPrintLayoutArgs;
 export declare function parseGenerateConfigArgs(argv: string[]): ParsedGenerateConfigArgs;
-export declare const USAGE = "Usage:\n  agents-host start <serverUrl> <apiKey> [options]\n  agents-host start --config <path-to-host-config>\n  agents-host validate --config <path-to-host-config>\n  agents-host describe --config <path-to-host-config>\n  agents-host print-layout --root <dir>\n  agents-host generate-config --root <dir> --stdin\n  agents-host generate-config --root <dir> --spec-json <json>\n\nSingle-agent options:\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>           Ignored by the Copilot ACP prototype\n  --copilot-session-ttl-minutes <minutes>\n                                   Idle session TTL for Copilot ACP sessions (default: 2880)\n\nLocal-config mode:\n  start --config <path>           Start agents + supervisor + watchers from a host config file\n  validate --config <path>        Validate local-config files without starting agents or watchers\n  describe --config <path>        Print the current managed full-set spec as JSON\n  print-layout --root <dir>       Print the canonical default local-config layout as JSON\n  generate-config --root <dir> --stdin  Materialize canonical local-config files from stdin\n  generate-config --root <dir> --spec-json <json>\n                                   Compatibility input; JSON is exposed in process arguments\n\nExamples:\n  agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot\n  agents-host start --config ./agents-host.yaml\n  agents-host validate --config ./agents-host.yaml\n  agents-host describe --config ./agents-host.yaml\n  agents-host print-layout --root ./runtime-root\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host generate-config --root ./runtime-root --stdin\n";
+export declare function parseDaemonArgs(argv: string[]): ParsedDaemonArgs;
+export declare function parseLogArgs(argv: string[]): ParsedLogArgs;
+export declare function parseDescribeManagedArgs(argv: string[]): ParsedDescribeManagedArgs;
+export declare function parseCleanupManagedArgs(argv: string[]): ParsedCleanupManagedArgs;
+export declare function parseApplyManagedArgs(argv: string[]): ParsedApplyManagedArgs;
+export declare const USAGE = "Usage:\n  agents-host start <serverUrl> <apiKey> [options]\n  agents-host start-managed <serverUrl>\n  agents-host start-managed <serverUrl> <apiKey> [agent-options]\n  agents-host describe-managed <serverUrl>\n  agents-host cleanup-managed <serverUrl> [--purge]\n  agents-host apply-managed <serverUrl> --stdin\n  agents-host apply-managed <serverUrl> --spec-json <json>\n  agents-host log <serverUrl> [--lines <n>] [--follow]\n  agents-host log <serverUrl> --path\n  agents-host start --config <path-to-host-config> [--debug]\n  agents-host validate --config <path-to-host-config>\n  agents-host describe --config <path-to-host-config>\n  agents-host print-layout --root <dir>\n  agents-host generate-config --root <dir> --stdin\n  agents-host generate-config --root <dir> --spec-json <json>\n\nForeground start options:\n  --debug                         Enable host/provider debug logs (or set AGENTS_HOST_DEBUG=1)\n\nSingle-agent agent options:\n  --name <name>                   Display name (default: Assistant)\n  --provider <claude|codex|copilot>\n                                   Runtime provider (default: claude)\n  --claude-command <cmd>          Local Claude CLI command (default: claude)\n  --claude-args <args>            Local Claude CLI args (default: --print --permission-mode bypassPermissions)\n  --codex-command <cmd>           Local Codex ACP adapter command (default: codex-acp)\n  --codex-args <args>             Local Codex ACP adapter args\n  --copilot-command <cmd>         Local Copilot CLI command (default: copilot)\n  --copilot-args <args>           Ignored by the Copilot ACP prototype\n  --copilot-session-ttl-minutes <minutes>\n                                   Idle session TTL for Copilot ACP sessions (default: 2880)\n\nCommand summary:\n  start <serverUrl> <apiKey>      Start one foreground hosted agent (legacy-compatible behavior)\n  start --config <path>           Start agents + supervisor + watchers from a host config file\n  start-managed <serverUrl>       Restart or resume an existing per-serverUrl managed daemon\n  start-managed <serverUrl> <apiKey>\n                                   Upsert one agent into the per-serverUrl local daemon and exit after reconcile\n  describe-managed <serverUrl>    Print managed-runtime spec JSON for machine callers\n  cleanup-managed <serverUrl>     Stop one managed-runtime daemon locally; --purge also removes its runtime root\n  apply-managed <serverUrl>       Apply one managed-runtime full-set spec for machine callers\n  log <serverUrl>                 Print the managed daemon log tail for one server runtime\n  validate --config <path>        Validate local-config files without starting agents or watchers\n  describe --config <path>        Print the current managed full-set spec as JSON\n  print-layout --root <dir>       Print the canonical default local-config layout as JSON\n  generate-config --root <dir> --stdin  Materialize canonical local-config files from stdin\n  generate-config --root <dir> --spec-json <json>\n                                   Compatibility input; JSON is exposed in process arguments\n\nExamples:\n  agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot --debug\n  agents-host start-managed https://borgee.example.com\n  agents-host start-managed https://borgee.example.com bgr_xxxxxxxx --provider copilot\n  agents-host describe-managed https://borgee.example.com\n  agents-host cleanup-managed https://borgee.example.com --purge\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host apply-managed https://borgee.example.com --stdin\n  agents-host log https://borgee.example.com --lines 200 --follow\n  agents-host log https://borgee.example.com --path\n  agents-host start --config ./agents-host.yaml --debug\n  agents-host validate --config ./agents-host.yaml\n  agents-host describe --config ./agents-host.yaml\n  agents-host print-layout --root ./runtime-root\n  printf '%s' '{\"host\":{\"borgeeBaseUrl\":\"https://borgee.example.com\"},\"agents\":[{\"key\":\"cp1\",\"name\":\"Copilot\",\"apiKey\":\"bgr_xxx\",\"provider\":\"copilot\"}]}' | agents-host generate-config --root ./runtime-root --stdin\n";

package/dist/cli-args.js

@@ -1,26 +1,72 @@
 /**
- * Maps single-agent `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 env-var entry
- * point (`index.ts`) always agree on defaults/validation.
+ * Maps `agents-host start` / `agents-host start-managed` agent 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
+ * standalone 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',
+    'codex-command': 'CODEX_COMMAND',
+    'codex-args': 'CODEX_ARGS',
     'copilot-command': 'COPILOT_COMMAND',
     'copilot-args': 'COPILOT_ARGS',
     'copilot-session-ttl-minutes': 'COPILOT_SESSION_TTL_MINUTES',
 };
 const SINGLE_AGENT_FLAG_NAMES = new Set(Object.keys(CLI_FLAG_TO_ENV));
+const FLAGS_ALLOWING_DASH_PREFIX_VALUE = new Set(['claude-args', 'codex-args', 'copilot-args']);
 export class CliUsageError extends Error {
 }
+function parseSingleAgentPositionals(positionals) {
+    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 };
+}
+function readSingleAgentFlagValue(argv, index, flag) {
+    const value = argv[index + 1];
+    if (value === undefined ||
+        (value.startsWith('--') && !FLAGS_ALLOWING_DASH_PREFIX_VALUE.has(flag))) {
+        throw new CliUsageError(`Missing value for --${flag}`);
+    }
+    return value;
+}
+function applySingleAgentFlag(argv, index, env, seenSingleAgentFlags) {
+    const flag = argv[index]?.slice(2) ?? '';
+    const envKey = CLI_FLAG_TO_ENV[flag];
+    if (!envKey) {
+        throw new CliUsageError(`Unknown option: --${flag}`);
+    }
+    env[envKey] = readSingleAgentFlagValue(argv, index, flag);
+    seenSingleAgentFlags.add(flag);
+    return index + 1;
+}
+function parseNonNegativeInteger(value, flag) {
+    if (!/^\d+$/u.test(value)) {
+        throw new CliUsageError(`--${flag} must be a non-negative integer`);
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isSafeInteger(parsed)) {
+        throw new CliUsageError(`--${flag} must be a non-negative integer`);
+    }
+    return parsed;
+}
 export function parseStartArgs(argv) {
     const positionals = [];
     const env = {};
     const seenSingleAgentFlags = new Set();
     let configPath;
+    let debug = false;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (!arg.startsWith('--')) {
@@ -28,25 +74,22 @@ export function parseStartArgs(argv) {
             continue;
         }
         const flag = arg.slice(2);
-        const value = argv[i + 1];
-        if (value === undefined || value.startsWith('--')) {
-            throw new CliUsageError(`Missing value for --${flag}`);
+        if (flag === 'debug') {
+            if (debug) {
+                throw new CliUsageError('--debug may only be specified once');
+            }
+            debug = true;
+            continue;
         }
         if (flag === 'config') {
             if (configPath !== undefined) {
                 throw new CliUsageError('--config may only be specified once');
             }
-            configPath = value;
+            configPath = readSingleAgentFlagValue(argv, i, flag);
             i++;
             continue;
         }
-        const envKey = CLI_FLAG_TO_ENV[flag];
-        if (!envKey) {
-            throw new CliUsageError(`Unknown option: --${flag}`);
-        }
-        env[envKey] = value;
-        seenSingleAgentFlags.add(flag);
-        i++;
+        i = applySingleAgentFlag(argv, i, env, seenSingleAgentFlags);
     }
     if (configPath !== undefined) {
         if (positionals.length > 0) {
@@ -58,25 +101,49 @@ export function parseStartArgs(argv) {
         return {
             mode: 'local-config',
             configPath,
+            debug,
         };
     }
-    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]}`);
-    }
+    const { serverUrl, apiKey } = parseSingleAgentPositionals(positionals);
     return {
         mode: 'single-agent',
         serverUrl,
         apiKey,
+        debug,
         env,
     };
 }
+export function parseManagedStartArgs(argv) {
+    const positionals = [];
+    const env = {};
+    const seenSingleAgentFlags = new Set();
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const flag = arg.slice(2);
+        if (flag === 'debug') {
+            throw new CliUsageError('start-managed does not support --debug; use foreground start for debug logging');
+        }
+        if (flag === 'config') {
+            throw new CliUsageError('start-managed does not support --config');
+        }
+        i = applySingleAgentFlag(argv, i, env, seenSingleAgentFlags);
+    }
+    if (positionals.length === 1) {
+        if (seenSingleAgentFlags.size > 0) {
+            throw new CliUsageError(`Cannot combine bare start-managed <serverUrl> resume with agent option --${[...seenSingleAgentFlags][0]}; provide <apiKey> to bootstrap or update an agent`);
+        }
+        return {
+            serverUrl: positionals[0],
+            env,
+        };
+    }
+    const { serverUrl, apiKey } = parseSingleAgentPositionals(positionals);
+    return { serverUrl, apiKey, env };
+}
 export function parseValidateArgs(argv) {
     const positionals = [];
     let configPath;
@@ -218,27 +285,234 @@ export function parseGenerateConfigArgs(argv) {
     }
     return { rootPath, input: 'argv', specJson };
 }
+export function parseDaemonArgs(argv) {
+    const positionals = [];
+    let rootPath;
+    let debug = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const flag = arg.slice(2);
+        if (flag === 'debug') {
+            if (debug) {
+                throw new CliUsageError('--debug may only be specified once');
+            }
+            debug = true;
+            continue;
+        }
+        if (flag === 'root') {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new CliUsageError('Missing value for --root');
+            }
+            if (rootPath !== undefined) {
+                throw new CliUsageError('--root may only be specified once');
+            }
+            rootPath = value;
+            i++;
+            continue;
+        }
+        throw new CliUsageError(`Unknown option: --${flag}`);
+    }
+    if (positionals.length > 0) {
+        throw new CliUsageError(`Unexpected argument: ${positionals[0]}`);
+    }
+    if (!rootPath) {
+        throw new CliUsageError('Missing required --root <dir>');
+    }
+    return { rootPath, debug };
+}
+export function parseLogArgs(argv) {
+    const positionals = [];
+    let lines = 100;
+    let follow = false;
+    let pathOnly = false;
+    let linesSpecified = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const flag = arg.slice(2);
+        if (flag === 'follow') {
+            if (follow) {
+                throw new CliUsageError('--follow may only be specified once');
+            }
+            follow = true;
+            continue;
+        }
+        if (flag === 'path') {
+            if (pathOnly) {
+                throw new CliUsageError('--path may only be specified once');
+            }
+            pathOnly = true;
+            continue;
+        }
+        if (flag === 'lines') {
+            if (linesSpecified) {
+                throw new CliUsageError('--lines may only be specified once');
+            }
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new CliUsageError('Missing value for --lines');
+            }
+            lines = parseNonNegativeInteger(value, 'lines');
+            linesSpecified = true;
+            i++;
+            continue;
+        }
+        throw new CliUsageError(`Unknown option: --${flag}`);
+    }
+    const [serverUrl, ...extra] = positionals;
+    if (!serverUrl) {
+        throw new CliUsageError('Missing <serverUrl>');
+    }
+    if (extra.length > 0) {
+        throw new CliUsageError(`Unexpected argument: ${extra[0]}`);
+    }
+    if (pathOnly && (follow || linesSpecified)) {
+        throw new CliUsageError('--path cannot be combined with --follow or --lines');
+    }
+    return { serverUrl, lines, follow, pathOnly };
+}
+export function parseDescribeManagedArgs(argv) {
+    const [serverUrl, ...extra] = argv;
+    if (!serverUrl) {
+        throw new CliUsageError('Missing <serverUrl>');
+    }
+    if (serverUrl.startsWith('--')) {
+        throw new CliUsageError(`Unknown option: ${serverUrl}`);
+    }
+    if (extra.length > 0) {
+        throw new CliUsageError(`Unexpected argument: ${extra[0]}`);
+    }
+    return { serverUrl };
+}
+export function parseCleanupManagedArgs(argv) {
+    const positionals = [];
+    let purge = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const flag = arg.slice(2);
+        if (flag === 'purge') {
+            if (purge) {
+                throw new CliUsageError('--purge may only be specified once');
+            }
+            purge = true;
+            continue;
+        }
+        throw new CliUsageError(`Unknown option: --${flag}`);
+    }
+    const [serverUrl, ...extra] = positionals;
+    if (!serverUrl) {
+        throw new CliUsageError('Missing <serverUrl>');
+    }
+    if (extra.length > 0) {
+        throw new CliUsageError(`Unexpected argument: ${extra[0]}`);
+    }
+    return { serverUrl, purge };
+}
+export function parseApplyManagedArgs(argv) {
+    const positionals = [];
+    let specJson;
+    let stdin = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const flag = arg.slice(2);
+        if (flag === 'stdin') {
+            if (stdin) {
+                throw new CliUsageError('--stdin may only be specified once');
+            }
+            stdin = true;
+            continue;
+        }
+        if (flag === 'spec-json') {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new CliUsageError('Missing value for --spec-json');
+            }
+            if (specJson !== undefined) {
+                throw new CliUsageError('--spec-json may only be specified once');
+            }
+            specJson = value;
+            i++;
+            continue;
+        }
+        throw new CliUsageError(`Unknown option: --${flag}`);
+    }
+    const [serverUrl, ...extra] = positionals;
+    if (!serverUrl) {
+        throw new CliUsageError('Missing <serverUrl>');
+    }
+    if (extra.length > 0) {
+        throw new CliUsageError(`Unexpected argument: ${extra[0]}`);
+    }
+    if (stdin && specJson !== undefined) {
+        throw new CliUsageError('apply-managed accepts exactly one input source: --stdin or --spec-json');
+    }
+    if (stdin) {
+        return { serverUrl, input: 'stdin' };
+    }
+    if (!specJson) {
+        throw new CliUsageError('Missing required input: use --stdin or --spec-json <json>');
+    }
+    return { serverUrl, input: 'argv', specJson };
+}
 export const USAGE = `Usage:
   agents-host start <serverUrl> <apiKey> [options]
-  agents-host start --config <path-to-host-config>
+  agents-host start-managed <serverUrl>
+  agents-host start-managed <serverUrl> <apiKey> [agent-options]
+  agents-host describe-managed <serverUrl>
+  agents-host cleanup-managed <serverUrl> [--purge]
+  agents-host apply-managed <serverUrl> --stdin
+  agents-host apply-managed <serverUrl> --spec-json <json>
+  agents-host log <serverUrl> [--lines <n>] [--follow]
+  agents-host log <serverUrl> --path
+  agents-host start --config <path-to-host-config> [--debug]
   agents-host validate --config <path-to-host-config>
   agents-host describe --config <path-to-host-config>
   agents-host print-layout --root <dir>
   agents-host generate-config --root <dir> --stdin
   agents-host generate-config --root <dir> --spec-json <json>
 
-Single-agent options:
+Foreground start options:
+  --debug                         Enable host/provider debug logs (or set AGENTS_HOST_DEBUG=1)
+
+Single-agent agent options:
   --name <name>                   Display name (default: Assistant)
-  --provider <claude|copilot>     Runtime provider (default: claude)
+  --provider <claude|codex|copilot>
+                                   Runtime provider (default: claude)
   --claude-command <cmd>          Local Claude CLI command (default: claude)
-  --claude-args <args>            Local Claude CLI args (default: --print)
+  --claude-args <args>            Local Claude CLI args (default: --print --permission-mode bypassPermissions)
+  --codex-command <cmd>           Local Codex ACP adapter command (default: codex-acp)
+  --codex-args <args>             Local Codex ACP adapter args
   --copilot-command <cmd>         Local Copilot CLI command (default: copilot)
   --copilot-args <args>           Ignored by the Copilot ACP prototype
   --copilot-session-ttl-minutes <minutes>
                                    Idle session TTL for Copilot ACP sessions (default: 2880)
 
-Local-config mode:
+Command summary:
+  start <serverUrl> <apiKey>      Start one foreground hosted agent (legacy-compatible behavior)
   start --config <path>           Start agents + supervisor + watchers from a host config file
+  start-managed <serverUrl>       Restart or resume an existing per-serverUrl managed daemon
+  start-managed <serverUrl> <apiKey>
+                                   Upsert one agent into the per-serverUrl local daemon and exit after reconcile
+  describe-managed <serverUrl>    Print managed-runtime spec JSON for machine callers
+  cleanup-managed <serverUrl>     Stop one managed-runtime daemon locally; --purge also removes its runtime root
+  apply-managed <serverUrl>       Apply one managed-runtime full-set spec for machine callers
+  log <serverUrl>                 Print the managed daemon log tail for one server runtime
   validate --config <path>        Validate local-config files without starting agents or watchers
   describe --config <path>        Print the current managed full-set spec as JSON
   print-layout --root <dir>       Print the canonical default local-config layout as JSON
@@ -247,8 +521,15 @@ Local-config mode:
                                    Compatibility input; JSON is exposed in process arguments
 
 Examples:
-  agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot
-  agents-host start --config ./agents-host.yaml
+  agents-host start https://borgee.example.com bgr_xxxxxxxx --provider copilot --debug
+  agents-host start-managed https://borgee.example.com
+  agents-host start-managed https://borgee.example.com bgr_xxxxxxxx --provider copilot
+  agents-host describe-managed https://borgee.example.com
+  agents-host cleanup-managed https://borgee.example.com --purge
+  printf '%s' '{"host":{"borgeeBaseUrl":"https://borgee.example.com"},"agents":[{"key":"cp1","name":"Copilot","apiKey":"bgr_xxx","provider":"copilot"}]}' | agents-host apply-managed https://borgee.example.com --stdin
+  agents-host log https://borgee.example.com --lines 200 --follow
+  agents-host log https://borgee.example.com --path
+  agents-host start --config ./agents-host.yaml --debug
   agents-host validate --config ./agents-host.yaml
   agents-host describe --config ./agents-host.yaml
   agents-host print-layout --root ./runtime-root

package/dist/cli.d.ts

@@ -1,14 +1,23 @@
 #!/usr/bin/env node
+import { applyManagedSpec, bootstrapManagedDaemonStart, cleanupManagedRuntime, describeManagedSpec } from './managed-daemon.js';
+import { runManagedDaemonLogCommand } from './managed-daemon-log.js';
 import { describeLocalConfig, generateLocalConfig, printLocalConfigLayout, runMain, validateLocalConfig } from './run.js';
 export interface CliDeps {
     env?: NodeJS.ProcessEnv;
     logger?: Pick<Console, 'error'>;
     runMain?: typeof runMain;
+    bootstrapManagedDaemonStart?: typeof bootstrapManagedDaemonStart;
+    startManagedDaemon?: (rootPath: string, debug: boolean) => Promise<void>;
     validateLocalConfig?: typeof validateLocalConfig;
     describeLocalConfig?: typeof describeLocalConfig;
     printLocalConfigLayout?: typeof printLocalConfigLayout;
     generateLocalConfig?: typeof generateLocalConfig;
     readStdin?: () => Promise<string>;
+    runManagedDaemonLogCommand?: typeof runManagedDaemonLogCommand;
+    describeManagedSpec?: typeof describeManagedSpec;
+    cleanupManagedRuntime?: typeof cleanupManagedRuntime;
+    applyManagedSpec?: typeof applyManagedSpec;
+    stdout?: Pick<Console, 'log'>;
 }
 interface CliEntrypointDeps {
     realpath?: (path: string) => string;