okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py

@@ -0,0 +1,215 @@
+"""argparse 표면과 명령 분배.
+
+여기 있는 것은 인자 정의와 `main` 의 분기뿐이다. 각 명령의 실제 동작은
+`materialize` 와 `results` 에 있다. `_CLI_EPILOG` 는 이 명령의 사용법 정본이다 —
+TypeScript 포워더가 들고 있던 USAGE 문자열이 여기로 왔다.
+"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+
+from ..invocation import AgentInvocationError
+from ...worker_prompt_headers import WorkerPromptHeaderError
+from ...dispatch_state import BACKEND_CLI_WRAPPER, BACKEND_CMUX_PANE, DispatchError
+from .emit import _emit, _prepared_payload
+from .inputs import AgentPromptCliError
+from .materialize import _materialize
+from .results import (
+    _complete,
+    _link_result,
+    _materialize_result,
+    _record_dispatch,
+    _abandon_attempt,
+    _reject_result,
+    _verify,
+    _verify_completion,
+)
+
+
+_CLI_EPILOG = r"""Usage:
+  okstra agent-prompt materialize [options]
+  okstra agent-prompt verify [options]
+  okstra agent-prompt materialize-result [options]
+  okstra agent-prompt complete [options]
+  okstra agent-prompt verify-completion [options]
+  okstra agent-prompt record-dispatch [options]
+  okstra agent-prompt link-result [options]
+"""
+
+
+_CLI_DESCRIPTION = "Materialize and verify auditable agent invocations."
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra agent-prompt")
+    commands = parser.add_subparsers(dest="command", required=True)
+    _add_materialize_parser(commands)
+    _add_completion_parsers(commands)
+    _add_dispatch_parsers(commands)
+    return parser
+
+
+def _add_materialize_parser(commands: argparse._SubParsersAction) -> None:
+    materialize = commands.add_parser("materialize")
+    _common_paths(materialize)
+    materialize.add_argument("--invocation-id", required=True)
+    materialize.add_argument("--audience", required=True)
+    materialize.add_argument("--instruction", required=True)
+    materialize.add_argument("--prompt", required=True)
+    materialize.add_argument("--run-manifest")
+    materialize.add_argument("--worker-id")
+    materialize.add_argument("--dispatch-kind")
+    materialize.add_argument("--assignment-ref")
+    materialize.add_argument("--source-role-execution-ref")
+    materialize.add_argument("--result")
+    materialize.add_argument("--audit-source")
+    materialize.add_argument("--host-runtime")
+    materialize.add_argument(
+        "--terminal-backend",
+        choices=(BACKEND_CLI_WRAPPER, BACKEND_CMUX_PANE),
+    )
+    materialize.add_argument("--provider")
+    materialize.add_argument("--model-role")
+    materialize.add_argument("--model", default="")
+    materialize.add_argument("--purpose")
+    materialize.add_argument(
+        "--replace-undispatched",
+        action="store_true",
+        help="rewrite a prompt this invocation id already wrote, allowed only "
+             "while no dispatch has referenced it — the exit for a prompt that "
+             "failed a pre-dispatch gate and never ran. Not available for v2 "
+             "reverify prompts (--assignment-ref reverify/…): their reservation "
+             "records the prompt's input digest in the run manifest and "
+             "reservations are append-only, so a rewrite needs a fresh "
+             "invocation id and prompt path",
+    )
+    materialize.add_argument("--json", action="store_true")
+
+    verify = commands.add_parser("verify")
+    _common_paths(verify)
+    verify.add_argument("--run-manifest")
+    verify.add_argument("--metadata", required=True)
+    verify.add_argument("--json", action="store_true")
+    verify.add_argument("--text", action="store_true")
+
+
+def _add_completion_parsers(commands: argparse._SubParsersAction) -> None:
+    materialize_result = commands.add_parser("materialize-result")
+    _standalone_completion_args(materialize_result)
+    materialize_result.add_argument("--returned-body-file", required=True)
+
+    complete = commands.add_parser("complete")
+    _standalone_completion_args(complete)
+
+    verify_completion = commands.add_parser("verify-completion")
+    _common_paths(verify_completion)
+    verify_completion.add_argument("--purpose", required=True)
+    verify_completion.add_argument("--completion", required=True)
+    verify_completion.add_argument("--json", action="store_true")
+
+
+def _add_dispatch_parsers(commands: argparse._SubParsersAction) -> None:
+    record_dispatch = commands.add_parser("record-dispatch")
+    _common_paths(record_dispatch)
+    record_dispatch.add_argument("--run-manifest", required=True)
+    record_dispatch.add_argument("--metadata", required=True)
+    record_dispatch.add_argument(
+        "--enforcement-mode",
+        required=True,
+        choices=("core-pre-dispatch", "host-native-spec-link-gate"),
+    )
+    record_dispatch.add_argument("--json", action="store_true")
+
+    reject_result = commands.add_parser(
+        "reject-result",
+        help="mark a linked result rejected so a corrective re-dispatch can "
+             "claim its path",
+    )
+    _common_paths(reject_result)
+    reject_result.add_argument("--run-manifest", required=True)
+    reject_result.add_argument("--dispatch-id", required=True)
+    reject_result.add_argument("--superseded-by", required=True)
+    reject_result.add_argument("--reason", required=True)
+    reject_result.add_argument("--json", action="store_true")
+
+    abandon = commands.add_parser(
+        "abandon-attempt",
+        help="close a started source-readonly attempt whose worker died "
+             "without a result, so a retry can follow it",
+    )
+    _common_paths(abandon)
+    abandon.add_argument("--run-manifest", required=True)
+    abandon.add_argument("--invocation-ref", required=True)
+    abandon.add_argument("--reason", required=True)
+    abandon.add_argument("--json", action="store_true")
+
+    link_result = commands.add_parser("link-result")
+    _common_paths(link_result)
+    link_result.add_argument("--run-manifest", required=True)
+    link_result.add_argument("--dispatch-id", required=True)
+    link_result.add_argument("--result", required=True)
+    link_result.add_argument("--json", action="store_true")
+
+
+def _common_paths(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--project-root", required=True)
+
+
+def _standalone_completion_args(parser: argparse.ArgumentParser) -> None:
+    _common_paths(parser)
+    parser.add_argument("--purpose", required=True)
+    parser.add_argument("--metadata", required=True)
+    parser.add_argument("--json", action="store_true")
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        args = _parser().parse_args(argv)
+        if args.command == "materialize":
+            prepared = _materialize(args)
+            _emit(_prepared_payload(prepared, args.audience), args.json)
+            return 0
+        if args.command == "verify":
+            _verify(args)
+            _emit(
+                {"ok": True, "metadataPath": str(Path(args.metadata).resolve())},
+                args.json,
+                args.text,
+            )
+            return 0
+        if args.command == "materialize-result":
+            _materialize_result(args)
+            return 0
+        if args.command == "complete":
+            _complete(args)
+            return 0
+        if args.command == "verify-completion":
+            _verify_completion(args)
+            return 0
+        if args.command == "record-dispatch":
+            _record_dispatch(args)
+            return 0
+        if args.command == "reject-result":
+            _reject_result(args)
+            return 0
+        if args.command == "abandon-attempt":
+            _abandon_attempt(args)
+            return 0
+        _link_result(args)
+        return 0
+    except (
+        AgentPromptCliError,
+        AgentInvocationError,
+        DispatchError,
+        WorkerPromptHeaderError,
+        OSError,
+        ValueError,
+    ) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2

package/runtime/python/okstra_ctl/agent/prompt_cli/dynamic_verifier.py

@@ -0,0 +1,155 @@
+"""동적 검증자 요청을 예약하고, 그 출처가 자격이 있는지 본다.
+
+재검증 라운드에서 리드가 추가 검증자를 요청할 수 있고, 그 요청은 예약(슬롯
+확보)과 자격 검사(요청한 role 이 이 run 에서 그럴 수 있는가)를 함께 통과해야
+한다. 두 가지가 한 파일에 있는 이유는 예약이 자격 검사를 통과한 뒤에만
+일어나야 하기 때문이다 — 순서가 곧 계약이다.
+"""
+from __future__ import annotations
+
+import argparse
+from dataclasses import replace
+import hashlib
+from pathlib import Path
+from typing import Any, Mapping
+
+from ..invocation import (
+    AgentInvocationRequest,
+    AgentModelAssignment,
+    compose_agent_prompt,
+    compose_unbound_run_prompt,
+    v2_role_assignment_authority_errors,
+)
+from ...convergence_store import (
+    DYNAMIC_VERIFIER_SOURCE_ROLES,
+    reserve_dynamic_verifier,
+)
+from .inputs import AgentPromptCliError
+
+
+def _reserve_dynamic_verifier_request(
+    request: AgentInvocationRequest,
+    *,
+    args: argparse.Namespace,
+    manifest: Mapping[str, Any],
+    manifest_path: Path,
+    source_role_execution_ref: str,
+) -> AgentInvocationRequest:
+    _validate_dynamic_source_assignment(
+        manifest,
+        source_role_execution_ref,
+        request.assignment,
+    )
+    prompt_bytes = compose_unbound_run_prompt(request)
+    verifier, invocation = reserve_dynamic_verifier(
+        manifest_path,
+        source_role_execution_ref=source_role_execution_ref,
+        duty_id=args.audience,
+        round_number=_reverify_round(args.dispatch_kind),
+        task_key=_required_manifest_string(manifest, "taskKey"),
+        input_digest="sha256:" + hashlib.sha256(prompt_bytes).hexdigest(),
+        invocation_ref=args.invocation_id,
+    )
+    bound = replace(
+        request,
+        worker_id=None,
+        participant_ref=verifier.participant_ref,
+        role_execution_ref=verifier.role_execution_ref,
+        duty_id=args.audience,
+        invocation_ref=invocation.invocation_ref,
+    )
+    if compose_agent_prompt(bound).encode("utf-8") != prompt_bytes:
+        raise AgentPromptCliError(
+            "dynamic verifier identity changed immutable prompt bytes"
+        )
+    return bound
+
+
+def _dynamic_verifier_source(
+    args: argparse.Namespace,
+    manifest: Mapping[str, Any],
+) -> str | None:
+    is_v2 = (
+        manifest.get("schemaVersion") == "2.0"
+        and manifest.get("executionIdentityVersion") == 2
+    )
+    is_reverify = (
+        args.assignment_ref.startswith("reverify/")
+        and args.audience == "reverification-worker"
+    )
+    source = args.source_role_execution_ref
+    if is_v2 and is_reverify:
+        if args.replace_undispatched:
+            raise AgentPromptCliError(
+                "v2 dynamic verifier prompts are append-only: this "
+                "invocation's reservation already recorded this prompt's input "
+                "digest in the run manifest, and a reservation cannot be "
+                "rewritten. Use a fresh invocation ID and prompt path."
+            )
+        if not source:
+            raise AgentPromptCliError(
+                "v2 reverify materialization requires "
+                "--source-role-execution-ref"
+            )
+        return source
+    if source:
+        raise AgentPromptCliError(
+            "--source-role-execution-ref is allowed only for v2 reverify"
+        )
+    return None
+
+
+def _reverify_round(dispatch_kind: str) -> int:
+    prefix = "reverify-r"
+    value = dispatch_kind.removeprefix(prefix)
+    if not dispatch_kind.startswith(prefix) or not value.isdigit() or int(value) < 1:
+        raise AgentPromptCliError(
+            "dynamic verifier dispatch kind must be reverify-r<N>"
+        )
+    return int(value)
+
+
+def _validate_dynamic_source_assignment(
+    manifest: Mapping[str, Any],
+    source_role_execution_ref: str,
+    assignment: AgentModelAssignment,
+) -> None:
+    rows = manifest.get("roleExecutions")
+    source = next(
+        (
+            row
+            for row in rows
+            if isinstance(row, Mapping)
+            and row.get("roleExecutionRef") == source_role_execution_ref
+        ),
+        None,
+    ) if isinstance(rows, list) else None
+    if source is None:
+        raise AgentPromptCliError(
+            f"source role execution is unknown: {source_role_execution_ref}"
+        )
+    if source.get("role") not in DYNAMIC_VERIFIER_SOURCE_ROLES:
+        raise AgentPromptCliError(
+            "dynamic verifier source role is not eligible for re-verification"
+        )
+    errors = v2_role_assignment_authority_errors(
+        manifest,
+        role_execution_ref=source_role_execution_ref,
+        participant_ref=str(source.get("participantRef") or ""),
+        assignment=assignment,
+    )
+    if errors:
+        raise AgentPromptCliError(
+            "dynamic verifier source does not match the selected assignment: "
+            + "; ".join(errors)
+        )
+
+
+def _required_manifest_string(
+    manifest: Mapping[str, Any],
+    key: str,
+) -> str:
+    value = manifest.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise AgentPromptCliError(f"run manifest has no {key}")
+    return value

package/runtime/python/okstra_ctl/agent/prompt_cli/emit.py

@@ -0,0 +1,66 @@
+"""명령의 결과를 표준 출력으로 내보낸다.
+
+`--json` 이면 JSON, 아니면 고정 Markdown 줄이다. 두 형태를 한자리에 둬서
+명령마다 출력 모양이 갈라지지 않게 한다. 파일을 읽지도 쓰지도 않는다.
+"""
+from __future__ import annotations
+
+import json
+from typing import Mapping
+
+from ..invocation import PreparedAgentInvocation
+from ...fixed_text import line
+
+
+
+def _prepared_payload(
+    prepared: PreparedAgentInvocation,
+    audience: str,
+) -> dict[str, object]:
+    assignment = prepared.assignment
+    return {
+        "ok": True,
+        "invocationId": prepared.invocation_id,
+        "workerId": prepared.worker_id,
+        "assignmentRef": prepared.assignment_ref,
+        "audience": audience,
+        "promptPath": str(prepared.prompt_path),
+        "metadataPath": str(prepared.metadata_path),
+        "modelAssignment": {
+            "provider": assignment.provider,
+            "model": assignment.model,
+            "modelExecutionValue": assignment.model_execution_value,
+            "runner": assignment.runner,
+            "hostRuntime": assignment.host_runtime,
+            "hostModelValue": assignment.host_model_value,
+        },
+        "digests": {
+            "catalogDigest": prepared.catalog_digest,
+            "assignmentDigest": prepared.assignment_digest,
+            "dutyDigest": prepared.duty_digest,
+            "instructionDigest": prepared.instruction_digest,
+            "promptDigest": prepared.prompt_digest,
+        },
+    }
+
+
+def _emit(
+    payload: Mapping[str, object], as_json: bool, as_text: bool = False
+) -> None:
+    if as_json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    elif as_text:
+        print(render_agent_prompt_text(payload), end="")
+    else:
+        print(payload.get("promptPath") or payload.get("metadataPath") or "ok")
+
+
+def render_agent_prompt_text(payload: Mapping[str, object]) -> str:
+    """agent prompt 검증 결과의 승인된 경로만 투영한다."""
+    rows = ["Okstra agent prompt\n"]
+    rows.append(line("Status", "ready" if payload.get("ok", True) else "error"))
+    for label, key in (("Prompt path", "promptPath"), ("Metadata path", "metadataPath"),
+                       ("Assignment ID", "assignmentId"), ("Worker role", "workerRole")):
+        if key in payload:
+            rows.append(line(label, payload.get(key)))
+    return "".join(rows)

package/runtime/python/okstra_ctl/agent/prompt_cli/inputs.py

@@ -0,0 +1,138 @@
+"""명령이 받은 경로를 해석하고, 허용된 것만 돌려준다.
+
+이 CLI 는 모델이 부르는 표면이라 경로 인자를 그대로 믿을 수 없다. 여기 있는
+함수들은 전부 같은 모양이다 — 받은 문자열을 절대 경로로 만들고, 프로젝트
+루트(또는 명시된 상위) 안에 있는지 확인하고, 벗어나면 거절한다. 어느 것도
+okstra 의 phase 나 role 을 모른다.
+
+`AgentPromptCliError` 도 여기 있다. 모든 층이 이 하나로 실패를 알린다.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from pathlib import PurePosixPath
+from typing import Any, Mapping
+
+from ...json_boundary import JsonBoundaryError, load_owned_object
+
+
+
+class AgentPromptCliError(RuntimeError):
+    """Raised when CLI input cannot become a valid invocation request."""
+
+
+def _authorized_path(
+    project_root: Path,
+    raw_path: str,
+    raw_roots: object,
+    label: str,
+    *,
+    must_exist: bool,
+) -> Path:
+    if not isinstance(raw_roots, list) or not raw_roots:
+        raise AgentPromptCliError(f"run manifest has no authorized {label} roots")
+    path = _candidate(project_root, raw_path, must_exist=must_exist, label=label)
+    roots = [
+        _project_manifest_path(project_root, value, f"{label} root", must_exist=True)
+        for value in raw_roots
+    ]
+    if not any(_is_relative_to(path, root) for root in roots):
+        raise AgentPromptCliError(f"{label} path is outside authorized roots: {path}")
+    return path
+
+
+def _candidate(project_root: Path, raw: str, *, must_exist: bool, label: str) -> Path:
+    candidate = Path(raw)
+    if not candidate.is_absolute():
+        candidate = project_root / candidate
+    try:
+        if must_exist or candidate.exists() or candidate.is_symlink():
+            return candidate.resolve(strict=True)
+        return candidate.parent.resolve(strict=True) / candidate.name
+    except OSError as exc:
+        raise AgentPromptCliError(f"{label} path is invalid: {candidate}") from exc
+
+
+def _project_input(project_root: Path, raw: str, label: str) -> Path:
+    path = _candidate(project_root, raw, must_exist=True, label=label)
+    if not _is_relative_to(path, project_root):
+        raise AgentPromptCliError(f"{label} path escapes project root: {path}")
+    return path
+
+
+def _project_manifest_path(
+    project_root: Path,
+    value: object,
+    label: str,
+    *,
+    must_exist: bool,
+) -> Path:
+    if not isinstance(value, str) or not value:
+        raise AgentPromptCliError(f"{label} path is invalid")
+    pure = PurePosixPath(value)
+    if pure.is_absolute() or any(part in {"", ".", ".."} for part in pure.parts):
+        raise AgentPromptCliError(f"{label} path is invalid")
+    path = _candidate(project_root, value, must_exist=must_exist, label=label)
+    if not _is_relative_to(path, project_root):
+        raise AgentPromptCliError(f"{label} path escapes project root: {path}")
+    return path
+
+
+def _exact_path(raw: str, expected: Path, must_exist: bool, label: str) -> Path:
+    actual = (
+        Path(raw).resolve(strict=True)
+        if must_exist
+        else Path(raw).parent.resolve(strict=True) / Path(raw).name
+    )
+    expected_actual = (
+        expected.resolve(strict=True)
+        if must_exist
+        else expected.parent.resolve(strict=True) / expected.name
+    )
+    if actual != expected_actual:
+        raise AgentPromptCliError(f"{label} does not use canonical standalone path")
+    return actual
+
+
+def _project_root(value: str) -> Path:
+    try:
+        return Path(value).resolve(strict=True)
+    except OSError as exc:
+        raise AgentPromptCliError(f"project root not found: {value}") from exc
+
+
+def _relative(project_root: Path, path: Path) -> str:
+    try:
+        return path.relative_to(project_root).as_posix()
+    except ValueError as exc:
+        raise AgentPromptCliError(f"path escapes project root: {path}") from exc
+
+
+def _read_json_object(path: Path, label: str) -> dict[str, Any]:
+    try:
+        value = load_owned_object(path, artifact="agent prompt metadata")
+    except JsonBoundaryError as exc:
+        raise AgentPromptCliError(f"{label} is invalid: {path}") from exc
+    if not isinstance(value, dict):
+        raise AgentPromptCliError(f"{label} must be a JSON object: {path}")
+    return value
+
+
+def _mapping(value: object, label: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise AgentPromptCliError(f"{label} is missing or invalid")
+    return value
+
+
+def _is_relative_to(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return False
+    return True
+
+
+def _is_slug(value: str) -> bool:
+    if not value or value.startswith("-") or value.endswith("-"):
+        return False
+    return all(part.isalnum() and part.lower() == part for part in value.split("-"))