Summary

This PR removes the old Pi-shaped agent/runtime architecture from OpenClaw and re-integrates that functionality as OpenClaw-owned core, plugin, and SDK surfaces.

The main result is that OpenClaw no longer treats Pi as an embedded dependency or organizing concept. Agent execution, model/provider handling, sessions, compaction, transcript storage, provider startup, plugin runtime loading, and docs/tests now use OpenClaw names, OpenClaw ownership boundaries, and OpenClaw package/runtime contracts.

At a high level this PR:

• Extracts an OpenClaw-owned @openclaw/agent-core package from the previously embedded agent runtime code.
• Renames Pi-era source modules, tests, config surfaces, docs, QA scenarios, and type shims into OpenClaw agent/runtime concepts.
• Removes legacy provider/model compatibility behavior that was only there because Pi used to be a dependency boundary.
• Moves provider-owned behavior and dependencies into the owning provider/plugin packages instead of keeping them in root/core.
• Consolidates duplicated session, transcript, compaction, ACPX, Google stream, JSON parser, and test helper logic.
• Keeps compatibility only where it is a real plugin/public boundary, and marks those compatibility paths as deprecated instead of letting them look like internal architecture.
• Updates license/notice text for the incorporated Pi-derived code now that the code is internalized.
• Updates documentation, QA scenarios, test shards, dependency ownership metadata, and package/build wiring to match the new architecture.

Why

The previous structure still had Pi concepts in places where OpenClaw should own the abstraction directly:

• package names and type declarations still referred to Pi agent/core/coding-agent concepts
• model/provider code still had fallback and alias behavior inherited from the dependency relationship
• sessions and transcript writing had parallel stacks instead of one canonical OpenClaw path
• provider runtime and plugin runtime code carried compatibility branches for old Pi/plugin layouts
• root dependencies included provider-specific packages that should belong to provider plugins
• docs and QA scenarios taught users and maintainers a Pi-era architecture that no longer matched the product

That made the refactor look like a dependency shuffle instead of a real integration. This PR makes the structure look like Pi had never existed as a separate internal dependency: OpenClaw owns the runtime core, providers own provider behavior, plugins cross into core through the SDK/manifest contracts, and compatibility is explicit/deprecated at the public boundary only.

Architectural Changes

OpenClaw Agent Core

Adds a new workspace package at packages/agent-core.

This package now owns the reusable agent runtime primitives that were previously internalized from the Pi dependency shape:

• agent loop orchestration
• harness execution types
• message conversion helpers
• prompt template helpers
• compaction primitives
• branch summarization utilities
• session interfaces and storage abstractions
• JSONL and memory-backed session repositories
• shell output/truncation helpers
• runtime dependency injection points
• validation helpers
• Node runtime helpers

The package is exported as @openclaw/agent-core and wired into root package/build config, workspace config, TypeScript config, and package manager metadata.

Core OpenClaw code now imports the shared runtime contracts from this package instead of reaching through Pi-named local modules or dependency shims.

Agent Runtime Naming And Ownership

Renames Pi-era agent files and tests under src/agents into OpenClaw-owned names.

Examples of the broad rename/integration:

• pi-auth-* became agent-auth-*
• pi-bundle-* became agent-bundle-*
• pi-hooks became agent-hooks
• pi-settings became agent-settings
• pi-tools* became agent-tools*
• pi-project-settings* became agent-project-settings*
• pi-model-discovery* became agent-model-discovery*
• pi-agent-core.d.ts became agent-core.d.ts

The goal is not just cosmetic. The renamed modules now sit behind OpenClaw runtime ownership:

• agent runtime ids are OpenClaw runtime ids
• agent settings are OpenClaw agent settings
• bundled MCP materialization is OpenClaw agent bundle materialization
• tool definitions and tool policies are OpenClaw agent tool contracts
• compaction hooks are OpenClaw agent hooks

Runtime And Plugin Boundary Cleanup

The PR tightens the boundary between core and plugins.

Core remains plugin-agnostic and no longer carries provider/plugin behavior simply because the old dependency needed it. Provider-specific defaults, catalogs, auth choices, discovery, and stream behavior move toward provider-owned packages or focused SDK seams.

Important changes include:

