feat(atelier): worker_engine_factory state convention + helper

[veegee82]

Summary

Adds the optional state-key convention (state["worker_engine_factory"]) that lets host wrappers (AtelierOS, OpenClaw, ...) inject a WorkerEngine factory into the AWP state dict so workers can route their LLM calls through the host's engine layer instead of bypassing it.

This closes the architecture gap surfaced during AtelierOS Phase-4 integration: host-side engine_id audit events have no enclosing AWP-task-id correlation when AWP-workers reach for an LLM directly.

The convention is OPTIONAL — workers ignoring the key keep working exactly as before. Only workers wanting host-engine routing need to adopt it.

Changes

File	What
awp/atelier_integration.py	New helper module — extract_engine_factory, extract_engine_id, resolve_engine, has_atelier_context. Zero hard deps on AtelierOS; any host following the convention works.
spec/versions/1.0/layers/04-memory-state.md	Adds worker_engine_factory to the reserved-keys table in §2.3 with OPTIONAL status. Workers MUST NOT write to this key directly; the orchestrator (host) owns it.
reference/python/tests/test_atelier_integration.py	20 unittest cases covering all four helpers' happy + edge + failure paths.

Backwards compatibility

100%. Workers and hosts that don't know about this key see no behaviour change.

Test plan

• python -m unittest reference.python.tests.test_atelier_integration -v — 20/20 green
• AtelierOS-side wiring already injects the factory; verify a real AtelierOS+AWP round-trip surfaces it in state for a stub worker
• Worker-side adoption example to land in a follow-up PR

How a worker uses it

from awp.agent import AWPAgent
from awp.atelier_integration import resolve_engine

class MyWorker(AWPAgent):
    @property
    def name(self): return "my_worker"

    def run(self, task, state):
        engine = resolve_engine(state, "claude_code")
        if engine is not None:
            result = engine.spawn(prompt=task)
        else:
            result = self._internal_llm_call(task)
        return {self.name: {"result": result, "confidence": 0.9}}

Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agent-workflow-protocol	Error		May 10, 2026 7:37pm