| 1 | # parallel.py DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own the `parallel.py` agent tool. |
| 6 | - This tool wraps independent tool calls so they can be started together, awaited by job ID, collected, or canceled. |
| 7 | - Keep this file-level DOX profile synchronized with `parallel.py` because this directory is intentionally flat. |
| 8 | |
| 9 | ## Ownership |
| 10 | |
| 11 | - `parallel.py` owns the runtime implementation. |
| 12 | - `parallel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation. |
| 13 | - Classes: |
| 14 | - `ParallelTool` (`Tool`) |
| 15 | - `async execute(self, tool_calls=..., calls=..., items=..., job_ids=..., wait=..., action=..., timeout=..., **kwargs)` |
| 16 | - `async before_execution(self, **kwargs)` |
| 17 | - `async after_execution(self, response, **kwargs)` |
| 18 | |
| 19 | ## Runtime Contracts |
| 20 | |
| 21 | - Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`. |
| 22 | - Wrapped items use the same schema as normal tool calls: a tool name plus arguments. |
| 23 | - The tool is intended for independent calls only; dependent operations remain sequential. |
| 24 | - Independent calls should share one batch even when they use different tools; split only for dependencies, ordering, shared mutable state, or parent-context state/tool-availability changes. |
| 25 | - `document_query` is intentionally excluded from wrapped calls because it is too heavy for parallel workers and must be called sequentially. |
| 26 | - `response` is excluded because a wrapped response cannot end the parent message loop; final responses must be top-level calls. |
| 27 | - `action="start"` starts calls and optionally waits according to `wait`. |
| 28 | - `action="await"` waits for requested job IDs until completion or `timeout`; timeout returns running job handles without canceling them. |
| 29 | - `action="collect"` returns completed job results without waiting. |
| 30 | - `action="cancel"` requests cancellation for requested job IDs. |
| 31 | - Recursive use of `parallel` from inside a direct background tool worker is blocked before execution; numbered subordinate child chats can use normal child-chat tools, including `parallel`, to create their next-level descendants. |
| 32 | - Wrapped `call_subordinate` uses the same lifecycle as a top-level call. `job_id` identifies one parallel invocation, while its returned `context_id` identifies the reusable child agent for later `reset=false` calls. |
| 33 | - The wrapper tool does not create its own visible process-step log; each wrapped child call owns the visible log row, and the wrapper result is recorded only in model history. |
| 34 | - Terminal direct jobs are collected after the wrapper result enters model history. Any explicitly queued parent-history messages are appended next, preserving result-before-content ordering for native multimodal tools. |
| 35 | |
| 36 | ## Key Concepts |
| 37 | |
| 38 | - `tool_calls`, `calls`, and `items` are accepted aliases for the wrapped call list; a valid JSON string encoding of the list is tolerated for provider/model recovery. |
| 39 | - Wrapped call items can use the same `tool_name`/`tool_args` shape as top-level agent replies; extra planning fields are ignored by normalization. |
| 40 | - `job_ids` can be supplied as a string or list when awaiting, collecting, or canceling existing jobs. |
| 41 | - The response is compact JSON intended for the model to read and continue with. |
| 42 | - Visible child rows are emitted by `helpers/parallel_tools.py` before each background job starts. |
| 43 | |
| 44 | ## Work Guidance |
| 45 | |
| 46 | - Keep output concise enough for message history while preserving job IDs, statuses, and results. |
| 47 | - Coordinate tool argument or output changes with `prompts/agent.system.tool.parallel.md`, prompt contract tests, and helper tests. |
| 48 | - Avoid adding tool-specific execution logic here; shared execution behavior belongs in `helpers/parallel_tools.py`. |
| 49 | |
| 50 | ## Verification |
| 51 | |
| 52 | - Run targeted tool and prompt-contract tests after changing behavior. |
| 53 | - Run a live WebUI or CLI chat that invokes `parallel` with multiple subordinate jobs. |
| 54 | |
| 55 | ## Child DOX Index |
| 56 | |
| 57 | No child DOX files. |