Skip to content

feat(jobs): multi-agent awareness — job owners, presence, concurrency e2e - #76

Merged
sebyx07 merged 1 commit into
mainfrom
feat/multi-agent-awareness
Nov 14, 2026
Merged

sebyx07 merged 1 commit into
mainfrom
feat/multi-agent-awareness

Conversation

@sebyx07

@sebyx07 sebyx07 commented Nov 14, 2026

Copy link
Copy Markdown
Contributor

What

Answers "does it support 2 agents on 1 server, and can they see each other?" — yes, and now provably so:

  • Concurrency is proven end-to-end (real binary over HTTP): two separately registered OAuth clients, each with its own bearer and session, run inline commands and background jobs at the same time without waiting on each other.
  • Awareness: every job records which OAuth client started it; job(action="list") opens with a presence line and gives each job a by; poll/kill of another agent's job says whose it is; the admin CLI shows owners and last activity. Still 3 tools — new behaviour lives on job(action="list"|"poll"|"kill").
job(action="list")
3 agents active (last 15 min): you (alpha#930e), evil[31m forged-row#a5c5, beta#e01d
[
  { "id": "beta-job-08-30-42", "state": { "status": "exited", "code": 0 }, "by": "beta#e01d" },
  { "id": "alpha-job-08-30-42", "state": { "status": "running" }, "by": "you" }
]

job(action="poll", id="alpha-job-08-30-42")   # called by beta
[started by another agent: alpha#930e]
{"status":"failed","error":"killed"}

(evil[31m forged-row is the e2e's hostile client_name "evil\x1b[31m\nforged-row" after cleaning.)

Why

The owner asked whether several agents can share one host and whether they know about each other. Before this PR they already ran concurrently, but no test proved it, and an agent had no way to tell its own jobs from another agent's.

Changes

  • src/agent.rs (new): Agent (client id + cleaned name) and ClientName::parse. client_name from DCR is untrusted, so control characters and zero-width/bidi characters are stripped, whitespace is collapsed, and names are capped at 32 chars. The label is <name>#<first 4 hex of SHA-256(client_id)>, which tells two "Claude Code" clients apart without showing any part of the client_id. Debug shows only the label.
  • src/auth.rs: require_auth now calls Store::authenticate, which returns the bearer's Agent and inserts it into the request extensions. rmcp passes the HTTP Parts to each tool, so attribution is per request, not per session.
  • src/oauth/store/presence.rs (new): authenticate (records last use at most once a minute per client, so busy agents' requests stay reads), active_agents (15 min window), logged_in_agents. The stream re-check (validate_hash) does not count as activity, so an idle open SSE stream doesn't keep an agent "active".
  • Schema v7 (add_agent_identity): jobs.client_id, jobs.client_name (stored on the row, so the owner still shows after the client is swept), clients.client_name, clients.last_used_unix.
  • Jobs: JobMeta { title, owner } replaces the title arg of JobStore::run / JobRepo::insert_running. This avoids an 8-argument fn and accounts for most of the test churn. Adds JobStore::owner; JobSummary/JobRow carry the owner.
  • Tools: src/tools/caller.rs (new), presence + by rendering in job_render.rs, an agent label on every dispatch span, and updated job description and server instructions.
  • Admin: mcp-ssh jobs gets a BY column; mcp-ssh sessions adds an "agents (logged in, most recently active first)" section with last-active times.
  • Docs: README, docs/usage.md, docs/architecture.md, CLAUDE.md (module map + tool table + span rule), changelog.

Decisions to flag

  • Awareness, not isolation. Any agent can still poll/kill any job. This is one service user, so isolation would be theatre. The reply names the owner.
  • job(action="list") is no longer bare JSON: the presence line comes first. It already wasn't strict JSON when paged (the [older jobs: …] footer). Called out in the changelog.
  • Rows from before v7 show by: "unknown" (agent) and - (CLI).
  • The caller is always listed in presence, even before its first last-use write.
  • No auth behaviour changes: same validation and expiry eviction, same 401/503 paths. Token values and hashes are never read into presence queries.

Concurrency findings

No defect found. Audited the paths:

  • Db::call: std mutex taken only inside spawn_blocking.
  • jobs map: tokio mutex, released before every .await on I/O.
  • kill_reason: guard dropped before escalation.
  • Per-request rmcp dispatch; per-session Tools.
  • Concurrent same-title same-second job ids: resolved by create_new reservation, now also covered by e2e.

SQLite writes stay serialized by design (one connection) and are low-frequency.

Verification

  • bin/check green: fmt, clippy -D warnings, 309 unit, 13 e2e, module_map, public_tree.
  • New e2e tests (tests/e2e/agents.rs):
    • two_agents_run_commands_and_jobs_concurrently:
      • Both agents start a bg sleep 3 job in the same second under the same title, and get distinct ids.
      • While alpha sits in a 2 s inline call, beta's 5 quick commands all return inline in under 1.5 s.
      • Both jobs finish and each agent polls its own in under 5.5 s total (run one after the other they'd take at least 6 s), with no cross-talk in output.
    • agents_see_each_other_and_whose_job_is_whose:
      • Presence line, by values cross-checked from both sides.
      • Beta can poll and kill alpha's job, and the reply has the owner note.
      • Own-job replies carry no note.
      • The hostile name is cleaned, and no ESC byte reaches the agent or the terminal.
      • mcp-ssh jobs --all shows owners in BY; mcp-ssh sessions shows last-active.
  • Unit tests:
    • name cleaning and labels
    • authenticate throttling and expiry
    • active window ordering
    • the v7 migration on a legacy DB
    • job owner recorded, read back and listed
    • render of presence, by and owner notes
    • admin renders
    • the in-process router test confirms the Agent survives auth → rmcp → tool (you (client#…))

Touches src/auth.rs, so it needs a security-minded review.

🤖 Generated with Claude Code

… e2e

Several OAuth clients can share one host; prove they run side by side and
let them see each other, without adding a tool.

- Every /mcp request carries the Agent its bearer was issued to
  (auth::require_auth -> request extensions -> rmcp Parts -> tools).
- Schema v7: jobs.client_id/client_name, clients.client_name/last_used_unix.
  Last use is rewritten at most once a minute per client.
- job(action="list") opens with the agents active in the last 15 min (the
  caller as `you`) and gives each job `by`; poll/kill of another agent's job
  still works and says whose it is.
- mcp-ssh jobs gains a BY column; mcp-ssh sessions lists each logged-in
  agent's last activity.
- client_name from DCR is untrusted: control/invisible chars stripped,
  whitespace collapsed, <=32 chars; labels carry a hash tag, never the
  client_id.
- e2e: two_agents_run_commands_and_jobs_concurrently,
  agents_see_each_other_and_whose_job_is_whose.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@developerz-ai

developerz-ai Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

🟡 Reviewed

5 actionable comment(s) · grounded on your code

⚠️ 1 config note(s): test files were not shown to the reviewer — this diff touched no path recognised as a test, so no assertion was available to read the change against

🤖 developerz.ai — automated review, running on your model and your box.

@developerz-ai developerz-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review summary — 37 file(s), 5 finding(s).

Critical 0 · Major 1 · Minor 4 · Nit 0

Adds per-job OAuth-client ownership, a presence line in job(action="list") and owner columns in the admin CLI. Low risk: the auth guard and token hashing are unchanged, and the v7 migration only adds nullable columns.

File Findings
docs/architecture.md 1 minor
src/oauth/store.rs 1 minor
src/oauth/store/presence.rs 1 major
src/oauth/store/tests.rs 2 minor
  • test files were not shown to the reviewer — this diff touched no path recognised as a test, so no assertion was available to read the change against

🤖 developerz.ai review — automated, running on your model and your box. What is this?

Comment on lines +47 to +52
if last_used.is_none_or(|at| now - at >= TOUCH_EVERY) {
conn.execute(
"UPDATE clients SET last_used_unix = ?1 WHERE client_id = ?2",
(now, &client_id),
)?;
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

major · bug require_auth now goes through authenticate, which writes the client's last-use time.

Suggested change
if last_used.is_none_or(|at| now - at >= TOUCH_EVERY) {
conn.execute(
"UPDATE clients SET last_used_unix = ?1 WHERE client_id = ?2",
(now, &client_id),
)?;
}
if last_used.is_none_or(|at| now - at >= TOUCH_EVERY)
&& let Err(error) = conn.execute(
"UPDATE clients SET last_used_unix = ?1 WHERE client_id = ?2",
(now, &client_id),
)
{
tracing::warn!(%error, "could not record the client's last use");
}

If that UPDATE fails (the disk filled by a runaway job log, or the CLI holding the write lock past the busy timeout), the ? turns it into StoreUnavailable and every /mcp request gets a 503, so agents lose access exactly when they need it to free disk.

Comment thread docs/architecture.md
- **Registered clients** — `clients` (`client_id` → redirect URIs, no secrets), capped at 1000; a client at least 7 days old that holds no live token is swept.
- **Job metadata** — id, title, status (`running`/`exited`/`failed`), exit code or error, start/finish time, process group + boot id, and a saved **output tail** (last 500 lines, ≤256 KiB). This is what makes `job(action="list")` show history across restarts.
- **Registered clients** — `clients` (`client_id` → redirect URIs, the cleaned `client_name` it registered, when it last used a bearer; no secrets), capped at 1000; a client at least 7 days old that holds no live token is swept. The last-use time is rewritten at most once a minute per client, so a busy agent's requests stay reads; it is what `job(action="list")`'s presence line and `mcp-ssh sessions` read.
- **Job metadata** — id, title, status (`running`/`exited`/`failed`), exit code or error, start/finish time, process group + boot id, the OAuth client that started it (id + name, so the owner still reads right after the client is swept), and a saved **output tail** (last 500 lines, ≤256 KiB). This is what makes `job(action="list")` show history across restarts.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minor · docs docs/architecture.md:64 still says job(action="list") "exposes only the id and state", but ListedJob (src/tools/job_render.rs:46) now adds by, and every list reply opens with a presence line. Update line 64 (and the job row in README.md:74) to mention by and the presence line, while keeping the claim that command text is never exposed.

Comment thread src/oauth/store.rs
None => Ok(false),
}
})
.call(move |conn| live_token_client(conn, &hash, now).map(|client| client.is_some()))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minor · test The design says the stream re-check (validate_hash) never counts as activity, so an idle open SSE stream does not keep an agent active. No test pins that: if a later change routes the re-check through authenticate, nothing fails. Add a store test that calls validate_hash on a live bearer and asserts last_used_unix stays NULL.

Comment thread src/oauth/store/tests.rs
Comment on lines +464 to +470
// A second use within a minute is a read: the time doesn't move.
store
.authenticate(&hash_token(&bearer))
.await
.unwrap()
.unwrap();
assert_eq!(last_used(&db).await, first);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minor · test The throttle test only checks that a second authenticate within a minute leaves last_used_unix alone.

A regression that never refreshes the time after the first write still passes, and that agent would drop out of presence after 15 minutes while busy. Backdate last_used_unix by 61s, call authenticate again, and assert the time moved forward.

Comment thread src/oauth/store/tests.rs
Comment on lines +521 to +528
let logged_in = store.logged_in_agents().await.unwrap();
let names: Vec<_> = logged_in.iter().map(|a| a.agent.name()).collect();
assert_eq!(
names,
[Some("beta"), Some("alpha"), Some("idle")],
"most recent first, never-used last"
);
assert_eq!(logged_in[2].last_used_unix, None);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minor · test Every client in active_agents_are_those_seen_in_the_window_newest_first holds a live token.

If the live-token WHERE client_id IN (...) filter in logged_in_agents were dropped, the test would still pass and mcp-ssh sessions would list agents whose logins have expired. Expire one client's access and refresh tokens and assert it is not in logged_in_agents.

@sebyx07
sebyx07 merged commit 0be4b2e into main Nov 14, 2026
13 checks passed
@sebyx07
sebyx07 deleted the feat/multi-agent-awareness branch November 14, 2026 13:42
@sebyx07 sebyx07 mentioned this pull request Nov 14, 2026
sebyx07 added a commit that referenced this pull request Nov 14, 2026
Version bump to 2.2.0: Cargo.toml, Cargo.lock, changelog (unreleased →
docs/changelog/2.2.0.md, CHANGELOG.md index). Ships #76 (multi-agent
awareness, schema v7). No source change.

Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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