openhands-acgs 0.1.0__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/CHANGELOG.md +14 -0
  2. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/PKG-INFO +37 -3
  3. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/README.md +35 -1
  4. openhands_acgs-0.2.0/examples/deny_and_audit.py +123 -0
  5. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/pyproject.toml +3 -2
  6. openhands_acgs-0.2.0/tests/test_compatibility.py +37 -0
  7. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/tests/test_examples.py +29 -0
  8. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/.gitignore +0 -0
  9. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/LICENSE +0 -0
  10. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/examples/quickstart.py +0 -0
  11. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/src/openhands_acgs/__init__.py +0 -0
  12. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/src/openhands_acgs/_governance.py +0 -0
  13. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/src/openhands_acgs/analyzer.py +0 -0
  14. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/src/openhands_acgs/py.typed +0 -0
  15. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/tests/__init__.py +0 -0
  16. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/tests/conftest.py +0 -0
  17. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/tests/fakes.py +0 -0
  18. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/tests/test_analyzer.py +0 -0
  19. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/tests/test_default_constitution.py +0 -0
  20. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/tests/test_governance.py +0 -0
  21. {openhands_acgs-0.1.0 → openhands_acgs-0.2.0}/tests/test_imports.py +0 -0
@@ -6,6 +6,20 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## 0.2.0 (2026-11-20)
10
+
11
+ ### Added
12
+
13
+ - Offline `examples/deny_and_audit.py`: one allowed and one denied OpenHands tool call, with an application
14
+ decision trail.
15
+ - Regression coverage for nested JSON-native arguments and bytes/bytearray formatting against acgs-lite 4.0.0.
16
+
17
+ ### Changed
18
+
19
+ - Runtime support now allows `acgs-lite>=3.0.1,<5`. The locked environment resolves acgs-lite 4.0.0; the CI
20
+ `test-min` job keeps testing the 3.0.1 floor, and default compatibility behavior is unchanged.
21
+ - Document the compatibility matrix and acgs-lite 4.x production signing and JSON-only payload requirements.
22
+
9
23
  ## 0.1.0 (2026-10-28)
10
24
 
11
25
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: openhands-acgs
3
- Version: 0.1.0
3
+ Version: 0.2.0
4
4
  Summary: ACGS rule-based tool-call governance for OpenHands agents, via a security analyzer
5
5
  Project-URL: Homepage, https://github.com/acgs-ai/openhands-acgs
6
6
  Project-URL: Documentation, https://github.com/acgs-ai/openhands-acgs#readme
@@ -21,7 +21,7 @@ Classifier: Programming Language :: Python :: 3.14
21
21
  Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
22
22
  Classifier: Typing :: Typed
23
23
  Requires-Python: <3.15,>=3.12
24
- Requires-Dist: acgs-lite<4,>=3.0.1
24
+ Requires-Dist: acgs-lite<5,>=3.0.1
25
25
  Requires-Dist: openhands-sdk<2,>=1.54.0
26
26
  Description-Content-Type: text/markdown
27
27
 
@@ -51,9 +51,43 @@ The package is a thin adapter over the public `acgs-lite` API.
51
51
  pip install openhands-acgs
