okstra 0.174.0 → 0.176.0

package/runtime/python/okstra_ctl/agent_prompt_cli.py

@@ -2,7 +2,9 @@
 from __future__ import annotations
 
 import argparse
+from dataclasses import replace
 from datetime import datetime, timezone
+import hashlib
 import json
 import os
 from pathlib import Path
@@ -21,24 +23,33 @@ from .agent_invocation import (
     AgentModelAssignment,
     PreparedAgentInvocation,
     agent_model_assignment_from_payload,
+    compose_agent_prompt,
+    compose_unbound_run_prompt,
     digest_duty_catalog,
+    invocation_execution_identity_from_manifest,
     materialize_standalone_result,
     prepare_agent_invocation,
     publish_standalone_completion,
     verify_standalone_completion,
     verify_agent_invocation,
+    v2_role_assignment_authority_errors,
 )
-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 .convergence_store import (
+    DYNAMIC_VERIFIER_SOURCE_ROLES,
+    reserve_dynamic_verifier,
+)
+from .assignment_environment import load_assignment_context
+from .assignment_resolver import AssignmentContext, resolve_dispatch_assignment
 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_artifact_paths import audit_sidecar_rel
+from .wrapper_status import status_path_for_prompt
 from .worker_prompt_policy import resolve_prompt_plan_for_manifest
 from .dispatch_state import (
+    BACKEND_CLI_WRAPPER,
+    BACKEND_CMUX_PANE,
     DispatchError,
+    detect_terminal_backend,
     link_agent_dispatch_result,
     record_verified_agent_dispatch,
     reject_agent_dispatch_result,
@@ -65,9 +76,14 @@ def _parser() -> argparse.ArgumentParser:
     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="")
@@ -314,7 +330,19 @@ def _materialize_run(
         raise AgentPromptCliError(
             f"assignment reference is missing from run manifest: {args.assignment_ref}"
         )
-    assignment = agent_model_assignment_from_payload(assignments[args.assignment_ref])
+    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"),
@@ -345,9 +373,9 @@ def _materialize_run(
         manifest=manifest,
         active_context=active_context,
     ))
