claw3d/docs/integrations/custom-runtime-provider-spec.md

Custom Runtime Provider Spec

Generic extension seam for non-OpenClaw, non-Hermes stacks.

Goal

Define a clean custom runtime provider class for Claw3D.

This provider should let external orchestration stacks integrate with Claw3D through a stable seam without requiring:

• OpenClaw emulation
• Hermes-specific semantics
• named first-class core support for every stack

The idea is:

• upstream concept: custom provider
• downstream implementations provide their own runtime behavior against that seam

Current Branch Status

On dev/vera_lane, the custom provider is no longer just a design placeholder.

Current implemented behavior:

• custom is a first-class provider ID in the runtime seam
• Studio persists the selected backend mode as custom
• the provider exposes runtime metadata such as runtimeName, vendor, runtimeVersion, and routeProfile when available
• Claw3D probes GET /health, GET /state, and GET /registry
• chat uses a direct HTTP path to POST /v1/chat/completions
• browser traffic is proxied through Claw3D's same-origin /api/runtime/custom route instead of calling the runtime directly

Still intentionally missing in this branch:

• normalized streaming event support
• richer session persistence beyond the synthetic provider session layer
• direct approvals/files/cron surfaces
• process auto-launch from Studio

Why This Matters

Not every useful runtime should have to become a named built-in provider in upstream Claw3D.

A clean custom provider seam gives:

• extensibility
• lower upstream friction
• room for proprietary or stack-specific orchestration
• a path for advanced internal systems without polluting core abstractions

This is especially important when a stack is:

• internal
• organization-specific
• experimental
• orchestration-heavy

Product Position

The custom provider should be treated as:

• a first-class extension seam
• not a hack
• not a vendor-specific side path

This is the upstream-safe abstraction.

Relationship To Existing Provider Work

Claw3D’s runtime abstraction already points toward multiple providers:

• openclaw
• hermes
• future providers

The custom provider should sit alongside those as a generic lane for:

• external orchestrators
• private agent stacks
• organization-specific routing systems

Core Principle

Do not leak implementation-specific internal logic into the generic provider contract.

The provider should expose:

• common runtime behaviors
• provider capabilities
• normalized events
• optional metadata

It should not require upstream Claw3D to know:

• runtime-specific routing internals
• proprietary state logic
• private planning models
• stack-specific heuristics

Provider Identity

Suggested provider IDs:

• openclaw
• hermes
• custom

Then allow custom metadata such as:

type CustomRuntimeDescriptor = {
  providerId: "custom";
  runtimeName: string;
  runtimeVersion?: string | null;
  vendor?: string | null;
  capabilities?: string[];
};

This gives Claw3D enough identity for UI without hardcoding a brand into the provider class.

Reference Implementation Strategy

The custom provider should exist as a generic extension seam.

That means:

• upstream Claw3D gets custom
• downstream stacks supply their own behavior
• others can later implement their own custom providers against the same seam

That is much easier to justify upstream than:

• adding a deeply stack-specific built-in provider before the generic extension seam exists

Suggested Contract Shape

This should align with the existing runtime abstraction, but allow custom metadata.

Example:

type RuntimeProviderId = "openclaw" | "hermes" | "custom";

type RuntimeProviderMetadata = {
  id: RuntimeProviderId;
  label: string;
  runtimeName?: string | null;
  runtimeVersion?: string | null;
  vendor?: string | null;
};

The custom provider should still implement the same base runtime methods:

• list agents
• list sessions
• send chat
• abort run
• wait for run
• stream normalized events
• expose capabilities honestly

Capability Philosophy

The custom provider should be capability-driven, not assumption-driven.

That means if a custom stack supports:

• roles
• approvals
• files
• cron
• whiteboard integration
• meeting signals

it should declare those clearly.

If it does not, the UI should degrade honestly.

Event Model

The custom provider should emit the same normalized event categories as other providers.

Examples:

• presence.changed
• session.activity
• chat.delta
• chat.final
• chat.error
• run.lifecycle
• tool.progress

This keeps Claw3D stable even if the custom stack has richer private event semantics internally.

Custom Metadata Surface

The custom provider may optionally expose richer metadata for display.

Examples:

• routed lane
• active model id
• strategy label
• execution mode
• custom stack status

Important:

This metadata should be additive and optional.

It should not change the core runtime contract.

Reference Implementation Model

A custom provider can reasonably map:

• agents -> routed roles / lanes
• sessions -> runtime conversations
• streaming -> orchestrator or gateway output streams
• provider metadata -> runtime name, lane, model, or route state

The public upstream concept remains custom.

Implementation-specific mapping stays in the runtime layer.

Relationship To Agent State Model

The custom provider is the right place for richer internal state to enter Claw3D.

For example:

• a custom runtime computes deeper control or state signals
• the provider maps them into public office states

This keeps:

• internal intelligence private
• public office state understandable

Relationship To Office Systems

The custom provider should be able to support office systems without Claw3D needing to know the backend’s internals.

Examples:

• bulletin board gets agent/session/task context
• whiteboard gets planning-session context
• meetings get coordination state
• QA gets review or readiness metadata

Again, the custom provider should expose only what the office needs.

V1 Scope

Recommended V1 scope:

• define custom provider identity
• allow custom provider metadata
• ensure capability-driven UI behavior
• make no runtime-specific assumptions in core Claw3D

Actual runtime adapters can be implemented separately against that seam.

Out of Scope For V1

• embedding proprietary internal orchestration logic in Claw3D core
• hardcoding any one runtime as upstream architecture
• requiring all custom providers to support advanced signals

The point is generic extensibility first.

Implementation Strategy

Recommended order:

1. Add custom as a first-class runtime provider identity.
2. Add a metadata surface for runtime name/vendor/version.
3. Ensure the provider factory supports custom.
4. Keep the runtime event and capability model normalized.
5. Implement Vera as the first reference adapter outside the generic contract.

Success Criteria

This spec is successful if:

• upstream Claw3D gains a clean extension seam
• Vera can integrate without bloating core architecture
• future stacks can follow the same pattern
• the office systems continue to work against normalized runtime behavior

Summary

The custom runtime provider is the right upstream abstraction for stack-specific orchestrators.

It gives Claw3D extensibility, gives Vera a clean path in, and avoids hardwiring a personal stack directly into the core product model.