@terminai/core 0.21.0

package/dist/docs/security-posture.md

@@ -0,0 +1,52 @@
+# TerminaI Security Posture
+
+This document captures the current threat model and controls for TerminaI (local
+CLI + web-remote). It should be reviewed before enabling non-local access or
+relaxing guardrails.
+
+## Threat Model
+
+- **Trusted boundary:** The local terminal user.
+- **Conditionally trusted:** Web-remote clients that possess the auth token.
+- **Untrusted inputs:** Files from the workspace, model responses, user-provided
+  URLs, and web content fetched at runtime.
+
+### Considered Attack Vectors
+
+1. Prompt injection via untrusted files or model responses.
+2. Command injection through crafted inputs passed to the shell tool.
+3. Web-remote session hijacking or replay.
+4. CSRF/XSRF against web-remote endpoints.
+5. Destructive shell commands (accidental or malicious).
+6. Privilege escalation via `sudo` or device writes.
+
+## Security Controls
+
+| Control                    | Implementation                                                    |
+| -------------------------- | ----------------------------------------------------------------- |
+| Auth tokens for web-remote | `packages/a2a-server/src/http/auth.ts`                            |
+| CORS allowlist             | `packages/a2a-server/src/http/cors.ts`                            |
+| Replay protection          | `packages/a2a-server/src/http/replay.ts`                          |
+| Session notifications      | `packages/core/src/tools/process-notifications.ts`                |
+| Risk classification        | `packages/core/src/safety/risk-classifier.ts`                     |
+| Destructive guardrails     | `packages/core/src/safety/built-in.ts` (`checkDestructive`)       |
+| Preview mode               | `--preview` flag; enforced in `shell.ts` and `file-ops.ts`        |
+| Confirmation bus           | `packages/core/src/confirmation-bus/`                             |
+| Folder trust               | `packages/cli/src/config/trustedFolders.ts`                       |
+| Voice-safe approvals       | Voice mode forces non-YOLO in `packages/cli/src/config/config.ts` |
+| Static web client          | Served from `/ui` with tokenized URL                              |
+
+## Operator Guidance
+
+- Prefer `--preview` when exploring unfamiliar repos.
+- Keep web-remote bound to loopback; if exposing externally, rotate tokens and
+  set an allowlist of origins.
+- Avoid running as root; TerminaI will label privileged commands as high risk.
+- Treat model responses as untrusted—verify before executing.
+
+## Future Hardening
+
+- Per-command provenance labeling in the UI.
+- Stronger CSRF protections with double-submit tokens.
+- Explicit opt-in for model-provided URLs before fetching.
+- Optional IP allowlisting for web-remote.

package/dist/docs/sidebar.json

