ouroboros-ai 0.27.3.dev4__tar.gz → 0.27.3.dev6__tar.gz

{ouroboros_ai-0.27.3.dev4 → ouroboros_ai-0.27.3.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.27.3.dev4
+Version: 0.27.3.dev6
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE
@@ -144,6 +144,13 @@ Legacy compatibility: `ouroboros-ai[dashboard]` is still accepted as a compatibi
 
 See runtime guides: [Claude Code](./docs/runtime-guides/claude-code.md) · [Codex CLI](./docs/runtime-guides/codex.md)
 
+Chat platform integration (OpenClaw / Slack / Discord):
+```bash
+clawhub install ouroboros                    # install OpenClaw skill
+openclaw mcp set ouroboros '{"command":"uvx","args":["--from","ouroboros-ai","ouroboros","mcp","serve"]}'
+```
+Guide: [Channel workflow integration](./docs/guides/openclaw-channel-workflow.md)
+
 </details>
 
 <details>

{ouroboros_ai-0.27.3.dev4 → ouroboros_ai-0.27.3.dev6}/README.md

@@ -105,6 +105,13 @@ Legacy compatibility: `ouroboros-ai[dashboard]` is still accepted as a compatibi
 
 See runtime guides: [Claude Code](./docs/runtime-guides/claude-code.md) · [Codex CLI](./docs/runtime-guides/codex.md)
 
+Chat platform integration (OpenClaw / Slack / Discord):
+```bash
+clawhub install ouroboros                    # install OpenClaw skill
+openclaw mcp set ouroboros '{"command":"uvx","args":["--from","ouroboros-ai","ouroboros","mcp","serve"]}'
+```
+Guide: [Channel workflow integration](./docs/guides/openclaw-channel-workflow.md)
+
 </details>
 
 <details>

{ouroboros_ai-0.27.3.dev4 → ouroboros_ai-0.27.3.dev6}/docs/api/mcp.md

@@ -247,6 +247,94 @@ class MCPServerInfo:
 
 ---
 
+## Ouroboros MCP Tools
+
+### Tool: `ouroboros_channel_workflow`
+
+Channel-native workflow orchestration surface intended for OpenClaw/Discord-style
+message transports.
+
+This tool wraps:
+
+- per-channel queueing
+- default repository mapping
+- input-detected entry points
+- interview / seed / execution handoff
+- execution status inspection
+- change-driven execution waiting
+
+#### Supported actions
+
+| Action | Purpose |
+|--------|---------|
+| `message` | Submit a new message or continue an interview |
+| `set_repo` | Configure the default repo for a channel |
+| `status` | Inspect current channel workflow state |
+| `poll` | Read the current active workflow state immediately |
+| `wait` | Wait for execution state to change via job wait |
+
+#### Parameters
+
+| Name | Type | Required | Notes |
+|------|------|----------|------|
+| `channel_id` | `string` | yes | Originating channel identifier |
+| `guild_id` | `string` | no | Optional guild/server identifier |
+| `user_id` | `string` | no | Optional caller/user identifier |
+| `message` | `string` | no | Channel message content or interview answer |
+| `repo` | `string` | no | Explicit repo override |
+| `seed_content` | `string` | no | Inline seed/spec payload |
+| `seed_path` | `string` | no | Seed path |
+| `action` | `string` | no | `message`, `set_repo`, `status`, `poll`, `wait` |
+| `mode` | `string` | no | For `message`: `auto`, `new`, `answer` |
+| `timeout_seconds` | `integer` | no | For `wait`: maximum wait duration |
+
+#### Stable response metadata
+
+The tool emits a stable metadata envelope with these keys:
+
+| Key | Meaning |
+|-----|---------|
+| `action` | Action that produced the response |
+| `channel_key` | Normalized channel key (`guild_id:channel_id` or `channel_id`) |
+| `workflow_id` | Workflow identifier when available |
+| `stage` | Workflow stage when available |
+| `entry_point` | Detected entry point (`interview` / `execution`) |
+| `repo` | Target repository when available |
+| `session_id` | Interview/runtime session identifier |
+| `execution_id` | Execution identifier |
+| `job_id` | Background job identifier |
+| `seed_id` | Generated seed identifier |
+| `pr_url` | Draft PR URL on success |
+| `job_status` | Underlying job status when waiting/running |
+| `cursor` | Last seen job cursor for wait semantics |
+| `changed` | Whether a `wait` call observed a change |
+| `ambiguity_score` | Interview ambiguity score when available |
+| `seed_ready` | Whether interview output is ready for seed generation |
+| `next_workflow_started` | Whether queue advancement started the next workflow |
+| `duplicate_delivery` | True when an inbound message was treated as a redelivery |
+| `duplicate_of` | Existing workflow ID reused for a duplicate delivery |
+| `active` | Used by `status` / `poll` / `wait` summaries when no active workflow exists |
+
+#### Example
+
+```python
+result = await client.call_tool(
+    "ouroboros_channel_workflow",
+    {
+        "action": "message",
+        "channel_id": "123",
+        "guild_id": "guild-1",
+        "user_id": "user-42",
+        "message": "work on issue #320",
+    },
+)
+
+print(result.value.text_content)
+print(result.value.meta["workflow_id"])
+```
+
+---
+
 ## Error Hierarchy
 
 All MCP-specific exceptions inherit from `MCPError`, which inherits from `OuroborosError`.

ouroboros_ai-0.27.3.dev6/docs/contributing/openclaw-current-baseline.md

@@ -0,0 +1,53 @@
+# OpenClaw Workflow Current Baseline
+
+This note records the current verification baseline while the OpenClaw channel
+workflow work is still in progress.
+
+## What is green
+
+The OpenClaw-focused scope currently passes targeted verification:
+
+- `ruff` for the OpenClaw-related files
+- `mypy` for `src/ouroboros/openclaw` and `channel_workflow_handler.py`
+- targeted OpenClaw unit/integration suites
+
+Examples of green scope:
+
+- contracts
+- command parsing
+- workflow state / queue logic
+- duplicate-delivery protection
+- wait-driven orchestration
+- transport bridge
+- MCP server wiring for `ouroboros_channel_workflow`
+
+## What is not yet green
+
+The full repository-wide test suite is not currently all-green.
+When last checked, the failing set was dominated by existing non-OpenClaw areas such as:
+
+- orchestrator runner / cancellation
+- full workflow e2e
+- session persistence e2e
+- unrelated event tests present in the working tree
+
+These failures should not be interpreted as evidence that the OpenClaw workflow
+scaffold itself is broken. They indicate that the repository baseline is broader
+than the current OpenClaw change set.
+
+## Recommended verification posture for this work
+
+Until the broader suite is stabilized, treat this as the primary confidence bar:
+
+1. targeted OpenClaw tests must remain green
+2. ruff + mypy on OpenClaw-related files must remain green
+3. transport-facing contracts and metadata shape should stay stable
+
+## Why this note exists
+
+This project currently has a mismatch between:
+
+- "OpenClaw-specific work is passing"
+- "the entire repository test suite is green"
+
+Writing that down explicitly reduces confusion during ongoing iteration.

ouroboros_ai-0.27.3.dev6/docs/guides/openclaw-channel-workflow.md

@@ -0,0 +1,152 @@
+# Channel Workflow Integration
+
+This guide explains how to connect a chat platform (OpenClaw, Slack, Discord,
+or any MCP-capable client) to the Ouroboros `ouroboros_channel_workflow` MCP
+tool for channel-native workflow orchestration.
+
+## What this tool does
+
+`ouroboros_channel_workflow` provides a transport-agnostic orchestration layer for:
+
+- per-channel queueing
+- default repository mapping per channel
+- input-detected entry points (interview vs. direct execution)
+- in-channel interview bridging
+- change-driven execution waiting and result reporting
+
+## Setup
+
+### 1. Install Ouroboros
+
+```bash
+pip install ouroboros-ai
+# or
+uv tool install ouroboros-ai
+```
+
+### 2. Register Ouroboros MCP server in OpenClaw
+
+```bash
+openclaw mcp set ouroboros '{"command":"uvx","args":["--from","ouroboros-ai","ouroboros","mcp","serve"]}'
+```
+
+Verify the registration:
+
+```bash
+openclaw mcp list
+openclaw mcp show ouroboros
+```
+
+### 3. Install the OpenClaw skill
+
+From ClawHub:
+
+```bash
+clawhub install ouroboros
+```
+
+Or manually copy `skills/ouroboros/SKILL.md` into your OpenClaw skills directory.
+
+### 4. Test the connection
+
+```bash
+# Using mcporter (ad-hoc MCP tool call)
+mcporter call ouroboros.ouroboros_channel_workflow \
+  action=status channel_id=test
+
+# Or via OpenClaw agent — prefix with ooo in any channel:
+# ooo interview add dark mode to settings
+```
+
+### Usage
+
+All commands are prefixed with `ooo`:
+
+```
+ooo interview <request>    Start a requirements interview
+ooo seed                   Generate seed from current interview
+ooo run <description>      Start execution
+ooo eval                   Evaluate current execution
+ooo status                 Check workflow state
+ooo poll                   Poll execution progress
+ooo wait                   Long-poll for changes
+ooo repo <path>            Set default repo for channel
+ooo <answer text>          Answer an interview question
+```
+
+## Supported actions
+
+### `action="set_repo"`
+
+Configure the default repo for a channel.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `channel_id` | yes | Channel identifier |
+| `guild_id` | no | Guild/server identifier |
+| `repo` | yes | Repository path |
+
+### `action="message"`
+
+Handle a user message — starts interview or execution based on input detection.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `channel_id` | yes | Channel identifier |
+| `message` | yes | User message content |
+| `guild_id` | no | Guild/server identifier |
+| `user_id` | no | Caller identifier |
+| `repo` | no | Explicit repo override |
+| `seed_content` | no | Inline seed/spec YAML |
+| `seed_path` | no | Path to seed file |
+| `mode` | no | `auto`, `new`, or `answer` |
+| `message_id` | no | Transport message ID for dedup |
+| `event_id` | no | Transport event ID for dedup |
+
+### `action="status"`
+
+Inspect current channel workflow state.
+
+### `action="poll"`
+
+Read the current active workflow state immediately.
+
+### `action="wait"`
+
+Wait for execution state to change (long-poll).
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `timeout_seconds` | no | Max wait duration (default: 30) |
+
+## Entry point detection
+
+The tool automatically detects the appropriate starting stage:
+
+- **Vague natural-language request** → starts an interview
+- **Issue / feature discussion** → starts an interview
+- **Seed/spec-like YAML payload** → skips to execution
+
+## Queue behavior
+
+- One active workflow per channel
+- Additional requests are queued
+- Workflows in other channels remain independent
+- Queue advances automatically when a workflow completes or fails
+
+## Response metadata
+
+Every response includes a stable metadata envelope:
+
+| Key | Description |
+|-----|-------------|
+| `action` | Action that produced the response |
+| `channel_key` | Normalized channel key |
+| `workflow_id` | Workflow identifier |
+| `stage` | Current workflow stage |
+| `entry_point` | Detected entry point (`interview` / `execution`) |
+| `repo` | Target repository |
+| `session_id` | Interview/runtime session ID |
+| `job_id` | Background job ID |
+| `job_status` | Underlying job status |
+| `duplicate_delivery` | True if message was a redelivery |

ouroboros_ai-0.27.3.dev6/skills/openclaw/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: ouroboros
+description: "When user message starts with 'ooo', call ouroboros_channel_workflow MCP tool. Do NOT answer the request yourself. Do NOT generate code. Do NOT summarize. Just call the tool and relay the response."
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🐍",
+        "requires": { "mcp": ["ouroboros"] },
+      },
+  }
+---
+
+# Ouroboros
+
+## Rule
+
+When a user message starts with `ooo`, you MUST:
+
+1. Call `ouroboros_channel_workflow` MCP tool
+2. Relay the tool response back to the channel
+3. Do NOTHING else
+
+Do NOT:
+- Answer the request yourself
+- Generate code or specs
+- Summarize or reinterpret the request
+- Offer alternatives or next steps
+- Ask clarifying questions yourself
+
+The Ouroboros MCP server handles all logic: interviewing, seed generation,
+execution, and status tracking. Your only job is to be a relay.
+
+## Setup
+
+```bash
+openclaw mcp set ouroboros '{"command":"uvx","args":["--from","ouroboros-ai","ouroboros","mcp","serve"]}'
+```
+
+## Routing
+
+Strip `ooo ` prefix. Match the first word:
+
+| First word | Tool arguments |
+|---|---|
+| `interview <text>` | `action: "message", mode: "new", message: "<text>"` |
+| `seed` | `action: "message", mode: "new", message: "generate seed"` |
+| `run <text>` | `action: "message", mode: "new", message: "<text>"` |
+| `eval` | `action: "message", mode: "new", message: "evaluate"` |
+| `status` | `action: "status"` |
+| `poll` | `action: "poll"` |
+| `wait` | `action: "wait", timeout_seconds: 30` |
+| `repo <path>` | `action: "set_repo", repo: "<path>"` |
+| anything else | `action: "message", mode: "answer", message: "<full text>"` |
+
+Always include `channel_id`, `guild_id`, `user_id` from message context.
+Always include `message_id` for dedup when available.
+
+## Example
+
+User: `ooo add dark mode to settings`
+
+You call:
+
+```json
+{
+  "tool": "ouroboros_channel_workflow",
+  "arguments": {
+    "action": "message",
+    "channel_id": "C123",
+    "guild_id": "G456",
+    "user_id": "U789",
+    "message": "add dark mode to settings",
+    "mode": "new"
+  }
+}
+```
+
+Then post the tool response text to the channel. Nothing more.
+
+User: `ooo yes use CSS variables`
+
+You call:
+
+```json
+{
+  "tool": "ouroboros_channel_workflow",
+  "arguments": {
+    "action": "message",
+    "channel_id": "C123",
+    "guild_id": "G456",
+    "user_id": "U789",
+    "message": "yes use CSS variables",
+    "mode": "answer"
+  }
+}
+```
+
+Then post the tool response text to the channel. Nothing more.

