olas-ocb-agent 0.1.0__py3-none-any.whl

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.
@@ -0,0 +1 @@
1
+ __version__ = "0.1.0" # the package version (pyproject.toml); the agent reports it to Connect
@@ -0,0 +1,453 @@
1
+ """The olas-ocb-agent agent loop: mini-swe-agent's design plus what a chat product needs.
2
+
3
+ Kept from mini-swe-agent: bash is the only tool; actions are parsed from a
4
+ fenced block in plain text (so any model works, no tool-calling API needed);
5
+ the history is linear, so the trajectory is exactly what the model saw.
6
+
7
+ Added: multi-turn chat (a reply without a bash block ends the turn and goes
8
+ to the user), context compaction, an append-only session log that can be
9
+ resumed, streaming callbacks and per-turn limits.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import json
15
+ import re
16
+ import threading
17
+ import time
18
+ import uuid
19
+ from collections.abc import Callable
20
+ from dataclasses import dataclass, field
21
+ from pathlib import Path
22
+
23
+ ACTION_RE = re.compile(r"```(?:bash|sh)[ \t]*\n(.*?)```", re.S) # any closing ```: the fallback, and for summaries
24
+ OPEN_RE = re.compile(r"```(?:bash|sh)[ \t]*\n")
25
+ FENCE_RE = re.compile(r"^```([^\s`]*)[ \t]*$", re.M) # a fence line: ``` alone closes, ```lang opens a nested block
26
+ # Some models emit their native tool-call markup as text when the provider doesn't parse it
27
+ # (DeepSeek's DSML, Anthropic-style XML). Read it as the action rather than losing the step.
28
+ INVOKE_RE = re.compile(
29
+ r"<[^>]*invoke name=\"bash\"[^>]*>\s*<[^>]*parameter name=\"command\"[^>]*>(.*?)</[^>]*parameter>", re.S
30
+ )
31
+
32
+ # A bash fence the model closed with its tool-call markup instead of ``` (DeepSeek V4.1 does this, in OnchainBench).
33
+ MIXED_RE = re.compile(r"```(?:bash|sh)[ \t]*\n(.*?)</[^>]*parameter>", re.S)
34
+
35
+
36
+ def fenced_action(text: str) -> tuple[int, str, int] | None:
37
+ """(start, command, end) of the first fenced bash block. It closes on a ``` line of its own; a ```lang line
38
+ inside it (a heredoc holding a fenced example) opens a nested block, whose own ``` line doesn't close the
39
+ bash block. If the nesting never balances, the last ``` line closes it; with no ``` line at all, the first ```
40
+ anywhere does (a block closed on its command's line)."""
41
+ m = OPEN_RE.search(text)
42
+ if not m:
43
+ return None
44
+ depth, last = 0, None
45
+ for f in FENCE_RE.finditer(text, m.end()):
46
+ if f.group(1):
47
+ depth += 1
48
+ elif depth:
49
+ depth, last = depth - 1, f
50
+ else:
51
+ return m.start(), text[m.end() : f.start()], f.end()
52
+ if last is not None:
53
+ return m.start(), text[m.end() : last.start()], last.end()
54
+ old = ACTION_RE.match(text, m.start())
55
+ return (m.start(), old.group(1), old.end()) if old else None
56
+
57
+
58
+ def text_action(text: str) -> tuple[str | None, int]:
59
+ """(command, end offset) of the first action in plain text: a fenced bash block, else tool-call markup,
60
+ else a bash fence closed by tool-call markup."""
61
+ m = fenced_action(text)
62
+ n = INVOKE_RE.search(text)
63
+ if m and (not n or m[0] < n.start()):
64
+ return m[1], m[2]
65
+ if n:
66
+ end = text.find(">", text.find("invoke>", n.end()))
67
+ return n.group(1), (end + 1 if end > 0 else n.end())
68
+ x = MIXED_RE.search(text)
69
+ if x:
70
+ end = text.find(">", text.find("invoke>", x.end()))
71
+ return x.group(1), (end + 1 if end > 0 else x.end())
72
+ return None, -1
73
+
74
+
75
+ NUDGE_EMPTY = "Your reply was empty. Run the next command in one ```bash block, or answer."
76
+ NUDGE_DONE = (
77
+ "You're running unattended, so nobody will reply to that. If the task is finished, reply with no bash "
78
+ "block, starting with 'DONE:' and your report. Otherwise run the next command in one ```bash block."
79
+ )
80
+
81
+ OBSERVATION = "<returncode>{rc}</returncode>{timeout}\n<output>\n{output}\n</output>"
82
+ DROPPED = (
83
+ "\n<note>your reply went on after its bash block; that part was dropped unread. "
84
+ "Send one bash block per reply and end the reply there.</note>"
85
+ )
86
+ SHELL_CLOSED = "[ocb-agent] the shell was closed (the session ended); stopping this turn."
87
+ # The limit is checked before each model call: the call that crosses it finishes (and its command runs), then the
88
+ # turn stops before the next call. Its spend is restored on resume, so only a higher limit lets it go on.
89
+ COST_LIMIT = (
90
+ "[ocb-agent] session cost limit ${limit:.2f} reached (${cost:.4f} spent): this turn stopped before its next "
91
+ "model call, and the session can't go on at this limit. Start a new session (run ocb-agent without --resume), "
92
+ "or resume this one with a higher --cost-limit."
93
+ )
94
+
95
+
96
+ def count_turns(messages: list[dict]) -> int:
97
+ """The user's requests in a message list (not observations, nudges or a compaction summary): for sessions saved
98
+ before the turn count was."""
99
+ skip = ("<returncode>", "[Summary of the earlier conversation]", NUDGE_EMPTY, NUDGE_DONE)
100
+ return sum(1 for m in messages if m["role"] == "user" and not str(m.get("content") or "").startswith(skip))
101
+
102
+
103
+ SUMMARY_PROMPT = (
104
+ "Summarise the conversation so far for your own later use; it will replace the older messages. Keep: "
105
+ "the user's goals and instructions, decisions taken, facts learned (addresses, amounts, tx hashes, "
106
+ "request ids, file paths), what was done and what is still pending, and any errors. Be complete but terse. "
107
+ "Do not include a bash block."
108
+ )
109
+
110
+
111
+ @dataclass
112
+ class AgentConfig:
113
+ step_limit: int = 30 # model calls per user turn (--step-limit; a benchmark may set its own)
114
+ cost_limit: float = 2.0 # USD per session for API (litellm) backends (marketplace models use the model budget)
115
+ context_chars: int = 400_000 # ~100k tokens at 4 chars/token
116
+ compact_at: float = 0.75 # compact when the history passes this share of context_chars
117
+ keep_recent: int = 6 # messages kept verbatim after a compaction
118
+ unattended: bool = False # headless: the turn ends only on a 'DONE:' reply
119
+ max_nudges: int = 3 # consecutive no-action replies nudged before giving up
120
+
121
+
122
+ def _secs(s: float) -> float:
123
+ return round(s, 3)
124
+
125
+
126
+ def _flatten_tools(messages: list[dict]) -> list[dict]:
127
+ """Tool calls and results as plain text, for the summary request (and for backends without tools)."""
128
+ out = []
129
+ for m in messages:
130
+ if m.get("tool_calls"):
131
+ cmds = "\n".join(json.loads(c["function"]["arguments"] or "{}").get("command", "") for c in m["tool_calls"])
132
+ out.append({"role": "assistant", "content": (m.get("content") or "") + f"\n```bash\n{cmds}\n```"})
133
+ elif m["role"] == "tool":
134
+ out.append({"role": "user", "content": m["content"]})
135
+ else:
136
+ out.append({"role": m["role"], "content": m.get("content") or ""})
137
+ return out
138
+
139
+
140
+ class Session:
141
+ """Append-only JSONL: one event per message, plus compaction events. Replay = resume."""
142
+
143
+ def __init__(self, path: Path):
144
+ self.path = path
145
+ self._lock = threading.Lock()
146
+ path.parent.mkdir(parents=True, exist_ok=True)
147
+
148
+ @classmethod
149
+ def new(cls, root: Path) -> Session:
150
+ sid = time.strftime("%Y%m%d-%H%M%S-") + uuid.uuid4().hex[:6]
151
+ return cls(root / f"{sid}.jsonl")
152
+
153
+ @property
154
+ def id(self) -> str:
155
+ return self.path.stem
156
+
157
+ def append(self, event: dict) -> None:
158
+ with self._lock, self.path.open("a") as f: # the broker thread saves spend too
159
+ f.write(json.dumps(event) + "\n")
160
+
161
+ def events(self) -> list[dict]:
162
+ """Every event logged so far, in order."""
163
+ if not self.path.exists():
164
+ return []
165
+ return [json.loads(line) for line in self.path.read_text().splitlines()]
166
+
167
+ def replay(self) -> tuple[list[dict], dict]:
168
+ """The message list and state to resume from. Timing (`t`, `dur_s`, `ttft_s`) sits on the event, outside the
169
+ message, so it never reaches the model; sessions saved before it was logged replay the same."""
170
+ messages, state = [], {}
171
+ for ev in self.events():
172
+ if ev["type"] == "message":
173
+ messages.append(ev["message"])
174
+ elif ev["type"] == "compaction":
175
+ messages = ev["messages"]
176
+ elif ev["type"] == "state":
177
+ state.update(ev["state"])
178
+ return messages, state
179
+
180
+
181
+ @dataclass
182
+ class UI:
183
+ """Callbacks; the CLI prints, the eval runner records, tests ignore."""
184
+
185
+ on_token: Callable[[str], None] = lambda s: None
186
+ on_action: Callable[[str], None] = lambda s: None
187
+ on_observation: Callable[[dict], None] = lambda o: None
188
+ on_info: Callable[[str], None] = lambda s: None
189
+
190
+
191
+ @dataclass
192
+ class Agent:
193
+ model: object
194
+ shell: object
195
+ system_prompt: str
196
+ session: Session | None = None
197
+ config: AgentConfig = field(default_factory=AgentConfig)
198
+ messages: list = field(default_factory=list)
199
+ ledger: object = None # snapshot() -> dict / restore(dict): the session's spend outside the agent (runtime)
200
+ cost: float = 0.0
201
+ n_calls: int = 0
202
+ n_compactions: int = 0
203
+ n_truncated: int = 0 # replies cut after their first bash block (the model ran ahead, e.g. invented output)
204
+ prompt_tokens: int = 0
205
+ completion_tokens: int = 0
206
+ cached_tokens: int = 0 # prompt tokens the provider served from its cache (part of prompt_tokens), where reported
207
+ cost_sources: dict = field(default_factory=dict) # model calls per cost source: billed (by the provider), estimate
208
+ n_turns: int = 0 # the user's requests this session (send calls)
209
+ last_request: str = "" # the latest of them (first 500 characters), for the recap on --resume
210
+ # monotonic start of the current turn (of the agent, before its first turn): events log `t` from it
211
+ t0: float = field(default=0.0, init=False, repr=False)
212
+
213
+ def __post_init__(self):
214
+ self.t0 = time.monotonic()
215
+ if not self.messages:
216
+ self._add({"role": "system", "content": self.system_prompt})
217
+
218
+ # ---- public --------------------------------------------------------
219
+ @classmethod
220
+ def resume(cls, session: Session, model, shell, system_prompt: str, config: AgentConfig | None = None, ledger=None):
221
+ messages, state = session.replay()
222
+ if messages and messages[0]["role"] == "system": # today's prompt: the sandbox in place now, the edited brief
223
+ messages[0] = {"role": "system", "content": system_prompt}
224
+ agent = cls(
225
+ model=model,
226
+ shell=shell,
227
+ system_prompt=system_prompt,
228
+ session=session,
229
+ config=config or AgentConfig(),
230
+ messages=messages,
231
+ ledger=ledger,
232
+ cost=float(state.get("cost") or 0.0), # caps are per session, not per process
233
+ cost_sources=dict(state.get("cost_sources") or {}),
234
+ n_calls=int(state.get("n_calls") or 0), # and so are the counts the session reports
235
+ prompt_tokens=int(state.get("prompt_tokens") or 0),
236
+ completion_tokens=int(state.get("completion_tokens") or 0),
237
+ cached_tokens=int(state.get("cached_tokens") or 0),
238
+ n_compactions=int(state.get("n_compactions") or 0),
239
+ n_turns=int(state.get("n_turns") or count_turns(messages)),
240
+ last_request=str(state.get("last_request") or ""),
241
+ )
242
+ if ledger is not None:
243
+ ledger.restore(state)
244
+ if state.get("cwd") and Path(state["cwd"]).is_dir():
245
+ shell.run(f"cd {json.dumps(state['cwd'])}")
246
+ return agent
247
+
248
+ def _query(self, messages: list[dict], on_token=None) -> tuple[dict, dict]:
249
+ """A model call: (reply, timing). timing has `dur_s` (request sent to reply complete) and, once a token
250
+ arrived, `ttft_s`. If the call fails after paying (a mech follow-up, a facilitator deposit), its spend is
251
+ saved before the error goes up, so `--resume` keeps it. Record-only fields (`dropped`) never reach the
252
+ model."""
253
+ messages = [{k: v for k, v in m.items() if k != "dropped"} if "dropped" in m else m for m in messages]
254
+ start, first = time.monotonic(), []
255
+
256
+ def token(s: str) -> None:
257
+ if not first:
258
+ first.append(time.monotonic())
259
+ if on_token:
260
+ on_token(s)
261
+
262
+ try:
263
+ reply = self.model.query(messages, on_token=token)
264
+ except Exception:
265
+ self._save_state()
266
+ raise
267
+ timing = {"dur_s": _secs(time.monotonic() - start)}
268
+ if first:
269
+ timing["ttft_s"] = _secs(first[0] - start)
270
+ return reply, timing
271
+
272
+ def _run(self, cmd: str) -> tuple[dict, dict]:
273
+ """A shell command: (output, timing), `dur_s` from sending it to its returncode."""
274
+ start = time.monotonic()
275
+ out = self.shell.run(cmd)
276
+ return out, {"dur_s": _secs(time.monotonic() - start)}
277
+
278
+ def _t(self) -> float:
279
+ return _secs(time.monotonic() - self.t0)
280
+
281
+ def _count(self, reply: dict) -> None:
282
+ """Every model call, the turn's and compaction's summary alike: one call, its cost and its tokens."""
283
+ self.n_calls += 1
284
+ self.cost += reply.get("cost", 0.0) or 0.0
285
+ u = reply.get("usage") or {}
286
+ self.prompt_tokens += int(u.get("prompt_tokens") or 0)
287
+ self.completion_tokens += int(u.get("completion_tokens") or 0)
288
+ self.cached_tokens += int((u.get("prompt_tokens_details") or {}).get("cached_tokens") or 0)
289
+ if src := reply.get("cost_source"):
290
+ self.cost_sources[src] = self.cost_sources.get(src, 0) + 1
291
+
292
+ def _save_state(self) -> None:
293
+ """cwd plus everything spent and counted so far, so --resume continues the same caps and totals."""
294
+ if self.session:
295
+ state = {
296
+ "cost": self.cost,
297
+ "cost_sources": self.cost_sources,
298
+ "n_calls": self.n_calls,
299
+ "prompt_tokens": self.prompt_tokens,
300
+ "completion_tokens": self.completion_tokens,
301
+ "cached_tokens": self.cached_tokens,
302
+ "n_compactions": self.n_compactions,
303
+ "n_turns": self.n_turns,
304
+ "last_request": self.last_request,
305
+ **(self.ledger.snapshot() if self.ledger else {}),
306
+ }
307
+ if self.shell is not None:
308
+ state["cwd"] = self.shell.cwd
309
+ self.session.append({"type": "state", "state": state, "t": self._t()})
310
+
311
+ def send(self, user_text: str, ui: UI | None = None) -> str:
312
+ """One user turn: loop until the model replies without an action. Returns that reply."""
313
+ ui = ui or UI()
314
+ self.t0 = time.monotonic() # the turn's events log `t` from here
315
+ self._add({"role": "user", "content": user_text})
316
+ self.n_turns += 1
317
+ self.last_request = user_text[:500]
318
+ nudges = 0
319
+ for _ in range(self.config.step_limit):
320
+ if getattr(self.shell, "closed", False): # the session was closed under a running turn
321
+ return self._stop(SHELL_CLOSED, ui)
322
+ self._maybe_compact(ui)
323
+ if self.cost >= self.config.cost_limit: # checked before each model call: no call starts past the limit
324
+ return self._stop(COST_LIMIT.format(limit=self.config.cost_limit, cost=self.cost), ui)
325
+ reply, timing = self._query(self.messages, on_token=ui.on_token)
326
+ self._count(reply)
327
+ self._save_state() # the call's spend, before anything else can fail
328
+ text = reply["content"] or ""
329
+ calls = reply.get("tool_calls") or []
330
+ if calls: # native tool calling: run the first call; answer the rest without running them
331
+ self._add(
332
+ {
333
+ "role": "assistant",
334
+ "content": text,
335
+ "tool_calls": [
336
+ {
337
+ "id": c["id"],
338
+ "type": "function",
339
+ "function": {"name": c["name"], "arguments": c["arguments"]},
340
+ }
341
+ for c in calls
342
+ ],
343
+ },
344
+ timing,
345
+ )
346
+ nudges = 0
347
+ cmd = calls[0]["command"]
348
+ ui.on_action(cmd)
349
+ out, ran = (
350
+ self._run(cmd)
351
+ if cmd
352
+ else ({"output": "error: the bash tool needs a 'command'", "returncode": -1}, {})
353
+ )
354
+ if out.get("closed"):
355
+ return self._stop(SHELL_CLOSED, ui)
356
+ ui.on_observation(out)
357
+ self._add({"role": "tool", "tool_call_id": calls[0]["id"], "content": self._observation(out)}, ran)
358
+ for c in calls[1:]:
359
+ self._add(
360
+ {
361
+ "role": "tool",
362
+ "tool_call_id": c["id"],
363
+ "content": "not run: one command per step. Call it again after reading the output above.",
364
+ }
365
+ )
366
+ self._save_state()
367
+ continue
368
+ cmd, end = text_action(text)
369
+ dropped = cmd is not None and bool(text[end:].strip())
370
+ message = {"role": "assistant", "content": text}
371
+ if dropped:
372
+ # Anything after the first action was written without seeing its output (often an invented
373
+ # <output> and more commands). Keep the reply up to the action, run it, drop the rest, and say so.
374
+ # The model's context gets the cut reply; the session and transcript also keep what was cut.
375
+ text = text[:end]
376
+ message = {"role": "assistant", "content": text, "dropped": message["content"][end:]}
377
+ self.n_truncated += 1
378
+ self._add(message, timing)
379
+ if cmd is None:
380
+ done = text.lstrip().upper().startswith("DONE")
381
+ if text.strip() and (done or not self.config.unattended):
382
+ return text.lstrip()[5:].lstrip() if done and self.config.unattended else text
383
+ if nudges >= self.config.max_nudges: # say why the turn ended rather than return nothing
384
+ return (
385
+ text or f"[ocb-agent] the model gave {nudges + 1} empty replies in a row; stopping this turn."
386
+ )
387
+ nudges += 1
388
+ if text and not text.endswith("\n"): # end the streamed reply, so the next one starts on a new line
389
+ ui.on_token("\n")
390
+ self._add({"role": "user", "content": NUDGE_DONE if text.strip() else NUDGE_EMPTY})
391
+ continue
392
+ nudges = 0
393
+ ui.on_action(cmd)
394
+ out, ran = self._run(cmd)
395
+ if out.get("closed"):
396
+ return self._stop(SHELL_CLOSED, ui)
397
+ ui.on_observation(out)
398
+ self._add({"role": "user", "content": self._observation(out) + (DROPPED if dropped else "")}, ran)
399
+ self._save_state()
400
+ return self._stop(f"[ocb-agent] step limit {self.config.step_limit} reached for this turn.", ui)
401
+
402
+ @staticmethod
403
+ def _stop(msg: str, ui: UI) -> str:
404
+ ui.on_info(msg)
405
+ return msg
406
+
407
+ def compact(self, ui: UI | None = None) -> None:
408
+ ui = ui or UI()
409
+ k = self.config.keep_recent
410
+ if len(self.messages) <= k + 2:
411
+ return
412
+ head, middle, tail = self.messages[:1], self.messages[1:-k], self.messages[-k:]
413
+ while tail and tail[0]["role"] != "user": # start the kept tail on a user message (never on a tool result)
414
+ middle.append(tail.pop(0))
415
+ req = [*head, *_flatten_tools(middle), {"role": "user", "content": SUMMARY_PROMPT}]
416
+ reply, timing = self._query(req)
417
+ self._count(reply)
418
+ summary = ACTION_RE.sub("", reply["content"]).strip()
419
+ self.messages = [
420
+ *head,
421
+ {"role": "user", "content": f"[Summary of the earlier conversation]\n{summary}"},
422
+ {"role": "assistant", "content": "Understood; continuing from that summary."},
423
+ *tail,
424
+ ]
425
+ self.n_compactions += 1
426
+ if self.session:
427
+ self.session.append({"type": "compaction", "messages": self.messages, "t": self._t(), **timing})
428
+ self._save_state() # the summary call is counted like any other, so a resume keeps it
429
+ ui.on_info(f"[ocb-agent] compacted {len(middle)} messages into a summary")
430
+
431
+ # ---- internals -----------------------------------------------------
432
+ @staticmethod
433
+ def _observation(out: dict) -> str:
434
+ timeout = (
435
+ "\n<note>the command timed out and was killed; the shell was restarted</note>"
436
+ if out.get("timed_out")
437
+ else ""
438
+ )
439
+ return OBSERVATION.format(rc=out["returncode"], timeout=timeout, output=out["output"].rstrip("\n"))
440
+
441
+ def _chars(self) -> int:
442
+ return sum(len(m.get("content") or "") + len(json.dumps(m.get("tool_calls", ""))) for m in self.messages)
443
+
444
+ def _maybe_compact(self, ui: UI) -> None:
445
+ if self._chars() > self.config.compact_at * self.config.context_chars:
446
+ self.compact(ui)
447
+
448
+ def _add(self, message: dict, timing: dict | None = None) -> None:
449
+ """Log a message. Its event carries `t` (seconds since the turn started) and the timing of the model call
450
+ or command that produced it, beside the message: the message itself, what the model is sent, is unchanged."""
451
+ self.messages.append(message)
452
+ if self.session:
453
+ self.session.append({"type": "message", "message": message, "t": self._t(), **(timing or {})})