tutti/docs/specs/2026-08-08-windows-agent-runtime-setup-reliability.md

# Windows Agent Runtime Setup Reliability

## Background and goal

Windows Agent installation currently depends on three independent conditions:
the daemon must inherit the same outbound proxy behavior as Desktop, the `uv`
bootstrap download must reach GitHub, and every consumer must select the same
installed agent executable. The goal is to remove the avoidable `uv` network
dependency, make static system-proxy handling symmetric with macOS, and prevent
stale Windows shims from splitting status/login/model/session behavior.

## Current architecture and chain

```text
Desktop -> tuttid -> Target installer -> download uv -> uv installs Python agent
                  -> provider resolver -> PATH/npm shim -> status/login/session
```

- macOS system proxy is converted to process proxy environment; Windows only
  receives explicit environment variables.
- `uv` is pinned and verified, but downloaded dynamically on first use.
- OpenCode installation may produce a complete managed npm package while an
  older PATH shim remains visible to some consumers.
- Kimi versions before `0.34.0` can initialize ACP yet reject API-key
  `session/new` as unauthenticated.

## Target architecture and chain

```text
Desktop package
  -> inject packaged uv archive root
  -> tuttid verifies cache or packaged archive; download only when absent
  -> uv installs the pinned Python agent dynamically

OS proxy adapter -> shared merge/cache -> daemon HTTP + every child process

provider resolver -> one absolute executable
                  -> status + login + model catalog + ACP session
```

## Repository and module changes

| Repository/module | Change |
| --- | --- |
| `tutti` Desktop packaging | Stage one official compressed `uv` archive per packaged architecture; inject `TUTTI_BUNDLED_UV_ROOT`. |
| `tutti` agent extension service | Verify size/SHA, safely extract packaged `uv`, keep verified cache and network fallback. |
| `tutti` runtime command | Split native proxy reads into Darwin/Windows/other build-tagged files; keep merge policy shared. |
| `tutti` agent status | Resolve a complete managed npm binary once and reuse it across OpenCode consumers. |
| Kimi extension | Pin install to `0.34.0`, require local `>=0.34.0 <1.0.0`, and verify API-key `session/new`. |
| Hermes extension | Document that the host owns `uv`; keep Hermes/Python installation dynamic and the package declarative. |

No public HTTP API or persisted-data schema is added. The only new interface is
the internal Desktop-to-daemon environment variable `TUTTI_BUNDLED_UV_ROOT`.

## Reuse and adapter boundary

Proxy precedence, bypass normalization, caching, child-process injection, and
HTTP transport behavior remain shared. Native adapters only read OS settings.
The existing UV artifact catalog, checksum, safe archive extraction, and
verified cache are reused; Desktop owns resource layout, while tuttid never
depends on Electron paths directly.

## Explicitly out of scope

- Bundling Node, Python, Kimi, Hermes, OpenCode, or their dependency graphs.
- Executing Windows PAC scripts or translating SOCKS proxies.
- Changing user credentials or publishing managed agent commands globally.
- Adding a new public service/API or migrating persisted records.

## Migration and compatibility

There is no data migration. Existing verified UV caches continue to win. A
package without the new resource uses the existing signed dynamic download.
Explicit proxy environment variables and `TUTTI_DISABLE_PROXY_AUTODETECT`
retain precedence. Kimi installations below `0.34.0` are not reused; the Target
installer creates/updates its isolated pinned runtime without overwriting the
user's global Kimi installation.

## Risk and rollback

- Package size grows by about 22–26 MiB compressed per shipped architecture.
  Production architecture-specific builds stage one archive; the local
  `MAC_ARCH=all` convenience build stages both Darwin archives into every
  artifact produced by that combined invocation.
- Native proxy state can be stale for at most the existing 60-second cache TTL.
- A corrupt packaged UV archive is never executed; tuttid falls back to the
  same checksum-verified official download and reports both causes if that
  download also fails.

Rollback is a normal code/package rollback: remove the Desktop resource and
environment injection to restore dynamic UV download; revert the Windows
adapter to restore explicit-env-only proxy behavior; revert the Kimi pin if the
upstream runtime regresses. No database rollback is required.

## Tests and acceptance

- Parser/precedence tests cover macOS and Windows proxy forms, bypasses, SOCKS
  rejection, and explicit-env priority; Windows and Darwin files compile.
- UV tests prove a verified bundle performs zero network requests and corrupt
  bundles are rejected; release staging verifies the real official archive.
- OpenCode tests plant a stale shim plus complete managed package and require
  the managed absolute command.
- Kimi tests require pinned version, API-key ACP `session/new`, commands, and
  Skill discovery.
- Packaged Windows acceptance blocks GitHub UV downloads, installs Hermes, and
  completes ACP initialize/session creation through the configured package
  index.

## Phased order

1. Land host proxy, bundled UV, and OpenCode resolution with compatibility
   fallback.
2. Land Kimi minimum-version/package pin and its ACP regression test.
3. Land Hermes host-contract documentation and run packaged Windows acceptance.
4. Monitor integrity/proxy diagnostics; promote Windows packaging only through
   its existing release gates.

## Pending confirmation

- Whether PAC support is required for managed enterprise Windows deployments.
- Final installer-size budget and whether universal macOS packages may include
  both architecture archives.