• provider runtime selection no longer routes through legacy Pi runtime names
• old provider alias normalization paths are removed or moved to explicit command/provider-facing compatibility where needed
• provider discovery fallbacks that existed for the old dependency graph are removed
• provider auth bridge behavior that referenced Pi concepts is removed
• provider runtime model types are made more explicit
• runtime plugin loading now uses OpenClaw plugin/runtime contracts instead of Pi package graph assumptions
• startup model ownership moves to manifests/provider catalogs instead of a static root model catalog
• bundled plugin metadata, gateway startup plugin ids, and runtime plugin tests are updated accordingly

Provider And Model Refactor

This PR removes the old static model-catalog shape from core and replaces it with OpenClaw/provider-owned registry behavior.

Key points:

• static generated model catalogs are removed from runtime ownership paths
• model registration and lookup go through OpenClaw LLM registry code
• provider model ownership is resolved through provider/plugin metadata rather than hard-coded Pi-era catalog assumptions
• GitHub Copilot policy models are sourced from the provider path rather than duplicated core state
• model selection tests are updated for OpenClaw provider ids and current provider ownership
• provider alias handling is narrowed to command/user-facing interpretation where still needed
• legacy provider compatibility paths are removed from hot runtime code

The new LLM area under src/llm owns core model/provider contracts and built-in provider implementations:

• API registries
• model registries
• image model registries
• model utilities
• provider stream wrappers
• provider OAuth helpers
• provider diagnostics/event streams
• provider JSON parsing/sanitization utilities
• built-in provider registration

Provider Dependencies Move To Owning Extensions

Provider-only dependencies are moved out of root/core and into the owning provider/plugin packages.

The most visible case is AWS/Bedrock:

• AWS SDK dependencies move to the Amazon Bedrock extension packages.
• Bedrock provider stream/runtime behavior is owned by the Bedrock extension.
• Root package metadata and lock/shrinkwrap files are updated so root no longer pulls provider-only AWS dependencies.
• Dependency ownership metadata is updated to describe the new package boundary.

Other provider packages and shrinkwraps are updated similarly where dependencies were previously inherited from the Pi/root dependency shape.

Session And Transcript Unification

This PR consolidates session storage and transcript writing around OpenClaw-owned config/session modules and the new agent-core session abstractions.

Changes include:

• session version ownership moves into config session code
• transcript append helpers are shared instead of duplicated
• transcript headers and JSONL writing are centralized
• session load/store code is updated to use OpenClaw session contracts
• agent session SDK surfaces are updated to point at OpenClaw-owned session types
• gateway/session and command/session tests are updated for the new session model

This is intended to remove the old split between a Pi session stack and an OpenClaw session stack.

Compaction And Context Runtime Cleanup

Compaction and context-engine code is updated to use the OpenClaw agent-core/runtime shape.

The PR:

• moves shared compaction primitives into packages/agent-core
• removes Pi-specific compaction constants/names
• updates compaction docs and QA scenarios to OpenClaw terminology
• updates context-engine host compatibility references
• keeps compaction/session behavior wired through OpenClaw runtime contracts
• adjusts tests to validate the renamed runtime paths

ACPX Runtime Turn Deduplication

The ACPX plugin had duplicated lazy turn/run-turn adapter logic in both registration and service paths.

This PR extracts that into extensions/acpx/src/runtime-turn.ts and updates both callers to use the shared helper.

That shared helper now owns:

• lazy runtime resolution for startTurn
• compatibility adaptation from legacy runTurn runtimes to startTurn
• queued event delivery for legacy run-turn streams
• terminal result conversion from ACP done/error events
• cancellation and stream-close behavior

The behavior stays equivalent, but the implementation is now one path.

Google And Vertex Stream Projection Deduplication

src/llm/providers/google.ts and src/llm/providers/google-vertex.ts had near-identical streaming loops.

This PR moves the shared projection into consumeGoogleGenerateContentStream(...) in src/llm/providers/google-shared.ts.

The shared path handles:

• stream start/done events
• first response id retention
• text block start/delta/end events
• thinking block start/delta/end events
• thought signature retention
• function call/tool call projection
• duplicate or missing tool call id handling
• stop reason mapping
• forcing toolUse when tool calls are present
• usage metadata conversion
• cost calculation
• abort/error handling

A new focused test, src/llm/providers/google-shared.test.ts, locks the shared projection behavior across text, thinking, tool calls, response ids, stop reasons, and usage/cost accounting.

