Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

feat(agent-core): run independent tool calls of one response concurrently (#2431)

Call Whitedc353d614723
diff --git a/core/agent_core/agent/README.md b/core/agent_core/agent/README.md
index 02fa1cce3..9e3ec117b 100644
--- a/core/agent_core/agent/README.md
+++ b/core/agent_core/agent/README.md
@@ -106,9 +106,15 @@ localize that error rather than deliver a silent success.
`empty_response` and end as error. A received terminal is never retried.
Empty non-final responses with queued inputs can still continue to a reply;
tool calls, explicit hook end, and tool termination retain their contracts.
-- A tool batch runs sequentially and commits results in call order. Steers
- enter after the whole batch. Follow-ups enter at natural termination after
- steers have been consumed. A terminating tool still finishes its batch.
+- A tool batch runs in groups (C-3 section 2): neighbouring calls to tools that
+ declare `concurrent` run at the same time, every other call runs alone, and
+ each group starts after the one before it has committed. Each group's
+ `before_tool` gates run before it starts; results, `after_tool`, and
+ `ToolFinished` follow call order. Every call task is awaited or cancelled
+ before the batch ends, and `emit` serializes events so their `seq` stays in
+ order across concurrent calls. Steers enter after the whole batch.
+ Follow-ups enter at natural termination after steers have been consumed. A
+ terminating tool still finishes its batch.
An `Exception` from `Tool.execute` becomes an error result (at most 500
characters), with a logged traceback; the run continues. `BaseException`,
including `CancelledError`, retains lifecycle semantics.
diff --git a/core/agent_core/agent/loop.py b/core/agent_core/agent/loop.py
index c33e07fe0..cd71dff78 100644
--- a/core/agent_core/agent/loop.py
+++ b/core/agent_core/agent/loop.py
@@ -18,7 +18,7 @@ from collections import deque
from contextlib import asynccontextmanager, suppress
from copy import deepcopy
from dataclasses import asdict, dataclass, replace
-from typing import Any, AsyncIterator, Awaitable, Callable, Literal, Mapping, Optional, Sequence, TypeVar
+from typing import Any, AsyncIterator, Awaitable, Callable, Iterable, Literal, Mapping, Optional, Sequence, TypeVar
from core.agent_core.agent.events import (
AgentError,
@@ -139,6 +139,9 @@ from core.agent_core.tools.paths import to_thread_joined
T = TypeVar("T")
logger = logging.getLogger(__name__)
+#: The result of a call a hook's ``end`` or ``skip_tools`` settled without running it (C-3 section 3).
+_SKIPPED = "[skipped by policy]"
+
class _Ended(Exception):
pass
@@ -351,14 +354,18 @@ class Agent:
# Bounded delivery applies backpressure to provider streaming. No emit
# awaits this queue while holding the input-admission lock.
events: asyncio.Queue[AgentEvent] = asyncio.Queue(maxsize=64)
+ # Concurrent tool calls emit too, and a put can overtake one that waits for room in the full queue: events
+ # enter it one at a time, in ``seq`` order.
+ ordered = asyncio.Lock()
async def emit(event_type: Any, **fields: Any) -> Optional[AgentEvent]:
- if self._consumer_closed:
- return None
- event = event_type(turn_id=turn_id, seq=self._seq, **fields)
- self._seq += 1
- await events.put(event)
- return event
+ async with ordered:
+ if self._consumer_closed:
+ return None
+ event = event_type(turn_id=turn_id, seq=self._seq, **fields)
+ self._seq += 1
+ await events.put(event)
+ return event
worker = asyncio.create_task(drive(emit))
receive: Optional[asyncio.Task] = None
@@ -921,16 +928,7 @@ class Agent:
if reason == "length"
else f"Tool call not executed because the model stopped with {reason}."
)
- for call in message.tool_calls:
- self._scope.check()
- await self._tool(
- call,
- response,
- tools,
- True,
- emit,
- skip_reason=skip_reason,
- )
+ await self._calls(message.tool_calls, response, tools, emit, skip=skip_reason)
if reason == "length":
if end:
return "ended_by_hook"
@@ -968,12 +966,10 @@ class Agent:
return "completed"
continue
- terminate = False
- for call in message.tool_calls:
- self._scope.check()
- result, step_end = await self._tool(call, response, tools, skip or end, emit)
- terminate = terminate or result.terminate
- end = end or step_end
+ terminate, step_end = await self._calls(
+ message.tool_calls, response, tools, emit, skip=_SKIPPED if skip or end else None
+ )
+ end = end or step_end
if end:
return "ended_by_hook"
if terminate:
@@ -1003,49 +999,101 @@ class Agent:
if isinstance(decision, Deny):
return call, ToolResult((text(decision.reason),), is_error=True), False
if isinstance(decision, End):
- return call, ToolResult((text("[skipped by policy]"),), is_error=True), True
+ return call, ToolResult((text(_SKIPPED),), is_error=True), True
if isinstance(decision, AlterArgs):
call = replace(call, arguments=deepcopy(decision.arguments))
return call, None, False
- async def _tool(
+ @staticmethod
+ def _groups(calls: Sequence[ToolCallBlock], tools: Mapping[str, Tool]) -> list[list[ToolCallBlock]]:
+ """C-3 section 2: each maximal run of consecutive concurrent calls is one group, and every other call is a
+ group of its own. A call to a tool that is not available runs nothing, so it never splits a group."""
+ groups: list[list[ToolCallBlock]] = []
+ joins = False
+ for call in calls:
+ tool = tools.get(call.name)
+ concurrent = tool is None or getattr(tool, "concurrent", False) is True
+ if concurrent and joins:
+ groups[-1].append(call)
+ else:
+ groups.append([call])
+ joins = concurrent
+ return groups
+
+ async def _calls(
self,
- original: ToolCallBlock,
+ calls: Sequence[ToolCallBlock],
response: ContextEntry,
tools: Mapping[str, Tool],
- skip: bool,
emit: Callable[..., Awaitable[None]],
*,
- skip_reason: str | None = None,
- ) -> tuple[ToolResult, bool]:
- call = deepcopy(original)
- end = False
- result = None
- if skip:
- result = ToolResult((text(skip_reason or "[skipped by policy]"),), is_error=True)
- else:
- call, result, end = await self._gate(call, self.hooks)
- await emit(
- ToolStarted,
- tool_call_id=call.id,
- name=call.name,
- preview=json.dumps(call.arguments, ensure_ascii=False)[:500],
- )
- if result is None:
- tool = tools.get(call.name)
- if tool is None:
- result = ToolResult((text(f"Tool {call.name} is not available."),), is_error=True)
- else:
- instance = CallInstance(response.session_id, response.row_id, response.context_seq, call.id)
- result = await self._execute(tool, call, instance, emit)
- if not end and not skip:
- for hook in self.hooks:
- decision = await self._hook(lambda: hook.after_tool(call, result, self._ctx))
- if isinstance(decision, End):
- end = True
- break
- if isinstance(decision, AlterResult):
- result = decision.result
+ skip: Optional[str] = None,
+ ) -> tuple[bool, bool]:
+ """A response's calls, group after group (C-3 sections 2 and 3): whether a result terminates the run, and
+ whether a hook ended it. ``skip`` settles every call with that text instead, one at a time, running none."""
+ terminate = end = False
+ for group in [[call] for call in calls] if skip is not None else self._groups(calls, tools):
+ self._scope.check()
+ # Every gate of the group runs before any of its calls starts: (call, result, whether after_tool runs).
+ gated: list[tuple[ToolCallBlock, Optional[ToolResult], bool]] = []
+ for original in group:
+ call = deepcopy(original)
+ if skip is not None or end:
+ gated.append((call, ToolResult((text(skip or _SKIPPED),), is_error=True), False))
+ continue
+ call, result, ended = await self._gate(call, self.hooks)
+ if result is None and call.name not in tools:
+ result = ToolResult((text(f"Tool {call.name} is not available."),), is_error=True)
+ gated.append((call, result, not ended))
+ end = end or ended
+ running: dict[int, asyncio.Task[ToolResult]] = {}
+ try:
+ for index, (call, result, _) in enumerate(gated):
+ await emit(
+ ToolStarted,
+ tool_call_id=call.id,
+ name=call.name,
+ preview=json.dumps(call.arguments, ensure_ascii=False)[:500],
+ )
+ if result is None:
+ instance = CallInstance(response.session_id, response.row_id, response.context_seq, call.id)
+ running[index] = asyncio.create_task(self._execute(tools[call.name], call, instance, emit))
+ # Results commit in call order. After an after_tool ``end``, the group's later calls have started
+ # already: they still pass after_tool and commit their real results.
+ for index, (call, result, after) in enumerate(gated):
+ if index in running:
+ result = await running[index]
+ if after:
+ for hook in self.hooks:
+ decision = await self._hook(lambda: hook.after_tool(call, result, self._ctx))
+ if isinstance(decision, End):
+ end = True
+ break
+ if isinstance(decision, AlterResult):
+ result = decision.result
+ await self._commit_result(call, result, emit)
+ terminate = terminate or result.terminate
+ finally:
+ await self._join(running.values())
+ return terminate, end
+
+ @staticmethod
+ async def _join(calls: Iterable[asyncio.Task]) -> None:
+ """No call outlives its batch: the calls still running are cancelled, and every one is awaited."""
+ calls = tuple(calls)
+ for task in calls:
+ if not task.done():
+ task.cancel()
+ joined = asyncio.gather(*calls, return_exceptions=True)
+ try:
+ await asyncio.shield(joined)
+ except asyncio.CancelledError:
+ await joined
+ raise
+
+ async def _commit_result(
+ self, call: ToolCallBlock, result: ToolResult, emit: Callable[..., Awaitable[None]]
+ ) -> None:
message = ToolResultMessage(call.id, call.name, result.content, result.is_error)
validate_message_append(self._rows, session_id=self.session_id, kind="tool_result", message=message)
await self._save_state()
@@ -1061,7 +1109,6 @@ class Agent:
is_error=result.is_error,
watch_id=result.details.get("watch_id"),
)
- return result, end
async def _execute(
self,
diff --git a/core/agent_core/tools/base.py b/core/agent_core/tools/base.py
index f10a8aa65..b51413778 100644
--- a/core/agent_core/tools/base.py
+++ b/core/agent_core/tools/base.py
@@ -66,6 +66,9 @@ class ToolResult:
class Tool(Protocol):
+ """``concurrent``, optional: ``True`` lets a call run at the same time as the neighbouring concurrent calls of its
+ response (C-3 loop-control.md section 2). A tool without it, or with ``False``, is exclusive."""
+
@property
def spec(self) -> ToolSpec: ...
diff --git a/core/agent_core/tools/bash.py b/core/agent_core/tools/bash.py
index 8504ea10f..fb2daa9f2 100644
--- a/core/agent_core/tools/bash.py
+++ b/core/agent_core/tools/bash.py
@@ -186,6 +186,8 @@ async def settle_bash_call(jobs: LocalJobHost, call: CallInstance) -> Optional[T
class BashTool:
"""``jobs`` is the loop's tracking wrapper around the adapter's host; ``bash`` never makes its own."""
+ concurrent = True
+
def __init__(self, jobs: JobHost, *, foreground_window_s: float = DEFAULT_FOREGROUND_WINDOW_S) -> None:
self._jobs = jobs
self._window_s = foreground_window_s
diff --git a/core/agent_core/tools/read.py b/core/agent_core/tools/read.py
index 601debf6a..b73a7814c 100644
--- a/core/agent_core/tools/read.py
+++ b/core/agent_core/tools/read.py
@@ -69,6 +69,8 @@ READ_SCHEMA: Mapping[str, Any] = {
class ReadTool:
+ concurrent = True
+
def __init__(self, *, image_sink: Optional[ImageSink] = None) -> None:
self._image_sink = image_sink
self._spec = ToolSpec(name="read", description=READ_DESCRIPTION, input_schema=READ_SCHEMA)
diff --git a/docs/plans/agent-core-contracts/conversion-tables.md b/docs/plans/agent-core-contracts/conversion-tables.md
index 46f622f3d..7dfcbbb6d 100644
--- a/docs/plans/agent-core-contracts/conversion-tables.md
+++ b/docs/plans/agent-core-contracts/conversion-tables.md
@@ -29,6 +29,7 @@ rules on top of those mappings.
| Partial and abort | The shared `partial_message` policy is used by all three adapters. Usage captured before the first visible delta is retained, and errors/abort carry an assembled `AssistantMessage` whenever visible content or usage exists; empty placeholder slots alone do not count as streamed output, while non-empty terminal snapshots do. Consumer/task cancellation is preserved even if response cleanup fails. |
| Retry admission | `RetryPolicy.delay` in `core/agent_core/agent/models.py` applies only the bounded retry count/time budget and obeys `ProviderError.retryable`; it does not reject a usage-only partial or infer a second streamed-output boundary. A retry-admitted usage-only partial is never context: the retry resends the original request, and the attempt's usage is one non-context `ModelAttempt` audit row, in every mode (C-9 `context.md` §10, invariant 4), so per-attempt usage is kept without adding prompt attempts together in one response. `test_retry_obeys_provider_flag_and_allows_usage_only_partial` and `test_retry_keeps_a_usage_only_partial_out_of_the_context` are the loop proofs. |
| Tool-call stop normalization | `StreamAssembler.finalize` changes only `stop` with one or more tool calls to canonical `tool_use`, following Pi. The loop admits execution only for `stop_reason="tool_use"`; calls attached to `length`, `safety`, `refusal`, or `error` are settled as `is_error` results explaining the stop reason. |
+| Parallel tool calls | No request turns them off, so a response may carry several calls: Anthropic Messages sends no `tool_choice`, so `disable_parallel_tool_use` keeps its default `false`; Chat Completions and Responses send no `parallel_tool_calls`, which defaults to `true`; a `google` hop is called over Chat Completions at the Model Hub gateway (`modules/agents/vibey/models.py`), whose translation to Gemini sets no `toolConfig` for such a request. No request may send `parallel_tool_calls: false`: Gemini has no switch for it, and the gateway's engine (CLIProxyAPI `c404af96`, `internal/translator/gemini/openai/chat-completions/gemini_openai_request.go`) then turns every tool off. The loop runs neighbouring concurrent calls at the same time and every `edit` or `write` alone (C-3 `loop-control.md` §2), a deviation from Pi, which runs a response's calls at once and serializes mutations only per file path. |
## Shared stream assembler and dispatch ledger
diff --git a/docs/plans/agent-core-contracts/fork.md b/docs/plans/agent-core-contracts/fork.md
index 49ae6bd18..4b71cb587 100644
--- a/docs/plans/agent-core-contracts/fork.md
+++ b/docs/plans/agent-core-contracts/fork.md
@@ -327,7 +327,8 @@ turn runs inside the caller's run, in these steps:
3. **Execution.** A scratch write goes through the root's descriptor, as joined work that an abort waits for.
4. **The bound.** The result is cut to `room - room_slack`.
- The policy's fixed texts are never cut.
+ The policy's fixed texts are never cut. A response's calls take this pipeline one at a time, in call order, never
+ in the run's concurrent groups (C-3 §2): each call's `room` depends on the results before it.
4. **End.** A response that stops with `stop` and calls no tool is the reply. Anything else fails the turn: an
overflow, an error, a response refused at admission, a length stop, or calls after the budget closed.
5. **Fold.** The caller's `fold(reply)` decides what enters the caller's context, if anything, and commits it. For
diff --git a/docs/plans/agent-core-contracts/loop-control.md b/docs/plans/agent-core-contracts/loop-control.md
index f3e4a1953..a2f8bbb9a 100644
--- a/docs/plans/agent-core-contracts/loop-control.md
+++ b/docs/plans/agent-core-contracts/loop-control.md
@@ -34,7 +34,10 @@ commit input → loop:
→ provider stream (events out) → admission of the response
if the response has tool calls:
commit it as `assistant`
- for each call, in order: before_tool → execute → after_tool → commit tool result
+ for each group of calls, in call order (below):
+ before_tool for each call of the group, in call order
+ start the calls the gates let run, in call order; they run at the same time
+ for each call of the group, in call order: its result → after_tool → commit tool result
drain steers (commit each) → continue loop
else, holding the queue lock:
if a steer or follow-up is pending: commit the response as `assistant`, commit the pending inputs,
@@ -51,7 +54,31 @@ delivers committed rows through the shared emit path and nothing re-delivers the
steer that arrives after the queues closed is refused by the running Turn, and Avibe's delivery falls back to the P3
queue, which starts the next run.
-Tool calls in one response execute sequentially in call order in v1; results are always committed in call order.
+**The calls of one response.** Each tool says whether its calls may run concurrently (`Tool.concurrent`, C-7
+[`tools.md`](tools.md)); a tool that does not is exclusive. The loop walks the calls in call order: a maximal run of
+consecutive concurrent calls is one group, whose calls run at the same time, and every exclusive call is a group of its
+own. Groups run one after another. So an exclusive call starts only after every call before it has finished, and no
+call after it starts until it has finished: a reader-writer lock taken in call order, as Codex's `tools/parallel.rs`
+does. Whenever an `edit` or `write` is involved, the observable result equals running the calls one by one;
+concurrency only ever applies between neighbouring `read` and `bash` calls. A call to a tool that is not available runs
+nothing and never splits a group.
+
+- `tool_started` is emitted when a call starts. Results commit in call order: a call that finishes early waits for the
+ calls before it, and `tool_finished` follows the commits.
+- One call failing, by an exception (which becomes its error result) or by an error result, never cancels another
+ call.
+- No call outlives its batch: every call is awaited or cancelled before the run moves on or ends.
+- There is no cap on how many calls run at once, as in Pi and Codex.
+- Calls that run nothing keep one-at-a-time order: those of a response that stopped at its output limit, and those an
+ `after_model` `skip_tools` or `end` settles.
+- A side turn (C-10 [`fork.md`](fork.md) §7) runs its calls one at a time, in call order, and never through groups:
+ the room each call gets depends on the results before it.
+
+Pi differs (`packages/agent/src/agent-loop.ts` at `7fbbd5f`): it runs every call of a response at the same time unless
+a tool in it declares `executionMode: "sequential"`, and its `edit` and `write` serialize only per file path
+(`withFileMutationQueue`), which `bash` bypasses. Avibe makes mutations exclusive instead, so a command never races an
+edit and never sees a batch of edits half applied. `file_mutation_lock` (`tools/paths.py`) still serializes `edit` and
+`write` across Sessions and forks in the same process.
## 3. Hooks
@@ -71,6 +98,16 @@ reconstructible from the rows, and A10 is stated for requests without a transien
a restart, or that context management must see, goes through C-5 rows (`context_edit`, `context_compaction`). `end`
finishes the run after the current step commits.
+The tool hooks follow the groups of §2:
+
+- `before_tool` runs for each call, in call order, before that call starts. A group's gates all run before the group
+ starts, so no gate sees a result from its own group. `deny` and `alter_args` affect only their call. An `end`
+ settles its call and every later call `[skipped by policy]`; the calls before it in its group still run.
+- `after_tool` runs for each call, in call order, when its result is available, before its commit. An `end` settles
+ every call that has not started `[skipped by policy]`. The later calls of its group have already started: they
+ finish, pass `after_tool`, and commit their real results, because their effects happened and the committed result
+ is the truthful record.
+
In v1 an Agent with a C-9 `ContextConfig` takes no user hooks: passing both is a configuration error, because C-9
owns the request and the checkpoint turn's tools. Hooks with context management are a post-v1 design item
(`context.md` §10, plan §10).
@@ -82,9 +119,10 @@ owns the request and the checkpoint turn's tools. Hooks with context management
running tool. Avibe P1 deliveries map to `steer`.
- `follow_up(m)` enters only when the run would otherwise end. It exists for hooks and the future tension system;
Avibe's P3 queue starts a new run after the Turn settles instead.
-- `abort(reason)` cancels the provider stream and the running tool: a foreground job's process tree is killed (Pi's
- behavior). Jobs already handed to Watch are not affected. The run ends with `run_ended{reason: "aborted"}`; what was
- committed stays committed.
+- `abort(reason)` cancels the provider stream and every running tool call of the batch: each foreground job's process
+ tree is killed (Pi's behavior). Jobs already handed to Watch are not affected. The run ends with
+ `run_ended{reason: "aborted"}`; what was committed stays committed, and T2 ([`recovery.md`](recovery.md)) gives each
+ call left open exactly one result.
- A tool result with `terminate: true` ends the run after the batch commits.
## 5. Tools per call
diff --git a/docs/plans/agent-core-contracts/recovery.md b/docs/plans/agent-core-contracts/recovery.md
index fe6d1cc34..4d7c1fc62 100644
--- a/docs/plans/agent-core-contracts/recovery.md
+++ b/docs/plans/agent-core-contracts/recovery.md
@@ -24,7 +24,7 @@ at-least-once, and that is stated where it applies.
| ID | Invariant | Proof |
| --- | --- | --- |
| T1 | `project()` reads only committed rows; the same rows always produce the same request. | projection before and after job state changes |
-| T2 | At resume, before the first projection, and when a run ends without completing (a Stop), every tool call without a committed `tool_result` gets exactly one, chosen from the state of the job its call instance started (exited: the output; running: handover; stopped with a recorded reason: that result; never ran: the interrupted result). A call without job state (`write`, `edit`) gets `[tool call interrupted; it may or may not have completed; re-read the file before continuing]`. Retries settle nothing twice, and neither do concurrent writers: the store's `append_tool_result` returns the result already committed for the call instance instead of writing a second. | crash between settlement steps, then resume twice |
+| T2 | At resume, before the first projection, and when a run ends without completing (a Stop), every tool call without a committed `tool_result` gets exactly one, chosen from the state of the job its call instance started (exited: the output; running: handover; stopped with a recorded reason: that result; never ran: the interrupted result). A call without job state (`write`, `edit`) gets `[tool call interrupted; it may or may not have completed; re-read the file before continuing]`. Retries settle nothing twice, and neither do concurrent writers: the store's `append_tool_result` returns the result already committed for the call instance instead of writing a second. | crash between settlement steps, then resume twice; a Stop while several calls of one group (C-3 §2) run |
| T3 | Inputs accepted by `steer` or `follow_up` are never dropped: they enter the context, including after a crash. They belong to the Turn that accepted them and are never re-queued as a new P3 Turn. A run that ended by design runs again for them within its Turn; after a stop, an error, or a crash they are admitted into the context (at the end of the run, or at the Session's resume) and share the Turn's outcome. | a terminating tool while a steer is queued; a crash before consumption |
| T4 | An unsettled Turn found at startup is settled as interrupted after T2; the agent never continues it on its own (a hook `end`, an abort, or a crash all leave the same safe state). The user's next message starts a new Turn with the full context. When T2 handed the Turn's running commands to Watches, its notice names them and offers no Retry, because a resend would run them twice. | crash after an `end` hook and after a mid-turn commit |
diff --git a/docs/plans/agent-core-contracts/tools.md b/docs/plans/agent-core-contracts/tools.md
index 3ffed88cf..def3fdf17 100644
--- a/docs/plans/agent-core-contracts/tools.md
+++ b/docs/plans/agent-core-contracts/tools.md
@@ -5,6 +5,11 @@ The coding tools in `core/agent_core/tools/`. Names, parameters, logic, and mode
are Pi's unless marked as an Avibe addition. tau 0.4.7 (MIT, Copyright (c) 2026 Alejandro AO) is the Python
reference. One tool set serves every model.
+`Tool.concurrent` (Avibe) says whether a tool's calls may run at the same time as the neighbouring concurrent calls of
+the same response (C-3 [`loop-control.md`](loop-control.md) §2). When it is absent or `False`, every call of the tool
+is exclusive. `read` and `bash` are concurrent; `write` and `edit` are exclusive. Pi instead runs a response's calls at
+the same time unless a tool opts out, and serializes `write` and `edit` only per file path, which `bash` bypasses.
+
## 1. Constants
| Name | Value |
diff --git a/modules/agents/vibey/prompt.py b/modules/agents/vibey/prompt.py
index 8ed98e11b..a48d29767 100644
--- a/modules/agents/vibey/prompt.py
+++ b/modules/agents/vibey/prompt.py
@@ -54,6 +54,12 @@ TOOL_GUIDELINES: dict[str, tuple[str, ...]] = {
}
TOOL_ORDER = ("read", "bash", "edit", "write")
FINAL_REPLY_RULE = "Only your final reply is reliably shown to the user; put anything the user must see in it"
+#: Avibe's: the loop runs a response's neighbouring read and bash calls at the same time (C-3 loop-control.md section 2).
+CONCURRENT_CALLS_RULE = (
+ "Send independent calls (reads, searches, separate commands) together in one response: they run at the same "
+ "time. Edits and writes run one at a time, in order. A call that needs an earlier call's result goes in a later "
+ "response"
+)
#: The first input of a fork (C-10 fork.md section 8): the inherited history is the source's, and so is its work.
FORK_NOTICE = (
"<fork>\nThis Session is a fork of {title} (Session {source}): {history}. Every command, Watch, Task, and run "
@@ -76,6 +82,8 @@ def coding_prompt(tool_names: Iterable[str], *, rg: bool) -> str:
rules.append(f"Use bash for file operations like ls, {'rg' if rg else 'grep'}, find")
for name in names:
rules.extend(TOOL_GUIDELINES.get(name, ()))
+ if names:
+ rules.append(CONCURRENT_CALLS_RULE)
rules += ["Be concise in your responses", "Show file paths clearly when working with files", FINAL_REPLY_RULE]
return "\n\n".join(
(
diff --git a/tests/agent_core/agent/test_loop.py b/tests/agent_core/agent/test_loop.py
index 37e05ed9b..c44409c3b 100644
--- a/tests/agent_core/agent/test_loop.py
+++ b/tests/agent_core/agent/test_loop.py
@@ -1549,3 +1549,234 @@ async def test_admitted_commit_finishes_before_cancellation_releases_run_ownersh
assert rows[-1].kind == "response"
assert agent.snapshot().context_seq == rows[-1].context_seq
assert await agent.steer(input_row("late", "late")) is False
+
+
+
+# --- The calls of one response (C-3 section 2) ------------------------------------------------------------------------
+#
+# ``ConcurrentTool`` declares ``concurrent`` as C-7 ``read`` and ``bash`` do; ``FakeTool`` is exclusive, as ``edit`` and
+# ``write`` are. A call that cannot finish until its siblings arrive proves that they run at the same time: run one at a
+# time, the first never finishes, and ``wait_for`` turns that deadlock into a failure.
+
+
+class ConcurrentTool(FakeTool):
+ concurrent = True
+
+
+class Gathering:
+ """Lets every caller through once ``parties`` calls have arrived."""
+
+ def __init__(self, parties: int) -> None:
+ self.parties, self.arrived, self.complete = parties, [], asyncio.Event()
+
+ async def arrive(self, name: str) -> None:
+ self.arrived.append(name)
+ if len(self.arrived) == self.parties:
+ self.complete.set()
+ await self.complete.wait()
+
+
+def calls(*specs: str) -> list[ToolCallBlock]:
+ """``"a:read"`` is call ``a`` to ``read``."""
+ return [ToolCallBlock(*spec.split(":")) for spec in specs]
+
+
+def tool_agent(response_calls, tools, *, hooks=(), then=([Done(assistant())],)):
+ return make_agent(ScriptedProvider([[Done(assistant(calls=response_calls))], *then]), tools=tools, hooks=hooks)
+
+
+def tool_events(events) -> list[tuple[str, str]]:
+ return [
+ ("started" if isinstance(event, ToolStarted) else "finished", event.tool_call_id)
+ for event in events
+ if isinstance(event, (ToolStarted, ToolFinished))
+ ]
+
+
+async def committed_results(agent) -> list[tuple[str, str, bool]]:
+ rows = await agent.store.load("session")
+ return [
+ (row.message.tool_call_id, row.message.content[0].text, row.message.is_error)
+ for row in rows
+ if row.kind == "tool_result"
+ ]
+
+
+async def test_neighbouring_concurrent_calls_start_together_and_commit_in_call_order():
+ gathering, finished, others_finished = Gathering(3), [], asyncio.Event()
+
+ async def execute(arguments, ctx):
+ await gathering.arrive(ctx.tool_call_id)
+ if ctx.tool_call_id == "a":
+ await others_finished.wait() # the first call finishes last
+ finished.append(ctx.tool_call_id)
+ if len(finished) == 2:
+ others_finished.set()
+ return ToolResult((text(f"{ctx.tool_call_id} done"),))
+
+ tools = [ConcurrentTool("read", execute=execute), ConcurrentTool("bash", execute=execute)]
+ agent = tool_agent(calls("a:read", "b:read", "c:bash"), tools)
+ events = await asyncio.wait_for(collect(agent), 5)
+
+ assert finished[-1] == "a"
+ assert tool_events(events) == [
+ ("started", "a"), ("started", "b"), ("started", "c"),
+ ("finished", "a"), ("finished", "b"), ("finished", "c"),
+ ]
+ assert [event.seq for event in events] == list(range(len(events)))
+ assert await committed_results(agent) == [("a", "a done", False), ("b", "b done", False), ("c", "c done", False)]
+ assert events[-1].reason == "completed"
+
+
+async def test_an_exclusive_call_starts_after_the_calls_before_it_and_holds_the_calls_after_it():
+ gathering, running, seen = Gathering(2), set(), {}
+
+ async def execute(arguments, ctx):
+ seen[ctx.tool_call_id] = set(running) # what was still running when this call started
+ running.add(ctx.tool_call_id)
+ if ctx.tool_call_id in {"r1", "r2"}:
+ await gathering.arrive(ctx.tool_call_id)
+ running.discard(ctx.tool_call_id)
+ return ToolResult((text(ctx.tool_call_id),))
+
+ tools = [ConcurrentTool("read", execute=execute), FakeTool("edit", execute=execute), FakeTool("write", execute=execute)]
+ agent = tool_agent(calls("r1:read", "r2:read", "e:edit", "r3:read", "w1:write", "w2:write"), tools)
+ events = await asyncio.wait_for(collect(agent), 5)
+
+ # The groups are [r1, r2], [e], [r3], [w1], [w2]; each starts after the one before it has committed.
+ assert tool_events(events) == [
+ ("started", "r1"), ("started", "r2"), ("finished", "r1"), ("finished", "r2"),
+ ("started", "e"), ("finished", "e"),
+ ("started", "r3"), ("finished", "r3"),
+ ("started", "w1"), ("finished", "w1"),
+ ("started", "w2"), ("finished", "w2"),
+ ]
+ assert {name: seen[name] for name in ("e", "r3", "w1", "w2")} == {"e": set(), "r3": set(), "w1": set(), "w2": set()}
+
+
+async def test_a_groups_gates_run_before_it_starts_and_each_decides_only_its_call():
+ gathering, gates = Gathering(2), []
+
+ class Gate(Hooks):
+ async def before_tool(self, call, ctx):
+ gates.append((call.id, list(gathering.arrived)))
+ return {"b": Deny("denied"), "c": AlterArgs({"altered": True}), "d": End()}.get(call.id)
+
+ async def execute(arguments, ctx):
+ await gathering.arrive(ctx.tool_call_id)
+ return ToolResult((text(f"{ctx.tool_call_id} {dict(arguments)}"),))
+
+ read, edit = ConcurrentTool("read", execute=execute), FakeTool("edit")
+ agent = tool_agent(calls("a:read", "b:read", "c:read", "d:read", "f:read", "e:edit"), [read, edit], hooks=[Gate()])
+ events = await asyncio.wait_for(collect(agent), 5)
+
+ # No call had started when a gate ran. The end at d settles d and every later call; a and c, before it in the
+ # group, still ran, together.
+ assert gates == [("a", []), ("b", []), ("c", []), ("d", [])]
+ assert await committed_results(agent) == [
+ ("a", "a {}", False),
+ ("b", "denied", True),
+ ("c", "c {'altered': True}", False),
+ ("d", "[skipped by policy]", True),
+ ("f", "[skipped by policy]", True),
+ ("e", "[skipped by policy]", True),
+ ]
+ assert [ctx.tool_call_id for _, ctx in read.calls] == ["a", "c"] and edit.calls == []
+ assert events[-1].reason == "ended_by_hook"
+
+
+async def test_an_after_tool_end_lets_the_calls_already_running_commit_their_real_results():
+ b_running, release_b, after = asyncio.Event(), asyncio.Event(), []
+
+ class Stop(Hooks):
+ async def after_tool(self, call, result, ctx):
+ after.append(call.id)
+ if call.id == "a":
+ await b_running.wait()
+ release_b.set()
+ return End()
+ return AlterResult(replace(result, content=(text(result.content[0].text + " seen"),)))
+
+ async def execute(arguments, ctx):
+ if ctx.tool_call_id == "b":
+ b_running.set()
+ await release_b.wait()
+ return ToolResult((text(f"{ctx.tool_call_id} done"),))
+
+ read, edit = ConcurrentTool("read", execute=execute), FakeTool("edit", execute=execute)
+ agent = tool_agent(calls("a:read", "b:read", "e:edit"), [read, edit], hooks=[Stop()])
+ events = await asyncio.wait_for(collect(agent), 5)
+
+ # b was running when a's hook ended the run: it finishes, passes after_tool, and commits what it did. The edit
+ # had not started, so it never runs.
+ assert after == ["a", "b"]
+ assert await committed_results(agent) == [
+ ("a", "a done", False),
+ ("b", "b done seen", False),
+ ("e", "[skipped by policy]", True),
+ ]
+ assert edit.calls == []
+ assert events[-1].reason == "ended_by_hook"
+
+
+async def test_a_failing_or_unavailable_call_never_cancels_its_group():
+ gathering = Gathering(2)
+
+ async def execute(arguments, ctx):
+ await gathering.arrive(ctx.tool_call_id)
+ if ctx.tool_call_id == "a":
+ raise RuntimeError("a broke")
+ return ToolResult((text("b done"),))
+
+ # The unavailable call between a and b runs nothing and does not split their group.
+ agent = tool_agent(calls("a:read", "x:missing", "b:read"), [ConcurrentTool("read", execute=execute)])
+ events = await asyncio.wait_for(collect(agent), 5)
+
+ assert await committed_results(agent) == [
+ ("a", "a broke", True),
+ ("x", "Tool missing is not available.", True),
+ ("b", "b done", False),
+ ]
+ assert events[-1].reason == "completed"
+
+
+async def test_no_call_outlives_its_batch_when_the_run_fails_while_a_group_runs():
+ b_running, cancelled = asyncio.Event(), []
+
+ class Store(InMemoryTranscriptStore):
+ async def append_tool_result(self, *args, **kwargs):
+ raise RuntimeError("the store refused the result")
+
+ async def execute(arguments, ctx):
+ if ctx.tool_call_id == "a":
+ await b_running.wait()
+ return ToolResult((text("a done"),))
+ b_running.set()
+ try:
+ await asyncio.Event().wait()
+ except asyncio.CancelledError:
+ cancelled.append(ctx.tool_call_id)
+ raise
+
+ before = asyncio.all_tasks()
+ provider = ScriptedProvider([[Done(assistant(calls=calls("a:read", "b:read")))]])
+ agent = make_agent(provider, store=Store(), tools=[ConcurrentTool("read", execute=execute)])
+ events = await asyncio.wait_for(collect(agent), 5)
+
+ # a's commit fails while b still runs: the run ends in error only after b was cancelled and awaited.
+ assert events[-1].reason == "error" and cancelled == ["b"]
+ assert {task for task in asyncio.all_tasks() - before if not task.done()} == set()
+
+
+async def test_a_terminating_call_ends_the_run_after_its_whole_group_commits():
+ gathering = Gathering(2)
+
+ async def execute(arguments, ctx):
+ await gathering.arrive(ctx.tool_call_id)
+ return ToolResult((text(ctx.tool_call_id),), terminate=ctx.tool_call_id == "a")
+
+ agent = tool_agent(calls("a:read", "b:read"), [ConcurrentTool("read", execute=execute)], then=())
+ events = await asyncio.wait_for(collect(agent), 5)
+
+ assert await committed_results(agent) == [("a", "a", False), ("b", "b", False)]
+ assert events[-1].reason == "completed" and len(agent.models.provider.requests) == 1
diff --git a/tests/test_vibey_agent.py b/tests/test_vibey_agent.py
index fbd7571af..0f670d231 100644
--- a/tests/test_vibey_agent.py
+++ b/tests/test_vibey_agent.py
@@ -22,7 +22,9 @@ from __future__ import annotations
import asyncio
import json
import os
+import struct
import time
+import zlib
from pathlib import Path
from types import SimpleNamespace
from typing import Any, Optional
@@ -33,7 +35,15 @@ from sqlalchemy import select, update
from core.agent_core.agent.recovery import UNRECORDED_EFFECT
from core.agent_core.ai.provider import Done
from core.agent_core.harness.projection import project
-from core.agent_core.messages import AssistantMessage, TextBlock, ToolCallBlock, ToolResultMessage, UserMessage, text
+from core.agent_core.messages import (
+ AssistantMessage,
+ ImageBlock,
+ TextBlock,
+ ToolCallBlock,
+ ToolResultMessage,
+ UserMessage,
+ text,
+)
from core.agent_core.tools.base import CallInstance, JobStatus, ToolResult
from core.message_dispatcher import ConsolidatedMessageDispatcher
from core.services.agent_steering import ActiveSteerTarget, SteerOutcome, SteerRequest
@@ -2139,6 +2149,98 @@ async def test_a_stop_settles_the_running_command_with_its_recorded_reason(engin
assert harness.controller.terminals == [{"turn": _turn(request.context), "is_error": False, "settled_by": "stopped"}]
+async def test_a_stop_kills_every_command_of_a_concurrent_group_and_settles_each_once(
+ engine, session, tmp_path, published
+) -> None:
+ calls = tuple(
+ ToolCallBlock(id=f"call_{name}", name="bash", arguments={"command": f"echo started {name}; sleep 30"})
+ for name in ("a", "b")
+ )
+ suite = local_tool_suite(str(tmp_path / "jobs"))
+ harness = _Harness(engine, tmp_path, "avibe", [[Done(assistant("", calls=calls))]], suite=suite)
+ request = harness.request("run both")
+ before = asyncio.all_tasks()
+
+ running = asyncio.create_task(harness.agent.handle_message(request))
+
+ def jobs() -> list[Optional[str]]:
+ responses = harness.rows("assistant")
+ if not responses:
+ return [None, None]
+ return [suite.find_job(CallInstance(SESSION, responses[0]["id"], responses[0]["context_seq"], call.id)) for call in calls]
+
+ # Both commands of the one group are running at once.
+ await _until(lambda: all(jobs()), "the commands never both started")
+ job_ids = jobs()
+ await _until(lambda: all(b"started" in suite.jobs.output(job)[0] for job in job_ids), "a command printed nothing")
+ assert await harness.agent.handle_stop(AgentRequest(**{**request.__dict__, "message": "stop"})) is True
+ await running
+
+ for job in job_ids:
+ assert suite.jobs.stop_reason(job) == "aborted" and suite.jobs.status(job).state != "running"
+ # Each call is settled exactly once, at Stop, with why its command ended (T2).
+ results = [entry for entry in await harness.context_rows() if entry.kind == "tool_result"]
+ assert [entry.message.tool_call_id for entry in results] == ["call_a", "call_b"]
+ for entry, name in zip(results, ("a", "b")):
+ body = entry.message.content[0].text
+ assert body.startswith(f"started {name}\n") and body.endswith("Stopped by the user; the command was terminated.")
+ assert harness.controller.terminals == [{"turn": _turn(request.context), "is_error": False, "settled_by": "stopped"}]
+ # No call outlived the batch: what is left is the adapter's own job pruning after the run.
+ left = {task.get_name() for task in asyncio.all_tasks() - before if not task.done()}
+ assert left <= {"vibey-agent-job-prune"}
+
+
+def _png(pixel: bytes) -> bytes:
+ """A 1x1 RGB PNG of ``pixel`` (its filter byte, then three channel bytes)."""
+
+ def chunk(kind: bytes, body: bytes) -> bytes:
+ return struct.pack(">I", len(body)) + kind + body + struct.pack(">I", zlib.crc32(kind + body))
+
+ header = chunk(b"IHDR", struct.pack(">IIBBBBB", 1, 1, 8, 2, 0, 0, 0))
+ return b"\x89PNG\r\n\x1a\n" + header + chunk(b"IDAT", zlib.compress(pixel)) + chunk(b"IEND", b"")
+
+
+async def test_images_read_together_reach_the_model_with_their_own_calls_in_call_order(
+ engine, session, tmp_path, published
+) -> None:
+ pictures = {"first": _png(b"\0\xff\0\0"), "second": _png(b"\0\0\xff\0")}
+ for name, data in pictures.items():
+ (tmp_path / f"{name}.png").write_bytes(data)
+ real = local_tool_suite(str(tmp_path / "jobs"))
+ second_stored = asyncio.Event()
+
+ def create_tools(jobs, sink):
+ async def later_call_first(data: bytes, mime_type: str, name: str) -> str:
+ # The first call's image is stored only after the second's: the later call finishes first.
+ if name == "first.png":
+ await second_stored.wait()
+ token = await sink(data, mime_type, name)
+ if name == "second.png":
+ second_stored.set()
+ return token
+
+ return real.create_tools(jobs, later_call_first)
+
+ suite = ToolSuite(
+ jobs=real.jobs, create_tools=create_tools, render_recovered=real.render_recovered, find_job=real.find_job
+ )
+ calls = tuple(ToolCallBlock(id=name, name="read", arguments={"path": f"{name}.png"}) for name in pictures)
+ harness = _Harness(
+ engine, tmp_path, "avibe", [[Done(assistant("", calls=calls))], [Done(assistant("Two pictures."))]], suite=suite
+ )
+
+ # Read one at a time, the first call would wait for the second forever.
+ await asyncio.wait_for(harness.agent.handle_message(harness.request("look at both")), 10)
+
+ results = [entry.message for entry in await harness.context_rows() if entry.kind == "tool_result"]
+ assert [message.tool_call_id for message in results] == ["first", "second"]
+ assert [message for message in harness.provider.requests[1].messages if isinstance(message, ToolResultMessage)] == results
+ for message, name in zip(results, pictures):
+ (image,) = [block for block in message.content if isinstance(block, ImageBlock)]
+ assert image.name == f"{name}.png"
+ assert (await harness.agent.media.load(image.media_token))[0] == pictures[name]
+
+
@pytest.mark.parametrize("state", ["exited", "running"])
async def test_resume_settles_a_real_bash_job_through_the_real_renderer(
engine, session, tmp_path, published, state