okstra 0.173.0 → 0.175.1

package/runtime/bin/okstra-error-log.py

@@ -72,6 +72,7 @@ def _build_parser():
     grp.add_argument("--stderr-excerpt-file", default=None)
     obs.add_argument("--context-json", default=None,
                      help="JSON object string for context")
+    _add_identity_flags(obs)
 
     dump = sub.add_parser("append-from-worker",
                           help="Dump worker sidecar errors[] into errors.jsonl")
@@ -81,9 +82,33 @@ def _build_parser():
     dump.add_argument("--agent", required=True, choices=sorted(ALLOWED_AGENTS))
     dump.add_argument("--agent-role", required=True, choices=sorted(ALLOWED_AGENT_ROLES))
     dump.add_argument("--model", required=True)
+    _add_identity_flags(dump)
     return p
 
 
+def _add_identity_flags(parser):
+    parser.add_argument("--participant-ref", default="")
+    parser.add_argument("--role-execution-ref", default="")
+    parser.add_argument("--invocation-ref", default="")
+    parser.add_argument("--attempt", type=int, default=None)
+    parser.add_argument("--execution-label", default="")
+
+
+def _identity_from_args(args):
+    payload = {}
+    if args.participant_ref:
+        payload["participantRef"] = args.participant_ref
+    if args.role_execution_ref:
+        payload["roleExecutionRef"] = args.role_execution_ref
+    if args.invocation_ref:
+        payload["invocationRef"] = args.invocation_ref
+    if args.attempt is not None:
+        payload["attempt"] = args.attempt
+    if args.execution_label:
+        payload["executionLabel"] = args.execution_label
+    return payload or None
+
+
 def _read_stderr(args):
     if args.stderr_excerpt_file:
         return Path(args.stderr_excerpt_file).read_text()
@@ -114,6 +139,7 @@ def main(argv=None):
             message=args.message,
             stderr_excerpt=_read_stderr(args),
             context=_read_context(args),
+            identity=_identity_from_args(args),
         )
         return 0
     if args.cmd == "append-from-worker":
@@ -124,6 +150,7 @@ def main(argv=None):
             agent=args.agent,
             agent_role=args.agent_role,
             model=args.model,
+            identity=_identity_from_args(args),
         )
         print(n)
         return 0

package/runtime/bin/okstra-provider-exec.py

@@ -8,12 +8,13 @@ write scope in the order the CLIs are told it, and the role's idle budget.
 """
 from __future__ import annotations
 
+import json
 import os
 import shutil
 import sys
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Mapping
+from typing import Any, Callable, Mapping
 
 _HERE = Path(__file__).resolve().parent
 # ``okstra_ctl`` sits beside this file in the repo (``scripts/``) but under
@@ -26,7 +27,13 @@ sys.path.insert(0, str(_HERE))
 if _HOME_LIB.is_dir() and str(_HOME_LIB) not in sys.path:
     sys.path.append(str(_HOME_LIB))
 
-from okstra_ctl.domain.provider import ProviderSpec, UnknownProviderError  # noqa: E402
+from okstra_ctl.domain.provider import (  # noqa: E402
+    ProviderSpec,
+    ServedModelAttestation,
+    ServedModelNormalizer,
+    UnknownProviderError,
+)
+from okstra_ctl.domain.role import normalize_role, role_for_duty  # noqa: E402
 from okstra_ctl.domain.worker_exec import (  # noqa: E402
     ExecutionStrategy,
     WorkerExecRequest,
@@ -36,14 +43,32 @@ from okstra_ctl.registry.provider_registry import (  # noqa: E402
 )
 from okstra_ctl.worker_request import build_request, idle_timeout  # noqa: E402
 from okstra_ctl.worker_runner import LIVE, QUIET, run_worker  # noqa: E402
+from okstra_ctl.dispatch_core import verify_served_model  # noqa: E402
+from okstra_ctl.dispatch_state import DispatchError  # noqa: E402
+from okstra_ctl.execution_manifest import read_execution_manifest  # noqa: E402
+from okstra_ctl.write_policy import (  # noqa: E402
+    WriteEnforcement,
+    WritePolicy,
+    write_enforcement_from_payload,
+    write_policy_from_payload,
+)
+from okstra_ctl.model_pool import ModelPool  # noqa: E402
+from okstra_ctl.agent_invocation import (  # noqa: E402
+    AgentInvocationError,
+    agent_model_assignment_from_payload,
+    invocation_metadata_identity,
+)
 
 _USAGE = (
     "usage: okstra-provider-exec.py <provider> <project-root> "
     "<model-execution-value> <prompt-path> [worktree-path] [role] "
-    "[idle-timeout-seconds] [--presentation live|quiet]"
+    "[idle-timeout-seconds] [--presentation live|quiet] [--session-id <uuid>] "
+    "[--invocation-metadata path]"
 )
 
 _PRESENTATION_FLAG = "--presentation"
+_SESSION_ID_FLAG = "--session-id"
+_INVOCATION_METADATA_FLAG = "--invocation-metadata"
 _PRESENTATIONS = (LIVE, QUIET)
 
 
@@ -61,11 +86,25 @@ class Invocation:
     log_path: Path
     status_path: Path
     status_extra: Mapping[str, Any]
+    served_model_normalizer: ServedModelNormalizer | None
+    served_model_verifier: Callable[[ServedModelAttestation], str] | None
+
+
+@dataclass(frozen=True)
+class _V2InvocationContext:
+    status_extra: Mapping[str, Any]
+    verify_attestation: Callable[[ServedModelAttestation], str]
+    write_policy: WritePolicy
+    write_enforcement: WriteEnforcement
 
 
 def parse_invocation(argv: list[str]) -> Invocation:
     """Resolve the wrapper's positional contract into one runnable dispatch."""
     positional, presentation = _take_presentation(argv)
