@event4u/agent-config 1.9.1

package/scripts/runtime_dispatcher.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""
+Runtime Dispatcher — resolves execution type and drives real handler execution.
+
+Two modes:
+
+- resolve (default): produce a structured execution request, enforce safety,
+  return dispatch metadata. No side effects.
+- run: dispatch the skill, then hand it to the matching runtime handler to
+  actually execute. Returns a typed ExecutionResult.
+
+Usage:
+    python3 scripts/runtime_dispatcher.py --skill NAME [--format text|json]
+    python3 scripts/runtime_dispatcher.py resolve --skill NAME
+    python3 scripts/runtime_dispatcher.py run --skill NAME [--cwd PATH] [--output FILE]
+
+`run --output FILE` persists the ExecutionResult as JSON to FILE. CI uses
+this to feed `scripts/ci_summary.py`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import List, Optional
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from runtime_registry import SkillRuntime, build_registry
+from runtime_handler import ExecutionResult, HandlerError, execute_shell
+
+
+@dataclass
+class ExecutionRequest:
+    """Structured execution request produced by the dispatcher."""
+    skill_name: str
+    execution_type: str
+    handler: str
+    timeout_seconds: int
+    safety_mode: Optional[str]
+    allowed_tools: List[str]
+    status: str  # "ready", "blocked", "not_found"
+    reason: Optional[str]
+
+    @property
+    def is_ready(self) -> bool:
+        return self.status == "ready"
+
+
+@dataclass
+class DispatchResult:
+    """Result of dispatching a skill for execution."""
+    request: ExecutionRequest
+    warnings: List[str]
+
+
+def dispatch(skill_name: str, registry: List[SkillRuntime]) -> DispatchResult:
+    """Resolve and validate a skill for execution."""
+    warnings: List[str] = []
+
+    # Find skill in registry
+    matches = [s for s in registry if s.name == skill_name]
+    if not matches:
+        return DispatchResult(
+            request=ExecutionRequest(
+                skill_name=skill_name,
+                execution_type="unknown",
+                handler="none",
+                timeout_seconds=0,
+                safety_mode=None,
+                allowed_tools=[],
+                status="not_found",
+                reason=f"Skill '{skill_name}' not found in runtime registry",
+            ),
+            warnings=[],
+        )
+
+    skill = matches[0]
+
+    # Manual skills cannot be dispatched
+    if skill.execution_type == "manual":
+        return DispatchResult(
+            request=ExecutionRequest(
+                skill_name=skill.name,
+                execution_type=skill.execution_type,
+                handler=skill.handler,
+                timeout_seconds=skill.timeout_seconds,
+                safety_mode=skill.safety_mode,
+                allowed_tools=skill.allowed_tools,
+                status="blocked",
+                reason="Manual skills cannot be dispatched for execution",
+            ),
+            warnings=[],
+        )
+
+    # Automated skills must pass safety checks
+    if skill.is_automated:
+        if skill.handler == "none":
+            return DispatchResult(
+                request=ExecutionRequest(
+                    skill_name=skill.name,
+                    execution_type=skill.execution_type,
+                    handler=skill.handler,
+                    timeout_seconds=skill.timeout_seconds,
+                    safety_mode=skill.safety_mode,
+                    allowed_tools=skill.allowed_tools,
+                    status="blocked",
+                    reason="Automated skill has no handler",
+                ),
+                warnings=[],
+            )
+        if skill.safety_mode != "strict":
+            return DispatchResult(
+                request=ExecutionRequest(
+                    skill_name=skill.name,
+                    execution_type=skill.execution_type,
+                    handler=skill.handler,
+                    timeout_seconds=skill.timeout_seconds,
+                    safety_mode=skill.safety_mode,
+                    allowed_tools=skill.allowed_tools,
+                    status="blocked",
+                    reason="Automated skill requires safety_mode: strict",
+                ),
+                warnings=[],
+            )
+
+    # Assisted/automated skill is ready
+    if skill.execution_type == "assisted":
+        warnings.append("Assisted execution requires human confirmation before action")
+
+    return DispatchResult(
+        request=ExecutionRequest(
+            skill_name=skill.name,
+            execution_type=skill.execution_type,
+            handler=skill.handler,
+            timeout_seconds=skill.timeout_seconds,
+            safety_mode=skill.safety_mode,
+            allowed_tools=skill.allowed_tools,
+            status="ready",
+            reason=None,
+        ),
+        warnings=warnings,
+    )
+
+
+def run(skill_name: str, registry: List[SkillRuntime], cwd: Path) -> ExecutionResult:
+    """Dispatch and execute a skill. Raises HandlerError on structural issues."""
+    dispatch_result = dispatch(skill_name, registry)
+    req = dispatch_result.request
+    if not req.is_ready:
+        raise HandlerError(
+            f"Skill '{skill_name}' is not ready to run: "
+            f"{req.status} — {req.reason or 'no reason given'}"
+        )
+
+    skill = next(s for s in registry if s.name == skill_name)
+    if skill.handler in {"shell", "php", "node"}:
+        return execute_shell(skill, cwd)
+    raise HandlerError(
+        f"Handler '{skill.handler}' has no executor yet — "
+        f"only 'shell' is implemented in this phase"
+    )
+
+
+def _print_dispatch(result: DispatchResult, fmt: str) -> None:
+    if fmt == "json":
+        print(json.dumps(asdict(result), indent=2))
+        return
+    req = result.request
+    print(f"Skill: {req.skill_name}")
+    print(f"Status: {req.status}")
+    if req.reason:
+        print(f"Reason: {req.reason}")
+    if req.is_ready:
+        print(f"Type: {req.execution_type}")
+        print(f"Handler: {req.handler}")
+        print(f"Timeout: {req.timeout_seconds}s")
+        tools = ", ".join(req.allowed_tools) if req.allowed_tools else "none"
+        print(f"Tools: {tools}")
+    for w in result.warnings:
+        print(f"WARNING: {w}")
+
+
+def _print_execution(result: ExecutionResult, fmt: str) -> None:
+    if fmt == "json":
+        print(json.dumps(asdict(result), indent=2))
+        return
+    print(f"Skill: {result.skill_name}")
+    print(f"Handler: {result.handler}")
+    print(f"Command: {' '.join(result.command)}")
+    print(f"Cwd: {result.cwd}")
+    print(f"Status: {result.status}")
+    print(f"Exit code: {result.exit_code}")
+    print(f"Duration: {result.duration_ms}ms")
+    if result.error:
+        print(f"Error: {result.error}")
+    if result.stdout:
+        print("--- stdout ---")
+        print(result.stdout.rstrip())
+    if result.stderr:
+        print("--- stderr ---")
+        print(result.stderr.rstrip())
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Runtime Dispatcher — resolve or run skill execution")
+    sub = parser.add_subparsers(dest="action")
+
+    # Legacy flat flags retained for backward compatibility.
+    parser.add_argument("--skill", help="Skill name to dispatch")
+    parser.add_argument("--root", type=Path, default=Path("."), help="Repository root")
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+
+    resolve_p = sub.add_parser("resolve", help="Resolve skill and return dispatch metadata (no execution)")
+    resolve_p.add_argument("--skill", required=True)
+    resolve_p.add_argument("--root", type=Path, default=Path("."))
+    resolve_p.add_argument("--format", choices=["text", "json"], default="text")
+
+    run_p = sub.add_parser("run", help="Dispatch and execute the skill via its handler")
+    run_p.add_argument("--skill", required=True)
+    run_p.add_argument("--root", type=Path, default=Path("."))
+    run_p.add_argument("--cwd", type=Path, default=None, help="Working directory (default: --root)")
+    run_p.add_argument("--format", choices=["text", "json"], default="text")
+    run_p.add_argument(
+        "--output",
+        type=Path,
+        default=None,
+        help="Persist ExecutionResult as JSON to this path (parents created)",
+    )
+    return parser
+
+
+def main() -> int:
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    action = args.action or "resolve"
+    if action == "resolve" and not args.skill:
+        parser.error("--skill is required for resolve")
+
+    registry = build_registry(args.root)
+
+    if action == "run":
+        cwd = args.cwd if args.cwd is not None else args.root
+        try:
+            result = run(args.skill, registry, cwd)
+        except HandlerError as exc:
+            print(f"HandlerError: {exc}", file=sys.stderr)
+            return 2
+        _print_execution(result, args.format)
+        output = getattr(args, "output", None)
+        if output is not None:
+            output.parent.mkdir(parents=True, exist_ok=True)
+            output.write_text(json.dumps(asdict(result), indent=2) + "\n", encoding="utf-8")
+        return 0 if result.is_success else 1
+
+    result = dispatch(args.skill, registry)
+    _print_dispatch(result, args.format)
+    return 0 if result.request.is_ready or result.request.status == "blocked" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/runtime_handler.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+Runtime Handler — executes a skill's declared command and captures the result.
+
+This is the first real execution path in the runtime layer. It consumes a
+SkillRuntime (from the registry), runs its `command` argv through the
+appropriate handler, and returns a typed ExecutionResult.
+
+Responsibilities:
+- Shell-out safely: no shell=True, argv form only
+- Enforce timeout (SkillRuntime.timeout_seconds)
+- Capture stdout, stderr, exit code, wall-clock duration
+- Scrub environment to an allowlist
+- Resolve working directory relative to repository root
+
+Out of scope (remain in scaffold layers for now):
+- php/node handlers beyond running their binaries
+- tool registry integration
+- streaming output
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from runtime_registry import SkillRuntime
+
+
+# Environment variables that are always forwarded to the child process.
+# Kept deliberately narrow — no credentials, no shell config, no auth tokens.
+DEFAULT_ENV_ALLOWLIST: tuple[str, ...] = (
+    "PATH",
+    "HOME",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TZ",
+    "TMPDIR",
+    "PYTHONPATH",
+    "PYTHONDONTWRITEBYTECODE",
+)
+
+
+@dataclass
+class ExecutionResult:
+    """Typed result of a real command execution."""
+    skill_name: str
+    handler: str
+    command: List[str]
+    cwd: str
+    exit_code: int
+    stdout: str
+    stderr: str
+    duration_ms: int
+    status: str  # "success" | "failure" | "timeout" | "error"
+    timed_out: bool = False
+    error: Optional[str] = None
+    artifacts: List[str] = field(default_factory=list)
+
+    @property
+    def is_success(self) -> bool:
+        return self.status == "success"
+
+
+class HandlerError(Exception):
+    """Raised when a handler cannot execute for structural reasons."""
+
+
+def _build_env(allowlist: tuple[str, ...]) -> Dict[str, str]:
+    """Build a scrubbed environment dict from the allowlist."""
+    env: Dict[str, str] = {}
+    for key in allowlist:
+        value = os.environ.get(key)
+        if value is not None:
+            env[key] = value
+    # Guarantee a minimum PATH so subprocess can find binaries.
+    env.setdefault("PATH", "/usr/local/bin:/usr/bin:/bin")
+    return env
+
+
+def execute_shell(
+    skill: SkillRuntime,
+    cwd: Path,
+    env_allowlist: tuple[str, ...] = DEFAULT_ENV_ALLOWLIST,
+) -> ExecutionResult:
+    """Run a skill's command as a subprocess and capture the result."""
+    if not skill.command:
+        raise HandlerError(
+            f"Skill '{skill.name}' has no 'command' declared — cannot execute"
+        )
+    if skill.handler not in {"shell", "php", "node"}:
+        raise HandlerError(
+            f"Skill '{skill.name}' handler '{skill.handler}' is not a real-execution handler"
+        )
+
+    env = _build_env(env_allowlist)
+    cwd_str = str(cwd.resolve())
+    start = time.monotonic()
+
+    try:
+        completed = subprocess.run(
+            skill.command,
+            cwd=cwd_str,
+            env=env,
+            capture_output=True,
+            text=True,
+            timeout=skill.timeout_seconds,
+            shell=False,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        duration_ms = int((time.monotonic() - start) * 1000)
+        return ExecutionResult(
+            skill_name=skill.name, handler=skill.handler,
+            command=list(skill.command), cwd=cwd_str,
+            exit_code=-1,
+            stdout=(exc.stdout or "") if isinstance(exc.stdout, str) else "",
+            stderr=(exc.stderr or "") if isinstance(exc.stderr, str) else "",
+            duration_ms=duration_ms, status="timeout", timed_out=True,
+            error=f"Timed out after {skill.timeout_seconds}s",
+        )
+    except FileNotFoundError as exc:
+        duration_ms = int((time.monotonic() - start) * 1000)
+        return ExecutionResult(
+            skill_name=skill.name, handler=skill.handler,
+            command=list(skill.command), cwd=cwd_str,
+            exit_code=-1, stdout="", stderr="",
+            duration_ms=duration_ms, status="error",
+            error=f"Command not found: {exc.filename or skill.command[0]}",
+        )
+
+    duration_ms = int((time.monotonic() - start) * 1000)
+    status = "success" if completed.returncode == 0 else "failure"
+    return ExecutionResult(
+        skill_name=skill.name, handler=skill.handler,
+        command=list(skill.command), cwd=cwd_str,
+        exit_code=completed.returncode,
+        stdout=completed.stdout or "",
+        stderr=completed.stderr or "",
+        duration_ms=duration_ms, status=status,
+    )

package/scripts/runtime_registry.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""
+Runtime Registry — discovers skills with execution metadata.
+
+Responsibilities:
+- Discover skills with execution blocks in frontmatter
+- Validate handler support
+- Expose list of runtime-capable skills
+- Provide skill metadata lookup
+
+Usage:
+    python3 scripts/runtime_registry.py [--root ROOT] [--format text|json]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, asdict, field
+from pathlib import Path
+from typing import List, Optional
+
+# Import shared parsing from skill_linter
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from skill_linter import (
+    FRONTMATTER_PATTERN,
+    DESCRIPTION_PATTERN,
+    NAME_PATTERN,
+    VALID_EXECUTION_TYPES,
+    VALID_EXECUTION_HANDLERS,
+    parse_execution_block,
+    extract_frontmatter,
+)
+
+
+@dataclass
+class SkillRuntime:
+    """Runtime metadata for a single skill."""
+    name: str
+    path: str
+    description: str
+    execution_type: str
+    handler: str
+    timeout_seconds: int
+    safety_mode: Optional[str]
+    allowed_tools: List[str]
+    command: List[str] = field(default_factory=list)
+
+    @property
+    def is_executable(self) -> bool:
+        return self.execution_type in ("assisted", "automated")
+
+    @property
+    def is_automated(self) -> bool:
+        return self.execution_type == "automated"
+
+    @property
+    def is_runnable(self) -> bool:
+        """True when the skill declares an executable command for a real handler."""
+        return bool(self.command) and self.handler in {"shell", "php", "node"}
+
+
+def discover_skills(root: Path) -> List[Path]:
+    """Find all SKILL.md files, preferring .agent-src.uncompressed/."""
+    uncompressed = root / ".agent-src.uncompressed" / "skills"
+    compressed = root / ".agent-src" / "skills"
+    base = uncompressed if uncompressed.exists() else compressed
+    if not base.exists():
+        return []
+    return sorted(f for f in base.rglob("SKILL.md") if not f.is_symlink())
+
+
+def parse_skill_runtime(path: Path) -> Optional[SkillRuntime]:
+    """Parse a skill file and return its runtime metadata, or None if no execution block."""
+    text = path.read_text(encoding="utf-8")
+    frontmatter = extract_frontmatter(text)
+    if frontmatter is None:
+        return None
+
+    execution = parse_execution_block(frontmatter)
+    if execution is None:
+        return None
+
+    # Extract name and description
+    name_match = NAME_PATTERN.search(frontmatter)
+    name = name_match.group(1).strip() if name_match else path.parent.name
+    desc_match = DESCRIPTION_PATTERN.search(frontmatter)
+    description = desc_match.group(1).strip() if desc_match else ""
+
+    return SkillRuntime(
+        name=name,
+        path=str(path),
+        description=description,
+        execution_type=execution.get("type", "manual"),
+        handler=execution.get("handler", "none"),
+        timeout_seconds=execution.get("timeout_seconds", 30),
+        safety_mode=execution.get("safety_mode"),
+        allowed_tools=execution.get("allowed_tools", []),
+        command=execution.get("command", []),
+    )
+
+
+def build_registry(root: Path) -> List[SkillRuntime]:
+    """Build the full runtime registry from all skills."""
+    skills = discover_skills(root)
+    registry: List[SkillRuntime] = []
+    for skill_path in skills:
+        runtime = parse_skill_runtime(skill_path)
+        if runtime is not None:
+            registry.append(runtime)
+    return registry
+
+
+def validate_registry(registry: List[SkillRuntime]) -> List[str]:
+    """Validate the registry for consistency issues."""
+    errors: List[str] = []
+    for skill in registry:
+        if skill.execution_type not in VALID_EXECUTION_TYPES:
+            errors.append(f"{skill.name}: invalid execution type '{skill.execution_type}'")
+        if skill.handler not in VALID_EXECUTION_HANDLERS:
+            errors.append(f"{skill.name}: invalid handler '{skill.handler}'")
+        if skill.is_automated:
+            if skill.handler == "none":
+                errors.append(f"{skill.name}: automated skill has handler 'none'")
+            if skill.safety_mode != "strict":
+                errors.append(f"{skill.name}: automated skill missing safety_mode 'strict'")
+    return errors
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Runtime Registry — list runtime-capable skills")
+    parser.add_argument("--root", type=Path, default=Path("."), help="Repository root")
+    parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format")
+    parser.add_argument("--validate", action="store_true", help="Validate registry consistency")
+    args = parser.parse_args()
+
+    registry = build_registry(args.root)
+
+    if args.validate:
+        errors = validate_registry(registry)
+        if errors:
+            for e in errors:
+                print(f"ERROR: {e}", file=sys.stderr)
+            return 1
+        print(f"Registry valid: {len(registry)} runtime-capable skills")
+        return 0
+
+    if args.format == "json":
+        print(json.dumps([asdict(s) for s in registry], indent=2))
+    else:
+        if not registry:
+            print("No runtime-capable skills found.")
+        else:
+            print(f"Runtime-capable skills: {len(registry)}\n")
+            for s in registry:
+                tools = ", ".join(s.allowed_tools) if s.allowed_tools else "none"
+                print(f"  {s.name}")
+                print(f"    type: {s.execution_type} | handler: {s.handler} | "
+                      f"timeout: {s.timeout_seconds}s | tools: {tools}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/schemas/command.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/command.schema.json",
+  "title": "Command frontmatter",
+  "$comment": "Source: agents/docs/frontmatter-contract.md#commands. `description` is required at schema level because 66/67 commands declare it — the one exception is a known gap, not a supported shape.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "description", "disable-model-invocation"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500
+    },
+    "disable-model-invocation": {
+      "type": "boolean",
+      "enum": [true],
+      "description": "Commands are always user-invoked; model-invocation is disabled."
+    },
+    "skills": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$"
+      }
+    }
+  }
+}