Unsafe Integer JSON Parser Deduplication

Ollama had a local copy of the unsafe-integer-preserving JSON parser that already existed in core agent transport code.

This PR promotes that parser to a narrow generic SDK subpath:

• src/plugin-sdk/json-unsafe-integers.ts
• openclaw/plugin-sdk/json-unsafe-integers

The Ollama extension now imports the shared parser through the SDK boundary instead of duplicating the implementation or reaching into core internals.

Package exports, SDK entrypoint metadata, SDK docs, and plugin SDK export checks are updated for the new subpath.

Test Fixture Deduplication

src/agents/sandbox/workspace-skills-bridge-readonly.test.ts repeated the same remote shell runner fixture in multiple cases.

This PR extracts that fixture into one typed local helper inside the test file. The tests keep the same assertions, but the duplicate shell runner setup is gone.

Duplicate Scan Cleanup

After the final cleanup pass, duplicate scanning reports zero clones across the configured duplicate scan targets:

• production: 0 clones
• tests: 0 clones
• src-mixed: 0 clones
• extensions-mixed: 0 clones
• test-mixed: 0 clones

This specifically removed the remaining ACPX, Google/Vertex, Ollama JSON parser, and sandbox test fixture duplicate reports.

Plugin SDK And Compatibility

The plugin SDK is updated to expose only intentional OpenClaw seams.

Changes include:

• new agent-core and agent-session SDK forwarding surfaces
• provider/LLM SDK entrypoints for shared provider runtime contracts
• narrow provider stream/model helper updates
• json-unsafe-integers as a generic parser utility for plugin-owned runtime code
• SDK baseline/export metadata updates
• documentation updates for SDK subpaths and migration guidance

Compatibility is kept where it is a real public/plugin boundary, not where it was merely internal implementation convenience.

Old public compatibility paths are represented through explicit compatibility/deprecation metadata and tests instead of being treated as current internal architecture.

Legacy Pi Cleanup

This PR removes Pi as an internal runtime/package concept.

Removed or renamed areas include:

• Pi runtime internals
• Pi package graph tests
• Pi model fixture naming
• Pi agent/core type names
• Pi auth/model discovery names
• Pi docs pages and scenario names
• Pi-specific config/test shard names
• Pi wording in user-facing docs where the subject is now OpenClaw agent runtime

Remaining compatibility is intentionally narrow and boundary-owned:

• public SDK compatibility/deprecation metadata remains where old external plugin imports may still exist
• doctor/migration code retains explicit deprecation handling for real shipped config states
• docs/license notices explain incorporated code provenance

Documentation Changes

The documentation is updated to describe the new OpenClaw-owned architecture.

Major doc changes include:

• adds docs/agent-runtime-architecture.md
• renames docs/pi-dev.md to docs/openclaw-agent-runtime.md
• removes the old docs/pi.md
• updates agent runtime, agent loop, queue steering, model/provider, context engine, compaction, status, migration, and plugin architecture pages
• updates plugin bundle and SDK docs to reflect runtime ownership and plugin boundaries
• updates provider docs where provider behavior moved to provider/plugin ownership
• updates QA scenario names and docs away from Pi/Codex-specific legacy wording where OpenClaw runtime wording is now correct

Licensing And Notices

Because this PR internalizes code that originated in the Pi dependency shape, it updates repository notices:

• LICENSE gets the relevant additional copyright/provenance text.
• THIRD_PARTY_NOTICES.md records incorporated Pi-derived code.
• The changelog notes the agent runtime internalization/refactor.

macOS App Cleanup

The macOS app no longer carries its own static model catalog loader path from the old model-catalog architecture.

Removed:

• apps/macos/Sources/OpenClaw/ModelCatalogLoader.swift
• apps/macos/Tests/OpenClawIPCTests/ModelCatalogLoaderTests.swift
• associated debug/constants wiring for that removed catalog path

The app should consume the current OpenClaw model/provider surfaces instead of maintaining a parallel static catalog loader.

Build, Tooling, And CI Metadata

The PR updates build/test/tooling metadata to match the new package/runtime layout:

