Metadata-Version: 2.4
Name: te2
Version: 0.2.338
Summary: TE2 framework runtime and tooling
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi
Requires-Dist: starlette
Requires-Dist: uvicorn
Requires-Dist: websockets
Requires-Dist: httpx
Requires-Dist: msgspec>=0.21.1
Requires-Dist: anyio
Requires-Dist: fastmcp
Requires-Dist: framework-shells==0.0.63
Requires-Dist: agent-log-server==0.2.119
Requires-Dist: nodejs-wheel==24.16.0; sys_platform == "linux" and platform_machine == "x86_64"
Requires-Dist: libarchive-c>=5.1
Requires-Dist: python-socketio[asyncio-client,client]
Requires-Dist: pyyaml
Dynamic: license-file

# Termux Extensions 2 

> It won't make you a professional programmer... but it'll make you feel like one.
---

TE2 is a local development workspace that runs the same project environment on
Linux desktops and in Termux. Its framework launches isolated apps, owns shell
and process orchestration, and provides shared filesystem, Git, search, state,
proxy, console, and debugging services.

Code TE2 is the flagship workspace app: a Monaco-based editor with an Explorer,
terminal surfaces, language tooling through code-server, diagnostics, drafts,
diff/review flows, and stateful sidebar apps.

## Architecture

TE2 is Rust-first. Python remains a support and app-backend language, not the
framework authority.

```text
te2
  -> Python bootstrap locator
  -> fingerprinted Rust framework binary
       -> Ferrous / Framework-Shells process orchestration
       -> Rust filesystem, Git, search, state, app, and proxy services
       -> Python runtime bridge for TE2 console and MCP
       -> per-app Python/Node/native workers
```

The supported Rust framework source lives under `framework/`.

Important roots:

- `framework/rust/` — Rust framework workspace
- `framework/bootstrap/bootstrap.py` — cached build and launch bootstrap
- `app/apps/` — built-in TE2 apps
- `app/static/` and `app/templates/` — framework-served assets
- `app/te2_mcp/` and `app/te2_console_runtime.py` — runtime observability bridge
- `~/.local/share/te2/apps/` — user-local apps and proxy wrappers

## Included Apps

- `code_te2` — Code TE2, the primary workspace/editor app
- `terminal` — standalone Node PTY terminal with reconnect checkpoints
- `file_explorer` — standalone file browser
- `archive_manager` — archive browsing and extraction
- `aria_downloader` — aria2 download surface
- `settings` — framework settings and diagnostics
- `als-rs` — tracked ALS-RS proxy wrapper
- `file_editor` — older lightweight editor app retained separately from Code TE2

Integration depth varies by app. The app catalog is defined by the manifests
under `app/apps/*/manifest.json`; there is no built-in `codex_agent` app.

## Requirements

TE2's Python runtime requires Python 3.12 or newer. On the supported x86-64
Debian/Ubuntu Linux alpha, install `build-essential` before launching the
standalone Terminal: its first launch compiles the locked `node-pty` module,
then installs that module and the headless xterm modules into TE2's private data
root for the current Node ABI. TE2's Linux Python dependency supplies the exact
Node.js/npm runtime and matching headers, so a separate global Node.js install
is not required. Archive Manager additionally needs the platform `libarchive`
shared library.

The checked-in Code TE2 frontend, WBA backend, and shared browser assets are
already built or vendored; ordinary runtime does not install npm dependency
trees for them. The final archive-based Linux release will carry a prebuilt
Electron distribution. A source, editable, or Git/pip install instead carries
the small locked Electron source tree and builds it only when the user runs
`te2 desktop install` or first launches `te2-desktop`.

A source or Git/pip install also needs Rust with Cargo because the launcher
builds and caches the framework server. Building the optional desktop client
from that install requires a glibc Linux x86-64 host plus Node.js 22.12 or newer
and npm; its locked dependency and Electron downloads remain in the TE2 cache.
Outside that explicit desktop build and the Terminal's private first-use
runtime bootstrap, npm is development-only when regenerating checked-in
artifacts. No global npm application package is required. Git is needed to
clone the repository or resolve a Git dependency, but the running framework's
Git implementation is Rust/libgit2 owned.

Some source integrations invoke external tools:

- `aria2c` enables the Aria Downloader worker;
- `watchexec` enables Code TE2's optional polling watcher; and
- C/C++ compiler commands enable Code TE2's direct C/C++ Run action.

For installed releases, each retained integration is supplied through the
unified installer's validated Linux or Termux prerequisite manifest, or removed
from the product. Users are not sent to repository construction scripts for
dependency setup.

Code TE2 can use its built-in Monaco language workers without Code Server.
VS Code extension-host integration uses Code TE2's confirmation-gated pinned
private Code Server runtime; no global Code Server installation is supported.
The managed Code Server Linux standalone bootstrap may require `curl` or `wget`
when the user opts in. Its Termux path downloads the pinned package with Python
and installs the exact package dependencies at that time.

