olas-ocb-agent 0.1.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 (34) hide show
  1. olas_ocb_agent-0.1.0/LICENSE +202 -0
  2. olas_ocb_agent-0.1.0/MANIFEST.in +9 -0
  3. olas_ocb_agent-0.1.0/PKG-INFO +266 -0
  4. olas_ocb_agent-0.1.0/README.md +229 -0
  5. olas_ocb_agent-0.1.0/SECURITY.md +39 -0
  6. olas_ocb_agent-0.1.0/install.sh +159 -0
  7. olas_ocb_agent-0.1.0/olas_ocb_agent/__init__.py +1 -0
  8. olas_ocb_agent-0.1.0/olas_ocb_agent/agent.py +453 -0
  9. olas_ocb_agent-0.1.0/olas_ocb_agent/broker.py +259 -0
  10. olas_ocb_agent-0.1.0/olas_ocb_agent/chains.py +88 -0
  11. olas_ocb_agent-0.1.0/olas_ocb_agent/cli.py +770 -0
  12. olas_ocb_agent-0.1.0/olas_ocb_agent/connect_client.py +169 -0
  13. olas_ocb_agent-0.1.0/olas_ocb_agent/interim/__init__.py +6 -0
  14. olas_ocb_agent-0.1.0/olas_ocb_agent/interim/facilitator.py +443 -0
  15. olas_ocb_agent-0.1.0/olas_ocb_agent/interim/facilitator_assets.py +27 -0
  16. olas_ocb_agent-0.1.0/olas_ocb_agent/interim/marketplace_gate.py +101 -0
  17. olas_ocb_agent-0.1.0/olas_ocb_agent/interim/readonly_fallback.py +7 -0
  18. olas_ocb_agent-0.1.0/olas_ocb_agent/model.py +293 -0
  19. olas_ocb_agent-0.1.0/olas_ocb_agent/pearl_cli.py +114 -0
  20. olas_ocb_agent-0.1.0/olas_ocb_agent/policy.py +316 -0
  21. olas_ocb_agent-0.1.0/olas_ocb_agent/runtime.py +384 -0
  22. olas_ocb_agent-0.1.0/olas_ocb_agent/sandbox.py +248 -0
  23. olas_ocb_agent-0.1.0/olas_ocb_agent/shell.py +282 -0
  24. olas_ocb_agent-0.1.0/olas_ocb_agent/skill_trust.py +48 -0
  25. olas_ocb_agent-0.1.0/olas_ocb_agent/trusted_skills.json +4 -0
  26. olas_ocb_agent-0.1.0/olas_ocb_agent/workspace.py +270 -0
  27. olas_ocb_agent-0.1.0/olas_ocb_agent.egg-info/PKG-INFO +266 -0
  28. olas_ocb_agent-0.1.0/olas_ocb_agent.egg-info/SOURCES.txt +32 -0
  29. olas_ocb_agent-0.1.0/olas_ocb_agent.egg-info/dependency_links.txt +1 -0
  30. olas_ocb_agent-0.1.0/olas_ocb_agent.egg-info/entry_points.txt +3 -0
  31. olas_ocb_agent-0.1.0/olas_ocb_agent.egg-info/requires.txt +17 -0
  32. olas_ocb_agent-0.1.0/olas_ocb_agent.egg-info/top_level.txt +1 -0
  33. olas_ocb_agent-0.1.0/pyproject.toml +73 -0
  34. olas_ocb_agent-0.1.0/setup.cfg +4 -0
