agentengine-sdk-python 0.8.5__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/harness/native/child_promotion.py

@@ -0,0 +1,66 @@
+"""Host control of a waiting owned child, using the original command ledger.
+
+OpenCode fe3f3a41 task.ts races foreground waiting with promotion of the same
+background owner. Promotion changes delivery only; it never launches a Run,
+replays a tool, changes authorization or settles the child's usage.
+"""
+
+from typing import Protocol
+
+from pydantic import Field
+
+from .state import Contract, RunSnapshot
+from .transitions import commit_transition
+
+
+class ChildPromotionInput(Contract):
+    child_run_id: str = Field(min_length=1, max_length=256, pattern=r"\S")
+
+
+class ChildPromotionPort(Protocol):
+    def child_tasks(self, parent: RunSnapshot) -> tuple[dict, ...]: ...
+
+    def can_promote(self, parent: RunSnapshot, child_run_id: str) -> bool: ...
+
+    def release_foreground(self, parent: RunSnapshot, child_run_id: str) -> None: ...
+
+
+def consume_promotion(snapshot, command, *, enabled: bool, port: ChildPromotionPort | None, commit):
+    """Persist the delivery fact before waking the same child owner's waiter."""
+    reason, child_id = "child_promotion_policy_unavailable", None
+    if enabled:
+        try:
+            child_id = ChildPromotionInput.model_validate(command.payload).child_run_id
+        except ValueError:
+            reason = "invalid_child_promotion"
+        else:
+            reason = (
+                "applied"
+                if port.can_promote(snapshot, child_id)
+                else "foreground_child_unavailable"
+            )
+    updated = commit(
+        snapshot,
+        commit_transition(
+            snapshot,
+            snapshot,
+            "command.consumed",
+            {"command_id": command.command_id, "kind": command.kind, "reason": reason},
+            command_id=command.command_id,
+            extra_events=(
+                (
+                    "child.promoted",
+                    {
+                        "command_id": command.command_id,
+                        "child_run_id": child_id,
+                        "operation_key": snapshot.pending_intent,
+                    },
+                ),
+            )
+            if reason == "applied"
+            else (),
+        ),
+    )
+    if reason == "applied":
+        port.release_foreground(updated, child_id)
+    return updated

ksadk/harness/native/command_runtime.py

@@ -0,0 +1,99 @@
+"""Resolve a control command against any pending effect before one atomic commit."""
+
+from __future__ import annotations
+
+from ksadk.harness.stores.native_contract import RunStore
+
+from .machine import reduce_command
+from .model_runtime import unavailable_uncertain_usage
+from .ports import RunConfiguration
+from .state import CommitBatch, EffectReceipt, RunCommand, RunPhase, RunScope, RunSnapshot
+from .tool_interruption import record_tool_interruption
+from .transitions import commit_transition, finish, insert_event_before_terminal
+
+
+def resolve_command_batch(
+    store: RunStore,
+    scope: RunScope,
+    snapshot: RunSnapshot,
+    command: RunCommand,
+    *,
+    bound_tool_names: frozenset[str] | None = None,
+    guidance_enabled: bool = False,
+    replay_configuration: RunConfiguration | None = None,
+) -> CommitBatch:
+    batch = reduce_command(snapshot, command, bound_tool_names=bound_tool_names,
+                           guidance_enabled=guidance_enabled,
+                           replay_configuration=replay_configuration)
+    key = snapshot.pending_intent
+    if batch.snapshot.pending_intent is not None:
+        return batch
+    if not key:
+        return record_tool_interruption(snapshot, batch)
+    intent = store.get_intent(scope, snapshot.run_id, key)
+    receipt = store.get_receipt(scope, snapshot.run_id, key)
+    if receipt is not None or intent is None:
+        return record_tool_interruption(snapshot, batch, intent, receipt)
+    if intent.status == "running" and intent.kind != "workspace" and command.kind == "steer":
+        batch = commit_transition(
+            snapshot,
+            finish(snapshot, "unverified", "effect_outcome_unknown"),
+            "command.consumed",
+            {
+                "command_id": command.command_id,
+                "kind": "steer",
+                "reason": "effect_outcome_unknown",
+            },
+            command_id=command.command_id,
+        )
+    receipt = EffectReceipt(
+        operation_key=key,
+        status=(
+            "failed" if intent.status == "prepared" or intent.kind == "workspace" else "uncertain"
+        ),
+        result={
+            "reason": (
+                "not_dispatched"
+                if intent.status == "prepared"
+                else (
+                    "read_only_observation_discarded"
+                    if intent.kind == "workspace"
+                    else "effect_outcome_unknown"
+                )
+            )
+        },
+    )
+    if receipt.status == "uncertain" and intent.kind == "model":
+        batch = insert_event_before_terminal(snapshot, batch, unavailable_uncertain_usage(key))
+    updated = batch.snapshot
+    if intent.status == "running" and intent.kind in {"model", "tool"}:
+        counter = "model_calls" if intent.kind == "model" else "tool_calls"
+        updated = updated.model_copy(update={
+            counter: getattr(snapshot, counter) + intent.loop_attempts,
+        })
+    return record_tool_interruption(
+        snapshot, batch.model_copy(update={"receipts": (receipt,), "snapshot": updated}),
+        intent, receipt,
+    )
+
+
+def stage_child_cancellation(store, scope, snapshot, command, *, bound_tool_names):
+    """Close the parent effect, retaining its command until children settle.
+
+    Reuse ordinary command accounting and protocol closure. The intermediate
+    commit is nonterminal, and neither consumes nor re-enqueues cancellation.
+    """
+    batch = resolve_command_batch(
+        store, scope, snapshot, command, bound_tool_names=bound_tool_names,
+    )
+    updated = batch.snapshot.model_copy(update={
+        "phase": RunPhase.FINALIZING, "outcome": "unverified",
+        "reason": "parent_child_cleanup_pending",
+    })
+    accounting = tuple((event.kind, event.payload) for event in batch.events
+                       if event.kind.startswith("usage.") or event.kind == "tools.interrupted")
+    return commit_transition(
+        snapshot, updated, "child.parent_cancel_pending",
+        {"command_id": command.command_id, "kind": command.kind},
+        receipts=batch.receipts, extra_events=accounting,
+    )

