Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.mjs
index 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 it
if (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 once
diff --git a/plugins/ruflo-ruos/scripts/lib/jobs.mjs b/plugins/ruflo-ruos/scripts/lib/jobs.mjs
index 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.mjs
index 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.md
index 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.