Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
148 lines (111 loc) · 5.44 KB

ARCHITECTURE.md

File metadata and controls

148 lines (111 loc) · 5.44 KB
Raw

xCloud Terminal Architecture

Product shape

xterm is a terminal-first xCloud client with two execution modes:

  1. Direct command mode

    • Deterministic, scriptable, JSON-friendly.
    • Should reuse the current xCloudDev/xCloud-cli command map and output behavior.
    • No LLM involved.

  2. AI agent mode

    • Interactive Claude Code-style agent shell.
    • User can ask natural-language infra tasks.
    • Agent plans, calls xCloud tools, observes output, asks for missing data, and confirms dangerous actions.

Recommended Node libraries

Verified current npm package availability on this server:

  • commander — command routing and flags.
  • enquirer — lightweight prompts for confirmations and missing parameters.
  • chalk + ora — readable terminal UI and step progress.
  • zod — schema validation for model outputs and tool parameters.
  • ai (Vercel AI SDK) — provider abstraction and streaming model calls.
  • openai — OpenAI-compatible provider; also works with OpenRouter base URLs.
  • @anthropic-ai/sdk — direct Anthropic/Claude provider.
  • @modelcontextprotocol/sdk — future MCP support for local/server tools.
  • node-pty as optional dependency — PTY bridge for shell execution / terminal sessions if needed.

Optional later:

  • ink + @inkjs/ui for richer React-based terminal UI after core agent is stable.
  • xterm.js for a future web terminal, not required for Ubuntu CLI TTY.
  • blessed only if Ink is too heavy or not desired.

Mode switch UX

Recommended commands:

# Direct mode
xterm servers list
xterm sites status <site-uuid>
xterm api get /servers --output json

# AI mode
xterm --ai
xterm agent
xterm chat "What is wrong with my server?"

# Explicit agent backend
xterm --ai --agent local
xterm --ai --agent hosted
xterm --ai --agent off   # same as direct mode

Aliases after packaging decision:

  • Keep existing xcloud from @xcloud/cli for direct commands.
  • xterm is the agent-first terminal brand.
  • Later, xcloud --ai can be added by making @xcloud/cli delegate to @xcloud/terminal, or by merging both packages.

Provider strategy

Terminal config should support:

XCLOUD_AI_PROVIDER=openrouter|anthropic|openai
XCLOUD_AI_MODEL=anthropic/claude-sonnet-4-5
XCLOUD_AI_BASE_URL=https://openrouter.ai/api/v1
XCLOUD_AI_API_KEY=***

# xCloud AI branch / OpenRouter-compatible aliases supported by xterm:
OPENROUTER_API_KEY=***
OPENROUTER_API_URL=https://openrouter.ai/api/v1
OPENROUTER_DEFAULT_MODEL=anthropic/claude-sonnet-4.5

No secrets in repository or logs. xterm doctor should report whether a provider is configured without printing the key.

Agent loop

Core loop:

  1. Build system prompt from xCloud tool catalog, safety rules, current profile, and recent conversation summary.
  2. Ask model for strict JSON decision validated by Zod:
    • answer
    • ask_user
    • tool_call
    • plan
  3. For tool call:
    • validate tool exists
    • validate params
    • enforce auth/scope/safety
    • require confirmation for write/destructive/billing actions
    • execute through same direct command/API client
    • reduce large output before sending observation back to model
  4. Repeat until final answer, cancellation, max steps, or safety denial.

Tool model

Initial tool sources:

  1. Existing direct command map from xCloudDev/xCloud-cli.
  2. Static curated YAML/JSON catalog adapted from xCloud app Public/Enterprise APIs.
  3. Later: hosted /api/ai/tools/available endpoint from the Laravel AI branch.
  4. Later: MCP servers for local shell, GitHub, file, or xCloud server diagnostics.

Safety gates

  • Direct mode and AI mode use the same HTTP client and route metadata.
  • AI mode cannot call raw write endpoints unless catalog marks them safe and confirmation passes.
  • Non-interactive AI writes require --yes plus explicit detected intent.
  • Never send secrets/confidential values to the model unless the user intentionally supplied them for that step and the tool requires them.
  • Never feed raw logs/blobs/API payloads into the model; reduce/summarize deterministically first.
  • Maintain an audit transcript under ~/.config/xcloud-terminal/runs/ with secrets redacted.
  • Add max steps, token budget, timeout, and cancellation support.

Hosted vs local agent

Local agent

Pros:

  • Works against any xCloud installation with API token.
  • Uses the bundled @xcloud/cli direct command/API layer as its tool execution backend.
  • Can use the xCloud AI/tool catalog concepts locally with the user's own AI provider key.
  • Faster iteration in CLI repo.
  • Good for open-source CLI and DevOps users.

Cons:

  • User must provide AI provider key.
  • Tool catalog must be shipped or fetched.

Hosted agent

Pros:

  • Loads portable agent skills from https://github.com/xCloudDev/xcloud-agent-skills.
  • Lets users run the terminal agent with their own Anthropic/OpenAI/OpenRouter token.
  • Can later reuse Laravel AI branch endpoints for team context, policy checks, server-side chat history, and hosted execution.
  • Best fit for Claude Code/OpenCode-style workflows where skills define reusable xCloud operating procedures.

Cons:

  • Requires skills repo versioning and update strategy.
  • If using Laravel /api/ai/*, requires the large AI chatbot branch to be production-ready.
  • CLI depends on xCloud app endpoints and execution token flow.

Recommended: build both. Default to local for xterm --ai / xcloud --ai; support --agent hosted to clone/update and load xcloud-agent-skills plus the user's provider key.