Skip to content

Add async process run action - #99

Open
k2v7n24cbf-cyber wants to merge 2 commits into
sandydasari:mainfrom
k2v7n24cbf-cyber:agent/process-run-and-wait-tool
Open

Add async process run action#99
k2v7n24cbf-cyber wants to merge 2 commits into
sandydasari:mainfrom
k2v7n24cbf-cyber:agent/process-run-and-wait-tool

Conversation

@k2v7n24cbf-cyber

@k2v7n24cbf-cyber k2v7n24cbf-cyber commented Jul 19, 2026

Copy link
Copy Markdown

Summary

Reshapes the existing process tool instead of adding another model-facing tool. This adds process action run: one call starts a command, waits briefly for quick completion, and if the command is still running, detaches and posts a process_completed session event with the final stdout/stderr when the process exits.

The important behavior is that agents do not need a start + notify pair and do not need to poll in normal command execution. They make one tool call for the command. If it completes quickly, the result comes back in that call. If it runs longer, the tool host delivers the eventual completion back into the session and wakes the dispatcher.

Existing process start/poll/log/write/kill remains available for dev servers, watchers, stdin-driven commands, and manual debugging.

Observation that motivated this

In a real agentic session, the same underlying task was run two ways:

Mode Turns/steps Input tokens Cache-hit rate Actual command time
Blocking call 44 ~1.59M 91% essentially unchanged
Start + poll 72 (+64%) ~2.29M (+44%) 94.8% essentially unchanged

The poll-based run burned roughly 700K additional input tokens even though the shell work took essentially the same wall-clock time. One long-running command around 77s was polled 17 separate times before completion; 16 of those polls returned no new information beyond "still running." Another around 78s was polled 5 times.

This was observed while working with newer GPT-5.x-class agents and showed up broadly across deployed agents, not in one specialized agent flow.

Root Cause

The polling pattern does not match the LLM API cost model. Each poll is a full model turn, so the accumulated conversation history is resent as input even when the only new information is "still running." Prompt caching helps avoid recomputing the repeated prefix, but it does not shrink the input token count and it does not remove the latency of a round trip.

The issue compounds because each poll response is appended to the conversation and then resent on every later turn. In the observed run, the poll-heavy path had a higher cache-hit rate than the blocking path, which confirms caching was working; it still consumed substantially more input because the conversation kept growing with low-information poll turns.

Design

  • Adds process({ action: "run", command, ... }) as the one-call command execution path.
  • Waits up to waitMs for quick completion; default is two minutes.
  • If the process exits during the wait window, returns stdout/stderr/exit status in the same tool result.
  • If it is still running after the wait window, keeps it alive, returns a detached status once, and emits a process_completed session event with final output on exit.
  • The daemon appends that event to the session inbox and kicks the dispatcher so the agent wakes on completion rather than waiting for the next regular polling loop.
  • Keeps the existing process actions for workflows that really do need background process control.

Validation

  • pnpm --filter @openacme/tools test -- process-run.test.ts
  • pnpm --filter @openacme/tools check-types
  • pnpm --filter @openacme/tool-host check-types
  • pnpm --filter @openacme/tool-host test
  • pnpm --filter @openacme/server check-types
  • pnpm --filter @openacme/tasks check-types
  • pnpm --filter web check-types
  • pnpm --filter @openacme/server... build
  • Full pre-commit hook passed during the amended commit.

@k2v7n24cbf-cyber k2v7n24cbf-cyber changed the title Add blocking process run tool Add async process run action Jul 19, 2026
@k2v7n24cbf-cyber
k2v7n24cbf-cyber force-pushed the agent/process-run-and-wait-tool branch from 8d8a564 to 8c719c9 Compare July 19, 2026 22:02
@k2v7n24cbf-cyber
k2v7n24cbf-cyber marked this pull request as ready for review July 19, 2026 22:02
k2v7n24cbf-cyber added a commit to k2v7n24cbf-cyber/openacme that referenced this pull request Jul 22, 2026
Merge staged copy of sandydasari#99 into local-stage.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant