@cuylabs/physical-core

Agent-agnostic physical AI contracts.

This package defines shared TypeScript shapes for physical sessions, observations, artifacts, capabilities, safety policy, execution traces, and task outcomes. It does not depend on an agent runtime.

It is intentionally backend-neutral. It gives applications a common vocabulary for simulator and hardware sessions while backend packages connect those contracts to concrete robotics frameworks, runtime services, middleware, and hardware stacks.

@cuylabs/physical-core is not a robotics runtime and it is not a replacement for a backend's native environment. It defines the common contract for observing a physical session, inspecting artifacts, describing capabilities, capturing execution traces, and carrying safety metadata across higher-level agent or workflow systems.

Install

npm install @cuylabs/physical-core

Use

import type { PhysicalSession } from "@cuylabs/physical-core";

const session: PhysicalSession = await createYourPhysicalSession();
const state = await session.getState();

Package Boundary

Use this package when you need:

• a common PhysicalSession interface for simulator and hardware backends
• typed observations, artifacts, execution traces, and task outcomes
• safety metadata that can be consumed by host applications, approval systems, and UIs
• backend-neutral contracts that do not depend on any agent runtime

Do not put backend-specific launchers, prompts, simulators, perception models, robot APIs, or model-facing tools here. Those belong in runtime packages such as @cuylabs/physical-capx or binding packages such as @cuylabs/physical-agent-core.

Mental Model

A physical integration has three layers:

1. The host or agent harness decides what to do next.
2. The physical adapter translates shared session calls into a concrete robotics backend.
3. The robotics backend owns the simulator, robot, sensors, task state, and low-level execution.

@cuylabs/physical-core is the middle contract. It makes physical state and side-effecting actions legible to higher-level software without forcing every robotics backend to expose the same native APIs.

Boundary

This package owns reusable physical AI vocabulary. Agent-runtime tools belong in binding packages such as @cuylabs/physical-agent-core. Backend-specific runtime clients belong in packages such as @cuylabs/physical-capx.

Docs

• docs/README.md for the documentation map
• docs/architecture.md for package boundaries
• docs/safety.md for approval and replay expectations

License

Apache-2.0