PhyAgentOS-core: a Forge Gateway execution boundary for embodied agents

The problem: agents that call tools but never check whether the robot did anything

Most embodied agent stacks have a soft seam between deciding and doing. The planner emits a tool call, some runtime executes it, and the loop moves on. Whether the gripper closed on the object, or the arm reached the pose, is inferred from a return value that the same layer produced. PhyAgentOS-core is aimed at that seam. The README states the loop plainly: the Agent plans high-level Tool calls, the Forge Tool API reports what Gateway executed, an observation collector captures before/after evidence, and a task-level verifier decides whether the user-visible goal was actually achieved. The intended user is someone building on top of an existing robot or simulator who wants execution facts and visual evidence kept separate from the planner's own belief about what happened. That is a narrower audience than the tagline suggests. This is infrastructure for people who already have a policy, a simulator, or a hardware SDK and want a governed boundary in front of it, not a framework that supplies the manipulation capability itself.

The Forge Gateway boundary and what crosses it

The architectural claim in the README is that robot actions enter through one versioned Forge Gateway contract, and that the Agent never reaches into a policy, simulator, Dora node, or hardware SDK. That single sentence carries most of the design. If it holds, the agent layer cannot bypass the contract, which means every action is bound to an AgentTask and can be recorded. The v0.2.0 changelog describes Forge Gateway 1.0.0 as introducing immutable execution and evidence contracts, and v0.2.2 describes unified Forge execution on the Query/Action Tool API. So the Tool API has two verbs in the material: Query and Action. What the README does not give is the actual schema of either, or a worked example of a Gateway invocation. The claim that evidence is captured with source, sequence, time, size, digest, and retention metadata is specific enough to be checkable in the repository, but none of those fields appear in the README as a concrete record. Treat the boundary as the thing to audit first: if the Agent can still hold a reference to a policy object, the guarantee is a convention rather than an enforcement.

Verification that receives facts rather than an action-specific switch

The most defensible idea here is that the verifier is action-agnostic. According to the README, it receives the goal, criteria, constraints, execution facts, evidence, lineage history, and optional Skill-scoped advisories, and it never receives an action-specific verification switch. The README also states that advisories cannot replace criteria or evidence. That is a real constraint with a real cost: you cannot write a fast path that says if the tool was move-arm-by-ee then trust the returned pose. Everything routes through the same semantic check. The v0.1.6 changelog added a SessionVerifier and an explicit session-verification tool, and v0.2.1 added Skill-scoped advisory context for semantic verification, so the verification surface has grown across releases rather than being a single function. The failure mode is latency and cost. A semantic verifier that consumes images and lineage history is heavier than a return-code check, and the README gives no timing or budget guidance. If your control loop needs sub-second confirmation, this layer will not be where you get it.

Crash-safe task state and Planner-owned recovery

PhyAgentOS-core persists AgentTask, PlanRevision, Query records, and Gateway invocation references in SQLite transactions, and the README is explicit that this does not create a second physical execution protocol. The recovery model is what makes that persistence matter. A recovery verdict appends a bounded PlanRevision to the same task rather than spawning a new one, and the README states that unknown effects are reconciled and never retried blindly. That is the correct posture for physical systems: if the arm may or may not have moved, retrying the same command is how you break something. The word bounded is doing a lot of work in that sentence. Nothing in the supplied material says what the bound is, whether it is a count, a time window, or a budget, or what happens when the bound is hit and the task still cannot be reconciled. That is the first thing I would look for in the source, because an unbounded revision loop on a physical task is worse than a failed task.

Getting it running: what the README does and does not hand you

The repository metadata gives the hard requirements: Python 3.11 or higher, primary language Python, MIT license, default branch main. The README lists a tech report on arXiv, a documentation directory under docs, and separate English and Chinese README files. What it does not contain is a quickstart. There is no pip install line, no clone-and-run sequence, no config file example, and no named config keys in the supplied text. The architecture block is truncated mid-diagram at User / Channel / Sche, so even the component list is incomplete in the material I have. I cannot tell you which command starts a session, which file holds the Gateway endpoint, or how a Skill is installed. The v0.2.3 changelog says Forge Skills can be installed and managed independently and activated into immutable AgentTask bindings, which implies an install path exists, but the mechanism is not shown. If you are evaluating this, the honest first step is to read docs/README.md and the arXiv report, not the top-level README, because the top-level README is a positioning document.

