@ours.network/fleet 0.9.4 → 0.9.7

package/dist/session/acp.d.ts

@@ -0,0 +1,70 @@
+import type { CommonPermissions } from '../config.js';
+import type { ExitRecord, QueuedPrompt, SessionEvent, SessionHandle, SessionSnapshot, TurnOutcome, TurnResult } from './types.js';
+export interface AcpSessionOptions {
+    name: string;
+    argv: string[];
+    cwd: string;
+    env: Record<string, string>;
+    stateDir: string;
+    mode: 'fresh' | 'resume';
+    permissions: CommonPermissions;
+    log(line: string): void;
+}
+/**
+ * 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 declare function classifyStopReason(stopReason: string | undefined): TurnOutcome;
+/**
+ * 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.
+ */
+export declare class AcpSession implements SessionHandle {
+    private readonly options;
+    readonly backend: "acp";
+    readonly pid: number;
+    private readonly child;
+    private readonly events;
+    private readonly sessionFile;
+    private readonly pendingPermissions;
+    private connection;
+    private sessionId?;
+    private readiness;
+    private lastError?;
+    private promptTail;
+    private queueDepth;
+    private exit;
+    private capabilities?;
+    private controllerCount;
+    private constructor();
+    static start(options: AcpSessionOptions): Promise<AcpSession>;
+    isAlive(): boolean;
+    snapshot(): SessionSnapshot;
+    /**
+     * 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".
+     */
+    queuePrompt(text: string): Promise<QueuedPrompt>;
+    submitPrompt(text: string): Promise<TurnResult>;
+    interrupt(): Promise<void>;
+    respondPermission(permissionId: string, optionId: string): boolean;
+    eventsSince(seq: number): SessionEvent[];
+    subscribe(listener: (event: SessionEvent) => void): () => void;
+    setControllerAttached(attached: boolean): void;
+    exitResult(): ExitRecord | null;
+    close(): Promise<void>;
+    private initialize;
+    private runPrompt;
+    private requestPermission;
+    /**
+     * 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.
+     */
+    private settleAutomatically;
+    private withinAutomaticBoundary;
+    private recordUpdate;
+    private fail;
+}

package/dist/session/acp.js

