agent-lifecycle-kit 1.50.1__py3-none-any.whl

agent_lifecycle/__init__.py

@@ -0,0 +1,5 @@
+"""Agent Lifecycle Kit public package."""
+
+from ._version import __version__
+
+__all__ = ["__version__"]

agent_lifecycle/__main__.py

@@ -0,0 +1,5 @@
+"""python -m agent_lifecycle entry point."""
+
+from agent_lifecycle.cli import main
+
+raise SystemExit(main())

agent_lifecycle/_version.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "1.50.1"

agent_lifecycle/adapter_sessions/__init__.py

@@ -0,0 +1,41 @@
+"""Managed adapter session helpers."""
+
+from agent_lifecycle.adapter_sessions.contracts import (
+    build_adapter_session_receipt,
+    build_launch_receipt,
+    build_resume_receipt,
+)
+from agent_lifecycle.adapter_sessions.launcher import launch_from_descriptor
+from agent_lifecycle.adapter_sessions.session_store import (
+    create_session,
+    load_session,
+    session_path,
+    update_session,
+)
+from agent_lifecycle.adapter_sessions.task_intake import (
+    ADAPTER_TASK_RUN_REQUEST_SCHEMA,
+    ADAPTER_TASK_START_RECEIPT_SCHEMA,
+    start_adapter_task,
+)
+from agent_lifecycle.adapter_sessions.workflow_bridge import (
+    managed_adapter_run,
+    promote_session_to_workflow,
+    resume_adapter_session,
+)
+
+__all__ = [
+    "build_adapter_session_receipt",
+    "build_launch_receipt",
+    "build_resume_receipt",
+    "create_session",
+    "ADAPTER_TASK_RUN_REQUEST_SCHEMA",
+    "ADAPTER_TASK_START_RECEIPT_SCHEMA",
+    "launch_from_descriptor",
+    "load_session",
+    "managed_adapter_run",
+    "promote_session_to_workflow",
+    "resume_adapter_session",
+    "session_path",
+    "start_adapter_task",
+    "update_session",
+]

agent_lifecycle/adapter_sessions/contracts.py

