Admin UI: add bottom docked Kalam CLI console with multiple tabs

[jamals86]

Summary

Add a docked Kalam CLI-style console at the bottom of the Admin UI.

Important design decision: do not implement a second CLI inside the Admin UI/backend. The Admin UI console should reuse the existing kalam CLI tool as the execution layer, but run it in a restricted mode designed specifically for browser/admin usage.

The console should behave like a database terminal inside the UI, but it must not expose a real server shell. It should only execute KalamDB SQL and safe Kalam CLI-style meta commands.

Product goal

Give users the same experience they already get from the terminal CLI, directly inside the Admin UI:

kalam>

This makes the Admin UI feel like an IDE/database console while avoiding duplicate logic between:

• CLI
• Admin UI SQL console
• WebSocket subscriptions
• formatting
• meta commands
• error rendering

Recommended architecture

Use the existing kalam CLI binary in a restricted child process/session mode.

Admin UI bottom dock
  -> WebSocket /admin/console
  -> AdminConsoleSession
  -> spawn/reuse kalam CLI in restricted mode
  -> KalamDB server API/WebSocket

The Admin UI should not directly reimplement command parsing, formatting, subscription behavior, or meta-command logic unless there is a very strong reason.

Avoid this:

Admin UI
  -> WebSocket
  -> /bin/bash
  -> kalam

Also avoid this:

Admin UI/backend
  -> brand new console implementation duplicating kalam CLI behavior

Preferred implementation:

kalam \
  --url "$KALAMDB_URL" \
  --token "$SCOPED_TOKEN" \
  --no-shell \
  --disable-file-read \
  --disable-credentials \
  --disable-local-meta

CLI subtask: add restricted web-console flags

Add these CLI args to kalam:

--no-shell
--disable-file-read
--disable-credentials
--disable-local-meta

--no-shell

Purpose: make it explicit that this CLI session cannot execute any OS/shell command.

Behavior:

• Disable any present/future shell escape command.
• Block commands like \!, shell, exec, or anything that could run a host process.
• If shell escape does not exist today, still add this guard so it cannot be accidentally enabled later.
• Return a clear error:

ERROR: shell access is disabled in this session

--disable-file-read

Purpose: prevent browser-driven sessions from reading files from the server/container filesystem.

Behavior:

• Disable -f/--file in restricted sessions.
• Disable any interactive command that loads SQL from a local path.
• Disable future commands like \i, \include, \source, or similar.
• Return a clear error:

ERROR: reading local files is disabled in this session

--disable-credentials

Purpose: prevent credential leakage or credential mutation from the Admin UI console.

Behavior:

Disable commands/flags such as:

--show-credentials
--update-credentials
--delete-credentials
\show-credentials
\update-credentials
\delete-credentials

In this mode the CLI should only use credentials passed by the Admin UI/backend, preferably a short-lived scoped token.

Return a clear error:

ERROR: credential commands are disabled in this session

--disable-local-meta

Purpose: disable local-machine/session meta operations that make sense in a developer terminal but not in a web admin console.

Examples to block or carefully review:

\config
\show-credentials
\update-credentials
\delete-credentials
local config path inspection
local file path inspection

Safe commands should still work:

\help
\?
\q
\dt
\d app.messages
\health
\stats
\format table|json|csv
\subscribe SELECT * FROM app.messages WHERE conversation_id = 1
\unsubscribe

Return a clear error:

ERROR: local meta command is disabled in this session

Admin UI user experience

• Add a bottom panel/dock in the Admin UI.
• The panel can be opened and closed.
• The panel can be resized vertically.
• Support multiple CLI tabs.
• Each tab has its own independent console session/history.
• Tabs can be created, renamed, closed, and switched.
• Persist UI state locally when reasonable:
  • panel open/closed
  • active tab
  • tab names
  • optional command history
• Provide toolbar buttons:
  • open/close
  • new tab
  • close tab
  • rename tab
  • clear output
  • stop running command
  • format selector if useful
• Output should be selectable/copyable.
• Errors should be rendered cleanly, similar to the CLI and SQL editor.

Multiple tab behavior

Each tab should map to one independent restricted kalam session.

Example:

Tab 1 -> kalam session A
Tab 2 -> kalam session B
Tab 3 -> kalam session C

Each tab should have its own:

• command history
• output buffer
• active subscription state
• current output format
• cancellation state
• prompt lifecycle

Closing a tab should gracefully stop the underlying CLI session.

If a tab has an active subscription, closing the tab should unsubscribe/close the session cleanly.

Backend console service plan

Add an Admin UI backend console bridge.

Possible endpoint:

WS /admin/console

The bridge should:

1. Authenticate the Admin UI user.
2. Create a short-lived scoped token for the CLI session.
3. Spawn kalam in restricted mode.
4. Connect stdin/stdout/stderr to the WebSocket.
5. Stream output chunks back to the browser.
6. Accept input lines from the browser.
7. Support cancellation/interrupt for the active command.
8. Stop the process/session on tab close or idle timeout.
9. Enforce limits.

