okstra 0.168.0 → 0.169.1

package/runtime/python/okstra_ctl/agent_prompt_cli.py

@@ -0,0 +1,796 @@
+"""Materialize and verify one auditable LLM invocation specification."""
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+from pathlib import PurePosixPath
+import shutil
+import sys
+import tempfile
+from typing import Any, Mapping, get_args
+
+from .agent_invocation import (
+    AgentInstruction,
+    AgentInstructionSource,
+    AgentAudience,
+    AgentInvocationError,
+    AgentInvocationRequest,
+    AgentModelAssignment,
+    PreparedAgentInvocation,
+    agent_model_assignment_from_payload,
+    digest_duty_catalog,
+    materialize_standalone_result,
+    prepare_agent_invocation,
+    publish_standalone_completion,
+    verify_standalone_completion,
+    verify_agent_invocation,
+)
+from .application.resolve_assignment import resolve_assignment_runner
+from .model_discovery import normalize_execution_for_dispatch
+from .models import provider_default_model, resolve_model_metadata
+from .path_hints import hydrate_active_run_context
+from .ports.host_model import HostModelBindingRequest
+from .registry.host_registry import default_host_registry
+from .registry.provider_registry import default_provider_registry
+from .worker_prompt_headers import WorkerPromptHeaderError, worker_prompt_headers
+from .worker_prompt_policy import resolve_prompt_plan_for_manifest
+from .dispatch_state import (
+    DispatchError,
+    link_agent_dispatch_result,
+    record_verified_agent_dispatch,
+)
+
+
+_AUDIENCES = frozenset(get_args(AgentAudience))
+
+
+class AgentPromptCliError(RuntimeError):
+    """Raised when CLI input cannot become a valid invocation request."""
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="okstra agent-prompt")
+    commands = parser.add_subparsers(dest="command", required=True)
+    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("--result")
+    materialize.add_argument("--audit-source")
+    materialize.add_argument("--host-runtime")
+    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",
+    )
+    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")
+
+    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")
+
+    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")
+
+    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")
+    return parser
+
+
+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,
+            )
+            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
+        _link_result(args)
+        return 0
+    except (
+        AgentPromptCliError,
+        AgentInvocationError,
+        DispatchError,
+        WorkerPromptHeaderError,
+        OSError,
+        ValueError,
+    ) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+def _materialize(args: argparse.Namespace) -> PreparedAgentInvocation:
+    project_root = _project_root(args.project_root)
+    if args.run_manifest:
+        return _materialize_run(args, project_root)
+    return _materialize_standalone(args, project_root)
+
+
+def _record_dispatch(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    record = record_verified_agent_dispatch(
+        project_root=project_root,
+        run_manifest_path=_project_input(
+            project_root, args.run_manifest, "run manifest"
+        ),
+        metadata_path=_project_input(
+            project_root, args.metadata, "agent invocation metadata"
+        ),
+        enforcement_mode=args.enforcement_mode,
+    )
+    _emit(record, args.json)
+
+
+def _link_result(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    link = link_agent_dispatch_result(
+        project_root=project_root,
+        run_manifest_path=_project_input(
+            project_root, args.run_manifest, "run manifest"
+        ),
+        dispatch_id=args.dispatch_id,
+        result_path=_project_input(project_root, args.result, "agent result"),
+    )
+    _emit(link, args.json)
+
+
+def _materialize_run(
+    args: argparse.Namespace,
+    project_root: Path,
+) -> PreparedAgentInvocation:
+    required = {
+        "worker-id": args.worker_id,
+        "dispatch-kind": args.dispatch_kind,
+        "assignment-ref": args.assignment_ref,
+        "result": args.result,
+    }
+    missing = [name for name, value in required.items() if not value]
+    if missing:
+        raise AgentPromptCliError(
+            f"run materialization requires: {', '.join('--' + name for name in missing)}"
+        )
+    forbidden = {
+        "host-runtime": args.host_runtime,
+        "provider": args.provider,
+        "model-role": args.model_role,
+        "model": args.model,
+        "purpose": args.purpose,
+    }
+    present = [name for name, value in forbidden.items() if value]
+    if present:
+        raise AgentPromptCliError(
+            f"run materialization forbids: {', '.join('--' + name for name in present)}"
+        )
+    manifest_path = _project_input(project_root, args.run_manifest, "run manifest")
+    manifest = _read_json_object(manifest_path, "run manifest")
+    contract = _mapping(manifest.get("agentContract"), "run agent contract")
+    authorized = _mapping(contract.get("authorizedPaths"), "authorized paths")
+
+    instruction_path = _authorized_path(
+        project_root,
+        args.instruction,
+        authorized.get("instructionRoots"),
+        "instruction",
+        must_exist=True,
+    )
+    prompt_path = _authorized_path(
+        project_root,
+        args.prompt,
+        authorized.get("promptRoots"),
+        "prompt",
+        must_exist=False,
+    )
+    result_path = _authorized_path(
+        project_root,
+        args.result,
+        authorized.get("resultRoots"),
+        "result",
+        must_exist=False,
+    )
+    audit_source_path = (
+        _authorized_path(
+            project_root,
+            args.audit_source,
+            authorized.get("resultRoots"),
+            "audit source",
+            must_exist=False,
+        )
+        if args.audit_source
+        else result_path
+    )
+    _validate_run_identity(
+        manifest,
+        worker_id=args.worker_id,
+        dispatch_kind=args.dispatch_kind,
+        assignment_ref=args.assignment_ref,
+        audience=args.audience,
+    )
+    assignments = _mapping(
+        manifest.get("invocationAssignments"),
+        "run invocation assignments",
+    )
+    if args.assignment_ref not in assignments:
+        raise AgentPromptCliError(
+            f"assignment reference is missing from run manifest: {args.assignment_ref}"
+        )
+    assignment = agent_model_assignment_from_payload(assignments[args.assignment_ref])
+    duty_root = _project_manifest_path(
+        project_root,
+        contract.get("dutyRootPath"),
+        "duty root",
+        must_exist=True,
+    )
+    if contract.get("catalogDigest") != digest_duty_catalog(duty_root):
+        raise AgentPromptCliError("run duty snapshot catalog digest does not match")
+    active_context_path = _project_manifest_path(
+        project_root,
+        manifest.get("activeRunContextPath"),
+        "active run context",
+        must_exist=True,
+    )
+    active_context = hydrate_active_run_context(
+        _read_json_object(active_context_path, "active run context")
+    )
+    prompt_rel = _relative(project_root, prompt_path)
+    result_rel = _relative(project_root, result_path)
+    audit_rel = _relative(project_root, audit_source_path)
+    anchor_lines = tuple(worker_prompt_headers(
+        project_root=project_root,
+        prompt_rel=prompt_rel,
+        result_rel=result_rel,
+        audit_source_rel=audit_rel,
+        worker_id=args.worker_id,
+        dispatch_kind=args.dispatch_kind,
+        manifest=manifest,
+        active_context=active_context,
+    ))
+    return prepare_agent_invocation(AgentInvocationRequest(
+        invocation_id=args.invocation_id,
+        worker_id=args.worker_id,
+        audience=args.audience,
+        assignment_ref=args.assignment_ref,
+        purpose=None,
+        assignment=assignment,
+        instruction=AgentInstruction(
+            anchor_lines=anchor_lines,
+            body=instruction_path.read_text(encoding="utf-8"),
+            source_paths=(AgentInstructionSource(
+                kind="project",
+                path=_relative(project_root, instruction_path),
+            ),),
+        ),
+        project_root=project_root,
+        run_manifest_path=manifest_path,
+        duty_root=duty_root,
+        prompt_path=prompt_path,
+        metadata_path=prompt_path.with_name(prompt_path.name + ".meta.json"),
+        dispatch_kind=args.dispatch_kind,
+        replace_undispatched=args.replace_undispatched,
+    ))
+
+
+def _validate_run_identity(
+    manifest: Mapping[str, Any],
+    *,
+    worker_id: str,
+    dispatch_kind: str,
+    assignment_ref: str,
+    audience: str,
+) -> None:
+    expected: str
+    if assignment_ref == "lead":
+        expected = "lead"
+        if worker_id != "lead":
+            raise AgentPromptCliError("lead assignment requires worker ID 'lead'")
+    elif assignment_ref == "translator":
+        expected = "translator"
+        if worker_id != "translator":
+            raise AgentPromptCliError("translator assignment requires worker ID 'translator'")
+    elif assignment_ref.startswith("critic/"):
+        scope = assignment_ref.split("/", 1)[1]
+        expected = {"scope": "scope-critic", "acceptance": "acceptance-critic"}.get(
+            scope,
+            "",
+        )
+        if not expected or dispatch_kind != "critic":
+            raise AgentPromptCliError("critic assignment identity is invalid")
+        convergence = manifest.get("convergence")
+        critic = convergence.get("critic") if isinstance(convergence, Mapping) else None
+        provider = critic.get("provider") if isinstance(critic, Mapping) else None
+        if provider and provider != worker_id:
+            raise AgentPromptCliError("critic worker does not match manifest provider")
+    else:
+        try:
+            expected = resolve_prompt_plan_for_manifest(
+                manifest=manifest,
+                worker_id=worker_id,
+                dispatch_kind=dispatch_kind,
+            ).duty_audience
+        except ValueError as exc:
+            raise AgentPromptCliError(str(exc)) from exc
+    if audience != expected:
+        raise AgentPromptCliError(
+            f"audience {audience!r} does not match required audience {expected!r}"
+        )
+
+
+def _materialize_standalone(
+    args: argparse.Namespace,
+    project_root: Path,
+) -> PreparedAgentInvocation:
+    required = {
+        "host-runtime": args.host_runtime,
+        "provider": args.provider,
+        "model-role": args.model_role,
+        "purpose": args.purpose,
+    }
+    missing = [name for name, value in required.items() if not value]
+    if missing:
+        raise AgentPromptCliError(
+            "standalone materialization requires: "
+            + ", ".join("--" + name for name in missing)
+        )
+    forbidden = {
+        "worker-id": args.worker_id,
+        "dispatch-kind": args.dispatch_kind,
+        "assignment-ref": args.assignment_ref,
+        "result": args.result,
+        "audit-source": args.audit_source,
+    }
+    present = [name for name, value in forbidden.items() if value]
+    if present:
+        raise AgentPromptCliError(
+            "standalone materialization forbids: "
+            + ", ".join("--" + name for name in present)
+        )
+    if not _is_slug(args.purpose) or not _is_slug(args.invocation_id):
+        raise AgentPromptCliError("standalone purpose and invocation ID must be slugs")
+    if args.audience not in _AUDIENCES:
+        raise AgentPromptCliError(f"unknown duty audience: {args.audience}")
+    root = project_root / ".okstra" / "agent-invocations" / args.purpose
+    if not root.is_dir():
+        raise AgentPromptCliError(f"standalone invocation root not found: {root}")
+    resolved_root = root.resolve(strict=True)
+    if not _is_relative_to(resolved_root, project_root):
+        raise AgentPromptCliError("standalone invocation root escapes project root")
+    root = resolved_root
+    expected_instruction = root / f"{args.invocation_id}.instructions.md"
+    expected_prompt = root / f"{args.invocation_id}.prompt.md"
+    instruction_path = _exact_path(args.instruction, expected_instruction, True, "instruction")
+    prompt_path = _exact_path(args.prompt, expected_prompt, False, "prompt")
+    assignment = _standalone_assignment(
+        host_runtime=args.host_runtime,
+        provider=args.provider,
+        model_role=args.model_role,
+        model=args.model,
+    )
+    duty_root = root / f"{args.invocation_id}.duty-contracts"
+    _snapshot_standalone_duties(duty_root)
+    return prepare_agent_invocation(AgentInvocationRequest(
+        invocation_id=args.invocation_id,
+        worker_id=None,
+        audience=args.audience,
+        assignment_ref=None,
+        purpose=args.purpose,
+        assignment=assignment,
+        instruction=AgentInstruction(
+            anchor_lines=(),
+            body=instruction_path.read_text(encoding="utf-8"),
+            source_paths=(AgentInstructionSource(
+                kind="project",
+                path=_relative(project_root, instruction_path),
+            ),),
+        ),
+        project_root=project_root,
+        run_manifest_path=None,
+        duty_root=duty_root,
+        prompt_path=prompt_path,
+        metadata_path=prompt_path.with_name(prompt_path.name + ".meta.json"),
+        dispatch_kind="standalone",
+    ))
+
+
+def _standalone_assignment(
+    *, host_runtime: str, provider: str, model_role: str, model: str,
+) -> AgentModelAssignment:
+    provider_registry = default_provider_registry()
+    provider_spec = provider_registry.resolve(provider)
+    default_model = provider_default_model(provider, model_role)
+    if not default_model:
+        raise AgentPromptCliError(
+            f"provider {provider!r} has no default model for role {model_role!r}"
+        )
+    metadata = resolve_model_metadata(
+        provider=provider,
+        raw_value=model,
+        default_display=default_model,
+        default_execution=default_model,
+    )
+    host_adapter = default_host_registry(provider_registry).resolve(host_runtime)
+    runner = resolve_assignment_runner(
+        host=host_adapter.descriptor,
+        provider=provider_spec,
+        role=model_role,
+    ).runner
+    execution = (
+        normalize_execution_for_dispatch(
+            provider=provider,
+            execution=metadata.execution,
+            role=model_role,
+        )
+        if runner == "cli-wrapper"
+        else metadata.execution
+    )
+    host_model = host_adapter.host_model().resolve(HostModelBindingRequest(
+        host_runtime=host_runtime,
+        provider=provider,
+        model=metadata.display,
+        model_execution_value=execution,
+        runner=runner,
+    ))
+    return AgentModelAssignment(
+        provider=provider,
+        model=metadata.display,
+        model_execution_value=execution,
+        runner=runner,
+        host_runtime=host_runtime,
+        host_model_value=host_model,
+    )
+
+
+def _snapshot_standalone_duties(destination: Path) -> None:
+    source = Path(__file__).resolve().parents[2] / "prompts" / "duties"
+    if not source.is_dir():
+        raise AgentPromptCliError(f"duty contract source not found: {source}")
+    if destination.exists():
+        if not destination.is_dir() or digest_duty_catalog(destination) != digest_duty_catalog(source):
+            raise AgentPromptCliError("standalone duty snapshot conflicts with existing files")
+        return
+    temporary = Path(tempfile.mkdtemp(prefix=f".{destination.name}.", dir=destination.parent))
+    try:
+        shutil.copytree(source, temporary, dirs_exist_ok=True)
+        try:
+            os.rename(temporary, destination)
+        except FileExistsError:
+            if digest_duty_catalog(destination) != digest_duty_catalog(source):
+                raise AgentPromptCliError("standalone duty snapshot publication conflict")
+    finally:
+        if temporary.exists():
+            shutil.rmtree(temporary)
+
+
+def _verify(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    metadata_path = _project_input(project_root, args.metadata, "metadata")
+    metadata = _read_json_object(metadata_path, "metadata")
+    contract_source = _mapping(metadata.get("contractSource"), "contract source")
+    mode = contract_source.get("mode")
+    expected_manifest: Path | None = None
+    expected_assignment: AgentModelAssignment | None = None
+    if mode == "run":
+        if not args.run_manifest:
+            raise AgentPromptCliError("run invocation verification requires --run-manifest")
+        expected_manifest = _project_input(project_root, args.run_manifest, "run manifest")
+        manifest = _read_json_object(expected_manifest, "run manifest")
+        assignments = _mapping(manifest.get("invocationAssignments"), "run assignments")
+        reference = metadata.get("assignmentRef")
+        if not isinstance(reference, str) or reference not in assignments:
+            raise AgentPromptCliError("assignment reference is missing from run manifest")
+        expected_assignment = agent_model_assignment_from_payload(assignments[reference])
+    elif mode == "standalone":
+        if args.run_manifest:
+            raise AgentPromptCliError("standalone invocation verification forbids --run-manifest")
+    else:
+        raise AgentPromptCliError("contract source mode is invalid")
+    errors = verify_agent_invocation(
+        metadata_path,
+        project_root=project_root,
+        expected_run_manifest_path=expected_manifest,
+        expected_assignment=expected_assignment,
+    )
+    if errors:
+        raise AgentPromptCliError("; ".join(errors))
+
+
+def _materialize_result(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    metadata_path = _project_input(project_root, args.metadata, "metadata")
+    root = project_root / ".okstra" / "agent-invocations" / args.purpose
+    temporary_root = root / ".tmp"
+    returned_body_path = _project_input(
+        project_root,
+        args.returned_body_file,
+        "returned body",
+    )
+    if not temporary_root.is_dir() or not _is_relative_to(
+        returned_body_path,
+        temporary_root.resolve(strict=True),
+    ):
+        raise AgentPromptCliError(
+            "returned body file must be inside the standalone purpose .tmp directory"
+        )
+    result = materialize_standalone_result(
+        project_root=project_root,
+        purpose=args.purpose,
+        metadata_path=metadata_path,
+        returned_body=returned_body_path.read_bytes(),
+    )
+    _emit({
+        "ok": True,
+        "purpose": result.purpose,
+        "invocationId": result.invocation_id,
+        "metadataPath": str(result.prompt_metadata_path),
+        "resultPath": str(result.result_path),
+        "resultEnvelopeDigest": result.result_envelope_digest,
+    }, args.json)
+
+
+def _complete(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    metadata_path = _project_input(project_root, args.metadata, "metadata")
+    completion = publish_standalone_completion(
+        project_root=project_root,
+        purpose=args.purpose,
+        metadata_path=metadata_path,
+        completed_at=datetime.now(timezone.utc),
+    )
+    _emit({
+        "ok": True,
+        "purpose": args.purpose,
+        "metadataPath": str(metadata_path),
+        "completionPath": str(completion),
+    }, args.json)
+
+
+def _verify_completion(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    completion_path = _project_input(
+        project_root,
+        args.completion,
+        "completion",
+    )
+    verified = verify_standalone_completion(
+        completion_path,
+        project_root=project_root,
+        expected_purpose=args.purpose,
+    )
+    _emit({
+        "ok": True,
+        "purpose": verified.purpose,
+        "invocationId": verified.invocation_id,
+        "metadataPath": str(verified.prompt_metadata_path),
+        "resultPath": str(verified.result_path),
+        "completionPath": str(verified.completion_path),
+        "resultEnvelopeDigest": verified.result_envelope_digest,
+        "returnedBody": verified.returned_body,
+    }, args.json)
+
+
+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 = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) 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("-"))
+
+
+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) -> None:
+    if as_json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        print(payload.get("promptPath") or payload.get("metadataPath") or "ok")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())