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.
- olas_ocb_agent-0.1.0/LICENSE +202 -0
- olas_ocb_agent-0.1.0/MANIFEST.in +9 -0
- olas_ocb_agent-0.1.0/PKG-INFO +266 -0
- olas_ocb_agent-0.1.0/README.md +229 -0
- olas_ocb_agent-0.1.0/SECURITY.md +39 -0
- olas_ocb_agent-0.1.0/install.sh +159 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/__init__.py +1 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/agent.py +453 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/broker.py +259 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/chains.py +88 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/cli.py +770 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/connect_client.py +169 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/interim/__init__.py +6 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/interim/facilitator.py +443 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/interim/facilitator_assets.py +27 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/interim/marketplace_gate.py +101 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/interim/readonly_fallback.py +7 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/model.py +293 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/pearl_cli.py +114 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/policy.py +316 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/runtime.py +384 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/sandbox.py +248 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/shell.py +282 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/skill_trust.py +48 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/trusted_skills.json +4 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent/workspace.py +270 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent.egg-info/PKG-INFO +266 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent.egg-info/SOURCES.txt +32 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent.egg-info/dependency_links.txt +1 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent.egg-info/entry_points.txt +3 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent.egg-info/requires.txt +17 -0
- olas_ocb_agent-0.1.0/olas_ocb_agent.egg-info/top_level.txt +1 -0
- olas_ocb_agent-0.1.0/pyproject.toml +73 -0
- 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.
|