@pellux/goodvibes-agent 0.1.0

package/src/audio/text-chunker.ts

@@ -0,0 +1,110 @@
+export interface TtsTextChunkerOptions {
+  readonly minBoundaryChars?: number;
+  readonly maxChunkChars?: number;
+  readonly maxLatencyMs?: number;
+  readonly now?: () => number;
+}
+
+export class TtsTextChunker {
+  private buffer = '';
+  private firstBufferedAt: number | null = null;
+  private readonly minBoundaryChars: number;
+  private readonly maxChunkChars: number;
+  private readonly maxLatencyMs: number;
+  private readonly now: () => number;
+
+  constructor(options: TtsTextChunkerOptions = {}) {
+    this.minBoundaryChars = options.minBoundaryChars ?? 24;
+    this.maxChunkChars = options.maxChunkChars ?? 320;
+    this.maxLatencyMs = options.maxLatencyMs ?? 1_000;
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  push(delta: string): string[] {
+    if (!delta) return [];
+    if (this.firstBufferedAt === null) this.firstBufferedAt = this.now();
+    this.buffer += delta;
+    return this.drainReady(false);
+  }
+
+  flushDue(): string[] {
+    if (!this.buffer.trim() || this.firstBufferedAt === null) return [];
+    if (this.now() - this.firstBufferedAt < this.maxLatencyMs) return [];
+    return this.drainReady(true);
+  }
+
+  flushAll(): string[] {
+    if (!this.buffer.trim()) {
+      this.buffer = '';
+      this.firstBufferedAt = null;
+      return [];
+    }
+    return [this.takeChunk(this.buffer.length)].filter(Boolean);
+  }
+
+  reset(): void {
+    this.buffer = '';
+    this.firstBufferedAt = null;
+  }
+
+  private drainReady(forceLatencyFlush: boolean): string[] {
+    const chunks: string[] = [];
+    while (this.buffer.trim()) {
+      const boundary = this.findBoundary(forceLatencyFlush);
+      if (boundary <= 0) break;
+      const chunk = this.takeChunk(boundary);
+      if (chunk) chunks.push(chunk);
+      forceLatencyFlush = false;
+    }
+    return chunks;
+  }
+
+  private findBoundary(forceLatencyFlush: boolean): number {
+    const latestSentence = this.findLatestSentenceBoundary();
+    if (latestSentence >= this.minBoundaryChars) return latestSentence;
+
+    if (this.buffer.length >= this.maxChunkChars) {
+      return this.findWordBoundaryBefore(this.maxChunkChars) || this.maxChunkChars;
+    }
+
+    if (forceLatencyFlush) {
+      return this.buffer.length;
+    }
+
+    return -1;
+  }
+
+  private findLatestSentenceBoundary(): number {
+    let best = -1;
+    for (let i = 0; i < this.buffer.length; i++) {
+      const char = this.buffer[i];
+      if (char !== '.' && char !== '!' && char !== '?' && char !== ';' && char !== ':' && char !== '\n') {
+        continue;
+      }
+      const next = this.buffer[i + 1];
+      if (i === this.buffer.length - 1 || next === undefined || /\s/.test(next)) {
+        best = i + 1;
+      }
+    }
+    return best;
+  }
+
+  private findWordBoundaryBefore(index: number): number {
+    const max = Math.min(index, this.buffer.length);
+    for (let i = max; i > 0; i--) {
+      if (/\s/.test(this.buffer[i - 1] ?? '')) return i;
+    }
+    return -1;
+  }
+
+  private takeChunk(end: number): string {
+    const raw = this.buffer.slice(0, end);
+    this.buffer = this.buffer.slice(end);
+    this.firstBufferedAt = this.buffer.trim() ? this.now() : null;
+    return normalizeSpeechText(raw);
+  }
+}
+
+export function normalizeSpeechText(text: string): string {
+  return text.replace(/\s+/g, ' ').trim();
+}

package/src/cli/bundle-command.ts

@@ -0,0 +1,227 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { RuntimeEventBus } from '@/runtime/index.ts';
+import { createShellPathService } from '@/runtime/index.ts';
+import { listProviderRuntimeSnapshots } from '@pellux/goodvibes-sdk/platform/providers';
+import { createRuntimeServices } from '../runtime/services.ts';
+import { createRuntimeStore } from '../runtime/store/index.ts';
+import { getOnboardingCheckMarkerPath } from '../runtime/onboarding/index.ts';
+import { CONFIG_SCHEMA } from '../config/index.ts';
+import { SecretsManager } from '../config/secrets.ts';
+import type { ConfigKey } from '../config/index.ts';
+import type { CliCommandRuntime } from './management.ts';
+import type { CliCommandOutput } from './types.ts';
+import { getPackageVersion } from './help.ts';
+import { classifyProviderSetup } from './provider-classification.ts';
+import { buildCliServicePosture } from './service-posture.ts';
+import { REDACTED_VALUE, collectSensitiveConfigValues, isRedactedValue, redactConfig, redactSerializedSecrets } from './redaction.ts';
+import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
+
+interface BundleInspectSummary {
+  readonly type: string;
+  readonly version: string;
+  readonly path: string;
+  readonly capturedAt: number | null;
+  readonly configKeys: number;
+  readonly redactedConfigPaths: readonly string[];
+  readonly hasDiagnostics: boolean;
+}
+
+function formatJsonOrText(runtime: CliCommandRuntime, value: unknown, text: string): string {
+  return runtime.cli.flags.outputFormat === 'json' ? JSON.stringify(value, null, 2) : text;
+}
+
+function getNestedValue(source: unknown, key: string): unknown {
+  let cursor = source;
+  for (const part of key.split('.')) {
+    if (cursor == null || typeof cursor !== 'object') return undefined;
+    cursor = (cursor as Record<string, unknown>)[part];
+  }
+  return cursor;
+}
+
+function readJsonFile(path: string): { readonly ok: true; readonly value: Record<string, unknown> } | { readonly ok: false; readonly error: string } {
+  try {
+    return { ok: true, value: JSON.parse(readFileSync(path, 'utf-8')) as Record<string, unknown> };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function inspectBundle(path: string, parsed: Record<string, unknown>): BundleInspectSummary {
+  return {
+    type: String(parsed['type'] ?? 'unknown'),
+    version: String(parsed['version'] ?? 'unknown'),
+    path,
+    capturedAt: typeof parsed['capturedAt'] === 'number' ? parsed['capturedAt'] : null,
+    configKeys: parsed['config'] && typeof parsed['config'] === 'object'
+      ? CONFIG_SCHEMA.filter((setting) => getNestedValue(parsed['config'], setting.key) !== undefined).length
+      : 0,
+    redactedConfigPaths: Array.isArray((parsed['redaction'] as { redactedConfigPaths?: unknown } | undefined)?.redactedConfigPaths)
+      ? (parsed['redaction'] as { redactedConfigPaths: string[] }).redactedConfigPaths
+      : [],
+    hasDiagnostics: Boolean(parsed['diagnostics'] && typeof parsed['diagnostics'] === 'object'),
+  };
+}
+
+function readAuthPosture(runtime: CliCommandRuntime) {
+  const shellPaths = createShellPathService({
+    workingDirectory: runtime.workingDirectory,
+    homeDirectory: runtime.homeDirectory,
+  });
+  const userStorePath = shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'auth-users.json');
+  const bootstrapCredentialPath = shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'auth-bootstrap.txt');
+  const operatorTokenPath = join(runtime.homeDirectory, '.goodvibes', 'daemon', 'operator-tokens.json');
+  return {
+    userStorePath,
+    userStorePresent: existsSync(userStorePath),
+    bootstrapCredentialPath,
+    bootstrapCredentialPresent: existsSync(bootstrapCredentialPath),
+    operatorTokenPath,
+    operatorTokenPresent: existsSync(operatorTokenPath),
+  };
+}
+
+async function buildProviderReadiness(runtime: CliCommandRuntime) {
+  const runtimeBus = new RuntimeEventBus();
+  const runtimeStore = createRuntimeStore();
+  const services = createRuntimeServices({
+    configManager: runtime.configManager,
+    runtimeBus,
+    runtimeStore,
+    workingDir: runtime.workingDirectory,
+    homeDirectory: runtime.homeDirectory,
+  });
+  services.providerRegistry.initModelLimits();
+  services.benchmarkStore.initBenchmarks();
+  services.providerRegistry.initCatalog();
+  try {
+    await services.providerRegistry.ready();
+    const snapshots = await listProviderRuntimeSnapshots(services.providerRegistry);
+    return snapshots.map((snapshot) => ({
+      provider: snapshot.providerId,
+      active: snapshot.active,
+      configured: snapshot.runtime.auth?.configured ?? true,
+      configuredVia: snapshot.runtime.auth?.mode ?? 'unknown',
+      models: snapshot.modelCount,
+      setup: classifyProviderSetup({
+        providerId: snapshot.providerId,
+        authMode: snapshot.runtime.auth?.mode,
+        configured: snapshot.runtime.auth?.configured ?? true,
+        modelCount: snapshot.modelCount,
+      }),
+    }));
+  } finally {
+    services.providerRegistry.stopWatching();
+  }
+}
+
+export async function handleBundleCommand(runtime: CliCommandRuntime): Promise<CliCommandOutput> {
+  const [sub = 'inspect', ...rest] = runtime.cli.commandArgs;
+  const shellPaths = createShellPathService({
+    workingDirectory: runtime.workingDirectory,
+    homeDirectory: runtime.homeDirectory,
+  });
+
+  if (sub === 'inspect') {
+    const path = rest[0];
+    if (!path) return { output: 'Usage: goodvibes bundle inspect <path>', exitCode: 2 };
+    const sourcePath = shellPaths.resolveWorkspacePath(path);
+    const parsed = readJsonFile(sourcePath);
+    if (!parsed.ok) return { output: `Invalid bundle JSON: ${parsed.error}`, exitCode: 1 };
+    const summary = inspectBundle(sourcePath, parsed.value);
+    return {
+      output: formatJsonOrText(runtime, summary, [
+        'GoodVibes bundle',
+        `  type: ${summary.type}`,
+        `  version: ${summary.version}`,
+        `  path: ${summary.path}`,
+        `  capturedAt: ${summary.capturedAt === null ? 'n/a' : new Date(summary.capturedAt).toISOString()}`,
+        `  configKeys: ${summary.configKeys}`,
+        `  redactedConfigKeys: ${summary.redactedConfigPaths.length}`,
+        `  diagnostics: ${summary.hasDiagnostics ? 'present' : 'missing'}`,
+      ].join('\n')),
+      exitCode: 0,
+    };
+  }
+
+  if (sub === 'export') {
+    const outputPath = rest[0] ?? 'goodvibes-agent-bundle.json';
+    const secrets = new SecretsManager({
+      projectRoot: runtime.workingDirectory,
+      globalHome: runtime.homeDirectory,
+      configManager: runtime.configManager,
+    });
+    const rawConfig = runtime.configManager.getRaw();
+    const sensitiveValues = collectSensitiveConfigValues(rawConfig);
+    const redactedConfig = redactConfig(rawConfig);
+    const service = await buildCliServicePosture(runtime, { logTailBytes: 8192 });
+    const bundle = {
+      version: 2,
+      type: 'goodvibes-agent.support',
+      capturedAt: Date.now(),
+      package: {
+        name: '@pellux/goodvibes-agent',
+        version: getPackageVersion(),
+      },
+      roots: {
+        workingDirectory: runtime.workingDirectory,
+        homeDirectory: runtime.homeDirectory,
+      },
+      config: redactedConfig.value,
+      redaction: {
+        sentinel: REDACTED_VALUE,
+        redactedConfigPaths: redactedConfig.redactedPaths,
+      },
+      diagnostics: {
+        service,
+        auth: readAuthPosture(runtime),
+        providers: await buildProviderReadiness(runtime),
+      },
+      secrets: await secrets.inspect(),
+      onboarding: {
+        userMarker: existsSync(getOnboardingCheckMarkerPath(shellPaths, 'user')),
+        projectMarker: existsSync(getOnboardingCheckMarkerPath(shellPaths, 'project')),
+      },
+    };
+    const targetPath = shellPaths.resolveWorkspacePath(outputPath);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, redactSerializedSecrets(JSON.stringify(bundle, null, 2), sensitiveValues) + '\n', 'utf-8');
+    return {
+      output: formatJsonOrText(runtime, {
+        path: targetPath,
+        redactedConfigPaths: redactedConfig.redactedPaths,
+        serviceIssues: service.issues,
+      }, `Bundle exported: ${targetPath}\n  redactedConfigKeys: ${redactedConfig.redactedPaths.length}\n  serviceIssues: ${service.issues.length}`),
+      exitCode: 0,
+    };
+  }
+
+  if (sub === 'import') {
+    const path = rest[0];
+    if (!path) return { output: 'Usage: goodvibes bundle import <path>', exitCode: 2 };
+    const sourcePath = shellPaths.resolveWorkspacePath(path);
+    const parsed = readJsonFile(sourcePath);
+    if (!parsed.ok) return { output: `Invalid bundle JSON: ${parsed.error}`, exitCode: 1 };
+    const config = parsed.value['config'];
+    if (!config || typeof config !== 'object') return { output: 'Bundle has no config object to import.', exitCode: 1 };
+    let count = 0;
+    let skippedRedacted = 0;
+    for (const setting of CONFIG_SCHEMA) {
+      const value = getNestedValue(config, setting.key);
+      if (value === undefined) continue;
+      if (isRedactedValue(value)) {
+        skippedRedacted++;
+        continue;
+      }
+      runtime.configManager.setDynamic(setting.key as ConfigKey, value as never);
+      count++;
+    }
+    return {
+      output: `Bundle imported: ${count} config value${count === 1 ? '' : 's'} applied.${skippedRedacted ? ` ${skippedRedacted} redacted value${skippedRedacted === 1 ? '' : 's'} skipped.` : ''}`,
+      exitCode: 0,
+    };
+  }
+
+  return { output: 'Usage: goodvibes bundle export [path]|inspect <path>|import <path>', exitCode: 2 };
+}

