okstra 0.186.7 → 0.187.0

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

@@ -0,0 +1,408 @@
+"""프롬프트를 실제로 찍어 낸다 — run 에 매인 것과 독립 실행 두 갈래.
+
+`--run-manifest` 가 있으면 run 갈래다: 매니페스트에서 신원을 확인하고, 필요하면
+동적 검증자를 예약하고, 그 run 의 산출물 경로로 프롬프트를 쓴다. 없으면 독립
+갈래다: 인자로 받은 audience·duty 를 스냅샷해 감사 가능한 명세를 만든다. 두
+갈래가 같은 파일에 있는 이유는 `_materialize` 가 둘 중 하나를 고르는 유일한
+분기점이기 때문이다.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+import shutil
+import tempfile
+from typing import get_args
+
+from ..invocation import (
+    AgentInstruction,
+    AgentInstructionSource,
+    AgentAudience,
+    AgentInvocationRequest,
+    AgentModelAssignment,
+    PreparedAgentInvocation,
+    agent_model_assignment_from_payload,
+    digest_duty_catalog,
+    invocation_execution_identity_from_manifest,
+    prepare_agent_invocation,
+)
+from ...assignment_environment import load_assignment_context
+from ...assignment_resolver import AssignmentContext, resolve_dispatch_assignment
+from ...path_hints import hydrate_active_run_context
+from ...worker_prompt_headers import worker_prompt_headers
+from ...report_inputs import report_narrative_path, uses_report_contract_v3
+from ...dispatch_state import detect_terminal_backend
+from .dynamic_verifier import (
+    _dynamic_verifier_source,
+    _reserve_dynamic_verifier_request,
+)
+from .inputs import (
+    AgentPromptCliError,
+    _authorized_path,
+    _exact_path,
+    _is_relative_to,
+    _is_slug,
+    _mapping,
+    _project_input,
+    _project_manifest_path,
+    _project_root,
+    _read_json_object,
+    _relative,
+)
+from .run_identity import _validate_run_identity
+
+
+_AUDIENCES = frozenset(get_args(AgentAudience))
+
+
+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 _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,
+    )
+    if args.audience == "report-writer" and not args.audit_source:
+        # The report writer is the one audience whose result path is not its own
+        # worker result: it writes the report body, while the audit sidecar is
+        # derived from its `.md`. With both collapsed into one value the prompt
+        # loses its `**Worker Result Path:**` anchor and the writer puts the
+        # report where the audit file belongs — silently, because every header
+        # is still present and well-formed. The roster path derives both from
+        # the manifest; a dynamic call has to name them.
+        #
+        # Which artifact `--result` names depends on the report contract, and
+        # `dispatch_state.dispatch_result_path` is what decides it. Naming only
+        # the v2 answer here sent v3 runs to the data.json, so the narrative
+        # `report-finalize` assembles from was never written and the phase
+        # failed later, at a place that does not point back here.
+        if uses_report_contract_v3(manifest):
+            expected = report_narrative_path(project_root, manifest)
+            raise AgentPromptCliError(
+                "report-writer materialization requires --audit-source: under "
+                f"report contract 3.0 --result is the narrative ({expected}), "
+                "which `report-finalize` assembles the report data.json from, "
+                "and --audit-source the worker-result .md the audit sidecar is "
+                "derived from"
+            )
+        raise AgentPromptCliError(
+            "report-writer materialization requires --audit-source: under "
+            "report contract 2.0 --result is the report data.json, and "
+            "--audit-source the worker-result .md the audit sidecar is "
+            "derived from"
+        )
+    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: "
+            f"{args.assignment_ref}; this run declares "
+            + (", ".join(sorted(assignments)) or "no invocation assignment")
+        )
+    assignment_payload = assignments[args.assignment_ref]
+    assignment = agent_model_assignment_from_payload(assignment_payload)
+    dynamic_source = _dynamic_verifier_source(args, manifest)
+    identity = (
+        None
+        if dynamic_source is not None
+        else invocation_execution_identity_from_manifest(
+            manifest,
+            assignment=assignment,
+            assignment_ref=args.assignment_ref,
+            duty_id=args.audience,
+        )
+    )
+    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,
+    ))
+    request = AgentInvocationRequest(
+        invocation_id=args.invocation_id,
+        worker_id=args.worker_id if identity is None else None,
+        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,
+        participant_ref=identity.participant_ref if identity is not None else None,
+        role_execution_ref=(
+            identity.role_execution_ref if identity is not None else None
+        ),
+        duty_id=identity.duty_id if identity is not None else None,
+        invocation_ref=args.invocation_id if identity is not None else None,
+        attempt=1,
+        replace_undispatched=args.replace_undispatched,
+    )
+    if dynamic_source is not None:
+        request = _reserve_dynamic_verifier_request(
+            request,
+            args=args,
+            manifest=manifest,
+            manifest_path=manifest_path,
+            source_role_execution_ref=dynamic_source,
+        )
+    return prepare_agent_invocation(request)
+
+
+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,
+        "source-role-execution-ref": args.source_role_execution_ref,
+    }
+    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_context = load_assignment_context(
+        host_runtime=args.host_runtime,
+        terminal_backend=args.terminal_backend or detect_terminal_backend(),
+        execution_provider_ids=(args.provider,),
+        include_native_provider=False,
+    )
+    assignment = _standalone_assignment(
+        context=assignment_context,
+        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",
+        participant_ref=None,
+        role_execution_ref=None,
+        duty_id=None,
+        invocation_ref=None,
+        attempt=1,
+    ))
+
+
+def _standalone_assignment(
+    *,
+    context: AssignmentContext,
+    provider: str,
+    model_role: str,
+    model: str,
+) -> AgentModelAssignment:
+    host_runtime = context.environment.host_descriptor.id
+    resolved = resolve_dispatch_assignment(
+        context=context,
+        host_runtime=host_runtime,
+        role=model_role,
+        duty_id=model_role,
+        provider=provider,
+        model=model,
+    )
+    binding = resolved.binding
+    if binding is None:
+        raise AgentPromptCliError("standalone assignment requires a model binding")
+    return AgentModelAssignment(
+        provider=resolved.provider_id,
+        model=resolved.display_name,
+        model_execution_value=binding.resolved_execution_value,
+        runner=binding.runner,
+        host_runtime=host_runtime,
+        host_model_value=binding.host_model_value,
+    )
+
+
+def _snapshot_standalone_duties(destination: Path) -> None:
+    # 부모 개수를 세면 체크아웃(`<root>/scripts/okstra_ctl/agent/prompt_cli/`)
+    # 에서만 맞는다 — 설치본은 패키지가 `~/.okstra/lib/python/` 이라 prompts 가
+    # 한 단계 위(`~/.okstra/prompts/`)에 있다. duties 를 실제로 가진 루트를
+    # 탐색해서 해소한다.
+    from ...paths import find_asset_root
+
+    duties_relative = ("prompts", "duties")
+    root = find_asset_root(duties_relative, is_present=Path.is_dir)
+    if root is None:
+        raise AgentPromptCliError(
+            "duty contract source not found: no prompts/duties under "
+            "OKSTRA_HOME or this checkout"
+        )
+    source = root.joinpath(*duties_relative)
+    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)

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

@@ -0,0 +1,197 @@
+"""찍어 낸 명세와 워커가 낸 결과를 잇는다.
+
+materialize 가 만든 명세에 대해, 이 층은 그 뒤에 오는 것들을 다룬다 — 디스패치
+기록, 결과 링크, 거절, 완료 표시, 검증. 전부 이미 존재하는 명세를 전제하고,
+새 명세를 만들지 않는다.
+"""
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ..invocation import (
+    AgentModelAssignment,
+    agent_model_assignment_from_payload,
+    materialize_standalone_result,
+    publish_standalone_completion,
+    verify_standalone_completion,
+    verify_agent_invocation,
+)
+from ...dispatch_state import (
+    link_agent_dispatch_result,
+    record_verified_agent_dispatch,
+    abandon_agent_dispatch_attempt,
+    reject_agent_dispatch_result,
+)
+from .emit import _emit
+from .inputs import (
+    AgentPromptCliError,
+    _is_relative_to,
+    _mapping,
+    _project_input,
+    _project_root,
+    _read_json_object,
+)
+
+
+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 _reject_result(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    row = reject_agent_dispatch_result(
+        project_root=project_root,
+        run_manifest_path=_project_input(
+            project_root, args.run_manifest, "run manifest"
+        ),
+        dispatch_id=args.dispatch_id,
+        superseded_by=args.superseded_by,
+        reason=args.reason,
+    )
+    _emit(row, args.json)
+
+
+def _abandon_attempt(args: argparse.Namespace) -> None:
+    project_root = _project_root(args.project_root)
+    row = abandon_agent_dispatch_attempt(
+        project_root=project_root,
+        run_manifest_path=_project_input(
+            project_root, args.run_manifest, "run manifest"
+        ),
+        invocation_ref=args.invocation_ref,
+        reason=args.reason,
+    )
+    _emit(row, 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 _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)