maka-agent 0.2.0-dev.29.20260912 → 0.2.0-dev.30.20260912

package/dist/cli-core.js

@@ -22,6 +22,7 @@ import { fileURLToPath } from 'node:url';
 import { deriveMakaDataRoots, resolveMakaDataRoots } from './workspace-root.js';
 import { configureRuntimeHostPeerClient, resolveRuntimeHostNativePath, } from './runtime-host-peer-artifact.js';
 import { parseRuntimeHostCommand, parseRuntimeHostInstalledUpdateCommand, } from './runtime-host-cli.js';
+import { sessionBundleHelpText } from './runtime-host-help.js';
 import { resolveCliUiLocale } from './cli-ui-locale.js';
 export const RELEASE_MAKA_CLI_LAUNCH_OPTIONS = {
     dataProfileName: 'Maka',
@@ -52,16 +53,17 @@ export function parseMakaCliArgs(argv, version, cliCommand = RELEASE_MAKA_CLI_LA
         return { kind: 'run', args: argv.slice(1) };
     if (first === 'activate')
         return { kind: 'activate', args: argv.slice(1) };
-    if (first === 'session-export')
-        return { kind: 'session-export', args: argv.slice(1) };
-    if (first === 'session-import')
-        return { kind: 'session-import', args: argv.slice(1) };
+    if (first === 'session-export' || first === 'session-import') {
+        return argv[1] === '--help' || argv[1] === '-h'
+            ? { kind: 'help', text: sessionBundleHelpText(cliCommand, first) }
+            : { kind: first, args: argv.slice(1) };
+    }
     if (first === 'eval')
         return { kind: 'eval', args: argv.slice(1) };
     if (first === 'update')
-        return parseRuntimeHostInstalledUpdateCommand(argv.slice(1));
+        return parseRuntimeHostInstalledUpdateCommand(argv.slice(1), cliCommand);
     if (first === 'runtime-host')
-        return parseRuntimeHostCommand(argv.slice(1));
+        return parseRuntimeHostCommand(argv.slice(1), cliCommand);
     return {
         kind: 'error',
         message: `Unexpected argument: ${first ?? ''}`,
@@ -97,48 +99,23 @@ function helpText(cliCommand) {
         'Launches the Maka terminal UI in the current working directory.',
         '',
         'Commands:',
-        `  ${cliCommand}              Start the TUI`,
-        `  ${cliCommand} --acp      Serve ACP v1 over stdio (initialize, session/new, session/list)`,
-        `  ${cliCommand} run ...      Run one non-interactive model turn`,
-        `  ${cliCommand} activate ... Run one Cloud Session activation and emit JSONL`,
-        `  ${cliCommand} session-export --workspace-root <dir> --session <id> --out <file.maka-session>`,
-        `  ${cliCommand} session-import --workspace-root <dir> --bundle <file.maka-session>`,
-        `  ${cliCommand} -p ...       Alias for ${cliCommand} run`,
-        `  ${cliCommand} eval ...     Run one declarative multi-arm experiment`,
-        `  ${cliCommand} update --target <latest|next|version>  Update this npm-global CLI and its local Runtime Host`,
-        `  ${cliCommand} runtime-host serve [options]  Run a Runtime Host service`,
-        `  ${cliCommand} runtime-host activate --framed --root-id <id>`,
-        `  ${cliCommand} runtime-host setup --principal <id> --preset <desktop-client|terminal-client> [options]`,
-        `  ${cliCommand} runtime-host service install [options]`,
-        `  ${cliCommand} runtime-host service configure (--project-root <label>=<path> ... | --no-project-roots) --expected-config-fingerprint <sha256:...> --expected-service-id <id> --expected-root-path <path> --expected-root-id <id> [--allow-interrupt-active-tasks]`,
-        `  ${cliCommand} runtime-host service status|start|stop|restart|logs [--json]`,
-        `  ${cliCommand} runtime-host service uninstall --expected-service-id <id> --expected-root-path <path> --expected-root-id <id> [--allow-interrupt-active-tasks]`,
-        `  ${cliCommand} runtime-host service peer enable|disable|status|rotate|descriptor [options]`,
-        `  ${cliCommand} runtime-host service mesh status|create|invite|join|remove|leave|close|reconcile [options]`,
-        `  ${cliCommand} runtime-host service retire --expected-service-id <id> --expected-root-path <path> --expected-root-id <id> [--allow-interrupt-active-tasks]`,
-        `  ${cliCommand} runtime-host service check-update --target <latest|next|version> [--json]`,
-        `  ${cliCommand} runtime-host service update [--target <latest|next|version>] --expected-service-id <id> --expected-root-path <path> --expected-root-id <id> [--allow-interrupt-active-tasks]`,
-        `  ${cliCommand} runtime-host service update-policy [--target <manual|latest|next|version>] [--json]`,
-        `  ${cliCommand} runtime-host service reconcile-update [--json]`,
-        `  ${cliCommand} runtime-host access issue --principal <id> --grant <operation>`,
-        `  ${cliCommand} runtime-host access issue --principal <id> --preset <desktop-client|terminal-client>`,
-        `  ${cliCommand} runtime-host access connection-code [--name <name>] [--root <path>]`,
-        `  ${cliCommand} runtime-host access list`,
-        `  ${cliCommand} runtime-host access issue --kind capability-provider --principal <id>`,
-        `  ${cliCommand} runtime-host access revoke --credential <id>`,
-        `  ${cliCommand} runtime-host project list [--root <path>]`,
-        `  ${cliCommand} runtime-host project add <path> [--prefer] [--root <path>]`,
-        `  ${cliCommand} runtime-host plugin status|list|inspect|failures [--root <path>]`,
-        `  ${cliCommand} runtime-host plugin install|uninstall|reload <target> [--root <path>]`,
-        `  ${cliCommand} runtime-host plugin export <extension-id> <bundle-path> [--root <path>]`,
-        `  ${cliCommand} runtime-host plugin apply <operations.json> [--root <path>]`,
-        `  ${cliCommand} runtime-host plugin reconcile [--root <path>]`,
-        `  ${cliCommand} runtime-host profile list`,
-        `  ${cliCommand} runtime-host profile set --id <id> --name <name> --tls-url <wss-url> --expected-root <root-id> [--credential-env <name>]`,
-        `  ${cliCommand} runtime-host profile set --id <id> --name <name> --ssh-destination <user@host> --ssh-remote-port <port> --expected-root <root-id> [--ssh-port <port>] [--credential-env <name>]`,
-        `  ${cliCommand} runtime-host profile set --id <id> --name <name> --plaintext-url <ws-url> --acknowledge-plaintext --expected-root <root-id> [--credential-env <name>]`,
-        `  ${cliCommand} runtime-host profile remove --id <id>`,
-        `  ${cliCommand} runtime-host capability-provider serve --url <ws-url> --mcp-config <path> --expected-root <root-id>`,
+        ...[
+            ['', 'Start the TUI'],
+            ['--acp', 'Serve ACP v1 over stdio (initialize, session/new, session/list)'],
+            ['run ...', 'Run one non-interactive model turn'],
+            ['-p ...', `Alias for ${cliCommand} run`],
+            ['activate ...', 'Run one Cloud Session activation and emit JSONL'],
+            ['eval ...', 'Run one declarative multi-arm experiment'],
+            ['session-export ...', 'Write a Session bundle to a file'],
+            ['session-import ...', 'Read a Session bundle back into a workspace'],
+            ['update ...', 'Update this npm-global CLI and its local Runtime Host'],
+            ['runtime-host ...', 'Serve and manage a Runtime Host'],
+        ].map(([name, summary], _index, entries) => {
+            // A custom launcher ("npm run cli:dev --") is far wider than `maka`, so the
+            // column is measured, never assumed.
+            const width = Math.max(...entries.map(([other]) => `${cliCommand} ${other}`.trimEnd().length));
+            return `  ${`${cliCommand} ${name}`.trimEnd().padEnd(width + 2)}${summary}`;
+        }),
         '',
         'Options:',
         '  -h, --help        Show help',
@@ -147,70 +124,8 @@ function helpText(cliCommand) {
         '  --resume <id> --cwd <path>  Reopen a session after its directory moved',
         '  --host <profile-id>     Connect the TUI to a saved Runtime Host profile',
         '  --project <project-id>  Select an existing Project on a remote Host',
-        '  MAKA_RUNTIME_HOST_ACCESS_CREDENTIAL  Access credential used by runtime-host profile set',
-        '',
-        'Runtime Host serve options:',
-        '  --root <path>                 Select the canonical data root',
-        '  --project-root <label>=<path> Publish an absolute project directory root (repeatable)',
-        '  --no-project-roots            Disable remote project browsing and registration',
-        '  --websocket-port <port>       Enable an authenticated WebSocket listener',
-        '  --websocket-host <host>       Bind host (default: 127.0.0.1)',
-        '  --websocket-path <path>       Upgrade path (default: /runtime-host)',
-        '  --tls-certificate <path>      TLS certificate for WSS',
-        '  --tls-private-key <path>      TLS private key for WSS',
-        '  --allow-insecure-remote       Allow plaintext WebSocket access beyond loopback',
-        '  --allow-origin <origin>       Allow one browser Origin (repeatable)',
-        '  --peer-native-path <path>     Load the experimental direct-peer native module',
-        '  --peer-key <path>             Persist the direct-peer transport identity',
-        '  --peer-id <id>                Require an existing direct-peer transport identity',
-        '  --peer-listen <multiaddr>     Listen on a direct-peer address (repeatable)',
-        '  --peer-coordination-relay <multiaddr>  Use a DCUtR coordination relay (repeatable)',
-        '  --json                        Emit one machine-readable ready event',
-        '',
-        'Managed Runtime Host service install options (Linux or macOS):',
-        '  --root <path>                 Select the canonical data root',
-        '  --project-root <label>=<path> Publish an absolute directory root (repeatable)',
-        '  --no-project-roots            Disable remote project browsing and registration',
-        '  --websocket-port <port>       Persist a loopback port (chosen automatically by default)',
-        '  --websocket-path <path>       Persist the upgrade path (default: /runtime-host)',
-        '  --json                        Emit a machine-readable result',
-        '',
-        'Managed Runtime Host setup options (Linux or macOS):',
-        '  --principal <id>              Stable Client pairing identity',
-        '  --preset <name>               Pair a desktop-client or terminal-client',
-        '  --root <path>                 Select the canonical data root',
-        '  --project-root <label>=<path> Publish an absolute directory root (repeatable)',
-        '  --no-project-roots            Disable remote project browsing and registration',
-        '  --websocket-port <port>       Persist a loopback port (chosen automatically by default)',
-        '  --websocket-path <path>       Persist the upgrade path (default: /runtime-host)',
-        '  --json                        Emit framed machine-readable progress and result records',
-        '',
-        'Managed Runtime Host direct-peer options:',
-        '  --listen <multiaddr>          Persist a listener address (repeatable)',
-        '  --coordination-relay <addr>   Prefer a Circuit Relay v2 address (repeatable)',
-        '  --clear-coordination-relays   Remove every manually configured relay',
-        '  --automatic-relay-discovery   Enable best-effort public relay discovery',
-        '  --no-automatic-relay-discovery  Disable public discovery and retain manual relays',
-        '  --default-public-stun          Use the packaged best-effort public STUN policy',
-        '  --no-public-stun               Disable public STUN and keep host candidates only',
-        '  --webrtc-stun <stun-url>       Use a custom STUN endpoint (repeatable)',
-        '',
-        'Runtime Host access issue options:',
-        '  --root <path>                 Select the canonical data root',
-        '  --kind <kind>                 remote-owner or capability-provider',
-        '  --principal <id>              Name the authenticated Client principal',
-        '  --grant <operation>           Grant one exact operation (repeatable)',
-        '  --preset <name>               Grant the desktop-client or terminal-client operation set',
-        '  --publish-client-capabilities Allow Client Capability publication',
-        '  --allow-host-paths            Allow operations that submit Host paths',
-        '  --capability-owner-credential <id>  Bind a provider to one Client-bound owner credential',
         '',
-        'Runtime Host capability provider options:',
-        '  --url <ws-url>                Connect to an authenticated Runtime Host WebSocket',
-        '  --mcp-config <path>           Publish tools from an MCP configuration file',
-        '  --expected-root <root-id>     Pin the canonical Runtime Host root identity',
-        '  --credential-env <name>       Read the access credential from this environment variable',
-        '  --client-identity <path>      Persist the provider Client instance identity here',
+        `Run \`${cliCommand} <command> --help\` for a command's own options.`,
     ].join('\n');
 }
 export async function runMakaCli(argv = process.argv.slice(2), options = RELEASE_MAKA_CLI_LAUNCH_OPTIONS) {

package/dist/runtime-host-cli.js

@@ -21,7 +21,14 @@ import { isProductReleaseVersion, isSha512PackageIntegrity, } from '@maka/runtim
 import { createRuntimeHostLegacyPosixOperatorCommand, decodeRuntimeHostPosixOperatorCommand, decodeRuntimeHostWebRtcStunPolicy, } from '@maka/runtime-host/operator';
 import { canonicalProjectDirectoryRootSpec, isCanonicalRuntimeHostWebSocketPath, PROJECT_DIRECTORY_MAX_ROOTS, projectDirectoryPosixRootSpecValid, projectDirectoryRootSpecValid, } from '@maka/runtime-host/protocol';
 import { hasEphemeralRuntimeHostPeerPort } from './runtime-host-peer-artifact.js';
-export function parseRuntimeHostCommand(argv) {
+import { installedUpdateHelpText, isRuntimeHostHelpTopic, runtimeHostCommandHelpText, runtimeHostHelpText, } from './runtime-host-help.js';
+export function parseRuntimeHostCommand(argv, cliCommand = 'maka') {
+    if (!argv[0] || argv[0] === '--help' || argv[0] === '-h') {
+        return { kind: 'help', text: runtimeHostHelpText(cliCommand) };
+    }
+    if ((argv[1] === '--help' || argv[1] === '-h') && isRuntimeHostHelpTopic(argv[0])) {
+        return { kind: 'help', text: runtimeHostCommandHelpText(cliCommand, argv[0]) };
+    }
     if (argv[0] === 'activate' || argv[0] === 'connect') {
         return parseManagedRootFramedCommand(argv[0], argv.slice(1));
     }
@@ -48,9 +55,7 @@ export function parseRuntimeHostCommand(argv) {
     }
     if (argv[0] === 'profile')
         return parseProfileCommand(argv.slice(1));
-    return error(argv[0]
-        ? `Unexpected runtime-host command: ${argv[0]}`
-        : 'runtime-host requires the activate, connect, serve, setup, service, access, project, plugin, profile, or capability-provider command');
+    return error(`Unexpected runtime-host command: ${argv[0]}`);
 }
 function parseManagedRootFramedCommand(action, argv) {
     let rootId;
@@ -93,7 +98,10 @@ function parseManagedRootFramedCommand(action, argv) {
         ...(repairRootAfterRemount ? { repairRootAfterRemount: true } : {}),
     };
 }
-export function parseRuntimeHostInstalledUpdateCommand(argv) {
+export function parseRuntimeHostInstalledUpdateCommand(argv, cliCommand = 'maka') {
+    if (argv[0] === '--help' || argv[0] === '-h') {
+        return { kind: 'help', text: installedUpdateHelpText(cliCommand) };
+    }
     let target;
     let allowInterruptActiveTasks = false;
     for (let index = 0; index < argv.length; index += 1) {

package/dist/runtime-host-help.js

@@ -0,0 +1,244 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+const SUBCOMMANDS = {
+    activate: {
+        summary: 'Run one framed activation against a managed root',
+        lines: (cliCommand) => [
+            `  ${cliCommand} runtime-host activate --framed --root-id <id>`,
+            `  ${cliCommand} runtime-host connect --framed --root-id <id>`,
+            '',
+            'Managed root options:',
+            '  --framed                      Frame stdio for a supervising parent',
+            '  --root-id <id>                Pin the canonical Runtime Host root identity',
+            '  --repair-root-after-remount   Repair the root after its volume was remounted',
+        ],
+    },
+    serve: {
+        summary: 'Run a Runtime Host service',
+        lines: (cliCommand) => [
+            `  ${cliCommand} runtime-host serve [options]  Run a Runtime Host service`,
+            '',
+            'Options:',
+            '  --root <path>                 Select the canonical data root',
+            '  --project-root <label>=<path> Publish an absolute project directory root (repeatable)',
+            '  --no-project-roots            Disable remote project browsing and registration',
+            '  --websocket-port <port>       Enable an authenticated WebSocket listener',
+            '  --websocket-host <host>       Bind host (default: 127.0.0.1)',
+            '  --websocket-path <path>       Upgrade path (default: /runtime-host)',
+            '  --tls-certificate <path>      TLS certificate for WSS',
+            '  --tls-private-key <path>      TLS private key for WSS',
+            '  --allow-insecure-remote       Allow plaintext WebSocket access beyond loopback',
+            '  --allow-origin <origin>       Allow one browser Origin (repeatable)',
+            '  --peer-native-path <path>     Load the experimental direct-peer native module',
+            '  --peer-key <path>             Persist the direct-peer transport identity',
+            '  --peer-id <id>                Require an existing direct-peer transport identity',
+            '  --peer-listen <multiaddr>     Listen on a direct-peer address (repeatable)',
+            '  --peer-coordination-relay <multiaddr>  Use a DCUtR coordination relay (repeatable)',
+            '  --json                        Emit one machine-readable ready event',
+            '',
+        ],
+    },
+    setup: {
+        summary: 'Provision a managed Runtime Host',
+        lines: (cliCommand) => [
+            `  ${cliCommand} runtime-host setup --principal <id> --preset <desktop-client|terminal-client> [options]`,
+            '',
+            'Options (Linux or macOS):',
+            '  --principal <id>              Stable Client pairing identity',
+            '  --preset <name>               Pair a desktop-client or terminal-client',
+            '  --root <path>                 Select the canonical data root',
+            '  --project-root <label>=<path> Publish an absolute directory root (repeatable)',
+            '  --no-project-roots            Disable remote project browsing and registration',
+            '  --websocket-port <port>       Persist a loopback port (chosen automatically by default)',
+            '  --websocket-path <path>       Persist the upgrade path (default: /runtime-host)',
+            '  --json                        Emit framed machine-readable progress and result records',
+            '',
+        ],
+    },
+    service: {
+        summary: 'Install and operate the managed service',
+        lines: (cliCommand) => [
+            `  ${cliCommand} runtime-host service install [options]`,
+            `  ${cliCommand} runtime-host service configure (--project-root <label>=<path> ... | --no-project-roots) --expected-config-fingerprint <sha256:...> --expected-service-id <id> --expected-root-path <path> --expected-root-id <id> [--allow-interrupt-active-tasks]`,
+            `  ${cliCommand} runtime-host service status|start|stop|restart|logs [--json]`,
+            `  ${cliCommand} runtime-host service uninstall --expected-service-id <id> --expected-root-path <path> --expected-root-id <id> [--allow-interrupt-active-tasks]`,
+            `  ${cliCommand} runtime-host service peer enable|disable|status|rotate|descriptor [options]`,
+            `  ${cliCommand} runtime-host service mesh status|create|invite|join|remove|leave|close|reconcile [options]`,
+            `  ${cliCommand} runtime-host service retire --expected-service-id <id> --expected-root-path <path> --expected-root-id <id> [--allow-interrupt-active-tasks]`,
+            `  ${cliCommand} runtime-host service check-update --target <latest|next|version> [--json]`,
+            `  ${cliCommand} runtime-host service update [--target <latest|next|version>] --expected-service-id <id> --expected-root-path <path> --expected-root-id <id> [--allow-interrupt-active-tasks]`,
+            `  ${cliCommand} runtime-host service update-policy [--target <manual|latest|next|version>] [--json]`,
+            `  ${cliCommand} runtime-host service reconcile-update [--json]`,
+            '',
+            'Install options (Linux or macOS):',
+            '  --root <path>                 Select the canonical data root',
+            '  --project-root <label>=<path> Publish an absolute directory root (repeatable)',
+            '  --no-project-roots            Disable remote project browsing and registration',
+            '  --websocket-port <port>       Persist a loopback port (chosen automatically by default)',
+            '  --websocket-path <path>       Persist the upgrade path (default: /runtime-host)',
+            '  --json                        Emit a machine-readable result',
+            '',
+            '',
+            'Direct-peer options:',
+            '  --listen <multiaddr>          Persist a listener address (repeatable)',
+            '  --coordination-relay <addr>   Prefer a Circuit Relay v2 address (repeatable)',
+            '  --clear-coordination-relays   Remove every manually configured relay',
+            '  --automatic-relay-discovery   Enable best-effort public relay discovery',
+            '  --no-automatic-relay-discovery  Disable public discovery and retain manual relays',
+            '  --default-public-stun          Use the packaged best-effort public STUN policy',
+            '  --no-public-stun               Disable public STUN and keep host candidates only',
+            '  --webrtc-stun <stun-url>       Use a custom STUN endpoint (repeatable)',
+            '',
+        ],
+    },
+    access: {
+        summary: 'Issue and revoke access credentials',
+        lines: (cliCommand) => [
+            `  ${cliCommand} runtime-host access issue --principal <id> --grant <operation>`,
+            `  ${cliCommand} runtime-host access issue --principal <id> --preset <desktop-client|terminal-client>`,
+            `  ${cliCommand} runtime-host access connection-code [--name <name>] [--root <path>]`,
+            `  ${cliCommand} runtime-host access list`,
+            `  ${cliCommand} runtime-host access issue --kind capability-provider --principal <id>`,
+            `  ${cliCommand} runtime-host access revoke --credential <id>`,
+            '',
+            'Issue options:',
+            '  --root <path>                 Select the canonical data root',
+            '  --kind <kind>                 remote-owner or capability-provider',
+            '  --principal <id>              Name the authenticated Client principal',
+            '  --grant <operation>           Grant one exact operation (repeatable)',
+            '  --preset <name>               Grant the desktop-client or terminal-client operation set',
+            '  --publish-client-capabilities Allow Client Capability publication',
+            '  --allow-host-paths            Allow operations that submit Host paths',
+            '  --capability-owner-credential <id>  Bind a provider to one Client-bound owner credential',
+            '',
+        ],
+    },
+    project: {
+        summary: 'Register project directory roots',
+        lines: (cliCommand) => [
+            `  ${cliCommand} runtime-host project list [--root <path>]`,
+            `  ${cliCommand} runtime-host project add <path> [--prefer] [--root <path>]`,
+        ],
+    },
+    plugin: {
+        summary: 'Install and inspect plugins',
+        lines: (cliCommand) => [
+            `  ${cliCommand} runtime-host plugin status|list|inspect|failures [--root <path>]`,
+            `  ${cliCommand} runtime-host plugin install|uninstall|reload <target> [--root <path>]`,
+            `  ${cliCommand} runtime-host plugin export <extension-id> <bundle-path> [--root <path>]`,
+            `  ${cliCommand} runtime-host plugin apply <operations.json> [--root <path>]`,
+            `  ${cliCommand} runtime-host plugin reconcile [--root <path>]`,
+        ],
+    },
+    profile: {
+        summary: 'Save and select remote Host profiles',
+        lines: (cliCommand) => [
+            `  ${cliCommand} runtime-host profile list`,
+            `  ${cliCommand} runtime-host profile set --id <id> --name <name> --tls-url <wss-url> --expected-root <root-id> [--credential-env <name>]`,
+            `  ${cliCommand} runtime-host profile set --id <id> --name <name> --ssh-destination <user@host> --ssh-remote-port <port> --expected-root <root-id> [--ssh-port <port>] [--credential-env <name>]`,
+            `  ${cliCommand} runtime-host profile set --id <id> --name <name> --plaintext-url <ws-url> --acknowledge-plaintext --expected-root <root-id> [--credential-env <name>]`,
+            `  ${cliCommand} runtime-host profile remove --id <id>`,
+            '',
+            'Environment:',
+            '  MAKA_RUNTIME_HOST_ACCESS_CREDENTIAL  Access credential used when --credential-env is omitted',
+        ],
+    },
+    'capability-provider': {
+        summary: 'Publish MCP tools to a Host',
+        lines: (cliCommand) => [
+            `  ${cliCommand} runtime-host capability-provider serve --url <ws-url> --mcp-config <path> --expected-root <root-id>`,
+            '',
+            'Options:',
+            '  --url <ws-url>                Connect to an authenticated Runtime Host WebSocket',
+            '  --mcp-config <path>           Publish tools from an MCP configuration file',
+            '  --expected-root <root-id>     Pin the canonical Runtime Host root identity',
+            '  --credential-env <name>       Read the access credential from this environment variable',
+            '  --client-identity <path>      Persist the provider Client instance identity here',
+        ],
+    },
+};
+export function isRuntimeHostHelpTopic(value) {
+    return Object.hasOwn(SUBCOMMANDS, value);
+}
+/** Overview of the Runtime Host commands, one line each. */
+export function runtimeHostHelpText(cliCommand) {
+    return [
+        `Usage: ${cliCommand} runtime-host <command> [options]`,
+        '',
+        'Serves and manages a Runtime Host: the background service that runs Sessions.',
+        '',
+        'Commands:',
+        ...Object.entries(SUBCOMMANDS).map(([name, topic]) => `  ${name.padEnd(20)}${topic.summary}`),
+        '',
+        `Run \`${cliCommand} runtime-host <command> --help\` for its own options.`,
+    ].join('\n');
+}
+/** A lone command line that only repeats the Usage grammar adds nothing to its screen. */
+function withoutRedundantUsage(lines, usage) {
+    const rest = lines[0]?.trim().startsWith(usage) ? lines.slice(1) : lines;
+    const body = rest[0]?.trim() === '' ? rest.slice(1) : rest;
+    // A screen that still opens on command lines needs the heading its option
+    // sections already carry.
+    return body[0]?.startsWith('  ') && !body[0].trim().startsWith('-')
+        ? ['Commands:', ...body]
+        : body;
+}
+/** Every command line and option belonging to one Runtime Host command. */
+export function runtimeHostCommandHelpText(cliCommand, topic) {
+    return [
+        `Usage: ${cliCommand} runtime-host ${topic} [options]`,
+        '',
+        ...withoutRedundantUsage(SUBCOMMANDS[topic].lines(cliCommand), `${cliCommand} runtime-host ${topic} [options]`),
+    ].join('\n');
+}
+/** `maka update` manages the npm-global CLI, so it sits outside the Host topics. */
+export function installedUpdateHelpText(cliCommand) {
+    return [
+        `Usage: ${cliCommand} update [options]`,
+        '',
+        'Updates this npm-global CLI and the Runtime Host it manages locally.',
+        '',
+        'Options:',
+        '  --target <latest|next|version>  Select the release to install',
+        '  --allow-interrupt-active-tasks  Update even while the Host has running work',
+    ].join('\n');
+}
+/** Session bundles move a Session between workspaces; neither side takes flags beyond these. */
+export function sessionBundleHelpText(cliCommand, command) {
+    return command === 'session-export'
+        ? [
+            `Usage: ${cliCommand} session-export --workspace-root <dir> --session <id> --out <file.maka-session>`,
+            '',
+            'Writes one Session and its transcript to a portable bundle.',
+            '',
+            'Options:',
+            '  --workspace-root <dir>   Workspace holding the Session',
+            '  --session <id>           Session to export',
+            '  --out <file>             Bundle path to write',
+        ].join('\n')
+        : [
+            `Usage: ${cliCommand} session-import --workspace-root <dir> --bundle <file.maka-session>`,
+            '',
+            'Reads a Session bundle back into a workspace.',
+            '',
+            'Options:',
+            '  --workspace-root <dir>   Workspace to import into',
+            '  --bundle <file>          Bundle path to read',
+        ].join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maka-agent",
-  "version": "0.2.0-dev.29.20260912",
+  "version": "0.2.0-dev.30.20260912",
   "description": "Apache Maka (Incubating) developer snapshot; not an Apache release.",
   "license": "Apache-2.0",
   "type": "module",