cowork-flow 0.0.19 → 0.0.21

package/template/.cowork-flow/scripts/subagent.py

@@ -1,21 +1,31 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-"""Generic subagent scoped recovery state."""
+"""Runtime-context scoped subagent state."""
 
 from __future__ import annotations
 
 import argparse
 import json
 import re
-import secrets
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
+from common.active_task import (
+    bind_runtime_context,
+    close_runtime_context,
+    read_runtime_context,
+    resolve_context_key,
+    runtime_context_path,
+    sessions_dir,
+    subagent_contexts_dir,
+    write_runtime_context,
+    write_subagent_logical_session,
+)
 from common.execution_context import build_internal_execution_context_parser
-from common.paths import DIR_WORKFLOW, get_repo_root
+from common.paths import get_repo_root
 
-VALID_STATUSES = {"active", "success", "needs_context", "blocked"}
+VALID_STATUSES = {"pending", "bound", "active", "success", "needs_context", "blocked", "closed"}
 FIXED_AGENT_TYPES = {"cowork-research", "cowork-implement", "cowork-check"}
 GENERIC_AGENT_TYPE = "worker"
 ROLE_AGENT_TYPE_ALIASES = {
@@ -34,10 +44,6 @@ def _slug(value: str) -> str:
     return slug or "subagent"
 
 
-def _subagents_dir(repo_root: Path) -> Path:
-    return repo_root / DIR_WORKFLOW / "subagents"
-
-
 def _relative(repo_root: Path, path: Path) -> str:
     try:
         return path.resolve().relative_to(repo_root.resolve()).as_posix()
@@ -45,28 +51,26 @@ def _relative(repo_root: Path, path: Path) -> str:
         return str(path)
 
 
-def _write_json(path: Path, data: object) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-
-
-def _append_event(path: Path, event: dict[str, object]) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    with path.open("a", encoding="utf-8") as handle:
-        handle.write(json.dumps(event, ensure_ascii=False) + "\n")
-
-
 def _next_id(base_dir: Path, title: str) -> str:
-    prefix = datetime.now().strftime("%Y%m%d-%H%M%S")
-    base = f"{prefix}-{_slug(title)}"
+    prefix = datetime.now().strftime("rtx_%Y%m%d_%H%M%S")
+    base = f"{prefix}_{_slug(title)}"
     candidate = base
     counter = 2
-    while (base_dir / candidate).exists():
-        candidate = f"{base}-{counter}"
+    while (base_dir / f"{candidate}.json").exists():
+        candidate = f"{base}_{counter}"
         counter += 1
     return candidate
 
 
+def _host_context_prefix(host: str) -> str:
+    normalized = host.strip().lower()
+    if normalized == "claude-code":
+        return "claude"
+    return re.sub(r"[^a-z0-9]+", "_", normalized).strip("_") or "host"
+
+def _suggest_host_context_key(host: str, runtime_context_id: str) -> str:
+    return f"{_host_context_prefix(host)}_{runtime_context_id}"
+
 def _resolve_agent_type(role: str, agent_type: str | None) -> tuple[str, str]:
     normalized_role = role.strip()
     requested = agent_type.strip() if isinstance(agent_type, str) else ""
@@ -76,245 +80,119 @@ def _resolve_agent_type(role: str, agent_type: str | None) -> tuple[str, str]:
                 raise ValueError(f"agent-type {requested} cannot use role {normalized_role}")
             if normalized_role in ROLE_AGENT_TYPE_ALIASES and ROLE_AGENT_TYPE_ALIASES[normalized_role] != requested:
                 raise ValueError(f"agent-type {requested} cannot use role {normalized_role}")
-            return requested, "fixed"
+            return requested, "formal"
         if requested == GENERIC_AGENT_TYPE:
             if normalized_role in FIXED_AGENT_TYPES or normalized_role in ROLE_AGENT_TYPE_ALIASES:
                 raise ValueError("agent-type worker requires non-fixed role")
-            return requested, "best-effort"
+            return requested, "advisory"
         raise ValueError("agent-type must be cowork-research, cowork-implement, cowork-check, or worker")
     if normalized_role in FIXED_AGENT_TYPES:
-        return normalized_role, "fixed"
+        return normalized_role, "formal"
     if normalized_role in ROLE_AGENT_TYPE_ALIASES:
-        return ROLE_AGENT_TYPE_ALIASES[normalized_role], "fixed"
-    return GENERIC_AGENT_TYPE, "best-effort"
-
-
-def _build_dispatch_message(
-    *,
-    dispatch_id: str,
-    agent_type: str,
-    role: str,
-    task_dir: str | None,
-    context_file: Path,
-    ack_token: str,
-    dispatch_reliability: str,
-) -> str:
-    lines = [
-        "COWORK_DISPATCH_V1",
-        f"dispatch_id: {dispatch_id}",
-        f"agent_type: {agent_type}",
-    ]
-    if task_dir:
-        lines.append(f"task_dir: {task_dir}")
-    lines.extend(
-        [
-            f"role: {role}",
-            f"context_file: {_relative(get_repo_root(), context_file)}",
-            f"ack_token: {ack_token}",
-            f"dispatch_reliability: {dispatch_reliability}",
-            "COWORK_DISPATCH_END",
-            "",
-            f"Return only: COWORK_ACK {dispatch_id} {ack_token}",
-        ]
-    )
-    if dispatch_reliability == "best-effort":
-        lines.insert(7, "This generic worker dispatch is best-effort only.")
-    return "\n".join(lines)
-
-
-def _build_execute_message(dispatch_id: str, goal: str, dispatch_reliability: str) -> str:
-    lines = [
-        f"EXECUTE {dispatch_id}",
-        "",
-        goal,
-    ]
-    if dispatch_reliability == "best-effort":
-        lines.extend(
-            [
-                "",
-                "Treat this as best-effort.",
-            ]
-        )
-    return "\n".join(lines)
+        return ROLE_AGENT_TYPE_ALIASES[normalized_role], "formal"
+    return GENERIC_AGENT_TYPE, "advisory"
 
 
 def cmd_init(args: argparse.Namespace) -> int:
     repo_root = get_repo_root()
-    base_dir = _subagents_dir(repo_root)
-    subagent_id = _next_id(base_dir, args.title)
-    subagent_dir = base_dir / subagent_id
+    base_dir = subagent_contexts_dir(repo_root)
+    runtime_context_id = _next_id(base_dir, args.title)
     task_dir = getattr(args, "execution_task_dir", None)
     try:
-        agent_type, dispatch_reliability = _resolve_agent_type(args.role, getattr(args, "agent_type", None))
+        agent_type, dispatch_kind = _resolve_agent_type(args.role, getattr(args, "agent_type", None))
     except ValueError as error:
         print(f"Error: {error}", file=sys.stderr)
         return 1
-    if dispatch_reliability == "fixed" and not task_dir:
+    if dispatch_kind == "formal" and not task_dir:
         print("Error: fixed agent dispatch requires --execution-task-dir", file=sys.stderr)
         return 1
-    subagent_dir.mkdir(parents=True, exist_ok=False)
-    dispatch_id = subagent_id
-    ack_token = f"ACK:{dispatch_id}:{secrets.token_hex(8)}"
+
     allowed_context = [{"file": item, "reason": "prompt-named context"} for item in args.allowed_context]
-    status_file = subagent_dir / "status.json"
-    events_file = subagent_dir / "events.jsonl"
-    brief_file = subagent_dir / "brief.md"
-    context_file = subagent_dir / "context.json"
-    expected_ack = f"COWORK_ACK {dispatch_id} {ack_token}"
-    dispatch_message = _build_dispatch_message(
-        dispatch_id=dispatch_id,
-        agent_type=agent_type,
-        role=args.role,
-        task_dir=task_dir,
-        context_file=context_file,
-        ack_token=ack_token,
-        dispatch_reliability=dispatch_reliability,
-    )
-    execute_message = _build_execute_message(dispatch_id, args.goal or args.title, dispatch_reliability)
-
-    brief_file.write_text(
-        "\n".join(
-            [
-                dispatch_message,
-                "",
-                f"Do not execute the task until the coordinator sends EXECUTE {dispatch_id}.",
-                "",
-                f"# {args.title}",
-                "",
-                f"Role: {args.role}",
-                f"Agent type: {agent_type}",
-                f"Task directory: {task_dir or 'unknown'}",
-                f"Dispatch reliability: {dispatch_reliability}",
-                f"Source: {args.source}",
-                "",
-                "## Goal",
-                "",
-                args.goal or args.title,
-                "",
-                "## Scope Rules",
-                "",
-                "- Read only prompt-named files and allowed context unless more context is requested.",
-                "- Do not run main-session start/resume or coordinator mutation commands.",
-                "- Stop with success, needs_context, or blocked evidence.",
-                "",
-            ]
-        ),
-        encoding="utf-8",
-    )
-    status = {
-        "id": subagent_id,
-        "status": "active",
-        "title": args.title,
-        "role": args.role,
-        "agentType": agent_type,
-        "taskDir": task_dir,
-        "dispatchReliability": dispatch_reliability,
-        "source": args.source,
-        "goal": args.goal or args.title,
-        "updatedAt": _now(),
-        "note": "initialized",
-        "dispatchId": dispatch_id,
-        "dispatchStatus": "planned",
-        "ackToken": ack_token,
-        "expectedAck": expected_ack,
-        "dispatchMessage": dispatch_message,
-        "executeMessage": execute_message,
-    }
-    _write_json(status_file, status)
+    parent_context_key = resolve_context_key()
     context = {
-        "mode": "subagent",
-        "kind": "generic-subagent",
-        "id": subagent_id,
-        "agentType": agent_type,
-        "taskDir": task_dir,
-        "dispatchReliability": dispatch_reliability,
-        "dispatchId": dispatch_id,
-        "ackToken": ack_token,
-        "expectedAck": expected_ack,
-        "dispatchMessage": dispatch_message,
-        "executeMessage": execute_message,
-        "dispatchStatus": "planned",
-        "title": args.title,
+        "schema_version": 2,
+        "runtime_context_id": runtime_context_id,
+        "scope": "subagent",
+        "host": args.host,
+        "adapter": args.adapter,
+        "agent_type": agent_type,
         "role": args.role,
-        "source": args.source,
-        "goal": args.goal or args.title,
-        "allowedContext": allowed_context,
-        "forbiddenActions": [
-            "full-start",
-            "unscoped-resume",
-            "task-start",
-            "task-finish",
-            "task-archive",
-            "spawn-agent",
-        ],
-        "briefFile": _relative(repo_root, brief_file),
-        "statusFile": _relative(repo_root, status_file),
-        "eventsFile": _relative(repo_root, events_file),
+        "task_dir": task_dir,
+        "parent_context_key": parent_context_key,
+        "transport": {
+            "kind": "prompt",
+            "key": "cowork_runtime_context_id",
+        },
+        "assignment": {
+            "title": args.title,
+            "goal": args.goal or args.title,
+            "allowed_context": allowed_context,
+            "expected_output": args.expected_output,
+            "source": args.source,
+        },
+        "authority": {
+            "may_start_task": False,
+            "may_resume_main": False,
+            "may_archive": False,
+            "may_commit": False,
+            "may_spawn": False,
+        },
+        "status": "pending",
+        "dispatch_kind": dispatch_kind,
+        "created_at": _now(),
+        "bound_context_key": None,
+        "closed_at": None,
     }
-    _write_json(context_file, context)
-    _append_event(events_file, {"time": _now(), "event": "init", "status": "active", "title": args.title})
-
-    index_path = base_dir / "index.json"
-    if index_path.is_file():
-        try:
-            index = json.loads(index_path.read_text(encoding="utf-8"))
-        except json.JSONDecodeError:
-            index = {"subagents": []}
-    else:
-        index = {"subagents": []}
-    subagents = index.setdefault("subagents", [])
-    if isinstance(subagents, list):
-        subagents.append(
-            {
-                "id": subagent_id,
-                "dispatchId": dispatch_id,
-                "agentType": agent_type,
-                "taskDir": task_dir,
-                "title": args.title,
-                "contextFile": _relative(repo_root, context_file),
-                "status": "active",
-                "dispatchStatus": "planned",
-                "dispatchReliability": dispatch_reliability,
-            }
-        )
-    _write_json(index_path, index)
+    write_runtime_context(repo_root, runtime_context_id, context)
+    logical_context_key = write_subagent_logical_session(
+        repo_root,
+        runtime_context_id,
+        task_dir,
+        args.host,
+    )
+    host_context_key = _suggest_host_context_key(args.host, runtime_context_id)
 
     print(
         json.dumps(
-                {
-                    "id": subagent_id,
-                    "agentType": agent_type,
-                    "taskDir": task_dir,
-                    "dispatchReliability": dispatch_reliability,
-                    "dispatchId": dispatch_id,
-                    "ackToken": ack_token,
-                    "expectedAck": expected_ack,
-                    "dispatchMessage": dispatch_message,
-                    "executeMessage": execute_message,
-                    "contextFile": _relative(repo_root, context_file),
-                },
-                ensure_ascii=False,
-            )
+            {
+                "id": runtime_context_id,
+                "runtimeContextId": runtime_context_id,
+                "cowork_runtime_context_id": runtime_context_id,
+                "hostContextKey": host_context_key,
+                "cowork_host_context_key": host_context_key,
+                "agentType": agent_type,
+                "role": args.role,
+                "taskDir": task_dir,
+                "dispatchKind": dispatch_kind,
+                "runtimeContextFile": _relative(repo_root, runtime_context_path(repo_root, runtime_context_id)),
+                "logicalSessionFile": _relative(repo_root, sessions_dir(repo_root) / f"{logical_context_key}.json"),
+                "promptTransport": (
+                    f"cowork_runtime_context_id: {runtime_context_id}\n"
+                    f"cowork_host_context_key: {host_context_key}"
+                ),
+                "bindCommand": f".cowork-flow/run subagent bind {runtime_context_id} {host_context_key}",
+            },
+            ensure_ascii=False,
         )
+    )
     return 0
 
 
