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

ksadk/harness/native/final_output.py

@@ -0,0 +1,34 @@
+"""Conservative final-answer normalization for an explicit host output contract."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from ksadk._model_json import load_model_json
+
+
+def normalize_final_output(
+    text: str, *, output_format: Literal["text", "json_object", "json_value"]
+) -> str:
+    """Unwrap one pure JSON fence; leave ambiguous or invalid output to verification.
+
+    Text-mode answers never change. JSON-mode candidates must contain only the
+    declared object or JSON value, optionally inside one complete unlabeled/json
+    Markdown fence. The host never infers, repairs, or coerces field values.
+    """
+    if output_format == "text":
+        return text
+    candidate = text.strip()
+    if candidate.startswith("```"):
+        lines = candidate.splitlines()
+        if len(lines) < 3 or lines[-1].strip() != "```":
+            return text
+        language = lines[0][3:].strip().lower()
+        if language not in {"", "json"}:
+            return text
+        candidate = "\n".join(lines[1:-1]).strip()
+    try:
+        parsed = load_model_json(candidate)
+    except (TypeError, ValueError, RecursionError):
+        return text
+    return candidate if output_format == "json_value" or isinstance(parsed, dict) else text

ksadk/harness/native/final_submission.py

@@ -0,0 +1,58 @@
+"""Host-governed structured final submission, separate from executable tools."""
+
+from __future__ import annotations
+
+import json
+
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import ValidationError
+
+from .model import ModelToolCall
+from .ports import RunConfiguration, ToolDefinition
+
+FINAL_SUBMISSION_TOOL = "submit_final_output"
+
+
+def final_submission_tool(config: RunConfiguration) -> ToolDefinition | None:
+    schema = config.final_submission_schema
+    if schema is None:
+        return None
+    return ToolDefinition(
+        name=FINAL_SUBMISSION_TOOL,
+        description=(
+            "Submit the final structured answer for host verification. "
+            "This does not execute a workspace action."
+            + (
+                (" Put the complete requested JSON object in "
+                 f"{config.final_submission_payload_key}."
+                 if config.final_output_format == "json_object"
+                 else " Put only the complete requested value in "
+                 f"{config.final_submission_payload_key}.")
+                if config.final_submission_payload_key is not None
+                else ""
+            )
+        ),
+        parameters=schema,
+    )
+
+
+def submitted_final_text(call: ModelToolCall, config: RunConfiguration) -> str | None:
+    schema = config.final_submission_schema
+    if schema is None or call.name != FINAL_SUBMISSION_TOOL or call.wire_arguments_invalid:
+        return None
+    try:
+        Draft202012Validator(schema).validate(call.arguments)
+    except ValidationError:
+        return None
+    output = (
+        call.arguments[config.final_submission_payload_key]
+        if config.final_submission_payload_key is not None
+        else call.arguments
+    )
+    if config.final_output_format == "text":
+        return output if isinstance(output, str) else None
+    try:
+        return json.dumps(output, ensure_ascii=False, sort_keys=True,
+                          separators=(",", ":"), allow_nan=False)
+    except (ValueError, TypeError):
+        return None

ksadk/harness/native/finalization_workspace.py

@@ -0,0 +1,96 @@
+"""Re-observe a recovered final candidate through the ordinary workspace effect."""
+
+from __future__ import annotations
+
+from .completion import CompletionCandidate, VerificationReport, _report_mismatch
+from .ports import RunConfiguration, WorkspaceObservation
+from .state import CommitBatch, EffectIntent, EffectReceipt, RunPhase, RunSnapshot
+from .transitions import finish, prepare_effect
+from .verification_binding import verification_subject_context_digest
+from .verification_workspace import changed_verification_subject
+
+
+def _cursor(snapshot: RunSnapshot, fence: int) -> str:
+    return (f"finalize:{fence}:{snapshot.goal_revision}:{snapshot.model_calls}:"
+            f"{snapshot.tool_calls}:{(snapshot.candidate or {}).get('candidate_id', '')}")
+
+
+def prepare_finalization_workspace(snapshot: RunSnapshot, fence: int) -> CommitBatch | None:
+    """A receipt from another owner cannot discharge this owner's fresh check."""
+    if (snapshot.phase != RunPhase.FINALIZING or snapshot.verification is None
+            or snapshot.reason == "policy_revoked"):
+        return None
+    cursor = _cursor(snapshot, fence)
+    return prepare_effect(snapshot, "workspace", {
+        "purpose": "finalization", "cursor": cursor, "fencing_token": fence,
+    }).model_copy(update={"require_no_pending_commands": True})
+
+
+def _unavailable(snapshot: RunSnapshot, reason: str, *, wall_expired: bool = False) -> RunSnapshot:
+    # The old receipt remains immutable in the Store. Only its eligibility as
+    # the current final answer is withdrawn; no replacement verifier is forged.
+    cleared = snapshot.model_copy(update={
+        "candidate": None, "verification": None, "verification_tool_calls": None,
+        "workspace_observation_cursor": None,
+    })
+    return finish(cleared, "budget_exhausted" if wall_expired else "unverified", reason)
+
+
+def _workspace_independent_report(
+    snapshot: RunSnapshot, observation: WorkspaceObservation, config: RunConfiguration,
+) -> bool:
+    # Equal capture failures cannot attest freshness. This narrow exception is
+    # for an explicitly independent report when no workspace existed on either
+    # side, never for a formerly captured workspace that disappeared.
+    if (snapshot.workspace_observation_status != "unavailable"
+            or snapshot.workspace_observation_reason != "workspace_missing"
+            or snapshot.workspace_revision is not None or snapshot.workspace_changed_paths
+            or observation.status != "unavailable" or observation.reason != "workspace_missing"
+            or observation.revision is not None or observation.changed_paths
+            or snapshot.verification_tool_calls != snapshot.tool_calls):
+        return False
+    try:
+        candidate = CompletionCandidate.model_validate(snapshot.candidate)
+        report = VerificationReport.model_validate(snapshot.verification)
+    except ValueError:
+        return False
+    known = {item.acceptance_id for item in config.contract.items}
+    return (
+        report.workspace_dependency == "none"
+        and all(item.acceptance_id in known for item in report.items)
+        and _report_mismatch(config.contract, candidate, report) is None
+        and candidate.subject_context_digest == verification_subject_context_digest(snapshot)
+    )
+
+
+def reduce_finalization_workspace(
+    snapshot: RunSnapshot, intent: EffectIntent, receipt: EffectReceipt,
+    config: RunConfiguration,
+) -> RunSnapshot:
+    """Seal observation, or revoke the stale candidate without spending repair calls."""
+    wall_expired = (receipt.result.get("reason") == "wall_time_hard_limit"
+                    or receipt.result.get("deadline_cause") == "wall_time_hard_limit")
+    if receipt.status != "committed":
+        return _unavailable(snapshot, "wall_time_hard_limit" if wall_expired
+                            else "finalization_workspace_unavailable", wall_expired=wall_expired)
+    fence = intent.payload.get("fencing_token")
+    if (snapshot.phase != RunPhase.FINALIZING or type(fence) is not int or fence < 1
+            or intent.payload.get("cursor") != _cursor(snapshot, fence)):
+        return _unavailable(snapshot, "finalization_workspace_mismatch")
+    try:
+        observation = WorkspaceObservation.model_validate(receipt.result)
+    except ValueError:
+        return _unavailable(snapshot, "finalization_workspace_mismatch")
+    if observation.operation_key != snapshot.pending_intent:
+        return _unavailable(snapshot, "finalization_workspace_mismatch")
+    if ((observation.status != "captured" or snapshot.workspace_observation_status != "captured")
+            and not _workspace_independent_report(snapshot, observation, config)):
+        return _unavailable(snapshot, "finalization_workspace_unavailable")
+    if changed := changed_verification_subject(
+        snapshot, observation, 0, reason="finalization_workspace_changed",
+    ):
+        return changed
+    # The original cursor is part of the sealed verification subject identity.
+    # Completion of this check is tracked by the current lease owner, not by
+    # rewriting that identity. A later owner always starts a new check.
+    return snapshot.model_copy(update={"pending_intent": None})