@@ -0,0 +1,329 @@
+[
+  {
+    "label": "Overview",
+    "items": [
+      {
+        "label": "Introduction",
+        "slug": "docs"
+      },
+      {
+        "label": "TerminaI operator recipes",
+        "slug": "docs/termai-operator-recipes"
+      },
+      {
+        "label": "TerminaI quickstart",
+        "slug": "docs/termai-quickstart"
+      },
+      {
+        "label": "What can TerminaI do?",
+        "slug": "docs/termai-examples"
+      },
+      {
+        "label": "TerminaI comparison",
+        "slug": "docs/termai-comparison"
+      },
+      {
+        "label": "Demo scripts",
+        "slug": "docs/demos"
+      },
+      {
+        "label": "Architecture overview",
+        "slug": "docs/architecture"
+      },
+      {
+        "label": "Contribution guide",
+        "slug": "docs/contributing"
+      },
+      {
+        "label": "Security posture",
+        "slug": "docs/security-posture"
+      }
+    ]
+  },
+  {
+    "label": "Get started",
+    "items": [
+      {
+        "label": "TerminaI quickstart",
+        "slug": "docs/termai-quickstart"
+      },
+      {
+        "label": "Gemini CLI quickstart",
+        "slug": "docs/get-started"
+      },
+      {
+        "label": "Gemini 3 on Gemini CLI",
+        "slug": "docs/get-started/gemini-2.0-flash-exp"
+      },
+      {
+        "label": "Authentication",
+        "slug": "docs/get-started/authentication"
+      },
+      {
+        "label": "Configuration",
+        "slug": "docs/get-started/configuration"
+      },
+      {
+        "label": "Installation",
+        "slug": "docs/get-started/installation"
+      },
+      {
+        "label": "Examples",
+        "slug": "docs/get-started/examples"
+      }
+    ]
+  },
+  {
+    "label": "CLI",
+    "items": [
+      {
+        "label": "Introduction",
+        "slug": "docs/cli"
+      },
+      {
+        "label": "Commands",
+        "slug": "docs/cli/commands"
+      },
+      {
+        "label": "Checkpointing",
+        "slug": "docs/cli/checkpointing"
+      },
+      {
+        "label": "Custom commands",
+        "slug": "docs/cli/custom-commands"
+      },
+      {
+        "label": "Enterprise",
+        "slug": "docs/cli/enterprise"
+      },
+      {
+        "label": "Headless mode",
+        "slug": "docs/cli/headless"
+      },
+      {
+        "label": "TerminaI process manager",
+        "slug": "docs/termai-process-manager"
+      },
+      {
+        "label": "Keyboard shortcuts",
+        "slug": "docs/cli/keyboard-shortcuts"
+      },
+      {
+        "label": "Model selection",
+        "slug": "docs/cli/model"
+      },
+      {
+        "label": "Sandbox",
+        "slug": "docs/cli/sandbox"
+      },
+      {
+        "label": "Session Management",
+        "slug": "docs/cli/session-management"
+      },
+      {
+        "label": "Settings",
+        "slug": "docs/cli/settings"
+      },
+      {
+        "label": "Telemetry",
+        "slug": "docs/cli/telemetry"
+      },
+      {
+        "label": "Themes",
+        "slug": "docs/cli/themes"
+      },
+      {
+        "label": "Token caching",
+        "slug": "docs/cli/token-caching"
+      },
+      {
+        "label": "Trusted Folders",
+        "slug": "docs/cli/trusted-folders"
+      },
+      {
+        "label": "Tutorials",
+        "slug": "docs/cli/tutorials"
+      },
+      {
+        "label": "Uninstall",
+        "slug": "docs/cli/uninstall"
+      },
+      {
+        "label": "System prompt override",
+        "slug": "docs/cli/system-prompt"
+      }
+    ]
+  },
+  {
+    "label": "Core",
+    "items": [
+      {
+        "label": "Introduction",
+        "slug": "docs/core"
+      },
+      {
+        "label": "Tools API",
+        "slug": "docs/core/tools-api"
+      },
+      {
+        "label": "Memory Import Processor",
+        "slug": "docs/core/memport"
+      },
+      {
+        "label": "Policy Engine",
+        "slug": "docs/core/policy-engine"
+      }
+    ]
+  },
+  {
+    "label": "Tools",
+    "items": [
+      {
+        "label": "Introduction",
+        "slug": "docs/tools"
+      },
+      {
+        "label": "File system",
+        "slug": "docs/tools/file-system"
+      },
+      {
+        "label": "Shell",
+        "slug": "docs/tools/shell"
+      },
+      {
+        "label": "Web fetch",
+        "slug": "docs/tools/web-fetch"
+      },
+      {
+        "label": "Web search",
+        "slug": "docs/tools/web-search"
+      },
+      {
+        "label": "Memory",
+        "slug": "docs/tools/memory"
+      },
+      {
+        "label": "Todos",
+        "slug": "docs/tools/todos"
+      },
+      {
+        "label": "MCP servers",
+        "slug": "docs/tools/mcp-server"
+      }
+    ]
+  },
+  {
+    "label": "Extensions",
+    "items": [
+      {
+        "label": "Introduction",
+        "slug": "docs/extensions"
+      },
+      {
+        "label": "Get started with extensions",
+        "slug": "docs/extensions/getting-started-extensions"
+      },
+      {
+        "label": "Extension releasing",
+        "slug": "docs/extensions/extension-releasing"
+      }
+    ]
+  },
+  {
+    "label": "Hooks",
+    "items": [
+      {
+        "label": "Introduction",
+        "slug": "docs/hooks"
+      },
+      {
+        "label": "Writing hooks",
+        "slug": "docs/hooks/writing-hooks"
+      },
+      {
+        "label": "Hooks reference",
+        "slug": "docs/hooks/reference"
+      },
+      {
+        "label": "Best practices",
+        "slug": "docs/hooks/best-practices"
+      }
+    ]
+  },
+  {
+    "label": "IDE integration",
+    "items": [
+      {
+        "label": "Introduction",
+        "slug": "docs/ide-integration"
+      },
+      {
+        "label": "IDE companion spec",
+        "slug": "docs/ide-integration/ide-companion-spec"
+      }
+    ]
+  },
+  {
+    "label": "Development",
+    "items": [
+      {
+        "label": "NPM",
+        "slug": "docs/npm"
+      },
+      {
+        "label": "Releases",
+        "slug": "docs/releases"
+      },
+      {
+        "label": "Integration tests",
+        "slug": "docs/integration-tests"
+      },
+      {
+        "label": "Issue and PR automation",
+        "slug": "docs/issue-and-pr-automation"
+      }
+    ]
+  },
+  {
+    "label": "Releases",
+    "items": [
+      {
+        "label": "Release notes",
+        "slug": "docs/changelogs/"
+      },
+      {
+        "label": "Latest release",
+        "slug": "docs/changelogs/latest"
+      },
+      {
+        "label": "Preview release",
+        "slug": "docs/changelogs/preview"
+      },
+      {
+        "label": "Changelog",
+        "slug": "docs/changelogs/releases"
+      }
+    ]
+  },
+  {
+    "label": "Support",
+    "items": [
+      {
+        "label": "FAQ",
+        "slug": "docs/faq"
+      },
+      {
+        "label": "Troubleshooting",
+        "slug": "docs/troubleshooting"
+      },
+      {
+        "label": "Quota and pricing",
+        "slug": "docs/quota-and-pricing"
+      },
+      {
+        "label": "Terms of service",
+        "slug": "docs/tos-privacy"
+      }
+    ]
+  }
+]

