agent-workflow-ui 1.0.0__tar.gz

agent_workflow_ui-1.0.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: agent-workflow-ui
+Version: 1.0.0
+Summary: MCP plugin that gives opencode agents tools for visual interaction (HTML forms, dashboards) with users
+Author: EnerJize
+License: MIT
+Project-URL: Homepage, https://github.com/EnerJizeIT/agentic-workflow
+Project-URL: Repository, https://github.com/EnerJizeIT/agentic-workflow
+Project-URL: Issues, https://github.com/EnerJizeIT/agentic-workflow/issues
+Keywords: opencode,mcp,ai-agent,pipeline,dashboard,forms
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: awf>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+
+# agent-workflow-ui
+
+MCP plugin для opencode. 29 typed tools (5 UI + 24 workflow).
+
+## Установка
+
+```bash
+pip install -e ".[dev]"
+```
+
+Plugin автоматически регистрируется в opencode через `awf init`.
+
+## Tools
+
+### UI (5)
+`open_form`, `read_submit`, `cancel_form`, `list_pending_forms`, `list_templates`
+
+### Workflow (24)
+`awf_init`, `awf_status`, `awf_start`, `awf_continue`, `awf_kill`, `awf_retry_stage`, `awf_baseline`, `awf_rollback`, `awf_approve`, `awf_reject`, `awf_report`, `awf_reset`, `awf_add_role`, `awf_analyze_roles`, `awf_dispatch_todo`, `awf_load_supervisor_context`, `awf_open_project_setup_form`, `awf_open_increment_planning_form`, `awf_open_pipeline_dashboard`, `awf_wait_for_event`, `awf_check_model_config`, `awf_current_step`, `awf_set_goal`, `awf_confirm_normalized`
+
+Все workflow tools возвращают `next_action` — guide для supervisor.
+
+## Структура
+
+```
+src/agent_workflow_ui/
+├── server.py              # MCP server, 29 tools
+├── tools/awf.py           # 24 awf wrappers (asyncio.to_thread + next_action)
+├── tools/forms.py         # 5 UI wrappers
+├── http_endpoint.py       # Form HTTP server
+├── opencode_config.py     # Model discovery
+├── roles_processor.py     # Role setup materialization
+├── state.py               # Form state persistence
+└── render/                # Jinja2 templates
+```
+
+Все workflow tools — thin async wrappers над `awf.api.*()`. Бизнес-логика в `awf`.

agent_workflow_ui-1.0.0/README.md

@@ -0,0 +1,37 @@
+# agent-workflow-ui
+
+MCP plugin для opencode. 29 typed tools (5 UI + 24 workflow).
+
+## Установка
+
+```bash
+pip install -e ".[dev]"
+```
+
+Plugin автоматически регистрируется в opencode через `awf init`.
+
+## Tools
+
+### UI (5)
+`open_form`, `read_submit`, `cancel_form`, `list_pending_forms`, `list_templates`
+
+### Workflow (24)
+`awf_init`, `awf_status`, `awf_start`, `awf_continue`, `awf_kill`, `awf_retry_stage`, `awf_baseline`, `awf_rollback`, `awf_approve`, `awf_reject`, `awf_report`, `awf_reset`, `awf_add_role`, `awf_analyze_roles`, `awf_dispatch_todo`, `awf_load_supervisor_context`, `awf_open_project_setup_form`, `awf_open_increment_planning_form`, `awf_open_pipeline_dashboard`, `awf_wait_for_event`, `awf_check_model_config`, `awf_current_step`, `awf_set_goal`, `awf_confirm_normalized`
+
+Все workflow tools возвращают `next_action` — guide для supervisor.
+
+## Структура
+
+```
+src/agent_workflow_ui/
+├── server.py              # MCP server, 29 tools
+├── tools/awf.py           # 24 awf wrappers (asyncio.to_thread + next_action)
+├── tools/forms.py         # 5 UI wrappers
+├── http_endpoint.py       # Form HTTP server
+├── opencode_config.py     # Model discovery
+├── roles_processor.py     # Role setup materialization
+├── state.py               # Form state persistence
+└── render/                # Jinja2 templates
+```
+
+Все workflow tools — thin async wrappers над `awf.api.*()`. Бизнес-логика в `awf`.