-def _find_subagent(repo_root: Path, subagent_id: str) -> Path:
-    path = _subagents_dir(repo_root) / subagent_id
-    if not path.is_dir():
-        raise FileNotFoundError(subagent_id)
-    return path
+def _find_subagent(repo_root: Path, runtime_context_id: str) -> dict:
+    context = read_runtime_context(repo_root, runtime_context_id)
+    if not context:
+        raise FileNotFoundError(runtime_context_id)
+    return context
 
 
 def cmd_status(args: argparse.Namespace) -> int:
     repo_root = get_repo_root()
     try:
-        subagent_dir = _find_subagent(repo_root, args.subagent_id)
+        context = _find_subagent(repo_root, args.subagent_id)
     except FileNotFoundError:
         print(f"Error: subagent not found: {args.subagent_id}", file=sys.stderr)
         return 1
-    status_file = subagent_dir / "status.json"
-    print(status_file.read_text(encoding="utf-8"), end="")
+    print(json.dumps(context, ensure_ascii=False, indent=2) + "\n", end="")
     return 0
 
 
@@ -324,48 +202,84 @@ def cmd_update(args: argparse.Namespace) -> int:
         return 1
     repo_root = get_repo_root()
     try:
-        subagent_dir = _find_subagent(repo_root, args.subagent_id)
+        context = _find_subagent(repo_root, args.subagent_id)
     except FileNotFoundError:
         print(f"Error: subagent not found: {args.subagent_id}", file=sys.stderr)
         return 1
