Skip to content

task.md

Latest commit

 

History

History
142 lines (133 loc) · 15.9 KB

task.md

File metadata and controls

142 lines (133 loc) · 15.9 KB
Raw

Task: Production Remote Hosts System

Goal

Build the production-grade Rust implementation of the remote host knowledge, access, state, and execution center described in REMOTE_HOSTS_PRODUCT_TECH_PLAN.md.

Completed

  • Product and technical plan.
  • Rust workspace pinned to Rust 1.94.1.
  • Core crates for domain, core policy, vault, db, connector, API, MCP contracts, and CLI.
  • Initial database migration covering hosts, environments, credentials, access paths, facts, software installs, connection sessions, workspaces, PTYs, operations, knowledge, and state events.
  • Internal credential vault with Argon2id + XChaCha20-Poly1305.
  • Server protection baseline policy.
  • Command profile validation.
  • Secret redaction.
  • Guarded transport wrapper for validation, concurrency limiting, truncation, and redaction.
  • CLI doctor and migration commands.
  • Health API shell.
  • MCP tool name and request schema contracts.
  • Repositories for environments, connectors, credentials, access paths, access path health, facts, software installs, connection sessions, workspaces, PTYs, operations, knowledge, and state events.
  • Access resolver and host state aggregation service.
  • HTTP API endpoints for host listing, host detail, access path listing, access resolution, and host state.
  • OpenSSH native ControlMaster transport backend behind RemoteTransport.
  • Connector heartbeat service with state snapshots and state event writing.
  • Agent workspace supervisor core with default one-workspace-per-host protection.
  • HTTP API endpoints for connector heartbeat/events and workspace create/list/get/state/PTY listing.
  • MCP tool contract names and schemas for connector heartbeat/events and workspace state surfaces.
  • Repository-backed MCP server handlers for host/access/state/knowledge/heartbeat/workspace tools.
  • CLI MCP stdio entrypoint for local agent integration.
  • Built-in structured command profile catalog for agent-safe workspace operations.
  • Workspace operation queue planning with policy checks, operation records, and initial system output chunks.
  • Database migration and repositories for workspace-linked operations and redacted output chunks.
  • MCP handlers for command profile listing, run-in-workspace, output reading, workspace waiting, and close workspace.
  • HTTP API endpoints for command profiles, workspace operation queueing/listing/output/wait/close.
  • Operation claim leases with attempt counts, claim tokens, lease expiry, and last-error tracking.
  • Connector-side operation worker that claims queued operations, executes through RemoteTransport, stores redacted output chunks, and updates workspace/operation state.
  • Cached OpenSSH ControlMaster transport provider keyed by access path.
  • CLI worker-once command for executing one queued operation for a connector.
  • Long-running connector daemon loop with heartbeat emission, idle backoff, infrastructure-error backoff, Ctrl-C graceful shutdown, and offline state recording.
  • Lease renewal during long-running remote exec and claim-token-guarded operation finish.
  • File-backed large output artifacts with SHA-256 metadata, redacted previews, API/MCP metadata surfaces, and connector CLI tuning flags.
  • Recovery policy and agent-visible exhausted operation state for expired claims that reach max_attempts.
  • Policy-guarded persistent PTY lifecycle records with open/heartbeat/close/reap API and MCP tools.
  • Connector-local managed shell backend over reused OpenSSH transport with redacted PTY output chunks.
  • HTTP and MCP read surfaces for bounded PTY output polling.
  • DB-backed PTY input queue with API/MCP enqueue, status polling, connector claim leases, and connector-owned delivery pump.
  • Per-session/access-path OpenSSH PTY backend factory with existing-session activation and shipped worker-daemon input pump wiring.
  • Agent-visible PTY backend state and capability fields persisted in PTY session records.
  • OpenSSH ControlMaster true-TTY backend mode using a persistent ssh -tt child without repeated SSH handshakes.
  • Native russh check/exec transport provider with cached sessions, host-key policy, and internal vault-backed SSH credentials.
  • Shared native russh transport pool for operation and PTY backends.
  • Native russh persistent PTY backend with request-pty, shell startup, pooled session reuse, and persistent input/output streaming.
  • Access-path keepalive and idle TTL wired into OpenSSH ControlMaster and native russh sessions.
  • Cached-session health validation, bounded replacement handshake token bucket, connection-session metrics, access-path failure state, and circuit cooldown enforcement.
  • Connector startup PTY reconciliation and backend-exit state convergence without silently replacing a lost runtime with a new shell.
  • Automatic logical connection-session selection/creation for PTY open requests and operation-to-session binding.
  • Snapshot-first MCP runtime view across connector, access path, SSH session, workspace, PTY, and recent operation state.
  • Shared OpenSSH transport pool injected into daemon operation and PTY backends.
  • Monotonic runtime state-event cursors with explicit live_only/after_cursor HTTP and MCP waits.
  • MCP agent/admin/full tool profiles with a bounded task-oriented default agent surface.
  • Agent-profile encrypted credential capture for registration and existing-host credential rotation.
  • Native key-first authentication with bounded SSH-agent/default-key attempts, password fallback, and idempotent POSIX/Windows public-key bootstrap.
  • Persistent authorized-key bootstrap state with independent timeout, crash cooldown, bounded retry suppression, permanent-failure classification, key-fingerprint reset, and agent-visible recovery hints.
  • Multi-hop route preflight that reloads route metadata, invalidates stale direct caches, and rejects unsupported jump chains before SSH handshake.
  • Automatic local vault-key generation and shared MCP/connector launch configuration.
  • Task-oriented prepare_workspace and combined get_workspace_result facade tools.
  • One-call named password credential creation through ensure_host, with canonical environment preservation and same-endpoint route reclassification.
  • Single-hop bastion endpoint semantics for interactive menus and gateway usernames, while real proxy chains still fail before handshake.
  • Managed shell.posix and shell.powershell profiles for real operations through the pooled workspace, with bounded summaries and configurable timeout/output limits.
  • Proactive connector-side PTY activation before first input plus MCP backend readiness and polling guidance.
  • Terminal-workspace PTY filtering and one-shot activation failure convergence with redacted recovery output.
  • Runtime snapshot filtering so disabled access paths cannot contribute stale connection-health warnings.
  • Managed OpenSSH and native russh SFTP upload/download through the existing pooled session, with bounded size/time, SHA-256 verification, same-directory temporary placement, atomic rename, mode, and overwrite policy.
  • Route-compatible POSIX exec-channel file transfer for empty-chain bastion endpoints that cannot carry SFTP writes, with bounded encrypted chunks, no file body in MCP/audit persistence, and mandatory per-stage completion markers.
  • Resumable exec-channel uploads with artifact-stable temporary paths, prefix SHA-256 validation, idempotent chunk replay, connector-restart recovery, and already-placed destination convergence.
  • Single-channel stdin uploads with per-I/O no-progress timeouts, resumable fallback, and healthy pooled-session retention after successful commands and transfers.
  • File-transfer progress events and 30-second active heartbeats with verified bytes, total bytes, resumed bytes, retry count, and elapsed time.
  • Best-effort transfer progress persistence so a diagnostic output-write failure cannot cancel an active data channel.
  • Independent per-access-path and connector-wide shared SSH handshake budgets; local path cooldown is no longer expanded to the ten-minute global window.
  • Route-aware raw and guarded transport cache replacement after endpoint, route, host-kind, keepalive, or connection-policy changes.
  • Bounded MCP reads for complete redacted output artifacts with offset pagination, UTF-8 boundary handling, and artifact-root containment checks.
  • Local handshake-budget exhaustion reported separately from target sshd rate limiting, preserving the exact retry delay without increasing target failure counters or opening its circuit.
  • Workspace preparation reuses only idle or working workspaces and never returns throttled, blocked, failed, or closed workspaces for new work.
  • Successful PTY activation converges access-path health to connected and clears expired local-handshake throttle attention.
  • Runtime snapshots convert expired local-handshake throttles into local_handshake_budget_ready with one-retry guidance instead of a zero-second wait loop.
  • Connector startup invalidates connector-local connected/healthy/resolving sessions and clears open-channel counts so persisted history cannot masquerade as a live SSH transport.
  • Connector-local SSH runtime telemetry and per-channel evidence for exec, file transfer, and PTY, distinguishing handshake, real transport reuse, same-runtime reconnect, and runtime replacement.
  • Durable Agent Session identity with session-owned Workspaces, PTYs, operations, output, artifacts, and legacy-state recovery rules.
  • Session-scoped semantic idempotency for commands, file transfers, and PTY input, including exact retry reuse and mismatched-payload rejection.
  • Hierarchical Workspace coordination_scope leases: host remains the safe default, equal and parent/child resources serialize, and independent sibling resources can mutate concurrently.
  • Interactive asset-menu bastion downloads through the selected active PTY with in-memory frame capture, per-chunk and whole-file SHA-256 verification, source-change detection, and atomic local placement.
  • PTY lease continuity with a 300-second post-input window, output/activity renewal, and bounded handoff after close, backend exit, or connector restart.
  • Arbitrary POSIX/PowerShell commands over reused exec channels plus persistent PTY state when shell context must survive between inputs.
  • CLI worker-daemon --pty-backend-mode auto|control-master-tty|pipe-shell|russh-native-pty.
  • macOS launchd service management script for install/update/start/stop/restart/status/logs.
  • Local launchd deployment running API and connector daemon with release binary, SQLite database, logs, and default connector bootstrap.
  • Verification: cargo fmt --all, cargo test --workspace, cargo check --workspace, strict clippy.
  • Release deployment smoke: migration applied, launchd API/connector healthy, fresh MCP stdio exposes 18 Agent tools and the current runtime snapshot without opening a remote SSH connection.
  • Generic infrastructure topology graph for hosts, clusters, VMs, reverse proxies, middleware, data services, business services, and arbitrary directed dependencies.
  • Source- and scope-aware topology snapshot reconciliation with idempotent upserts and non-destructive inactive history.
  • Encrypted credential storage and purpose-specific bindings for any topology resource, with metadata-only HTTP responses.
  • Embedded local administration console with server registry, route health, topology SVG, filtering, snapshot import, resource details, and credential capture.
  • Loopback-only safety boundary for an HTTP process with an unlocked credential vault.
  • launchd API wrapper passes the generated local vault password file so topology credential capture is usable after install/update.
  • Repository-owned Remote Hosts Agent Skill with topology workflow guidance and automatic Codex/Antigravity synchronization during service install/update.
  • Grouped and collapsible topology console with dynamic swimlane layout, bounded relationship rendering, topology search, focus mode, and an atomically hot-swappable external admin HTML file.
  • Native Windows runtime through the cross-platform russh connector, with Unix-only OpenSSH mux dependencies excluded from MSVC builds.
  • Rust-native Windows MSVC cross-compilation and ZIP packaging through cargo-xwin, including SHA-256 release output, admin UI, and Agent Skill.
  • Windows per-user Task Scheduler installation, login startup, failure restart, versioned staging, drain-gated updates, logs, status, UI refresh, Skill installation, and uninstall.
  • Stable low-overhead Rust MCP launcher for Windows so new Agent Sessions follow the current version pointer without a PowerShell proxy or client-config rewrite.
  • Rust-owned local connector bootstrap and restart-readiness commands, removing the service scripts' dependency on an external SQLite CLI.
  • Documented real macOS resource sample for a history-heavy daily-use installation.
  • Compact Postcard plus Zstandard output segments, upgrade-safe legacy write compatibility, explicit compressed-write activation, low-latency PTY batch writes, transparent legacy reads, bounded history migration, stale PTY-input cleanup, and guarded SQLite reclamation on macOS and Windows.