agent_workflow_ui-1.0.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-workflow-ui"
+version = "1.0.0"
+description = "MCP plugin that gives opencode agents tools for visual interaction (HTML forms, dashboards) with users"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "EnerJize" }]
+keywords = ["opencode", "mcp", "ai-agent", "pipeline", "dashboard", "forms"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp>=1.0",
+    "jinja2>=3.1",
+    "pyyaml>=6.0",
+    "awf>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/EnerJizeIT/agentic-workflow"
+Repository = "https://github.com/EnerJizeIT/agentic-workflow"
+Issues = "https://github.com/EnerJizeIT/agentic-workflow/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[project.scripts]
+agent-workflow-ui = "agent_workflow_ui.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["agent_workflow_ui*"]
+
+[tool.setuptools.package-data]
+agent_workflow_ui = ["render/default_templates/*.j2", "SKILL.md"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+# F: pyflakes (real bugs)
+# E/W: pycodestyle (PEP 8)
+# I: isort (import sorting)
+# UP: pyupgrade (modernize syntax)
+select = ["F", "E", "W", "I", "UP"]
+ignore = [
+    "E501",  # line too long — handled by formatter, not linter
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "F841",  # unused local variables (test fixtures often have them)
+    "E501",
+]

agent_workflow_ui-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_workflow_ui-1.0.0/src/agent_workflow_ui/SKILL.md

@@ -0,0 +1,258 @@
+# Agent Workflow UI
+
+MCP plugin for [opencode](https://opencode.ai/) that gives agents tools for visual
+interaction with users: HTML forms for structured input, dashboards for monitoring.
+
+Use forms when chat is inefficient for the task at hand. Forms are a supplement
+to chat, not a replacement.
+
+## When to use a form
+
+**For project setup** (configuring pipeline + roles + models + supervisor):
+use `awf_open_project_setup_form(project_dir)` — dedicated shortcut tool.
+Plugin auto-populates roles/models/skills. Do NOT call `open_form`
+directly for project setup, do NOT study template structure.
+
+**For increment planning** (choosing decomposition strategy):
+use `awf_open_increment_planning_form(variants, project_dir)` — user
+picks from supervisor-generated variants.
+
+**For pipeline monitoring** (watching agents work):
+use `awf_open_pipeline_dashboard(project_dir)` — live dashboard with
+auto-refresh 5s. Ask user before opening.
+
+**For supervisor wake-up** (no more polling):
+use `awf_wait_for_event(project_dir, timeout=120)` — ONE call blocks
+until verify/blocked/checkpoint/done. Replaces sleep+status loops.
+
+Call `open_form` directly when:
+
+- **A file upload** is needed (ТЗ, product-vision, custom role `.md`).
+- **Ad-hoc decision forks** with custom template you created.
+- Monitoring a **long-running pipeline** (→ dashboard, see above).
+
+## When NOT to use a form (use chat instead)
+
+- A simple **Y/N** answer.
+- Choosing between **2-3 short options**.
+- **Clarifying questions** during work.
+- **Tone calibration** or approach discussion.
+- Anything that can be answered in one line of text.
+
+## Usage pattern — NON-BLOCKING
+
+**Always use `open_form` (non-blocking). Never use `open_form_and_wait` (it is not registered as MCP tool anyway).**
+
+1. Agent decides a form is needed.
+2. Call `open_form(template="...", data={...})` — opens form, returns `form_id` immediately.
+3. Tell the user in CLI: **"I opened a form in your browser. Fill it out, click Submit, then tell me here when you're done."**
+4. Agent is now **free** — can continue other work, answer questions, or wait for the user.
+5. When the user types something in CLI (e.g., "done", "submitted", "I filled it"):
+   - Call `read_submit(form_id)` to retrieve the submitted data.
+   - Analyze `data` and proceed.
+
+**Why non-blocking?**
+
+The agent stays responsive. The user controls the pace — they fill the form
+when ready, then explicitly tell the agent to proceed. This avoids the agent
+"hanging" silently while the user is still thinking.
+
+**Critical:** You MUST tell the user to come back to CLI and notify you after
+submitting. The form's "Submitted!" page also reminds them, but you should
+say it in your message too.
+
+### What to tell the user
+
+After calling `open_form`, ALWAYS say something like:
+
+> "I've opened a form in your browser (Form ID: FORM-...).
+> Please fill it out and click Submit.
+> When done, come back here and tell me — I'll pick up your answers."
+
+### When the user says "done" / "submitted" / "filled it"
+
+Call `read_submit(form_id)` immediately to get the data. Don't make the user
+repeat themselves. If `read_submit` returns `submitted: false`, tell the user
+the form hasn't been submitted yet and ask them to check.
+
+## Tool reference
+
+### `open_form(template, data, project_dir?, ttl_seconds?)` — PRIMARY TOOL
+
+Render and open an HTML form in the user's browser. Non-blocking — returns immediately.
+
+**Arguments:**
+- `template` (str, required) — Template name without extension (e.g., "project-setup").
+- `data` (dict, optional) — Variables to render in the template.
+- `project_dir` (str, optional but **required for project-setup**) — Absolute path to awf project root. When provided, submit triggers automatic materialization via `awf.api.apply_project_setup` (writes pipeline.yaml, patches config.yaml + supervisor.md). Without it, submit is saved to `inputs/` only — agent must materialize manually. MCP subprocess runs in $HOME, so cwd-based detection does NOT work — pass explicitly.
+- `ttl_seconds` (int, optional) — Auto-expire form after N seconds.
+
+**Returns:** `{form_id, browser_opened, submit_url, expires_at?, error?}`
+
+**MUST for project-setup:** Always pass `project_dir` explicitly:
+```python
+open_form(template="project-setup", data={...}, project_dir="/abs/path/to/project")
+```
+
+### `read_submit(form_id)` — USE WHEN USER SAYS "DONE"
+
+Check if user submitted the form. Non-blocking — returns immediately.
+
+**Returns:** `{submitted, form_id, status, data?, submitted_at?, error?}`
+
+**Status values:** `pending`, `submitted`, `cancelled`, `expired`, `unknown`, `error`
+
+### `cancel_form(form_id)`
+
+Cancel a pending form. Future HTTP submits for this form_id are ignored.
+
+**Returns:** `{cancelled, form_id, reason?}`
+
+### `list_pending_forms()`
+
+List forms opened but not yet submitted, cancelled, or expired.
+
+**Returns:** `{pending: [{form_id, template, opened_at, age_seconds}], count}`
+
+### `list_templates()`
+
+List available form templates with metadata.
+
+**Returns:** `{templates: [{name, source, description, required_data_keys, optional_data_keys}]}`
+
+## Available templates
+
+Call `list_templates` to see what's available at runtime.
+
+### Primary (MVP)
+
+| Template | Description | Required data keys |
+|---|---|---|
+| `project-setup` | Composite form: context + ТЗ files + supervisor + team (with models). Models pulled from opencode automatically. | `available_roles` |
+
+Plugin injects automatically into every template:
+- `form_id`, `submit_url`, `template_name`
+- `available_models`, `recent_models` (from opencode CLI + SQLite history)
+- `custom_supervisor_roles`, `custom_agents` (from `~/.config/awf/roles/`)
+- `existing_supervisor_slugs`, `existing_agent_slugs` (for client-side conflict detection)
+
+### Future templates
+
+Templates for scenarios 2-6 (decision forks, blockage recovery, dashboards, priority planning, onboarding wizard) will be added as those scenarios are implemented. Currently only `project-setup` ships as a default template.
+
+**Until future scenarios are implemented:** Use `project-setup` for project configuration. Use chat for everything else.
+
+## Creating new templates (agent-driven)
+
+**Only the agent (you, LLM) can create new templates.** The user does not edit `.agentic/templates/` manually — if a custom form is needed, you create it.
+
+### How to create a new template
+
+1. **Front (HTML form):** write a Jinja2 template at `.agentic/templates/<name>.html.j2`. Structure:
+   ```jinja2
+   ---
+   description: What this form does
+   required_data_keys:
+     - some_required_var
+   optional_data_keys:
+     - some_optional_var
+   ---
+   <!DOCTYPE html>
+   <html>
+   <head><title>...</title></head>
+   <body>
+     <form action="{{ submit_url }}" method="POST">
+       <input type="hidden" name="form_id" value="{{ form_id }}">
+       <!-- form fields here -->
+       <button type="submit">Submit</button>
+     </form>
+   </body>
+   </html>
+   ```
+
+2. **Back (interpretation):** describe in supervisor.md (or in your response to the user) how to interpret the submit data. Plugin's HTTP endpoint saves the raw form data to `inputs/<form_id>.yaml` — you read it via `read_submit` and parse the fields yourself.
+
+3. **Use:** call `open_form(template="<name>", data={...})`. Plugin's `ChoiceLoader` finds project templates first, then defaults — so your new template is available immediately.
+
+### Template variables available
+
+Every template gets these injected by plugin:
+- `{{ form_id }}` — current form ID
+- `{{ submit_url }}` — POST endpoint
+- `{{ template_name }}` — current template name
+- `{{ available_models }}`, `{{ recent_models }}` — opencode models
+- `{{ custom_supervisor_roles }}`, `{{ custom_agents }}` — saved roles
+- Plus any keys you pass in `data` argument
+
+### Important rules
+
+- Always use `<form action="{{ submit_url }}" method="POST">` — that's how submits reach the plugin.
+- Always include `<input type="hidden" name="form_id" value="{{ form_id }}">`.
+- Plugin uses Jinja2 with autoescape — user input is safe.
+- YAML frontmatter is stripped from output automatically.
+
+## Mistakes to avoid
+
+- **DO NOT** use blocking wait tools — they are not registered. Use `open_form` + user notification pattern.
+- **DO NOT** forget to tell the user to come back to CLI after submitting.
+- **DO NOT** open a form for Y/N questions — use chat.
+- **DO NOT** open more than 3 forms simultaneously — the user will be confused.
+- **DO NOT** use forms as a chat replacement — they're a supplement.
+- **DO NOT** invent template names — only `project-setup` ships as default. Future scenarios will add more.
+
+## Example workflow
+
+```
+Agent: "I need to configure your project. Let me open a form."
+
+→ open_form(template="project-setup", project_dir="/abs/path/to/project", data={"available_roles": [
+    {"id": "backend-dev", "title": "Backend Developer"},
+    {"id": "frontend-dev", "title": "Frontend Developer"},
+    {"id": "tester", "title": "Tester"}
+  ]})
+  Returns: {form_id: "FORM-20260726143022-a1b2", browser_opened: true, submit_url: "..."}
+
+Agent (to user): "I've opened project setup form in your browser.
+                   Fill context, pick supervisor, build your team, click Submit.
+                   When done, tell me here."
+
+[Agent is free — can answer other questions, do other work, or wait]
+
+User (in CLI): "Done!"
+
+→ read_submit("FORM-20260726143022-a1b2")
+  Returns: {submitted: true, data: {
+    context_message: "...",
+    team_config: '[{"type":"default","agent":"backend-dev","model":"anthropic/claude-3.5"}]',
+    spec_files_json: '[...]',
+    ...
+  }}
+
+After submit, plugin writes:
+- Custom roles to global + project (BD-3-B, BD-5).
+- Pipeline stages to .agentic/pipelines/default.yaml (BD-9).
+- Per-role models to .agentic/config.yaml (BD-32).
+
+Next `awf start` runs the pipeline. Supervisor (interactive session or
+subprocess in --auto mode) creates TODO from phases/plan.md, agents
+execute, supervisor verifies.
+
+Optional: run `awf analyze-roles` (BD-31) before `awf start` if roles
+have overlapping zones — adds disambiguation patches to role files.
+
+Agent (to user): "Got it. Generating .agentic/config.yaml and roles/..."
+[Agent writes project files using its own tools — plugin does NOT generate them]
+```
+
+## Troubleshooting
+
+- **Browser didn't open:** The `open_form` result may have `browser_opened: false`
+  with an error message. Tell the user the form HTML is at a local file path, or
+  offer to collect the answer via chat instead.
+- **User can't access browser (SSH/remote):** Offer a CLI fallback — ask the user
+  to type their choice in the chat. Call `cancel_form` to clean up.
+- **User says "done" but read_submit returns `submitted: false`:** The user may
+  have closed the form without submitting. Ask them to check and submit again.
+- **Form expired:** If `read_submit` returns `status: "expired"`, open a new form
+  with a longer TTL or ask via chat.
+- **Conflict on save:** If the user is saving a custom role with a name that already exists, the form will show a JS confirm dialog. If they confirm — overwrite; if cancel — they change the name or uncheck save.

agent_workflow_ui-1.0.0/src/agent_workflow_ui/__init__.py

@@ -0,0 +1,2 @@
+"""agent-workflow-ui — MCP plugin for visual interaction in opencode workflows."""
+__version__ = "0.1.0"

agent_workflow_ui-1.0.0/src/agent_workflow_ui/__main__.py

@@ -0,0 +1,64 @@
+"""Entry point: python -m agent_workflow_ui"""
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+from .config import detect_project_dir, ensure_directories, load
+from .http_endpoint import start_http_server
+from .opencode_config import read_opencode_models, read_recent_models
+from .render.engine import create_env
+from .server import create_server
+from .skill_installer import ensure_skill_installed
+from .state import get_registry, set_config, set_http_port, set_jinja_env, set_project_dir
+
+log = logging.getLogger(__name__)
+
+DEFAULT_TEMPLATES_DIR = Path(__file__).parent / "render" / "default_templates"
+
+
+def main() -> int:
+    """Run the MCP server on stdio transport, with HTTP endpoint in background."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+    try:
+        # Lazy skill install: copy SKILL.md to ~/.config/opencode/skills/agent-workflow-ui/
+        # Idempotent — overwrites if bundled version differs. No-op if already current.
+        ensure_skill_installed()
+
+        config = load()
+        ensure_directories(config)
+        set_config(config)
+        set_project_dir(detect_project_dir())
+
+        env = create_env([config.templates_dir, DEFAULT_TEMPLATES_DIR])
+        env.globals["available_models"] = read_opencode_models()
+        env.globals["recent_models"] = read_recent_models()
+        set_jinja_env(env)
+
+        registry = get_registry()
+        server, port = start_http_server(config, registry)
+        set_http_port(port)
+        log.info("agent_workflow_ui started (HTTP on port %d)", port)
+
+        mcp = create_server()
+        mcp.run()  # blocks; stdio transport
+
+        server.shutdown()
+        return 0
+    except KeyboardInterrupt:
+        log.info("agent_workflow_ui interrupted by user")
+        return 130
+    except Exception:
+        log.exception("agent_workflow_ui crashed during startup/runtime")
+        print("FATAL: agent_workflow_ui failed to start", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_workflow_ui-1.0.0/src/agent_workflow_ui/browser.py

@@ -0,0 +1,70 @@
+"""Cross-platform browser open via stdlib subprocess."""
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def detect_open_command(configured: str = "auto") -> str:
+    """Detect the platform-appropriate command to open a file in the browser.
+
+    Args:
+        configured: "auto" for platform detection, or an explicit command name.
+
+    Returns:
+        Command string: "xdg-open" (Linux), "open" (macOS), "explorer" (Windows).
+    """
+    if configured != "auto":
+        return configured
+
+    system = platform.system()
+    if system == "Linux":
+        return "xdg-open"
+    if system == "Darwin":
+        return "open"
+    if system == "Windows":
+        return "explorer"
+    # Fallback
+    return "xdg-open"
+
+
+def open_path(target: Path | str, command: str = "auto") -> tuple[bool, str]:
+    """Open a file path or URL in the default browser.
+
+    Fire-and-forget: does not block the calling process beyond a short timeout.
+    stdout/stderr are captured so they don't interfere with MCP stdio transport.
+
+    Args:
+        target: File path or URL to open.
+        command: "auto" (detect by platform), or explicit command name.
+
+    Returns:
+        Tuple (success, message). On success: (True, "opened via <cmd>").
+        On failure: (False, error description).
+    """
+    cmd = detect_open_command(command)
+
+    if shutil.which(cmd) is None:
+        return False, f"Browser open command '{cmd}' not found on PATH"
+
+    try:
+        result = subprocess.run(
+            [cmd, str(target)],
+            capture_output=True,
+            timeout=5,
+            check=False,
+        )
+        if result.returncode == 0:
+            return True, f"opened via {cmd}"
+
+        stderr = result.stderr.decode("utf-8", errors="replace").strip()
+        return (
+            False,
+            f"'{cmd}' exited with code {result.returncode}: {stderr or 'unknown error'}",
+        )
+    except subprocess.TimeoutExpired:
+        return False, f"'{cmd}' timed out after 5s"
+    except FileNotFoundError:
+        return False, f"Browser open command '{cmd}' not found"

agent_workflow_ui-1.0.0/src/agent_workflow_ui/config.py

@@ -0,0 +1,74 @@
+"""Configuration via environment variables."""
+from __future__ import annotations
+
+import os
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class Config:
+    """Resolved plugin configuration."""
+    inputs_dir: Path
+    templates_dir: Path
+    dashboards_dir: Path
+    http_port: int
+    open_browser_cmd: str
+    temp_dir: Path
+    default_ttl_seconds: int
+
+
+def load() -> Config:
+    """Load config from environment variables.
+
+    Paths are resolved against the current working directory (which is the
+    opencode project root when the plugin runs).
+    """
+    cwd = Path.cwd()
+
+    def _path(env_var: str, default: str) -> Path:
+        value = os.environ.get(env_var, default)
+        p = Path(value)
+        if not p.is_absolute():
+            p = (cwd / p).resolve()
+        return p
+
+    return Config(
+        inputs_dir=_path("AWF_INPUTS_DIR", ".agentic/inputs"),
+        templates_dir=_path("AWF_TEMPLATES_DIR", ".agentic/templates"),
+        dashboards_dir=_path("AWF_DASHBOARDS_DIR", ".agentic/dashboards"),
+        http_port=int(os.environ.get("AWF_HTTP_PORT", "0")),
+        open_browser_cmd=os.environ.get("AWF_OPEN_BROWSER_CMD", "auto"),
+        temp_dir=_path("AWF_TEMP_DIR", tempfile.gettempdir()),
+        default_ttl_seconds=int(os.environ.get("AWF_DEFAULT_TTL_SECONDS", "86400")),
+    )
+
+
+def detect_project_dir() -> Path | None:
+    """Detect active awf project directory.
+
+    Returns Path.cwd() if it contains .agentic/ directory, None otherwise.
+
+    .. note::
+        When opencode supports setting env vars for MCP subprocess, switch to
+        ``AWF_PROJECT_DIR`` env var as primary source. Until then,
+        agent-passed ``project_dir`` in ``open_form(data)`` is canonical.
+    """
+    import logging
+
+    log = logging.getLogger(__name__)
+    cwd = Path.cwd()
+    agentic = cwd / ".agentic"
+    if agentic.is_dir():
+        log.debug("Detected awf project directory: %s", cwd)
+        return cwd
+    log.debug("No .agentic/ found at %s — not inside an awf project", cwd)
+    return None
+
+
+def ensure_directories(config: Config) -> None:
+    """Create runtime directories if missing. Idempotent."""
+    config.inputs_dir.mkdir(parents=True, exist_ok=True)
+    config.templates_dir.mkdir(parents=True, exist_ok=True)
+    config.dashboards_dir.mkdir(parents=True, exist_ok=True)