ksadk/harness/native/completion.py

@@ -0,0 +1,302 @@
+"""Pure completion reduction from a pinned contract and trusted evidence metadata.
+
+The host must execute verifiers and resolve evidence before supplying a report.
+Model text, including a final answer, has no authority to produce ``verified``.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue, model_validator
+
+from .output_contract import validate_submission_schema
+
+NonBlank = Annotated[str, Field(min_length=1, pattern=r"\S")]
+VerificationMethod = Literal["deterministic", "human", "model_assisted"]
+VerificationStatus = Literal["passed", "failed", "not_run", "blocked"]
+CompletionOutcome = Literal["verified", "unverified", "partial", "blocked"]
+
+
+class _ContractModel(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class VerificationRepairTarget(_ContractModel):
+    """Host diagnosis of the delivery to repair, never a tool permission grant."""
+
+    kind: Literal["workspace_file", "final_output"]
+    path: Annotated[str, Field(min_length=1, max_length=2048)] | None = None
+
+    @model_validator(mode="after")
+    def relative_workspace_path(self) -> VerificationRepairTarget:
+        if self.kind == "final_output":
+            if self.path is not None:
+                raise ValueError("final output target has no workspace path")
+        elif (
+            self.path is None
+            or not self.path.strip()
+            or any(c in self.path for c in ("\\", ":"))
+            or any(ord(c) < 32 for c in self.path)
+            or any(part in {"", ".", ".."} for part in self.path.split("/"))
+        ):
+            raise ValueError("repair target requires a relative workspace path")
+        return self
+
+
+class AcceptanceItem(_ContractModel):
+    acceptance_id: NonBlank
+    required: bool = True
+    verifier_ref: NonBlank
+    verifier_version: NonBlank
+    verification_method: VerificationMethod
+    description: NonBlank
+
+
+class HostResolvedAnswer(_ContractModel):
+    """A host-owned candidate for one goal; never a verification verdict.
+
+    The host may resolve a deterministic information query from its locked
+    state. The Kernel still commits and verifies the candidate, and never
+    fabricates a model request or a usage receipt for it.
+    """
+
+    goal_digest: Annotated[str, Field(pattern=r"^[0-9a-f]{64}$")]
+    goal_revision: Annotated[int, Field(strict=True, ge=0)]
+    text: Annotated[str, Field(min_length=1, max_length=8192, pattern=r"\S")]
+    authority: NonBlank
+    evidence_ref: NonBlank
+
+
+class TaskContract(_ContractModel):
+    revision: NonBlank
+    items: tuple[AcceptanceItem, ...]
+    # Trusted host restriction for this goal. None inherits the Build's full
+    # bound surface; an empty tuple permits no executable task tools.
+    allowed_tool_names: tuple[NonBlank, ...] | None = None
+    # Per-goal delivery protocol, pinned with acceptance and tool authority.
+    # None keeps the activation's default delivery; no previous goal is inherited.
+    final_submission_schema: dict[str, JsonValue] | None = None
+    final_submission_payload_key: NonBlank | None = None
+    host_resolved_answer: HostResolvedAnswer | None = None
+
+    @model_validator(mode="after")
+    def unique_acceptance_ids(self) -> TaskContract:
+        _check_unique_ids(self.items)
+        if self.host_resolved_answer is not None and (
+            self.allowed_tool_names != () or self.final_submission_schema is not None
+        ):
+            raise ValueError("host resolved answer requires no task tools or structured submission")
+        if self.allowed_tool_names is not None and len(set(self.allowed_tool_names)) != len(
+            self.allowed_tool_names
+        ):
+            raise ValueError("duplicate allowed_tool_names")
+        if self.final_submission_schema is not None:
+            validate_submission_schema(
+                self.final_submission_schema, self.final_submission_payload_key
+            )
+        elif self.final_submission_payload_key is not None:
+            raise ValueError("final submission payload requires a schema")
+        return self
+
+
+class CompletionCandidate(_ContractModel):
+    candidate_id: NonBlank
+    final_text: str
+    subject_digest: NonBlank
+    # Older native snapshots remain readable, but cannot qualify as current evidence.
+    subject_context_digest: NonBlank | None = None
+    environment_digest: NonBlank
+
+
+class VerificationItemResult(_ContractModel):
+    acceptance_id: NonBlank
+    status: VerificationStatus
+    verifier_id: NonBlank
+    verifier_version: NonBlank
+    evidence_refs: tuple[NonBlank, ...]
+    verification_method: VerificationMethod
+    safe_summary: str = ""
+    # Host-signed item-level repair authority. None preserves older reports'
+    # report-wide decision; True can keep one actionable item in a mixed report.
+    repairable: bool | None = None
+    repair_target: VerificationRepairTarget | None = None
+
+
+class VerificationReport(_ContractModel):
+    candidate_id: NonBlank
+    contract_revision: NonBlank
+    subject_digest: NonBlank
+    subject_context_digest: NonBlank | None = None
+    environment_digest: NonBlank
+    items: tuple[VerificationItemResult, ...]
+    repairable: bool
+    failure_fingerprint: str
+    # Only the trusted verifier may declare that its evidence has no workspace
+    # dependency. Missing metadata remains conservative, including old receipts.
+    workspace_dependency: Literal["required", "none"] = Field(
+        default="required", exclude_if=lambda value: value == "required"
+    )
+
+    @model_validator(mode="after")
+    def unique_acceptance_ids(self) -> VerificationReport:
+        _check_unique_ids(self.items)
+        return self
+
+
+class CompletionDecision(_ContractModel):
+    action: Literal["finalize", "repair"]
+    outcome: CompletionOutcome
+    reason: NonBlank
+
+
+def _check_unique_ids(
+    items: tuple[AcceptanceItem, ...] | tuple[VerificationItemResult, ...],
+) -> None:
+    identities = [item.acceptance_id for item in items]
+    if len(set(identities)) != len(identities):
+        raise ValueError("duplicate acceptance_id")
+
+
+def _finalize(outcome: CompletionOutcome, reason: str) -> CompletionDecision:
+    return CompletionDecision(action="finalize", outcome=outcome, reason=reason)
+
+
+def _report_mismatch(
+    contract: TaskContract,
+    candidate: CompletionCandidate,
+    report: VerificationReport,
+) -> str | None:
+    expected_items = {item.acceptance_id: item for item in contract.items}
+    if any(item.acceptance_id not in expected_items for item in report.items):
+        raise ValueError("unknown report acceptance_id")
+    if candidate.subject_context_digest is None or report.subject_context_digest is None:
+        return "subject_context_digest_missing"
+    checks = (
+        (report.candidate_id, candidate.candidate_id, "candidate_mismatch"),
+        (report.contract_revision, contract.revision, "contract_revision_mismatch"),
+        (report.subject_digest, candidate.subject_digest, "subject_digest_mismatch"),
+        (
+            report.subject_context_digest,
+            candidate.subject_context_digest,
+            "subject_context_digest_mismatch",
+        ),
+        (
+            report.environment_digest,
+            candidate.environment_digest,
+            "environment_digest_mismatch",
+        ),
+    )
+    for actual, expected, reason in checks:
+        if actual != expected:
+            return reason
+    for item in report.items:
+        expected = expected_items[item.acceptance_id]
+        if item.verifier_id != expected.verifier_ref:
+            return "verifier_identity_mismatch"
+        if item.verifier_version != expected.verifier_version:
+            return "verifier_version_mismatch"
+        if item.verification_method != expected.verification_method:
+            return "verification_method_mismatch"
+    return None
+
+
+def reduce_completion(
+    contract: TaskContract,
+    candidate: CompletionCandidate,
+    report: VerificationReport | None,
+    repair_attempts: int = 0,
+    max_repairs: int = 3,
+) -> CompletionDecision:
+    """Decide completion without I/O or changing the acceptance contract.
+
+    ``repair_attempts`` counts repairs already performed. Fingerprint history,
+    policy/budget revocation, evidence resolution, and trusted report provenance
+    belong to the host; this reducer enforces metadata pins and a repair cap.
+    """
+    for value in (repair_attempts, max_repairs):
+        if type(value) is not int or value < 0:
+            raise ValueError("repair budgets must be a non-negative integer")
+    if report is None:
+        return _finalize("unverified", "verification_report_missing")
+    if mismatch := _report_mismatch(contract, candidate, report):
+        return _finalize("unverified", mismatch)
+    required = tuple(item for item in contract.items if item.required)
+    if not required:
+        return _finalize("unverified", "required_acceptance_empty")
+
+    results = {item.acceptance_id: item for item in report.items}
+    observations = tuple(results.get(item.acceptance_id) for item in required)
+    qualified = tuple(
+        item
+        for item in observations
+        if item is not None
+        and item.status == "passed"
+        and item.evidence_refs
+        and item.verification_method != "model_assisted"
+    )
+    if len(qualified) == len(required):
+        return _finalize("verified", "required_acceptance_verified")
+    if any(item is not None and item.status == "blocked" for item in observations):
+        return _finalize("blocked", "required_acceptance_blocked")
+
+    outcome: CompletionOutcome = "partial" if qualified else "unverified"
+    # An absent required result is an incomplete host report, not an Agent
+    # failure. An explicit not_run can be repaired only when the trusted host
+    # supplied an actionable explanation, a stable failure identity and an
+    # affirmative repairability decision; unknown verifier state cannot retry.
+    if any(item is None for item in observations):
+        return _finalize(outcome, "required_verification_incomplete")
+    has_not_run = any(item.status == "not_run" for item in observations)
+    has_failed = any(item.status == "failed" for item in observations)
+    item_repairable = any(
+        item is not None
+        and item.status in {"failed", "not_run"}
+        and item.repairable is True
+        and item.safe_summary.strip()
+        and item.evidence_refs
+        for item in observations
+    )
+    actionable_not_run = (
+        has_not_run
+        and not has_failed
+        and bool(report.failure_fingerprint.strip())
+        and (
+            item_repairable
+            or (
+                report.repairable
+                and all(
+                    item.safe_summary.strip() and item.evidence_refs
+                    for item in observations
+                    if item is not None and item.status == "not_run"
+                )
+            )
+        )
+    )
+    if has_not_run and not has_failed and not actionable_not_run:
+        return _finalize(outcome, "required_verification_incomplete")
+    if any(
+        item is not None
+        and item.status == "passed"
+        and (not item.evidence_refs or item.verification_method == "model_assisted")
+        for item in observations
+    ):
+        return _finalize(outcome, "qualified_evidence_missing")
+    if not (report.repairable or item_repairable):
+        return _finalize(
+            outcome,
+            "required_verification_incomplete" if has_not_run else "required_acceptance_failed",
+        )
+    if repair_attempts >= max_repairs:
+        return _finalize(outcome, "repair_budget_exhausted")
+    if not report.failure_fingerprint.strip():
+        return _finalize(outcome, "failure_fingerprint_missing")
+    return CompletionDecision(
+        action="repair",
+        outcome=outcome,
+        reason=(
+            "required_verification_incomplete"
+            if actionable_not_run
+            else "required_acceptance_failed"
+        ),
+    )

ksadk/harness/native/completion_text.py

@@ -0,0 +1,116 @@
+"""Assemble only a contiguous, host-authenticated output continuation chain."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import JsonValue
+
+from .model_replay import replay_fields
+
+if TYPE_CHECKING:
+    from .state import RunSnapshot
+
+
+def candidate_model_message(
+    snapshot: RunSnapshot,
+    *,
+    kind: Literal[
+        "rejected_final_candidate", "delivery_review_candidate"
+    ] = "rejected_final_candidate",
+) -> dict[str, JsonValue]:
+    """Keep the actual draft available to same-turn review and repair.
+
+    This typed message is model input, not a tool observation or an accepted
+    final answer. Public state and future Session history exclude it.
+    """
+    assert snapshot.candidate is not None
+    return {
+        "role": "assistant",
+        "kind": kind,
+        "content": snapshot.candidate["final_text"],
+        "candidate_id": snapshot.candidate["candidate_id"],
+        "candidate_status": "unverified" if kind == "delivery_review_candidate" else "rejected",
+        **replay_fields(snapshot.candidate_replay),
+    }
+
+
+def fragment_digest(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def complete_continuation(messages: tuple[dict[str, JsonValue], ...], final_suffix: str) -> str:
+    """Prepend contiguous output-limit fragments to their final suffix.
+
+    A task-resume frame, user message, tool batch, feedback, or malformed host
+    metadata breaks the chain. The model is explicitly asked for a suffix, so
+    this function does not guess at fuzzy overlap or rewrite model text.
+    """
+    fragments: list[str] = []
+    index = len(messages) - 1
+    while index >= 1:
+        observation = messages[index]
+        fragment = messages[index - 1]
+        if (
+            observation.get("role") != "user"
+            or observation.get("kind") != "continuation_observation"
+            or observation.get("continuation_mode", "suffix") != "suffix"
+            or fragment.get("role") != "assistant"
+            or fragment.get("kind") != "continuation_fragment"
+        ):
+            break
+        content = fragment.get("content")
+        response_id = fragment.get("continuation_response_id")
+        if (
+            not isinstance(content, str)
+            or not isinstance(response_id, str)
+            or observation.get("continuation_response_id") != response_id
+            or observation.get("continuation_fragment_digest") != fragment_digest(content)
+        ):
+            break
+        fragments.append(content)
+        index -= 2
+    return "".join(reversed(fragments)) + final_suffix
+
+
+def abandon_continuation(
+    messages: tuple[dict[str, JsonValue], ...], last_fragment: str
+) -> tuple[dict[str, JsonValue], ...]:
+    """Retire one unfinished chain without leaving executable tool JSON in context."""
+    prefix = list(messages)
+    discarded = [last_fragment]
+    while len(prefix) >= 2:
+        observation, fragment = prefix[-1], prefix[-2]
+        if (
+            observation.get("role") != "user"
+            or observation.get("kind") != "continuation_observation"
+            or fragment.get("role") != "assistant"
+            or fragment.get("kind") != "continuation_fragment"
+        ):
+            break
+        content = fragment.get("content")
+        response_id = fragment.get("continuation_response_id")
+        if (
+            not isinstance(content, str)
+            or not isinstance(response_id, str)
+            or observation.get("continuation_response_id") != response_id
+            or observation.get("continuation_fragment_digest") != fragment_digest(content)
+        ):
+            break
+        discarded.append(content)
+        del prefix[-2:]
+    fingerprint = fragment_digest("".join(reversed(discarded)))
+    return (
+        *prefix,
+        {
+            "role": "user",
+            "kind": "output_limit_restart_observation",
+            "content": (
+                "The previous response exceeded the output limit repeatedly. "
+                "Its unfinished tool call was not executed. Use smaller independent "
+                "tool calls or files; do not repeat one oversized call. "
+                f"Discarded output fingerprint: {fingerprint}."
+            ),
+        },
+    )