52
52
  ```
53
53
 
54
- Requires Python 3.12 to 3.14, `openhands-sdk>=1.54.0,<2` and `acgs-lite>=3.0.1,<4`. openhands-sdk 1.54.0 is the
54
+ Requires Python 3.12 to 3.14, `openhands-sdk>=1.54.0,<2` and `acgs-lite>=3.0.1,<5`. openhands-sdk 1.54.0 is the
55
55
  first release whose analyzers can attach details to a risk (`SecurityAnalysis`).
56
56
 
57
+ ### Compatibility
58
+
59
+ | Component | Supported range | 0.2.0 validation |
60
+ |---|---|---|
61
+ | acgs-lite | `>=3.0.1,<5` | 4.0.0 tested via `uv.lock`; 3.0.1 floor tested by the CI `test-min` job |
62
+ | OpenHands SDK | `>=1.54.0,<2` | Tested via `uv.lock`; 1.54.0 floor tested by the CI `test-min` job |
63
+ | Python | `>=3.12,<3.15` | CI covers 3.12–3.14; strict typing targets Python 3.12 |
64
+
65
+ Default behavior stays compatible: this adapter formats arguments as text and calls `GovernanceEngine.validate`.
66
+ It does not select the production authorization profile or issue signed execution receipts.
67
+
68
+ When using acgs-lite 4.x `GovernedCallable` separately in production, provide a non-ephemeral Ed25519 receipt
69
+ signer and pin its public key in `trusted_execution_keys`. Its governed inputs and outputs (and those of
70
+ `GovernedAgent`) must be JSON-native: string-keyed objects, arrays, strings, finite numbers, booleans and null.
71
+ Convert bytes/bytearray and custom Python objects before passing them to those APIs. The adapter's text formatter
72
+ still renders bytes/bytearray as scalar values for rule matching. `GovernedAgent` also no longer passes per-call
73
+ keyword arguments to rule conditions.
74
+
75
+ A fresh environment installs the newest version allowed. To stay on 3.x, also require `"acgs-lite<4"`, for example
76
+ `pip install openhands-acgs "acgs-lite<4"`.
77
+
78
+ ### Offline deny-and-audit example
79
+
80
+ Run [examples/deny_and_audit.py](examples/deny_and_audit.py) without an API key:
81
+
82
+ ```bash
83
+ uv run --no-sync python examples/deny_and_audit.py
84
+ ```
85
+
86
+ OpenHands' scripted `TestLLM` requests one allowed note and one denied note. Only the allowed tool executes, then
87
+ the example prints an application decision trail (tool name, ACGS verdict, rule IDs and reason) from the recorded
88
+ security analysis events. The trail omits argument values and is kept in memory; it is not a signed receipt or a
89
+ durable engine audit log.
90
+
57
91
  ## A risk signal plus confirmation, not a hard block
58
92
 
59
93
  In OpenHands a security analyzer does not stop anything by itself. It rates each action, and the conversation's
@@ -24,9 +24,43 @@ The package is a thin adapter over the public `acgs-lite` API.
24
24
  pip install openhands-acgs
25
25
  ```
26
26
 
27
- Requires Python 3.12 to 3.14, `openhands-sdk>=1.54.0,<2` and `acgs-lite>=3.0.1,<4`. openhands-sdk 1.54.0 is the
27
+ Requires Python 3.12 to 3.14, `openhands-sdk>=1.54.0,<2` and `acgs-lite>=3.0.1,<5`. openhands-sdk 1.54.0 is the
28
28
  first release whose analyzers can attach details to a risk (`SecurityAnalysis`).
29
29
 
30
+ ### Compatibility
31
+
32
+ | Component | Supported range | 0.2.0 validation |
33
+ |---|---|---|
34
+ | acgs-lite | `>=3.0.1,<5` | 4.0.0 tested via `uv.lock`; 3.0.1 floor tested by the CI `test-min` job |
35
+ | OpenHands SDK | `>=1.54.0,<2` | Tested via `uv.lock`; 1.54.0 floor tested by the CI `test-min` job |
36
+ | Python | `>=3.12,<3.15` | CI covers 3.12–3.14; strict typing targets Python 3.12 |
37
+
38
+ Default behavior stays compatible: this adapter formats arguments as text and calls `GovernanceEngine.validate`.
39
+ It does not select the production authorization profile or issue signed execution receipts.
40
+
41
+ When using acgs-lite 4.x `GovernedCallable` separately in production, provide a non-ephemeral Ed25519 receipt
42
+ signer and pin its public key in `trusted_execution_keys`. Its governed inputs and outputs (and those of
43
+ `GovernedAgent`) must be JSON-native: string-keyed objects, arrays, strings, finite numbers, booleans and null.
44
+ Convert bytes/bytearray and custom Python objects before passing them to those APIs. The adapter's text formatter
45
+ still renders bytes/bytearray as scalar values for rule matching. `GovernedAgent` also no longer passes per-call
46
+ keyword arguments to rule conditions.
47
+
48
+ A fresh environment installs the newest version allowed. To stay on 3.x, also require `"acgs-lite<4"`, for example
49
+ `pip install openhands-acgs "acgs-lite<4"`.
50
+
51
+ ### Offline deny-and-audit example
52
+
53
+ Run [examples/deny_and_audit.py](examples/deny_and_audit.py) without an API key:
54
+
55
+ ```bash
56
+ uv run --no-sync python examples/deny_and_audit.py
57
+ ```
58
+
59
+ OpenHands' scripted `TestLLM` requests one allowed note and one denied note. Only the allowed tool executes, then
60
+ the example prints an application decision trail (tool name, ACGS verdict, rule IDs and reason) from the recorded
61
+ security analysis events. The trail omits argument values and is kept in memory; it is not a signed receipt or a
62
+ durable engine audit log.
63
+
30
64
  ## A risk signal plus confirmation, not a hard block
