The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
docs: add agent-os technical report
dotta482dac709789
diff --git a/doc/plans/2026-04-08-agent-os-technical-report.md b/doc/plans/2026-04-08-agent-os-technical-report.mdnew file mode 100644index 0000000000..923cf7d26d--- /dev/null+++ b/doc/plans/2026-04-08-agent-os-technical-report.md@@ -0,0 +1,397 @@+# Agent OS Technical Report for Paperclip++Date: 2026-04-08+Analyzed upstream: `rivet-dev/agent-os` at commit `0063cdccd1dcb1c8e211670cd05482d70d26a5c4` (`0063cdc`), dated 2026-04-06++## Executive summary++`agent-os` is not a competitor to Paperclip's core product. It is an execution substrate: an embedded, VM-like runtime for agents, tools, filesystems, and session orchestration. Paperclip is a control plane: company scoping, task hierarchy, approvals, budgets, activity logs, workspaces, and governance.++The strongest takeaway is not "copy agent-os wholesale." The strongest takeaway is that Paperclip could selectively use its runtime ideas to improve local agent execution safety, reproducibility, and portability while keeping all company/task/governance logic in Paperclip.++My recommendation is:++1. Do not merge agent-os concepts into the Paperclip core product model.+2. Do evaluate an optional `agentos_local` execution adapter or internal runtime experiment.+3. Borrow a few design patterns aggressively:+ - layered/snapshotted execution filesystems+ - explicit capability-based runtime permissions+ - a better host-tools bridge for controlled tool execution+ - a normalized session capability model for agent adapters+4. Do not import its workflow/cron/queue abstractions into Paperclip core until they are reconciled with Paperclip's issue/comment/governance model.++## What agent-os actually is++From the repo layout and implementation, `agent-os` is a mixed TypeScript/Rust system that provides:++- an `AgentOs` TypeScript API for creating isolated agent VMs+- a Rust kernel/sidecar that virtualizes filesystem, processes, PTYs, pipes, permissions, and networking+- an ACP-based session model for agent runtimes such as Pi, OpenCode, and Claude-style adapters+- a registry of WASM command packages and mount plugins+- optional host toolkits, cron scheduling, and filesystem mounts++The repo is substantial already:++- monorepo with `packages/`, `crates/`, and `registry/`+- roughly 1,200 files just across `packages/`, `crates/`, and `registry/`+- mixed implementation model: TypeScript public API plus Rust kernel/sidecar internals++## Architecture notes++### 1. Public runtime surface++The main API lives in `packages/core/src/agent-os.ts` and exports an `AgentOs` class with methods such as:++- `create()`+- `createSession()`+- `prompt()`+- `exec()`+- `spawn()`+- `snapshotRootFilesystem()`+- cron scheduling helpers++This is an execution API, not a coordination API.++### 2. Virtualized kernel model++The kernel is implemented in Rust under `crates/kernel/src/`. It models:++- virtual filesystem+- process table+- PTYs and pipes+- resource accounting+- permissioned filesystem access+- network permission checks++That gives `agent-os` a much stronger isolation story than Paperclip's current "launch a host CLI in a workspace" local adapter approach.++### 3. Layered filesystem and snapshots++The filesystem design is one of the most reusable ideas. `agent-os` uses:++- a bundled base filesystem+- a writable overlay+- optional mounted filesystems+- snapshot export/import for reusing root states++This is cleaner than treating every execution workspace as a mutable checkout plus ad hoc cleanup. It enables reproducible starting states and cheap isolation.++### 4. Capability-based permissions++The kernel-level permission vocabulary is strong and concrete:++- filesystem operations+- network operations+- child-process execution+- environment access++The Rust kernel defaults are deny-oriented, but the high-level JS API currently serializes permissive defaults unless the caller provides a policy. That is an important nuance: the primitive is security-minded, but the product surface is still convenience-first.++### 5. Host-tools bridge++`agent-os` exposes host-side tools via a toolkit abstraction (`hostTool`, `toolKit`) and a local RPC bridge. This is a strong pattern because it gives the agent explicit, typed tools rather than ambient shell access to everything on the host.++### 6. ACP session abstraction++The session model is more uniform than most agent wrappers. It includes:++- capabilities+- mode/config options+- permission requests+- sequenced session events+- JSON-RPC transport through ACP adapters++This is directly relevant to Paperclip because our adapter layer still normalizes each CLI agent in a fairly bespoke way.++## Paperclip anchor points++The most relevant current Paperclip surfaces for any future `agent-os` integration are:++- `packages/adapter-utils/src/types.ts`+ - shared adapter contract, session metadata, runtime service reporting, environment tests, and optional `detectModel()`+- `server/src/services/heartbeat.ts`+ - heartbeat execution, adapter invocation, cost capture, workspace realization, and issue-comment summaries+- `server/src/services/execution-workspaces.ts`+ - execution workspace lifecycle and git readiness/cleanup logic+- `server/src/services/plugin-loader.ts`+ - dynamic plugin activation, host capability boundaries, and runtime extension loading+- local adapters such as `packages/adapters/codex-local/src/server/execute.ts` and peers+ - current host-CLI execution model that an `agent-os` runtime experiment would complement or replace for selected agents++## What Paperclip can learn from it++### 1. A safer local execution substrate++Paperclip's local adapters currently run host CLIs in managed workspaces and rely on adapter-specific behavior plus process-level controls. That is pragmatic, but weakly isolated.++`agent-os` shows a path toward:++- running local agent tooling in a constrained runtime+- applying explicit network/filesystem/env policies+- reducing accidental host leakage+- making adapter behavior more portable across machines++Best use in Paperclip:++- as an optional runtime beneath local adapters+- or as a new adapter family for agents that can run inside ACP-compatible `agent-os` sessions++This fits Paperclip because it improves execution safety without changing the control-plane model.++### 2. Snapshotted execution roots instead of only mutable workspaces++Paperclip already has strong execution-workspace concepts, but they are repo/worktree-centric. `agent-os` adds a stronger "start from known lower layers, write into a disposable upper layer" model.++That could improve:++- reproducible issue starts+- disposable task sandboxes+- faster reset/cleanup+- "resume from snapshot" behavior for recurring routines+- safe preview environments for risky agent operations++This is especially interesting for tasks that do not need a full git worktree.++### 3. A capability vocabulary for runtime governance++Paperclip has governance at the company/task level:++- approvals+- budgets+- activity logs+- actor permissions+- company scoping++It has less structure at the runtime capability level. `agent-os` offers a clear vocabulary that Paperclip could adopt even without adopting the runtime itself:++- `fs.read`, `fs.write`, `fs.mount_sensitive`+- `network.fetch`, `network.http`, `network.listen`, `network.dns`+- child process execution+- env access++That vocabulary would improve:++- adapter configuration schemas+- policy UIs+- execution review surfaces+- future approval gates for governed actions++### 4. Typed host tools instead of shelling out for everything++Paperclip's plugin system and adapters already have the beginnings of a controlled extension surface. `agent-os` reinforces the value of exposing capabilities as typed tools rather than raw shell access.++Concrete Paperclip uses:++- board-approved toolkits for sensitive operations+- company-scoped service tools+- plugin-defined tools with explicit schemas+- safer execution for common actions like git metadata inspection, preview lookups, deployment status checks, or document generation++This aligns well with Paperclip's governance story.++### 5. Better adapter normalization around sessions and capabilities++Paperclip's adapter contract already supports execution results, session params, environment tests, skill syncing, quota windows, and optional `detectModel()`. But much of the per-agent behavior is still adapter-specific.++`agent-os` suggests a cleaner normalization target:++- a standard capability map+- a consistent event stream model+- explicit mode/config surfaces+- explicit permission request semantics++Paperclip does not need ACP everywhere, but it would benefit from a more formal internal session capability model inspired by this.++### 6. On-demand heavy sandbox escalation++One of the best architectural choices in `agent-os` is that it does not pretend every workload fits the lightweight runtime. It has a sandbox extension for workloads that need a fuller environment.++Paperclip can adopt that philosophy directly:++- lightweight execution by default+- escalate to full worktree / container / remote sandbox only when needed+- keep the escalation explicit in the issue/run model++That is better than forcing all tasks into the heaviest environment up front.++## What does not fit Paperclip well++### 1. Its built-in orchestration primitives overlap the wrong layer++`agent-os` includes cron/session/workflow style primitives inside the runtime package. Paperclip already has higher-level orchestration concepts:++- issues/comments+- heartbeat runs+- approvals+- company/org structure+- execution workspaces+- budget enforcement++If Paperclip copied `agent-os` cron/workflow/queue ideas directly into core, we would likely duplicate orchestration across two layers. That would blur ownership and make debugging harder.++Paperclip should keep orchestration authoritative at the control-plane layer.++### 2. It is not company-scoped or governance-native++`agent-os` is runtime-first, not company-first. It has no native concepts for:++- company boundaries+- board/operator actor types+- audit logs for business actions+- issue hierarchy+- approval routing+- budget hard-stop behavior++Those are Paperclip's differentiators. They should not be displaced by runtime abstractions.++### 3. It introduces meaningful implementation complexity++Adopting `agent-os` deeply would add:++- Rust build/runtime complexity+- sidecar lifecycle management+- new failure modes across JS/Rust boundaries+- more packaging and platform compatibility work+- another abstraction layer for debugging already-complex local adapters++This is justified only if we want stronger local isolation or portability. It is not justified as a general refactor.++### 4. Its security model is not a drop-in governance solution++The permission model is good, but it is low-level. Paperclip would still need to answer:++- who can authorize a capability+- how approval decisions are logged+- how policies are scoped by company/project/issue/agent+- how runtime permissions interact with budgets and task status++In other words, `agent-os` can supply enforcement primitives, not the control policy system itself.++### 5. The agent compatibility story is still selective++The repo is explicit that some runtimes are planned, partial, or still being adapted. In practice this means:++- good ideas for ACP-native or compatible agents+- less certainty for every CLI agent we support today+- real integration work for Codex/Cursor/Gemini-style Paperclip adapters++So the main near-term value is not universal replacement. It is selective use where compatibility is strong.++## Concrete recommendations for Paperclip++### Recommendation A: prototype an optional `agentos_local` adapter++This is the highest-value experiment.++Goal:++- run one supported agent type inside `agent-os`+- keep Paperclip heartbeat/task/workspace/budget logic unchanged+- evaluate startup time, isolation, transcript quality, and operational complexity++Good first target:++- `pi_local` or `opencode_local`++Why not start with Codex:++- Paperclip's Codex adapter is already important and carries repo-specific behavior+- `agent-os`'s Codex story is present in the registry/docs, but the safest path is to validate the runtime on a less central adapter first++Success criteria:++- heartbeat can invoke the adapter reliably+- session resume works across heartbeats+- Paperclip still records logs, summaries, cost metadata, and issue comments normally+- runtime permissions can be configured without breaking common tasks++### Recommendation B: adopt capability vocabulary into adapter configs++Even without using `agent-os`, Paperclip should consider standardizing adapter/runtime permissions around a vocabulary like:++- filesystem+- network+- subprocess/tool execution+- environment access++This would improve:++- schema-driven adapter UIs+- future approvals+- observability+- policy portability across adapters++### Recommendation C: explore snapshot-backed execution workspaces++Paperclip should evaluate whether some execution workspaces can be backed by:++- a reusable lower snapshot+- a disposable upper layer+- optional mounts for project data or artifacts++This is most valuable for:++- non-repo tasks+- repeatable routines+- preview/test environments+- isolation-heavy local execution++It is less urgent for full repo editing flows that already benefit from git worktrees.++### Recommendation D: strengthen typed tool surfaces++Paperclip plugins and adapters should continue moving toward explicit typed tools over ad hoc shell access. `agent-os` confirms that this is the right direction.++This is a good fit for:++- plugin tools+- workspace runtime services+- governed operations that need approval or auditability++### Recommendation E: do not import runtime-level workflows into Paperclip core++Paperclip should not copy `agent-os` cron/workflow/queue concepts into core orchestration yet.++If we want them later, they must map cleanly onto:++- issues+- comments+- heartbeats+- approvals+- budgets+- activity logs++Without that mapping, they would create a second orchestration system inside the product.++## A practical integration map++### Best near-term fits++- optional local adapter runtime+- runtime capability schema+- typed host-tool ideas for plugins/adapters+- snapshot ideas for disposable execution roots++### Medium-term fits++- stronger session capability normalization across adapters+- policy-aware runtime permission UI+- selective ACP-inspired event normalization++### Poor fits right now++- moving Paperclip orchestration into agent-os workflows+- replacing company/task/governance models with runtime constructs+- making Rust sidecars a mandatory dependency for all local execution++## Bottom line++`agent-os` is useful to Paperclip as an execution technology reference, not as a product model.++Paperclip should treat it the same way it treats sandboxes or agent CLIs:++- execution substrate underneath the control plane+- optional where the tradeoff is worth it+- never the source of truth for company/task/governance state++If we do one thing from this report, it should be a narrowly scoped `agentos_local` experiment plus a design pass on capability-based runtime permissions. Those two ideas have the best upside and the lowest architectural risk.