okstra 0.102.4 → 0.103.0

package/runtime/python/okstra_ctl/manager_launch.py

@@ -0,0 +1,198 @@
+"""Build manager child launch packets and context documents."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Mapping
+
+from okstra_ctl.jsonl import read_jsonl
+
+from .manager_paths import (
+    child_context_path,
+    children_json_path,
+    directives_jsonl_path,
+    projects_json_path,
+    snapshots_json_path,
+    task_manifest_path,
+)
+from .manager_store import ManagerError, _now_iso, _read_json, _read_json_default
+
+
+def select_child_lead_backend(env: Mapping[str, str]) -> str:
+    return "tmux-child-lead" if str(env.get("TMUX") or "").strip() else "subagent-child-lead"
+
+
+def _find_project(projects: dict, project_id: str) -> dict:
+    for project in projects.get("projects", []):
+        if isinstance(project, dict) and project.get("projectId") == project_id:
+            return project
+    raise ManagerError(f"unknown project membership: {project_id}")
+
+
+def _target_task_key(project_id: str, task_group: str, task_id: str) -> str:
+    return f"{project_id}:{task_group}:{task_id}"
+
+
+def _find_child(children: dict, project_id: str, task_group: str, task_id: str) -> dict:
+    target_key = _target_task_key(project_id, task_group, task_id)
+    for child in children.get("children", []):
+        if not isinstance(child, dict):
+            continue
+        if child.get("taskKey") == target_key:
+            return child
+        if (
+            child.get("projectId") == project_id
+            and child.get("taskGroup") == task_group
+            and child.get("taskId") == task_id
+        ):
+            return child
+    raise ManagerError(f"planned child not found for task key: {target_key}")
+
+
+def _validate_child_task_key(child: dict, target_task_key: str) -> None:
+    persisted_key = str(child.get("taskKey") or "").strip()
+    if persisted_key and persisted_key != target_task_key:
+        raise ManagerError(f"child taskKey mismatch: {persisted_key!r}, expected {target_task_key!r}")
+
+
+def _validated_project_root(project: dict) -> str:
+    raw_root = project.get("projectRoot")
+    if not isinstance(raw_root, str) or not raw_root.strip():
+        raise ManagerError(f"projectRoot is required for project: {project.get('projectId') or ''}")
+    root = Path(raw_root).resolve()
+    if not root.is_dir():
+        raise ManagerError(f"projectRoot is not a directory for project: {project.get('projectId') or ''}: {root}")
+    return str(root)
+
+
+def _directives_for_project(rows: list[dict], project_id: str) -> list[dict]:
+    directives: list[dict] = []
+    for row in rows:
+        if row.get("scope") == "shared":
+            directives.append(row)
+        elif row.get("scope") == "project" and row.get("projectId") == project_id:
+            directives.append(row)
+    return directives
+
+
+def _sibling_snapshots(snapshot: dict, target_task_key: str) -> list[dict]:
+    return [
+        row
+        for row in snapshot.get("children", [])
+        if isinstance(row, dict) and row.get("taskKey") != target_task_key
+    ]
+
+
+def _render_context(
+    *,
+    manifest: dict,
+    child: dict,
+    child_task_key: str,
+    directives: list[dict],
+    siblings: list[dict],
+) -> str:
+    lines = [
+        "# Okstra Manager Child Context",
+        "",
+        f"- manager-id: {manifest['managerId']}",
+        f"- task-group: {manifest['taskGroup']}",
+        f"- manager task-id: {manifest['taskId']}",
+        f"- child task-key: {child_task_key}",
+        f"- objective: {manifest.get('objective') or ''}",
+        f"- common brief: {manifest.get('commonBriefPath') or ''}",
+        "",
+        "## Assignment",
+        "",
+        f"- role: {child.get('role') or ''}",
+        f"- tags: {', '.join(child.get('tags') or [])}",
+        "",
+        child.get("assignment") or "",
+        "",
+        "## Manager Directives",
+        "",
+    ]
+    for row in directives:
+        lines.append(f"- [{row.get('scope')}] {row.get('body')}")
+    if not directives:
+        lines.append("- none")
+    lines.extend(
+        [
+            "",
+            "## Sibling Project Snapshots",
+            "",
+            "Sibling synced reports are read-side source material.",
+            "Do not write into sibling project roots.",
+            "Project-local files remain the edit boundary for this child task.",
+            "",
+        ]
+    )
+    for row in siblings:
+        lines.append(
+            f"- {row.get('taskKey')}: {row.get('latestRunStatus') or 'unknown'} {row.get('latestReportPath') or ''}"
+        )
+    if not siblings:
+        lines.append("- none")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def build_launch_packet(
+    home: Path,
+    manager_id: str,
+    task_group: str,
+    task_id: str,
+    project_id: str,
+    *,
+    child_task_id: str | None = None,
+    env: Mapping[str, str] | None = None,
+    now: str | None = None,
+) -> dict:
+    manifest = _read_json(task_manifest_path(home, manager_id, task_group, task_id))
+    projects = _read_json_default(projects_json_path(home, manager_id), {"projects": []})
+    children = _read_json_default(children_json_path(home, manager_id, task_group, task_id), {"children": []})
+    snapshot = _read_json_default(snapshots_json_path(home, manager_id, task_group, task_id), {"children": []})
+    directives = read_jsonl(directives_jsonl_path(home, manager_id, task_group, task_id))
+    project = _find_project(projects, project_id)
+    effective_child_task_id = child_task_id or task_id
+    child = _find_child(children, project_id, task_group, effective_child_task_id)
+    child_task_id_value = str(child.get("taskId") or effective_child_task_id)
+    target_task_key = _target_task_key(project_id, task_group, child_task_id_value)
+    _validate_child_task_key(child, target_task_key)
+    project_root = _validated_project_root(project)
+    backend = select_child_lead_backend(env or {})
+    context_path = child_context_path(home, manager_id, task_group, task_id, project_id, child_task_id_value)
+    context_path.parent.mkdir(parents=True, exist_ok=True)
+    context_path.write_text(
+        _render_context(
+            manifest=manifest,
+            child=child,
+            child_task_key=target_task_key,
+            directives=_directives_for_project(directives, project_id),
+            siblings=_sibling_snapshots(snapshot, target_task_key),
+        ),
+        encoding="utf-8",
+    )
+    return {
+        "managerId": manager_id,
+        "taskGroup": task_group,
+        "taskId": task_id,
+        "projectId": project_id,
+        "taskKey": target_task_key,
+        "backend": backend,
+        "workerDispatchBackend": "subagent",
+        "projectRoot": project_root,
+        "contextPath": str(context_path),
+        "runArgs": [
+            "run",
+            "--project-root",
+            project_root,
+            "--project-id",
+            project_id,
+            "--task-group",
+            str(child.get("taskGroup") or task_group),
+            "--task-id",
+            child_task_id_value,
+            "--directive",
+            f"Read manager child context: {context_path}",
+        ],
+        "createdAt": now or _now_iso(),
+    }

package/runtime/python/okstra_ctl/manager_paths.py

@@ -0,0 +1,98 @@
+"""Pure path computation for okstra manager state."""
+from __future__ import annotations
+
+from pathlib import Path
+import os
+
+from okstra_project import slugify
+
+
+class ManagerPathError(Exception):
+    """Invalid manager identity or task identity."""
+
+
+def _require_id(value: str, label: str) -> str:
+    cleaned = (value or "").strip()
+    if not cleaned:
+        raise ManagerPathError(f"{label} is required")
+    if not any(ch.isalnum() for ch in cleaned):
+        raise ManagerPathError(f"{label} must contain at least one alphanumeric character")
+    return cleaned
+
+
+def _slug_segment(value: str, label: str) -> str:
+    segment = slugify(_require_id(value, label))
+    if not segment:
+        raise ManagerPathError(f"{label} must contain at least one ASCII alphanumeric character")
+    return segment
+
+
+def _require_manager_id(value: str) -> str:
+    cleaned = (value or "").strip()
+    if not cleaned:
+        raise ManagerPathError("manager-id is required")
+    if cleaned in {".", ".."}:
+        raise ManagerPathError("manager-id cannot be absolute or dot path segment")
+    if os.path.isabs(cleaned):
+        raise ManagerPathError("manager-id cannot be absolute or dot path segment")
+    if any(ch in cleaned for ch in ("/", "\\")):
+        raise ManagerPathError("manager-id cannot contain path separators")
+    if not any(ch.isalnum() for ch in cleaned):
+        raise ManagerPathError("manager-id must contain at least one alphanumeric character")
+    return cleaned
+
+
+def canonical_manager_id(manager_id: str) -> str:
+    """Return validated, canonical manager identifier used for both path and payload."""
+    return _require_manager_id(manager_id)
+
+
+def manager_root(home: Path, manager_id: str) -> Path:
+    return Path(home) / "managers" / canonical_manager_id(manager_id)
+
+
+def task_root(home: Path, manager_id: str, task_group: str, task_id: str) -> Path:
+    group_segment = _slug_segment(task_group, "task-group")
+    task_segment = _slug_segment(task_id, "task-id")
+    return manager_root(home, manager_id) / "task-groups" / group_segment / task_segment
+
+
+def manager_json_path(home: Path, manager_id: str) -> Path:
+    return manager_root(home, manager_id) / "manager.json"
+
+
+def projects_json_path(home: Path, manager_id: str) -> Path:
+    return manager_root(home, manager_id) / "projects.json"
+
+
+def task_manifest_path(home: Path, manager_id: str, task_group: str, task_id: str) -> Path:
+    return task_root(home, manager_id, task_group, task_id) / "manifest.json"
+
+
+def children_json_path(home: Path, manager_id: str, task_group: str, task_id: str) -> Path:
+    return task_root(home, manager_id, task_group, task_id) / "children.json"
+
+
+def directives_jsonl_path(home: Path, manager_id: str, task_group: str, task_id: str) -> Path:
+    return task_root(home, manager_id, task_group, task_id) / "directives.jsonl"
+
+
+def snapshots_json_path(home: Path, manager_id: str, task_group: str, task_id: str) -> Path:
+    return task_root(home, manager_id, task_group, task_id) / "snapshots.json"
+
+
+def events_jsonl_path(home: Path, manager_id: str, task_group: str, task_id: str) -> Path:
+    return task_root(home, manager_id, task_group, task_id) / "events.jsonl"
+
+
+def child_context_path(
+    home: Path,
+    manager_id: str,
+    task_group: str,
+    task_id: str,
+    project_id: str,
+    child_task_id: str,
+) -> Path:
+    safe_project = slugify(_require_id(project_id, "project-id"))
+    safe_task = slugify(_require_id(child_task_id, "task-id"))
+    return task_root(home, manager_id, task_group, task_id) / "child-context" / f"{safe_project}-{safe_task}.md"

package/runtime/python/okstra_ctl/manager_store.py

@@ -0,0 +1,318 @@
+"""Manager-owned state mutations for cross-project okstra orchestration."""
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from okstra_project import project_json_path, upsert_project_json
+
+from okstra_ctl.jsonl import append_jsonl
+
+from .manager_paths import (
+    ManagerPathError,
+    canonical_manager_id,
+    children_json_path,
+    directives_jsonl_path,
+    events_jsonl_path,
+    manager_json_path,
+    manager_root,
+    projects_json_path,
+    task_manifest_path,
+)
+
+
+class ManagerError(Exception):
+    """Manager state validation or I/O failure."""
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _write_json(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def _read_json(path: Path) -> dict:
+    if not path.is_file():
+        raise ManagerError(f"manager file not found: {path}")
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ManagerError(f"failed to parse {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ManagerError(f"expected JSON object in {path}")
+    return data
+
+
+def _read_json_default(path: Path, default: dict) -> dict:
+    if not path.is_file():
+        return default
+    return _read_json(path)
+
+
+def _project_entry(projects: dict, project_id: str) -> dict | None:
+    for entry in projects.get("projects", []):
+        if isinstance(entry, dict) and entry.get("projectId") == project_id:
+            return entry
+    return None
+
+
+def _load_projects(home: Path, manager_id: str) -> dict:
+    return _read_json_default(projects_json_path(home, manager_id), {"projects": []})
+
+
+def init_manager(home: Path, manager_id: str, *, now: str | None = None) -> dict:
+    try:
+        canonical_id = canonical_manager_id(manager_id)
+        root = manager_root(home, canonical_id)
+    except ManagerPathError as exc:
+        raise ManagerError(str(exc)) from exc
+    path = manager_json_path(home, canonical_id)
+    if path.is_file():
+        return _read_json(path)
+    payload = {
+        "managerId": canonical_id,
+        "schemaVersion": 1,
+        "createdAt": now or _now_iso(),
+    }
+    root.mkdir(parents=True, exist_ok=True)
+    _write_json(path, payload)
+    return payload
+
+
+def load_manager(home: Path, manager_id: str) -> dict:
+    try:
+        path = manager_json_path(home, canonical_manager_id(manager_id))
+    except ManagerPathError as exc:
+        raise ManagerError(str(exc)) from exc
+    return _read_json(path)
+
+
+def discover_projects(home: Path) -> list[dict]:
+    base = Path(home) / "projects"
+    if not base.is_dir():
+        return []
+    items: list[dict] = []
+    for meta in sorted(base.glob("*/meta.json")):
+        try:
+            data = json.loads(meta.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if isinstance(data, dict):
+            items.append(
+                {
+                    "projectId": str(data.get("projectId") or ""),
+                    "projectRoot": str(data.get("projectRoot") or ""),
+                    "runCount": int(data.get("runCount", 0)),
+                    "activeCount": int(data.get("activeCount", 0)),
+                    "lastRunAt": str(data.get("lastRunAt") or ""),
+                }
+            )
+    return [item for item in items if item["projectId"]]
+
+
+def link_project(
+    home: Path,
+    manager_id: str,
+    project_id: str,
+    project_root: Path,
+    *,
+    role: str,
+    tags: list[str],
+    now: str | None = None,
+) -> dict:
+    load_manager(home, manager_id)
+    root = Path(project_root).resolve()
+    project_json = project_json_path(root)
+    if project_json.is_file():
+        try:
+            existing = json.loads(project_json.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise ManagerError(f"failed to parse {project_json}: {exc}") from exc
+        existing_id = str(existing.get("projectId") or "")
+        if existing_id != project_id:
+            raise ManagerError(
+                f"projectId mismatch: {project_json} has {existing_id!r}, expected {project_id!r}"
+            )
+    else:
+        try:
+            upsert_project_json(root, project_id, now=now)
+        except Exception as exc:
+            raise ManagerError(str(exc)) from exc
+    payload = _load_projects(home, manager_id)
+    entry = _project_entry(payload, project_id)
+    next_entry = {
+        "projectId": project_id,
+        "projectRoot": str(root),
+        "role": role,
+        "tags": list(tags),
+        "linkedAt": now or _now_iso(),
+    }
+    if entry is None:
+        payload["projects"].append(next_entry)
+    else:
+        entry.update(next_entry)
+    payload["projects"].sort(key=lambda item: item.get("projectId", ""))
+    _write_json(projects_json_path(home, manager_id), payload)
+    return payload
+
+
+def create_task_group(home: Path, manager_id: str, task_group: str, *, now: str | None = None) -> dict:
+    load_manager(home, manager_id)
+    group_dir = task_manifest_path(home, manager_id, task_group, "group-marker").parents[1]
+    group_dir.mkdir(parents=True, exist_ok=True)
+    return {"managerId": manager_id, "taskGroup": task_group, "createdAt": now or _now_iso()}
+
+
+def create_task(
+    home: Path,
+    manager_id: str,
+    task_group: str,
+    task_id: str,
+    child_specs: list[dict],
+    *,
+    objective: str = "",
+    common_brief_path: str = "",
+    progress_mode: str = "manual",
+    now: str | None = None,
+) -> dict:
+    projects = _load_projects(home, manager_id)
+    when = now or _now_iso()
+    manifest = {
+        "managerId": manager_id,
+        "taskGroup": task_group,
+        "taskId": task_id,
+        "progressMode": progress_mode,
+        "commonBriefPath": common_brief_path,
+        "objective": objective,
+        "createdAt": when,
+    }
+    children = []
+    for spec in child_specs:
+        project_id = str(spec.get("projectId") or "")
+        child_task_id = str(spec.get("taskId") or task_id)
+        if _project_entry(projects, project_id) is None:
+            raise ManagerError(f"unknown project membership: {project_id}")
+        children.append(
+            {
+                "projectId": project_id,
+                "taskGroup": task_group,
+                "taskId": child_task_id,
+                "taskKey": f"{project_id}:{task_group}:{child_task_id}",
+                "role": "",
+                "tags": [],
+                "assignment": "",
+                "launch": {
+                    "status": "planned",
+                    "childLeadBackend": "auto",
+                    "workerDispatchBackend": "subagent",
+                },
+            }
+        )
+    payload = {"manifest": manifest, "children": {"children": children}}
+    _write_json(task_manifest_path(home, manager_id, task_group, task_id), manifest)
+    _write_json(children_json_path(home, manager_id, task_group, task_id), payload["children"])
+    append_jsonl(
+        events_jsonl_path(home, manager_id, task_group, task_id),
+        {"event": "task-created", "createdAt": when},
+    )
+    return payload
+
+
+def _load_children(home: Path, manager_id: str, task_group: str, task_id: str) -> dict:
+    return _read_json_default(children_json_path(home, manager_id, task_group, task_id), {"children": []})
+
+
+def _child_task_key(project_id: str, task_group: str, child_task_id: str) -> str:
+    return f"{project_id}:{task_group}:{child_task_id}"
+
+
+def _matches_child_task(child: dict, project_id: str, task_group: str, child_task_id: str) -> bool:
+    target_key = _child_task_key(project_id, task_group, child_task_id)
+    if child.get("taskKey") == target_key:
+        return True
+    return (
+        child.get("projectId") == project_id
+        and child.get("taskGroup") == task_group
+        and child.get("taskId") == child_task_id
+    )
+
+
+def _select_child_for_assignment(
+    children: list,
+    project_id: str,
+    task_group: str,
+    child_task_id: str | None,
+) -> dict:
+    if child_task_id is not None:
+        for child in children:
+            if isinstance(child, dict) and _matches_child_task(
+                child,
+                project_id,
+                task_group,
+                child_task_id,
+            ):
+                return child
+        raise ManagerError(
+            f"planned child not found for task key: {_child_task_key(project_id, task_group, child_task_id)}"
+        )
+    matches = [child for child in children if isinstance(child, dict) and child.get("projectId") == project_id]
+    if len(matches) == 1:
+        return matches[0]
+    if len(matches) > 1:
+        raise ManagerError(f"ambiguous child assignment for project: {project_id}; pass child_task_id")
+    raise ManagerError(f"planned child not found for project: {project_id}")
+
+
+def assign_child(
+    home: Path,
+    manager_id: str,
+    task_group: str,
+    task_id: str,
+    project_id: str,
+    *,
+    role: str,
+    tags: list[str],
+    assignment: str,
+    child_task_id: str | None = None,
+) -> dict:
+    payload = _load_children(home, manager_id, task_group, task_id)
+    child = _select_child_for_assignment(payload["children"], project_id, task_group, child_task_id)
+    child["role"] = role
+    child["tags"] = list(tags)
+    child["assignment"] = assignment
+    _write_json(children_json_path(home, manager_id, task_group, task_id), payload)
+    return payload
+
+
+def append_directive(
+    home: Path,
+    manager_id: str,
+    task_group: str,
+    task_id: str,
+    *,
+    scope: str,
+    body: str,
+    project_id: str = "",
+    now: str | None = None,
+    source: str = "user",
+) -> dict:
+    if scope not in {"shared", "project"}:
+        raise ManagerError("scope must be shared or project")
+    if scope == "project" and not project_id:
+        raise ManagerError("project directive requires project-id")
+    row = {
+        "scope": scope,
+        "projectId": project_id if scope == "project" else "",
+        "body": body,
+        "createdAt": now or _now_iso(),
+        "source": source,
+    }
+    append_jsonl(directives_jsonl_path(home, manager_id, task_group, task_id), row)
+    return row