Pentect roadmap: researched remaining work

# Pentect roadmap This is the single source of truth for unfinished Pentect work. It was audited against the repository, published packages, release evidence, and current official product documentation on **2026-08-11**. Do not create a second roadmap or support matrix. Focused implementation issues or PRs may link back here, but status lives here. ## Status - ✅ released and covered by compatibility evidence - 🟡 implemented, but authenticated or signed-GUI evidence is incomplete - ⬜ planned through a documented integration boundary - 🔬 research required; do not promise support yet - — not applicable ## Rules that apply to every integration - A product is not “supported” when only one of its CLI, app, editor, completion, remote, or cloud surfaces is protected. - A normal `HTTP_PROXY` does not expose HTTPS request bodies and is not a masking integration. - Cloud Code and native Gemini are different protocols. - “OpenAI-compatible” does not guarantee compatible tools, streaming, Files, or Responses behavior. - A local loopback gateway does not protect a remote extension host, background agent, or cloud task. - Undocumented endpoint overrides and global TLS interception are not stable default integrations. - Unknown content on a declared AI route remains blocked by default. Unrelated login, update, marketplace, telemetry, and non-AI traffic passes through unchanged. ## Released foundations - [x] Install, versioned update, uninstall, and package-manager automation - [x] OpenAI Responses, OpenAI Chat Completions, Anthropic Messages, and Cloud Code gateways - [x] Codex CLI and Claude Code launchers - [x] Codex App and Claude Desktop scoped launchers - [x] OpenCode and Antigravity CLI launchers, plus the native `@pentect/pi` provider extension - [x] Custom/local upstream routing, including Bifrost-compatible paths - [x] Files API, inline image/PDF, OCR, and remote-reference handling for supported content - [x] Unknown-format policy with an explicit compatibility override - [x] WebAssembly plugin runtime, Rust SDK, registry, publisher verification, approval, and network broker - [x] Versioned compatibility evidence and provider-boundary CI
- [x] One shared opaque-handle contract across OpenAI, Anthropic, Gemini, Cloud Code, Claude App, and Pi-backed requests --- ## 1. Shared client and protocol architecture Every client must use one shared gateway runtime. Client launch logic and protocol transformation are separate adapters. ### Gateway runtime owns - listener lifecycle and upstream forwarding; - HTTP/1.1, HTTP/2, SSE, streaming, cancellation, and retries; - request masking and response transformation; - files, images, screenshots, OCR, remote references, and limits; - handle storage and restoration only at a recognized local tool boundary; - plugins, logs, policy, upstream authentication, and unrelated-traffic passthrough. ### Client descriptor owns - executable and aliases; - surface: CLI, desktop, editor, extension, or remote; - endpoint injection method and original-upstream discovery; - protocol adapter and authentication forwarding; - temporary configuration lifecycle; - supported feature set and remote behavior. It never stores a secret value. ### Protocol adapter owns - recognizing declared request, response, error, and stream envelopes; - decoding them into shared message/tool/file representations; - encoding transformed content back into the original protocol; - recognizing completed tool calls without restoring ordinary model text. ### Foundation work - [ ] Extract one gateway lifecycle and transport layer from the current product-specific proxies. - [x] Define data-driven client descriptors for the current launchers. - [ ] Extract protocol-adapter interfaces and shared message/tool representations. - [ ] Define shared representations for messages, tool calls, completion prefix/suffix, and indexed chunks. - [ ] Reuse OpenAI Responses/Chat and Anthropic adapters; keep Cloud Code and native Gemini separate. - [ ] Add adapter conformance fixtures, fragmented-stream tests, and public compatibility generation. - [ ] Detect upstream schema and route changes in CI. - [ ] Show unsupported surfaces before launch. - [ ] Migrate existing clients without changing their current behavior. --- ## 2. Client and editor support ### Verified current paths | Surface | Status | Injection path | Protocol | Important remaining evidence | | --- | ---: | --- | --- | --- | | Codex CLI | ✅ | temporary Codex provider | OpenAI Responses | current schema, custom provider, auth variants | | Codex App local thread | 🟡 | scoped App provider | OpenAI Responses | signed App E2E; cloud task is separate | | Claude Code | ✅ | `ANTHROPIC_BASE_URL` + temporary settings | Anthropic Messages | managed settings and auth variants | | Claude Desktop Chat/Cowork/Code | 🟡 | scoped desktop proxy | Anthropic/OpenAI surfaces | verify each surface independently | | OpenCode CLI | ✅ | temporary `OPENCODE_CONFIG_CONTENT` provider | Chat/Responses | background/small model and schema drift | | Pi CLI | ✅ | published `@pentect/pi` JS provider extension | Chat/Responses | dynamic model metadata, images/reasoning, and other API types | | Antigravity CLI (`agy`) | 🟡 | observed `CLOUD_CODE_URL` override | Cloud Code `v1internal` | real CLI startup and mocked Cloud Code E2E pass; real Google-account live E2E and SSH remain unverified | | Antigravity IDE | 🔬 | not verified | unknown | treat separately from `agy` | ### Existing-client follow-up - [ ] Codex: test `openai_base_url`, custom `model_providers`, API key, ChatGPT login, command-backed auth, and AWS provider separately. - [ ] Codex App: distinguish local threads from remote/cloud tasks; track Responses, Files, images, SSE, and future WebSocket use. - [ ] Claude: continue Anthropic gateway E2E; design Bedrock, Vertex, Foundry, and Mantle as separate authenticated transports rather than silently forwarding them. - [ ] Claude Desktop: capture Chat, Cowork, and Code traffic separately. - [ ] OpenCode: fixture Chat/Responses tools and SSE; confirm background/small-model calls also use Pentect. #### Pi v0.0.29-v0.0.30 release corrections