+    # Empty unless the dispatcher issued one. Without it the CLI picks its own
+    # id and nothing downstream can map that session back to this worker.
+    positional, session_id = _take_flag(positional, _SESSION_ID_FLAG, "")
+    positional, metadata_raw = _take_flag(positional, _INVOCATION_METADATA_FLAG, "")
     if not 4 <= len(positional) <= 7:
         raise PreflightError(64, _USAGE)
     provider_id, project_root_raw, model, prompt_raw = positional[:4]
@@ -73,7 +112,6 @@ def parse_invocation(argv: list[str]) -> Invocation:
     role = positional[5] if len(positional) >= 6 and positional[5] else "worker"
     timeout_raw = positional[6] if len(positional) >= 7 and positional[6] else ""
 
-    spec = _provider_spec(provider_id)
     project_root = _existing_dir(project_root_raw, 65, "project-root")
     if not model:
         raise PreflightError(66, "model-execution-value is empty")
@@ -82,6 +120,32 @@ def parse_invocation(argv: list[str]) -> Invocation:
     worktree = (
         _existing_dir(worktree_raw, 68, "worktree-path") if worktree_raw else None
     )
+    spec = _provider_spec(provider_id)
+    status_extra: dict[str, Any] = {"wrapper": spec.wrapper, "role": role}
+    served_model_normalizer: ServedModelNormalizer | None = None
+    served_model_verifier: Callable[[ServedModelAttestation], str] | None = None
+    write_policy: WritePolicy | None = None
+    write_enforcement: WriteEnforcement | None = None
+    if metadata_raw:
+        context = _v2_status_extra(
+            metadata_path=_existing_file(
+                metadata_raw, 64, "invocation-metadata"
+            ),
+            project_root=project_root,
+            prompt_path=prompt_path,
+            provider_id=provider_id,
+            model=model,
+            role=role,
+        )
+        status_extra.update(context.status_extra)
+        served_model_normalizer = spec.served_model_normalizer
+        served_model_verifier = context.verify_attestation
+        write_policy = context.write_policy
+        write_enforcement = context.write_enforcement
+        if not spec.supports_role(role):
+            raise PreflightError(
+                64, f"provider {provider_id!r} does not support role {role!r}"
+            )
 
     request = build_request(
         prompt_text=prompt_path.read_text(encoding="utf-8"),
@@ -90,6 +154,9 @@ def parse_invocation(argv: list[str]) -> Invocation:
         worktree_path=worktree,
         role=role,
         idle_timeout_seconds=idle_timeout_seconds,
+        session_id=session_id,
+        write_policy=write_policy,
+        write_enforcement=write_enforcement,
     )
     strategy = spec.exec_strategy
     _check_command(strategy, request)
