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

ksadk/sandbox/local_launcher.py

@@ -0,0 +1,90 @@
+"""Isolated Python entrypoint that applies rlimits before exec.
+
+It is started with ``python -I -S`` so untrusted workspace modules cannot replace
+the imported launcher or the standard-library ``resource`` module.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("--limits", required=True)
+    parser.add_argument("--report-fd", required=True, type=int)
+    parser.add_argument("command", nargs=argparse.REMAINDER)
+    arguments = parser.parse_args(argv)
+    command = list(arguments.command)
+    if command[:1] == ["--"]:
+        command = command[1:]
+    report = _apply_limits(json.loads(arguments.limits))
+    os.write(arguments.report_fd, json.dumps(report, sort_keys=True).encode("utf-8"))
+    os.close(arguments.report_fd)
+    status = report["status"]
+    if status != "applied" and not (status == "partial" and sys.platform == "darwin"):
+        return 125
+    if not command:
+        return 125
+    try:
+        os.execvpe(command[0], command, os.environ)
+    except OSError as exc:
+        print(f"local-process launcher exec failed: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 126
+
+
+def _apply_limits(configured: dict[str, object]) -> dict[str, object]:
+    try:
+        import resource
+    except ImportError:
+        return {"status": "unsupported", "applied": {}, "unsupported": ["resource_module"]}
+
+    names = {
+        "cpu_seconds": "RLIMIT_CPU",
+        "address_space_bytes": "RLIMIT_AS",
+        "max_processes": "RLIMIT_NPROC",
+        "max_open_files": "RLIMIT_NOFILE",
+        "max_file_bytes": "RLIMIT_FSIZE",
+    }
+    applied: dict[str, int] = {}
+    unsupported: list[str] = []
+    failed: list[str] = []
+    for name, constant_name in names.items():
+        limit = configured.get(name)
+        if type(limit) is not int or limit < 1:
+            failed.append(f"{name}:invalid")
+            continue
+        if name == "address_space_bytes" and sys.platform == "darwin":
+            # Darwin exposes RLIMIT_AS but rejects useful values on supported
+            # Python/macOS combinations. Linux is the deployment target.
+            unsupported.append(name)
+            continue
+        if name == "max_processes" and sys.platform == "darwin":
+            # RLIMIT_NPROC is per UID. Developer desktops commonly already have
+            # more processes than the requested Skill budget.
+            unsupported.append(name)
+            continue
+        if not hasattr(resource, constant_name):
+            unsupported.append(name)
+            continue
+        resource_id = getattr(resource, constant_name)
+        try:
+            _, hard = resource.getrlimit(resource_id)
+            effective = limit if hard == resource.RLIM_INFINITY else min(limit, hard)
+            resource.setrlimit(resource_id, (effective, effective))
+            soft_after, hard_after = resource.getrlimit(resource_id)
+            if soft_after != effective or hard_after != effective:
+                failed.append(f"{name}:verification")
+            else:
+                applied[name] = effective
+        except (OSError, ValueError) as exc:
+            failed.append(f"{name}:{type(exc).__name__}")
+    status = "failed" if failed else ("partial" if unsupported else "applied")
+    return {"status": status, "applied": applied, "unsupported": unsupported, "failed": failed}
+
+
+if __name__ == "__main__":  # pragma: no cover - exercised through subprocesses
+    raise SystemExit(main())

ksadk/scheduler/dispatcher.py

@@ -30,7 +30,7 @@ class AgentControlSchedulerDispatcher:
     """Translate one occurrence into a single durable AgentControl enqueue.
 
     This dispatcher is intentionally local-runtime only.  A hosted scheduler
