okstra 0.186.7 → 0.188.0

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

@@ -0,0 +1,605 @@
+"""프롬프트를 실제로 찍어 낸다 — 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 Any, Mapping, 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 ...final_report_paths import final_report_data_path
+from ...report_inputs import report_narrative_path, uses_report_contract_v3
+from ...report_synthesis_packet import (
+    ReportSynthesisPacketError,
+    materialize_report_synthesis_packet,
+)
+from ...worker_prompt_body import report_writer_input_lines
+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))
+# 결과 파일과 별개의 워커 결과 포인터를 가진 audience. 이들만 `--audit-source` 로
+# 두 번째 경로를 받고, 프롬프트에 `**Worker Result Path:**` 앵커가 생긴다.
+# 나머지 audience 의 결과는 하나뿐이고 감사 사이드카는 그 이름에서 파생된다.
+_POINTER_AUDIENCES = frozenset({"report-writer", "translator"})
+
+
+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,
+    )
+    audit_source_path = (
+        _authorized_path(
+            project_root,
+            args.audit_source,
+            authorized.get("resultRoots"),
+            "audit source",
+            must_exist=False,
+        )
+        if args.audit_source
+        else None
+    )
+    if args.audience not in _POINTER_AUDIENCES:
+        # 결과가 하나뿐인 audience 다. 두 번째 경로는 워커(`**Result Path:**` 에
+        # 쓴다)와 수집기(jobs-file 의 workerResultPath 를 기다린다)에게 서로 다른
+        # 파일을 말하는 것밖에 못 한다. 실측(2026-09-02, fontsninja-v3-site
+        # dev-10626-1 error-analysis r04): 리드가 reverify 에 `-worker-` 이름을
+        # `--audit-source` 로 따로 넘겨 검증 디스패치 9건 중 8건이 결과를 다
+        # 쓰고도 `required worker artifact was not produced` 로 끝났다.
+        if (
+            audit_source_path is not None
+            and _normalized(audit_source_path) != _normalized(result_path)
+        ):
+            raise AgentPromptCliError(
+                f"{args.audience} materialization forbids --audit-source: this "
+                "audience writes one result and its audit sidecar derives from "
+                "that result's name. Name --result with the canonical `-worker-` "
+                "token instead (reverify: "
+                "<worker-id>-worker-reverify-r<N>-<task-type>-<seq>.md) and put "
+                "the same path in the jobs file's workerResultPath"
+            )
+        audit_source_path = result_path
+    elif args.audience == "report-writer":
+        if audit_source_path is None:
+            # 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: "
+                    f"under report contract 3.0 --result is the narrative "
+                    f"({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"
+            )
+        _validate_report_writer_paths(
+            project_root,
+            manifest,
+            worker_id=args.worker_id,
+            result_path=result_path,
+            audit_source_path=audit_source_path,
+        )
+    elif audit_source_path is None:
+        audit_source_path = 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,
+    ))
+    body = instruction_path.read_text(encoding="utf-8")
+    if args.audience == "report-writer":
+        body = _with_inputs_section(
+            body,
+            _report_writer_input_lines(
+                project_root,
+                manifest,
+                active_context,
+                narrative_path=result_path,
+            ),
+        )
+    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=body,
+            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 _normalized(path: Path) -> Path:
+    return Path(os.path.normpath(path))
+
+
+def _validate_report_writer_paths(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    *,
+    worker_id: str,
+    result_path: Path,
+    audit_source_path: Path,
+) -> None:
+    """report-writer 의 두 경로를 run 이 이미 정한 값에 못 박는다.
+
+    `--result` 는 조립이 읽는 서술문 경로다: 계약 3.0 이면 매니페스트의
+    `reportNarrativePath`, 2.0 이면 `expectedReportRecordPath` 의 data.json.
+    다른 경로에 쓴 서술문은 `report-finalize` 가 읽지 않는다. `--audit-source`
+    는 명부(team-state `workers[].resultPath`)의 워커 결과다: `okstra team
+    await` 는 그 파일이 있어야 명부 행을 completed 로 적는다. 실측(2026-09-02,
+    fontsninja-v3-site dev-10626-1 r04): 리드가 재시도마다 `-a2`/`-a3` 접미를
+    붙인 경로를 넘겨 서술문 세 벌이 조립 밖에 쌓였고, 결국 손으로 `cp` 했다.
+    교정 디스패치는 프롬프트 경로와 invocation ID 만 새로 하고 이 두 경로는
+    그대로 쓴다.
+    """
+    if uses_report_contract_v3(manifest):
+        expected_result = report_narrative_path(project_root, manifest)
+        what = "the narrative report-finalize assembles from (run manifest reportNarrativePath)"
+    else:
+        expected_result = final_report_data_path(_project_manifest_path(
+            project_root,
+            manifest.get("expectedReportRecordPath"),
+            "expected report record",
+            must_exist=False,
+        ))
+        what = "the report data.json (run manifest expectedReportRecordPath)"
+    if _normalized(result_path) != _normalized(expected_result):
+        raise AgentPromptCliError(
+            f"report-writer --result must be {what}: expected {expected_result}, "
+            f"got {result_path}. A corrective dispatch reuses this path with a "
+            "fresh prompt path and invocation ID"
+        )
+    roster_result = _roster_result_path(project_root, manifest, worker_id)
+    if (
+        roster_result is not None
+        and _normalized(audit_source_path) != _normalized(roster_result)
+    ):
+        raise AgentPromptCliError(
+            "report-writer --audit-source must be the roster's worker result "
+            f"(team-state workers[].resultPath): expected {roster_result}, got "
+            f"{audit_source_path}. `okstra team await` records the roster row "
+            "completed only when that file exists"
+        )
+
+
+def _load_team_state(project_root: Path, manifest: Mapping[str, Any]) -> Mapping[str, Any]:
+    """매니페스트가 가리키는 team-state. 없으면 빈 매핑."""
+    team_state_value = manifest.get("teamStatePath")
+    if not isinstance(team_state_value, str) or not team_state_value:
+        return {}
+    team_state_path = Path(team_state_value)
+    if not team_state_path.is_absolute():
+        team_state_path = project_root / team_state_path
+    if not team_state_path.is_file():
+        return {}
+    return _read_json_object(team_state_path, "team state")
+
+
+def _report_writer_input_lines(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    *,
+    narrative_path: Path,
+) -> list[str]:
+    """report-writer 의 `## Inputs` 줄. 로스터 경로(`worker_prompt_body`)와 같은 규칙.
+
+    계약 3.0 이면 합성 묶음을 여기서 만들고 그 한 줄을 싣는다; 그 전 계약은
+    옛 목록이다. 실측(2026-09-02, fontsninja-v3-site dev-10626-1 r04): run
+    갈래의 프롬프트에는 이 절이 없어, 작성자가 "읽을 게 없다"며 서술문을
+    거부했고 리드가 경로 22개를 손으로 열거하고서야 통과했다. 두 갈래가 같은
+    입력 표면을 내야 하는 이유다.
+    """
+    team_state = _load_team_state(project_root, manifest)
+    if not uses_report_contract_v3(manifest):
+        return report_writer_input_lines(manifest, active_context, team_state)
+    try:
+        _, markdown_path = materialize_report_synthesis_packet(
+            project_root=project_root,
+            manifest=manifest,
+            active_context=active_context,
+            team_state=team_state,
+            narrative_path=narrative_path,
+        )
+    except ReportSynthesisPacketError as exc:
+        defects = "; ".join(
+            f"owner={issue.owner} source={issue.label} path={issue.path} "
+            f"reason={issue.reason}"
+            for issue in exc.issues
+        )
+        raise AgentPromptCliError(
+            f"report synthesis packet contract defects: {defects}"
+        ) from exc
+    return [f"- Report synthesis packet: `{_relative(project_root, markdown_path)}`"]
+
+
+def _with_inputs_section(body: str, input_lines: list[str]) -> str:
+    """런타임 소유 입력 줄을 본문의 `## Inputs` 첫머리에 넣는다.
+
+    리드가 이미 그 절을 썼으면 그 제목 바로 아래에 끼워 한 절로 두고, 없으면
+    머리의 `**…:**` 헤더 블록 뒤에 절을 새로 연다.
+    """
+    lines = body.splitlines()
+    for index, line in enumerate(lines):
+        if line.strip() == "## Inputs":
+            merged = lines[: index + 1] + input_lines + lines[index + 1 :]
+            return "\n".join(merged) + "\n"
+    insert_at = 0
+    while insert_at < len(lines) and (
+        not lines[insert_at].strip() or lines[insert_at].startswith("**")
+    ):
+        insert_at += 1
+    section = ["## Inputs", *input_lines, ""]
+    if insert_at and lines[insert_at - 1].strip():
+        section = ["", *section]
+    return "\n".join(lines[:insert_at] + section + lines[insert_at:]) + "\n"
+
+
+def _roster_result_path(
+    project_root: Path, manifest: Mapping[str, Any], worker_id: str,
+) -> Path | None:
+    """명부가 이 워커에 적어 둔 `resultPath`. 행이 없으면 None."""
+    workers = _load_team_state(project_root, manifest).get("workers")
+    if not isinstance(workers, list):
+        return None
+    for row in workers:
+        if not isinstance(row, Mapping) or row.get("workerId") != worker_id:
+            continue
+        value = row.get("resultPath")
+        if not isinstance(value, str) or not value.strip():
+            return None
+        path = Path(value.strip())
+        return path if path.is_absolute() else project_root / path
+    return None
+
+
+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)