{ouroboros_ai-0.27.3.dev4 → ouroboros_ai-0.27.3.dev6}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.27.3.dev4'
-__version_tuple__ = version_tuple = (0, 27, 3, 'dev4')
+__version__ = version = '0.27.3.dev6'
+__version_tuple__ = version_tuple = (0, 27, 3, 'dev6')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.27.3.dev4 → ouroboros_ai-0.27.3.dev6}/src/ouroboros/mcp/server/adapter.py

@@ -735,6 +735,7 @@ def create_ouroboros_server(
         ACDashboardHandler,
         CancelExecutionHandler,
         CancelJobHandler,
+        ChannelWorkflowHandler,
         EvaluateHandler,
         EvolveRewindHandler,
         EvolveStepHandler,
@@ -755,6 +756,7 @@ def create_ouroboros_server(
     from ouroboros.mcp.tools.pm_handler import PMInterviewHandler
     from ouroboros.mcp.tools.qa import QAHandler
     from ouroboros.mcp.tools.registry import ToolRegistry
+    from ouroboros.openclaw.workflow import ChannelRepoRegistry, ChannelWorkflowManager
     from ouroboros.orchestrator import create_agent_runtime, resolve_agent_runtime_backend
     from ouroboros.orchestrator.runner import (
         OrchestratorRunner,
@@ -788,8 +790,8 @@ def create_ouroboros_server(
 
     # Create state directory for interviews
     if state_dir is None:
-        state_dir = Path.home() / ".ouroboros" / "data"
-        state_dir.mkdir(parents=True, exist_ok=True)
+        state_dir = Path.cwd() / ".ouroboros" / "data"
+    state_dir.mkdir(parents=True, exist_ok=True)
 
     # Create core service instances
     interview_engine = InterviewEngine(
@@ -1255,6 +1257,9 @@ def create_ouroboros_server(
         validator=_evolution_validator,
     )
     job_manager = JobManager(event_store)
+    openclaw_db_path = state_dir / "openclaw.db"
+    workflow_manager = ChannelWorkflowManager(openclaw_db_path)
+    repo_registry = ChannelRepoRegistry(openclaw_db_path)
 
     # Create tool registry for dependency injection
     registry = ToolRegistry()
@@ -1319,6 +1324,39 @@ def create_ouroboros_server(
             llm_backend=llm_backend,
         ),
         BrownfieldHandler(),
+        ChannelWorkflowHandler(
+            workflow_manager=workflow_manager,
+            repo_registry=repo_registry,
+            interview_handler=InterviewHandler(
+                interview_engine=interview_engine,
+                event_store=event_store,
+                llm_adapter=llm_adapter,
+                llm_backend=llm_backend,
+            ),
+            generate_seed_handler=GenerateSeedHandler(
+                interview_engine=interview_engine,
+                seed_generator=seed_generator,
+                llm_adapter=llm_adapter,
+                llm_backend=llm_backend,
+            ),
+            start_execute_seed_handler=StartExecuteSeedHandler(
+                execute_handler=execute_seed,
+                event_store=event_store,
+                job_manager=job_manager,
+            ),
+            job_status_handler=JobStatusHandler(
+                event_store=event_store,
+                job_manager=job_manager,
+            ),
+            job_wait_handler=JobWaitHandler(
+                event_store=event_store,
+                job_manager=job_manager,
+            ),
+            job_result_handler=JobResultHandler(
+                event_store=event_store,
+                job_manager=job_manager,
+            ),
+        ),
         EvaluateHandler(
             event_store=event_store,
             llm_adapter=llm_adapter,

{ouroboros_ai-0.27.3.dev4 → ouroboros_ai-0.27.3.dev6}/src/ouroboros/mcp/tools/__init__.py

@@ -14,6 +14,7 @@ from ouroboros.mcp.tools.definitions import (
     ACTreeHUDHandler,
     CancelExecutionHandler,
     CancelJobHandler,
+    ChannelWorkflowHandler,
     EvaluateHandler,
     EvolveRewindHandler,
     EvolveStepHandler,
@@ -32,6 +33,7 @@ from ouroboros.mcp.tools.definitions import (
     StartExecuteSeedHandler,
     ac_tree_hud_handler,
     cancel_job_handler,
+    channel_workflow_handler,
     evaluate_handler,
     evolve_rewind_handler,
     evolve_step_handler,
@@ -58,6 +60,7 @@ __all__ = [
     "BrownfieldHandler",
     "CancelExecutionHandler",
     "CancelJobHandler",
+    "ChannelWorkflowHandler",
     "EvaluateHandler",
     "EvolveRewindHandler",
     "EvolveStepHandler",
@@ -78,6 +81,7 @@ __all__ = [
     "ToolRegistry",
     "ac_tree_hud_handler",
     "cancel_job_handler",
+    "channel_workflow_handler",
     "evaluate_handler",
     "evolve_rewind_handler",
     "evolve_step_handler",