-    status_file = subagent_dir / "status.json"
-    status = json.loads(status_file.read_text(encoding="utf-8"))
-    status["status"] = args.status
-    status["updatedAt"] = _now()
+    context["status"] = args.status
+    context["updated_at"] = _now()
     if args.note:
-        status["note"] = args.note
-    _write_json(status_file, status)
-    _append_event(subagent_dir / "events.jsonl", {"time": _now(), "event": "update", "status": args.status, "note": args.note})
+        context["note"] = args.note
+    write_runtime_context(repo_root, args.subagent_id, context)
     print(f"subagent {args.subagent_id} status={args.status}")
     return 0
 
 
+def cmd_bind(args: argparse.Namespace) -> int:
+    repo_root = get_repo_root()
+    existing = read_runtime_context(repo_root, args.subagent_id)
+    existing_key = existing.get("bound_context_key") if existing else None
+    if isinstance(existing_key, str) and existing_key.strip() and existing_key != args.context_key:
+        print(
+            f"Error: runtime context {args.subagent_id} already bound to {existing_key}",
+            file=sys.stderr,
+        )
+        return 1
+    context = bind_runtime_context(repo_root, args.subagent_id, args.context_key)
+    if context is None:
+        print(f"Error: cannot bind runtime context: {args.subagent_id}", file=sys.stderr)
+        return 1
+    print(json.dumps(context, ensure_ascii=False, indent=2) + "\n", end="")
+    return 0
+
+
+def cmd_close(args: argparse.Namespace) -> int:
+    repo_root = get_repo_root()
+    if not close_runtime_context(repo_root, args.subagent_id):
+        print(f"Error: subagent not found: {args.subagent_id}", file=sys.stderr)
+        return 1
+    print(f"subagent {args.subagent_id} closed")
+    return 0
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
-        description="Generic subagent scoped recovery",
+        description="Runtime-context scoped subagent state",
         parents=[build_internal_execution_context_parser()],
     )
     subparsers = parser.add_subparsers(dest="command", required=True)
 