@@ -99,31 +166,45 @@ def parse_invocation(argv: list[str]) -> Invocation:
         presentation=presentation,
         log_path=_log_path(prompt_path),
         status_path=Path(f"{prompt_path}.status.json"),
-        status_extra={"wrapper": spec.wrapper, "role": role},
+        status_extra=status_extra,
+        served_model_normalizer=served_model_normalizer,
+        served_model_verifier=served_model_verifier,
     )
 
 
-def _take_presentation(argv: list[str]) -> tuple[list[str], str]:
-    """Split the one flag out of an otherwise positional argv.
+def _take_flag(argv: list[str], flag: str, default: str) -> tuple[list[str], str]:
+    """Split one value-carrying flag out of an otherwise positional argv.
 
-    Defaults to ``quiet``. ``live`` is only ever right where a screen was
-    declared, and the only callers that can declare one are the pane backends —
-    which pass the flag explicitly. Defaulting the other way assumed a screen
-    that a subagent dispatch does not have, and sent every worker's progress
-    into its caller's context window instead.
+    The wrapper's contract is positional, so every flag it grows has to be
+    lifted out before the positions are counted. Written once because the flags
+    differ only in the value they carry: a second copy of this loop is where
+    their refusals of a flag with no value would drift apart.
     """
     positional: list[str] = []
-    presentation = QUIET
+    value = default
     index = 0
     while index < len(argv):
-        if argv[index] != _PRESENTATION_FLAG:
+        if argv[index] != flag:
             positional.append(argv[index])
             index += 1
             continue
         if index + 1 >= len(argv):
-            raise PreflightError(64, f"{_PRESENTATION_FLAG} needs a value: {_USAGE}")
-        presentation = argv[index + 1]
+            raise PreflightError(64, f"{flag} needs a value: {_USAGE}")
+        value = argv[index + 1]
         index += 2
+    return positional, value
+
+
+def _take_presentation(argv: list[str]) -> tuple[list[str], str]:
+    """``_take_flag`` plus the allowlist only this flag has.
+
+    Defaults to ``quiet``. ``live`` is only ever right where a screen was
+    declared, and the only callers that can declare one are the pane backends —
+    which pass the flag explicitly. Defaulting the other way assumed a screen
+    that a subagent dispatch does not have, and sent every worker's progress
+    into its caller's context window instead.
+    """
+    positional, presentation = _take_flag(argv, _PRESENTATION_FLAG, QUIET)
     if presentation not in _PRESENTATIONS:
         allowed = " | ".join(_PRESENTATIONS)
         raise PreflightError(
@@ -132,6 +213,152 @@ def _take_presentation(argv: list[str]) -> tuple[list[str], str]:
     return positional, presentation
 
 
+def _v2_status_extra(
+    *,
+    metadata_path: Path,
+    project_root: Path,
+    prompt_path: Path,
+    provider_id: str,
+    model: str,
+    role: str,
+) -> _V2InvocationContext:
+    try:
+        metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise PreflightError(64, "invocation metadata is invalid") from exc
+    if not isinstance(metadata, dict):
+        raise PreflightError(64, "invocation metadata must be an object")
+    try:
+        identity = invocation_metadata_identity(metadata)
+        assignment = agent_model_assignment_from_payload(
+            metadata.get("modelAssignment")
+        )
+    except AgentInvocationError as exc:
+        raise PreflightError(64, str(exc)) from exc
+    if identity is None:
+        raise PreflightError(64, "new worker dispatch requires v2 invocation metadata")
+    if (
+        assignment.provider != provider_id
+        or assignment.model_execution_value != model
+    ):
+        raise PreflightError(64, "invocation metadata model assignment does not match wrapper")
+    try:
+        expected_role = role_for_duty(identity.duty_id)
+        actual_role = normalize_role(role)
+    except ValueError as exc:
+        raise PreflightError(64, f"invocation metadata role is invalid: {exc}") from exc
+    if expected_role != actual_role:
+        raise PreflightError(64, "invocation metadata duty does not match role")
+    prompt = metadata.get("prompt")
+    recorded_path = prompt.get("path") if isinstance(prompt, Mapping) else None
+    if not isinstance(recorded_path, str):
+        raise PreflightError(64, "invocation metadata prompt path is invalid")
+    recorded = Path(recorded_path)
+    if not recorded.is_absolute():
+        recorded = project_root / recorded
+    if recorded.resolve(strict=False) != prompt_path.resolve(strict=True):
+        raise PreflightError(64, "invocation metadata prompt does not match wrapper")
+    role_execution, invocation, pool = _execution_authority(
+        metadata=metadata,
+        project_root=project_root,
+        role_execution_ref=identity.role_execution_ref,
+        invocation_ref=identity.invocation_ref,
+    )
+    binding = role_execution.binding
+    if (
+        role_execution.participant_ref != identity.participant_ref
+        or role_execution.role != expected_role
+        or role_execution.provider != assignment.provider
+        or binding is None
+        or binding.runner != assignment.runner
+        or binding.resolved_execution_value != assignment.model_execution_value
+    ):
+        raise PreflightError(
+            64, "invocation metadata role execution binding does not match run manifest"
+        )
+    if role_execution.execution_label != identity.execution_label:
+        raise PreflightError(
+            64, "invocation metadata execution label does not match run manifest"
+        )
+
+    def verify_attestation(attestation: ServedModelAttestation) -> str:
+        try:
+            verify_served_model(role_execution, attestation, pool=pool)
+        except DispatchError as exc:
+            return str(exc)
+        return ""
+
+    try:
+        write_policy = write_policy_from_payload(invocation.write_policy)
+        write_enforcement = write_enforcement_from_payload(
+            invocation.write_enforcement
+        )
+    except ValueError as exc:
+        raise PreflightError(64, f"invocation write contract is invalid: {exc}") from exc
+
+    return _V2InvocationContext({
+        "schemaVersion": "2.0",
+        "executionIdentityVersion": 2,
+        "participantRef": identity.participant_ref,
+        "roleExecutionRef": identity.role_execution_ref,
+        "executionLabel": identity.execution_label,
+        "dutyId": identity.duty_id,
+        "invocationRef": identity.invocation_ref,
+        "attempt": identity.attempt,
+        "servedModelAttestation": {
+            "observedModel": None,
+            "normalizedModelRef": None,
+            "level": "unknown",
+            "source": "unavailable",
+        },
+        "writePolicyDigest": invocation.write_policy_digest,
+        "writeEnforcement": write_enforcement.to_payload(),
+    }, verify_attestation, write_policy, write_enforcement)
+
+
+def _execution_authority(
+    *,
+    metadata: Mapping[str, Any],
+    project_root: Path,
+    role_execution_ref: str,
+    invocation_ref: str,
+):
+    source = metadata.get("contractSource")
+    manifest_raw = source.get("runManifestPath") if isinstance(source, Mapping) else None
+    if not isinstance(manifest_raw, str) or not manifest_raw:
+        raise PreflightError(64, "invocation metadata run manifest is invalid")
+    manifest_path = Path(manifest_raw)
+    if not manifest_path.is_absolute():
+        manifest_path = project_root / manifest_path
+    try:
+        manifest_path = manifest_path.resolve(strict=True)
+        manifest_path.relative_to(project_root.resolve(strict=True))
+        manifest = read_execution_manifest(manifest_path)
+    except (OSError, ValueError) as exc:
+        raise PreflightError(64, "invocation metadata run manifest is invalid") from exc
+    role_execution = next((
+        row for row in manifest.role_executions
+        if row.role_execution_ref == role_execution_ref
+    ), None)
+    if role_execution is None:
+        raise PreflightError(
+            64, "invocation metadata role execution does not match run manifest"
+        )
+    invocation = next((
+        row for row in manifest.invocations
+        if row.invocation_ref == invocation_ref
+    ), None)
+    if invocation is None or invocation.role_execution_ref != role_execution_ref:
+        raise PreflightError(
+            64, "invocation metadata invocation does not match run manifest"
+        )
+    return (
+        role_execution,
+        invocation,
+        ModelPool.from_registry(default_provider_registry()),
+    )
+
+
 def _provider_spec(provider_id: str) -> ProviderSpec:
     try:
         spec = default_provider_registry().resolve(provider_id)
@@ -197,6 +424,8 @@ def main(argv: list[str]) -> int:
             log_path=invocation.log_path,
             status_path=invocation.status_path,
             status_extra=invocation.status_extra,
+            served_model_normalizer=invocation.served_model_normalizer,
+            served_model_verifier=invocation.served_model_verifier,
         )
     except PreflightError as exc:
         print(f"okstra-provider-exec: {exc}", file=sys.stderr)