[Siddharth-DWT]

Title: The agent and monitors: agent(), AgentRun with continue_, arc.monitors, and the run_agent and continue_agent MCP tools

Branch: feat/web-search-agent → main. Three commits on top of main (27f1332, Release 0.6.0):

• 41a14f2 Merge origin/main (0.6.0) into feat/web-search-agent. This brings the branch onto 0.6.0 with no file changes of its own: its tree is exactly 0.6.0's.
• 0ffa768 the agent and monitors.
• 91bf33a review fixes (below).

The branch's two older commits (3b07879, ce8a7a6) were released as 0.5.0 and add nothing to the diff.

Up to date with main (checked 12 Oct): main (27f1332) has no commits the branch lacks, and the branch merges into it cleanly. Against main the diff is 9 files, +1,926 −73.

Review fixes (91bf33a)

From a code review of this branch:

1. run_agent stays on its starting sites. Given urls and no allowed_domains, the MCP tool holds the agent to the URLs' sites: each host, lower case, without www (the API keeps its subdomains). The app does the same, because a page the agent reads could tell it to go elsewhere.
   • allowed_domains given wins, and [] means no limit;
   • with no urls there is nothing to hold it to;
   • the client's agent() is unchanged, and sends what it is given, as the API documents.
2. cancel_agent(run_id) stops an agent run by its id in one request. MCP cancel_job(kind="agent") uses it instead of reading the run first, and AgentRun.cancel() shares it.
3. One cursor pager (_paged) serves searches(), agent_runs() and monitors.runs(), instead of three copies of the loop.
4. AgentRun.wait() returns only a done, cancelled or credit_limit run. Any other end raises MeshArcError 502 job_failed, as the Node client does.

What

Client (mesharc/__init__.py)

• agent(prompt, urls=, schema=, max_credits=, max_steps=, allowed_domains=, webhook=, connection_id=, timeout_s=0, idempotency_key=) returns an AgentRun at once.
  • wait() returns once the run is done, cancelled or credit_limit, and raises MeshArcError for error.
  • It also has refresh(), cancel(), and trace(after=0, follow=True), which yields the steps.
  • It holds data, sources and field_sources (each value's path → {url, pageId}).
  • webhook_secret is returned once and kept by the handle across refresh() and continue_().
• AgentRun.continue_(max_credits=, max_steps=, timeout_s=, idempotency_key=) carries on a run stopped at credit_limit.
  • The new run keeps the pages already read (not paid for again) and the webhook.
  • continues_run_id and continued_by link the two runs.
  • Errors: 409 conflict for a run that cannot be continued; 410 expired past 7 days.
• cancel_agent(id) stops a run by its id, with no handle needed.
• get_agent(id) reopens a run; agent_runs(status=, model=, since=, until=, limit=) walks the workspace's runs, following next. since and until take ISO strings, dates or datetimes.
• web_search(news=True, page=) reads news results (with publisher and age) and results pages 2–10. Both come last in the signature, so no existing call changes meaning.
• arc.monitors: create(kind, request, schedule, name=, webhook=, baseline_id=, idempotency_key=), list(kind=), get, update, pause, resume, run, runs (following next) and delete. A search or agent request is kept on a schedule. arc.monitor(), the job queue, is unchanged.

MCP server (mesharc/mcp.py): 17 tools on 0.6.0's names (search_web, list_pages(url=))

• run_agent hands a question to the agent and returns at once with a job.
• continue_agent(id, max_credits=, max_steps=) carries on a run stopped at its limit:
  • a run already carried on is answered with the run that continued it;
  • a run that cannot be continued is conflict, an unknown one not_found, one past its 7 days expired.
• Both: need write access ({"code": "read_only"} otherwise); send their own idempotency key, made from their inputs and a ten-minute window; answer a 409 in_flight as running.
• run_agent with urls and no allowed_domains stays on those URLs' sites; [] means no limit.
• get_job and cancel_job take kind="agent"; cancel_job stops a run in one request. A finished answer keeps within 60,000 characters: fieldSources is dropped first, then the sources are cut, then data. The answer never includes the webhook secret.
• Eleven of the seventeen tools need write access.

Docs: README (the agent, continue, monitors, the MCP tool list, idempotency, timeouts) and CHANGELOG (under Unreleased).

Testing

• Checks on the branch head (12 Oct): ruff clean, mypy no issues, pytest 247 passed (4 of them new, for the review fixes), scripts/check_release.py passes (version 0.6.0).

• The review fixes, live against the local API (6/6):

  • run_agent with https://www.Books.toscrape.com/ and no allowed_domains made a run held to books.toscrape.com;
  • allowed_domains=[] gave a run with no limit, and no urls gave none;
  • MCP cancel_job and the client's cancel_agent each stopped a run;
  • wait() returned the cancelled run as an answer.

• Live, against the local API in production mode: 17/17. Covered:

  • news search and page 2;
  • creating a monitor with a search as its baseline, listing, update (schedule, webhook set and removed), pause and resume;
  • run now, with a second run refused with 409, settled and compared; then delete;
  • an agent run on a tiny budget stopping at credit_limit, then continue_() to a full answer with field sources and the thread links;
  • continuing twice refused with 409;
  • agent_runs(model=, since=date);
  • MCP get_job(kind="agent") without the webhook secret, and continue_agent on a finished run refused with conflict.

  The MCP server lists exactly the 17 expected tools, and search_web answered live.

Notes

• Needs the API's feature branch (Seam-be feat/search-agent-groundwork, PR #26): /agent, /agent/{id}/continue, /monitors, and search news and page. Release only after it is live on mesharc.dev.

• Not in this PR: the API branch has more that the client and MCP do not cover yet:

  • follow-ups and conversations (/agent/{id}/follow-up, /agent/conversations);
  • an agent monitor's records;
  • agent batches;
  • triggers;
  • proposals;
  • /estimate.

  They come in a follow-up PR. Proposals will only be listable over MCP, so an AI client cannot approve its own agent's proposals.

• Version: stays 0.6.0 here; the release PR bumps it.