Next

  • Add a real gateway/SSHD regression suite for pooled arbitrary commands, session invalidation, one bounded reconnect, cross-workspace reuse, SFTP and exec-channel file transfer, 1 GiB files, complete Artifact reads, and gateways that drop stdin/EOF/stdout/exit-status signals. The local shell regression already covers disconnect-equivalent stateless chunk continuation, duplicate chunk replies, and already-placed destination recovery.
  • Add local SSHD integration tests for control-master-tty and native russh PTY backend.
  • Add a multi-process MCP integration test that drives two Agent Sessions through one real pooled SSH transport while proving workspace/PTY isolation and write-lease handoff.
  • Persist authoritative connection, workspace, operation, PTY, input, and transfer lifecycle transitions through a same-transaction durable outbox; publish them idempotently into the general runtime event log without coupling publisher failure to remote work.
  • Add Agent Work Context v1 as a session-scoped snapshot/wait explain contract with one deterministic primary action.
  • Add a target-side worker mode for true PTY/process continuity across connector restarts.
  • Add HTTP/MCP control methods for native russh PTY resize and signal delivery.
  • Implement port forwarding behind the existing pooled transport trait.
  • Define a typed proxy-chain schema and implement verified multi-hop routing without exposing jump-host credentials or bypassing route intent.
  • Expand HTTP API endpoints for registry mutation, knowledge search, and operations.
  • Add Linux systemd packaging and service templates.
  • Add first-class CLI registry mutation commands for hosts/environments/connectors/access paths.
  • Add opt-in topology discovery adapters for nginx/Caddy/Traefik, Docker/Podman, systemd, Kubernetes, and common middleware; adapters should emit the existing topology snapshot contract instead of adding product-specific graph tables.

Domain-specific Kubernetes, Harbor, database, middleware, GPU, and deployment behavior is intentionally not a core MCP-tool roadmap. Use arbitrary shell/PowerShell or PTY on the pooled connection; package repeated workflows as optional runbooks.

Verification Gates

  • cargo fmt --all
  • cargo test --workspace
  • cargo check --workspace
  • cargo clippy --workspace --all-targets -- -D warnings
  • CLI migration smoke test against a new SQLite file
  • Fresh installed-binary MCP initialize/tool-list/read-only snapshot smoke test
  • No plaintext secrets in logs/API/MCP responses