ksadk/harness/native/fork.py

@@ -0,0 +1,151 @@
+"""Pure transcript branching; no old execution state or workspace rollback."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from pydantic import JsonValue
+
+from .activation_contract import ActivationResourceRef
+from .completion import TaskContract
+from .history import project_session_history
+from .model import ModelReplayMetadata
+from .model_replay import remap_anthropic_replay, replay_fields
+from .ports import RunConfiguration, digest
+from .state import Contract, ForkCommand, ForkSource, RunScope, RunSnapshot
+
+
+class ForkCreation(Contract):
+    """Only the creator may start driving; duplicates receive current facts."""
+
+    snapshot: RunSnapshot
+    created: bool
+
+
+def command_run_id(scope: RunScope, source_run_id: str, command_id: str) -> str:
+    raw = json.dumps(
+        ["ksadk.native.fork-command/v1", scope.model_dump(mode="json"), source_run_id, command_id],
+        sort_keys=True, ensure_ascii=False, separators=(",", ":"),
+    )
+    return "fork_" + hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def fork_request_digest(snapshot: RunSnapshot) -> str:
+    # Run/Turn IDs, remapped historical call IDs and mutable workspace facts
+    # do not identify the request. Configuration and source authority do.
+    names = (
+        "scope", "fork_source", "session_id", "initial_goal_digest", "task_contract",
+        "configuration_digest", "profile_digest", "contract_digest", "context_binding",
+        "origin", "activation_resource_ref",
+    )
+    payload = snapshot.model_dump(mode="json", include=set(names))
+    raw = json.dumps(payload, sort_keys=True, ensure_ascii=False, separators=(",", ":"),
+                     allow_nan=False)
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def fork_source(source: RunSnapshot) -> ForkSource:
+    return ForkSource(
+        source_run_id=source.run_id,
+        source_session_id=source.session_id,
+        source_revision=source.revision,
+        source_event_seq=source.event_seq,
+        source_snapshot_digest=digest(source),
+    )
+
+
+def project_fork_history(
+    source: RunSnapshot, run_id: str, *, profile_digest: str | None = None,
+    configuration_digest: str | None = None,
+) -> tuple[dict[str, JsonValue], ...]:
+    """Rebuild protocol pair identities while preserving exact source provenance.
+
+    The normal history projector closes unfinished calls as unknown. An
+    unchanged host journal retains model frames with historical provenance;
+    other imports filter prior controls. Neither grants the new branch rights.
+    The new branch gets its own call IDs and matching private replay mappings,
+    including those already imported by an earlier source turn.
+    """
+    messages = project_session_history(
+        source, profile_digest=profile_digest, configuration_digest=configuration_digest,
+    )
+    ids: dict[str, str] = {}
+    for message in messages:
+        for call in message.get("tool_calls", ()):
+            original = call["id"]
+            raw = json.dumps([run_id, source.run_id, original], ensure_ascii=False)
+            mapped = "fork_" + hashlib.sha256(raw.encode()).hexdigest()[:32]
+            ids[original] = mapped
+            call["id"] = mapped
+    for message in messages:
+        if message.get("role") == "assistant" and message.get("provider_replay") is not None:
+            message.update(replay_fields(remap_anthropic_replay(
+                ModelReplayMetadata.model_validate(message["provider_replay"]), ids,
+            )))
+        if message.get("role") == "tool":
+            message["tool_call_id"] = ids[message["tool_call_id"]]
+        elif message.get("kind") == "historical_tool_observation":
+            content = message.get("content")
+            if not isinstance(content, str):
+                continue
+            try:
+                observation = json.loads(content)
+            except ValueError:
+                continue
+            if (isinstance(observation, dict)
+                    and observation.get("observation") == "kernel_effective_tool_input"
+                    and isinstance(observation.get("tool_call_id"), str)
+                    and observation["tool_call_id"] in ids):
+                observation["tool_call_id"] = ids[observation["tool_call_id"]]
+                message["content"] = json.dumps(observation, ensure_ascii=False)
+    return messages
+
+
+def build_fork_snapshot(
+    source: RunSnapshot,
+    *,
+    run_id: str,
+    turn_id: str,
+    session_id: str,
+    goal: str,
+    configuration: RunConfiguration,
+    contract: TaskContract,
+    context_binding: str,
+    workspace_revision: str,
+    activation_resource: ActivationResourceRef | None,
+    origin: dict | None,
+    command_id: str | None = None,
+) -> RunSnapshot:
+    """Construct a fresh run from history plus the destination host's authority."""
+    snapshot = RunSnapshot(
+        scope=source.scope,
+        run_id=run_id,
+        turn_id=turn_id,
+        session_id=session_id,
+        fork_source=fork_source(source),
+        goal=goal,
+        initial_goal_digest=hashlib.sha256(goal.encode("utf-8")).hexdigest(),
+        messages=(*project_fork_history(
+            source, run_id, profile_digest=configuration.profile.digest,
+            configuration_digest=configuration.digest,
+        ), {"role": "user", "content": goal}),
+        task_contract=contract.model_dump(mode="json"),
+        context_binding=context_binding,
+        profile_digest=configuration.profile.digest,
+        contract_digest=digest(contract),
+        configuration_digest=configuration.digest,
+        origin=origin or {},
+        workspace_revision=workspace_revision if workspace_revision != "unavailable" else None,
+        workspace_observation_status=(
+            "initial" if workspace_revision != "unavailable" else "unavailable"
+        ),
+        activation_resource_ref=(
+            activation_resource.model_dump(mode="json") if activation_resource is not None else None
+        ),
+    )
+    if command_id is not None:
+        snapshot = snapshot.model_copy(update={"fork_command": ForkCommand(
+            command_id=command_id, request_digest=fork_request_digest(snapshot),
+        )})
+    return snapshot