package/src/cli/completion.ts

@@ -0,0 +1,90 @@
+const COMMANDS = [
+  'tui',
+  'run',
+  'exec',
+  'serve',
+  'web',
+  'service',
+  'onboarding',
+  'setup',
+  'doctor',
+  'status',
+  'models',
+  'providers',
+  'auth',
+  'subscription',
+  'secrets',
+  'sessions',
+  'tasks',
+  'pair',
+  'qrcode',
+  'surfaces',
+  'listener',
+  'control-plane',
+  'bundle',
+  'remote',
+  'bridge',
+  'completion',
+  'version',
+  'help',
+] as const;
+
+const OPTIONS = [
+  '--help',
+  '--version',
+  '--model',
+  '--provider',
+  '--cd',
+  '--working-dir',
+  '--daemon-home',
+  '--config',
+  '--enable',
+  '--disable',
+  '--prompt',
+  '--print',
+  '--output',
+  '--output-format',
+  '--json',
+  '--no-alt-screen',
+  '--port',
+  '--hostname',
+  '--open',
+  '--resume',
+  '--session',
+  '--continue',
+  '--fork',
+  '--password',
+  '--password-stdin',
+  '--role',
+  '--manual',
+] as const;
+
+export function renderCompletion(shell: string | undefined, binary = 'goodvibes'): string {
+  const normalized = (shell ?? 'bash').toLowerCase();
+  const words = [...COMMANDS, ...OPTIONS].join(' ');
+
+  if (normalized === 'zsh') {
+    return [
+      `#compdef ${binary}`,
+      `_${binary}() {`,
+      `  compadd -- ${words}`,
+      '}',
+      `_${binary} "$@"`,
+    ].join('\n');
+  }
+
+  if (normalized === 'fish') {
+    return [...COMMANDS, ...OPTIONS]
+      .map((word) => `complete -c ${binary} -a ${JSON.stringify(word)}`)
+      .join('\n');
+  }
+
+  return [
+    `_${binary}() {`,
+    '  local cur',
+    '  cur="${COMP_WORDS[COMP_CWORD]}"',
+    `  COMPREPLY=( $(compgen -W "${words}" -- "$cur") )`,
+    '}',
+    `complete -F _${binary} ${binary}`,
+  ].join('\n');
+}

