arbora 0.1.8.dev4__tar.gz → 0.1.8.dev5__tar.gz

{arbora-0.1.8.dev4 → arbora-0.1.8.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arbora
-Version: 0.1.8.dev4
+Version: 0.1.8.dev5
 Summary: The deployable MCP, REST, control-plane, fleet, WebUI, and operations composition for the Knuckles agent platform.
 Author-email: Repository Maintainers <maintainers@knuckles.team>
 License-Expression: MIT

{arbora-0.1.8.dev4 → arbora-0.1.8.dev5}/arbora/_version.py

@@ -3,4 +3,4 @@
 Updated only by `bump-my-version` (see `.bumpversion.toml`) — never hand-edited.
 """
 
-__version__ = "0.1.8.dev4"
+__version__ = "0.1.8.dev5"

{arbora-0.1.8.dev4 → arbora-0.1.8.dev5}/arbora/a2a/authority.py

@@ -1072,10 +1072,15 @@ class WorkItemA2AAuthority:
         return tasks, next_cursor
 
     async def cancel(self, task_id: str) -> A2ATask:
+        from arbora.run_origin import revoke_run_origins
+
+        cancellation_session = self._session("kg:write")
         item = await asyncio.to_thread(self._authorized_item, task_id, "kg:write")
         if item is None:
             raise A2ATaskNotCancelable("A2A task is not cancelable")
+        run_id = str(item["metadata"].get("a2a_run_id") or task_id)
         if item.get("status") == "cancelled":
+            revoke_run_origins(cancellation_session, run_id)
             return self._project(item, task_id=task_id)
         if item.get("status") in _TERMINAL:
             raise A2ATaskNotCancelable("A2A task is not cancelable")
@@ -1087,6 +1092,7 @@ class WorkItemA2AAuthority:
             work_items.cancel_work_item, work_engine, item_id
         ):
             raise A2ATaskNotCancelable("A2A task is not cancelable")
+        revoke_run_origins(cancellation_session, run_id)
         current = await asyncio.to_thread(
             work_items.get_work_item, work_engine, item_id
         )

{arbora-0.1.8.dev4 → arbora-0.1.8.dev5}/arbora/access/action_policy.py

@@ -52,7 +52,7 @@ import threading
 import time
 import uuid
 from collections.abc import Callable, Mapping
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from enum import StrEnum
 from pathlib import Path
 from typing import Any, ClassVar
@@ -612,6 +612,18 @@ class ActionPolicy:
             setting("ACTION_IRREVERSIBILITY_AVERSION", False, cast=bool)
         )
 
+    def qualified_source_revision(self) -> str:
+        """Read explicit source evidence; this revision grants no action."""
+        from arbora.access.action_policy_source import qualified_policy_source
+
+        return qualified_policy_source(self).revision
+
+    async def qualified_source_revision_async(self) -> str:
+        """Capture source evidence without switching the native client loop."""
+        from arbora.access.action_policy_source import qualified_policy_source_async
+
+        return (await qualified_policy_source_async(self)).revision
+
     # ── policy loading ──────────────────────────────────────────────
 
     def _load_file_policy(self) -> dict[str, Any]:
@@ -686,14 +698,22 @@ class ActionPolicy:
         rules.sort(key=lambda r: -r.priority)
         return rules
 
-    def _match(self, request: ActionRequest) -> tuple[ActionRule, dict[str, Any]]:
+    def _rule_inputs(self, source: Any) -> tuple[dict[str, Any], list[ActionRule]]:
+        """Select live policy inputs or the already captured qualified snapshot."""
+        if source is None:
+            return self._load_file_policy(), self._kg_rules()
+        return source.inputs()
+
+    def _match(
+        self, request: ActionRequest, *, source: Any = None
+    ) -> tuple[ActionRule, dict[str, Any]]:
         """First matching rule — KG overrides first, then file order — plus defaults."""
-        data = self._load_file_policy()
+        data, graph_rules = self._rule_inputs(source)
         raw_defaults = data.get("defaults")
         defaults: dict[str, Any] = (
             raw_defaults if isinstance(raw_defaults, dict) else {}
         )
-        for rule in self._kg_rules():
+        for rule in graph_rules:
             if rule.matches(request):
                 return rule, defaults
         for raw in data.get("rules") or []:
@@ -721,6 +741,13 @@ class ActionPolicy:
         if self.engine is None:
             return []
         try:
+            legacy = self.engine.query_cypher(
+                "MATCH (d {type: 'ActionDecision', kind: $kind}) "
+                "WHERE d.node_type IS NULL RETURN d.id AS id LIMIT 1",
+                {"kind": kind},
+            )
+            if legacy:
+                return None
             rows = self.engine.query_cypher(
                 "MATCH (d:ActionDecision {kind: $kind}) "
                 "RETURN d.id AS id, d.target AS target, d.decision AS decision, "
@@ -777,7 +804,7 @@ class ActionPolicy:
 
     # ── assurance verifier (CONCEPT:AU-OS.governance.assurance-state-machine-verifier) ──
 
-    def _verify(self, request: ActionRequest):
+    def _verify(self, request: ActionRequest, *, source: Any = None):
         """Run the deterministic invariant verifier for ``request``.
 
         The reference-existence check (invariant 4) is best-effort: it only
@@ -785,8 +812,14 @@ class ActionPolicy:
         ``known_tools``/``known_targets`` registries (empty/absent ⇒ skipped,
         never a false deny — CONCEPT:AU-OS.governance.fail-closed-claim-check).
         """
-        known_tools = self.option("known_tools")
-        known_targets = self.option("known_targets")
+        if source is None:
+            known_tools = self.option("known_tools")
+            known_targets = self.option("known_targets")
+        else:
+            document, _rules = source.inputs()
+            options = document.get("options") or {}
+            known_tools = options.get("known_tools")
+            known_targets = options.get("known_targets")
         return verify_action(
             request,
             known_tools=frozenset(known_tools) if known_tools else None,
@@ -930,6 +963,58 @@ class ActionPolicy:
                 reason=f"policy unavailable (fail closed): {e}",
                 rule_origin="unavailable",
             )
+        return self._finish_decision(decision)
+
+    def decide_qualified(
+        self, request: ActionRequest, *, expected_revision: str
+    ) -> ActionDecision:
+        """Evaluate one explicit source snapshot through the shared evaluator.
+
+        The exact request must bind its source revision. Source evidence is
+        rechecked after evaluation and audit, never inferred from shipped
+        defaults. The browser owner must still recheck after its own awaits.
+        """
+        from arbora.access.action_policy_source import qualified_policy_source
+
+        try:
+            digest = request.digest()
+            captured = replace(request, params=_canonical_policy_value(request.params))
+            source = qualified_policy_source(self)
+            if (
+                source.revision != expected_revision
+                or request.params.get("policy_source_revision") != expected_revision
+            ):
+                raise RuntimeError("Policy source revision changed")
+            self._check_qualified_request(request, captured, digest)
+            decision = self._decide_inner(captured, source=source)
+            self._check_qualified_request(request, captured, digest)
+            if self.qualified_source_revision() != expected_revision:
+                raise RuntimeError("Policy source changed during evaluation")
+            decision = self._finish_decision(decision)
+            if self.qualified_source_revision() != expected_revision:
+                raise RuntimeError("Policy source changed during audit")
+            self._check_qualified_request(request, captured, digest)
+            return decision
+        except Exception:  # noqa: BLE001 - qualified source absence never widens authority
+            return self._bind_decision_receipt(
+                ActionDecision(
+                    decision=DECISION_UNAVAILABLE,
+                    tier=TIER_FORBIDDEN,
+                    request=request,
+                    reason="qualified policy source unavailable or changed",
+                    rule_origin="unavailable",
+                )
+            )
+
+    @staticmethod
+    def _check_qualified_request(
+        request: ActionRequest, captured: ActionRequest, digest: str
+    ) -> None:
+        if request.digest() != digest or captured.digest() != digest:
+            raise RuntimeError("Qualified action request changed")
+
+    def _finish_decision(self, decision: ActionDecision) -> ActionDecision:
+        request = decision.request
         decision = self._bind_decision_receipt(decision)
         if decision.decision == DECISION_ALLOW_NOTIFY:
             self._notify(
@@ -981,13 +1066,27 @@ class ActionPolicy:
             return self._hold(base, "tier requires human approval")
         return None
 
-    def _decide_inner(self, request: ActionRequest) -> ActionDecision:
+    def _verify_selected_source(self, request: ActionRequest, source: Any):
+        """Preserve the legacy verifier call unless a snapshot was selected."""
+        if source is None:
+            return self._verify(request)
+        return self._verify(request, source=source)
+
+    def _selected_irreversibility_aversion(self, source: Any) -> bool:
+        """Read the selected setting only when evaluation reaches this guard."""
+        if source is None:
+            return self._irreversibility_aversion
+        return source.irreversibility_aversion
+
+    def _decide_inner(
+        self, request: ActionRequest, *, source: Any = None
+    ) -> ActionDecision:
         # CONCEPT:AU-OS.governance.assurance-state-machine-verifier — the deterministic
         # invariant verifier runs BEFORE the rule/tier pipeline: a payload that fails
         # role/schema/precondition/reference checks is denied outright (fail-closed),
         # regardless of what tier its kind/target would otherwise match. This is the
         # enforced half of the gate — the caller's action genuinely does not execute.
-        verify = self._verify(request)
+        verify = self._verify_selected_source(request, source)
         if not verify.ok:
             return ActionDecision(
                 decision=DECISION_DENY,
@@ -999,7 +1098,7 @@ class ActionPolicy:
                 verify_ms=verify.latency_ms,
             )
 
-        rule, defaults = self._match(request)
+        rule, defaults = self._match(request, source=source)
         base = ActionDecision(
             decision=DECISION_DENY,
             tier=rule.tier,
@@ -1033,7 +1132,8 @@ class ActionPolicy:
         # CONCEPT:AU-OS.safety.irreversibility-aversion — irreversibility aversion (opt-in). An irreversible
         # action that would otherwise auto-execute is routed to a human, since
         # policy-gating alone is brittle as autonomy rises.
-        if self._irreversibility_aversion:
+        aversion = self._selected_irreversibility_aversion(source)
+        if aversion:
             if is_irreversible(request.kind):
                 return self._hold(
                     base, "irreversible action — queued for approval (SAFE-1.5)"
@@ -1144,7 +1244,7 @@ class ActionPolicy:
         audit_id = f"action_decision:{uuid.uuid4().hex}"
         req = decision.request
         try:
-            create_record(
+            created = create_record(
                 self.engine,
                 audit_id,
                 "ActionDecision",
@@ -1164,10 +1264,10 @@ class ActionPolicy:
                     "decided_unix": _now(),
                 },
             )
-        except Exception as e:  # noqa: BLE001 — audit is best-effort, decision stands
+        except Exception as e:  # noqa: BLE001 — missing audit evidence cannot authorize
             logger.debug("action_policy: audit write failed: %s", e)
             return None
-        return audit_id
+        return audit_id if created else None
 
     def _notify(self, message: str) -> None:
         """Send ``message`` to the bound operator notifier, else log it."""

arbora-0.1.8.dev5/arbora/access/action_policy_source.py

@@ -0,0 +1,215 @@
+"""Strict source snapshots for the canonical ActionPolicy owner.
+
+A source revision is descriptive evidence, never an action grant. Legacy
+best-effort policy loading remains unchanged; opted-in boundaries use this
+stricter source contract before requesting an exact canonical decision.
+"""
+
+import asyncio
+import contextvars
+import hashlib
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+_MAX_POLICY_BYTES = 1_048_576
+_MAX_OVERRIDE_RULES = 100
+
+
+@dataclass(frozen=True, slots=True)
+class _QualifiedPolicySource:
+    revision: str
+    configuration_origin: str
+    normalized_document: str = field(repr=False)
+
+    @property
+    def irreversibility_aversion(self) -> bool:
+        return bool(json.loads(self.normalized_document)["irreversibility_aversion"])
+
+    def inputs(self) -> tuple[dict[str, Any], list[Any]]:
+        from arbora.access.action_policy import ActionRule
+
+        data = json.loads(self.normalized_document)
+        return data["file"], [ActionRule(**rule) for rule in data["graph_overrides"]]
+
+
+def _configured_document(path: Path | None) -> dict[str, Any]:
+    if path is None:
+        raise RuntimeError("Explicitly configured action policy required")
+    import yaml
+
+    with path.open("rb") as stream:
+        raw = stream.read(_MAX_POLICY_BYTES + 1)
+    if len(raw) > _MAX_POLICY_BYTES:
+        raise RuntimeError("Configured action policy exceeds the size bound")
+    data = yaml.safe_load(raw.decode("utf-8"))
+    if not isinstance(data, dict) or not isinstance(data.get("rules"), list):
+        raise RuntimeError("Configured action policy rules are unavailable")
+    return data
+
+
+def _override_rules(engine: Any) -> list[Any]:
+    if engine is None:
+        raise RuntimeError("Canonical policy override authority required")
+    rows = engine.query_cypher(
+        "MATCH (r:governance_rule {scope: 'action_policy'}) RETURN r LIMIT 101"
+    )
+    return _rules_from_rows(rows)
+
+
+def _rules_from_rows(rows: Any) -> list[Any]:
+    if not isinstance(rows, list) or len(rows) > _MAX_OVERRIDE_RULES:
+        raise RuntimeError("Complete bounded policy overrides required")
+    rules = []
+    for row in rows:
+        rule = _override_rule(row)
+        if rule is not None:
+            rules.append(rule)
+    rules.sort(key=lambda rule: -rule.priority)
+    return rules
+
+
+def _override_rule(row: Any) -> Any:
+    from arbora.access.action_policy import _coerce_rule
+
+    props = row.get("r") if isinstance(row, dict) else None
+    if not isinstance(props, dict):
+        raise RuntimeError("Malformed policy override")
+    if str(props.get("active", "true")).lower() in {"false", "0", "no"}:
+        return None
+    raw = props
+    if props.get("rule_json"):
+        payload = json.loads(props["rule_json"])
+        if not isinstance(payload, dict):
+            raise RuntimeError("Malformed policy override payload")
+        raw = {**props, **payload}
+    _validate_rule(raw)
+    rule = _coerce_rule(raw, origin="kg")
+    if rule is None:
+        raise RuntimeError("Malformed effective policy override")
+    return rule
+
+
+def _validate_rule(raw: Any) -> None:
+    from arbora.access.action_policy import _TIERS, TIER_APPROVAL
+
+    if not isinstance(raw, dict):
+        raise RuntimeError("Malformed configured policy rule")
+    tier = raw.get("tier") or TIER_APPROVAL
+    if not isinstance(tier, str) or tier not in _TIERS:
+        raise RuntimeError("Unknown configured policy tier")
+
+
+def _validated_document(path: Path | None) -> dict[str, Any]:
+    from arbora.access.action_policy import _coerce_rule
+
+    document = _configured_document(path)
+    for raw in document["rules"]:
+        _validate_rule(raw)
+        if _coerce_rule(raw, origin="file") is None:
+            raise RuntimeError("Malformed configured policy rule")
+    return document
+
+
+def _source_from_inputs(
+    document: dict[str, Any], overrides: list[Any], aversion: bool
+) -> _QualifiedPolicySource:
+    from arbora.access.action_policy import _canonical_policy_value
+
+    normalized = json.dumps(
+        _canonical_policy_value(
+            {
+                "schema": "action-policy-source.v1",
+                "configuration_origin": "configured_file",
+                "file": document,
+                "graph_overrides": [asdict(rule) for rule in overrides],
+                "irreversibility_aversion": aversion,
+            }
+        ),
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+        allow_nan=False,
+    )
+    return _QualifiedPolicySource(
+        revision="sha256:" + hashlib.sha256(normalized.encode("utf-8")).hexdigest(),
+        configuration_origin="configured_file",
+        normalized_document=normalized,
+    )
+
+
+def qualified_policy_source(policy: Any) -> _QualifiedPolicySource:
+    """Capture complete source evidence without changing decisions or state."""
+    try:
+        source = _source_from_inputs(
+            _validated_document(policy.policy_path),
+            _override_rules(policy.engine),
+            policy._irreversibility_aversion,
+        )
+    except Exception:  # noqa: BLE001 - redact source failures before refusal
+        source = None
+    if source is None:
+        raise RuntimeError("Qualified configured action policy unavailable")
+    return source
+
+
+async def _retained_file_document(path: Path | None) -> dict[str, Any]:
+    """Cancellation retains this task until its exact file worker completes."""
+    context = contextvars.copy_context()
+    worker = asyncio.get_running_loop().run_in_executor(
+        None, context.run, _validated_document, path
+    )
+    cancelled = None
+    while not worker.done():
+        try:
+            await asyncio.shield(worker)
+        except asyncio.CancelledError as error:
+            cancelled = error
+        except Exception:  # noqa: BLE001 - retrieve and redact in source owner
+            break
+    if cancelled is not None:
+        # Retrieve any failure without leaking it through the cancellation chain.
+        if not worker.cancelled():
+            worker.exception()
+        raise cancelled
+    return worker.result()
+
+
+def _check_selection(policy: Any, engine: Any, path: Any, aversion: bool) -> None:
+    if (
+        policy.engine is not engine
+        or policy.policy_path != path
+        or policy._irreversibility_aversion != aversion
+    ):
+        raise RuntimeError("Configured policy selection changed")
+
+
+async def qualified_policy_source_async(policy: Any) -> _QualifiedPolicySource:
+    """Use one captured caller and source selection; issue no effect authority.
+
+    Callers must retain capacity until this task completes, even if cancelled.
+    A stalled file worker therefore denies capacity rather than accumulating
+    detached workers. File latency and parsing CPU are not wall-clock bounded.
+    """
+    from arbora.api.contracts.session import resolve_session
+
+    try:
+        engine, path = policy.engine, policy.policy_path
+        aversion = policy._irreversibility_aversion
+        caller = resolve_session(None, required_scope="kg:read")
+        document = await _retained_file_document(path)
+        _check_selection(policy, engine, path, aversion)
+        resolve_session(caller, required_scope="kg:read")
+        rows = await engine.query_cypher_async(
+            "MATCH (r:governance_rule {scope: 'action_policy'}) RETURN r LIMIT 101",
+            session=caller,
+        )
+        _check_selection(policy, engine, path, aversion)
+        resolve_session(caller, required_scope="kg:read")
+        source = _source_from_inputs(document, _rules_from_rows(rows), aversion)
+    except Exception:  # noqa: BLE001 - redact source failures before refusal
+        source = None
+    if source is None:
+        raise RuntimeError("Qualified configured action policy unavailable")
+    return source

{arbora-0.1.8.dev4 → arbora-0.1.8.dev5}/arbora/agent_runs.py

@@ -443,10 +443,13 @@ class AgentRunPort:
     async def execute_agent(
         self, request: AgentExecutionRequest, *, session: GraphSession
     ) -> AgentExecutionResult:
+        from arbora.run_origin import agent_run_origin_scope
+
         ownership = current_native_run(request)
         if ownership is not None and ownership.session != session:
             raise RuntimeError("native run session does not match the host scope")
-        result = await self._executor.execute_agent(request, session=session)
+        with agent_run_origin_scope(session, request.agent_name, request.run_id):
+            result = await self._executor.execute_agent(request, session=session)
         return AgentExecutionResult(
             run_id=result.run_id,
             output=result.output,

{arbora-0.1.8.dev4 → arbora-0.1.8.dev5}/arbora/api/generated/descriptors.json

@@ -217,6 +217,18 @@
       ],
       "verb": "act"
     },
+    {
+      "domain": "browser",
+      "examples": [
+        "ask the attended browser owner to navigate"
+      ],
+      "id": "browser.request_call",
+      "summary": "Propose an exact browser action for attended human acceptance",
+      "tags": [
+        "browser"
+      ],
+      "verb": "act"
+    },
     {
       "domain": "browser",
       "examples": [
@@ -6161,6 +6173,18 @@
       ],
       "verb": "ask"
     },
+    {
+      "domain": "runs",
+      "examples": [
+        "show the declared steps and evidenced lifecycle of this run"
+      ],
+      "id": "runs.execution_graph",
+      "summary": "Read a bounded flat execution graph of an owned run",
+      "tags": [
+        "runs"
+      ],
+      "verb": "ask"
+    },
     {
       "domain": "runs",
       "examples": [
@@ -6306,5 +6330,5 @@
       "verb": "act"
     }
   ],
-  "registry_digest": "ce35e3e02b0e24a6eb88cbeed77b44089efeb313f408e9579e2e15ceb38627a2"
+  "registry_digest": "27b9f48df91b04f699c016125c221c290c42ff651cbecf5b00c44e9136f55506"
 }

{arbora-0.1.8.dev4 → arbora-0.1.8.dev5}/arbora/api/generated/engine_errors.py

@@ -1,6 +1,6 @@
 """Generated engine error contract. Do not edit."""
 
-REGISTRY_DIGEST = "ce35e3e02b0e24a6eb88cbeed77b44089efeb313f408e9579e2e15ceb38627a2"
+REGISTRY_DIGEST = "27b9f48df91b04f699c016125c221c290c42ff651cbecf5b00c44e9136f55506"
 EG_RECEIPT_DIGEST = "5bd7b375a923a5832a8cf493826fdba369916a0cfc4163e5cd9be7a4303d19bc"
 ENGINE_ERRORS: dict[str, tuple[int, bool]] = {
     "ABORTED_ATOMIC_GRAPH_BATCH": (400, False),