@gaia-ai/ui 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytec GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @gaia-ai/ui
+
+GAIA home-rooted cockpit: the `gaia ui` command plugin (renderer resolved dynamically).
+
+Part of the GAIA conductor. Install the meta package `@gaia-ai/gaia` to get the `gaia` CLI with all plugins. Source: https://git.key-tec.de/keytec/gaia (conductor/).

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export { cmdUi, default, type RunGaiaUiOptions, type UiDeps } from './ui.js';
+export { buildHomeConnection, type HomeConnection, resolveAgentCommand, resolveDefaultProject, resolveUiConfigPath, } from './ui-home.js';

package/dist/src/index.js

@@ -0,0 +1,5 @@
+// GAIA-201: `@gaia-ai/ui` — the home-rooted `gaia ui` command plugin. The
+// default export is the `GaiaCommandPlugin` the host mounts; `cmdUi` + the
+// home-connection builders are exported for tests.
+export { cmdUi, default } from './ui.js';
+export { buildHomeConnection, resolveAgentCommand, resolveDefaultProject, resolveUiConfigPath, } from './ui-home.js';

package/dist/src/preset.d.ts

@@ -0,0 +1,2 @@
+import type { GaiaPreset } from '@gaia-ai/core';
+export declare const commands: GaiaPreset['commands'];

package/dist/src/preset.js

@@ -0,0 +1,8 @@
+export const commands = (acc) => [
+    ...acc,
+    {
+        name: 'ui',
+        plugin: '@gaia-ai/ui',
+        describe: 'interactive terminal UI: project dashboard, ticket list, ticket detail',
+    },
+];

package/dist/src/ui-home.d.ts

@@ -0,0 +1,65 @@
+import { type ConductorRegistryEntry, type MachineContext } from '@gaia-ai/core';
+/**
+ * The resolved home control-plane connection passed to the renderer launcher.
+ * A structural mirror of `@gaia-ai/plugin-gaia-ui`'s `HomeConnection` — kept
+ * local so this package needs NO compile-time dependency on the renderer (it
+ * resolves the renderer dynamically, ESLint-style, at runtime).
+ */
+export interface HomeConnection {
+    baseUrl: string;
+    jsonapiPrefix?: string | undefined;
+    authPlugins: unknown[];
+    configPath?: string | undefined;
+    authProfile?: string | undefined;
+}
+/** The `session` oauth2 client-credentials descriptor, matching the connection
+ *  config template shape exactly so home reads authenticate identically to a
+ *  project-rooted `gaia dropsh`. */
+export interface SessionAuthDescriptor {
+    plugin: '@dropsh/plugin-oauth2';
+    export: 'oauth2Plugin';
+    with: {
+        id: 'session';
+        default: true;
+        type: 'oauth2_client_credentials';
+        client_id: string;
+        client_secret: string;
+        token_url: string;
+        scope: 'gaia:session';
+    };
+}
+/**
+ * Build the home control-plane connection from the machine context. Throws an
+ * actionable error when the context is missing `base_url` / `client_id` /
+ * `client_secret` (there is no project config to fall back to). The returned
+ * `authPlugins` carries a single `session` oauth2 descriptor; `configPath` is
+ * filled in by the entry once it has resolved the connection config file.
+ */
+export declare function buildHomeConnection(machine: Partial<MachineContext>): HomeConnection;
+/**
+ * Resolve the default project (opaque group) from the conductor registry: the
+ * `preferred` project when it is registered, else the first entry's project.
+ * `undefined` when the registry is empty — a valid empty cockpit.
+ */
+export declare function resolveDefaultProject(entries: ConductorRegistryEntry[], preferred?: string): string | undefined;
+/**
+ * Resolve the agent-launch command builder from the home config. Turns a TUI
+ * prompt into the shell command herdr runs. Defaults to `claude` (an empty
+ * prompt yields the bare launch command). A machine context may name a
+ * different `agent_command` binary.
+ */
+export declare function resolveAgentCommand(machine: Partial<MachineContext> & {
+    agent_command?: string;
+}): (prompt: string) => string;
+/**
+ * Resolve which connection config `gaia ui` reads. A user-authored home
+ * `~/.gaia/gaia.config.js` (`userConfigPath`) wins — a real home-level cockpit
+ * connection — used verbatim (`fallback: false`). Otherwise the shipped
+ * machine-context fallback (`fallbackPath`) is used (`fallback: true`), which
+ * requires a complete machine context. Pure: the caller does the
+ * `$DROPSH_CONFIG` / `$GAIA_MACHINE_CONTEXT` wiring.
+ */
+export declare function resolveUiConfigPath(userConfigPath: string, fallbackPath: string): {
+    path: string;
+    fallback: boolean;
+};