-    must obtain a Server-issued permit at its admission boundary in Phase 3;
+    must obtain a Server-issued permit at its admission boundary in admission boundary;
     this class never makes local permits look valid against hosted JWKS.
     """
 

ksadk/server/invocation_identity.py

@@ -0,0 +1,118 @@
+"""Private trusted-identity carrier for hosted runtime requests."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from fastapi import Header, HTTPException
+
+from ksadk.runtime_context import TRUSTED_IDENTITY_METADATA_KEY, PlatformIdentityContext
+
+
+def _header_value(value: Any) -> str:
+    return value.strip() if isinstance(value, str) else ""
+
+
+def trusted_invocation_identity_from_headers(
+    headers: Mapping[str, Any],
+) -> PlatformIdentityContext:
+    """Resolve the private carrier from an ASGI/HTTP header mapping."""
+
+    return _resolve_trusted_invocation_identity_values(
+        identity_namespace=headers.get("x-agentengine-identity-namespace"),
+        tenant_id=headers.get("x-agentengine-business-tenant-id"),
+        subject_type=headers.get("x-agentengine-subject-type"),
+        subject_id=headers.get("x-agentengine-subject-id"),
+    )
+
+
+def _resolve_trusted_invocation_identity_values(
+    *,
+    identity_namespace: Any,
+    tenant_id: Any,
+    subject_type: Any,
+    subject_id: Any,
+) -> PlatformIdentityContext:
+    values = {
+        "identity_namespace": _header_value(identity_namespace),
+        "tenant_id": _header_value(tenant_id),
+        "subject_type": _header_value(subject_type),
+        "subject_id": _header_value(subject_id),
+    }
+    present = {field for field, value in values.items() if value}
+    if not present:
+        return PlatformIdentityContext()
+    if present != set(values):
+        raise HTTPException(status_code=401, detail="Incomplete trusted business identity context")
+    limits = {"identity_namespace": 128, "tenant_id": 128, "subject_type": 32, "subject_id": 128}
+    for field, value in values.items():
+        if len(value) > limits[field] or any(ord(char) < 32 or ord(char) == 127 for char in value):
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid trusted business identity field: {field}",
+            )
+    return PlatformIdentityContext.from_payload(values)
+
+
+def trusted_invocation_identity_headers(identity: Any) -> dict[str, str]:
+    """Build the private header carrier for an in-process runtime hop."""
+
+    resolved = coerce_trusted_invocation_identity(identity)
+    if resolved.is_empty:
+        return {}
+    return {
+        "X-AgentEngine-Identity-Namespace": resolved.identity_namespace,
+        "X-AgentEngine-Business-Tenant-Id": resolved.tenant_id,
+        "X-AgentEngine-Subject-Type": resolved.subject_type,
+        "X-AgentEngine-Subject-Id": resolved.subject_id,
+    }
+
+
+def resolve_trusted_invocation_identity(
+    x_agentengine_identity_namespace: str | None = Header(
+        None, alias="X-AgentEngine-Identity-Namespace"
+    ),
+    x_agentengine_business_tenant_id: str | None = Header(
+        None, alias="X-AgentEngine-Business-Tenant-Id"
+    ),
+    x_agentengine_subject_type: str | None = Header(None, alias="X-AgentEngine-Subject-Type"),
+    x_agentengine_subject_id: str | None = Header(None, alias="X-AgentEngine-Subject-Id"),
+) -> PlatformIdentityContext:
+    """Resolve the all-or-none identity rebuilt by the private gateway hop."""
+
+    return _resolve_trusted_invocation_identity_values(
+        identity_namespace=x_agentengine_identity_namespace,
+        tenant_id=x_agentengine_business_tenant_id,
+        subject_type=x_agentengine_subject_type,
+        subject_id=x_agentengine_subject_id,
+    )
+
+
+def coerce_trusted_invocation_identity(value: Any) -> PlatformIdentityContext:
+    """Keep direct unit calls compatible with FastAPI's dependency default."""
+
+    return value if isinstance(value, PlatformIdentityContext) else PlatformIdentityContext()
+
+
+def inject_trusted_invocation_identity(
+    metadata: Mapping[str, Any] | None,
+    identity: Any,
+) -> dict[str, Any]:
+    """Overwrite the private key; caller metadata can never create this context."""
+
+    result = dict(metadata or {})
+    result.pop(TRUSTED_IDENTITY_METADATA_KEY, None)
+    resolved = coerce_trusted_invocation_identity(identity)
+    if not resolved.is_empty:
+        result[TRUSTED_IDENTITY_METADATA_KEY] = resolved.to_payload()
+    return result
+
+
+__all__ = [
+    "TRUSTED_IDENTITY_METADATA_KEY",
+    "coerce_trusted_invocation_identity",
+    "inject_trusted_invocation_identity",
+    "resolve_trusted_invocation_identity",
+    "trusted_invocation_identity_from_headers",
+    "trusted_invocation_identity_headers",
+]