The planned installed release uses one autodetecting `install-te2` entrypoint
with target-specific, checksummed tar/gzip archives. Detection checks Termux
first, then supports an initial apt-based glibc Linux target. An explicit local
payload or matching archive beside the installer supports offline application
payload installation; otherwise the installer downloads the immutable release
archive. Unsupported libc implementations, package managers, architectures,
and platforms fail explicitly.

Linux installs beneath the canonical TE2 data root with a private Python venv
and prebuilt Rust/Electron payloads; apt is limited to system prerequisites.
Termux reuses its shared Python interpreter and apt-supplied dependencies
without a venv, while TE2's own Python tree and Bionic server remain versioned
beneath the canonical TE2 data root. Both targets share manifest verification,
receipts, atomic current-release activation, upgrade/rollback, and removal.

Repository scripts are developer/release construction tooling and may build the
public installer and target archives. They are not copied into an ordinary
install or exposed as user installation entrypoints; users see them only in a
cloned or editable source checkout.

## Install And Run

For the supported x86-64 Debian/Ubuntu Linux alpha from PyPI:

```bash
sudo apt-get update
sudo apt-get install -y build-essential
python -m venv ~/.local/share/te2-alpha-venv
. ~/.local/share/te2-alpha-venv/bin/activate
python -m pip install "te2==0.2.338"
te2
```

`build-essential` supplies the compiler and `make` needed by the Terminal's
first-use `node-pty` build. It is a system prerequisite, not part of TE2's
Python environment.

For a source checkout:

```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .
te2
```

For a package install directly from Git:

```bash
python -m pip install "te2 @ git+https://github.com/mrsurge/termux-extensions-2.git"
te2
```

On supported Linux desktops, the same source/Git install can build and register
the Electron client in the current Python environment:

```bash
te2 desktop install
te2-desktop
```

`te2 desktop status`, `repair`, and `uninstall` inspect, rebuild, or remove the
fingerprinted user-local runtime and receipt-owned XDG integration. The build
requires at least 3 GiB of free disk space; a matching validated runtime is
reused without rebuilding.

Open `http://127.0.0.1:8089`. TE2 binds to localhost by default. Use
`te2 --broadcast all` only when unrestricted network access is intentional.
Prefer a narrower source or interface policy:

```bash
# Machine-readable names, addresses, prefixes, and networks.
te2 --list-interfaces

# Admit traffic whose destination is an address owned by this interface.
# This works for ordinary LAN adapters and /32 VPN adapters such as Tailscale.
te2 --broadcast tailscale0

# Admit only one client address or a client subnet.
te2 --broadcast 100.91.80.45
te2 --broadcast 100.64.0.0/10

# Mixed IPv4/IPv6 selectors are supported.
te2 --broadcast 192.168.1.0/24 fd7a:115c:a1e0::/48
```

Every filtered mode continues to admit loopback. The launcher resolves the
selectors once, opens only the required IPv4/IPv6 wildcard listeners, and
enforces the same policy before HTTP, SSE, raw WebSocket, or Socket.IO routing.
Framework-owned subprocesses continue to receive a loopback
`TE_FRAMEWORK_URL`, even when public listeners use wildcard addresses.

`--host <exact-ip>` remains an advanced bind override. A non-loopback exact
host binds that address plus a private same-family loopback listener; wildcard
host overrides allow all clients. Invalid selectors and interfaces without a
usable IP address fail before the framework binds any socket.

The launcher builds an optimized release server by default; pass `--debug` only
for an unoptimized development server. Cargo incremental artifacts live under
`$TE2_CACHE_HOME/framework/build/cargo-target`, where `$TE2_CACHE_HOME` means
the resolved canonical root described below. Final-binary publication is
locked and atomic, and only the selected validated fingerprint is retained.

Launcher overrides use the canonical `TE2_SERVER_*` namespace:
`TE2_SERVER_HOST`, `TE2_SERVER_PORT`, `TE2_SERVER_CACHE_DIR`,
`TE2_SERVER_BIN`, `TE2_SERVER_CARGO_MANIFEST`, `TE2_SERVER_DEBUG`,
`TE2_SERVER_FORCE_BUILD`, `TE2_SERVER_NO_BUILD_CACHE`, and
`TE2_SERVER_DISABLE_FERROUS_FRAMEWORK`. Bootstrap-to-server values use the same
namespace for bind hosts, internal host, network policy, project/app roots, and
Cargo target selection. The private Python sidecar uses
`TE2_RUNTIME_BRIDGE_HOST`, `TE2_RUNTIME_BRIDGE_PORT`, and
`TE2_RUNTIME_BRIDGE_URL`. Experimental-name environment variables are not read
as compatibility aliases. `TE_PORT` and `TE_FRAMEWORK_URL` remain the stable
cross-component framework contracts.