package/scripts/schemas/persona.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/persona.schema.json",
+  "title": "Persona frontmatter",
+  "$comment": "Source: agents/docs/frontmatter-contract.md#personas. `mode` enum mirrors the values declared in personas/*.md plus the additional `incident` value from templates/persona.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "role", "description", "tier", "mode", "version", "source"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Must match the persona filename stem."
+    },
+    "role": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240
+    },
+    "tier": {
+      "type": "string",
+      "enum": ["core", "specialist"]
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["developer", "reviewer", "tester", "product-owner", "incident", "planner"]
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+(\\.[0-9]+){0,2}$"
+    },
+    "source": {
+      "type": "string",
+      "enum": ["package", "project"]
+    }
+  }
+}

package/scripts/schemas/rule.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/rule.schema.json",
+  "title": "Rule frontmatter",
+  "$comment": "Source: agents/docs/frontmatter-contract.md#rules. `type` is authoritative; `alwaysApply` is a Cursor/Cline sidecar and accepted but not enforced.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["type", "source", "description"],
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": ["always", "auto"]
+    },
+    "source": {
+      "type": "string",
+      "enum": ["package", "project"]
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500
+    },
+    "alwaysApply": {
+      "type": "boolean",
+      "description": "Optional sidecar for Cursor/Cline; by convention true when type=always, false when type=auto."
+    }
+  }
+}