agent-lifecycle-kit 2.47.0__tar.gz → 2.48.0__tar.gz

{agent_lifecycle_kit-2.47.0/src/agent_lifecycle_kit.egg-info → agent_lifecycle_kit-2.48.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle-kit
-Version: 2.47.0
+Version: 2.48.0
 Summary: Provider-neutral lifecycle control layer that helps coding agents plan, execute, validate, and prove software tasks to completion.
 Author: Agent Lifecycle Kit contributors
 License: Apache-2.0
@@ -42,7 +42,7 @@ Release 2.28 adds [bounded lifecycle and accounting baselines](docs/reference/pe
 ## Quick start
 Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.23 adds [compact S0/S1 authoring](docs/reference/tier-proportional-plan-packages.md) with explicit checklist completion and unchanged approval gates. Release 2.22 adds [conservative plan-review reuse](docs/reference/conservative-delta-review.md) with independent current applicability and no automatic full reruns. Release 2.21 adds [command accounting, bounded preparation and response recovery](docs/reference/source-native-workflow-accounting.md). Release 2.20 adds [target-bound initialization](docs/reference/cli.md#release-220-composed-initialization-and-digest-display), [bounded local continuation](docs/reference/workflow-continuation.md) and batched Git snapshots. Release 2.19 adds [safe artifact authoring and planning preflight](docs/reference/safe-artifact-authoring.md), [bounded review handoff](docs/reference/review-mesh.md#bounded-review-handoff) and thin skills with complete references. Release 2.18 bounds process/Git diagnostics, hardens signing and distinguishes OpenCode 1.x/2.x compatibility ([adapter notes](docs/adapters/opencode.md)); 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
 
-It includes macOS, Linux and Windows instructions, Python 3.11-3.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.47.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
+It includes macOS, Linux and Windows instructions, Python 3.11-3.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.48.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
 
 For a quick start, run:
 
@@ -188,7 +188,7 @@ Adapter installation and support-level details live in [Adapter install](docs/ad
 ## Documentation
 
 - Start: [English documentation](docs/README.md), [Русская документация](docs/ru/README.md), [Install](docs/guides/install-and-first-run.md), [Quickstart](docs/guides/quickstart.md), [Beginner and advanced workflows](docs/guides/beginner-and-advanced-workflows.md), [Commands by task](docs/guides/commands-by-task.md), [Research workflow](docs/guides/research-workflow.md), [Lifecycle task scenarios](docs/guides/lifecycle-cookbook.md), and [Code review workflows](docs/guides/code-review-workflows.md).
-- Planning and adapters: [Issue to specification drafts](docs/guides/issue-to-spec.md), [Adapter install](docs/adapters/install.md), and [Adapter support matrix](docs/adapters/support-matrix.md).
+- Planning and adapters: [Bounded plugin updates](docs/reference/plugin-updates.md), [Issue to specification drafts](docs/guides/issue-to-spec.md), [Adapter install](docs/adapters/install.md), and [Adapter support matrix](docs/adapters/support-matrix.md).
 - Reference: [System architecture](docs/architecture/system-architecture.md), [workflow customization and execution controls](docs/reference/workflow-customization.md), [guided workflow continuation](docs/reference/workflow-continuation.md), [execution strategy](docs/reference/execution-strategy.md), [CLI reference](docs/reference/cli.md), [External verification checks](docs/reference/external-verification-checks.md), [Bounded external tool jobs](docs/reference/external-tool-jobs.md), [Project domain language](docs/reference/project-domain-language.md), [Multi-run attention view](docs/reference/multi-run-attention-view.md), [Plan verification](docs/reference/plan-verification.md), [Research evidence](docs/reference/research-evidence.md), [Public locators and redaction](docs/reference/public-locators-and-redaction.md), [Finding-to-check adoption](docs/reference/finding-check-adoption.md), [Source of truth](docs/reference/source-of-truth.md), [Managed lifecycle runner](docs/reference/managed-lifecycle-runner.md), [Managed adapter sessions](docs/reference/managed-adapter-sessions.md), [Portable Agent Plugins](docs/reference/agent-plugins.md), [Plugin publication](docs/reference/plugin-publication.md), [Implementation audit](docs/reference/implementation-audit.md), [Plan completeness](docs/reference/plan-completeness.md), [Public contracts](docs/reference/public-contracts.md), and [Readiness diagnostics](docs/reference/readiness-diagnostics.md).
 - Quality and resources: [Reference-task evaluation](docs/reference/reference-task-evaluation.md), [model routing and optional ranking](docs/reference/model-routing.md), [quality-cost learning](docs/reference/quality-cost-learning.md), [review efficiency](docs/reference/review-efficiency.md), [evidence independence](docs/reference/evidence-independence.md), [performance and resource budgets](docs/reference/performance-and-resource-budgets.md), [lifecycle cost accounting](docs/reference/lifecycle-cost.md), [host-local token accounting](docs/reference/host-local-token-accounting.md), [process execution observability](docs/reference/process-execution-observability.md), [Usage export](docs/reference/usage-export.md), and [Evidence integrity](docs/reference/evidence-integrity.md).
 - Profiles and operations: [Project workflow presets](docs/reference/workflow-presets.md), [Project workflow profile](docs/reference/project-workflow-profile.md), [Read-only status views](docs/reference/read-only-status-view.md), [Adapter progress bridge](docs/reference/automatic-progress-bridge.md), [Sandbox boundaries](docs/reference/sandbox-boundaries.md), [Import mappers](docs/reference/import-mappers.md), [Episode retrieval](docs/reference/episode-retrieval.md), [Runner migration](docs/guides/runner-migration-2.md), [Runner recovery records](docs/reference/runner-recovery.md), [Cross-check profile](docs/reference/cross-check-profile.md), [Review Mesh](docs/reference/review-mesh.md), [Risk-bound independent verification](docs/reference/risk-bound-independent-verification.md), [Bug Forensics profile](docs/reference/bug-forensics.md), and [Bug Forensics context budget](docs/reference/bug-forensics-context-budget.md).

{agent_lifecycle_kit-2.47.0 → agent_lifecycle_kit-2.48.0}/README.md

@@ -19,7 +19,7 @@ Release 2.28 adds [bounded lifecycle and accounting baselines](docs/reference/pe
 ## Quick start
 Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.23 adds [compact S0/S1 authoring](docs/reference/tier-proportional-plan-packages.md) with explicit checklist completion and unchanged approval gates. Release 2.22 adds [conservative plan-review reuse](docs/reference/conservative-delta-review.md) with independent current applicability and no automatic full reruns. Release 2.21 adds [command accounting, bounded preparation and response recovery](docs/reference/source-native-workflow-accounting.md). Release 2.20 adds [target-bound initialization](docs/reference/cli.md#release-220-composed-initialization-and-digest-display), [bounded local continuation](docs/reference/workflow-continuation.md) and batched Git snapshots. Release 2.19 adds [safe artifact authoring and planning preflight](docs/reference/safe-artifact-authoring.md), [bounded review handoff](docs/reference/review-mesh.md#bounded-review-handoff) and thin skills with complete references. Release 2.18 bounds process/Git diagnostics, hardens signing and distinguishes OpenCode 1.x/2.x compatibility ([adapter notes](docs/adapters/opencode.md)); 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
 
-It includes macOS, Linux and Windows instructions, Python 3.11-3.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.47.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
+It includes macOS, Linux and Windows instructions, Python 3.11-3.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.48.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
 
 For a quick start, run:
 
@@ -165,7 +165,7 @@ Adapter installation and support-level details live in [Adapter install](docs/ad
 ## Documentation
 
 - Start: [English documentation](docs/README.md), [Русская документация](docs/ru/README.md), [Install](docs/guides/install-and-first-run.md), [Quickstart](docs/guides/quickstart.md), [Beginner and advanced workflows](docs/guides/beginner-and-advanced-workflows.md), [Commands by task](docs/guides/commands-by-task.md), [Research workflow](docs/guides/research-workflow.md), [Lifecycle task scenarios](docs/guides/lifecycle-cookbook.md), and [Code review workflows](docs/guides/code-review-workflows.md).
-- Planning and adapters: [Issue to specification drafts](docs/guides/issue-to-spec.md), [Adapter install](docs/adapters/install.md), and [Adapter support matrix](docs/adapters/support-matrix.md).
+- Planning and adapters: [Bounded plugin updates](docs/reference/plugin-updates.md), [Issue to specification drafts](docs/guides/issue-to-spec.md), [Adapter install](docs/adapters/install.md), and [Adapter support matrix](docs/adapters/support-matrix.md).
 - Reference: [System architecture](docs/architecture/system-architecture.md), [workflow customization and execution controls](docs/reference/workflow-customization.md), [guided workflow continuation](docs/reference/workflow-continuation.md), [execution strategy](docs/reference/execution-strategy.md), [CLI reference](docs/reference/cli.md), [External verification checks](docs/reference/external-verification-checks.md), [Bounded external tool jobs](docs/reference/external-tool-jobs.md), [Project domain language](docs/reference/project-domain-language.md), [Multi-run attention view](docs/reference/multi-run-attention-view.md), [Plan verification](docs/reference/plan-verification.md), [Research evidence](docs/reference/research-evidence.md), [Public locators and redaction](docs/reference/public-locators-and-redaction.md), [Finding-to-check adoption](docs/reference/finding-check-adoption.md), [Source of truth](docs/reference/source-of-truth.md), [Managed lifecycle runner](docs/reference/managed-lifecycle-runner.md), [Managed adapter sessions](docs/reference/managed-adapter-sessions.md), [Portable Agent Plugins](docs/reference/agent-plugins.md), [Plugin publication](docs/reference/plugin-publication.md), [Implementation audit](docs/reference/implementation-audit.md), [Plan completeness](docs/reference/plan-completeness.md), [Public contracts](docs/reference/public-contracts.md), and [Readiness diagnostics](docs/reference/readiness-diagnostics.md).
 - Quality and resources: [Reference-task evaluation](docs/reference/reference-task-evaluation.md), [model routing and optional ranking](docs/reference/model-routing.md), [quality-cost learning](docs/reference/quality-cost-learning.md), [review efficiency](docs/reference/review-efficiency.md), [evidence independence](docs/reference/evidence-independence.md), [performance and resource budgets](docs/reference/performance-and-resource-budgets.md), [lifecycle cost accounting](docs/reference/lifecycle-cost.md), [host-local token accounting](docs/reference/host-local-token-accounting.md), [process execution observability](docs/reference/process-execution-observability.md), [Usage export](docs/reference/usage-export.md), and [Evidence integrity](docs/reference/evidence-integrity.md).
 - Profiles and operations: [Project workflow presets](docs/reference/workflow-presets.md), [Project workflow profile](docs/reference/project-workflow-profile.md), [Read-only status views](docs/reference/read-only-status-view.md), [Adapter progress bridge](docs/reference/automatic-progress-bridge.md), [Sandbox boundaries](docs/reference/sandbox-boundaries.md), [Import mappers](docs/reference/import-mappers.md), [Episode retrieval](docs/reference/episode-retrieval.md), [Runner migration](docs/guides/runner-migration-2.md), [Runner recovery records](docs/reference/runner-recovery.md), [Cross-check profile](docs/reference/cross-check-profile.md), [Review Mesh](docs/reference/review-mesh.md), [Risk-bound independent verification](docs/reference/risk-bound-independent-verification.md), [Bug Forensics profile](docs/reference/bug-forensics.md), and [Bug Forensics context budget](docs/reference/bug-forensics-context-budget.md).

{agent_lifecycle_kit-2.47.0 → agent_lifecycle_kit-2.48.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-lifecycle-kit"
-version = "2.47.0"
+version = "2.48.0"
 description = "Provider-neutral lifecycle control layer that helps coding agents plan, execute, validate, and prove software tasks to completion."
 readme = "README.md"
 requires-python = ">=3.11,<3.16"
@@ -56,7 +56,7 @@ agent-lifecycle-neutrality = "agent_lifecycle.neutrality.cli:main"
 where = ["src"]
 
 [tool.setuptools.package-data]
-agent_lifecycle = ["py.typed", "data/profiles/**/*.json"]
+agent_lifecycle = ["py.typed", "data/profiles/**/*.json", "data/plugin-updates/*.json"]
 
 [tool.ruff]
 target-version = "py311"

{agent_lifecycle_kit-2.47.0 → agent_lifecycle_kit-2.48.0}/src/agent_lifecycle/_version.py

@@ -1,3 +1,3 @@
 """Package version."""
 
-__version__ = "2.47.0"
+__version__ = "2.48.0"

agent_lifecycle_kit-2.48.0/src/agent_lifecycle/adapter_sessions/plugin_updates.py

@@ -0,0 +1,223 @@
+"""Host-neutral advice and explicit refusal; no native update dispatch."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+from agent_lifecycle.contracts import canonical_digest, sha256_hex
+from agent_lifecycle.contracts.paths import normalize_repo_path, read_stable_repository_file
+from agent_lifecycle.contracts.plugin_update_schemas import UPDATE_SOURCE
+from agent_lifecycle.contracts.plugin_update_validation import (
+    MAX_PLAN_INPUT_BYTES,
+    MAX_UPDATE_BYTES,
+    require_update,
+    update_digest,
+    update_object,
+    update_report,
+    update_version,
+    validate_update_report,
+    validate_update_request,
+)
+from agent_lifecycle.diagnostics.plugin_updates import observe_update_identities
+
+
+def _assessment_subjects(assessment: dict[str, Any]) -> tuple[dict[str, str], list[dict[str, Any]]]:
+    plans = assessment["details"].get("plans")
+    require_update(isinstance(plans, list) and 0 < len(plans) <= 32, "offer needs1..32 assessed plans")
+    plans = cast(list[dict[str, Any]], plans)
+    subjects: dict[str, str] = {}
+    for plan in plans:
+        require_update(
+            isinstance(plan, dict) and plan.get("structuralResult") == "PASS",
+            "offer requires structurally verified plans",
+        )
+        hashes = plan.get("inputSHA256")
+        require_update(isinstance(hashes, dict) and 0 < len(hashes) <= 64, "offer input file cap64")
+        hashes = cast(dict[str, str], hashes)
+        require_update(
+            isinstance(plan.get("manifest"), str) and plan["manifest"] in hashes,
+            "assessed manifest must have an exact input hash",
+        )
+        require_update(isinstance(plan.get("lifecycle"), dict), "assessed lifecycle unavailable")
+        for path, digest in hashes.items():
+            normalized = normalize_repo_path(path)
+            update_digest(digest)
+            require_update(
+                normalized not in subjects or subjects[normalized] == digest, "conflicting assessed file identity"
+            )
+            subjects[normalized] = digest
+    return subjects, plans
+
+
+def _recheck_subjects(root: Path, subjects: dict[str, str]) -> None:
+    remaining = MAX_PLAN_INPUT_BYTES
+    for path, digest in subjects.items():
+        require_update(remaining > 0, "offer aggregate input cap8MiB")
+        body = read_stable_repository_file(root, path, max_bytes=min(MAX_UPDATE_BYTES, remaining))
+        remaining -= len(body)
+        require_update(sha256_hex(body) == digest, "assessment became stale; reassess changed input")
+
+
+def _target(request: dict[str, Any], assessment: dict[str, Any]) -> dict[str, Any]:
+    target = update_object(
+        assessment["details"].get("target"), {"version", "sourceCommit"}, {"version", "sourceCommit"}
+    )
+    version = update_version(target.get("version"))
+    commit = target["sourceCommit"]
+    if commit is not None:
+        update_digest(commit, 40)
+    require_update(request.get("targetVersion", version) == version, "offer target differs from request")
+    require_update(request.get("pin") in (None, "v" + version), "offer differs from immutable pin")
+    require_update(
+        commit is None or request.get("trustedTargetCommit", commit) == commit, "offer commit differs from request"
+    )
+    require_update(
+        request.get("channel", "stable") == "prerelease" or "-" not in version, "offer prerelease is not opted in"
+    )
+    return {"version": version, "sourceCommit": commit, "source": UPDATE_SOURCE}
+
+
+def _manual_codex_commands(version: str) -> list[list[str]]:
+    # Inert native CLI shapes, not a transaction, qualification or permission.
+    return [
+        ["codex", "plugin", "marketplace", "remove", "agent-lifecycle-kit"],
+        ["codex", "plugin", "marketplace", "add", UPDATE_SOURCE + ".git", "--ref", "v" + version, "--json"],
+        ["codex", "plugin", "add", "agent-lifecycle-kit@agent-lifecycle-kit", "--json"],
+        ["codex", "plugin", "list", "--marketplace", "agent-lifecycle-kit", "--json"],
+    ]
+
+
+def offer_plugin_update(
+    request: dict[str, Any], assessment: dict[str, Any], *, repository_root: Path
+) -> dict[str, Any]:
+    """Recheck declared subjects, then show inert operator advice or defer."""
+    validate_update_request(request)
+    mode = request.get("mode", "manual")
+    if mode == "off":
+        return update_report("offer", "OFF", request, {"hostDispatch": False, "networkRequests": 0})
+    if mode in ("safe-auto", "notify"):
+        return update_report(
+            "offer",
+            "UNSUPPORTED",
+            request,
+            {"reason": "No qualified automatic update/notification boundary", "hostDispatch": False},
+        )
+    host = request.get("host", {})
+    if host.get("adapterId") != "codex" or not host.get("version"):
+        return update_report(
+            "offer",
+            "UNSUPPORTED",
+            request,
+            {
+                "reason": "No documented manual native shape mapped for this declared host",
+                "hostDispatch": False,
+                "installationEligibility": "UNQUALIFIED",
+            },
+        )
+    validate_update_report(assessment)
+    require_update(
+        assessment["action"] == "assess"
+        and assessment["status"] == "ASSESSED"
+        and assessment["details"].get("assessmentComplete") is True,
+        "offer needs a complete explicit assessment",
+    )
+    require_update(assessment["requestDigest"] == canonical_digest(request), "assessment policy changed")
+    target = _target(request, assessment)
+    if target["sourceCommit"] is None:
+        return update_report(
+            "offer",
+            "UNKNOWN",
+            request,
+            {
+                "reason": "TARGET_COMMIT_UNRESOLVED: bind a separately observed exact commit before offering commands",
+                "target": target,
+                "assessmentTrust": "DECLARED_LOCAL_REPORT_NOT_AUTHORITY",
+                "installationEligibility": "UNQUALIFIED",
+                "hostDispatch": False,
+            },
+            {"assessmentDigest": canonical_digest(assessment)},
+        )
+    subjects, plans = _assessment_subjects(assessment)
+    _recheck_subjects(repository_root, subjects)
+    deferred = [plan.get("lifecycle", {}).get("action") for plan in plans]
+    if any(action not in ("PROPOSE_UNAPPLIED_EDITS_AND_REVIEW", "PRESERVE_IMMUTABLE_HISTORY") for action in deferred):
+        return update_report(
+            "offer",
+            "UNKNOWN",
+            request,
+            {
+                "reason": "DEFER_ACTIVATION: active or unqualified state boundary",
+                "target": target,
+                "installationEligibility": "UNQUALIFIED",
+                "hostDispatch": False,
+            },
+            {"assessmentDigest": canonical_digest(assessment)},
+        )
+    return update_report(
+        "offer",
+        "OFFERED",
+        request,
+        {
+            "target": target,
+            "host": host,
+            "hostIdentityProvenance": "DECLARED",
+            "commands": _manual_codex_commands(target["version"]),
+            "commandStatus": "INERT_OPERATOR_RECIPE_NOT_QUALIFIED_EXECUTION",
+            "assessmentTrust": "DECLARED_LOCAL_REPORT_NOT_AUTHORITY",
+            "installationEligibility": "UNQUALIFIED",
+            "hostDispatch": False,
+            "globalEffectScope": "UNKNOWN_BEYOND_EXPLICIT_INVENTORY",
+            "upstreamTagRecheckRequired": True,
+            "separateNativePermissionRequired": True,
+            "activation": "RESTART_AND_OBSERVE_SEPARATELY",
+            "recovery": "UNKNOWN_NO_BLIND_RETRY_OR_CACHE_RETENTION_PROMISE",
+            "planGaps": [plan.get("gaps", []) for plan in plans],
+            "assessedFilesRechecked": len(subjects),
+            "compatibilityGuarantee": "NONE; manual recipe is not an install recommendation",
+        },
+        {"assessmentDigest": canonical_digest(assessment)},
+    )
+
+
+def refuse_plugin_install(request: dict[str, Any], offer: dict[str, Any]) -> dict[str, Any]:
+    """No current host operation is qualified; never try a generic launcher."""
+    validate_update_request(request)
+    if request.get("mode") == "off":
+        return update_report("install", "OFF", request, {"hostDispatch": False})
+    validate_update_report(offer)
+    require_update(offer["action"] == "offer", "installation input is not an offer")
+    require_update(offer["requestDigest"] == canonical_digest(request), "offer policy changed")
+    return update_report(
+        "install",
+        "UNSUPPORTED",
+        request,
+        {
+            "reason": "NATIVE_INSTALL_UNQUALIFIED",
+            "hostDispatch": False,
+            "safeAutoSupported": False,
+            "scopeQualification": "UNAVAILABLE",
+            "activation": "NOT_PERFORMED",
+            "retry": "NONE",
+            "nextAction": "Use separately authorized host-owned procedure; reconcile any external effect",
+        },
+        {"offerDigest": canonical_digest(offer)},
+    )
+
+
+def reconcile_plugin_update(request: dict[str, Any]) -> dict[str, Any]:
+    identities = observe_update_identities(request)
+    status = "DRIFT" if identities["labelComparison"] == "DRIFT" else "UNKNOWN"
+    return update_report(
+        "reconcile",
+        status,
+        request,
+        {
+            "identities": identities,
+            "hostDispatch": False,
+            "activation": "NOT_ATTESTED_BY_CALLER_LABELS",
+            "planMutation": False,
+            "retry": "NONE",
+            "nextAction": "Preserve active authority and qualify loaded instructions/runtime before continuing",
+        },
+    )

{agent_lifecycle_kit-2.47.0 → agent_lifecycle_kit-2.48.0}/src/agent_lifecycle/cli/command_registry.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 COMMAND_DISPATCH = {
+    "plugin-update": ("agent_lifecycle.cli.plugin_updates", "dispatch_plugin_updates", False),
     "start": ("agent_lifecycle.cli.start", "dispatch_start", True),
     "host-launch": ("agent_lifecycle.cli.host_launch", "dispatch_host_launch", False),
     "strategy": ("agent_lifecycle.cli.strategy", "dispatch_strategy", False),

{agent_lifecycle_kit-2.47.0 → agent_lifecycle_kit-2.48.0}/src/agent_lifecycle/cli/dispatch.py

@@ -41,6 +41,10 @@ def dispatch_research(args: argparse.Namespace) -> dict[str, Any] | str | None:
     return _lazy_call("agent_lifecycle.cli.dispatch_research", "dispatch_research", args)
 
 
+def dispatch_plugin_updates(args: argparse.Namespace) -> dict[str, Any] | str | None:
+    return _lazy_call("agent_lifecycle.cli.plugin_updates", "dispatch_plugin_updates", args)
+
+
 def dispatch_contracts(args: argparse.Namespace) -> dict[str, Any] | str | None:
     return _lazy_call("agent_lifecycle.cli.dispatch_contracts", "dispatch_contracts", args)
 

{agent_lifecycle_kit-2.47.0 → agent_lifecycle_kit-2.48.0}/src/agent_lifecycle/cli/parsers.py

@@ -26,6 +26,7 @@ def build_parser(argv: list[str] | None = None) -> argparse.ArgumentParser:
     from agent_lifecycle.cli.metrics_parser import add_metrics_parser
     from agent_lifecycle.cli.observability_parsers import _add_report_parser
     from agent_lifecycle.cli.planning_parsers import _add_plan_parser, _add_task_parser
+    from agent_lifecycle.cli.plugin_updates import add_plugin_update_parser
     from agent_lifecycle.cli.policy import add_policy_parser
     from agent_lifecycle.cli.research import add_research_parser
     from agent_lifecycle.cli.worktree import add_worktree_parser
@@ -50,6 +51,7 @@ def build_parser(argv: list[str] | None = None) -> argparse.ArgumentParser:
     _add_strategy_parser(subparsers)
     _add_report_parser(subparsers)
     add_policy_parser(subparsers)
+    add_plugin_update_parser(subparsers)
     _add_workflow_parser(subparsers)
     _add_audit_parser(subparsers)
     _add_context_parser(subparsers)

agent_lifecycle_kit-2.48.0/src/agent_lifecycle/cli/plugin_updates.py

@@ -0,0 +1,140 @@
+"""Bounded advisory plugin-update CLI; no native installation authority."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_bytes
+from agent_lifecycle.contracts.authority_io import create_authority_bytes
+from agent_lifecycle.contracts.paths import normalize_repo_path
+from agent_lifecycle.contracts.plugin_update_validation import (
+    MAX_UPDATE_BYTES,
+    UPDATE_FORBIDDEN_ROOTS,
+    read_update_json,
+    require_update,
+    validate_plan_inventory,
+    validate_update_report,
+    validate_update_request,
+)
+
+
+def add_plugin_update_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    group = subparsers.add_parser("plugin-update", help="bounded plugin discovery and read-only plan advice")
+    actions = group.add_subparsers(dest="plugin_update_command", required=True)
+    for action in ("check", "assess", "offer", "install", "reconcile"):
+        parser = actions.add_parser(action)
+        parser.add_argument("--request", required=True)
+        parser.add_argument("--out")
+        if action == "check":
+            parser.add_argument("--cache")
+        elif action == "assess":
+            parser.add_argument("--release", required=True)
+            parser.add_argument("--inventory", required=True)
+            parser.add_argument("--repository-root", default=".")
+        elif action == "offer":
+            parser.add_argument("--assessment", required=True)
+        elif action == "install":
+            parser.add_argument("--offer", required=True)
+
+
+def _protected_path(name: str, inputs: set[str]) -> str:
+    name = normalize_repo_path(name)
+    require_update(name not in inputs, "output/cache aliases an input")
+    require_update(name.split("/")[0].casefold() not in UPDATE_FORBIDDEN_ROOTS, "unsafe output scope")
+    require_update(
+        not name.casefold().endswith((".state.json", ".lock.json", "plan.manifest.json")),
+        "output cannot use authority filename",
+    )
+    return name
+
+
+def _output_preflight(root: Path, output: str | None, inputs: set[str]) -> str | None:
+    if output is None:
+        return None
+    name = _protected_path(output, inputs)
+    path = root / name
+    require_update(not path.exists() and not path.is_symlink(), "output already exists")
+    parent = path.parent
+    while parent != root:
+        require_update(not parent.is_symlink(), "output parent is a symlink")
+        parent = parent.parent
+    return name
+
+
+def _subject_inputs(action: str, data: dict[str, Any]) -> set[str]:
+    subjects: set[str] = set()
+    if action == "assess":
+        for item in data.get("plans", []):
+            if isinstance(item, dict):
+                subjects.update(normalize_repo_path(path) for path in item.values() if isinstance(path, str))
+    elif action == "offer":
+        plans = data["details"].get("plans", [])
+        require_update(isinstance(plans, list) and len(plans) <= 32, "invalid assessment plan count")
+        for item in plans:
+            if isinstance(item, dict) and isinstance(item.get("inputSHA256"), dict):
+                subjects.update(normalize_repo_path(path) for path in item["inputSHA256"])
+    return subjects
+
+
+def _write_update_report(root: Path, output: str | None, payload: dict[str, Any]) -> None:
+    validate_update_report(payload)
+    body = canonical_bytes(payload) + b"\n"
+    require_update(len(body) <= MAX_UPDATE_BYTES, "update output exceeds256KiB")
+    if output is not None:
+        require_update(
+            payload["action"] != "assess" or payload["details"].get("assessmentComplete") is True,
+            "incomplete assessment cannot write --out; omit --out for its diagnostic report",
+            code="plugin-update-incomplete-assessment-output",
+        )
+        create_authority_bytes(root / output, body, root=root, private=True)
+
+
+def dispatch_plugin_updates(args: argparse.Namespace) -> dict[str, Any]:
+    from agent_lifecycle.adapter_sessions.plugin_updates import (
+        offer_plugin_update,
+        reconcile_plugin_update,
+        refuse_plugin_install,
+    )
+    from agent_lifecycle.diagnostics.plugin_updates import check_plugin_updates, store_update_cache
+    from agent_lifecycle.planning.update_impact import assess_plugin_update
+
+    action = args.plugin_update_command
+    root = Path(getattr(args, "repository_root", ".")).absolute()
+    fields = [key for key in ("request", "release", "inventory", "assessment", "offer") if hasattr(args, key)]
+    names = {key: normalize_repo_path(getattr(args, key)) for key in fields}
+    inputs = set(names.values())
+    cache_name = getattr(args, "cache", None)
+    if cache_name:
+        cache_name = _protected_path(cache_name, inputs)
+        inputs.add(cache_name)
+    output = _output_preflight(root, args.out, inputs)
+    data = {key: read_update_json(root, name) for key, name in names.items()}
+    request = validate_update_request(data["request"])
+    if action == "assess":
+        validate_plan_inventory(data["inventory"])
+    elif action in ("offer", "install"):
+        validate_update_report(data["assessment"] if action == "offer" else data["offer"])
+    inputs.update(_subject_inputs(action, data.get("inventory", data.get("assessment", {}))))
+    output = _output_preflight(root, output, inputs)
+    if action == "check":
+        reads_cache = request.get("mode", "manual") not in ("off", "notify", "safe-auto")
+        cache = (
+            read_update_json(root, cache_name) if reads_cache and cache_name and (root / cache_name).exists() else None
+        )
+        payload = check_plugin_updates(request, cache=cache)
+        if cache_name and payload["details"].get("cacheUpdated") is True:
+            store_update_cache(root, cache_name, payload["details"]["cache"], inputs=tuple(names.values()))
+    elif action == "assess":
+        payload = assess_plugin_update(request, data["release"], data["inventory"], repository_root=root)
+    elif action == "offer":
+        payload = offer_plugin_update(request, data["assessment"], repository_root=root)
+    elif action == "install":
+        payload = refuse_plugin_install(request, data["offer"])
+    elif action == "reconcile":
+        payload = reconcile_plugin_update(request)
+    else:
+        raise LifecycleError("command-not-implemented", "plugin-update action is not implemented")
+    _write_update_report(root, output, payload)
+    return payload