• workspace package metadata for packages/agent-core
• root package exports/dependencies
• package manager lock/shrinkwrap data
• tsconfig and tsdown package/build wiring
• plugin SDK entrypoint metadata and generated baseline hashes
• dependency ownership metadata
• test project/shard names
• CodeQL workflow/query references for renamed runtime boundaries
• docs/i18n and QA scenario references
• duplicate scan coverage remains valid

Review Shape

The branch is organized as a stack of focused commits rather than one giant mechanical blob.

Commit themes:

• extract the OpenClaw agent core package
• remove Pi runtime internals
• document the OpenClaw agent runtime cleanup
• decouple and make agent core runtime explicit
• consolidate compaction/runtime/session handling
• move model/provider ownership out of static Pi-era paths
• remove provider Pi auth and legacy runtime selection paths
• trim provider legacy paths and discovery fallbacks
• move CLI runtime ownership to plugins
• drop core provider alias normalization
• dedupe remaining helper implementations

Behavior Notes

Expected behavior should stay the same for normal OpenClaw users, except that internal ownership, docs, diagnostics, and developer-facing names now reflect OpenClaw instead of Pi.

Intentional behavior/architecture changes:

• provider-only dependencies are no longer root/core dependencies when a provider plugin owns them
• provider/model fallback paths that existed only for the old Pi dependency boundary are removed
• static root model catalog behavior is replaced by provider/manifest/runtime ownership
• internal callers are migrated to current OpenClaw SDK/runtime surfaces
• compatibility is treated as deprecated public boundary support, not internal architecture

Verification

Behavior addressed: fully internalize the old Pi-shaped agent runtime into OpenClaw-owned core/plugin/SDK surfaces; remove Pi-era runtime/provider/session duplication; keep only explicit deprecated compatibility at public/plugin boundaries; confirm no duplicate scan findings remain.

Real environment tested: local macOS checkout on branch refactor/openclaw-agent-runtime-cleanup at pushed head f650426d547d8d2b15d2cef3ca228dddd51dbdc3; AWS Crabbox Linux runner for broad changed gate before the final rebase, provider aws, lease cbx_9b165c987860, run run_958f0472af21.

Exact steps or command run after this patch:

• node scripts/run-vitest.mjs src/agents/sandbox/workspace-skills-bridge-readonly.test.ts src/llm/providers/google-shared.test.ts extensions/acpx/register.runtime.test.ts extensions/acpx/src/service.test.ts extensions/ollama/src/stream.test.ts src/plugin-sdk/api-baseline.test.ts src/plugin-sdk/channel-message.test.ts
• pnpm build
• node scripts/check-plugin-sdk-subpath-exports.mjs
• node scripts/sync-plugin-sdk-exports.mjs --check
• node scripts/check-extension-plugin-sdk-boundary.mjs
• git diff --check origin/main...HEAD
• pnpm dup:check:json
• .agents/skills/autoreview/scripts/autoreview --mode local --no-web-search
• Crabbox/AWS broad gate: pnpm crabbox:run -- --idle-timeout 90m --ttl 240m --timing-json --shell -- "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"

Evidence after fix:

• focused Vitest: 8 files passed, 45 tests passed
• build: passed, including plugin SDK export verification
• plugin SDK subpath export check: passed
• plugin SDK package export sync check: passed
• extension/plugin SDK boundary check: passed
• whitespace diff check: passed
• duplicate scan: 0 clones in production, tests, src-mixed, extensions-mixed, and test-mixed
• autoreview: autoreview clean: no accepted/actionable findings reported
• Crabbox/AWS pnpm check:changed: exit 0 on run run_958f0472af21, lease cbx_9b165c987860

Observed result after fix: OpenClaw builds with the new @openclaw/agent-core package and renamed runtime surfaces; focused ACPX/Ollama/Google/plugin-SDK/sandbox tests pass; SDK exports are consistent; plugin boundary guards pass; duplicate scanner reports zero clones across all configured targets; broad changed gate passed on AWS Crabbox before the final rebase; the branch is rebased onto current origin/main and pushed at f650426d547d8d2b15d2cef3ca228dddd51dbdc3.

What was not tested: full release packaging, full live provider authentication against every provider, macOS app UI runtime behavior, and a successful post-rebase Crabbox rerun. A post-rebase Crabbox attempt was made, but one AWS lease lost SSH after sync before command start and a retry lease never opened SSH during bootstrap; those were infrastructure failures before tests executed, not test failures. Post-rebase local focused tests and build passed.