package/dist/docs/termai-comparison.md

@@ -0,0 +1,91 @@
+# TerminaI comparison (systems-first)
+
+This guide explains _category differences_.
+
+TerminaI is not “another coding agent.” It’s a **system operator**: governed
+execution + PTY + auditability, designed to safely fix and manage real machines
+(laptops and servers).
+
+## Quick mental model
+
+| Category                                                     | Optimized for                 | What you get                                                                    | What you don’t get                                             |
+| ------------------------------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| **Coding agents** (Aider / Claude Code / Cursor-style flows) | editing code fast             | great diffs, repo changes                                                       | strong ops governance + audited system repairs                 |
+| **Terminal UX tools** (Warp)                                 | nicer terminal experience     | UI + autocomplete + some AI help                                                | an operator loop that executes multi-step tasks with approvals |
+| **Desktop automation** (Open Interpreter-style)              | “do stuff on my desktop”      | broad automation                                                                | often weak governance/audit for risky ops                      |
+| **TerminaI**                                                 | **governed system operation** | policy ladder + approvals + PTY execution + audit trail + MCP/A2A extensibility | not (yet) a polished enterprise fleet product                  |
+
+## TerminaI vs Gemini CLI (upstream engine)
+
+TerminaI is currently a forked product direction built on a stable upstream
+core.
+
+- **Focus:** Gemini CLI is broad and developer-oriented; TerminaI is
+  **systems-first**.
+- **Product primitives:** TerminaI centers:
+  - policy/approval ladders
+  - PTY-based execution (real TUIs)
+  - auditability
+  - A2A + MCP integration
+- **Command surface:** TerminaI is branded around `terminai`.
+
+## TerminaI vs Aider
+
+- **Aider wins** when: you want tight, code-only iteration with git-aware edits.
+- **TerminaI wins** when: the problem is _the machine_, not just the repo.
+  - diagnose environment drift
+  - fix build toolchains
+  - manage processes/services
+  - repair system networking/storage
+  - do it under governance (approvals + audit)
+
+## TerminaI vs Claude Code / editor-centric agents
+
+- **Editor agents win** when: the task is entirely inside the editor.
+- **TerminaI wins** when: code changes must be paired with **real operational
+  actions**:
+  - install packages
+  - restart services
+  - inspect logs
+  - run migrations
+  - update system config
+
+## TerminaI vs Warp (and other terminal UX)
+
+- **Warp wins** when: you want a beautiful terminal replacement.
+- **TerminaI wins** when: you want a **governed operator** layered on your
+  terminal/host:
+  - multi-step plans
+  - tool confirmation
+  - structured logs + audit trails
+
+## TerminaI vs Open Interpreter (desktop automation)
+
+- **Open Interpreter wins** when: you want broad “desktop” actions.
+- **TerminaI wins** when: you need:
+  - explicit trust boundaries
+  - preview/approval before destructive ops
+  - reproducible actions
+  - audit trails you can show other humans
+
+## TerminaI vs “just scripts”
+
+Scripts are great—when you already know the correct script.
+
+TerminaI shines when the job is:
+
+- ambiguous (“why is this machine slow?”)
+- environment-specific
+- risky (needs guardrails)
+- multi-system (MCP/A2A coordination)
+
+## Why contributors should care
+
+If you want to build _trustworthy_ agentic automation, TerminaI is a playground
+of the right primitives:
+
+- **Policy engine** (governance)
+- **PTY execution** (real operator substrate)
+- **Audit log** (accountability)
+- **MCP** (capability bus)
+- **A2A** (agent control plane)

package/dist/docs/termai-examples.md

