cleveragents/cleveractors-core

Fork 0

Align cleveractors-core to The Actor Configuration Standard v1.0.0 #9

New issue

Open

opened 2026-05-27 07:44:46 +00:00 by hurui200320 · 2 comments

hurui200320 commented

2026-05-27 07:44:46 +00:00

Member

Overview

The Actor Configuration Standard (actors-spec) v1.0.0 is the normative YAML schema, runtime semantics, and security model that all compliant implementations must satisfy. cleveractors-core is the Python reference implementation, but a thorough audit reveals significant divergences:

Many §16 forbidden patterns (deprecated YAML forms) are silently accepted instead of rejected
The three-phase template lifecycle (Phase A pre-YAML / Phase B instantiation / Phase C per-message) is not fully implemented per spec
The four loop-detection guards (§6.8) use ad-hoc print(..., sys.stderr) signalling rather than spec-defined semantics
sandbox.py defines SAFE_BUILTINS but ToolAgent builds its own parallel dict and never imports it
§12 Runtime Behavior (lifecycle ordering, message structure, standard metadata keys, [TOOL_EXECUTE:] block processing, routing prefix stripping, stream-route cycle detection) has no designated owner
§17 Compliance Test Vectors (12 test categories) are entirely uncovered — there is no structured verification suite
Domain-specific constants (scientific-paper-writer routing prefixes, minimal_context paper keys) are hardcoded in the framework core
session.py is a one-line placeholder; network.py raises NotImplementedError; the lsp/ module has no source files
The Actor Registry Standard (actor-registry-standard.md) — a complete HTTP API for content-addressed package storage — is entirely unimplemented
typeCheckingMode is set to "off" in pyrightconfig.json

This Legendary tracks all work to bring cleveractors-core into full conformance with both standards documents.

Spec Documents

Actor Configuration Standard: actors-spec/docs/index.md (v1.0.0)
Actor Registry Standard: actors-spec/docs/actor-registry-standard.md (v1.0.0)

Child Epics

Epic A1 — §3.1 + §11 + §16 + §20: Validation, Forbidden Patterns, File Merging, and Error Taxonomy

Enforce all §11 pre-instantiation validation rules and all §16 forbidden patterns as hard rejections. Currently accepted (and silently ignored) patterns that must produce ConfigurationError include: top-level streams: / graphs: sections, list-form routes with from:/to: shorthand, agent_template: key, strategy: on composite agent, dynamic_router node type, short-form bare-string prompts, sequence-form template parameters, template+type coexisting on the same agent, and prompt+prompt_reference on a chain agent.

Additional scope beyond the original 9-epic draft:

§3.1 Deep-merge semantics: implement the 4-rule algorithm for multi-file config loading (absent → add; mapping+mapping → recursive merge; sequence+sequence → append; otherwise replace)
§20 Error taxonomy enforcement: ensure metadata.error_type is populated with the correct §20 category on every error emitted to __error__; ensure AgentCreationError is raised for unavailable providers (not ConfigurationError)
§9.5 / §9.6: advisory fields (verbose, logging.level, version) must be accepted without error even if they are not acted on

Epic A2 — §4: Agent Type Completeness

Verify and complete all five agent types against the full §4 behavioral spec:

LLM (§4.4): all three required providers (case-insensitive), default model per provider, structured output (response_format with JSON schema forwarding), memory list capped at max_history, conversation_history context pass-through when memory_enabled: false, _temperature_override context key, system prompt rendered at invocation with context+message (warn and use literal on failure)
Tool (§4.5): align _execute_python_code to use sandbox.py's SAFE_BUILTINS (currently a parallel dict); the 5-step tool invocation dispatch algorithm (single inline-code tool → full message; JSON with tool key; JSON parse failure error; space-separated command; unknown tool error); all seven built-in tools with their exact argument semantics; file_write modes (w/a/insert, position semantics); progress bar facility (24-cell bar, █/░, percentage to 1 decimal, counter, optional label, trailing newline at 100%)
Composite (§4.6): enforce strategy: key prohibition (already in §16; verify enforcement path)
template_instance (§4.8): verify full support
Chain (§4.7): enforce prompt/prompt_reference mutual exclusion; verify "ChainAgent processed: " prefix + " -> " separator semantics; no external calls
§4.9 Context inheritance: global context (context.global) MUST be merged into each agent's config.context at creation time unless the agent declares its own
§4.11 Capabilities & Metadata: each agent must expose the standard capabilities list and metadata mapping; the 15 standard capability identifier strings ("text-generation", "conversation", "reasoning", "analysis", "creative-writing", "structured-output", "tool-execution", "command-execution", "http-requests", "file-operations", "math-evaluation", "composite", "stateful-workflow", "reactive-processing", "chain-processing") must all be supported; required per-agent metadata fields: name, type, capabilities, reactive: true