ksadk/server/routes/common.py

@@ -16,6 +16,7 @@ from fastapi.responses import FileResponse, Response
 
 from ksadk.conversations.attachments import compact_attachment_result_for_session
 from ksadk.conversations.model_context import normalize_model_metadata
+from ksadk.runtime_context import PlatformIdentityContext
 from ksadk.runtime_state import load_state as load_runtime_state
 from ksadk.server.factory import (
     RuntimeAppState,
@@ -28,6 +29,7 @@ from ksadk.server.terminal_sessions import (
     register_terminal_routes,
 )
 from ksadk.sessions import Session
+from ksadk.sessions.invocation_identity import identity_scope_ref
 from ksadk.sessions.local_service import resolve_local_session_dir
 from ksadk.ui_config import UI_PROFILE_CUSTOM, resolve_ui_config
 from ksadk_runtime_common.workspace_files import (
@@ -35,6 +37,10 @@ from ksadk_runtime_common.workspace_files import (
     workspace_files_enabled,
 )
 
+from ..invocation_identity import (
+    trusted_invocation_identity_from_headers,
+    trusted_invocation_identity_headers,
+)
 from . import dependencies as deps
 from .routers import health_meta_router
 
@@ -92,8 +98,17 @@ _MAX_REFERENCE_TEXT_BYTES = 3_000_000
 _UPLOAD_URI_SCHEME = "ksadk-upload://"
 
 
-def _workspace_root_dir() -> Path:
-    return Path(resolve_local_session_dir()) / "workspace"
+def _workspace_root_dir(
+    invocation_identity: PlatformIdentityContext | None = None,
+) -> Path:
+    root = Path(resolve_local_session_dir()) / "workspace"
+    if invocation_identity is not None and not invocation_identity.is_empty:
+        root = root / "identities" / identity_scope_ref(invocation_identity)
+    return root
+
+
+def _workspace_request_root(request: Request) -> Path:
+    return _workspace_root_dir(trusted_invocation_identity_from_headers(request.headers))
 
 
 _NATIVE_TUI_FRAMEWORKS = {"hermes", "openclaw"}
@@ -104,10 +119,18 @@ def _current_framework() -> str:
     return str(context.runtime_type if context is not None else "").strip().lower()
 
 
-def _build_native_terminal_capability(framework: str) -> dict[str, Any]:
+def _build_native_terminal_capability(
+    framework: str,
+    invocation_identity: PlatformIdentityContext | None = None,
+) -> dict[str, Any]:
+    isolated_identity = (
+        isinstance(invocation_identity, PlatformIdentityContext)
+        and not invocation_identity.is_empty
+    )
     enabled = (
         native_terminal_supported()
         and str(framework or "").strip().lower() in _NATIVE_TUI_FRAMEWORKS
+        and not isolated_identity
     )
     return {
         "Enabled": enabled,
@@ -127,6 +150,7 @@ def _register_integrated_routers(app: FastAPI, state: RuntimeAppState) -> None:
         create_workspace_files_router(
             root_getter=_workspace_root_dir,
             enabled_getter=lambda: workspace_files_enabled(default=True),
+            request_root_getter=_workspace_request_root,
         )
     )
     state.terminal_manager = TerminalSessionManager(
@@ -137,6 +161,9 @@ def _register_integrated_routers(app: FastAPI, state: RuntimeAppState) -> None:
         app,
         state.terminal_manager,
         bind_context=lambda: bind_runtime_state(state),
+        identity_access_allowed=lambda headers: (
+            trusted_invocation_identity_from_headers(headers).is_empty
+        ),
     )
 
 
@@ -631,6 +658,7 @@ async def _workspace_runtime_request(
     *,
     params: Optional[Dict[str, Any]] = None,
     files: Optional[Dict[str, Any]] = None,
+    invocation_identity: PlatformIdentityContext | None = None,
 ) -> httpx.Response:
     runtime_app = get_state().app
     if runtime_app is None:
@@ -640,6 +668,7 @@ async def _workspace_runtime_request(
         response = await client.request(
             method,
             runtime_path,
+            headers=trusted_invocation_identity_headers(invocation_identity),
             params=params,
             files=files,
         )

ksadk/server/routes/control.py

@@ -10,7 +10,7 @@ import uuid
 from collections.abc import AsyncIterator, Mapping
 from typing import Any, Optional
 
-from fastapi import HTTPException, Query
+from fastapi import Depends, HTTPException, Query
 from fastapi.responses import StreamingResponse
 
 from ksadk.conversations.run_kinds import (
@@ -19,10 +19,17 @@ from ksadk.conversations.run_kinds import (
     RUN_TRIGGER_CHECKPOINT_RESUME,
 )
 from ksadk.conversations.runtime_payloads import build_responses_payload
+from ksadk.conversations.runtime_persistence import require_conversation_session
 from ksadk.conversations.runtime_streaming import stream_runtime_responses_conversation_turn
 from ksadk.runtime.conversation_execution import invoke_runtime_conversation_once
+from ksadk.runtime_context import PlatformIdentityContext
 from ksadk.server.factory import get_runtime_execution, get_state
 
+from ..invocation_identity import (
+    coerce_trusted_invocation_identity,
+    inject_trusted_invocation_identity,
+    resolve_trusted_invocation_identity,
+)
 from . import dependencies as deps
 from .checkpoint_resolution import _find_session_checkpoint
 from .common import _action_response
@@ -54,6 +61,33 @@ from .streaming import (
 )
 
 
+async def _require_control_session(
+    service: Any,
+    *,
+    session_id: str,
+    agent_id: str | None,
+    user_id: str | None,
+    invocation_identity: PlatformIdentityContext,
+):
+    invocation_identity = coerce_trusted_invocation_identity(invocation_identity)
+    if invocation_identity.is_empty:
+        return await _require_action_session(
+            service,
+            session_id=session_id,
+            agent_id=agent_id,
+            user_id=user_id,
+        )
+    if not agent_id:
+        raise HTTPException(status_code=400, detail="AgentId is required")
+    return await require_conversation_session(
+        agent_id=agent_id,
+        user_id=str(user_id or ""),
+        session_id=session_id,
+        session_service_provider=lambda: service,
+        invocation_identity=invocation_identity,
+    )
+
+
 def _resolve_active_runner() -> Any:
     """Expose the adapter-owned runner for persistence capability probing."""
 
@@ -66,13 +100,18 @@ def _resolve_active_runner() -> Any:
 
 
 @control_router.post("/agentengine/api/v1/GetCheckpointResumePreview")
-async def get_checkpoint_resume_preview_action(request: GetCheckpointResumePreviewActionRequest):
+async def get_checkpoint_resume_preview_action(
+    request: GetCheckpointResumePreviewActionRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
+    invocation_identity = coerce_trusted_invocation_identity(invocation_identity)
     service = deps.resolve_session_service()
-    await _require_action_session(
+    await _require_control_session(
         service,
         session_id=request.SessionId,
         agent_id=request.AgentId,
         user_id=request.UserId,
+        invocation_identity=invocation_identity,
     )
 
     checkpoint = await _find_session_checkpoint(
@@ -123,14 +162,19 @@ async def get_checkpoint_resume_preview_action(request: GetCheckpointResumePrevi
 
 
 @control_router.post("/agentengine/api/v1/ResumeRun")
-async def resume_run_action(request: ResumeRunActionRequest):
+async def resume_run_action(
+    request: ResumeRunActionRequest,
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
+):
+    invocation_identity = coerce_trusted_invocation_identity(invocation_identity)
     executor, launch_context = get_runtime_execution()
     service = deps.resolve_session_service()
-    session = await _require_action_session(
+    session = await _require_control_session(
         service,
         session_id=request.SessionId,
         agent_id=request.AgentId,
         user_id=request.UserId,
+        invocation_identity=invocation_identity,
     )
 
     checkpoint = await _find_session_checkpoint(
@@ -201,6 +245,10 @@ async def resume_run_action(request: ResumeRunActionRequest):
         **_metadata_runtime_controls,
         "responses_conversation": True,
     }
+    resume_request_metadata = inject_trusted_invocation_identity(
+        resume_request_metadata,
+        invocation_identity,
+    )
 
     if request.Background:
         resume_invocation_id = str(request.InvocationId or resume_input["resume_attempt_id"])
@@ -374,9 +422,7 @@ async def _runtime_capability_snapshot(*, force: bool) -> Any:
 
     state = get_state()
     runner = _resolve_active_runner()
-    wait_timeout = max(
-        0.1, float(os.getenv("KSADK_PERSISTENCE_PROBE_TIMEOUT") or "2")
-    )
+    wait_timeout = max(0.1, float(os.getenv("KSADK_PERSISTENCE_PROBE_TIMEOUT") or "2"))
     return await state.persistence_capability.get_snapshot(
         runner=runner,
         framework=_runner_framework(runner),
@@ -430,17 +476,20 @@ async def subscribe_run_events_action(
     AfterSeqId: int = Query(0),
     AgentId: Optional[str] = Query(None),
     UserId: Optional[str] = Query(None),
+    invocation_identity: PlatformIdentityContext = Depends(resolve_trusted_invocation_identity),
 ):
+    invocation_identity = coerce_trusted_invocation_identity(invocation_identity)
     session_id = str(SessionId or "").strip()
     invocation_id = str(InvocationId or "").strip()
     if not session_id or not invocation_id:
         raise HTTPException(status_code=400, detail="SessionId and InvocationId are required")
     service = deps.resolve_session_service()
-    await _require_action_session(
+    await _require_control_session(
         service,
         session_id=session_id,
         agent_id=AgentId,
         user_id=UserId,
+        invocation_identity=invocation_identity,
     )
     if not await _session_contains_invocation(service, session_id, invocation_id):
         raise HTTPException(
@@ -453,6 +502,12 @@ async def subscribe_run_events_action(
         deadline = time.monotonic() + 5 * 60
         last_heartbeat_at = time.monotonic()
         last_terminal_check_at = 0.0
+        if deps.heartbeat_interval() <= 0:
+            # A zero interval explicitly requests an immediate keepalive. Do
+            # this before the first storage poll so a concurrently completed
+            # run cannot make the reconnect response timing-dependent.
+            yield ": heartbeat\n\n"
+            last_heartbeat_at = time.monotonic()
         while True:
             events = await _oldest_unconsumed_session_events(
                 service,

ksadk/server/routes/dependencies.py

@@ -78,7 +78,8 @@ def describe_session_backend() -> dict[str, Any]:
 async def get_persistence_status(
     *, framework: str | None = None, use_cache: bool = True
 ) -> dict[str, Any]:
-    provider = current().get_persistence_status
+    # App-scoped session routes also run without the legacy global app.
+    provider = _dependencies.get_persistence_status if _dependencies is not None else None
     if provider is None:
         from ksadk.sessions.persistence import get_persistence_status as provider
     try:

ksadk/server/routes/kernel_ingress.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""RunAgent / Responses 入口的 kernel 路径（Phase 1 Task 8 Step 3-5）。
+"""RunAgent / Responses 入口的 kernel 路径（Kernel Task 8 Step 3-5）。
 
 只在 ``kernel_route_active()`` 时启用（灰度 opt-in）；旧 HTTP 行为保持兼容：
 - accepted -> 202、duplicate -> 200、rejected -> 400、unsupported -> 409、
@@ -18,6 +18,8 @@ from fastapi.responses import JSONResponse, StreamingResponse
 
 from ksadk.kernel import ingress
 from ksadk.kernel.contracts import AgentControlReceipt
+from ksadk.runtime_context import PlatformIdentityContext
+from ksadk.sessions.invocation_identity import identity_owner_payload
 
 logger = logging.getLogger(__name__)
 
@@ -35,6 +37,7 @@ async def _kernel_submit(
     correlation_ref: str | None,
     source_kind: str,
     runtime_options: dict[str, Any] | None = None,
+    invocation_identity: PlatformIdentityContext | None = None,
 ) -> tuple[AgentControlReceipt, ingress.TrustedRuntimeContext]:
     trusted = ingress.trusted_context(
         source_kind=source_kind,
@@ -60,6 +63,11 @@ async def _kernel_submit(
         **({correlation_kwarg: correlation_ref} if correlation_ref else {}),
         **({"runtime_options": runtime_options} if runtime_options else {}),
     )
+    owner = identity_owner_payload(invocation_identity)
+    if owner:
+        command = command.model_copy(
+            update={"payload": {**dict(command.payload), "invocation_identity": owner}}
+        )
     receipt = await ingress.submit_command(command, permit=trusted.permit)
     return receipt, trusted