package/src/cli/config-overrides.ts

@@ -0,0 +1,159 @@
+import type { ConfigKey, ConfigManager, ConfigSetting, GoodVibesConfig, PersistedFlagState } from '../config/index.ts';
+import { CONFIG_SCHEMA, ConfigError } from '../config/index.ts';
+import type { GoodVibesCliCommand, GoodVibesCliFlags } from './types.ts';
+import { RUNTIME_ENDPOINT_CONFIG_KEYS, hostModeForHostname } from './endpoints.ts';
+import type { RuntimeEndpointId } from './endpoints.ts';
+
+const CONFIG_SCHEMA_BY_KEY = new Map<string, ConfigSetting>(
+  CONFIG_SCHEMA.map((setting) => [setting.key, setting]),
+);
+
+function parseConfigOverrideValue(value: string): unknown {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return '';
+  try {
+    return JSON.parse(trimmed) as unknown;
+  } catch {
+    if (trimmed === 'true') return true;
+    if (trimmed === 'false') return false;
+    if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) return Number(trimmed);
+    return value;
+  }
+}
+
+function getRuntimeConfig(configManager: ConfigManager): GoodVibesConfig {
+  const mutable = configManager as unknown as { config?: GoodVibesConfig };
+  if (!mutable.config || typeof mutable.config !== 'object') {
+    throw new ConfigError('ConfigManager runtime config is not available for CLI overrides.');
+  }
+  return mutable.config;
+}
+
+function validateConfigValue(setting: ConfigSetting, value: unknown): void {
+  if (setting.type === 'boolean' && typeof value !== 'boolean') {
+    throw new ConfigError(`Invalid value for ${setting.key}: expected boolean.`);
+  }
+  if (setting.type === 'number' && (typeof value !== 'number' || !Number.isFinite(value))) {
+    throw new ConfigError(`Invalid value for ${setting.key}: expected number.`);
+  }
+  if (setting.type === 'string' && typeof value !== 'string') {
+    throw new ConfigError(`Invalid value for ${setting.key}: expected string.`);
+  }
+  if (setting.type === 'enum' && setting.enumValues && !setting.enumValues.includes(String(value))) {
+    throw new ConfigError(`Invalid value for ${setting.key}: "${String(value)}". Allowed: ${setting.enumValues.join(', ')}`);
+  }
+  if (setting.validate && !setting.validate(value)) {
+    throw new ConfigError(`Invalid value for ${setting.key}: ${String(value)}`);
+  }
+}
+
+function setNestedConfigValue(config: GoodVibesConfig, key: ConfigKey, value: unknown): void {
+  const parts = key.split('.');
+  let cursor: unknown = config;
+  for (const part of parts.slice(0, -1)) {
+    if (cursor == null || typeof cursor !== 'object' || !(part in cursor)) {
+      throw new ConfigError(`Invalid config path: section '${part}' does not exist`);
+    }
+    cursor = (cursor as Record<string, unknown>)[part];
+  }
+  if (cursor == null || typeof cursor !== 'object') {
+    throw new ConfigError(`Invalid config path: section '${parts.slice(0, -1).join('.')}' does not exist`);
+  }
+  (cursor as Record<string, unknown>)[parts[parts.length - 1]!] = value;
+}
+
+export function applyRuntimeConfigValue(configManager: ConfigManager, key: ConfigKey, value: unknown): void {
+  const setting = CONFIG_SCHEMA_BY_KEY.get(key);
+  if (!setting) {
+    throw new ConfigError(`Unknown config key: ${key}`);
+  }
+  validateConfigValue(setting, value);
+  setNestedConfigValue(getRuntimeConfig(configManager), key, value);
+}
+
+export function applyRuntimeConfigOverrides(
+  configManager: ConfigManager,
+  overrides: readonly string[],
+): readonly string[] {
+  const errors: string[] = [];
+  for (const override of overrides) {
+    const index = override.indexOf('=');
+    if (index <= 0) {
+      errors.push(`Invalid --config override "${override}". Expected key=value.`);
+      continue;
+    }
+    const key = override.slice(0, index) as ConfigKey;
+    const rawValue = override.slice(index + 1);
+    try {
+      applyRuntimeConfigValue(configManager, key, parseConfigOverrideValue(rawValue));
+    } catch (error) {
+      errors.push(error instanceof Error ? `Invalid --config ${override}: ${error.message}` : `Invalid --config ${override}`);
+    }
+  }
+  return errors;
+}
+
+export function applyRuntimeFeatureFlagOverrides(
+  configManager: ConfigManager,
+  options: {
+    readonly enableFeatures: readonly string[];
+    readonly disableFeatures: readonly string[];
+  },
+): void {
+  if (options.enableFeatures.length === 0 && options.disableFeatures.length === 0) return;
+  const config = getRuntimeConfig(configManager);
+  const flags = { ...config.featureFlags };
+  for (const feature of options.enableFeatures) {
+    flags[feature] = 'enabled' satisfies PersistedFlagState;
+  }
+  for (const feature of options.disableFeatures) {
+    flags[feature] = 'disabled' satisfies PersistedFlagState;
+  }
+  config.featureFlags = flags;
+}
+
+export function applyRuntimeEndpointFlagOverrides(
+  configManager: ConfigManager,
+  endpoint: RuntimeEndpointId,
+  flags: Pick<GoodVibesCliFlags, 'hostname' | 'port'>,
+): readonly string[] {
+  const keys = RUNTIME_ENDPOINT_CONFIG_KEYS[endpoint];
+  const errors: string[] = [];
+
+  if (flags.hostname !== undefined) {
+    try {
+      applyRuntimeConfigValue(configManager, keys.hostMode, hostModeForHostname(flags.hostname));
+      applyRuntimeConfigValue(configManager, keys.host, flags.hostname);
+    } catch (error) {
+      errors.push(error instanceof Error
+        ? `Invalid --hostname ${flags.hostname}: ${error.message}`
+        : `Invalid --hostname ${flags.hostname}`);
+    }
+  }
+
+  if (flags.port !== undefined) {
+    try {
+      applyRuntimeConfigValue(configManager, keys.port, flags.port);
+    } catch (error) {
+      errors.push(error instanceof Error
+        ? `Invalid --port ${flags.port}: ${error.message}`
+        : `Invalid --port ${flags.port}`);
+    }
+  }
+
+  return errors;
+}
+
+export function applyRuntimeCommandEndpointFlagOverrides(
+  configManager: ConfigManager,
+  command: GoodVibesCliCommand,
+  flags: Pick<GoodVibesCliFlags, 'hostname' | 'port'>,
+): readonly string[] {
+  if (flags.hostname === undefined && flags.port === undefined) return [];
+  if (command === 'web') return applyRuntimeEndpointFlagOverrides(configManager, 'web', flags);
+  if (command === 'listener') return applyRuntimeEndpointFlagOverrides(configManager, 'httpListener', flags);
+  if (command === 'control-plane' || command === 'pair' || command === 'serve') {
+    return applyRuntimeEndpointFlagOverrides(configManager, 'controlPlane', flags);
+  }
+  return [];
+}