Epic A3 — §5 + §7.3: Stream Routes, Operators, Conditions, Bridge Routes, and Pipelines

Implement all 19 stream operators per §5.3 with exact semantics (including the 4 bridge operators: graph_execute, state_update, state_checkpoint, graph_node). Enforce subscriptions as informational-only (canonical wiring is via merges only; no auto-subscription from subscriptions list). Deprecate the merges: [{sources: [__input__], target: ...}] default-router approach in favour of the default_router parameter.

Additional scope:

§5.3.4 Agent mapper contract: 5-point contract — context resolution order, 120 s hard timeout, error message format "Error: <reason>", processed_by metadata key, metadata.context propagation into outgoing messages
§5.4 Conditions per-subsystem: each condition type is only honored in its designated subsystem (e.g. source_is only in stream-router; context_value/output_pattern/message_pattern only in pure-graph edges; custom only in conditional graph nodes); §5.4.2 default-behavior table (stream-router → True on unknown type; bridge conditional_route → False; pure-graph edges → True with warning; conditional graph nodes → True)
§5.5 At-most-once delivery guarantee on publications (prevent double-delivery when a publications target is also a merge/split source)
§5.6 Bridge Routes: all fields (upgrade_conditions, downgrade_conditions, state_extractor, state_flattener, preserve_subscriptions, preserve_checkpointing); all 7 bridge condition keys; advisory-only semantics (implementations MAY not act but MUST NOT reject valid bridge declarations)
§7.3 Pipelines behavioral semantics: sequential stage chaining (output of stage N feeds input of stage N+1); MUST accept, MAY warn on discouraged patterns

Epic A4 — §6: Graph Route Completeness

Complete all seven node types including message_router with all five match modes (prefix/suffix/contains/regex/exact) and their extraction semantics. Implement the four §6.8 loop-detection guards with the precise auto_finish_active bypass, 200-character fingerprint, and routing token list (GOTO_, ROUTE_, SET_, CMD_, DISCOVERY_RESPONSE, AUTO_SECTIONS_COMPLETE, COMMAND_OUTPUT). Replace print(..., file=sys.stderr) loop signals with proper exception/return-value semantics. Implement checkpointing + time travel (§6.6) and parallel node execution (§6.7). Implement pure-graph mode (§6.9) with post-execution context promotion.

Additional scope:

§6.3.2 State update modes: implement replace, merge (default — deep for dicts, extend for lists), append
§6.3.3 Custom state schemas: state_class resolution; default fallback with warning on unknown class
§6.11 Setup-time graph analysis: 6 required analyses — adjacency, cycle detection, topological levels, reachability (warn on unreachable nodes), edge validation, entry-point validation; currently only cycle detection is partially implemented
§6.10 Graph-internal streams: in non-pure mode, per-node streams __<graph>_node_<node>__, __<graph>_control__, __<graph>_state__ must be created with the correct reserved-name pattern

Epic A5 — §8: Three-Phase Template System

Implement the complete three-phase template lifecycle:

Phase A (pre-YAML): Jinja2 rendering of the YAML document itself using sentinel strings (<<<TEMPLATE_START>>> / <<<TEMPLATE_END>>> / <<<BLOCK_START>>> / <<<BLOCK_END>>>) to protect system_prompt expressions during document parsing
Phase B (component instantiation): template parameter validation, default fill, deep-copy, expression rendering, scalar coercion, empty-conditional elimination, agent_ref/component_ref resolution (local composite → outer actor scope)
Phase C (per-message runtime): system prompt and prompts re-rendered per invocation with live context; on failure, warn and use literal text

Add template_strings: section support for templates whose {% for %} loops generate YAML keys. Verify all §8.3 built-in callables and filters for all three template engines (JINJA2, MUSTACHE, SIMPLE). Verify SIMPLE dialect's two-pass behavior (expression sandbox first, then format-string substitution).

