Skip to content

Comments

Architect Sovereign Runtime#43

Draft
google-labs-jules[bot] wants to merge 3885 commits intomainfrom
architect/sovereign-runtime-17950837186394507145
Draft

Architect Sovereign Runtime#43
google-labs-jules[bot] wants to merge 3885 commits intomainfrom
architect/sovereign-runtime-17950837186394507145

Conversation

@google-labs-jules
Copy link
Contributor

Added docs-terminai/specs/sovereign_runtime_architecture.md detailing the Sovereign Runtime Architecture.
This architecture defines:

  1. Tier 1: Sovereign Sandbox (Docker/Podman with repo-owned image).
  2. Tier 2: Managed Host Shim (Auto-bootstrapped local venv with terminai-apts).
  3. Tier 3: Embedded Runtime (Future).
  4. T-APTS: A new repo-owned Python library to replace opaque upstream dependencies.

PR created automatically by Jules for task 17950837186394507145 started by @Prof-Harita

scidomino and others added 30 commits December 15, 2025 21:18
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
…on format take priority over ones using the old format (#15116)
Co-authored-by: Abhi <abhipatel@google.com>
… (#14606)

Co-authored-by: Miguel Solorio <miguelsolorio@google.com>
Co-authored-by: gemini-cli-robot <gemini-cli-robot@google.com>
Co-authored-by: joshualitt <joshualitt@google.com>
Co-authored-by: Sehoon Shon <sshon@google.com>
Co-authored-by: Adam Weidman <65992621+adamfweidman@users.noreply.github.com>
Co-authored-by: Adib234 <30782825+Adib234@users.noreply.github.com>
Co-authored-by: Jenna Inouye <jinouye@google.com>
…und (#15218)

Co-authored-by: sgeraldes <sgeraldes@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Prof-Harita and others added 22 commits January 17, 2026 18:10
- confirmation-policy.test.ts: 15s → 60s timeout
- coreToolScheduler.test.ts: 20s → 60s timeout
- clipboardUtils.test.ts: skip clipboard tests on Windows CI
- gemini.test.tsx: 30s → 90s timeout
- scripts/lint.js: Windows-compatible yamllint installation

Root cause: Windows process spawning (PowerShell, cmd.exe) is
~10x slower than Linux. Clipboard operations hang in headless CI.
- Fix browser launch blocking on Linux (spawn + unref)
- Fix credential import token reuse (reset lastRefresh)
- Fix Redirect URI mismatch (decouple binding to 127.0.0.1 from public localhost)
- Add standalone browser launch test script
This commit adds the detailed architectural specification for the
Sovereign Runtime, including the three-tiered execution strategy
(Sovereign Sandbox, Managed Host Shim, Embedded Runtime) and the
design for the T-APTS (TerminAI Python Tool Set) library.

This addresses the reliability issues identified in recent crashes
where host execution failed due to missing dependencies.
@google-labs-jules
Copy link
Contributor Author

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.


For security, I will only act on instructions from the user who triggered this task.

@github-actions
Copy link

🤖 Hi @google-labs-jules[bot], I've received your request, and I'm working on it now! You can track my progress in the logs for more details.

Copy link

@github-actions github-actions bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📋 Review Summary

This pull request introduces a comprehensive architectural document for the Sovereign Runtime, outlining a robust multi-tiered execution strategy. The document effectively addresses critical challenges related to user experience, environment management, and security, providing a clear roadmap for implementation.

🔍 General Feedback

  • The document is well-structured and provides a clear rationale for the proposed architecture.
  • The risk analysis and mitigation strategies are thoughtfully detailed.
  • The breakdown of implementation phases is helpful for understanding the project's complexity and timeline.


---

## 1. Why

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Consistency: Consider using a consistent term for "non-technical users" throughout the document. "Laymen" is used in the goal statement, while "Layman" is used as a singular noun for the Tier 2 description.

* `getPythonExecutable()`: Returns the path to the correct python binary (Docker path or Local Venv path).

---

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Clarity: In Tier 2's bootstrapping mechanism, it mentions checking for system python3 (or python). While Risk 4 clarifies that Python 3.11+ is required, it would enhance immediate clarity to explicitly mention the 3.11+ requirement when describing the initial check for python3 or python in Tier 2.

### Risk 3: Connectivity & Pip Failures
* **Risk:** The user is offline or behind a firewall during the first run of Tier 2, preventing `pip install terminai-apts`.
* **Mitigation:**
* **Graceful Failure:** Catch `pip` errors and return a human-readable error: "Internet connection required for initial setup."

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Minor: For consistency and clarity, explicitly add the .py extension when referring to cleanup.py in the terminai_apts.action structure, as it's a file.

This commit updates the Sovereign Runtime Architecture specification
to explicitly address cross-platform compatibility, specifically
detailing the difference between the "Lunchbox" (Sandbox) and
"Home Kitchen" (Managed Host Shim) execution models.

It adds an ELI5 summary and an OS Compatibility Matrix to ensure
clarity on how Windows and non-Docker environments are handled.
This commit updates the Sovereign Runtime Architecture specification
to formalize the "Lean Core + Dynamic Expansion" philosophy. It
addresses the question of whether to pre-install all tools or
allow on-demand installation.

Key additions:
-   Section 7: Philosophy: Core Environment vs. Dynamic Capabilities.
-   Defined the "Core Environment" (Python, T-APTS, Package Managers).
-   Defined "Dynamic Capabilities" (Agent-driven, Just-in-Time installation).
-   Outlined guardrails for dynamic builds (Ephemeral in Docker, User-Scoped on Host).
This commit refines the "Core Environment" definition in the
Sovereign Runtime Architecture specification. It explicitly lists
the "System Primitives" (Network, Archive, Process, Privilege)
that are required for the agent to bootstrap dynamic capabilities.

This ensures that the "Lean Core" philosophy provides a sufficient
foundation for the agent to survive and build upon, addressing the
need for reliable operations beyond software development tasks.
This commit adds the "Technical Architecture Implementation" section
to the Sovereign Runtime Architecture specification. It provides the
detailed blueprints for implementation, including:

1.  **Data Flow Diagrams (Mermaid):** Visualizing the current crash,
    the container-only fix, and the final multi-tier solution.
2.  **Component Design:** Specifications for `SandboxManager`,
    `RuntimeSession` interface, and concrete runtimes.
3.  **Bootstrapping Sequence:** The exact flow for the Tier 2 Host Shim.
4.  **File Structure:** The required layout for new core components.

This completes the architectural specification required for the
engineering team to begin implementation.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.