okstra 0.173.0 → 0.175.1

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -18,6 +18,7 @@ from .agent_invocation import (
     AgentInvocationRequest,
     agent_model_assignment_from_payload,
     compose_agent_prompt,
+    invocation_execution_identity_from_manifest,
     prepare_agent_invocation,
     verify_agent_invocation,
 )
@@ -127,6 +128,11 @@ _MODEL_ASSIGNMENT_KEYS = {
     "hostRuntime",
     "hostModelValue",
 }
+_V2_EXECUTION_IDENTITY_KEYS = {
+    "participantRef",
+    "roleExecutionRef",
+    "dutyId",
+}
 _RUN_INVOCATION_PATH_KEYS = {
     "runManifestPath",
     "workerPromptsDirectoryPath",
@@ -259,6 +265,26 @@ def _validate_invocation_manifest_authority(
         return
     contract = manifest.get("agentContract")
     assignments = manifest.get("invocationAssignments")
+    schema = manifest.get("schemaVersion")
+    identity_version = manifest.get("executionIdentityVersion")
+    is_v1 = schema in (None, 1, "1", "1.0") and identity_version is None
+    is_v2 = schema == "2.0" and identity_version == 2
+    if not is_v1 and not is_v2:
+        raise InitialPromptMaterializationError(
+            "required_input_missing",
+            "invocation manifest mixes v1 and v2 execution identity",
+        )
+    allowed_assignment_shapes = {frozenset(_MODEL_ASSIGNMENT_KEYS)}
+    if is_v2 and isinstance(assignments, Mapping):
+        if any(
+            isinstance(item, Mapping)
+            and bool(set(item) & _V2_EXECUTION_IDENTITY_KEYS)
+            for item in assignments.values()
+        ):
+            raise InitialPromptMaterializationError(
+                "required_input_missing",
+                "invocation assignment duplicates v2 execution identity",
+            )
     complete = (
         isinstance(contract, Mapping)
         and set(contract) == _AGENT_CONTRACT_KEYS
@@ -267,7 +293,7 @@ def _validate_invocation_manifest_authority(
         and bool(assignments)
         and all(
             isinstance(item, Mapping)
-            and set(item) == _MODEL_ASSIGNMENT_KEYS
+            and frozenset(item) in allowed_assignment_shapes
             for item in assignments.values()
         )
         and all(
@@ -453,6 +479,12 @@ def _agent_invocation_request(
     payload = assignments.get(assignment_ref) if isinstance(assignments, Mapping) else None
     try:
         assignment = agent_model_assignment_from_payload(payload)
+        identity = invocation_execution_identity_from_manifest(
+            context.manifest,
+            assignment=assignment,
+            assignment_ref=assignment_ref,
+            duty_id=item.plan.duty_audience,
+        )
     except AgentInvocationError as exc:
         raise InitialPromptMaterializationError(
             "required_input_missing", str(exc)
@@ -475,9 +507,10 @@ def _agent_invocation_request(
             "project", _required_string(context.manifest, "teamStatePath")
         ),
     )
+    invocation_id = _worker_invocation_id(context.manifest, item.worker.worker_id)
     return AgentInvocationRequest(
-        invocation_id=_worker_invocation_id(context.manifest, item.worker.worker_id),
-        worker_id=item.worker.worker_id,
+        invocation_id=invocation_id,
+        worker_id=item.worker.worker_id if identity is None else None,
         audience=item.plan.duty_audience,
         assignment_ref=assignment_ref,
         purpose=None,
@@ -493,6 +526,13 @@ def _agent_invocation_request(
         prompt_path=item.final_path,
         metadata_path=item.final_path.with_name(item.final_path.name + ".meta.json"),
         dispatch_kind="initial",
+        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=invocation_id if identity is not None else None,
+        attempt=1,
     )
 
 

package/runtime/python/okstra_ctl/legacy_model_selection.py

@@ -0,0 +1,490 @@
+"""Normalize canonical role selections and legacy provider CLI inputs."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Mapping, Sequence
+
+from .domain.host import (
+    CurrentSessionModelAttestation,
+    HostSessionContext,
+)
+from .domain.role import RoleCatalogError, normalize_role
+from .role_requirements import RoleProfile, RoleRequirement
+
+
+class ModelSelectionInputError(ValueError):
+    """Raised before prepare side effects when role selection is invalid."""
+
+
+@dataclass(frozen=True)
+class CanonicalModelSelection:
+    role_counts: Mapping[str, int]
+    role_models: Mapping[str, tuple[str, ...]]
+    provider_constraints: Mapping[str, tuple[str, ...]]
+    legacy_model_values: Mapping[str, Mapping[str, str]]
+    legacy_sources: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        model_values = {
+            role: MappingProxyType(dict(values))
+            for role, values in self.legacy_model_values.items()
+        }
+        object.__setattr__(
+            self,
+            "role_counts",
+            MappingProxyType(dict(self.role_counts)),
+        )
+        object.__setattr__(
+            self,
+            "role_models",
+            MappingProxyType(dict(self.role_models)),
+        )
+        object.__setattr__(
+            self,
+            "provider_constraints",
+            MappingProxyType(dict(self.provider_constraints)),
+        )
+        object.__setattr__(
+            self,
+            "legacy_model_values",
+            MappingProxyType(model_values),
+        )
+
+
+def normalize_model_selection_inputs(
+    *,
+    profile: RoleProfile,
+    role_counts_raw: Sequence[str],
+    role_models_raw: Sequence[str],
+    workers: str,
+    worker_model: str,
+    critic: str,
+    executor: str,
+    lead_provider: str,
+    lead_model: str,
+    report_writer_provider: str,
+    report_writer_model: str,
+    provider_models: Mapping[str, str],
+) -> CanonicalModelSelection:
+    """Return one ordered role-selection view for canonical and legacy inputs."""
+    counts = _parse_role_counts(role_counts_raw)
+    models = _parse_role_models(role_models_raw)
+    legacy = _legacy_selection(
+        profile=profile,
+        workers=workers,
+        worker_model=worker_model,
+        critic=critic,
+        executor=executor,
+        lead_provider=lead_provider,
+        lead_model=lead_model,
+        report_writer_provider=report_writer_provider,
+        report_writer_model=report_writer_model,
+        provider_models=provider_models,
+    )
+    _reject_source_conflicts(counts, models, legacy)
+    merged_counts = {**counts, **legacy.role_counts}
+    merged_models = {**models, **legacy.role_models}
+    _validate_selection(profile, merged_counts, merged_models, counts)
+    return CanonicalModelSelection(
+        merged_counts,
+        merged_models,
+        legacy.provider_constraints,
+        legacy.legacy_model_values,
+        legacy.legacy_sources,
+    )
+
+
+def _parse_role_counts(raw_values: Sequence[str]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for raw in raw_values:
+        role, value = _split_role_value(raw, "--role-count")
+        if role in counts:
+            raise ModelSelectionInputError(f"duplicate --role-count role: {role}")
+        try:
+            count = int(value)
+        except ValueError as exc:
+            raise ModelSelectionInputError(
+                f"--role-count requires role=<non-negative integer>: {raw!r}"
+            ) from exc
+        if count < 0 or str(count) != value:
+            raise ModelSelectionInputError(
+                f"--role-count requires role=<non-negative integer>: {raw!r}"
+            )
+        counts[role] = count
+    return counts
+
+
+def _parse_role_models(raw_values: Sequence[str]) -> dict[str, tuple[str, ...]]:
+    grouped: dict[str, list[str]] = {}
+    for raw in raw_values:
+        role, model_ref = _split_role_value(raw, "--role-model")
+        grouped.setdefault(role, []).append(model_ref)
+    return {role: tuple(values) for role, values in grouped.items()}
+
+
+def _split_role_value(raw: str, option: str) -> tuple[str, str]:
+    role_raw, separator, value = raw.partition("=")
+    role_raw = role_raw.strip()
+    value = value.strip()
+    if not separator or not role_raw or not value:
+        raise ModelSelectionInputError(f"{option} requires role=value: {raw!r}")
+    try:
+        role = normalize_role(role_raw)
+    except RoleCatalogError as exc:
+        raise ModelSelectionInputError(str(exc)) from exc
+    return role, value
+
+
+def _legacy_selection(
+    *,
+    profile: RoleProfile,
+    workers: str,
+    worker_model: str,
+    critic: str,
+    executor: str,
+    lead_provider: str,
+    lead_model: str,
+    report_writer_provider: str,
+    report_writer_model: str,
+    provider_models: Mapping[str, str],
+) -> CanonicalModelSelection:
+    counts: dict[str, int] = {}
+    constraints: dict[str, tuple[str, ...]] = {}
+    values: dict[str, dict[str, str]] = {}
+    sources: list[str] = []
+    needs_initial = bool(
+        workers.strip()
+        or worker_model.strip()
+        or any(model.strip() for model in provider_models.values())
+    )
+    initial = (
+        _initial_cross_verification_requirement(profile)
+        if needs_initial
+        else None
+    )
+    if workers.strip() and initial is not None:
+        providers = _legacy_worker_providers(workers)
+        _validate_legacy_workers(initial, providers)
+        counts[initial.role] = len(providers)
+        constraints[initial.role] = providers
+        report_writer = _requirement(profile, "report-writer")
+        if report_writer is not None:
+            counts["report-writer"] = report_writer.count
+        sources.append("--workers")
+    worker_values = _parse_worker_models(worker_model, provider_models)
+    if worker_values and initial is not None:
+        values[initial.role] = worker_values
+        sources.append("worker-model")
+    _add_provider_selection(
+        constraints, values, sources, "leader", lead_provider, lead_model, "lead"
+    )
+    _add_provider_selection(
+        constraints,
+        values,
+        sources,
+        "report-writer",
+        report_writer_provider,
+        report_writer_model,
+        "report-writer",
+    )
+    _add_simple_legacy_roles(counts, constraints, sources, critic, executor)
+    return CanonicalModelSelection(counts, {}, constraints, values, tuple(sources))
+
+
+def _initial_cross_verification_requirement(profile: RoleProfile) -> RoleRequirement:
+    for requirement in profile.roles:
+        if not requirement.dynamic and requirement.role in {
+            "analyser", "designer", "planner", "verifier"
+        }:
+            return requirement
+    raise ModelSelectionInputError(
+        "profile has no initial cross-verification role for legacy --workers"
+    )
+
+
+def _legacy_worker_providers(workers: str) -> tuple[str, ...]:
+    tokens = tuple(
+        token.strip().lower() for token in workers.split(",") if token.strip()
+    )
+    return tuple(token for token in tokens if token != "report-writer")
+
+
+def _validate_legacy_workers(
+    requirement: RoleRequirement,
+    providers: tuple[str, ...],
+) -> None:
+    maximum = requirement.count + requirement.optional_count
+    diversity = requirement.min_distinct_providers
+    if diversity is not None and len(set(providers)) < diversity:
+        raise ModelSelectionInputError(
+            "legacy --workers roster violates "
+            f"minDistinctProviders={diversity}; select at least {diversity} "
+            "providers or migrate to --role-model"
+        )
+    if len(providers) < requirement.count or len(providers) > maximum:
+        raise ModelSelectionInputError(
+            f"legacy --workers selects {len(providers)} {requirement.role} instances; "
+            f"profile requires {requirement.count}..{maximum}"
+        )
+
+
+def _parse_worker_models(
+    worker_model: str,
+    provider_models: Mapping[str, str],
+) -> dict[str, str]:
+    values = {
+        provider.strip().lower(): model.strip()
+        for provider, model in provider_models.items()
+        if model.strip()
+    }
+    for item in worker_model.split(","):
+        if not item.strip():
+            continue
+        provider, separator, model = item.partition("=")
+        provider = provider.strip().lower()
+        model = model.strip()
+        if not separator or not provider or not model:
+            raise ModelSelectionInputError(
+                "--worker-model must use provider=model entries separated by commas"
+            )
+        if provider in values:
+            raise ModelSelectionInputError(
+                f"duplicate legacy worker model provider: {provider}"
+            )
+        values[provider] = model
+    return values
+
+
+def _add_provider_selection(
+    constraints: dict[str, tuple[str, ...]],
+    values: dict[str, dict[str, str]],
+    sources: list[str],
+    role: str,
+    provider_raw: str,
+    model_raw: str,
+    source: str,
+) -> None:
+    provider = provider_raw.strip().lower()
+    model = model_raw.strip()
+    if not provider and not model:
+        return
+    constraints[role] = (provider,)
+    if model:
+        values[role] = {provider: model}
+    sources.append(source)
+
+
+def _add_simple_legacy_roles(
+    counts: dict[str, int],
+    constraints: dict[str, tuple[str, ...]],
+    sources: list[str],
+    critic_raw: str,
+    executor_raw: str,
+) -> None:
+    critic = critic_raw.strip().lower()
+    if critic:
+        counts["critic"] = 0 if critic == "off" else 1
+        if critic != "off":
+            constraints["critic"] = (critic,)
+        sources.append("critic")
+    executor = executor_raw.strip().lower()
+    if executor:
+        constraints["implementer"] = (executor,)
+        sources.append("executor")
+
+
+def _reject_source_conflicts(
+    canonical_counts: Mapping[str, int],
+    canonical_models: Mapping[str, tuple[str, ...]],
+    legacy: CanonicalModelSelection,
+) -> None:
+    canonical_roles = set(canonical_counts) | set(canonical_models)
+    legacy_roles = (
+        set(legacy.role_counts)
+        | set(legacy.provider_constraints)
+        | set(legacy.legacy_model_values)
+    )
+    conflicts = sorted(canonical_roles & legacy_roles)
+    if conflicts:
+        raise ModelSelectionInputError(
+            "canonical and legacy model selections conflict for role "
+            f"{conflicts[0]!r}"
+        )
+
+
+def _validate_selection(
+    profile: RoleProfile,
+    counts: Mapping[str, int],
+    models: Mapping[str, tuple[str, ...]],
+    explicit_counts: Mapping[str, int],
+) -> None:
+    requirements = {row.role: row for row in profile.roles if not row.dynamic}
+    requirements["leader"] = RoleRequirement("leader", 1, "lead")
+    for role in sorted(set(counts) | set(models)):
+        requirement = requirements.get(role)
+        if requirement is None:
+            raise ModelSelectionInputError(
+                f"role {role!r} is not static in the profile"
+            )
+        _validate_role_count(
+            role,
+            counts,
+            requirement,
+            explicit=role in explicit_counts,
+        )
+        selected_count = counts.get(role, requirement.count)
+        model_count = len(models.get(role, ()))
+        if model_count > selected_count:
+            if role not in explicit_counts:
+                raise ModelSelectionInputError(
+                    f"set --role-count {role}={model_count} before assigning "
+                    f"{model_count} models"
+                )
+            raise ModelSelectionInputError(
+                f"role {role!r} has {model_count} models for {selected_count} instances"
+            )
+
+
+def _validate_role_count(
+    role: str,
+    counts: Mapping[str, int],
+    requirement: RoleRequirement,
+    *,
+    explicit: bool,
+) -> None:
+    if role not in counts:
+        return
+    count = counts[role]
+    maximum = requirement.count + requirement.optional_count
+    if explicit and requirement.optional_count == 0:
+        raise ModelSelectionInputError(
+            f"role {role!r} has a fixed quantity and cannot receive --role-count"
+        )
+    if requirement.optional_count == 0 and count != requirement.count:
+        raise ModelSelectionInputError(
+            f"role {role!r} has a fixed quantity of {requirement.count}"
+        )
+    if count < requirement.count or count > maximum:
+        raise ModelSelectionInputError(
+            f"role {role!r} count must be in {requirement.count}..{maximum}: {count}"
+        )
+
+
+def _requirement(profile: RoleProfile, role: str) -> RoleRequirement | None:
+    return next((row for row in profile.roles if row.role == role), None)
+
+
+def serialize_host_session_context(context: HostSessionContext) -> str:
+    """Serialize host-owned session facts as stable canonical JSON."""
+    current = context.current_model
+    payload = {
+        "availableFunctions": sorted(context.available_functions),
+        "currentModel": {
+            "level": current.level,
+            "normalizedModelRef": current.normalized_model_ref,
+            "observedModel": current.observed_model,
+            "providerId": current.provider_id,
+            "source": current.source,
+        },
+        "entryMode": context.entry_mode,
+        "hostId": context.host_id,
+        "interactionSurface": context.interaction_surface,
+    }
+    return json.dumps(
+        payload,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+
+
+def deserialize_host_session_context(payload: str) -> HostSessionContext:
+    """Deserialize only the shared context schema; never infer model identity."""
+    if not payload:
+        return HostSessionContext(
+            host_id="",
+            entry_mode="spawn-process",
+            available_functions=frozenset(),
+            interaction_surface="unavailable",
+            current_model=CurrentSessionModelAttestation.unknown(""),
+        )
+    try:
+        raw = json.loads(payload)
+    except json.JSONDecodeError as exc:
+        raise ModelSelectionInputError("invalid host session context JSON") from exc
+    if not isinstance(raw, dict):
+        raise ModelSelectionInputError("host session context must be a JSON object")
+    current = _deserialize_attestation(raw.get("currentModel"))
+    return HostSessionContext(
+        host_id=_required_string(raw, "hostId"),
+        entry_mode=_enum(raw, "entryMode", {"spawn-process", "current-session"}),
+        available_functions=frozenset(_string_list(raw, "availableFunctions")),
+        interaction_surface=_required_string(raw, "interactionSurface"),
+        current_model=current,
+    )
+
+
+def _deserialize_attestation(raw: object) -> CurrentSessionModelAttestation:
+    if raw is None:
+        return CurrentSessionModelAttestation.unknown("")
+    if not isinstance(raw, dict):
+        raise ModelSelectionInputError("currentModel must be a JSON object")
+    level = _enum(raw, "level", {"exact", "channel", "unknown"})
+    source = _enum(
+        raw,
+        "source",
+        {"host-session-metadata", "native-api", "cli-handoff", "unavailable"},
+    )
+    observed = _nullable_string(raw, "observedModel")
+    normalized = _nullable_string(raw, "normalizedModelRef")
+    if level == "unknown" and (observed is not None or normalized is not None):
+        raise ModelSelectionInputError("unknown currentModel must use null model fields")
+    if level != "unknown" and normalized is None:
+        raise ModelSelectionInputError(
+            "attested currentModel requires normalizedModelRef"
+        )
+    return CurrentSessionModelAttestation(
+        _required_string(raw, "providerId"),
+        observed,
+        normalized,
+        level,
+        source,
+    )
+
+
+def _required_string(raw: Mapping[str, object], key: str) -> str:
+    value = raw.get(key)
+    if not isinstance(value, str):
+        raise ModelSelectionInputError(f"host session context {key} must be a string")
+    return value
+
+
+def _nullable_string(raw: Mapping[str, object], key: str) -> str | None:
+    value = raw.get(key)
+    if value is not None and not isinstance(value, str):
+        raise ModelSelectionInputError(
+            f"host session context {key} must be a string or null"
+        )
+    return value
+
+
+def _enum(raw: Mapping[str, object], key: str, allowed: set[str]) -> str:
+    value = _required_string(raw, key)
+    if value not in allowed:
+        raise ModelSelectionInputError(
+            f"host session context {key} must be one of: {', '.join(sorted(allowed))}"
+        )
+    return value
+
+
+def _string_list(raw: Mapping[str, object], key: str) -> tuple[str, ...]:
+    value = raw.get(key)
+    if not isinstance(value, list) or not all(
+        isinstance(item, str) for item in value
+    ):
+        raise ModelSelectionInputError(
+            f"host session context {key} must be an array of strings"
+        )
+    return tuple(value)