Additional scope:

§8.8 Scalar coercion: after Phase B expression rendering, coerce rendered string scalars to typed forms: "true"/"false" → bool, integer patterns → int, float patterns → float, valid JSON arrays/objects → list/dict
§8.12 Render-failure policy: Phase A failure → ConfigurationError (fatal); Phase B failure → ConfigurationError; Phase C failure → warn and use literal unrendered text (processing continues)

Epic A6 — §13: Security Model

Align sandbox built-in allowlists to the two distinct §13 sets:

§13.2.1 Inline tool code: bool, dict, float, int, list, set, str, tuple, abs, all, any, enumerate, len, max, min, range, reversed, round, sorted, sum, zip, isinstance, type, locals, print, ValueError, IndexError, KeyError, TypeError, json module only
§13.2.2 Expression evaluation: bool, dict, float, int, list, set, str, tuple, abs, all, any, len, max, min, round, sum only (smaller set; no json, no exception types, no isinstance)

Consolidate all sandboxed execution to use a single source-of-truth dict (currently sandbox.py defines SAFE_BUILTINS but ToolAgent builds its own parallel dict). Enforce two-factor file_write restriction (safe_mode: false alone is insufficient — also requires _unsafe_mode: true in invocation context). Shell command blocklist (rm, del, format, shutdown, reboot, kill) applies in all modes regardless of safe/unsafe state.

Epic A7 — §10 + §14: Context, Environment Variables, and Prompts

Complete global context inheritance per §4.9. Implement env var type coercion per §14 (when interpolation is the entire string value: "true"/"false" → bool, integer patterns → int, float patterns → float; coercion applies recursively to all nested mappings and sequences). Enforce long-form prompts (reject bare-string prompts values; require {content: ...} mapping; silently skip non-conforming entries per §10.4).

Verify §10.3 reserved context key enforcement: all 19 reserved keys documented in the spec; user keys MUST NOT begin with __; keys beginning with _ are strongly discouraged.

Epic A8 — Actor Registry Standard: Package Registry HTTP API

Implement the HTTP API defined in actor-registry-standard.md:

All 8 required endpoints: GET /packages/{package_id}, GET /{type}/{namespace}/{name}?version={v}, POST /publish, GET /browse, GET /.well-known/cleverrouter-packages
Content-addressed immutable package storage: key = SHA-1 of canonical RFC-8785 JSON form
Version alias system: vX.Y.Z (immutable), vX.Y.x / vX.x / latest (mutable aliases)
Canonicalization pipeline: parse YAML → Unicode NFC normalize → sort dict keys → strip lifecycle fields → resolve internal references → RFC-8785 canonical JSON → SHA-1
All 8 package types: actor, graph, stream, agent, template, skill, mcp, lsp
Auth: anonymous read for public packages MUST be supported; publishing requires API key or OAuth2
Circular dependency detection: MUST be rejected

Epic A9 — Code Quality: Framework Depollution and Technical Debt

Remove all domain-specific constants from framework core: _strip_routing_prefixes's hardcoded paper-writer prefix list in application.py, minimal_context's paper-domain keys in config_parser.py, paper-stage list in routing_adapter.py
Implement or explicitly remove session.py (1-line placeholder) and network.py (NotImplementedError)
Recover or remove the lsp/ module (only .pyc files present; no source)
Enable Pyright type checking (typeCheckingMode: "standard" or "strict") and resolve all errors
Fix composite.py parameter propagation stub
§21 Versioning: add conformance declaration against spec v1.0.0 in library metadata
§2 Terminology: ensure framework domain constants (class names, error names, field names) are consistent with spec terminology (Actor, Agent, Route, Stream, Graph, Bridge, Node, Edge, Operator, Merge, Split, Template, Context, Message)

Epic A10 — §12: Runtime Behavior

This section has no current owner and covers cross-cutting contracts that all other epics depend on for correctness.