Released in [v0.0.29](https://github.com/EdamAme-x/pentect/releases/tag/v0.0.29) through [#230](https://github.com/EdamAme-x/pentect/pull/230). Additional compatibility fixes were released in [v0.0.30](https://github.com/EdamAme-x/pentect/releases/tag/v0.0.30) through [#232](https://github.com/EdamAme-x/pentect/pull/232).

- [x] Publish `@pentect/pi` as a native Pi extension through `pi.extensions`, without the obsolete bundled launcher or Pi runtime dependency.
- [x] Pin the matching published `pentect` package and launch its downloaded release binary.
- [x] Inject the same handle-use contract as the other gateways, and only when masking produced a handle.
- [x] Run release E2E against the published backend, the published extension, and Pi's real extension/model loader.
- [x] Accept native Pi/OpenAI wire API aliases and restore original provider credentials after startup or registration failure.
- [x] Allow validated context-window, output-token, input-type, and reasoning overrides for custom models; invalid values stop startup.
- [x] Gate releases against Pi 0.84.1 and current Codex, Claude Code, and OpenCode versions.
- [ ] Discover selected-model metadata automatically where the upstream exposes it, and add per-API fixtures for tool results, images, and reasoning events. - [ ] Antigravity: run an authenticated live E2E with a real Google account and verify that the provider receives handles and function calls restore locally. Current evidence covers real CLI installation/startup and mocked Cloud Code traffic only.\n- [ ] Antigravity: capture every supported `v1internal` route per release, distinguish model traffic from OAuth/control/telemetry, and test with Pentect installed on the SSH host. ### High-confidence new integrations

Released in [v0.0.28](https://github.com/EdamAme-x/pentect/releases/tag/v0.0.28). Provider-boundary E2E covers OpenAI-compatible, native Gemini, and the VS Code provider path; release CI also launches pinned Continue CLI 1.5.47, Cline CLI 3.0.52, and Gemini CLI 0.54.4.
These products document a usable endpoint/provider boundary. - [x] **Aider (OpenAI-compatible)** — process-local gateway with main, weak, and editor models pinned to Pentect. - [ ] **Aider native Anthropic and other providers** — add separate adapters only after authenticated protocol fixtures. - [x] **Continue** — use `apiBase`; track chat, autocomplete, embed, and rerank roles independently. - [x] **[Cline](https://cline.bot/)** — generate a temporary OpenAI-compatible provider profile; test streaming tool arguments, images, MCP results, and resumed conversations. - [x] **Roo Code** — OpenAI-compatible native tool calls; test incremental arguments and preserve tool-call IDs; CLI and extension are separate. - [x] **Zed** — `api_url` for Chat/Responses; test Agent, Inline Assistant, utility calls, and delegate External Agents to their own adapters. - [x] **Junie CLI** — temporary model profile via `--model-location`; route both primary and faster models; test OpenAI, Responses, Anthropic, and Google separately. - [x] **VS Code** — implement a `LanguageModelChatProvider` extension rather than permanently rewriting settings; test chat, local agent, inline chat, tools/MCP, images, and utility calls. - [x] **Goose CLI/Desktop** — temporary OpenAI/Anthropic provider configuration; do not persist the upstream key in Goose’s keychain. - [x] **Gemini CLI** — add a native Gemini adapter for `generateContent`, `streamGenerateContent`, `countTokens`, functions, and inline/file data; test API key, Vertex auth, and Code Assist OAuth separately. ### Research-only surfaces Do not advertise these until a documented interception boundary and authenticated E2E exist. - [ ] **Cursor local Agent** 🔬 — official BYOK does not prove a stable local base-URL override. - [ ] **Cursor Tab** 🔬 — uses Cursor’s built-in model rather than BYOK. - [ ] **Cursor Background Agents** 🔬 — run in remote VMs and need a remote gateway. - [ ] **Windsurf Cascade** 🔬 — no verified arbitrary base URL. - [ ] **Windsurf Tab** 🔬 — separate proprietary model path. - [ ] **Kiro** 🔬 — documented `HTTP_PROXY` support alone cannot transform TLS payloads. - [ ] **Junie IDE plugin** 🔬 — custom BYOK profiles are documented for CLI, not the IDE plugin. - [ ] **VS Code inline suggestions, embeddings, and cloud agents** 🔬 — not covered by its normal custom chat endpoint. - [ ] **Antigravity IDE** 🔬 — do not infer its behavior from `agy`. ### Completion, indexing, and remote execution - [ ] Give completion its own latency, allocation, debounce, cancellation, cache, and partial-response budgets. - [ ] Never restore a handle into generated source code. - [ ] Test overlapping chunks, renamed/deleted files, generated/binary files, and secret rotation. - [ ] Define local-only, remote-installed, and remotely reachable gateway modes. - [ ] Never expose the current loopback token endpoint as a remote service. - [ ] Add mutual authentication, upstream allowlists, session/project/machine scope, expiry, and two-host synthetic-secret E2E before remote support. - [ ] Never silently fall back to an unprotected provider connection. A matrix entry becomes ✅ only when the exact client version and surface are named; sanitized success/error/cancellation/stream fixtures exist; the provider sees a handle; restoration is limited to a recognized local tool field; unrelated traffic is untouched; and the result is published as release evidence. --- ## 3. Plugin system ### Already implemented - [x] WebAssembly-only untrusted runtime using `wasmi`, without WASI, filesystem, environment, process, or raw-socket access - [x] Declarative regex-only `plugin.toml` - [x] Ordered `prepare`, `inspect`, `finalize`, `request`, `response`, `tool_call`, and `file` hooks - [x] Continue-by-return and explicit block/respond behavior - [x] Published Rust SDK and first-party examples - [x] Per-plugin fuel, memory, input/output, finding, HTTP, origin, method, DNS, and address limits - [x] Host-mediated network broker with exact origins, redirect denial, DNS pinning, and private/insecure opt-in - [x] Approval bound to manifest hash and actual exported hooks - [x] Binary digest lock and GitHub artifact-attestation verification - [x] OpenAI Privacy Filter loopback sidecar example ### Runtime hardening - [x] Configure strict `wasmi::EnforcedLimits` and bounded store growth. - [ ] Separate the documented execution budget from the current fuel-derived `timeout_ms`; decide whether a true wall-clock hard stop requires a worker process or another runtime. - [x] Add request-wide plugin-chain deadline and aggregate input/output/finding/network budgets. - [x] Limit plugin cache total bytes and entries, with cleanup ([#229](https://github.com/EdamAme-x/pentect/pull/229)). - [ ] Add malicious-Wasm fuzz fixtures for huge sections, imports/exports, tables, memory growth, infinite loops, host-call spam, and invalid pointers. - [ ] Keep SSRF tests for DNS rebinding, IPv4-mapped IPv6, credential URLs, redirects, proxy env, Host/Content-Length, and response/header bombs. ### SDK and API - [ ] Freeze the core ABI v1 contract and publish host/SDK compatibility fixtures. - [ ] Keep the low-cognitive-load `Context + return to continue + explicit early return` model. Do not add Hono-style onion `next()` until a real before/after use case requires it. - [ ] Add concise finding builders and typed error codes. - [ ] Experiment with a language-neutral WIT/Component Model v2 without replacing v1 yet. - [ ] Evaluate TypeScript, Go, and Python SDKs only after the toolchain and ABI are stable. - [ ] If plugins inspect file bytes, expose a bounded stream/blob handle—not filesystem access. - [ ] Let a manifest declare the config key names it reads; show names, never values, during setup. ### Supply chain and updates - [x] Pin remote plugins by exact content digest in `pentect.plugins.lock`; only full commit SHAs may run without a project lock. - [x] Show value-free detector/label/category/confidence diffs before regex updates. - [ ] Bind approval canonically to source identity, version, manifest digest, artifact digest, hooks, and requested access. - [ ] Reapprove permission expansion; define behavior for reductions and same-permission binary updates. - [x] Implement tag/full-commit sources, concurrent-safe project lockfiles, and atomic rollback. - [ ] Add registry yank and deprecation behavior. - [ ] Bind artifact, manifest, and SBOM to one release/provenance record. - [ ] Add registry version, digest, publisher, license, security contact, API range, yank, and deprecation metadata. ### Local-model bridge - [ ] Generalize the privacy-filter sidecar recipe for a user-started loopback OpenAI-compatible/Ollama/llama.cpp service. - [ ] Add health checks, typed span results, limits, and fake-data E2E. - [ ] Never give plugins process execution, arbitrary environment, or filesystem access to launch the model. - [ ] Prototype a host-brokered `model.inspect` import using a model alias and explicit task/input/output/time budgets without exposing endpoint credentials. - [ ] Decide whether model access remains loopback-only; default to local-only while the plugin can receive full text. ### Decisions intentionally deferred - Do not migrate wholesale to Wasmtime/Component Model yet. Harden current `wasmi` and run an experimental typed-ABI PoC first. - Do not add onion middleware solely to resemble Hono. - Decide separately whether every binary version requires approval even when permissions are unchanged. --- ## 4. Public CLI cleanup ### Already implemented - [x] Normal client arguments pass through without requiring `--` - [x] Persistent CLI defaults and desktop launchers - [x] Diagnostics live in `pentect log` - [x] Internal commands are omitted from normal help ### Remaining - [x] Classify every builtin command as public, advanced, or internal; exclude internal commands from normal help. - [x] Keep `mask` and `read` separate because `read` records path-aware recovery metadata; document the distinction. - [x] Mark `resolve` advanced because it restores plaintext to files; keep `exec` as the standard tool path. - [x] Generate normal help from one command catalog and snapshot the public command set. - [ ] Add release snapshots for exit codes, stdout/stderr, docs, and shell completion. - [x] Keep argv passthrough regression tests before deleting aliases or wrappers. --- ## 5. Approval engine Design and implementation are intentionally deferred to #221. No approval-engine code is part of the current implementation batch. --- ## 6. Signed team policy Current user/project TOML merging is local and unsigned. Project policy may strengthen some protections but may not enable `unknown_formats=ignore`. - [x] Define and validate a signed Phase 1 schema with team policy precedence over project and user settings. - [ ] Explain the effective policy without exposing sensitive configuration. - [x] Define a canonical Ed25519 envelope containing schema, issuer, sequence, issue/expiry time, payload digest, and payload. - [x] Pin issuer and trust root only in the user config, never in repository policy. - [x] Add protected atomic last-known-good cache, expiry, sequence rollback/equivocation rejection, and trust-root-scoped reset. - [ ] Design managed key rotation and revocation. - [x] Start with a small Ed25519-signed local bundle. - [ ] Add authenticated HTTPS distribution after the rotation model is defined. - [ ] Evaluate TUF only when delegated roles/update infrastructure are needed, and Sigstore bundles only when CI identity is a required trust root. The key distribution and rotation model must be decided before implementation. --- ## 7. Files and large payloads ### Already implemented - [x] OpenAI/Anthropic multipart upload inspection - [x] UTF-8 rewrite, image OCR/reconstruction, and unknown-binary blocking - [x] OpenAI file-content retrieval and reinspection for unknown file IDs - [x] Bounded HTTPS remote fetch with public-IP and redirect checks - [x] Anthropic inline PDF text extraction and blocking when a safe reconstruction is unavailable ### Remaining - [x] Persist MAC-bound OpenAI/Anthropic/Claude App upload coverage by provider, upstream/service, keyed account scope, file ID, and TTL. - [ ] Add sanitizer digest/version if future re-upload or provenance workflows require it. - [ ] Do not plan to redownload old Anthropic uploads: its Files API marks uploaded files non-downloadable. Store encrypted sanitized bytes with TTL only when re-upload is truly required. - [ ] Fixture OpenAI file-content auth scope, content length, streaming limits, and MIME sniffing. - [ ] Implement PDF/Office content disarm and reconstruction rather than partial in-place editing. - [ ] MVP: rebuild PDF from sanitized text/page rasters; convert DOCX/PPTX/XLSX in a sandbox to sanitized PDF or plain text. - [ ] Drop macros, OLE/embedded files, actions, forms, comments, revisions, metadata, and signatures; rescan generated output and block if anything remains. - [ ] Replace full-body multipart collection with a streaming parser and encrypted temporary spool above a threshold. - [x] Enforce request-wide remote bytes/items and multipart bytes/parts/files/header/field/output limits. - [ ] Add inflate-ratio, time, and encrypted disk-spool quotas with the streaming parser. - [ ] Keep spool keys only in process memory, use unique nonces and AEAD chunks, clean stale ciphertext on startup, and never forward content before required inspection completes. LibreOffice and document parsers must run in a sandbox; normalization alone is not CDR. --- ## 8. Documentation and onboarding ### Already implemented - [x] Short README pointing to the website - [x] Install, Quick Start, clients, files/images, security, plugins, CLI, config, and examples - [x] Prompt paste, accidental tool output, MCP/browser-created credentials, screenshots/OCR, Files, and remote URLs - [x] Agent-readable `/index.md` generation without generator notes ### Remaining - [x] Publish a short root `AGENTS.md` and website copy covering protected launch, opaque handles, local tool use, blocks, logs, and doctor. - [ ] Generate the compatibility table from fixtures/release evidence with separate chat/tool/file/image/completion/remote columns. - [ ] Add the remote trust model and unsupported-surface explanations. - [ ] Add CLI-help snapshots, code-sample smoke tests, and generated Markdown URL validation to docs CI. - [ ] Keep user-facing English short and readable; remove duplicated or stale explanations rather than adding warnings everywhere. --- ## 9. Hermes and OpenClaw Do not embed either project. Both appear suitable for configuration-first adapters, but neither is supported until authenticated E2E exists. - [ ] **OpenClaw** 🔬 — test its documented OpenAI Chat, Responses, and Anthropic custom providers against existing Pentect adapters. - [ ] Keep OpenClaw’s native Codex runtime separate from its own custom-provider agent loop. - [ ] **Hermes** 🔬 — point its documented `OPENAI_BASE_URL` provider path at Pentect; begin with Chat Completions prompt/tool traffic. - [ ] Do not confuse Hermes’s API server (client-facing) with Hermes-to-model traffic (the boundary Pentect must protect). - [ ] Preserve existing config atomically and restore it after child exit. - [ ] Test tools, MCP/browser output, streaming, errors, retries, cancellation, and synthetic secrets. - [ ] Research a managed local gateway for background messaging/cron that outlives a one-shot child. - [ ] Install Pentect beside a VPS/Docker/SSH-originating agent rather than pulling secret traffic back to a laptop. --- ## Recommended implementation order 1. Shared client descriptor and protocol adapter foundation. 2. Existing-client migration and compatibility regression. 3. Aider, Continue, Cline/Roo, and Zed. 4. Junie CLI, VS Code extension, Goose, and native Gemini CLI. 5. Plugin resource/supply-chain hardening. 6. Deferred approval and team-policy design issues. 7. Anthropic file attestations and encrypted streaming spool. 8. PDF/Office CDR. 9. Remote gateway design. 10. Research-only proprietary/editor surfaces. ## Primary sources ### Clients - [Codex configuration schema](https://github.com/openai/codex/blob/main/codex-rs/core/config.schema.json) - [Claude Code LLM gateways](https://docs.anthropic.com/en/docs/claude-code/llm-gateway) - [OpenCode providers](https://opencode.ai/docs/providers) - [Pi custom providers](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/custom-provider.md) - [Antigravity CLI](https://github.com/google-antigravity/antigravity-cli) - [VS Code custom language models](https://code.visualstudio.com/docs/agent-customization/language-models) - [Continue configuration](https://docs.continue.dev/reference) - [Cline OpenAI-compatible provider](https://docs.cline.bot/provider-config/openai-compatible) - [Roo Code OpenAI-compatible provider](https://roocodeinc.github.io/Roo-Code/providers/openai-compatible/) - [Zed gateways](https://zed.dev/docs/ai/use-a-gateway) - [Aider OpenAI-compatible APIs](https://aider.chat/docs/llms/openai-compat.html) - [Goose providers](https://github.com/block/goose/blob/main/documentation/docs/getting-started/providers.md) - [Junie custom models](https://junie.jetbrains.com/docs/custom-llm-models.html) - [Gemini CLI configuration](https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md) - [Cursor API keys](https://docs.cursor.com/settings/api-keys) - [Windsurf models and BYOK](https://docs.windsurf.com/es/windsurf/models) - [Kiro firewall and proxy settings](https://kiro.dev/docs/privacy-and-security/firewalls/) ### Plugins and policy - [Hono middleware](https://hono.dev/docs/guides/middleware) - [WASI capability model](https://github.com/WebAssembly/WASI/blob/main/docs/Capabilities.md) - [WebAssembly Component Model and WIT](https://component-model.bytecodealliance.org/design/wit.html) - [Component Model 1.0 roadmap](https://bytecodealliance.org/articles/the-road-to-component-model-1-0) - [wasmi limits](https://docs.rs/wasmi/latest/wasmi/struct.StoreLimits.html) - [GitHub artifact attestations](https://docs.github.com/en/actions/concepts/security/artifact-attestations) - [VS Code Workspace Trust](https://code.visualstudio.com/docs/editing/workspaces/workspace-trust) - [The Update Framework metadata](https://theupdateframework.io/docs/metadata/) - [Sigstore verification](https://docs.sigstore.dev/cosign/verifying/verify/) ### Files, docs, and hosts - [OpenAI Files API](https://developers.openai.com/api/reference/resources/files) - [Anthropic Files API](https://platform.claude.com/docs/en/build-with-claude/files) - [OWASP File Upload guidance](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html) - [AGENTS.md](https://github.com/agentsmd/agents.md) - [OpenClaw gateway configuration](https://docs.openclaw.ai/gateway/config-tools) - [Hermes environment variables](https://hermes-agent.nousresearch.com/docs/reference/environment-variables/)

This issue is a broad Pentect roadmap rather than a self-contained change, and it names no specific file, test, or entry point. Start by selecting one unchecked integration or foundation item, then locate its existing client descriptor, gateway, protocol adapter, or compatibility evidence before defining a focused issue with a testable completion condition.

Written by the indexing model from the issue text.