ksadk/harness/native/guidance.py

@@ -0,0 +1,91 @@
+"""Current-turn guidance at sealed boundaries, separate from replacing a goal.
+
+Reference: ZCode 872ad960 turn-guide-drain.ts, turn-tools.ts and turn-stop.ts.
+One input is injected after a completed tool batch or text-only response, then
+gets one effective model step before the next guide. The existing Store owns
+admission FIFO, command identity and atomic delivery facts.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import Field, ValidationError
+
+from .completion_text import candidate_model_message
+from .state import Contract, RunCommand, RunPhase, RunSnapshot
+
+
+class GuidanceInput(Contract):
+    text: Annotated[str, Field(min_length=1, max_length=32768, pattern=r"\S")]
+    expected_goal_revision: int = Field(strict=True, ge=0)
+
+
+def runnable_commands(snapshot, commands, *, guidance_enabled: bool):
+    """Defer guides without hiding cancellation, approval or explicit steering."""
+    boundary = (
+        snapshot.pending_intent is None
+        and snapshot.phase
+        in {
+            RunPhase.CREATED,
+            RunPhase.PREPARING_CONTEXT,
+            RunPhase.VERIFYING,
+            RunPhase.FINALIZING,
+        }
+        and (not snapshot.pending_guidance_ids or snapshot.phase == RunPhase.FINALIZING)
+    )
+    return tuple(
+        command
+        for command in commands
+        if command.kind != "guide" or not guidance_enabled or boundary
+    )
+
+
+def apply_guidance(snapshot: RunSnapshot, command: RunCommand):
+    if snapshot.phase.terminal:
+        return snapshot, "run_is_terminal"
+    try:
+        guidance = GuidanceInput.model_validate(command.payload)
+    except ValidationError:
+        return snapshot, "invalid_guidance"
+    if guidance.expected_goal_revision != snapshot.goal_revision:
+        return snapshot, "stale_goal_revision"
+    if snapshot.pending_guidance_ids:
+        return snapshot, "guidance_previous_unconsumed"
+    if snapshot.phase == RunPhase.FINALIZING and snapshot.reason == "effect_outcome_unknown":
+        return snapshot, "guidance_effect_unreconciled"
+    if not runnable_commands(snapshot, (command,), guidance_enabled=True):
+        return snapshot, "guidance_not_at_boundary"
+    messages = snapshot.messages
+    if snapshot.candidate is not None:
+        messages = (*messages, candidate_model_message(snapshot))
+    message = {
+        "role": "user",
+        "kind": "user_guidance",
+        "content": guidance.text,
+        "input_id": command.command_id,
+        "input_delivery": "guide",
+        "input_goal_revision": snapshot.goal_revision,
+    }
+    updated = snapshot.model_copy(
+        update={
+            "phase": RunPhase.PREPARING_CONTEXT,
+            "messages": (*messages, message),
+            "pending_guidance_ids": (command.command_id,),
+            "candidate": None,
+            "candidate_replay": None,
+            "verification": None,
+            "verification_tool_calls": None,
+            "delivery_review": None,
+            "stop_hook_state": None,
+            "prepared_context": None,
+            "compaction_request": None,
+            "force_compaction": False,
+            "continuations": 0,
+            "retry_not_before": 0,
+            "outcome": None,
+            "final_text": "",
+            "reason": None,
+        }
+    )
+    return RunSnapshot.model_validate_json(updated.model_dump_json()), "applied"