§12.1 Lifecycle ordering: enforce the 8-step startup sequence as an integrated contract — Load+merge configs → Register templates → Create agents (abort on failure) → Set up routes → Set up merges/splits → Set up pipelines → Run → Cleanup on shutdown. Wrong ordering (e.g., routes set up before agents) can cause silent failures.
§12.2.1 Message structure: the 4 required observable properties (content, metadata, source_stream, timestamp) must be present on all messages; metadata.context MUST be preserved by reference on message copy; all other metadata MUST be shallow-copied (not deep-copied)
§12.2.1 Standard metadata keys: implement the full table of 14 standard keys (context, _unsafe_mode, processed_by, error, error_type, timeout, state_updated, checkpointed, graph, node, execution_history, execution_count, final_state, source) and the rules for when each must be set
§12.2.2 Within-stream ordering guarantee: messages MUST be delivered in order within a single stream; out-of-order delivery is a conformance violation
§12.2.3 Error emit format: any agent or operator error MUST emit to __error__ with content: <error string>, metadata.error: true, metadata.error_type: <§20 category>; downstream pipeline continues
§12.4 [TOOL_EXECUTE:] block processing: 5-rule algorithm — detect [TOOL_EXECUTE:<name>]...[/TOOL_EXECUTE] blocks across multiple lines in LLM output; sanitize JSON (escape unescaped backslashes, newlines, tabs, carriage returns); execute tool; substitute result in reverse-match order
§12.5 Routing prefix stripping: the 7 spec-defined prefixes (GOTO_<TARGET>:, ROUTE_<TARGET>:, SET_<KEY>:, CMD_<KEY>:, COMMAND_OUTPUT:, DISCOVERY_RESPONSE:, AUTO_SECTIONS_COMPLETE:) must be stripped from __output__ before exposing to the consumer; the current implementation has a hardcoded paper-writer-specific list (addressed in A9) and must be replaced with the spec-defined set
§12.6 Stream-route cycle detection: detect publication/subscription cycles at load time or runtime; report as error if the cycle would be unbounded (distinct from graph loop detection in §6.8, which is addressed in A4)

Epic A11 — §17: Compliance Test Vectors

Build a structured compliance test suite covering all 12 §17 test vector categories. Without this epic, there is no systematic evidence that any other epic's work actually satisfies the spec. The 12 categories are:

Minimal valid configs (accept) + structurally invalid configs (reject)
All agent types: llm, tool, composite, chain, template_instance
All stream operators (all 19)
All condition types in their designated subsystems
Graph routes: linear, branching, conditional, looping, parallel
Message router: all 5 match types (prefix, suffix, contains, regex, exact) with extraction
Templates and instances: parameter validation, rendering, inheritance
Environment variable interpolation: required, defaulted, type coercion
Merges and splits: behavioral semantics, edge cases
Error scenarios: each §20 error type raised in its correct context
Security boundaries: safe-mode restrictions, unsafe-mode permissions, sandbox allowlist enforcement
State persistence: checkpointing, restore, time travel

Success Criteria

All 12 §17 compliance test vector categories have passing tests
No §16 forbidden pattern is silently accepted — all produce ConfigurationError
typeCheckingMode enabled with zero type errors
No domain-specific constants exist in framework core
Package Registry API responds correctly to all 8 required endpoints
SAFE_BUILTINS is the single source of truth for all sandboxed execution, with the correct two-set split (§13.2.1 vs §13.2.2)
§12 Runtime Behavior contracts (lifecycle order, message structure, metadata keys, error emit format) are verified by tests