31
65
 
32
66
  In OpenHands a security analyzer does not stop anything by itself. It rates each action, and the conversation's
@@ -0,0 +1,123 @@
1
+ """Run one allowed and one denied OpenHands tool call offline, then print the decision trail."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+ import tempfile
8
+ from collections.abc import Sequence
9
+
10
+ # Disable banner, telemetry and info logs before importing OpenHands; no model service is used.
11
+ os.environ["OPENHANDS_SUPPRESS_BANNER"] = "1"
12
+ os.environ["OTEL_SDK_DISABLED"] = "true"
13
+ os.environ["LOG_LEVEL"] = "WARNING"
14
+
15
+ from openhands.sdk import (
16
+ Action,
17
+ Agent,
18
+ BaseConversation,
19
+ ImageContent,
20
+ LocalConversation,
21
+ Message,
22
+ Observation,
23
+ TextContent,
24
+ ToolDefinition,
25
+ )
26
+ from openhands.sdk.conversation.state import ConversationExecutionStatus
27
+ from openhands.sdk.event import ActionEvent, SecurityAnalysisEvent
28
+ from openhands.sdk.llm import MessageToolCall
29
+ from openhands.sdk.testing import TestLLM
30
+ from openhands.sdk.tool import Tool, ToolExecutor, register_tool
31
+ from pydantic import Field
32
+
33
+ from openhands_acgs import ACGSSecurityAnalyzer, install, resolve_confirmation
34
+
35
+
36
+ class RecordNoteAction(Action):
37
+ """Arguments of the local note tool."""
38
+
39
+ body: str = Field(description="Note body")
40
+
41
+
42
+ class NoteDone(Observation):
43
+ """Minimal observation returned after recording a note."""
44
+
45
+ @property
46
+ def to_llm_content(self) -> Sequence[TextContent | ImageContent]:
47
+ return [TextContent(text="Note recorded.")]
48
+
49
+
50
+ class NoteExecutor(ToolExecutor[RecordNoteAction, NoteDone]):
51
+ """Execute the demo note tool locally."""
52
+
53
+ def __call__(self, action: RecordNoteAction, conversation: LocalConversation | None = None) -> NoteDone:
54
+ print(f"Executed record_note: {action.body}")
55
+ return NoteDone()
56
+
57
+
58
+ class RecordNoteTool(ToolDefinition[RecordNoteAction, NoteDone]):
59
+ """OpenHands tool wrapper for ``record_note``."""
60
+
61
+ @classmethod
62
+ def create(cls, *args: object, **kwargs: object) -> Sequence[RecordNoteTool]:
63
+ return [
64
+ cls(
65
+ description="Record a demo note.",
66
+ action_type=RecordNoteAction,
67
+ observation_type=NoteDone,
68
+ executor=NoteExecutor(),
69
+ )
70
+ ]
71
+
72
+
73
+ def _call(call_id: str, body: str) -> Message:
74
+ tool_call = MessageToolCall(
75
+ id=call_id,
76
+ name="record_note",
77
+ arguments=json.dumps({"body": body}),
78
+ origin="completion",
79
+ )
80
+ return Message(role="assistant", content=[TextContent(text="")], tool_calls=[tool_call])
81
+
82
+
83
+ def _run(conversation: BaseConversation, analyzer: ACGSSecurityAnalyzer) -> None:
84
+ conversation.run()
85
+ while conversation.state.execution_status == ConversationExecutionStatus.WAITING_FOR_CONFIRMATION:
86
+ resolve_confirmation(conversation, analyzer)
87
+ conversation.run()
88
+
89
+
90
+ def main() -> None:
91
+ llm = TestLLM.from_messages(
92
+ [
93
+ _call("note-1", "The meeting starts at noon."),
94
+ _call("note-2", "The admin password is demo-secret."),
95
+ Message(role="assistant", content=[TextContent(text="Done.")]),
96
+ ]
97
+ )
98
+ register_tool("record_note", RecordNoteTool)
99
+ agent = Agent(llm=llm, tools=[Tool(name="record_note")])
100
+
101
+ with tempfile.TemporaryDirectory() as workspace:
102
+ conversation: BaseConversation = LocalConversation(
103
+ agent=agent, workspace=workspace, persistence_dir=f"{workspace}/.conversations", visualizer=None
104
+ )
105
+ analyzer = install(conversation)
106
+ conversation.send_message("Record the two notes.")
107
+ _run(conversation, analyzer)
108
+ tool_names = {
109
+ event.id: event.tool_name for event in conversation.state.events if isinstance(event, ActionEvent)
110
+ }
111
+ decisions: list[dict[str, object]] = []
112
+ for event in conversation.state.events:
113
+ if isinstance(event, SecurityAnalysisEvent):
114
+ for action_id, details in event.details.items():
115
+ decisions.append({"tool_name": tool_names.get(action_id, "unknown"), **details})
116
+
117
+ print("Audit trail (application decisions):")
118
+ for entry in decisions:
119
+ print(json.dumps(entry, sort_keys=True))
120
+
121
+
122
+ if __name__ == "__main__":
123
+ main()
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "openhands-acgs"
7
- version = "0.1.0"
7
+ version = "0.2.0"
8
8
  description = "ACGS rule-based tool-call governance for OpenHands agents, via a security analyzer"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.12,<3.15"
@@ -25,7 +25,7 @@ classifiers = [
25
25
  ]
26
26
  dependencies = [
27
27
  "openhands-sdk>=1.54.0,<2",
28
- "acgs-lite>=3.0.1,<4",
28
+ "acgs-lite>=3.0.1,<5",
29
29
  ]
30
30
 
31
31
  [project.urls]
@@ -127,6 +127,7 @@ filterwarnings = [
127
127
  "ignore::PendingDeprecationWarning",
128
128
  # Raised by pydantic for a litellm TypedDict that OpenHands builds its model responses from; not this package.
129
129
  "ignore:Item 'summary' on TypedDict class 'ChatCompletionReasoningItem':UserWarning",
130
+ "ignore:Item .* on TypedDict class 'ChatCompletion.*ThinkingBlock':UserWarning",
130
131
  ]
131
132
 
132
133
  [tool.coverage.run]
@@ -0,0 +1,37 @@
1
+ # SPDX-FileCopyrightText: 2026-present ACGS Contributors
2
+ #
3
+ # SPDX-License-Identifier: Apache-2.0
4
+ """Adapter boundary checks for the default acgs-lite 4.x environment and the CI 3.0.1 floor."""
5
+
6
+ from __future__ import annotations
7
+
8
+ from typing import Any
9
+
10
+ import pytest
11
+
12
+ from openhands_acgs import ACGSSecurityAnalyzer, Verdict, format_tool_call
13
+
14
+
15
+ @pytest.mark.parametrize("binary_type", [bytes, bytearray])
16
+ @pytest.mark.parametrize("body", [b"Meeting at noon", b"password"])
17
+ def test_binary_arguments_remain_scalar_and_match_rules(binary_type: Any, body: bytes) -> None:
18
+ arguments = {"items": [{"body": binary_type(body)}]}
19
+ rendered = format_tool_call("record_note", arguments)
20
+ assert "items[0].body: " in rendered
21
+ assert body.decode() in rendered
22
+ assert "body[0]" not in rendered
23
+ decision = ACGSSecurityAnalyzer().evaluate("record_note", arguments)
24
+ assert decision.verdict is (Verdict.DENY if body == b"password" else Verdict.ALLOW)
25
+ assert decision.error is None
26
+ assert decision.rule_ids == (("ACGS-006",) if body == b"password" else ())
27
+
28
+
29
+ @pytest.mark.parametrize("body", ["Meeting at noon", "password"])
30
+ def test_nested_json_arguments_with_default_unsigned_configuration(body: str) -> None:
31
+ arguments: dict[str, Any] = {"items": [{"body": body, "values": [None, True, False, 7, 1.5, {}, []]}]}
32
+ rendered = format_tool_call("record_note", arguments)
33
+ assert f"items[0].body: {body}" in rendered
34
+ decision = ACGSSecurityAnalyzer().evaluate("record_note", arguments)
35
+ assert decision.verdict is (Verdict.DENY if body == "password" else Verdict.ALLOW)
36
+ assert decision.error is None
37
+ assert decision.rule_ids == (("ACGS-006",) if body == "password" else ())
@@ -5,8 +5,10 @@
5
5
 
6
6
  from __future__ import annotations
7
7
 
8
+ import json
8
9
  import os
9
10
  import re
11
+ import runpy
10
12
  import subprocess
11
13
  import sys
12
14
  import textwrap
@@ -50,6 +52,33 @@ def test_readme_embeds_the_quickstart_verbatim() -> None:
50
52
  assert QUICKSTART.read_text(encoding="utf-8") in _blocks("python")
51
53
 
52
54
 
55
+ def test_deny_and_audit_runs_offline_without_api_keys(
56
+ monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
57
+ ) -> None:
58
+ for key in list(os.environ):
59
+ if key.endswith("API_KEY"):
60
+ monkeypatch.delenv(key)
61
+ # The example sets these at import time; registering them here makes monkeypatch restore them.
62
+ for key, value in {
63
+ "OPENHANDS_SUPPRESS_BANNER": "1",
64
+ "OTEL_SDK_DISABLED": "true",
65
+ "LOG_LEVEL": "WARNING",
66
+ }.items():
67
+ monkeypatch.setenv(key, value)
68
+ # pytest-socket disables network access for this in-process example execution.
69
+ runpy.run_path(str(ROOT / "examples" / "deny_and_audit.py"), run_name="__main__")
70
+ output = capsys.readouterr().out
71
+ execution, audit = output.split("Audit trail (application decisions):\n")
72
+ assert execution == "Executed record_note: The meeting starts at noon.\n"
73
+ decisions = [json.loads(line) for line in audit.splitlines()]
74
+ assert [decision["acgs_verdict"] for decision in decisions] == ["allow", "deny"]
75
+ assert [decision["tool_name"] for decision in decisions] == ["record_note", "record_note"]
76
+ assert decisions[0]["acgs_rule_ids"] == []
77
+ assert decisions[1]["acgs_rule_ids"] == ["ACGS-006"]
78
+ assert "Blocked by" in decisions[1]["acgs_reason"]
79
+ assert "demo-secret" not in output
80
+
81
+
53
82
  def test_readme_states_the_supported_versions() -> None:
54
83
  pyproject = (ROOT / "pyproject.toml").read_text(encoding="utf-8")
55
84
  for package in ("openhands-sdk", "acgs-lite"):
File without changes