agentengine-sdk-python 0.8.1__py3-none-any.whl → 0.8.3__py3-none-any.whl

ksadk/observability/trajectory.py

@@ -0,0 +1,105 @@
+"""Stable UI trajectory projection for canonical RuntimeEvents.
+
+The durable store owns only RuntimeEvent/v2 facts. This module derives its
+compact trajectory shape from the Studio v2 projection; it must not reach into
+the read-only RuntimeEvent/v1 compatibility model.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ksadk.events.canonical import RuntimeEvent, dump_runtime_event
+from ksadk.studio.run_service import project_runtime_event
+
+PROJECTION_VERSION = 1
+
+
+def _record_id(event: RuntimeEvent, event_type: str, data: dict[str, Any]) -> str:
+    if event_type.startswith(("message.", "thinking.")):
+        return f"assistant:{data.get('itemId') or event.scope_id}"
+    if event_type.startswith(("tool.", "command.")):
+        return f"tool:{data.get('callId') or data.get('itemId') or event.event_id}"
+    if event_type.startswith("approval."):
+        return f"approval:{data.get('approvalId') or data.get('itemId') or event.event_id}"
+    if event_type.startswith("checkpoint."):
+        return f"checkpoint:{data.get('checkpointId') or data.get('itemId') or event.event_id}"
+    if event_type.startswith("a2ui.surface."):
+        return f"surface:{data.get('surfaceId') or data.get('itemId') or event.event_id}"
+    if event_type.startswith("context.compaction."):
+        return f"context:{event.scope_id}:compaction"
+    return f"system:{event.event_id}"
+
+
+def _category(event_type: str) -> str:
+    if event_type.startswith(("message.", "thinking.")):
+        return "assistant"
+    if event_type.startswith(("tool.", "command.")):
+        return "tool"
+    if event_type.startswith("approval."):
+        return "approval"
+    if event_type.startswith("context.compaction."):
+        return "context"
+    if event_type.startswith("artifact."):
+        return "artifact"
+    return "system"
+
+
+def _status(event_type: str, data: dict[str, Any]) -> str | None:
+    value = data.get("status")
+    if isinstance(value, str) and value:
+        return value
+    if event_type.endswith((".started", ".delta", ".requested", ".progress")):
+        return "running"
+    if event_type.endswith((".completed", ".resolved")):
+        return "completed"
+    if event_type.endswith(".failed"):
+        return "failed"
+    if event_type.endswith(".cancelled"):
+        return "canceled"
+    if event_type.endswith(".interrupted"):
+        return "interrupted"
+    return None
+
+
+def _summary(event_type: str, data: dict[str, Any]) -> str:
+    if event_type.startswith(("message.", "thinking.")):
+        return "Message"
+    for key in ("tool", "command", "message", "reason", "error"):
+        value = data.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return event_type
+
+
+def project_trajectory_event(event: RuntimeEvent) -> dict[str, Any]:
+    """Project one immutable v2 fact into the stable trajectory display shape."""
+
+    event_type, data = project_runtime_event(event)
+    details = dict(data)
+    details.pop("runtimeEvent", None)
+    return {
+        "projectionVersion": PROJECTION_VERSION,
+        "seqId": event.seq,
+        "eventId": event.event_id,
+        "recordId": _record_id(event, event_type, details),
+        "type": event_type,
+        "category": _category(event_type),
+        "turnId": None,
+        "stepId": None,
+        "timestamp": event.timestamp,
+        "status": _status(event_type, details),
+        "durationMs": details.get("durationMs"),
+        "summary": _summary(event_type, details),
+        "details": details,
+        "source": dump_runtime_event(event),
+    }
+
+
+def encode_sse(value: dict[str, Any], *, event_id: int) -> str:
+    data = json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    return f"id: {event_id}\nevent: runtime_event\ndata: {data}\n\n"
+
+
+__all__ = ["PROJECTION_VERSION", "encode_sse", "project_trajectory_event"]

ksadk/plugins/__init__.py

@@ -0,0 +1,167 @@
+"""Versioned contracts for the Phase 2 plugin composition boundary.
+
+This package models discovery, deterministic locking, and the controlled
+PluginHost lifecycle.  It does not create a second runtime/event store;
+providers keep their native execution authority behind these contracts.
+"""
+
+from ksadk.plugins.bundle import (
+    PluginBundleError,
+    PluginBundleResolver,
+    ResolvedPluginBundle,
+)
+from ksadk.plugins.context_contributor import (
+    AuthenticatedContextScope,
+    ContextClassification,
+    ContextContributorCacheability,
+    ContextContributorCapabilities,
+    ContextContributorExchange,
+    ContextContributorFailureMode,
+    ContextContributorRequest,
+    ContextContributorResponse,
+    ContextFragment,
+    ContextSourceReference,
+    ProjectedContextContribution,
+    context_contributor_json_schema,
+)
+from ksadk.plugins.contracts import (
+    CapabilityDefinition,
+    CompositionProfile,
+    PluginInventory,
+    PluginLock,
+    canonical_plugin_lock,
+    plugin_lock_digest,
+)
+from ksadk.plugins.ecosystem_bridge import (
+    BridgeAction,
+    BridgeCommitRequest,
+    BridgeCommitResult,
+    BridgeDescribeRequest,
+    BridgeDescribeResult,
+    BridgeDescriptor,
+    BridgeDisposeRequest,
+    BridgeDisposeResult,
+    BridgeHostObservation,
+    BridgeHostRequirement,
+    BridgeInspectExchange,
+    BridgeInspectRequest,
+    BridgeInspectResult,
+    BridgePlanRequest,
+    BridgePlanResult,
+    BridgeProbeExchange,
+    BridgeProbeRequest,
+    BridgeProbeResult,
+    BridgeReconcileRequest,
+    BridgeReconcileResult,
+    BridgeRejection,
+    BridgeRollbackRequest,
+    BridgeRollbackResult,
+    BridgeStageRequest,
+    BridgeStageResult,
+    BridgeTransitionPlan,
+    EcosystemInstallReceipt,
+    EcosystemPluginDescriptor,
+    EcosystemPluginInventory,
+    PluginDesiredState,
+    PluginEcosystem,
+    PluginEcosystemBridge,
+    PluginEcosystemBridgeFixture,
+    PluginEcosystemBridgeTranscript,
+    PluginIntegrationMode,
+    PluginManifestCandidate,
+    PluginObservedState,
+    PluginSupportMaturity,
+    ecosystem_bridge_json_schema,
+)
+from ksadk.plugins.ecosystem_probe import EcosystemProbeError, probe_ecosystem_manifests
+from ksadk.plugins.host import (
+    ExecutableAgentProvider,
+    PluginActivationSession,
+    PluginCapabilityBinding,
+    PluginExecutionContext,
+    PluginHost,
+    PluginHostError,
+    PreparedAgent,
+)
+from ksadk.plugins.resolver import (
+    PluginRegistry,
+    PluginResolutionError,
+    ResolvedComposition,
+    composition_profile_digest,
+)
+
+__all__ = [
+    "AuthenticatedContextScope",
+    "BridgeAction",
+    "BridgeCommitRequest",
+    "BridgeCommitResult",
+    "BridgeDescribeRequest",
+    "BridgeDescribeResult",
+    "BridgeDescriptor",
+    "BridgeDisposeRequest",
+    "BridgeDisposeResult",
+    "BridgeHostObservation",
+    "BridgeHostRequirement",
+    "BridgeInspectExchange",
+    "BridgeInspectRequest",
+    "BridgeInspectResult",
+    "BridgePlanRequest",
+    "BridgePlanResult",
+    "BridgeProbeExchange",
+    "BridgeProbeRequest",
+    "BridgeProbeResult",
+    "BridgeReconcileRequest",
+    "BridgeReconcileResult",
+    "BridgeRejection",
+    "BridgeRollbackRequest",
+    "BridgeRollbackResult",
+    "BridgeStageRequest",
+    "BridgeStageResult",
+    "BridgeTransitionPlan",
+    "CapabilityDefinition",
+    "CompositionProfile",
+    "ContextClassification",
+    "ContextContributorCacheability",
+    "ContextContributorCapabilities",
+    "ContextContributorExchange",
+    "ContextContributorFailureMode",
+    "ContextContributorRequest",
+    "ContextContributorResponse",
+    "ContextFragment",
+    "ContextSourceReference",
+    "EcosystemInstallReceipt",
+    "EcosystemProbeError",
+    "EcosystemPluginDescriptor",
+    "EcosystemPluginInventory",
+    "PluginInventory",
+    "PluginLock",
+    "PluginDesiredState",
+    "PluginEcosystem",
+    "PluginEcosystemBridge",
+    "PluginEcosystemBridgeFixture",
+    "PluginEcosystemBridgeTranscript",
+    "PluginIntegrationMode",
+    "PluginManifestCandidate",
+    "PluginObservedState",
+    "PluginSupportMaturity",
+    "PluginBundleError",
+    "PluginBundleResolver",
+    "ResolvedPluginBundle",
+    "ExecutableAgentProvider",
+    "PluginActivationSession",
+    "PluginCapabilityBinding",
+    "PluginExecutionContext",
+    "PluginHost",
+    "PluginHostError",
+    "PreparedAgent",
+    "PluginRegistry",
+    "PluginResolutionError",
+    "ProjectedContextContribution",
+    "ResolvedComposition",
+    "composition_profile_digest",
+    "context_contributor_json_schema",
+    "ecosystem_bridge_json_schema",
+    "canonical_plugin_lock",
+    "plugin_lock_digest",
+    "probe_ecosystem_manifests",
+]

ksadk/plugins/bridges/__init__.py

@@ -0,0 +1,45 @@
+"""Native-host ecosystem bridges.
+
+Bridges keep each ecosystem's executable ABI inside its native host.  They do
+not add a generic plugin execution API to KsADK.
+"""
+
+from ksadk.plugins.bridges.codex import (
+    CodexAppServerPluginBridge,
+    CodexBridgeError,
+    CodexPluginApprovalRequired,
+    CodexPluginDetail,
+    CodexPluginInventory,
+    CodexPluginNotFoundError,
+)
+from ksadk.plugins.bridges.dsh import (
+    DshBridgeError,
+    DshBridgeHost,
+    DshClientBundle,
+    DshHostUnavailableError,
+    DshPluginApprovalRequired,
+    DshPluginInventory,
+    DshPluginMutationError,
+    DshPluginNotFoundError,
+    DshProfilePluginBridge,
+    DshProfileProjection,
+)
+
+__all__ = [
+    "CodexAppServerPluginBridge",
+    "CodexBridgeError",
+    "CodexPluginApprovalRequired",
+    "CodexPluginDetail",
+    "CodexPluginInventory",
+    "CodexPluginNotFoundError",
+    "DshBridgeError",
+    "DshBridgeHost",
+    "DshClientBundle",
+    "DshHostUnavailableError",
+    "DshPluginApprovalRequired",
+    "DshPluginInventory",
+    "DshPluginMutationError",
+    "DshPluginNotFoundError",
+    "DshProfilePluginBridge",
+    "DshProfileProjection",
+]