-    return prepare_agent_invocation(AgentInvocationRequest(
+    request = AgentInvocationRequest(
         invocation_id=args.invocation_id,
-        worker_id=args.worker_id,
+        worker_id=args.worker_id if identity is None else None,
         audience=args.audience,
         assignment_ref=args.assignment_ref,
         purpose=None,
@@ -366,8 +394,186 @@ def _materialize_run(
         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,
+            artifact_paths=_dynamic_verifier_artifact_paths(
+                project_root,
+                prompt_path,
+                result_path,
+                audit_source_path,
+                audit_rel,
+                active_context,
+                args.worker_id,
+            ),
+        )
+    return prepare_agent_invocation(request)
+
+
+def _reserve_dynamic_verifier_request(
+    request: AgentInvocationRequest,
+    *,
+    args: argparse.Namespace,
+    manifest: Mapping[str, Any],
+    manifest_path: Path,
+    source_role_execution_ref: str,
+    artifact_paths: tuple[Path, ...],
+) -> 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,
+        artifact_paths=artifact_paths,
+    )
+    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_artifact_paths(
+    project_root: Path,
+    prompt_path: Path,
+    result_path: Path,
+    audit_source_path: Path,
+    audit_rel: str,
+    active_context: Mapping[str, Any],
+    worker_id: str,
+) -> tuple[Path, ...]:
+    paths = {
+        result_path,
+        audit_source_path,
+        project_root / audit_sidecar_rel(audit_rel),
+        status_path_for_prompt(prompt_path),
+        prompt_path.with_suffix(prompt_path.suffix + ".log"),
+    }
+    error_logs = active_context.get("errorLogs")
+    sidecars = error_logs.get("sidecarsByWorkerId") if isinstance(error_logs, Mapping) else None
+    value = sidecars.get(worker_id) if isinstance(sidecars, Mapping) else None
+    if isinstance(value, str) and value:
+        path = Path(value)
+        paths.add(path if path.is_absolute() else project_root / path)
+    return tuple(sorted(paths, key=str))
+
+
+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; 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
 
 
 def _validate_run_identity(
@@ -437,6 +643,7 @@ def _materialize_standalone(
         "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:
@@ -459,8 +666,14 @@ def _materialize_standalone(
     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(
+    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,
@@ -488,54 +701,40 @@ def _materialize_standalone(
         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(
-    *, host_runtime: str, provider: str, model_role: str, model: str,
+    *,
+    context: AssignmentContext,
+    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 = 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=metadata.display,
-        model_execution_value=execution,
-        runner=runner,
-    ))
+        model=model,
+    )
+    binding = resolved.binding
+    if binding is None:
+        raise AgentPromptCliError("standalone assignment requires a model binding")
     return AgentModelAssignment(
-        provider=provider,
-        model=metadata.display,
-        model_execution_value=execution,
-        runner=runner,
+        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=host_model,
+        host_model_value=binding.host_model_value,
     )
 
 

package/runtime/python/okstra_ctl/application/open_worker.py

@@ -0,0 +1,29 @@
+"""Choose an execution surface from an injected port chain."""
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+
+from ..domain.worker_runtime import (
+    EnvironmentBlocked,
+    RuntimeHandle,
+    SurfaceUnavailable,
+    WorkerSpawnRequest,
+)
+from ..ports.worker_runtime import WorkerRuntimePort
+
+
+def open_worker(
+    chain: Sequence[WorkerRuntimePort],
+    request_for: Callable[[str], WorkerSpawnRequest],
+) -> RuntimeHandle:
+    last_unavailable: SurfaceUnavailable | None = None
+    for port in chain:
+        try:
+            return port.spawn(request_for(port.surface))
+        except EnvironmentBlocked:
+            raise
+        except SurfaceUnavailable as exc:
+            last_unavailable = exc
+    if last_unavailable is None:
+        raise SurfaceUnavailable("runtime chain is empty")
+    raise last_unavailable

package/runtime/python/okstra_ctl/application/resolve_assignment.py

@@ -25,7 +25,7 @@ def resolve_assignment_runner(
     role: str,
     requested_runner: str = "",
 ) -> RunnerResolution:
-    if role not in provider.supported_roles:
+    if not provider.supports_role(role):
         raise ProviderUnavailable(
             f"provider {provider.provider!r} does not support role {role!r}"
         )
@@ -66,20 +66,33 @@ def resolve_lead_provider(
     provider_registry,
 ) -> LeadProviderAssignment:
     host = host_registry.resolve(host_id).descriptor
+    provider_id = resolve_lead_provider_id(
+        host=host,
+        requested_provider=requested_provider,
+    )
+    provider = provider_registry.resolve(provider_id)
+    return resolve_lead_provider_from_specs(
+        host=host,
+        requested_provider=requested_provider,
+        provider=provider,
+    )
+
+
+def resolve_lead_provider_from_specs(
+    *,
+    host: HostDescriptor,
+    requested_provider: str,
+    provider: ProviderSpec,
+) -> LeadProviderAssignment:
+    """Resolve a lead from already loaded host and provider facts."""
     requested = (requested_provider or "").strip().lower()
-    if not requested and not host.native_provider_id:
-        raise HostCapabilityMismatch(
-            f"host {host.id!r} has no native lead provider; select an explicit "
-            "provider with lead capability"
-        )
-    if host.native_provider_id and requested not in {"", host.native_provider_id}:
+    _validate_lead_provider_request(host, requested)
+    provider_id = requested or host.native_provider_id
+    if provider.provider != provider_id:
         raise HostCapabilityMismatch(
-            f"{host.agent_label.removesuffix(' CLI')} host requires provider "
-            f"{host.native_provider_id!r} for the in-session lead; provider "
-            f"{requested!r} must be selected as a worker instead"
+            f"provider fact {provider.provider!r} does not match requested "
+            f"lead provider {provider_id!r}"
         )
-    provider_id = requested or host.native_provider_id
-    provider = provider_registry.resolve(provider_id)
     resolution = resolve_assignment_runner(
         host=host,
         provider=provider,
@@ -91,3 +104,31 @@ def resolve_lead_provider(
         wrapper=resolution.wrapper,
         reason=resolution.reason,
     )
+
+
+def resolve_lead_provider_id(
+    *,
+    host: HostDescriptor,
+    requested_provider: str,
+) -> str:
+    """Validate lead-provider selection and return its canonical id."""
+    requested = (requested_provider or "").strip().lower()
+    _validate_lead_provider_request(host, requested)
+    return requested or host.native_provider_id
+
+
+def _validate_lead_provider_request(
+    host: HostDescriptor,
+    requested: str,
+) -> None:
+    if not requested and not host.native_provider_id:
+        raise HostCapabilityMismatch(
+            f"host {host.id!r} has no native lead provider; select an explicit "
+            "provider with lead capability"
+        )
+    if host.native_provider_id and requested not in {"", host.native_provider_id}:
+        raise HostCapabilityMismatch(
+            f"{host.agent_label.removesuffix(' CLI')} host requires provider "
+            f"{host.native_provider_id!r} for the in-session lead; provider "
+            f"{requested!r} must be selected as a worker instead"
+        )

package/runtime/python/okstra_ctl/assignment_environment.py

@@ -0,0 +1,102 @@
+"""Load ambient adapter facts once, outside deterministic assignment logic."""
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from .assignment_resolver import (
+    AssignmentContext,
+    AssignmentEnvironment,
+    TerminalBackend,
+)
+from .domain.provider import ExecutionNormalization, UnknownProviderError
+from .domain.role import ROLE_DEFINITIONS
+from .domain.worker_exec import WorkerWriteCapability
+from .model_pool import ModelPool
+from .registry.host_registry import default_host_registry
+from .registry.provider_registry import default_provider_registry
+
+
+def load_assignment_context(
+    *,
+    host_runtime: str,
+    terminal_backend: TerminalBackend,
+    execution_provider_ids: Iterable[str] | None = None,
+    include_native_provider: bool = True,
+) -> AssignmentContext:
+    """Snapshot provider, host, terminal, and execution inputs for one caller."""
+    provider_registry = default_provider_registry()
+    pool = ModelPool.from_registry(provider_registry)
+    adapter = default_host_registry(provider_registry).resolve(host_runtime)
+    worker_port = adapter.worker_dispatch()
+    capability_reader = getattr(worker_port, "worker_write_capability", None)
+    native_capability = (
+        capability_reader()
+        if callable(capability_reader)
+        else WorkerWriteCapability("none")
+    )
+    roles = tuple(row.id for row in ROLE_DEFINITIONS)
+    if execution_provider_ids is None:
+        provider_ids = provider_registry.ids()
+    else:
+        requested = [
+            provider.strip().lower() for provider in execution_provider_ids
+        ]
+        if include_native_provider:
+            requested.insert(0, adapter.descriptor.native_provider_id)
+        requested_ids = dict.fromkeys(requested)
+        selected_ids = []
+        for provider_id in requested_ids:
+            if not provider_id:
+                continue
+            try:
+                provider_registry.resolve(provider_id)
+            except UnknownProviderError:
+                continue
+            selected_ids.append(provider_id)
+        provider_ids = tuple(selected_ids)
+    execution_resolutions = {}
+    for provider_id in provider_ids:
+        provider = provider_registry.resolve(provider_id)
+        models_by_id = {
+            model.model_id: model for model in provider.models.values()
+        }
+        models = tuple(models_by_id.values())
+        normalizer = provider.execution_normalizer
+        if normalizer is None:
+            rows = {
+                (model.model_id, role): ExecutionNormalization(
+                    model.execution_value
+                )
+                for model in models
+                for role in roles
+            }
+        else:
+            try:
+                rows = normalizer.snapshot(models, roles)
+            except Exception as exc:
+                rows = {
+                    (model.model_id, role): ExecutionNormalization(None, str(exc))
+                    for model in models
+                    for role in roles
+                }
+        for model in models:
+            for role in roles:
+                key = (model.model_id, role)
+                outcome = rows.get(key)
+                if outcome is None:
+                    outcome = ExecutionNormalization(
+                        None,
+                        f"provider {provider_id!r} did not snapshot model "
+                        f"{model.model_id!r} for role {role!r}",
+                    )
+                execution_resolutions[(f"{provider_id}/{model.model_id}", role)] = (
+                    outcome
+                )
+    environment = AssignmentEnvironment(
+        host_descriptor=adapter.descriptor,
+        host_model_port=adapter.host_model(),
+        native_worker_write_capability=native_capability,
+        terminal_backend=terminal_backend,
+        execution_resolutions=execution_resolutions,
+    )
+    return AssignmentContext(pool=pool, environment=environment)