-    init = subparsers.add_parser("init", help="Create generic subagent context")
+    init = subparsers.add_parser("init", help="Create runtime subagent context")
     init.add_argument("--title", required=True)
     init.add_argument("--role", default="subagent")
     init.add_argument("--agent-type")
     init.add_argument("--source", default="auto")
     init.add_argument("--goal")
+    init.add_argument("--expected-output", default="Files changed, validation commands, and blockers.")
     init.add_argument("--allowed-context", action="append", default=[])
+    init.add_argument("--host", default="codex")
+    init.add_argument("--adapter", default="codex.spawn_agent")
     init.set_defaults(func=cmd_init)
 
-    status = subparsers.add_parser("status", help="Print subagent status")
+    status = subparsers.add_parser("status", help="Print subagent runtime context")
     status.add_argument("subagent_id")
     status.set_defaults(func=cmd_status)
 
-    update = subparsers.add_parser("update", help="Update subagent status")
+    update = subparsers.add_parser("update", help="Update subagent runtime status")
     update.add_argument("subagent_id")
     update.add_argument("--status", required=True)
     update.add_argument("--note")
     update.set_defaults(func=cmd_update)
 
+    bind = subparsers.add_parser("bind", help="Bind host session to runtime context")
+    bind.add_argument("subagent_id")
+    bind.add_argument("context_key")
+    bind.set_defaults(func=cmd_bind)
+
+    close = subparsers.add_parser("close", help="Close subagent runtime context")
+    close.add_argument("subagent_id")
+    close.set_defaults(func=cmd_close)
+
     return parser