@@ -0,0 +1,202 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright 2026 Valory AG
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
202
+
@@ -0,0 +1,9 @@
1
+ # The sdist ships the package, its README, LICENSE and SECURITY.md, and install.sh; dev-only files stay in the repo.
2
+ include README.md LICENSE SECURITY.md install.sh
3
+ prune tests
4
+ prune docs
5
+ prune quint
6
+ prune scripts
7
+ prune .github
8
+ exclude CONTRIBUTING.md .gitignore
9
+ global-exclude *.py[cod] __pycache__
@@ -0,0 +1,266 @@
1
+ Metadata-Version: 2.4
2
+ Name: olas-ocb-agent
3
+ Version: 0.1.0
4
+ Summary: A minimal agent harness for on-chain work with Pearl Connect
5
+ Author: Valory
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/valory-xyz/olas-ocb-agent
8
+ Project-URL: Source, https://github.com/valory-xyz/olas-ocb-agent
9
+ Project-URL: Issues, https://github.com/valory-xyz/olas-ocb-agent/issues
10
+ Keywords: agent,llm,olas,pearl,ethereum,safe,mech
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: MacOS
15
+ Classifier: Operating System :: POSIX :: Linux
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
19
+ Requires-Python: >=3.10
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Provides-Extra: litellm
23
+ Requires-Dist: litellm>=1.60; extra == "litellm"
24
+ Requires-Dist: mcp; extra == "litellm"
25
+ Requires-Dist: tenacity; extra == "litellm"
26
+ Provides-Extra: facilitator
27
+ Requires-Dist: eth-abi>=5; extra == "facilitator"
28
+ Requires-Dist: eth-utils>=5; extra == "facilitator"
29
+ Requires-Dist: eth-hash[pycryptodome]; extra == "facilitator"
30
+ Provides-Extra: dev
31
+ Requires-Dist: pytest>=8; extra == "dev"
32
+ Requires-Dist: pytest-cov>=5; extra == "dev"
33
+ Requires-Dist: pytest-xdist>=3.6; extra == "dev"
34
+ Requires-Dist: ruff>=0.17; extra == "dev"
35
+ Requires-Dist: olas-ocb-agent[facilitator,litellm]; extra == "dev"
36
+ Dynamic: license-file
37
+
38
+ # olas-ocb-agent: a minimal agent for on-chain work with Pearl Connect
39
+
40
+ olas-ocb-agent is a minimal general-purpose agent harness for on-chain work with Pearl Connect. "OCB" stands for
41
+ OnchainBench, the benchmark for agents trusted with on-chain keys: the agent is measured there like any other entry.
42
+ It is open source, and the leaderboard lists it with its version and frozen digest, so anyone can rerun the exact
43
+ code that was scored.
44
+
45
+ **Based on mini-swe-agent's design.** The design comes from
46
+ [mini-swe-agent](https://github.com/SWE-agent/mini-swe-agent) by the SWE-agent team (Kilian A. Lieret, Carlos E.
47
+ Jimenez and contributors): bash as the only tool, actions in plain text and a linear history. olas-ocb-agent
48
+ re-implements that core (it doesn't depend on mini-swe-agent) and adds what on-chain work with Connect needs.
49
+
50
+ **The question it answers:** can a minimal harness, integrated with Pearl Connect and the Olas marketplace, match
51
+ Claude Code for on-chain, marketplace and unattended work? The harness isn't the gap (on the
52
+ [harness leaderboard](https://huggingface.co/spaces/joelniklaus/harness-leaderboard), mini-swe-agent and Claude
53
+ Code tie on the same open model). The design and its reasons are in [docs/DESIGN.md](https://github.com/valory-xyz/olas-ocb-agent/blob/main/docs/DESIGN.md);
54
+ the evidence comes from OnchainBench, whose run-1 analysis is fixed in advance in its
55
+ [METHODOLOGY.md](https://github.com/valory-xyz/onchainbench/blob/main/docs/METHODOLOGY.md).
56
+
57
+ ## Install
58
+
59
+ Pearl Connect installs and launches the agent for you when you pick it; nothing needs to be on the machine first.
60
+ To install it yourself, from PyPI with [uv](https://docs.astral.sh/uv/):
61
+
62
+ ```bash
63
+ uv tool install 'olas-ocb-agent[facilitator]' # the default model (Gemini through the mech facilitator)
64
+ uv tool install 'olas-ocb-agent[facilitator,litellm]' # also --model litellm:<model>, with your own API key
65
+ ```
66
+
67
+ Or with the install script (macOS, Linux, WSL2), fetched from the repo, without a checkout:
68
+
69
+ ```bash
70
+ curl -LsSf https://raw.githubusercontent.com/valory-xyz/olas-ocb-agent/main/install.sh | sh
71
+ curl -LsSf https://raw.githubusercontent.com/valory-xyz/olas-ocb-agent/main/install.sh | sh -s -- 0.1.0 # a given release
72
+ ```
73
+
74
+ Native Windows isn't supported by the script yet; on Windows, run it in WSL2.
75
+
76
+ - Installs `olas-ocb-agent[facilitator]==X.Y.Z` from PyPI (the script's release by default; enough for the default
77
+ model) with `uv tool install`, on a uv-managed Python 3.12. It never uses or changes a system Python and edits no
78
+ shell profile or `PATH`.
79
+ - uv: always the script's own copy of a pinned uv version (in `~/.local/share/olas-ocb-agent/bin`), never a uv found
80
+ on `PATH`. When it's missing or another version, Astral's installer for the pinned version is downloaded and its
81
+ sha256 checked against the one in the script before it runs; the installer in turn checks the uv it downloads
82
+ (with `shasum` standing in for a missing `sha256sum`). It runs unmanaged: no `PATH` edit and no install receipt, so
83
+ a uv you installed yourself keeps `uv self update`.
84
+ - Dependencies resolve as PyPI stood at the release (`--exclude-newer`, the date next to the version in the script).
85
+ An `ocb-agent` or `pearl` already in the bin directory that isn't this tool's is never overwritten: the install
86
+ fails instead (see [The `pearl` command](#the-pearl-command)).
87
+ - Another release: `sh install.sh X.Y.Z` (or `vX.Y.Z`), or `OCB_AGENT_VERSION`. `OCB_AGENT_SPEC` replaces the whole
88
+ requirement, e.g. a GitHub archive
89
+ (`'olas-ocb-agent[facilitator] @ https://github.com/valory-xyz/olas-ocb-agent/archive/<ref>.tar.gz'`) or a
90
+ checkout (`'olas-ocb-agent[facilitator] @ file:///path/to/checkout'`). `XDG_DATA_HOME` and uv's own
91
+ `UV_TOOL_DIR`, `UV_TOOL_BIN_DIR`, `UV_PYTHON_INSTALL_DIR` move what it installs.
92
+ - No prompts, and safe to rerun: when uv's olas-ocb-agent is already exactly that requirement (version, source and
93
+ the facilitator extra) on a uv-managed Python 3.12 it changes nothing; otherwise it reinstalls in place (a custom
94
+ `OCB_AGENT_SPEC` always does). On success the only line on stdout is the absolute path of `ocb-agent`, so a caller
95
+ can launch it without `PATH`. On failure stderr gets exactly one `ocb-install: error: ...` line, naming a log with
96
+ uv's details, and the exit code is non-zero. Progress goes to that log, and to stderr only at a terminal.
97
+
98
+ ### The `pearl` command
99
+
100
+ The package also installs `pearl`, the agent's command for Connect's tools (`pearl tools`, `pearl <tool> ...`). It
101
+ has nothing to do with the unrelated `pearl` package on PyPI. If another tool's `pearl` already sits in uv's bin
102
+ directory, the install stops: install.sh's one error line names the file and says what to do. Uninstall the tool
103
+ that owns it (`uv tool uninstall <its package>`) or remove the file, then rerun.
104
+
105
+ ## Quick start
106
+
107
+ ```bash
108
+ ocb-agent --facilitator-deposit 50000000000000000 # your Pearl Connect workspace (found under ~/.operate)
109
+ ocb-agent --model 'mech:<tool>@<mech address>' --model-budget 0.05
110
+ ocb-agent --model litellm:anthropic/claude-sonnet-5-5 # bring your own key (needs the [litellm] extra)
111
+ ocb-agent --dir ~/some/project --model litellm:deepseek/deepseek-v4.1-flash # any directory, no chain
112
+ ocb-agent --trust-skill <persistent_data>/.claude/skills/<name>/SKILL.md # a skill as instructions
113
+ ocb-agent -p "what's in my safe?" # one turn, headless; --resume last to continue
114
+ ocb-agent --list-sessions # the workspace's saved sessions, for --resume <id>
115
+ ocb-agent --help # every flag, with its default
116
+ ocb-agent --version
117
+ ```
118
+
119
+ - **The default model** (Gemini through the mech facilitator) needs a Pearl Connect workspace. It is paid from a
120
+ prepaid balance that the session tops up from the Safe, up to `--facilitator-deposit` (base units:
121
+ `50000000000000000` is 0.05 xDAI, about 50 calls; default 0, never). Each deposit is printed when it happens and
122
+ listed in `/cost`. In a plain `--dir` without Connect, use `--model litellm:<model>`.
123
+ - **Approval** defaults to `--approval ask`: every value call shows a one-line summary (amounts in the token's units
124
+ and USD, and what the session has left) and waits for y/N. A call nobody could answer (no terminal, end of input,
125
+ the 10-minute timeout, Ctrl-C at the prompt) is refused as unanswered, not as declined.
126
+ - **Caps:** `--max-native-usd` (default $0.10) caps **native-token value only** (xDAI, ETH, ...): ERC-20 transfers and
127
+ approvals are not capped, so in `--approval auto` they pass without a prompt. `--max-mech-usd` (default $1.00)
128
+ caps mech payments. Both are per session, converted per chain. Raw digest signing is off unless
129
+ `--allow-sign-message`. A call a rule blocks is printed as `[blocked] ...`.
130
+ - **Session cost limit** (`--cost-limit`, $2 by default, for API models): it is checked before each model call, so the
131
+ call that crosses it finishes and the turn stops before the next one. The spend is restored on resume, so the
132
+ session goes on only with a higher `--cost-limit`; or start a new one.
133
+ - **Skills:** a workspace `SKILL.md` is followed as instructions only if its SHA-256 is trusted; any other is shown
134
+ to the agent as unverified data. You trust one with `--trust-skill <path>` (kept outside the sandbox). The
135
+ package itself pins none: **a launcher** such as Pearl passes `--trusted-skill-hash <sha256>` once for each skill it
136
+ ships (repeatable, this session only).
137
+ - **Plain project folders** (`--dir`): `AGENTS.md` and `CLAUDE.md` are read-only to the agent, since the next session
138
+ reads them as your brief; `--allow-brief-edits` lets it edit them. A Connect workspace's brief is always read-only.
139
+ On Linux, a brief that is a symlink can't be kept read-only, so the agent refuses to start there unless
140
+ `--allow-brief-edits`.
141
+ - **Caches:** the user's `~/.cache` and `~/Library/Caches` are read-only to the agent; its tools cache under
142
+ `.ocb-agent/cache` (`XDG_CACHE_HOME`, uv, pip, pre-commit, Go, Yarn, Deno, Playwright). A tool that ignores these
143
+ variables can't write its cache on macOS.
144
+ - **REPL commands:** `/compact`, `/cost` (model spend, each limit and what's left, deposits, blocked calls) and
145
+ `/exit`. Ctrl-C kills the running command and cancels an approval prompt (on native Windows, where stdin can't be
146
+ polled, the cancelled prompt's reader thread stays waiting and may take the next line). `--resume` prints a recap.
147
+ Status lines (deposits, `[blocked]` calls, the recap) go to stderr. Output has colours only at a terminal.
148
+ - **Errors** (a mistyped flag, a model provider that fails, a missing extra) print one `ocb-agent: error: ...` line
149
+ and exit non-zero.
150
+
151
+ ## What it is
152
+
153
+ 1. **The harness** (`olas_ocb_agent/`): mini-swe-agent's core (bash only, plain-text actions, linear history) plus
154
+ chat turns, compaction, a persistent shell, resumable sessions and streaming. Model backends: Gemini through the
155
+ Olas mech facilitator (the default, signed through Connect, no API key), marketplace mechs through Connect, or
156
+ LiteLLM with your own key.
157
+ 2. **Connect access:** a broker that speaks Connect's MCP and REST API, a shim `.mcp.json`, and the `pearl` command.
158
+ Connect's skills and `signer_client.py` work unchanged.
159
+ 3. **Safety:** an OS sandbox (Seatbelt on macOS, bubblewrap on Linux and WSL2) with keys and the real token
160
+ unreadable (all of `~/.operate` but the Connect workspace) and writes confined to the agent's own directory
161
+ (`<workspace>/ocb-agent/`; the workspace brief and skills can't be rewritten), plus session approval and spend
162
+ caps in the broker, in front of Connect's guardrail. Session files (history and the spend ledger `--resume`
163
+ restores) live outside the workspace, in `$XDG_STATE_HOME/olas-ocb-agent/sessions/<sha256 of the workspace path>/`
164
+ (by default under `~/.local/state`), where the sandboxed agent can neither read nor write them. With
165
+ `--sandbox none`, or on native Windows where there is no sandbox, nothing stops the agent's shell from editing them.
166
+ 4. **On OnchainBench** the agent is a CLI arm like every other harness (`olas-ocb-agent:M`, `olas-ocb-agent-mech:M`):
167
+ the bench runs `ocb-agent -p --output json` in its own process (see [Headless runs](#headless-runs-benchmarks)).
168
+ The agent doesn't depend on the bench.
169
+
170
+ Formal checking: a Quint model of the broker policy, spend across crashes and the marketplace nonce in
171
+ [quint/](https://github.com/valory-xyz/olas-ocb-agent/blob/main/quint/README.md).
172
+
173
+ ## Chains
174
+
175
+ Any EVM chain in principle, 9 EVM chains out of the box (Ethereum, Gnosis, Polygon, Arbitrum, Optimism,
176
+ Base, Celo, Mode, Robinhood). The chain comes from Connect (`wallet_info`); `olas_ocb_agent/chains.py` holds only a
177
+ rough USD price per chain for the broker's caps (`--native-usd <chain>=<price>` for others). Mech payment assets are
178
+ read from the mech itself, so every `mech_request` names its mech.
179
+
180
+ ## Headless runs (benchmarks)
181
+
182
+ `-p` runs one turn and exits. By default the turn is unattended: the system prompt says nobody will reply, and the turn
183
+ ends only on a `DONE:` reply. With `--attended` a `-p` turn behaves like a REPL turn: it may end with a question, and
184
+ `-p "<answer>" --attended --resume <session id>` continues the same session.
185
+
186
+ Each `-p --resume` turn is a new process, as with other CLI harnesses. The history, the counts, the spend ledger
187
+ (caps and approvals) and the shell's working directory carry over. Shell variables, functions and background jobs
188
+ don't: each turn starts a new shell.
189
+
190
+ ```bash
191
+ ocb-agent --dir <workspace> --model 'litellm:openrouter/<model>?provider=<provider>' --approval auto \
192
+ --output json -p "<task>"
193
+ ```
194
+
195
+ - **Approvals** come from `--approval` (`auto` or `deny` for headless runs). JSON mode has no interactive approval
196
+ channel.
197
+ - **`--output json`** prints one JSON object on stdout, also when the turn fails or times out:
198
+ - the turn: `reply`, `session_id`, `done` (the turn ended on `DONE:`), `error` and `error_detail` (truncated,
199
+ secrets redacted). `error` is null on success, else `"model"` (a model budget or cap), `"provider"` (the model
200
+ API or the network failed, after retries), `"harness"` (anything else, including a bad `--resume`),
201
+ `"timeout"` (`--turn-seconds`) or `"terminated"` (SIGTERM). Any error exits non-zero.
202
+ - session totals, restored across `--resume`: `model_calls`, `prompt_tokens`, `completion_tokens`, `cached_tokens`
203
+ (0 where the provider doesn't report them), `cost_usd` (the agent's own figure: what OpenRouter billed, else
204
+ tokens x price), `cost_sources` and `compactions`.
205
+ - this turn only: `steps` (model calls), `policy_refusals`, `broker_refusals` and `tools_listed`, plus
206
+ `session_file` and `events` (the session events this turn logged; a new session's start with the system
207
+ prompt).
208
+ - timing, on every event in `events` and in the session file: `t`, seconds from the turn's start to when the
209
+ event was logged (0 for the system prompt). A model's reply (an assistant `message`, or a `compaction`) also
210
+ has `dur_s`, from the request sent to the reply complete, and `ttft_s`, the time to the first token (backends
211
+ that don't stream deliver the reply in one piece, so there it is about `dur_s`). A command's output (the
212
+ observation `message`) has `dur_s`, from the command sent to its return code. An event's work started at
213
+ `t - dur_s`, so the time between two steps is the next one's start minus the previous one's `t`. The timing
214
+ sits on the event beside `message`, never in what the model is sent.
215
+
216
+ The banner and progress go to stderr, without colour.
217
+ - **Limits:**
218
+ - `--step-limit N` (model calls per turn, default 30) and `--cost-limit USD` (per session, default 2);
219
+ - `--max-value-calls N` (default 20; 0 blocks value calls; `none`: no limit), and `--max-native-usd` and
220
+ `--max-mech-usd` (`inf`: no cap);
221
+ - `--turn-seconds N`: the turn stops itself after N seconds, kills its running command and still reports. SIGTERM
222
+ does the same.
223
+
224
+ Negative or NaN limits are refused.
225
+ - `--allow-sign-message` lets the agent request raw digest signatures (off by default).
226
+ - `--model-price JSON` registers a LiteLLM model_cost entry (numeric `input_cost_per_token` and
227
+ `output_cost_per_token` required) for the model in this process. It feeds the cost estimate and `--cost-limit` when
228
+ the provider reports no charge.
229
+ - **Workspace and shell settings:**
230
+ - `--sessions-dir`;
231
+ - `--agent-subdir`: the agent's directory in a Connect workspace, default `ocb-agent`;
232
+ - `--trusted-skill-hash SHA256`: a skill file trusted as instructions for this session only (64 hex characters,
233
+ repeatable). This is how a launcher such as Pearl trusts the skills it ships;
234
+ - `--shell-env KEY=VALUE`: a variable for the agent's shell only, e.g. a logging web proxy (repeatable; `PATH`,
235
+ `HOME`, `BASH_ENV`, `ENV`, `LD_*`, `DYLD_*` and the variables the harness sets for the shell are refused).
236
+
237
+ ## Development
238
+
239
+ ```bash
240
+ git clone https://github.com/valory-xyz/olas-ocb-agent && cd olas-ocb-agent
241
+ uv venv .venv -p 3.12 && VIRTUAL_ENV=$PWD/.venv uv pip install -e ".[dev]"
242
+ scripts/check.sh
243
+ ```
244
+
245
+ - **Every new feature or fix comes with a test:** `pytest` fails below **100% line coverage** of `olas_ocb_agent/`.
246
+ - **ruff** check and format must pass (line length 120; rules in pyproject). A `noqa` needs a one-line reason;
247
+ `# pragma: no cover` only with a reason.
248
+ - **The gate:** `scripts/check.sh`, also run in CI (`.github/workflows/check.yml`).
249
+ - Tests run against `tests/mock_connect/`, the agent's own Connect test double (a copy of OnchainBench's mock).
250
+
251
+ ## Contributing and security
252
+
253
+ Issues only: pull requests from outside Valory are closed, because Valory develops the agent with AI agents. Fork it to
254
+ build your own. See [CONTRIBUTING.md](https://github.com/valory-xyz/olas-ocb-agent/blob/main/CONTRIBUTING.md).
255
+ Report a vulnerability privately, never in an issue: see
256
+ [SECURITY.md](https://github.com/valory-xyz/olas-ocb-agent/blob/main/SECURITY.md).
257
+
258
+ ## Documents
259
+
260
+ - [docs/DESIGN.md](https://github.com/valory-xyz/olas-ocb-agent/blob/main/docs/DESIGN.md): the current design and its
261
+ reasons: principles, architecture, the loop, models, Connect access, the sandbox, the policy, known gaps and the
262
+ threat model.
263
+ - [quint/](https://github.com/valory-xyz/olas-ocb-agent/blob/main/quint/README.md): the Quint model and its invariants.
264
+ - [olas_ocb_agent/interim/](https://github.com/valory-xyz/olas-ocb-agent/blob/main/olas_ocb_agent/interim/README.md):
265
+ the stopgap code that goes away once Connect or the mech marketplace does the job itself, and what replaces each
266
+ module.