TE2 path overrides (`TE2_CACHE_HOME`, `TE2_DATA_HOME`, `TE2_CONFIG_HOME`, and
`TE2_RUNTIME_HOME`) name final TE2 roots. Without them, TE2 uses XDG bases when
available, normal `$HOME` fallbacks for cache/data/config, and a protected
runtime directory under `$TMPDIR` or Termux `$PREFIX/tmp`. Normal startup never
uses an old root as a fallback for these migrated caches. Durable framework and
Code TE2 store cutovers are tracked separately.

The first standalone Terminal launch installs its locked production Node
dependencies under `$TE2_DATA_HOME/node_runtime/terminal` (normally
`~/.local/share/te2/node_runtime/terminal` after root resolution). The runtime
is keyed by the lockfile, platform, architecture, and Node ABI, so Python
package installs do not depend on a source-checkout `node_modules` tree.

Useful launcher commands:

```bash
te2 --build-only
te2 --debug
te2 --print-command
te2 --memory-profile "$HOME/.cache/te2-memory-profile"
te2 console list-workers
te2 migrate-legacy-roots          # write-free report
te2 migrate-legacy-roots --json   # write-free structured report
```

`--memory-profile` is an explicit desktop diagnostic mode. It requires a
separately installed Heaptrack, uses an optimized symbolized Rust profile, and
enables explicit Python and Node heap snapshots. It is not a production
allocator mode. See
[the framework memory profiling guide](docs/apps/framework_memory_profiling/README.md)
before running it, especially when the active agent session is hosted by TE2.

Electron stores local launch policy separately at
`$TE2_CONFIG_HOME/desktop-local-framework.json`. When that file is absent,
Settings presents in-memory defaults and an unsaved `te2` PATH detection; the
Linux installer later seeds its exact private-venv and command paths. Source
smokes may still use the higher-priority absolute
`TE2_DESKTOP_TE2_EXECUTABLE` override. The versioned launch record owns the
command, optional venv, broadcast selectors, port, and bounded environment
overrides. An empty broadcast list stays loopback-only. Normal framework
traffic remains on HTTP/Socket.IO/WebSocket/SSE. The bootstrap's
`--stdio-control` mode is a desktop lifecycle channel: stdin accepts versioned
NDJSON control requests, inherited file descriptor 3 returns structured
responses/events, and stdout/stderr remain ordinary logs. Protocol v1 permits
only graceful shutdown; it is not an arbitrary command-execution interface.

Legacy-root recovery is deliberately opt-in. After reviewing the dry-run,
`te2 migrate-legacy-roots --apply` performs the versioned one-time migration
only while the framework is stopped. The allowlisted legacy source is
authoritative: matching canonical files are overwritten, while files that
exist only in a canonical destination tree are retained. Unknown or externally
owned content is reported and left untouched.

`te2-rust` is an alias for the same Rust launcher. `scripts/run_framework.sh`
is a source-checkout helper that also invokes the Rust launcher directly.

Code TE2 does not use a system, `PATH`, NVM, or environment-selected
code-server. Its Code Server mode always uses the pinned private runtime under
`$TE2_DATA_HOME/code_server/4.130.0` and routes process launch, VSIX/Open
VSX management, builtin-extension discovery, and WBA nid extraction through
that exact tree. The Languages & Extensions settings can switch the app to
Monaco language web workers instead; doing so stops the private runtime and
removes only its managed installation while preserving installed extensions.

## Build Code TE2 Frontend

Code TE2 serves generated bundles from `static/dist/`. After changing its
frontend source:

```bash
cd app/apps/code_te2
npm install
npm run typecheck
npm run build
```

The source entrypoints are `main.ts` for the host and
`monaco_editor/m_editor_app.ts` for the editor. Generated bundles are not the
source of truth.

## App Model

Built-in and user-local apps share the same manifest model. An app may provide
frontend assets, an app-worker shellspec, backend routes, semantic readiness,
sidebar state, and proxy-wrapper configuration.

External applications do not need to be rewritten as TE2 internals. A thin
wrapper under `~/.local/share/te2/apps/<app_id>` can launch the real application
through Framework-Shells and expose it through TE2's proxy surface. The wrapped
application remains independently runnable; TE2 is its development harness,
not a hidden product dependency.

## Acknowledgements

TE2 depends on excellent independent open-source projects, including:

- [Cefrium](https://codeberg.org/cefrium/cef-android), which brings CEF to
  Android and powers TE2's Chromium-based Android client. Special thanks to its
  maintainer for the `0.7.1` iframe WebSocket and scheduling-latency fix.
- [Electron](https://www.electronjs.org/), whose Chromium and Node.js runtime
  powers TE2's Linux desktop shell.

## Repository Guidance

[Technical Deep Dive](docs/apps/code_te2/CODE_TE2.md) (for a technical deep dive in how one makes a code/editor dev platform
 with a python script and have it perform as good as a VS-Clone)

GeckoView remains the primary Android client. The isolated `android/cefrium`
application module evaluates the Cefrium CEF runtime without adding Chromium
resources or native libraries to Gecko builds; see
`android/cefrium/README.md` for its build and runtime contract.