The RSI framing is ahead of the evidence in the README

The description calls PhyAgentOS a Recursive Self-Improving physical agent operating system, and the topics list includes rsi and self-evolution. The README's own mechanism for this is narrower than the framing. Verified AgentTasks support reusable workflow Skills and clustered Lessons, and learned guidance is loaded only with the matching Skill. The v0.2.1 changelog adds guarded Skill evolution and clustered scope-aware Lessons. So the improvement loop is: a task gets verified, the verified task can yield a Skill or a Lesson, and that artifact is scoped to matching future work. That is experience reuse with a guard, not an agent rewriting its own planner. The word guarded appears in the changelog without a description of the guard. Nothing in the material shows a measured improvement from one version to the next, and I have no benchmark numbers to cite. Anyone drawn in by the recursive self-improvement label should read it as skill accumulation under verification, and should check in the source what actually gates a Skill from being promoted.

Where this is the wrong tool, and what to compare it against

If you want a manipulation library, this is not it. There is no policy training code described, no dataset, and no claim that PhyAgentOS-core makes a robot better at grasping. It assumes you bring the capability and want it governed. A more useful comparison is against a plain agent harness that calls robot tools directly, such as the pattern of a planner with a tool registry and a return-code check. The difference is not features, it is where trust sits. In the direct-call pattern, the planner's tool result is the ground truth and verification is whatever the tool returns. In PhyAgentOS-core, the Gateway reports execution facts, a separate collector captures before/after evidence, and a verifier that did not execute anything decides whether the goal was met. That separation costs you a persistence layer, an evidence store with retention metadata, and a semantic verification step. It buys you a defensible answer to the question of whether the task actually succeeded, which matters when the action is physical and irreversible. If your tasks are reversible and cheap, the extra layer is overhead you will feel and not recover. The other case where it is wrong: if you need a stable API surface. The v0.2.0 entry states the legacy Runtime execution chain was removed completely, which is a large break for anyone who built on v0.1.x.

Licence, maintenance, and what to check before committing

The licence is MIT, which is permissive and places few obligations on how you redistribute or modify the code. That is a statement about the licence text, not legal advice; if you are shipping this inside a product, have your own counsel read it alongside the licences of whatever simulator, model weights, and hardware SDK you connect through the Gateway, because those are separate and the README does not discuss them. On maintenance: the repository is not archived, the last push is dated 2026-09-10, and v1.0.0 landed on 2026-09-05. The changelog shows a release roughly every one to three weeks from 2026-04-29 through 2026-09-05, including a v0.2.0 that removed an entire execution chain. That cadence is the maintenance cost. You are adopting a project that is still reshaping its core contracts, so pinning a version and reading the changelog before each upgrade is the practical posture. The specific things to verify in the source before you commit: the bound on PlanRevision per task, the schema of the Query and Action Tool API, the list of Resource Registry targets that ship adapters, and whether the verifier requires a hosted model provider to run.

Editorial conclusion

PhyAgentOS-core fits teams already running a robot or simulator stack who want a governed execution boundary and evidence-backed task verification, and who are willing to read source because the README stops at the architecture diagram. It does not fit anyone looking for a turnkey manipulation stack, and it does not fit teams that need stable APIs across releases: the changelog shows the legacy Runtime execution chain was removed wholesale in v0.2.0. Before adopting, verify three things against the repository itself: which hardware and simulator targets the Resource Registry actually ships adapters for, whether the Forge Gateway contract is versioned in a way your own tooling can pin, and whether the verifier can run without a model provider you are willing to send task evidence to.

Official sources

1. License: MIT
2. PhyAgentOS/PhyAgentOS-core on GitHub
3. Project website
4. README
5. Releases