@@ -0,0 +1,51 @@
+# What can TerminaI do?
+
+TerminaI is designed for everyday terminal tasks, not just code. Here are
+concrete examples you can copy-paste.
+
+## System and ops
+
+```text
+What's eating my CPU right now? Show top offenders.
+How much disk do I have left on this machine?
+Find all files larger than 1 GB and suggest safe ways to shrink them.
+```
+
+## Files and organization
+
+```text
+Organize my Downloads folder by type. Preview the changes first.
+Search this repo for any references to "deprecated" and summarize the files.
+Compress large log files in ./logs and leave the originals intact.
+```
+
+## Web + latest info
+
+```text
+What's the weather in Austin today? Cite sources.
+Find the latest release notes for Kubernetes 1.31 and summarize in 5 bullets.
+Search for the latest CVEs related to OpenSSL and list the top 5.
+```
+
+## Process control
+
+```text
+Start "npm run dev" as devserver and tell me when it's ready.
+Show me the last 50 lines from devserver.
+Send Ctrl+C to devserver.
+```
+
+## Automation prompts
+
+```text
+Every 5 minutes, check if https://example.com is up and alert me if it fails.
+Make a checklist for deploying the staging build, then run it step by step.
+```
+
+## Safe pattern
+
+Ask for a preview, then confirm:
+
+```text
+Find and delete node_modules folders over 500 MB, but show me a preview first.
+```

package/dist/docs/termai-operator-recipes.md

@@ -0,0 +1,93 @@
+# TerminaI Operator Recipes
+
+This page contains practical, safe prompts for common terminal tasks. Each
+recipe is designed to be concise, observable, and confirmable.
+
+## Safe pattern (recommended)
+
+1. **Preview:** Ask for a plan before execution.
+2. **Explain:** Ask for a short explanation of any command that modifies files.
+3. **Confirm:** Approve only the exact commands you expect.
+4. **Recap:** Ask for a brief summary of what changed.
+
+## System triage
+
+**CPU usage**
+
+```
+What is using my CPU right now? Summarize the top 5 processes and suggest a safe next step.
+```
+
+**Disk usage**
+
+```
+Why is my disk full? Show the largest directories and recommend a safe cleanup plan.
+```
+
+## Search files and content
+
+**Find files by pattern**
+
+```
+Find all *.log files under the current workspace and list the most recently modified ones.
+```
+
+**Search for text**
+
+```
+Search the workspace for "TODO" and show file paths with line numbers.
+```
+
+## Organize files safely
+
+**Create folders and organize**
+
+```
+Create an "archive" folder and move all *.log files into it. Show a plan first.
+```
+
+**Back up a directory**
+
+```
+Copy the "assets" folder into "backup/assets". Ask for confirmation before any overwrite.
+```
+
+**Compress large files**
+
+```
+Find the largest files over 1GB and compress them into an archive. Show a plan first.
+```
+
+**Organize Downloads**
+
+```
+Organize my Downloads folder by file type into subfolders (images, docs, archives). Show a plan first.
+```
+
+## Get latest online info (with sources)
+
+**Discover sources**
+
+```
+Find the latest release notes for Kubernetes and cite sources.
+```
+
+**Deep read a specific page**
+
+```
+Summarize https://kubernetes.io/docs/home/ in 5 bullets and cite sources.
+```
+
+## Logs and summaries
+
+**Tail logs and summarize**
+
+```
+Tail the last 200 lines of server.log and summarize errors by type.
+```
+
+**Explain an error**
+
+```
+Explain this error and suggest safe next steps: <paste error text>
+```

package/dist/docs/termai-process-manager.md

@@ -0,0 +1,68 @@
+# terminaI Process Manager — Manual Verification
+
+This page documents the manual verification flow for terminaI's process
+orchestration capabilities. These checks ensure that long-running sessions can
+be started, observed, and stopped safely.
+
+## Preconditions
+
+- You can run `gemini` from this repo (for example, via `npm run start`).
+- You have a project with a long-running command (example: `npm run dev`).
+
+## Manual verification steps
+
+1. **Start a long-running process**
+
+   Prompt:
+
+   ```
+   Start `npm run dev` as `devserver` and tell me when it’s ready.
+   ```
+
+   Expected:
+   - terminaI starts a named session `devserver`.
+   - Output is streamed or summarized.
+   - Readiness is acknowledged based on output text.
+
+2. **Read recent output**
+
+   Prompt:
+
+   ```
+   Show me the last 50 lines from `devserver`.
+   ```
+
+   Expected:
+   - terminaI returns the last 50 lines from the session buffer.
+   - Output is bounded and does not dump the full log.
+
+3. **Stop the session safely**
+
+   Prompt:
+
+   ```
+   Send Ctrl+C to `devserver`.
+   ```
+
+   Expected:
+   - terminaI sends SIGINT (or PTY input) to the process.
+   - If a confirmation prompt appears, approve it.
+   - The session stops cleanly.
+
+4. **List active sessions**
+
+   Prompt:
+
+   ```
+   List running sessions.
+   ```
+
+   Expected:
+   - terminaI lists known sessions.
+   - `devserver` is marked exited/stopped if it was terminated.
+
+## Notes
+
+- If a PTY is unavailable, input may not be accepted. The CLI should surface a
+  clear error in this case.
+- Destructive actions (stop/restart) should always require confirmation.