package/dist/src/ui-home.js

@@ -0,0 +1,82 @@
+// GAIA-201 (was GAIA-194): home-rooted bootstrap builders for `gaia ui`. Pure
+// functions that turn the user-global machine context (identity + connection) +
+// the conductor registry into everything `runGaiaUi` needs — WITHOUT a project
+// engine `conductor.config.js`. The `gaia ui` entry (`ui.ts`) wires them.
+import { existsSync } from 'node:fs';
+import { shellQuote, } from '@gaia-ai/core';
+/**
+ * Build the home control-plane connection from the machine context. Throws an
+ * actionable error when the context is missing `base_url` / `client_id` /
+ * `client_secret` (there is no project config to fall back to). The returned
+ * `authPlugins` carries a single `session` oauth2 descriptor; `configPath` is
+ * filled in by the entry once it has resolved the connection config file.
+ */
+export function buildHomeConnection(machine) {
+    const baseUrl = (machine.base_url ?? '').trim();
+    const clientId = (machine.client_id ?? '').trim();
+    const clientSecret = (machine.client_secret ?? '').trim();
+    const missing = [];
+    if (baseUrl === '')
+        missing.push('base_url');
+    if (clientId === '')
+        missing.push('client_id');
+    if (clientSecret === '')
+        missing.push('client_secret');
+    if (missing.length > 0) {
+        throw new Error(`gaia ui: the machine context is missing ${missing.join(', ')} — ` +
+            `run 'gaia conductor init --base-url <url>' to onboard this machine.`);
+    }
+    const descriptor = {
+        plugin: '@dropsh/plugin-oauth2',
+        export: 'oauth2Plugin',
+        with: {
+            id: 'session',
+            default: true,
+            type: 'oauth2_client_credentials',
+            client_id: clientId,
+            client_secret: clientSecret,
+            token_url: `${baseUrl}/oauth/token`,
+            scope: 'gaia:session',
+        },
+    };
+    return {
+        baseUrl,
+        jsonapiPrefix: '/jsonapi',
+        authPlugins: [descriptor],
+        authProfile: 'session',
+    };
+}
+/**
+ * Resolve the default project (opaque group) from the conductor registry: the
+ * `preferred` project when it is registered, else the first entry's project.
+ * `undefined` when the registry is empty — a valid empty cockpit.
+ */
+export function resolveDefaultProject(entries, preferred) {
+    if (preferred && entries.some((e) => e.project === preferred)) {
+        return preferred;
+    }
+    return entries[0]?.project;
+}
+/**
+ * Resolve the agent-launch command builder from the home config. Turns a TUI
+ * prompt into the shell command herdr runs. Defaults to `claude` (an empty
+ * prompt yields the bare launch command). A machine context may name a
+ * different `agent_command` binary.
+ */
+export function resolveAgentCommand(machine) {
+    const bin = (machine.agent_command ?? '').trim() || 'claude';
+    return (prompt) => prompt.trim() === '' ? bin : `${bin} ${shellQuote(prompt)}`;
+}
+/**
+ * Resolve which connection config `gaia ui` reads. A user-authored home
+ * `~/.gaia/gaia.config.js` (`userConfigPath`) wins — a real home-level cockpit
+ * connection — used verbatim (`fallback: false`). Otherwise the shipped
+ * machine-context fallback (`fallbackPath`) is used (`fallback: true`), which
+ * requires a complete machine context. Pure: the caller does the
+ * `$DROPSH_CONFIG` / `$GAIA_MACHINE_CONTEXT` wiring.
+ */
+export function resolveUiConfigPath(userConfigPath, fallbackPath) {
+    return existsSync(userConfigPath)
+        ? { path: userConfigPath, fallback: false }
+        : { path: fallbackPath, fallback: true };
+}

package/dist/src/ui.d.ts

@@ -0,0 +1,73 @@
+import { type ConductorRegistryEntry, type GaiaCommandHost, type GaiaCommandPlugin, type MachineContext } from '@gaia-ai/core';
+import { type AgentLaunchHost } from '@gaia-ai/plugin-herdr';
+import { type HomeConnection } from './ui-home.js';
+/** Prompt-level agent service the renderer consumes (mirror of gaia-ui's `TuiAgentService`). */
+interface TuiAgentService {
+    launch(o: {
+        group: string;
+        cwd: string;
+        prompt: string;
+        env: Record<string, string | undefined>;
+        isNew?: boolean | undefined;
+        label?: string | undefined;
+    }): Promise<{
+        id: string;
+        group: string;
+        label: string;
+    }>;
+    list(group: string): Promise<{
+        id: string;
+        group: string;
+        label: string;
+    }[]>;
+    focus(id: string): Promise<void>;
+    hide(group: string): Promise<void>;
+    kill(id: string): Promise<void>;
+}
+/** A dropsh program (only the `parseAsync` the launcher drives). */
+interface DropshProgram {
+    parseAsync(argv: string[], opts: {
+        from: 'user';
+    }): Promise<unknown>;
+}
+/** Options for gaia-ui's `runGaiaUi` (mirror of its `GaiaUiLauncherOptions`). */
+export interface RunGaiaUiOptions {
+    connection: HomeConnection;
+    cwd: string;
+    project?: string | undefined;
+    agents?: TuiAgentService | undefined;
+    currentUser?: string | undefined;
+    ownConductorMachineId?: string | undefined;
+    createPrompt?: string | undefined;
+    buildProgram: (opts: {
+        plugins: unknown[];
+    }) => DropshProgram;
+    renderer?: ((opts: unknown) => unknown) | undefined;
+}
+/** Test/composition seams for `gaia ui`. */
+export interface UiDeps {
+    /** Machine context (identity + connection); default: read from disk. */
+    machine?: Partial<MachineContext>;
+    /** Conductor registry entries; default: `listRegisteredConductors()`. */
+    registryEntries?: ConductorRegistryEntry[];
+    /** herdr-backed agent host; default: `herdrAgentHost(exec herdr)`. */
+    agentHost?: AgentLaunchHost;
+    /** The renderer launcher; default: the dynamically-resolved `runGaiaUi`. */
+    runUi?: (opts: RunGaiaUiOptions) => Promise<void>;
+    /** Pre-resolved home connection config path; default: resolved from ~/.gaia or the shipped fallback. */
+    homeConfigPath?: string;
+    /** Host contract (resolveBases) for renderer resolution; default: cwd + this install. */
+    host?: GaiaCommandHost;
+}
+/**
+ * `gaia ui` — launch the home-rooted interactive terminal UI. Reads the
+ * user-global machine context + the conductor registry (NOT a project engine
+ * config), resolves the connection from the home `gaia.config.js` scope, adapts
+ * a herdr-backed agent host to the renderer's prompt-level service, and
+ * delegates to `@gaia-ai/plugin-gaia-ui`'s `runGaiaUi`. `$GAIA_UI_PLUGIN`
+ * overrides the renderer module (dev).
+ */
+export declare function cmdUi(deps?: UiDeps): Promise<void>;
+/** The `ui` command plugin the host mounts (`gaia ui`). */
+declare const uiCommandPlugin: GaiaCommandPlugin;
+export default uiCommandPlugin;

package/dist/src/ui.js

@@ -0,0 +1,152 @@
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { CommandRunner, createLogger, exec, homeFallbackGaiaConfigPath, listRegisteredConductors, machineContextPath, readMachineContext, setDefaultCommandRunner, } from '@gaia-ai/core';
+import { herdrAgentHost } from '@gaia-ai/plugin-herdr';
+import { buildProgram as buildDropshProgram } from 'dropsh';
+import { buildHomeConnection, resolveAgentCommand, resolveDefaultProject, resolveUiConfigPath, } from './ui-home.js';
+function loggerFor(checkoutRoot) {
+    const logger = createLogger({ checkoutRoot });
+    setDefaultCommandRunner(new CommandRunner(logger));
+    return logger;
+}
+/**
+ * Resolve + dynamically import `@gaia-ai/plugin-gaia-ui` (the renderer launcher),
+ * ESLint-style over the host bases. This package never statically imports the
+ * renderer — it is a swappable plugin. Returns undefined (and logs) when the
+ * package is not installed.
+ */
+async function loadGaiaUiModule(logger, bases) {
+    let resolved;
+    for (const base of bases) {
+        try {
+            resolved = createRequire(base).resolve('@gaia-ai/plugin-gaia-ui');
+            break;
+        }
+        catch {
+            // try the next base
+        }
+    }
+    if (resolved === undefined) {
+        logger.error({}, 'gaia ui: could not resolve @gaia-ai/plugin-gaia-ui. ' +
+            'Install it, or set $GAIA_UI_PLUGIN to a renderer plugin path.');
+        return undefined;
+    }
+    return (await import(pathToFileURL(resolved).href));
+}
+/**
+ * `gaia ui` — launch the home-rooted interactive terminal UI. Reads the
+ * user-global machine context + the conductor registry (NOT a project engine
+ * config), resolves the connection from the home `gaia.config.js` scope, adapts
+ * a herdr-backed agent host to the renderer's prompt-level service, and
+ * delegates to `@gaia-ai/plugin-gaia-ui`'s `runGaiaUi`. `$GAIA_UI_PLUGIN`
+ * overrides the renderer module (dev).
+ */
+export async function cmdUi(deps = {}) {
+    const logger = loggerFor(homedir());
+    const host = deps.host ?? {
+        resolveBases: [`${process.cwd()}/`, import.meta.url],
+    };
+    const mcPath = machineContextPath();
+    const machine = deps.machine ?? (await readMachineContext(mcPath).catch(() => ({})));
+    // Which connection config `gaia ui` reads: a user-authored
+    // `~/.gaia/gaia.config.js` wins; otherwise the shipped machine-context
+    // fallback. The test seam `homeConfigPath` forces a path (fallback branch).
+    const userHomeConfig = join(homedir(), '.gaia', 'gaia.config.js');
+    const resolved = deps.homeConfigPath
+        ? { path: deps.homeConfigPath, fallback: true }
+        : resolveUiConfigPath(userHomeConfig, homeFallbackGaiaConfigPath());
+    let connection;
+    if (resolved.fallback) {
+        try {
+            connection = buildHomeConnection(machine);
+        }
+        catch (err) {
+            logger.error({}, err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+            return;
+        }
+        if (!process.env.GAIA_MACHINE_CONTEXT) {
+            process.env.GAIA_MACHINE_CONTEXT = mcPath;
+        }
+    }
+    else {
+        connection = { baseUrl: '', authProfile: 'session', authPlugins: [] };
+    }
+    connection.configPath = resolved.path;
+    const entries = deps.registryEntries ?? (await listRegisteredConductors());
+    const project = resolveDefaultProject(entries);
+    const projectEntry = entries.find((e) => e.project === project);
+    const cwd = projectEntry?.path ?? homedir();
+    const ownConductorMachineId = projectEntry?.id;
+    const agentCommand = resolveAgentCommand(machine);
+    const agentHost = deps.agentHost ?? herdrAgentHost((args) => exec('herdr', args));
+    const agents = {
+        launch: (o) => agentHost.launch({
+            group: o.group,
+            cwd: o.cwd,
+            command: agentCommand(o.prompt),
+            env: o.env,
+            ...(o.label !== undefined ? { label: o.label } : {}),
+        }),
+        list: (group) => agentHost.list(group),
+        focus: (id) => agentHost.focus(id),
+        hide: (group) => agentHost.hide(group),
+        kill: (id) => agentHost.kill(id),
+    };
+    let renderer;
+    const override = process.env.GAIA_UI_PLUGIN;
+    if (override) {
+        try {
+            const mod = (await import(pathToFileURL(override).href));
+            const factory = mod.default ?? mod.ticketRendererPlugin;
+            if (typeof factory !== 'function') {
+                throw new Error('module exports no renderer-plugin factory');
+            }
+            renderer = factory;
+        }
+        catch (err) {
+            logger.error({ override }, `gaia ui: could not load $GAIA_UI_PLUGIN at ${override} ` +
+                `(${err instanceof Error ? err.message : String(err)}).`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    let run = deps.runUi;
+    if (!run) {
+        const uiMod = await loadGaiaUiModule(logger, host.resolveBases);
+        if (uiMod === undefined) {
+            process.exitCode = 1;
+            return;
+        }
+        run = uiMod.runGaiaUi;
+    }
+    await run({
+        connection,
+        cwd,
+        ...(project !== undefined ? { project } : {}),
+        agents,
+        ...(machine.user_id ? { currentUser: machine.user_id } : {}),
+        ...(ownConductorMachineId ? { ownConductorMachineId } : {}),
+        buildProgram: (o) => buildDropshProgram({
+            plugins: o.plugins,
+        }),
+        ...(renderer ? { renderer } : {}),
+    });
+}
+/** The `ui` command plugin the host mounts (`gaia ui`). */
+const uiCommandPlugin = {
+    kind: 'command',
+    name: 'ui',
+    describe: 'interactive terminal UI: project dashboard, ticket list, ticket detail',
+    register(program, host) {
+        program
+            .command('ui')
+            .description('interactive terminal UI: project dashboard, ticket list, ticket detail')
+            .action(async () => {
+            await cmdUi({ host });
+        });
+    },
+};
+export default uiCommandPlugin;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@gaia-ai/ui",
+  "version": "0.6.0",
+  "description": "GAIA home-rooted cockpit: the `gaia ui` command plugin (renderer resolved dynamically).",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./preset": "./dist/src/preset.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.key-tec.de/keytec/gaia.git",
+    "directory": "conductor/ui"
+  },
+  "dependencies": {
+    "@gaia-ai/core": "^0.6.0",
+    "@gaia-ai/plugin-herdr": "^0.6.0",
+    "commander": "^12.1.0",
+    "dropsh": "^0.5.8"
+  }
+}