package/src/cli/endpoints.ts

@@ -0,0 +1,63 @@
+import type { ConfigKey, ConfigManager } from '../config/index.ts';
+
+export type RuntimeEndpointId = 'controlPlane' | 'httpListener' | 'web';
+export type RuntimeHostMode = 'local' | 'network' | 'custom';
+
+export const RUNTIME_ENDPOINT_DEFAULT_PORTS: Record<RuntimeEndpointId, number> = {
+  controlPlane: 3421,
+  httpListener: 3422,
+  web: 3423,
+};
+
+export const RUNTIME_ENDPOINT_CONFIG_KEYS: Record<RuntimeEndpointId, {
+  readonly hostMode: ConfigKey;
+  readonly host: ConfigKey;
+  readonly port: ConfigKey;
+}> = {
+  controlPlane: {
+    hostMode: 'controlPlane.hostMode',
+    host: 'controlPlane.host',
+    port: 'controlPlane.port',
+  },
+  httpListener: {
+    hostMode: 'httpListener.hostMode',
+    host: 'httpListener.host',
+    port: 'httpListener.port',
+  },
+  web: {
+    hostMode: 'web.hostMode',
+    host: 'web.host',
+    port: 'web.port',
+  },
+};
+
+export interface RuntimeEndpointBinding {
+  readonly hostMode: string;
+  readonly configuredHost: string;
+  readonly host: string;
+  readonly port: number;
+}
+
+export function hostModeForHostname(hostname: string): RuntimeHostMode {
+  const normalized = hostname.toLowerCase();
+  if (normalized === '0.0.0.0' || normalized === '::') return 'network';
+  if (normalized === '127.0.0.1' || normalized === 'localhost' || normalized === '::1') return 'local';
+  return 'custom';
+}
+
+export function resolveRuntimeEndpointBinding(
+  config: Pick<ConfigManager, 'get'>,
+  endpoint: RuntimeEndpointId,
+): RuntimeEndpointBinding {
+  const keys = RUNTIME_ENDPOINT_CONFIG_KEYS[endpoint];
+  const hostMode = String(config.get(keys.hostMode) ?? 'local');
+  const configuredHost = String(config.get(keys.host) ?? '127.0.0.1');
+  const port = Number(config.get(keys.port) || RUNTIME_ENDPOINT_DEFAULT_PORTS[endpoint]);
+  if (hostMode === 'network') {
+    return { hostMode, configuredHost, host: '0.0.0.0', port };
+  }
+  if (hostMode === 'custom') {
+    return { hostMode, configuredHost, host: configuredHost || '127.0.0.1', port };
+  }
+  return { hostMode, configuredHost, host: '127.0.0.1', port };
+}