Recommended command shape:

kalam \
  --url http://127.0.0.1:2900 \
  --token "$SCOPED_TOKEN" \
  --no-shell \
  --disable-file-read \
  --disable-credentials \
  --disable-local-meta

Do not pass root/admin credentials directly to the browser.

Session limits

Add defensive limits per user/session/tab:

• max tabs per user
• idle timeout
• query timeout
• max output bytes per command
• max buffered output per tab
• max subscription messages retained in UI
• max rows displayed by default
• cancellation timeout before force kill

Example defaults:

max_tabs_per_user = 5
idle_timeout_seconds = 600
query_timeout_seconds = 30
max_output_bytes = 1048576
max_buffered_lines = 5000
max_subscription_events = 1000

Supported commands

The console should support normal SQL statements, for example:

SELECT * FROM system.tables LIMIT 10;
DESCRIBE TABLE app.messages;
SHOW TABLES IN app;
FLUSH TABLE app.messages;

It should support safe Kalam CLI-style meta commands where applicable:

\help
\?
\q
\dt
\d app.messages
\health
\stats
\format table|json|csv
\subscribe SELECT * FROM app.messages WHERE conversation_id = 1
\unsubscribe

Security requirements

This console must not be a real terminal.

Do not expose:

• /bin/bash
• PowerShell
• SSH
• arbitrary process execution
• filesystem access
• environment variables
• shell escape commands
• local file loading such as -f file.sql
• credential display/update/delete commands from the browser console

The backend should treat this as a restricted Kalam CLI session, not an OS shell.

Live subscriptions

For \subscribe support:

• Reuse the existing Kalam CLI subscription behavior.
• Show incoming events in the tab output.
• Allow stopping the subscription with \unsubscribe or a stop button.
• Keep subscription output readable with timestamps and event type.
• Prevent runaway output with a max buffered message count.
• Closing the tab should stop the subscription cleanly.

Output formatting

Prefer reusing existing CLI formatting:

• table
• json
• csv
• row count
• latency/took time
• clean error messages

The Admin UI terminal should not invent a different result format unless needed for visual rendering.

Error handling

Examples:

ERROR: shell access is disabled in this session
ERROR: reading local files is disabled in this session
ERROR: credential commands are disabled in this session
ERROR: local meta command is disabled in this session
ERROR: command timed out after 30s
ERROR: output exceeded 1MB and was truncated

Implementation phases

Phase 1: CLI restricted mode

• Add --no-shell.
• Add --disable-file-read.
• Add --disable-credentials.
• Add --disable-local-meta.
• Add tests for blocked commands and blocked flags.
• Ensure existing normal CLI behavior is unchanged when flags are not passed.

Phase 2: Backend console bridge

• Add WebSocket endpoint for Admin UI console sessions.
• Spawn restricted kalam process per tab/session.
• Stream stdin/stdout/stderr.
• Add timeout and output limits.
• Add cancellation.
• Add cleanup on disconnect.

Phase 3: Admin UI bottom dock

• Add bottom dock component.
• Add open/close/resize behavior.
• Add multiple tabs.
• Wire tabs to backend console sessions.
• Add toolbar actions.
• Render output cleanly.

Phase 4: Subscriptions and polish

• Ensure \subscribe works well in a tab.
• Add stop/unsubscribe button.
• Add max event buffer.
• Add copy/select behavior.
• Persist local UI state where useful.

Testing plan

CLI tests

Cover:

• --no-shell blocks shell escape commands.
• --disable-file-read blocks -f/--file and local include/source commands.
• --disable-credentials blocks credential show/update/delete commands.
• --disable-local-meta blocks local-only meta commands.
• Safe commands still work.
• Normal CLI mode remains unchanged.

Backend tests

Cover:

• create console session
• send SQL command
• receive output
• command failure display
• cancellation
• idle timeout
• max output truncation
• process cleanup on disconnect

Admin UI tests

Cover:

• open/close dock
• resize dock
• create/switch/close tabs
• command execution
• command failure display
• blocked unsafe command
• subscription start/stop
• tab close cleans up session

Acceptance criteria

• Admin UI has a bottom Kalam console panel.
• User can open and close the panel.
• User can create and switch between multiple console tabs.
• Each tab uses the existing kalam CLI in restricted mode.
• SQL commands execute successfully from a tab.
• Safe meta commands work where supported.
• No duplicate CLI implementation is added.
• No OS shell access is possible.
• No filesystem/environment access is possible.
• Credential commands are blocked.
• Local-only meta commands are blocked.
• Long-running command can be cancelled.
• \subscribe can stream updates and be stopped.
• Output supports table/json/csv-like display modes.
• Tests cover restricted mode, backend bridge, and Admin UI behavior.

Notes

This could use wterm or a similar terminal UI renderer on the frontend, but the security boundary must be:

1. restricted kalam CLI mode
2. backend console bridge limits
3. scoped auth token

The terminal component itself should not be treated as a security boundary.

Similar to how Google Console have it: