Runtime Profile

Note

This document is informative, not normative. It provides recommended practices for CKP runtime implementers. Conformance is not affected by deviations from this profile.

---

Default values

When a manifest omits optional fields, runtimes SHOULD apply these defaults:

Primitive	Field	Default
Identity	autonomy	"supervised"
Identity	locale	"en-US"
Provider	streaming	false
Channel	access_control.mode	Implementation-defined
Sandbox	runtime	Inferred from level
Policy	prompt_injection.detection	"pattern"

---

Inline primitive name generation

When primitives are declared inline (without an explicit name), the runtime generates a name:

• Identity: Use the parent Claw manifest name
• Arrays: {kind}-{zero-indexed-position} (e.g., provider-0, channel-1)

Runtimes MUST detect name collisions and fail during INIT if two primitives of the same kind resolve to the same name.

---

Implicit CLI channel

When no Channel is declared, Level 1 runtimes SHOULD provide an implicit CLI channel:

• Transport: stdio (stdin/stdout)
• Access control: local process owner only
• No network listeners opened
• Not included in the manifest — purely a runtime convenience

This ensures Level 1 agents are immediately usable without configuration.

---

Extended error catalog

Beyond the core errors defined in Transport & Wire Format, runtimes SHOULD support:

Code	Name	Retryable	Description
-32020	Provider unavailable	Yes	LLM endpoint not responding
-32030	Memory backend error	Yes	Memory store read/write failed
-32040	Peer unreachable	Yes	Swarm peer not responding
-32050	Channel auth failed	Yes	Channel authentication rejected
-32051	Channel rate limited	Yes (after cooldown)	Channel rate limit exceeded
-32060	Manifest invalid	No	Manifest fails schema validation
-32061	Manifest incompatible	No	Primitive references unresolvable
-32070	Swarm topology error	No	Invalid swarm configuration
-32080	Memory compaction failed	Yes	Compaction operation failed

---

Retry semantics

For retryable errors, runtimes SHOULD implement exponential backoff:

delay = min(initial_delay * 2^attempt, max_delay)

Recommended values:

Parameter	Value
Initial delay	1 second
Max delay	30 seconds
Max attempts	3

Idempotency: Every retryable request MUST include a request_id (UUID v4). Runtimes SHOULD deduplicate requests with the same request_id within a 5-minute window.

---

Transport extensions

WebSocket

• Subprotocol: ckp-jsonrpc
• Keepalive: Ping every 30 seconds, timeout after 3 missed pongs
• Close codes: 4000 (normal CKP shutdown), 4001 (policy violation)

Message Queue (NATS, Redis)

• Subject naming: ckp.{agent-name}.{method} (e.g., ckp.research-assistant.tool.call)
• Delivery semantics: At-least-once with request_id deduplication
• Ordering: Not guaranteed — use request_id for correlation

Filesystem

• Write pattern: Atomic write to {dir}/{request_id}.json.tmp, then rename to {request_id}.json
• Read pattern: Watch or poll the directory for new .json files
• Archive: Move processed files to {dir}/archive/

---

Secret resolution

Runtimes SHOULD resolve secrets in this precedence order:

1. Runtime secret store (e.g., HashiCorp Vault, AWS Secrets Manager)
2. Environment variable (e.g., ANTHROPIC_API_KEY)
3. File at $CLAW_SECRETS_DIR/{name}

Security guidelines:

• NEVER log secret values
• NEVER include secrets in error messages or telemetry
• Fail with a clear error if a required secret is missing
• Rotate secrets without agent restart when possible

---

Memory consistency

• Default model: Eventual consistency
• Concurrent access: Optimistic concurrency via request_id
• Write conflicts: Last-write-wins unless the memory backend supports versioning
• Compaction: Runtimes SHOULD support claw.memory.compact to merge or summarize old entries

In CKP 0.3.0, runtimes MAY also interpret the optional cognitive hints on Memory stores:

• role helps separate working, episodic, semantic, and procedural memory responsibilities
• lifecycle guides acquisition, consolidation, and retrieval behavior
• forgetting guides decay or summarization of low-value state
• salience and confidence help rank retrievals or drive selective retention

These are intentionally descriptive rather than algorithmic. They should improve runtime behavior without creating a single mandatory memory algorithm.

---

WorldModel planning

CKP 0.3.0 introduces WorldModel as an optional primitive. It does not define new wire methods. This profile describes how runtimes can integrate predictive planning without changing the JSON-RPC surface.

Recommended planning loop

When a Skill references world_model_ref, or when runtime policy requires predictive planning, a runtime SHOULD:

1. Gather current task context and relevant Memory entries
2. Select the referenced WorldModel backend
3. Generate one or more bounded candidate futures
4. Score those futures against risk, cost, and task constraints
5. Choose an action, revise the plan, or fall back conservatively
6. Compare observed outcomes with predictions and update internal state

Adjustable policies

The values in WorldModel.spec.planning are intentionally policy-like:

• horizon: "adaptive" means the runtime chooses planning depth based on budget, latency, or task complexity
• uncertainty_mode: "bounded" means the runtime avoids overconfident plans when uncertainty grows too high
• fallback: "conservative" means the runtime prefers safer actions or supervised execution when predictions are weak

Runtimes SHOULD avoid treating these as fixed numeric defaults unless their deployment profile demands it.

Backend selection

• backend.type: "tool" is RECOMMENDED when prediction depends on an external simulator, search system, or environment model
• backend.type: "provider" is RECOMMENDED when the runtime uses an LLM or specialized model endpoint for rollouts
• backend.type: "custom" is RECOMMENDED for embedded or highly specialized deployments that do not expose the world model as a CKP Tool

If memory_ref is present, the runtime SHOULD load relevant memory before invoking the world model. If constraints.policy_ref is present, the runtime SHOULD apply that policy to planning-time side effects or expensive simulations.

Telemetry recommendations

When Telemetry is enabled, runtimes SHOULD emit:

• world_model_ops when predictions, simulations, or updates occur
• planning_ops when a plan is generated, revised, or downgraded
• prediction_error when realized outcomes diverge materially from the selected forecast
• plan_revision_count when multiple planning passes occur before action

---

Policy composition

When multiple policies apply to the same action, runtimes SHOULD evaluate them in declaration order:

1. First matching rule wins
2. If no rule matches, the default action is deny
3. Policies can be separated by concern (security, cost, compliance) and composed

policies:
  - name: security     # Evaluated first
    rules: [...]
  - name: compliance   # Evaluated second
    rules: [...]
  - name: cost         # Evaluated third
    rules: [...]

---

Tool execution lifecycle

1. Agent decides to call a tool
2. Policy evaluates the call → allow, deny, require-approval, or audit-only
3. If require-approval → pause and notify user via Channel
4. Sandbox allocates execution environment
5. Tool executes with configured timeout_ms
6. On timeout: send SIGTERM, wait 5s, send SIGKILL
7. Result returned to Agent (or error raised)
8. Telemetry event emitted (if configured)

Progress notifications (optional): Long-running tools MAY emit progress events during execution. The format is implementation-defined.