@ours.network/fleet 0.9.5 → 0.9.8

package/dist/session/acp.js

@@ -5,6 +5,19 @@ import { isAbsolute, join, relative, resolve } from 'node:path';
 import { Readable, Writable } from 'node:stream';
 import * as acp from '@agentclientprotocol/sdk';
 import { SessionEvents } from './events.js';
+import { SessionControlError, classifyChildExit, turnResult } from './types.js';
+/**
+ * Classify an ACP `stopReason` into a terminal outcome. A refusal and a
+ * cancellation are the two ways a delivered prompt ends without being carried
+ * out; every other stop reason ran the turn to an end the agent chose.
+ */
+export function classifyStopReason(stopReason) {
+    switch (stopReason) {
+        case 'refusal': return 'refused';
+        case 'cancelled': return 'cancelled';
+        default: return 'completed';
+    }
+}
 /**
  * Persistent ACP v1 client. It is the sole owner of the agent's stdio; all
  * human/automation attachment happens through the fleet role-control protocol.
@@ -22,6 +35,8 @@ export class AcpSession {
     readiness = 'starting';
     lastError;
     promptTail = Promise.resolve();
+    queueDepth = 0;
+    exit = null;
     capabilities;
     controllerCount = 0;
     constructor(options, child, connection) {
@@ -33,9 +48,12 @@ export class AcpSession {
         this.sessionFile = join(options.stateDir, '.acp-session-id');
         child.stderr.on('data', chunk => options.log(`[${options.name}] acp: ${String(chunk).trimEnd()}`));
         child.once('exit', (code, signal) => {
+            // Record the child's real exit code/signal. The tmux path can only see a
+            // shell's `$?`; here the truth is available, so keep it.
+            this.exit = classifyChildExit(code, signal);
             if (this.readiness !== 'failed') {
                 this.readiness = 'failed';
-                this.lastError = `ACP agent exited (${code ?? signal ?? 'unknown'})`;
+                this.lastError = `ACP agent ${this.exit.detail}`;
             }
             this.events.emit('state', { status: 'failed', text: this.lastError });
         });
@@ -88,10 +106,33 @@ export class AcpSession {
             pendingPermissionId: this.pendingPermissions.keys().next().value,
         };
     }
-    submitPrompt(text) {
-        const operation = this.promptTail.then(() => this.runPrompt(text));
-        this.promptTail = operation.then(() => undefined, () => undefined);
-        return operation;
+    /**
+     * Accept responsibility for a prompt, then return. The turn itself may run
+     * for minutes behind other queued turns; making an interactive caller wait
+     * for it is what turned a busy agent into a timeout and then into "dead".
+     */
+    async queuePrompt(text) {
+        if (!this.sessionId || !this.isAlive())
+            throw new SessionControlError('offline', this.lastError ?? 'ACP session is offline');
+        const promptId = randomUUID();
+        const queuedBehind = this.queueDepth++;
+        const run = this.promptTail.then(() => this.runPrompt(text, promptId));
+        this.promptTail = run.then(() => undefined, () => undefined);
+        const completion = run.then(result => { this.queueDepth = Math.max(0, this.queueDepth - 1); return result; }, error => {
+            this.queueDepth = Math.max(0, this.queueDepth - 1);
+            return turnResult(false, 'failed', error?.message ?? String(error));
+        });
+        return { promptId, queuedBehind, completion };
+    }
+    async submitPrompt(text) {
+        try {
+            return await (await this.queuePrompt(text)).completion;
+        }
+        catch (error) {
+            if (error instanceof SessionControlError)
+                return turnResult(false, 'failed', error.message);
+            throw error;
+        }
     }
     async interrupt() {
         if (!this.sessionId)
@@ -100,10 +141,19 @@ export class AcpSession {
     }
     respondPermission(permissionId, optionId) {
         const pending = this.pendingPermissions.get(permissionId);
-        if (!pending || !pending.options.some(option => option.optionId === optionId))
+        const chosen = pending?.options.find(option => option.optionId === optionId);
+        if (!pending || !chosen)
             return false;
         this.pendingPermissions.delete(permissionId);
         pending.resolve({ outcome: { outcome: 'selected', optionId } });
+        this.events.emit('permission', {
+            permissionId,
+            status: 'completed',
+            decision: chosen.kind.startsWith('reject') ? 'denied' : 'allowed',
+            decisionSource: 'manual',
+            reason: `answered from an attached controller (${chosen.kind})`,
+            optionId,
+        });
         this.readiness = 'running';
         return true;
     }
@@ -116,6 +166,9 @@ export class AcpSession {
     setControllerAttached(attached) {
         this.controllerCount = Math.max(0, this.controllerCount + (attached ? 1 : -1));
     }
+    exitResult() {
+        return this.exit;
+    }
     async close() {
         for (const pending of this.pendingPermissions.values())
             pending.resolve({ outcome: { outcome: 'cancelled' } });
@@ -166,11 +219,10 @@ export class AcpSession {
         this.readiness = 'idle';
         this.events.emit('state', { status: 'idle', text: `ACP session ${this.sessionId}` });
     }
-    async runPrompt(text) {
+    async runPrompt(text, turnId = randomUUID()) {
         if (!this.sessionId || !this.isAlive())
-            return { accepted: false, outcome: 'failed', detail: this.lastError ?? 'ACP session is offline' };
+            return turnResult(false, 'failed', this.lastError ?? 'ACP session is offline');
         this.readiness = 'running';
-        const turnId = randomUUID();
         this.events.emit('state', { turnId, status: 'running' });
         try {
             const response = await this.connection.agent.request(acp.methods.agent.session.prompt, {
@@ -180,12 +232,9 @@ export class AcpSession {
             this.readiness = 'idle';
             this.events.emit('turn_stop', { turnId, stopReason: response.stopReason });
             this.events.emit('state', { status: 'idle' });
-            const outcome = response.stopReason === 'cancelled'
-                ? 'cancelled'
-                : response.stopReason === 'refusal'
-                    ? 'refused'
-                    : 'completed';
-            return { accepted: true, outcome, detail: response.stopReason };
+            // The prompt was accepted either way — the agent answered. Whether the
+            // turn SUCCEEDED is a separate question, and only `stopReason` answers it.
+            return turnResult(true, classifyStopReason(response.stopReason), response.stopReason);
         }
         catch (error) {
             this.lastError = error?.message ?? String(error);
@@ -193,23 +242,35 @@ export class AcpSession {
             this.events.emit('error', { turnId, text: this.lastError });
             if (this.isAlive())
                 this.events.emit('state', { status: 'idle' });
-            return { accepted: false, outcome: 'failed', detail: this.lastError };
+            return turnResult(false, 'failed', this.lastError);
         }
     }
     requestPermission(params) {
-        const choose = (kinds) => params.options.find(option => kinds.includes(option.kind));
+        // `kinds` is a PRIORITY order. Scanning the agent's option array instead
+        // (`options.find(o => kinds.includes(o.kind))`) hands the choice to whatever
+        // order the agent happened to list, which is exactly how an automatic denial
+        // could land on `reject_always`.
+        const choose = (kinds) => {
+            for (const kind of kinds) {
+                const option = params.options.find(o => o.kind === kind);
+                if (option)
+                    return option;
+            }
+            return undefined;
+        };
         if (this.options.permissions.approval === 'allow' && this.withinAutomaticBoundary(params)) {
             const option = choose(['allow_always', 'allow_once']);
-            return Promise.resolve(option
-                ? { outcome: { outcome: 'selected', optionId: option.optionId } }
-                : { outcome: { outcome: 'cancelled' } });
+            return Promise.resolve(this.settleAutomatically(params, option, 'allowed', 'permissions.approval=allow', `the request is inside the ${this.options.permissions.filesystem} boundary`));
         }
-        if (this.options.permissions.approval === 'deny'
-            || (this.controllerCount === 0 && this.options.permissions.unattended === 'deny')) {
-            const option = choose(['reject_always', 'reject_once']);
-            return Promise.resolve(option
-                ? { outcome: { outcome: 'selected', optionId: option.optionId } }
-                : { outcome: { outcome: 'cancelled' } });
+        const unattended = this.controllerCount === 0 && this.options.permissions.unattended === 'deny';
+        if (this.options.permissions.approval === 'deny' || unattended) {
+            // reject_once FIRST: `reject_always` teaches the agent a standing rule from
+            // a decision no human made, so one unattended denial would silently disable
+            // the tool for the rest of the session.
+            const option = choose(['reject_once', 'reject_always']);
+            return Promise.resolve(this.settleAutomatically(params, option, 'denied', unattended ? 'permissions.unattended=deny' : 'permissions.approval=deny', unattended
+                ? 'no controller is attached, so the request cannot be shown to anyone'
+                : 'the role denies every permission request by policy'));
         }
         const permissionId = randomUUID();
         this.readiness = 'awaiting_permission';
@@ -226,6 +287,29 @@ export class AcpSession {
             this.pendingPermissions.set(permissionId, { options: params.options, resolve });
         });
     }
+    /**
+     * Resolve a permission request from policy alone and leave a record of it.
+     * Nothing else in the system can observe an automatic decision, so an
+     * unrecorded one is indistinguishable from a request that was never made.
+     */
+    settleAutomatically(params, option, decision, policy, reason) {
+        const settled = option ? decision : 'cancelled';
+        this.events.emit('permission', {
+            permissionId: randomUUID(),
+            toolCallId: params.toolCall.toolCallId,
+            title: params.toolCall.title ?? 'Permission requested',
+            status: 'completed',
+            decision: settled,
+            decisionSource: 'automatic',
+            policy,
+            reason: option ? reason : `${reason}, but the agent offered no matching option`,
+            optionId: option?.optionId,
+            options: params.options.map(o => ({ optionId: o.optionId, name: o.name, kind: o.kind })),
+        });
+        return option
+            ? { outcome: { outcome: 'selected', optionId: option.optionId } }
+            : { outcome: { outcome: 'cancelled' } };
+    }
     withinAutomaticBoundary(params) {
         const filesystem = this.options.permissions.filesystem;
         if (filesystem === 'unrestricted')

package/dist/session/control.d.ts

@@ -1,5 +1,5 @@
 import { type Socket } from 'node:net';
-import type { SessionHandle } from './types.js';
+import type { ControlFailureKind, SessionHandle } from './types.js';
 export interface ControlRequest {
     version: 1;
     id: string;
@@ -16,7 +16,49 @@ export interface ControlResponse {
     ok: boolean;
     result?: unknown;
     error?: string;
+    /** Why it failed, so the caller does not have to guess from the text. */
+    kind?: ControlFailureKind;
 }
+/**
+ * One line saying what a control failure does — and does not — prove about the
+ * agent. Only `offline` is evidence that it is gone; every other kind used to
+ * be rendered as "is not running", which is how a busy agent got restarted.
+ */
+export declare function livenessNote(kind: ControlFailureKind, name: string): string;
+/**
+ * The result taxonomy an overseer judges a role by (7.2).
+ *
+ * One console command is not a liveness verdict. `peek` and `send` can fail for
+ * five distinct reasons and succeed for one, and only ONE of the six says the
+ * agent is gone — collapsing them into "not running" is how busy agents got
+ * restarted. This is the single definition of that vocabulary: the generated
+ * briefing renders it, and the shipped oversee-agents skills quote it. The
+ * per-result wording comes from `livenessNote` rather than being restated, so
+ * the words an overseer reads in its instructions are the words the CLI prints.
+ */
+export interface OversightResult {
+    /** What the command reported: the one success, or the failure kind. */
+    result: 'queued' | ControlFailureKind;
+    /** What it proves about the agent. */
+    meaning: string;
+    /** What the overseer does next. */
+    action: string;
+    /**
+     * Whether this result ALONE justifies restarting the role. True for exactly
+     * one result. Every other one requires corroboration before touching a role
+     * that may simply be working.
+     */
+    restartJustified: boolean;
+}
+/** The taxonomy, in the order generated guidance presents it. */
+export declare function oversightTaxonomy(name?: string): OversightResult[];
+/**
+ * The taxonomy as guidance lines, for a briefing or any generated document.
+ * The shipped oversee-agents skills carry these same lines, and a test holds
+ * them to it — so an overseer reading its briefing and an overseer reading the
+ * skill cannot be given different rules.
+ */
+export declare function oversightTaxonomyLines(name?: string): string[];
 export declare const controlSocketPath: (stateDir: string) => string;
 export declare const controlTokenPath: (stateDir: string) => string;
 /** Private, versioned JSONL control plane for CLI and future console frontends. */
@@ -34,6 +76,12 @@ export declare class RoleControlServer {
     private handle;
     private write;
 }
+/**
+ * Send one control request. Every failure mode is classified: a missing token
+ * or socket is `control-unavailable`, a silent server is `timeout`, and a
+ * response that is not parseable JSON is `backend`. The caller never has to
+ * infer liveness from an exception message.
+ */
 export declare function controlRequest(stateDir: string, request: Omit<ControlRequest, 'version' | 'id' | 'token'>, timeoutMs?: number): Promise<ControlResponse>;
 export declare function followControl(stateDir: string, onMessage: (message: Record<string, unknown>) => void): Promise<{
     socket: Socket;

package/dist/session/control.js

@@ -2,7 +2,84 @@ import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { createConnection, createServer } from 'node:net';
 import { join } from 'node:path';
+import { SessionControlError } from './types.js';
 const MAX_LINE_BYTES = 64 * 1024;
+/**
+ * One line saying what a control failure does — and does not — prove about the
+ * agent. Only `offline` is evidence that it is gone; every other kind used to
+ * be rendered as "is not running", which is how a busy agent got restarted.
+ */
+export function livenessNote(kind, name) {
+    switch (kind) {
+        case 'offline':
+            return `'${name}' is confirmed offline.`;
+        case 'control-unavailable':
+            return `this says nothing about whether '${name}' is alive — its control plane did not answer; ` +
+                `check: ours-fleet status ${name}`;
+        case 'timeout':
+            return `'${name}' did not answer in time; a busy agent looks exactly like this. ` +
+                `Check: ours-fleet status ${name}`;
+        case 'rejected':
+            return `'${name}' is running and refused the request.`;
+        case 'backend':
+            return `this is a transport failure, not evidence that '${name}' is gone; ` +
+                `check: ours-fleet status ${name}`;
+    }
+}
+/** The taxonomy, in the order generated guidance presents it. */
+export function oversightTaxonomy(name = '<Name>') {
+    return [
+        {
+            result: 'queued',
+            meaning: `the session accepted the prompt for '${name}'; a turn already running is not a failure.`,
+            action: 'Nothing. Do not resend, and do not read the absence of a reply as a stall — '
+                + `check progress with: ours-fleet peek ${name}`,
+            restartJustified: false,
+        },
+        {
+            result: 'timeout',
+            meaning: livenessNote('timeout', name),
+            action: 'Treat delivery as UNCERTAIN — the request may already have been acted on, so do not '
+                + 'resend it blindly.',
+            restartJustified: false,
+        },
+        {
+            result: 'rejected',
+            meaning: livenessNote('rejected', name),
+            action: 'Fix the request, not the agent. A refusal is proof of life.',
+            restartJustified: false,
+        },
+        {
+            result: 'control-unavailable',
+            meaning: livenessNote('control-unavailable', name),
+            action: 'Read the role logs as well. The control plane and the agent are separate things, '
+                + 'and one being unreachable is not evidence about the other.',
+            restartJustified: false,
+        },
+        {
+            result: 'backend',
+            meaning: livenessNote('backend', name),
+            action: 'Investigate the transport, not the agent.',
+            restartJustified: false,
+        },
+        {
+            result: 'offline',
+            meaning: livenessNote('offline', name),
+            action: `This is the ONLY result that justifies a restart on its own: ours-fleet restart ${name} `
+                + 'for a permanent role. Read the logs first.',
+            restartJustified: true,
+        },
+    ];
+}
+/**
+ * The taxonomy as guidance lines, for a briefing or any generated document.
+ * The shipped oversee-agents skills carry these same lines, and a test holds
+ * them to it — so an overseer reading its briefing and an overseer reading the
+ * skill cannot be given different rules.
+ */
+export function oversightTaxonomyLines(name = '<Name>') {
+    return oversightTaxonomy(name).map(r => `- **${r.result}** — ${r.meaning} → ${r.action}`);
+}
 export const controlSocketPath = (stateDir) => join(stateDir, '.control.sock');
 export const controlTokenPath = (stateDir) => join(stateDir, '.control-token');
 function sameToken(actual, supplied) {
@@ -111,19 +188,28 @@ export class RoleControlServer {
                     return;
                 case 'submit_prompt': {
                     if (!request.text?.trim())
-                        throw new Error('text is required');
-                    const result = await this.session.submitPrompt(request.text);
-                    this.write(socket, { version: 1, id: request.id, ok: result.accepted, result,
-                        error: result.accepted ? undefined : result.detail });
+                        throw new SessionControlError('rejected', 'text is required');
+                    // Answer on QUEUE ACCEPTANCE, not on turn completion. A turn can run
+                    // for minutes; blocking here made every `send` into a busy agent time
+                    // out, and the timeout was then reported as a dead agent.
+                    const queued = await this.session.queuePrompt(request.text);
+                    this.write(socket, {
+                        version: 1, id: request.id, ok: true,
+                        result: {
+                            state: 'queued', promptId: queued.promptId, queuedBehind: queued.queuedBehind,
+                        },
+                    });
                     return;
                 }
                 case 'respond_permission': {
                     if (!request.permissionId || !request.optionId)
-                        throw new Error('permissionId and optionId are required');
+                        throw new SessionControlError('rejected', 'permissionId and optionId are required');
                     const accepted = this.session.respondPermission(request.permissionId, request.optionId);
                     this.write(socket, {
                         version: 1, id: request.id, ok: accepted,
-                        result: { accepted }, error: accepted ? undefined : 'stale or invalid permission response',
+                        result: { accepted },
+                        error: accepted ? undefined : 'stale or invalid permission response',
+                        kind: accepted ? undefined : 'rejected',
                     });
                     return;
                 }
@@ -146,11 +232,14 @@ export class RoleControlServer {
             }
         }
         catch (error) {
+            // Carry the session's own classification to the caller. Losing it here is
+            // what forced the CLI to invent one.
             this.write(socket, {
                 version: 1,
                 id: request.id,
                 ok: false,
                 error: error?.message ?? String(error),
+                kind: error instanceof SessionControlError ? error.kind : 'backend',
             });
         }
     }
@@ -159,18 +248,34 @@ export class RoleControlServer {
             socket.write(JSON.stringify(response) + '\n');
     }
 }
+/**
+ * Send one control request. Every failure mode is classified: a missing token
+ * or socket is `control-unavailable`, a silent server is `timeout`, and a
+ * response that is not parseable JSON is `backend`. The caller never has to
+ * infer liveness from an exception message.
+ */
 export async function controlRequest(stateDir, request, timeoutMs = 120_000) {
-    const token = readFileSync(controlTokenPath(stateDir), 'utf8').trim();
+    let token;
+    try {
+        token = readFileSync(controlTokenPath(stateDir), 'utf8').trim();
+    }
+    catch (error) {
+        throw new SessionControlError('control-unavailable', `cannot read the role control token: ${error?.message ?? String(error)}`);
+    }
     const id = randomUUID();
     const socket = createConnection(controlSocketPath(stateDir));
     socket.setEncoding('utf8');
-    const response = await new Promise((resolve, reject) => {
+    return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
             socket.destroy();
-            reject(new Error('role control request timed out'));
+            reject(new SessionControlError('timeout', `the role control plane did not answer '${request.command}' within ${timeoutMs}ms`));
         }, timeoutMs);
         let buffer = '';
-        socket.once('error', error => { clearTimeout(timer); reject(error); });
+        socket.once('error', error => {
+            clearTimeout(timer);
+            const code = error.code;
+            reject(new SessionControlError(code === 'ENOENT' || code === 'ECONNREFUSED' ? 'control-unavailable' : 'backend', `role control socket: ${error.message}`));
+        });
         socket.on('data', chunk => {
             buffer += chunk;
             const newline = buffer.indexOf('\n');
@@ -181,7 +286,7 @@ export async function controlRequest(stateDir, request, timeoutMs = 120_000) {
                 resolve(JSON.parse(buffer.slice(0, newline)));
             }
             catch (error) {
-                reject(error);
+                reject(new SessionControlError('backend', `malformed control response: ${error?.message ?? String(error)}`));
             }
             socket.end();
         });
@@ -189,7 +294,6 @@ export async function controlRequest(stateDir, request, timeoutMs = 120_000) {
             version: 1, id, token, ...request,
         }) + '\n'));
     });
-    return response;
 }
 export async function followControl(stateDir, onMessage) {
     const token = readFileSync(controlTokenPath(stateDir), 'utf8').trim();

package/dist/session/tmux.d.ts

@@ -1,5 +1,5 @@
 import type { Tmux } from '../tmux.js';
-import type { SessionEvent, SessionHandle, SessionSnapshot, TurnResult } from './types.js';
+import type { ExitRecord, QueuedPrompt, SessionEvent, SessionHandle, SessionSnapshot, TurnResult } from './types.js';
 /** SessionHandle adapter for the existing tmux transport. */
 export declare class TmuxSession implements SessionHandle {
     private readonly name;
@@ -10,11 +10,18 @@ export declare class TmuxSession implements SessionHandle {
     constructor(name: string, pid: number, tmux: Tmux, processAlive: (pid: number) => boolean);
     isAlive(): boolean;
     snapshot(): SessionSnapshot;
+    queuePrompt(text: string): Promise<QueuedPrompt>;
     submitPrompt(text: string): Promise<TurnResult>;
     interrupt(): Promise<void>;
     respondPermission(): boolean;
     eventsSince(): SessionEvent[];
     subscribe(): () => void;
     setControllerAttached(): void;
+    /**
+     * A tmux pane's exit is only visible through the record its shell wrapper
+     * writes; the runner owns that file and classifies it. Nothing observable
+     * from here, so say `null` rather than guess.
+     */
+    exitResult(): ExitRecord | null;
     close(): Promise<void>;
 }

package/dist/session/tmux.js

@@ -1,3 +1,5 @@
+import { randomUUID } from 'node:crypto';
+import { SessionControlError, turnResult } from './types.js';
 /** SessionHandle adapter for the existing tmux transport. */
 export class TmuxSession {
     name;
@@ -21,11 +23,31 @@ export class TmuxSession {
             readiness: this.isAlive() ? 'idle' : 'failed',
         };
     }
-    async submitPrompt(text) {
+    async queuePrompt(text) {
         if (!this.isAlive())
-            return { accepted: false, outcome: 'failed', detail: 'tmux pane is offline' };
-        await this.tmux.sendText(this.name, text);
-        return { accepted: true, outcome: 'inconclusive' };
+            throw new SessionControlError('offline', `tmux pane for '${this.name}' is offline`);
+        try {
+            await this.tmux.sendText(this.name, text);
+        }
+        catch (error) {
+            throw new SessionControlError('backend', error?.message ?? String(error));
+        }
+        // Keystrokes carry no terminal result: tmux cannot tell us how the turn ended.
+        return {
+            promptId: randomUUID(),
+            queuedBehind: 0,
+            completion: Promise.resolve(turnResult(true, 'inconclusive')),
+        };
+    }
+    async submitPrompt(text) {
+        try {
+            return await (await this.queuePrompt(text)).completion;
+        }
+        catch (error) {
+            if (error instanceof SessionControlError)
+                return turnResult(false, 'failed', error.message);
+            throw error;
+        }
     }
     async interrupt() {
         await this.tmux.sendKey(this.name, 'C-c');
@@ -40,6 +62,14 @@ export class TmuxSession {
         return () => { };
     }
     setControllerAttached() { }
+    /**
+     * A tmux pane's exit is only visible through the record its shell wrapper
+     * writes; the runner owns that file and classifies it. Nothing observable
+     * from here, so say `null` rather than guess.
+     */
+    exitResult() {
+        return null;
+    }
     async close() {
         await this.tmux.kill(this.name);
     }