@@ -0,0 +1,364 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+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.
+ */
+export class AcpSession {
+    options;
+    backend = 'acp';
+    pid;
+    child;
+    events;
+    sessionFile;
+    pendingPermissions = new Map();
+    connection;
+    sessionId;
+    readiness = 'starting';
+    lastError;
+    promptTail = Promise.resolve();
+    queueDepth = 0;
+    exit = null;
+    capabilities;
+    controllerCount = 0;
+    constructor(options, child, connection) {
+        this.options = options;
+        this.child = child;
+        this.connection = connection;
+        this.pid = child.pid ?? -1;
+        this.events = new SessionEvents(join(options.stateDir, '.session-events.jsonl'));
+        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 ${this.exit.detail}`;
+            }
+            this.events.emit('state', { status: 'failed', text: this.lastError });
+        });
+    }
+    static async start(options) {
+        if (!options.argv.length)
+            throw new Error('ACP agent command is empty');
+        const child = spawn(options.argv[0], options.argv.slice(1), {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        await new Promise((resolve, reject) => {
+            child.once('spawn', resolve);
+            child.once('error', reject);
+        });
+        let instance;
+        const app = acp.client({ name: 'ours-fleet' })
+            .onNotification(acp.methods.client.session.update, ({ params }) => {
+            instance?.recordUpdate(params.update);
+        })
+            .onRequest(acp.methods.client.session.requestPermission, ({ params }) => {
+            if (!instance)
+                return { outcome: { outcome: 'cancelled' } };
+            return instance.requestPermission(params);
+        });
+        const stream = acp.ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+        const connection = app.connect(stream);
+        instance = new AcpSession(options, child, connection);
+        try {
+            await instance.initialize();
+            return instance;
+        }
+        catch (error) {
+            instance.fail(error);
+            await instance.close();
+            throw error;
+        }
+    }
+    isAlive() {
+        return this.child.exitCode === null && !this.child.killed;
+    }
+    snapshot() {
+        return {
+            backend: 'acp',
+            alive: this.isAlive(),
+            readiness: this.readiness,
+            sessionId: this.sessionId,
+            lastError: this.lastError,
+            pendingPermissionId: this.pendingPermissions.keys().next().value,
+        };
+    }
+    /**
+     * 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)
+            return;
+        await this.connection.agent.notify(acp.methods.agent.session.cancel, { sessionId: this.sessionId });
+    }
+    respondPermission(permissionId, optionId) {
+        const pending = this.pendingPermissions.get(permissionId);
+        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;
+    }
+    eventsSince(seq) {
+        return this.events.since(seq);
+    }
+    subscribe(listener) {
+        return this.events.subscribe(listener);
+    }
+    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' } });
+        this.pendingPermissions.clear();
+        if (this.sessionId && this.capabilities?.sessionCapabilities?.close != null) {
+            await this.connection.agent.request(acp.methods.agent.session.close, { sessionId: this.sessionId }).catch(() => undefined);
+        }
+        this.connection.close();
+        if (this.isAlive())
+            this.child.kill('SIGTERM');
+    }
+    async initialize() {
+        const initialized = await this.connection.agent.request(acp.methods.agent.initialize, {
+            protocolVersion: acp.PROTOCOL_VERSION,
+            clientCapabilities: {},
+            clientInfo: { name: 'ours-fleet', version: '1' },
+        });
+        if (initialized.protocolVersion !== acp.PROTOCOL_VERSION)
+            throw new Error(`ACP protocol mismatch: agent selected ${initialized.protocolVersion}, client supports ${acp.PROTOCOL_VERSION}`);
+        this.capabilities = initialized.agentCapabilities;
+        const persisted = this.options.mode === 'resume' && existsSync(this.sessionFile)
+            ? readFileSync(this.sessionFile, 'utf8').trim()
+            : '';
+        if (persisted && this.capabilities?.sessionCapabilities?.resume != null) {
+            await this.connection.agent.request(acp.methods.agent.session.resume, {
+                sessionId: persisted,
+                cwd: this.options.cwd,
+                mcpServers: [],
+            });
+            this.sessionId = persisted;
+        }
+        else if (persisted && this.capabilities?.loadSession) {
+            await this.connection.agent.request(acp.methods.agent.session.load, {
+                sessionId: persisted,
+                cwd: this.options.cwd,
+                mcpServers: [],
+            });
+            this.sessionId = persisted;
+        }
+        else {
+            const created = await this.connection.agent.request(acp.methods.agent.session.new, {
+                cwd: this.options.cwd,
+                mcpServers: [],
+            });
+            this.sessionId = created.sessionId;
+        }
+        writeFileSync(this.sessionFile, this.sessionId + '\n', { mode: 0o600 });
+        this.readiness = 'idle';
+        this.events.emit('state', { status: 'idle', text: `ACP session ${this.sessionId}` });
+    }
+    async runPrompt(text, turnId = randomUUID()) {
+        if (!this.sessionId || !this.isAlive())
+            return turnResult(false, 'failed', this.lastError ?? 'ACP session is offline');
+        this.readiness = 'running';
+        this.events.emit('state', { turnId, status: 'running' });
+        try {
+            const response = await this.connection.agent.request(acp.methods.agent.session.prompt, {
+                sessionId: this.sessionId,
+                prompt: [{ type: 'text', text }],
+            });
+            this.readiness = 'idle';
+            this.events.emit('turn_stop', { turnId, stopReason: response.stopReason });
+            this.events.emit('state', { status: 'idle' });
+            // 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);
+            this.readiness = this.isAlive() ? 'idle' : 'failed';
+            this.events.emit('error', { turnId, text: this.lastError });
+            if (this.isAlive())
+                this.events.emit('state', { status: 'idle' });
+            return turnResult(false, 'failed', this.lastError);
+        }
+    }
+    requestPermission(params) {
+        // `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(this.settleAutomatically(params, option, 'allowed', 'permissions.approval=allow', `the request is inside the ${this.options.permissions.filesystem} boundary`));
+        }
+        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';
+        this.events.emit('permission', {
+            permissionId,
+            toolCallId: params.toolCall.toolCallId,
+            title: params.toolCall.title ?? 'Permission requested',
+            status: 'pending',
+            options: params.options.map(option => ({
+                optionId: option.optionId, name: option.name, kind: option.kind,
+            })),
+        });
+        return new Promise(resolve => {
+            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')
+            return true;
+        if (filesystem === 'read-only' && params.toolCall.kind !== 'read')
+            return false;
+        const locations = params.toolCall.locations ?? [];
+        if (locations.length === 0)
+            return false;
+        const cwd = resolve(this.options.cwd);
+        return locations.every(location => {
+            const path = resolve(location.path);
+            const rel = relative(cwd, path);
+            return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+        });
+    }
+    recordUpdate(update) {
+        switch (update.sessionUpdate) {
+            case 'agent_message_chunk':
+                this.events.emit('agent_text', {
+                    text: update.content.type === 'text' ? update.content.text : `[${update.content.type}]`,
+                });
+                break;
+            case 'agent_thought_chunk':
+                this.events.emit('thought', {
+                    text: update.content.type === 'text' ? update.content.text : `[${update.content.type}]`,
+                });
+                break;
+            case 'tool_call':
+                this.events.emit('tool_call', {
+                    toolCallId: update.toolCallId,
+                    title: update.title,
+                    status: update.status,
+                });
+                break;
+            case 'tool_call_update':
+                this.events.emit('tool_update', {
+                    toolCallId: update.toolCallId,
+                    title: update.title ?? undefined,
+                    status: update.status ?? undefined,
+                });
+                break;
+            default:
+                break;
+        }
+    }
+    fail(error) {
+        this.lastError = error?.message ?? String(error);
+        this.readiness = 'failed';
+        this.events.emit('error', { text: this.lastError });
+    }
+}

package/dist/session/control.d.ts

@@ -0,0 +1,89 @@
+import { type Socket } from 'node:net';
+import type { ControlFailureKind, SessionHandle } from './types.js';
+export interface ControlRequest {
+    version: 1;
+    id: string;
+    token: string;
+    command: 'status' | 'snapshot' | 'submit_prompt' | 'respond_permission' | 'interrupt' | 'follow';
+    text?: string;
+    permissionId?: string;
+    optionId?: string;
+    since?: number;
+}
+export interface ControlResponse {
+    version: 1;
+    id: string;
+    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. */
+export declare class RoleControlServer {
+    private readonly session;
+    private readonly log;
+    private readonly server;
+    private readonly socketPath;
+    private readonly token;
+    private readonly sockets;
+    constructor(stateDir: string, session: SessionHandle, log: (line: string) => void);
+    start(): Promise<void>;
+    close(): Promise<void>;
+    private accept;
+    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;
+    send(request: Omit<ControlRequest, 'version' | 'id' | 'token'>): void;
+}>;