The Core Requirement
An AI agent needs the answer to a question, but a CLI returns a conversation with a terminal: progress messages, repeated warnings, formatting and useful facts mixed together. My requirement for Pump-Me is to move that interpretation into reusable automation, before the output reaches the model.
For a repository overview, the useful answer might be three values: the number of worktrees, the current branch and the number of source lines containing TODOs. The agent should generate a PowerShell task that calculates those values locally. It should consume one bounded result, with enough status information to tell whether that answer is trustworthy.
The agent authors the observation contract
An observation contract specifies what the agent needs to know and how the result qualifies that knowledge. For worktrees, it defines the count, paths, HEAD, branch and state flags, the conditions for an exact total, and the representation of an incomplete analysis. The agent chooses these requirements before implementing the parser.
The agent reads the relevant documentation, machine format, help or source, then implements that contract in a provider. The provider can parse structured records, normalize values and calculate domain summaries. It returns named properties in .Data inside the common outcome and truncation envelope. The task consumes those properties directly, without asking the model to interpret the CLI's formatted text on every request.
There are two reusable layers. The provider exposes a coherent capability, such as listing worktrees with completion information. The task selects and combines the fields required for a particular question. A new question can project different fields from the same provider; genuinely missing functionality or semantics calls for extending the provider and its tests.
This is the central design choice: the AI participates in building the interface through which it observes a tool. Each implementation becomes inspectable user code, available for review, version control and reuse. The first request pays for research and validation; later requests can reuse that investment while the supported tool format remains valid.
The requirement given to the agent
The agent writes a .ps1 script for the request. Each CLI operation goes through a verified pump route. Each result consumed locally goes through Invoke-OutputPumpStep, so assigning it to a variable cannot hide failure or truncation from the task. The generated caller aggregates the task and serializes one compact JSON document.
When a route or required business field is missing, the agent first builds or extends a reusable provider from the tool's documented machine format. It tests the parser, publishes its catalogue and software sheet, activates it, and only then runs the task. Documentation and fixtures record the supported format so future requests can discover and reuse it. A tool or contract change requires revalidation.
This is the purpose of Pump-Me.PoSh as an approach. The implemented shared engine is the OutputPump.PoSh module inside FrenchExDev.OutputPumps.PoSh; independent FrenchExDev.OPumper.*.PoSh projects supply the tool-specific behavior.
A decision needs data and a qualification
A short answer can still be wrong. An empty search after an unreadable directory does not establish that there are no matches. A two-record preview does not establish that only two records exist. A process that has exited may still have unread stream data.
The contract must therefore preserve:
- Useful domain fields, such as branch, HEAD, paths and exact counts where available.
- Success, failure, timeout and unsupported-request outcomes.
- Explicit preview and serialization omissions.
- Completion information, with unknown totals represented by null.
- Retry advice that explains whether a narrower request or a corrected request is needed.
The AI reads .Data for the business answer and .Error, .Outcome, .RetryAdvice and .Truncation for its qualification. There is no .Context field in the implemented envelope.
Bound the task as well as each call
Twenty calls with an 8 KiB allowance can exceed the useful context for the entire question. The engine already provides task aggregation: Invoke-OutputPumpTask records steps, limits projections and diagnostic issues, and emits one bounded envelope.
The main walkthrough uses a 2 KiB task budget. Its intermediate objects stay inside the script. A separate verification exercises twenty steps under 1 KiB, including assigned failures, a late failure, a timeout and duplicate envelope emission.
A byte allowance is a reproducible transport limit. It is not a tokenizer-specific token count. The practical goal remains fewer output tokens reaching the AI while retaining the facts required for a sound decision.
The executable question
The series answers:
How many worktrees does this repository have, what branch am I on, and how many source lines contain TODO?
Git status and ripgrep are available. The inspected Git provider has no git worktree list route. We supply that route in a separate GitWorktrees provider, using Git's machine format, then combine the three results.
This small question exercises the essential lifecycle: discovery, implementation, validation, registration, task generation, local composition and reuse. It also exposes the limits honestly: exact counts require complete analysis, a preview can be omitted, and provider authoring has a cost.