π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
fix(ruflo-ruos): jobs API 400 is non-retryable; cancelled (exit 143) is a stop
ruvc150ac7582bf
diff --git a/plugins/ruflo-ruos/scripts/lib/adapter.mjs b/plugins/ruflo-ruos/scripts/lib/adapter.mjsindex b2347af282..3c8b76433a 100644--- a/plugins/ruflo-ruos/scripts/lib/adapter.mjs+++ b/plugins/ruflo-ruos/scripts/lib/adapter.mjs@@ -12,6 +12,8 @@ import { checkWindow } from './autostop.mjs';const TERMINAL = new Set(['exited', 'failed', 'cancelled']);export const POLL_MIN_MS = 1000;export const POLL_MAX_MS = 10_000;+/** after a cancel, keep reading output for at most this long (server KILLs at 10 s) */+export const CANCEL_DRAIN_MS = 15_000;/** heartbeat older than this is not evidence the desktop is up */export const HEARTBEAT_FRESH_SECS = 180;@@ -265,9 +267,15 @@ export class RuosHostAdapter {async stream(desktop, jobId, runId, agentId, st, o) {let delay = POLL_MIN_MS;let lostOnce = false;+ /** @type {number|null} */ let cancelAt = null;for (;;) {- if (o.signal?.aborted) {+ if (o.signal?.aborted && cancelAt === null) {+ // Cancel, then keep draining: the job API keeps output written+ // before the cancel and ends `cancelled` (exit 143, SIGTERM).await this.jobs.cancel(desktop, jobId).catch(() => false);+ cancelAt = this.now();+ }+ if (cancelAt !== null && this.now() - cancelAt > CANCEL_DRAIN_MS) {return { status: 'stopped', exitCode: null };}if (this.now() - o.t0 > o.timeoutSecs * 1000) {@@ -288,12 +296,14 @@ export class RuosHostAdapter {if (p.chunk.length > 0) { delay = POLL_MIN_MS; continue; }if (TERMINAL.has(p.state)) {// `exited` carries any exit code (ADR-105): only 0 is completed.- const status = p.state === 'cancelled' ? 'stopped' : p.state === 'exited' && p.exitCode === 0 ? 'completed' : 'failed';+ // `cancelled` (exit 143) is a stop, never a failure.+ const status = p.state === 'cancelled' || cancelAt !== null ? 'stopped' : p.state === 'exited' && p.exitCode === 0 ? 'completed' : 'failed';return { status, exitCode: p.exitCode };}if (p.state === 'stopped') {throw new RuosError('auto-stopped', `desktop stopped mid-run; HOME persists β wake it and \`attach --run ${runId}\` to read the output`);}+ if (p.state === 'lost' && cancelAt !== null) return { status: 'stopped', exitCode: p.exitCode }; // we killed itif (p.state === 'lost') {if (lostOnce) throw new RuosError('remote-error', 'runner died without an exit code (killed on the desktop?)');lostOnce = true; // exit.code is written just after the runner exits: re-check oncediff --git a/plugins/ruflo-ruos/scripts/lib/jobs.mjs b/plugins/ruflo-ruos/scripts/lib/jobs.mjsindex 52d7fba9d0..168c01f680 100644--- a/plugins/ruflo-ruos/scripts/lib/jobs.mjs+++ b/plugins/ruflo-ruos/scripts/lib/jobs.mjs@@ -151,7 +151,9 @@ export function createJobsApiTransport(backend, exec, nonce = defaultNonce) {* POST 409 β same key, different request: a client bug, never retried* POST 429 β per-tenant cap (4), no server queue β `capacity` (adapter backs off)* GET 503 β desktop up but the poll did not answer β retried here with backoff+ * 400 β invalid-input (e.g. a Lite machine target), never retried* 401 β auth-expired Β· 403 β insufficient-scope Β· 404 β not-owned (never retried)+ * DELETE 200 β job ends `cancelled`, exit 143, output before the cancel kept* @param {{ baseUrl: string, token: string, fetchImpl?: typeof fetch, sleep?: (ms: number) => Promise<void> }} o* @returns {JobsBackend & { detect: (machine: string) => Promise<boolean> }}*/@@ -178,6 +180,7 @@ export function createRestJobsBackend(o) {} catch {throw new RuosError('network-down', 'ruOS jobs API unreachable');}+ if (res.status === 400) throw new RuosError('invalid-input', 'jobs API refused the request (400; e.g. a Lite browser target has no shell); not retried');if (res.status === 401) throw new RuosError('auth-expired', 'jobs API refused the credential');if (res.status === 403) throw new RuosError('insufficient-scope', 'jobs API needs a desktop:control token');if (res.status === 404) throw new RuosError('not-owned', 'job not found (not yours, or gone)');diff --git a/plugins/ruflo-ruos/tests/requirements.test.mjs b/plugins/ruflo-ruos/tests/requirements.test.mjsindex 8c718bdde5..ac007492e1 100644--- a/plugins/ruflo-ruos/tests/requirements.test.mjs+++ b/plugins/ruflo-ruos/tests/requirements.test.mjs@@ -226,6 +226,7 @@ function adr105Server() {const json = (/** @type {number} */ status, /** @type {unknown} */ b) => new Response(JSON.stringify(b), { status });if (u.pathname === '/api/v1/desktop/jobs' && method === 'POST') {if (!body.idempotency_key) return json(400, { error: 'idempotency_key required' });+ if (String(body.machine).startsWith('lite-')) return json(400, { error: 'Lite browsers have no shell' });const prev = byKey.get(body.idempotency_key);if (prev) {return JSON.stringify(prev.body) === JSON.stringify(body)@@ -240,8 +241,13 @@ function adr105Server() {const id = u.pathname.split('/').pop() ?? '';const job = [...byKey.entries()].find(([k]) => `job_${k.slice(2, 10)}` === id)?.[1];if (!job) return json(404, { error: 'not found' });- if (method === 'DELETE') { job.state = 'cancelled'; return json(200, {}); }+ if (method === 'DELETE') { job.state = 'cancelled'; job.exit = 143; return json(200, { job_id: id, state: 'cancelled' }); }if (unanswered-- > 0) return new Response('', { status: 503 });+ if (job.state === 'cancelled') {+ const off = Number(u.searchParams.get('offset'));+ const chunk = job.out.subarray(off);+ return json(200, { chunk: chunk.toString('base64'), next_offset: off + chunk.length, running: false, state: 'cancelled', exit_code: 143, truncated: false, desktop: 'up' });+ }job.polls++;if (job.polls === 1) return json(200, { chunk: '', next_offset: 0, running: true, state: 'queued', exit_code: null, truncated: false, desktop: 'up' });const off = Number(u.searchParams.get('offset'));@@ -303,3 +309,32 @@ test('ADR-105: timeout_secs above 21600 is clamped client-side, never refused',await t.start(desktop(), { runId: RUN, prompt: 'p', runner: 'claude', timeoutSecs: 30000 });assert.equal(srv.log.find((r) => r.method === 'POST')?.body.timeout_secs, 21600);});++test('ADR-105: a Lite target is 400 β invalid-input, never retried', async () => {+ const srv = adr105Server();+ const backend = createRestJobsBackend({ baseUrl: 'https://ruos.cognitum.one', token: 'tok', fetchImpl: srv.f });+ await assert.rejects(backend.create({ machine: 'lite-2be6c1bd3e06f05ae8da5f470e4737c3', command: 'x', timeout_secs: 60, idempotency_key: RUN }),+ (e) => e instanceof RuosError && e.code === 'invalid-input');+ assert.equal(srv.log.filter((r) => r.method === 'POST').length, 1);+});++test('ADR-105: cancel β 200, job ends cancelled with exit 143, output before the cancel kept, reported as stopped', async () => {+ const srv = adr105Server();+ const clock = fakeClock();+ const backend = createRestJobsBackend({ baseUrl: 'https://ruos.cognitum.one', token: 'tok', fetchImpl: srv.f, sleep: clock.sleep });+ const ledger = fakeLedger();+ const adapter = new RuosHostAdapter({+ fleet: fakeFleet([desktop({ heartbeatAt: Math.floor(clock.now() / 1000) })]),+ jobs: createJobsApiTransport(backend, staging(), () => N),+ ledger: /** @type {any} */ (ledger), now: clock.now, sleep: clock.sleep,+ });+ const ac = new AbortController();+ ac.abort(); // cancel right after the first (queued) poll+ /** @type {string[]} */ const seen = [];+ const out = await adapter.run({ desktop: 'Work Desktop', prompt: 'p', runId: RUN, agentId: 'a1', signal: ac.signal, onOutput: (c) => seen.push(c.toString()) });+ assert.equal(out.status, 'stopped', 'cancelled is a stop, not a failure');+ assert.equal(out.exitCode, 143);+ assert.equal(seen.join(''), 'exit three\n', 'output written before the cancel is kept');+ assert.equal(srv.log.filter((r) => r.method === 'DELETE').length, 1);+ assert.equal(ledger.events.at(-1).type, 'run.stopped');+});diff --git a/v3/docs/adr/ADR-405-ruos-desktops-as-swarm-hosts.md b/v3/docs/adr/ADR-405-ruos-desktops-as-swarm-hosts.mdindex b572c70dab..877e6f39e7 100644--- a/v3/docs/adr/ADR-405-ruos-desktops-as-swarm-hosts.md+++ b/v3/docs/adr/ADR-405-ruos-desktops-as-swarm-hosts.md@@ -66,15 +66,25 @@ The adapter drives a `JobTransport` (`jobs.mjs`) through `start`, `poll(offset)`- `wait_ms` is a long-poll, so the adapter skips its own sleep, guarded against a server that answers instantly.- `503` means the desktop is up but the poll didn't answer; it is retried with 1 s, 2 s and 4 s backoff.- Polls do not take the desktop's run lock.- - **Cancel and list.** `DELETE β¦/jobs/{id}` sends TERM, then KILL after 10 s, and the job becomes `cancelled`. `GET β¦/jobs?machine=` lists jobs newest first.+ - **Cancel and list.** `DELETE β¦/jobs/{id}` returns `200`, sends TERM, then KILL after 10 s. The job ends `cancelled` with `exit_code` 143 (SIGTERM) and keeps the output written before the cancel. The adapter keeps reading output for up to 15 s after a cancel, and reports `cancelled` as **stopped**, never failed. `GET β¦/jobs?machine=` lists jobs newest first.- **States.**- `exited` carries any exit code; only 0 counts as `completed`.- `failed` means the launch never reached the desktop, or the job's own timeout fired.- `stopped` is re-pollable after `desktop_start`, so it is surfaced as resumable `auto-stopped`.- `queued`, `running`, `cancelled` and `lost` are the others.- - **Errors.** A `404` means "not yours, or gone" and is never retried. 401 maps to `auth-expired`, 403 to `insufficient-scope`.+ - **Errors.** A `400` (e.g. targeting a Lite browser, which has no shell) maps to `invalid-input` and is never retried. A `404` means "not yours, or gone" and is never retried. 401 maps to `auth-expired`, 403 to `insufficient-scope`.- **Backends.** REST with the tenant token, or the local stdio `@cognitum/ruos` server's `desktop_job_start/poll/list/cancel`. Those tools are stdio-only; the hosted remote MCP is unchanged at 42 tools (ruOS ADR-094).- - **Verification status:** **contract-tested, not exercised live.** Mocks reproduce the exact live codes and fields: 202, 200 replay, 409, 429, 503, 404, queued with `running: true`, `exited` with a non-zero code, and `wait_ms`. No live call was made, because no control-scoped token was available and a live run needs separate spend approval. ruOS's own 1195 service tests pass, but it has not yet run a live end-to-end of these endpoints either.+ - **Verification status:** ruOS validated the jobs API contract live (end-to-end by the ruOS lane, fleet `64261be`, Work Desktop):+ - POST returned 202 `queued`;+ - a replay returned 200 `idempotent_replay` with the same `job_id`;+ - the same key with a different command returned 409;+ - `wait_ms=5000` long-poll returned all output in order, then `exited` with exit 0;+ - `stop_at` was the next 23:00 ET;+ - an unknown id returned 404, and the list was newest first;+ - a Lite target returned 400;+ - DELETE returned 200, and the job ended `cancelled` with exit 143.++ ruflo's `JobsApiTransport` is **contract-tested against it, not called live by ruflo**. The mocks reproduce those exact codes and fields. ruflo made no live call: no control-scoped token was available, and a call would need separate spend approval.Polling is adaptive: 1 s while output flows, backing off to 10 s when idle. Every exec poll is an audited call that waits behind the run lock. Jobs-API polls long-poll server-side instead.