## Overview The Actor Configuration Standard (`actors-spec`) v1.0.0 is the normative YAML schema, runtime semantics, and security model that all compliant implementations must satisfy. `cleveractors-core` is the Python reference implementation, but a thorough audit reveals significant divergences: - Many §16 forbidden patterns (deprecated YAML forms) are silently accepted instead of rejected - The three-phase template lifecycle (Phase A pre-YAML / Phase B instantiation / Phase C per-message) is not fully implemented per spec - The four loop-detection guards (§6.8) use ad-hoc `print(..., sys.stderr)` signalling rather than spec-defined semantics - `sandbox.py` defines `SAFE_BUILTINS` but `ToolAgent` builds its own parallel dict and never imports it - §12 Runtime Behavior (lifecycle ordering, message structure, standard metadata keys, `[TOOL_EXECUTE:]` block processing, routing prefix stripping, stream-route cycle detection) has no designated owner - §17 Compliance Test Vectors (12 test categories) are entirely uncovered — there is no structured verification suite - Domain-specific constants (scientific-paper-writer routing prefixes, `minimal_context` paper keys) are hardcoded in the framework core - `session.py` is a one-line placeholder; `network.py` raises `NotImplementedError`; the `lsp/` module has no source files - The Actor Registry Standard (`actor-registry-standard.md`) — a complete HTTP API for content-addressed package storage — is entirely unimplemented - `typeCheckingMode` is set to `"off"` in `pyrightconfig.json` This Legendary tracks all work to bring `cleveractors-core` into full conformance with both standards documents. ## Spec Documents - **Actor Configuration Standard:** `actors-spec/docs/index.md` (v1.0.0) - **Actor Registry Standard:** `actors-spec/docs/actor-registry-standard.md` (v1.0.0) ## Child Epics ### Epic A1 — §3.1 + §11 + §16 + §20: Validation, Forbidden Patterns, File Merging, and Error Taxonomy Enforce all §11 pre-instantiation validation rules and all §16 forbidden patterns as hard rejections. Currently accepted (and silently ignored) patterns that must produce `ConfigurationError` include: top-level `streams:` / `graphs:` sections, list-form `routes` with `from:`/`to:` shorthand, `agent_template:` key, `strategy:` on composite agent, `dynamic_router` node type, short-form bare-string prompts, sequence-form template parameters, `template`+`type` coexisting on the same agent, and `prompt`+`prompt_reference` on a chain agent. Additional scope beyond the original 9-epic draft: - **§3.1 Deep-merge semantics:** implement the 4-rule algorithm for multi-file config loading (absent → add; mapping+mapping → recursive merge; sequence+sequence → append; otherwise replace) - **§20 Error taxonomy enforcement:** ensure `metadata.error_type` is populated with the correct §20 category on every error emitted to `__error__`; ensure `AgentCreationError` is raised for unavailable providers (not `ConfigurationError`) - **§9.5 / §9.6:** advisory fields (`verbose`, `logging.level`, `version`) must be accepted without error even if they are not acted on ### Epic A2 — §4: Agent Type Completeness Verify and complete all five agent types against the full §4 behavioral spec: - **LLM (§4.4):** all three required providers (case-insensitive), default model per provider, structured output (`response_format` with JSON schema forwarding), memory list capped at `max_history`, `conversation_history` context pass-through when `memory_enabled: false`, `_temperature_override` context key, system prompt rendered at invocation with `context`+`message` (warn and use literal on failure) - **Tool (§4.5):** align `_execute_python_code` to use `sandbox.py`'s `SAFE_BUILTINS` (currently a parallel dict); the 5-step tool invocation dispatch algorithm (single inline-code tool → full message; JSON with `tool` key; JSON parse failure error; space-separated command; unknown tool error); all seven built-in tools with their exact argument semantics; `file_write` modes (`w`/`a`/`insert`, `position` semantics); progress bar facility (24-cell bar, `█`/`░`, percentage to 1 decimal, counter, optional label, trailing newline at 100%) - **Composite (§4.6):** enforce `strategy:` key prohibition (already in §16; verify enforcement path) - **template_instance (§4.8):** verify full support - **Chain (§4.7):** enforce `prompt`/`prompt_reference` mutual exclusion; verify `"ChainAgent processed: "` prefix + `" -> "` separator semantics; no external calls - **§4.9 Context inheritance:** global context (`context.global`) MUST be merged into each agent's `config.context` at creation time unless the agent declares its own - **§4.11 Capabilities & Metadata:** each agent must expose the standard `capabilities` list and `metadata` mapping; the 15 standard capability identifier strings (`"text-generation"`, `"conversation"`, `"reasoning"`, `"analysis"`, `"creative-writing"`, `"structured-output"`, `"tool-execution"`, `"command-execution"`, `"http-requests"`, `"file-operations"`, `"math-evaluation"`, `"composite"`, `"stateful-workflow"`, `"reactive-processing"`, `"chain-processing"`) must all be supported; required per-agent metadata fields: `name`, `type`, `capabilities`, `reactive: true` ### Epic A3 — §5 + §7.3: Stream Routes, Operators, Conditions, Bridge Routes, and Pipelines Implement all 19 stream operators per §5.3 with exact semantics (including the 4 bridge operators: `graph_execute`, `state_update`, `state_checkpoint`, `graph_node`). Enforce `subscriptions` as informational-only (canonical wiring is via `merges` only; no auto-subscription from `subscriptions` list). Deprecate the `merges: [{sources: [__input__], target: ...}]` default-router approach in favour of the `default_router` parameter. Additional scope: - **§5.3.4 Agent mapper contract:** 5-point contract — context resolution order, 120 s hard timeout, error message format `"Error: <reason>"`, `processed_by` metadata key, `metadata.context` propagation into outgoing messages - **§5.4 Conditions per-subsystem:** each condition type is only honored in its designated subsystem (e.g. `source_is` only in stream-router; `context_value`/`output_pattern`/`message_pattern` only in pure-graph edges; `custom` only in conditional graph nodes); §5.4.2 default-behavior table (stream-router → True on unknown type; bridge `conditional_route` → False; pure-graph edges → True with warning; conditional graph nodes → True) - **§5.5 At-most-once delivery guarantee** on publications (prevent double-delivery when a `publications` target is also a merge/split source) - **§5.6 Bridge Routes:** all fields (`upgrade_conditions`, `downgrade_conditions`, `state_extractor`, `state_flattener`, `preserve_subscriptions`, `preserve_checkpointing`); all 7 bridge condition keys; advisory-only semantics (implementations MAY not act but MUST NOT reject valid bridge declarations) - **§7.3 Pipelines behavioral semantics:** sequential stage chaining (output of stage N feeds input of stage N+1); MUST accept, MAY warn on discouraged patterns ### Epic A4 — §6: Graph Route Completeness Complete all seven node types including `message_router` with all five match modes (prefix/suffix/contains/regex/exact) and their extraction semantics. Implement the four §6.8 loop-detection guards with the precise `auto_finish_active` bypass, 200-character fingerprint, and routing token list (`GOTO_`, `ROUTE_`, `SET_`, `CMD_`, `DISCOVERY_RESPONSE`, `AUTO_SECTIONS_COMPLETE`, `COMMAND_OUTPUT`). Replace `print(..., file=sys.stderr)` loop signals with proper exception/return-value semantics. Implement checkpointing + time travel (§6.6) and parallel node execution (§6.7). Implement pure-graph mode (§6.9) with post-execution context promotion. Additional scope: - **§6.3.2 State update modes:** implement `replace`, `merge` (default — deep for dicts, extend for lists), `append` - **§6.3.3 Custom state schemas:** `state_class` resolution; default fallback with warning on unknown class - **§6.11 Setup-time graph analysis:** 6 required analyses — adjacency, cycle detection, topological levels, reachability (warn on unreachable nodes), edge validation, entry-point validation; currently only cycle detection is partially implemented - **§6.10 Graph-internal streams:** in non-pure mode, per-node streams `__<graph>_node_<node>__`, `__<graph>_control__`, `__<graph>_state__` must be created with the correct reserved-name pattern ### Epic A5 — §8: Three-Phase Template System Implement the complete three-phase template lifecycle: - **Phase A** (pre-YAML): Jinja2 rendering of the YAML document itself using sentinel strings (`<<<TEMPLATE_START>>>` / `<<<TEMPLATE_END>>>` / `<<<BLOCK_START>>>` / `<<<BLOCK_END>>>`) to protect `system_prompt` expressions during document parsing - **Phase B** (component instantiation): template parameter validation, default fill, deep-copy, expression rendering, scalar coercion, empty-conditional elimination, `agent_ref`/`component_ref` resolution (local composite → outer actor scope) - **Phase C** (per-message runtime): system prompt and prompts re-rendered per invocation with live context; on failure, warn and use literal text Add `template_strings:` section support for templates whose `{% for %}` loops generate YAML keys. Verify all §8.3 built-in callables and filters for all three template engines (JINJA2, MUSTACHE, SIMPLE). Verify SIMPLE dialect's two-pass behavior (expression sandbox first, then format-string substitution). Additional scope: - **§8.8 Scalar coercion:** after Phase B expression rendering, coerce rendered string scalars to typed forms: `"true"`/`"false"` → `bool`, integer patterns → `int`, float patterns → `float`, valid JSON arrays/objects → `list`/`dict` - **§8.12 Render-failure policy:** Phase A failure → `ConfigurationError` (fatal); Phase B failure → `ConfigurationError`; Phase C failure → warn and use literal unrendered text (processing continues) ### Epic A6 — §13: Security Model Align sandbox built-in allowlists to the two distinct §13 sets: - **§13.2.1 Inline tool code:** `bool`, `dict`, `float`, `int`, `list`, `set`, `str`, `tuple`, `abs`, `all`, `any`, `enumerate`, `len`, `max`, `min`, `range`, `reversed`, `round`, `sorted`, `sum`, `zip`, `isinstance`, `type`, `locals`, `print`, `ValueError`, `IndexError`, `KeyError`, `TypeError`, `json` module only - **§13.2.2 Expression evaluation:** `bool`, `dict`, `float`, `int`, `list`, `set`, `str`, `tuple`, `abs`, `all`, `any`, `len`, `max`, `min`, `round`, `sum` only (smaller set; no `json`, no exception types, no `isinstance`) Consolidate all sandboxed execution to use a single source-of-truth dict (currently `sandbox.py` defines `SAFE_BUILTINS` but `ToolAgent` builds its own parallel dict). Enforce two-factor `file_write` restriction (`safe_mode: false` alone is insufficient — also requires `_unsafe_mode: true` in invocation context). Shell command blocklist (`rm`, `del`, `format`, `shutdown`, `reboot`, `kill`) applies in all modes regardless of safe/unsafe state. ### Epic A7 — §10 + §14: Context, Environment Variables, and Prompts Complete global context inheritance per §4.9. Implement env var type coercion per §14 (when interpolation is the entire string value: `"true"`/`"false"` → `bool`, integer patterns → `int`, float patterns → `float`; coercion applies recursively to all nested mappings and sequences). Enforce long-form prompts (reject bare-string `prompts` values; require `{content: ...}` mapping; silently skip non-conforming entries per §10.4). Verify §10.3 reserved context key enforcement: all 19 reserved keys documented in the spec; user keys MUST NOT begin with `__`; keys beginning with `_` are strongly discouraged. ### Epic A8 — Actor Registry Standard: Package Registry HTTP API Implement the HTTP API defined in `actor-registry-standard.md`: - All 8 required endpoints: `GET /packages/{package_id}`, `GET /{type}/{namespace}/{name}?version={v}`, `POST /publish`, `GET /browse`, `GET /.well-known/cleverrouter-packages` - Content-addressed immutable package storage: key = SHA-1 of canonical RFC-8785 JSON form - Version alias system: `vX.Y.Z` (immutable), `vX.Y.x` / `vX.x` / `latest` (mutable aliases) - Canonicalization pipeline: parse YAML → Unicode NFC normalize → sort dict keys → strip lifecycle fields → resolve internal references → RFC-8785 canonical JSON → SHA-1 - All 8 package types: `actor`, `graph`, `stream`, `agent`, `template`, `skill`, `mcp`, `lsp` - Auth: anonymous read for public packages MUST be supported; publishing requires API key or OAuth2 - Circular dependency detection: MUST be rejected ### Epic A9 — Code Quality: Framework Depollution and Technical Debt - Remove all domain-specific constants from framework core: `_strip_routing_prefixes`'s hardcoded paper-writer prefix list in `application.py`, `minimal_context`'s paper-domain keys in `config_parser.py`, paper-stage list in `routing_adapter.py` - Implement or explicitly remove `session.py` (1-line placeholder) and `network.py` (`NotImplementedError`) - Recover or remove the `lsp/` module (only `.pyc` files present; no source) - Enable Pyright type checking (`typeCheckingMode: "standard"` or `"strict"`) and resolve all errors - Fix `composite.py` parameter propagation stub - **§21 Versioning:** add conformance declaration against spec v1.0.0 in library metadata - **§2 Terminology:** ensure framework domain constants (class names, error names, field names) are consistent with spec terminology (Actor, Agent, Route, Stream, Graph, Bridge, Node, Edge, Operator, Merge, Split, Template, Context, Message) ### Epic A10 — §12: Runtime Behavior This section has no current owner and covers cross-cutting contracts that all other epics depend on for correctness. - **§12.1 Lifecycle ordering:** enforce the 8-step startup sequence as an integrated contract — Load+merge configs → Register templates → Create agents (abort on failure) → Set up routes → Set up merges/splits → Set up pipelines → Run → Cleanup on shutdown. Wrong ordering (e.g., routes set up before agents) can cause silent failures. - **§12.2.1 Message structure:** the 4 required observable properties (`content`, `metadata`, `source_stream`, `timestamp`) must be present on all messages; `metadata.context` MUST be preserved by reference on message copy; all other metadata MUST be shallow-copied (not deep-copied) - **§12.2.1 Standard metadata keys:** implement the full table of 14 standard keys (`context`, `_unsafe_mode`, `processed_by`, `error`, `error_type`, `timeout`, `state_updated`, `checkpointed`, `graph`, `node`, `execution_history`, `execution_count`, `final_state`, `source`) and the rules for when each must be set - **§12.2.2 Within-stream ordering guarantee:** messages MUST be delivered in order within a single stream; out-of-order delivery is a conformance violation - **§12.2.3 Error emit format:** any agent or operator error MUST emit to `__error__` with `content: <error string>`, `metadata.error: true`, `metadata.error_type: <§20 category>`; downstream pipeline continues - **§12.4 `[TOOL_EXECUTE:]` block processing:** 5-rule algorithm — detect `[TOOL_EXECUTE:<name>]...[/TOOL_EXECUTE]` blocks across multiple lines in LLM output; sanitize JSON (escape unescaped backslashes, newlines, tabs, carriage returns); execute tool; substitute result in reverse-match order - **§12.5 Routing prefix stripping:** the 7 spec-defined prefixes (`GOTO_<TARGET>:`, `ROUTE_<TARGET>:`, `SET_<KEY>:`, `CMD_<KEY>:`, `COMMAND_OUTPUT:`, `DISCOVERY_RESPONSE:`, `AUTO_SECTIONS_COMPLETE:`) must be stripped from `__output__` before exposing to the consumer; the current implementation has a hardcoded paper-writer-specific list (addressed in A9) and must be replaced with the spec-defined set - **§12.6 Stream-route cycle detection:** detect publication/subscription cycles at load time or runtime; report as error if the cycle would be unbounded (distinct from graph loop detection in §6.8, which is addressed in A4) ### Epic A11 — §17: Compliance Test Vectors Build a structured compliance test suite covering all 12 §17 test vector categories. Without this epic, there is no systematic evidence that any other epic's work actually satisfies the spec. The 12 categories are: 1. Minimal valid configs (accept) + structurally invalid configs (reject) 2. All agent types: `llm`, `tool`, `composite`, `chain`, `template_instance` 3. All stream operators (all 19) 4. All condition types in their designated subsystems 5. Graph routes: linear, branching, conditional, looping, parallel 6. Message router: all 5 match types (prefix, suffix, contains, regex, exact) with extraction 7. Templates and instances: parameter validation, rendering, inheritance 8. Environment variable interpolation: required, defaulted, type coercion 9. Merges and splits: behavioral semantics, edge cases 10. Error scenarios: each §20 error type raised in its correct context 11. Security boundaries: safe-mode restrictions, unsafe-mode permissions, sandbox allowlist enforcement 12. State persistence: checkpointing, restore, time travel ## Success Criteria - All 12 §17 compliance test vector categories have passing tests - No §16 forbidden pattern is silently accepted — all produce `ConfigurationError` - `typeCheckingMode` enabled with zero type errors - No domain-specific constants exist in framework core - Package Registry API responds correctly to all 8 required endpoints - `SAFE_BUILTINS` is the single source of truth for all sandboxed execution, with the correct two-set split (§13.2.1 vs §13.2.2) - §12 Runtime Behavior contracts (lifecycle order, message structure, metadata keys, error emit format) are verified by tests

hurui200320 added the

labels

2026-05-27 07:44:56 +00:00

hurui200320 commented

2026-05-27 07:57:28 +00:00

Author

Member

This epic drafting should cover the full actors-spec as of commit cleveragents/actors-spec@76e4299ae7, I haven't created those epics yet as the quick review shows that certain part of the spec may need to be updated. Once the spec is in good shape, I'll review the epic draft and create them.

This epic drafting should cover the full actors-spec as of commit https://git.cleverthis.com/cleveragents/actors-spec/commit/76e4299ae7fe13af8edba0d5bd9a0380a03e3f37, I haven't created those epics yet as the quick review shows that certain part of the spec may need to be updated. Once the spec is in good shape, I'll review the epic draft and create them.

hurui200320 commented

2026-05-27 14:56:42 +00:00

Author

Member

As of 2026 May 27, in the scrum meeting, Jeff advises Luis Mendes to prioritize integrating v2 as a stable working version, even if it disagrees with the spec. So for CleverRouter, I will start integrating the current version of CleverActors right away. This epic should be suspended for now.