@@ -0,0 +1,133 @@
+"""Typed receipts for managed adapter sessions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_lifecycle.contracts import canonical_digest
+
+ADAPTER_SESSION_RECEIPT_SCHEMA = "agent-adapter-session-receipt.v1"
+MANAGED_ADAPTER_LAUNCH_RECEIPT_SCHEMA = "agent-managed-adapter-launch-receipt.v1"
+ADAPTER_SESSION_RESUME_RECEIPT_SCHEMA = "agent-adapter-session-resume-receipt.v1"
+
+
+def build_adapter_session_receipt(
+    *,
+    status: str,
+    session_id: str,
+    adapter_id: str,
+    mode: str,
+    launch_profile: dict[str, Any],
+    state_identity: dict[str, Any] | None = None,
+    managed_workflow_proof: dict[str, Any] | None = None,
+    progress_hook_default: str = "off",
+    host_launch_started: bool = False,
+    state_written: bool = True,
+    blockers: list[dict[str, Any]] | None = None,
+    next_action: dict[str, Any] | None = None,
+    launch_receipt: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    managed_workflow = managed_workflow_proof is not None
+    body = {
+        "schemaVersion": ADAPTER_SESSION_RECEIPT_SCHEMA,
+        "status": status,
+        "sessionId": session_id,
+        "adapterId": adapter_id,
+        "mode": mode,
+        "managedWorkflow": managed_workflow,
+        "lifecycleCoverageClaimed": managed_workflow and status not in {"WAITING_FOR_TASK", "BLOCKED", "UNMANAGED"},
+        "launchProfile": _profile_summary(launch_profile),
+        "stateIdentity": state_identity,
+        "managedWorkflowProof": managed_workflow_proof,
+        "progressHookDefault": progress_hook_default,
+        "hostLaunchStarted": host_launch_started,
+        "modelCallsStarted": False,
+        "stateWritten": state_written,
+        "secretsWritten": False,
+        "nativeConfigWritten": False,
+        "blockers": blockers or [],
+        "nextAction": next_action,
+        "launchReceipt": launch_receipt,
+        "productionPromotionClaimed": False,
+    }
+    return {**body, "receiptDigest": canonical_digest(body)}
+
+
+def build_launch_receipt(
+    *,
+    status: str,
+    adapter_id: str,
+    session_id: str,
+    launch_mode: str,
+    argv: list[str],
+    timeout_seconds: float,
+    env: dict[str, Any],
+    exit_code: int | None,
+    timed_out: bool,
+    cancelled: bool = False,
+    stdout_tail: str = "",
+    stderr_tail: str = "",
+    host_launch_started: bool = False,
+    blockers: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    body = {
+        "schemaVersion": MANAGED_ADAPTER_LAUNCH_RECEIPT_SCHEMA,
+        "status": status,
+        "adapterId": adapter_id,
+        "sessionId": session_id,
+        "launchMode": launch_mode,
+        "argv": argv,
+        "shell": False,
+        "timeoutSeconds": timeout_seconds,
+        "env": env,
+        "exitCode": exit_code,
+        "timedOut": timed_out,
+        "cancelled": cancelled,
+        "stdout": {"tail": stdout_tail[-2000:], "redacted": True},
+        "stderr": {"tail": stderr_tail[-2000:], "redacted": True},
+        "hostLaunchStarted": host_launch_started,
+        "modelCallsStarted": False,
+        "secretsWritten": False,
+        "nativeConfigWritten": False,
+        "blockers": blockers or [],
+        "productionPromotionClaimed": False,
+    }
+    return {**body, "receiptDigest": canonical_digest(body)}
+
+
+def build_resume_receipt(
+    *,
+    session_id: str,
+    adapter_id: str,
+    expected_identity: dict[str, Any],
+    actual_identity: dict[str, Any],
+    blockers: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    items = blockers or []
+    lineage_status = "FAIL" if items else ("PASS" if actual_identity else "NOT_BOUND")
+    status = "BLOCKED" if items else ("PASS" if actual_identity else "UNMANAGED")
+    body = {
+        "schemaVersion": ADAPTER_SESSION_RESUME_RECEIPT_SCHEMA,
+        "status": status,
+        "sessionId": session_id,
+        "adapterId": adapter_id,
+        "lineageStatus": lineage_status,
+        "expectedIdentity": expected_identity,
+        "actualIdentity": actual_identity,
+        "managedWorkflow": not items and bool(actual_identity),
+        "lifecycleCoverageClaimed": not items and bool(actual_identity),
+        "blockers": items,
+        "productionPromotionClaimed": False,
+    }
+    return {**body, "receiptDigest": canonical_digest(body)}
+
+
+def _profile_summary(profile: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "status": profile.get("status"),
+        "reason": profile.get("reason"),
+        "source": "adapter.descriptor.json",
+        "shell": False,
+        "writesNativeConfig": bool(profile.get("writesNativeConfig", False)),
+        "promptInjectionDefault": bool(profile.get("promptInjectionDefault", False)),
+    }

agent_lifecycle/adapter_sessions/env.py

@@ -0,0 +1,44 @@
+"""Allowlisted environment resolution for managed adapter launches."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+from pathlib import Path
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, read_json_object
+from agent_lifecycle.adapter_sessions.redaction import redact_env_names
+
+
+def resolve_launch_env(
+    profile: dict[str, Any],
+    *,
+    policy_path: Path | None = None,
+    process_env: dict[str, str] | None = None,
+) -> tuple[dict[str, str], dict[str, Any]]:
+    """Return only allowlisted environment values and a redacted receipt view."""
+
+    env_policy = profile.get("env", {}) if isinstance(profile.get("env"), dict) else {}
+    names = set(_strings(env_policy.get("allow")))
+    patterns = set(_strings(env_policy.get("allowPatterns")))
+    if policy_path is not None:
+        if not env_policy.get("projectPolicyAllowed", False):
+            raise LifecycleError("adapter-env-policy-not-allowed", "descriptor does not allow project env policy extension")
+        policy = read_json_object(policy_path, label="adapter env policy")
+        names.update(_strings(policy.get("allow")))
+        patterns.update(_strings(policy.get("allowPatterns")))
+    source = dict(os.environ if process_env is None else process_env)
+    selected: dict[str, str] = {}
+    for name, value in source.items():
+        if name in names or any(fnmatch.fnmatchcase(name, pattern) for pattern in patterns):
+            selected[name] = value
+    return selected, redact_env_names(list(selected))
+
+
+def _strings(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if not isinstance(value, list) or not all(isinstance(item, str) and item for item in value):
+        raise LifecycleError("adapter-env-policy-invalid", "env policy entries must be non-empty strings")
+    return value

agent_lifecycle/adapter_sessions/launcher.py

@@ -0,0 +1,101 @@
+"""Descriptor-driven managed adapter launcher."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from agent_lifecycle.adapter_sessions.contracts import build_launch_receipt
+from agent_lifecycle.adapter_sessions.env import resolve_launch_env
+from agent_lifecycle.adapter_sessions.process import run_process
+from agent_lifecycle.contracts import LifecycleError, read_json_object
+
+
+def load_adapter_descriptor(adapter_id: str, descriptor_path: Path | None = None) -> tuple[Path, dict[str, Any]]:
+    path = descriptor_path or Path("adapters") / adapter_id / "adapter.descriptor.json"
+    descriptor = read_json_object(path, label="adapter descriptor")
+    if descriptor.get("adapterId") != adapter_id:
+        raise LifecycleError("adapter-descriptor-id-mismatch", "descriptor adapterId does not match requested adapter")
+    return path, descriptor
+
+
+def managed_launch_profile(descriptor: dict[str, Any]) -> dict[str, Any]:
+    profile = descriptor.get("managedLaunch")
+    if not isinstance(profile, dict):
+        raise LifecycleError("adapter-managed-launch-missing", "adapter descriptor must declare managedLaunch")
+    return profile
+
+
+def launch_from_descriptor(
+    *,
+    descriptor: dict[str, Any],
+    session_id: str,
+    launch_mode: str,
+    task_id: str | None = None,
+    state_path: Path | None = None,
+    policy_path: Path | None = None,
+    process_env: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    profile = managed_launch_profile(descriptor)
+    adapter_id = descriptor["adapterId"]
+    timeout_seconds = float(profile.get("timeoutSeconds", 30.0))
+    status = profile.get("status")
+    if status != "SUPPORTED":
+        reason = profile.get("reason") or f"managed launch profile is {status}"
+        return build_launch_receipt(
+            status="BLOCKED",
+            adapter_id=adapter_id,
+            session_id=session_id,
+            launch_mode=launch_mode,
+            argv=[],
+            timeout_seconds=timeout_seconds,
+            env={"includedNames": [], "valuesRedacted": True, "secretValuesStored": False},
+            exit_code=None,
+            timed_out=False,
+            blockers=[{"code": "adapter-managed-launch-unsupported", "profileStatus": status, "reason": reason}],
+        )
+    argv = _resolve_argv(profile, launch_mode=launch_mode, task_id=task_id, state_path=state_path)
+    env, env_receipt = resolve_launch_env(profile, policy_path=policy_path, process_env=process_env)
+    result = run_process(argv, env=env, timeout_seconds=timeout_seconds)
+    return build_launch_receipt(
+        status=result["status"],
+        adapter_id=adapter_id,
+        session_id=session_id,
+        launch_mode=launch_mode,
+        argv=argv,
+        timeout_seconds=timeout_seconds,
+        env=env_receipt,
+        exit_code=result["exitCode"],
+        timed_out=result["timedOut"],
+        stdout_tail=result["stdoutTail"],
+        stderr_tail=result["stderrTail"],
+        host_launch_started=True,
+        blockers=result["blockers"],
+    )
+
+
+def _resolve_argv(
+    profile: dict[str, Any],
+    *,
+    launch_mode: str,
+    task_id: str | None,
+    state_path: Path | None,
+) -> list[str]:
+    templates = profile.get("argvTemplates")
+    if not isinstance(templates, dict):
+        raise LifecycleError("adapter-managed-launch-argv-missing", "managed launch profile needs argvTemplates")
+    raw = templates.get(launch_mode)
+    if not isinstance(raw, list) or not all(isinstance(item, str) and item for item in raw):
+        raise LifecycleError("adapter-managed-launch-argv-invalid", f"argv template missing for {launch_mode}")
+    values = {
+        "taskId": task_id or "",
+        "state": state_path.as_posix() if state_path else "",
+    }
+    return [_render_template(item, values) for item in raw]
+
+
+def _render_template(value: str, values: dict[str, str]) -> str:
+    rendered = value
+    for key, replacement in values.items():
+        rendered = rendered.replace("{{" + key + "}}", replacement)
+    return rendered

agent_lifecycle/adapter_sessions/process.py

@@ -0,0 +1,39 @@
+"""Secure process execution for managed adapter sessions."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Any
+
+from agent_lifecycle.adapter_sessions.redaction import redact_text
+
+
+def run_process(argv: list[str], *, env: dict[str, str], timeout_seconds: float) -> dict[str, Any]:
+    try:
+        result = subprocess.run(
+            argv,
+            shell=False,
+            env=env,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=timeout_seconds,
+            check=False,
+        )
+        return {
+            "status": "PASS" if result.returncode == 0 else "FAIL",
+            "exitCode": result.returncode,
+            "timedOut": False,
+            "stdoutTail": redact_text(result.stdout[-2000:]),
+            "stderrTail": redact_text(result.stderr[-2000:]),
+            "blockers": [] if result.returncode == 0 else [{"code": "adapter-process-nonzero-exit", "exitCode": result.returncode}],
+        }
+    except subprocess.TimeoutExpired as exc:
+        return {
+            "status": "FAIL",
+            "exitCode": None,
+            "timedOut": True,
+            "stdoutTail": redact_text((exc.stdout or "")[-2000:] if isinstance(exc.stdout, str) else ""),
+            "stderrTail": redact_text((exc.stderr or "")[-2000:] if isinstance(exc.stderr, str) else ""),
+            "blockers": [{"code": "adapter-process-timeout", "timeoutSeconds": timeout_seconds}],
+        }

agent_lifecycle/adapter_sessions/redaction.py

@@ -0,0 +1,30 @@
+"""Redaction helpers for adapter session receipts."""
+
+from __future__ import annotations
+
+SENSITIVE_MARKERS = ("KEY", "TOKEN", "SECRET", "PASSWORD", "CREDENTIAL")
+
+
+def redact_env_names(names: list[str]) -> dict[str, object]:
+    return {
+        "includedNames": sorted(set(names)),
+        "valuesRedacted": True,
+        "secretValuesStored": False,
+    }
+
+
+def redact_text(value: str) -> str:
+    text = value
+    for marker in SENSITIVE_MARKERS:
+        text = _redact_marker(text, marker)
+    return text
+
+
+def _redact_marker(text: str, marker: str) -> str:
+    words = []
+    for word in text.split():
+        if marker in word.upper() and "=" in word:
+            words.append(word.split("=", 1)[0] + "=<redacted>")
+        else:
+            words.append(word)
+    return " ".join(words)

agent_lifecycle/adapter_sessions/session_store.py

@@ -0,0 +1,64 @@
+"""Filesystem store for managed adapter sessions."""
+
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_bytes, read_json_object, write_json_create
+
+DEFAULT_SESSION_ROOT = ".alk/adapter-sessions"
+
+
+def session_path(session_id: str, *, session_root: Path | None = None) -> Path:
+    if not session_id or "/" in session_id or "\\" in session_id or session_id in {".", ".."}:
+        raise LifecycleError("adapter-session-id-invalid", "session id is invalid")
+    root = session_root or Path(DEFAULT_SESSION_ROOT)
+    path = root / f"{session_id}.json"
+    resolved_root = root.resolve()
+    resolved_path = path.resolve()
+    if not resolved_path.is_relative_to(resolved_root):
+        raise LifecycleError("adapter-session-path-escape", "session path escapes session root")
+    return path
+
+
+def create_session(
+    *,
+    adapter_id: str,
+    mode: str,
+    status: str,
+    launch_profile: dict[str, Any],
+    session_root: Path | None = None,
+    state_identity: dict[str, Any] | None = None,
+    managed_workflow_proof: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    session_id = uuid.uuid4().hex
+    session = {
+        "schemaVersion": "agent-adapter-session-state.v1",
+        "sessionId": session_id,
+        "adapterId": adapter_id,
+        "mode": mode,
+        "status": status,
+        "launchProfile": {
+            "status": launch_profile.get("status"),
+            "reason": launch_profile.get("reason"),
+        },
+        "stateIdentity": state_identity,
+        "managedWorkflowProof": managed_workflow_proof,
+        "secretValuesStored": False,
+        "nativeConfigWritten": False,
+    }
+    write_json_create(session_path(session_id, session_root=session_root), session)
+    return session
+
+
+def load_session(session_id: str, *, session_root: Path | None = None) -> dict[str, Any]:
+    return read_json_object(session_path(session_id, session_root=session_root), label="adapter session")
+
+
+def update_session(session: dict[str, Any], *, session_root: Path | None = None) -> dict[str, Any]:
+    path = session_path(session["sessionId"], session_root=session_root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(canonical_bytes(session) + b"\n")
+    return session