@ours.network/fleet 0.15.1 → 0.15.4

package/dist/session/arbiter.js

@@ -58,12 +58,36 @@ export class RoleTurnArbiter {
     stopScheduledAdmission() { this.stopping = true; }
     isAlive() { return this.session.isAlive(); }
     snapshot() { return this.session.snapshot(); }
+    conversationPage(request = {}) {
+        if (!this.session.conversationPage)
+            throw new Error('conversation ledger is unavailable');
+        return this.session.conversationPage(request);
+    }
+    conversationSnapshot() {
+        if (!this.session.conversationSnapshot)
+            throw new Error('conversation snapshot is unavailable');
+        return this.session.conversationSnapshot();
+    }
+    subscribeConversation(listener) {
+        if (!this.session.subscribeConversation)
+            throw new Error('conversation subscription is unavailable');
+        return this.session.subscribeConversation(listener);
+    }
+    submitPromptBrowser(command) {
+        if (!this.session.submitPromptBrowser)
+            return Promise.reject(new Error('browser prompt admission is unavailable'));
+        return this.exclusive(() => this.session.submitPromptBrowser(command));
+    }
     interrupt(source = 'local-console') {
         return this.exclusive(() => this.session.interrupt(source));
     }
     respondPermission(permissionId, optionId) {
         return this.session.respondPermission(permissionId, optionId);
     }
+    respondPermissionV2(permissionId, optionId, sessionGeneration) {
+        return this.session.respondPermissionV2?.(permissionId, optionId, sessionGeneration)
+            ?? 'stale';
+    }
     eventsSince(seq) { return this.session.eventsSince(seq); }
     subscribe(listener) { return this.session.subscribe(listener); }
     setControllerAttached(attached) { this.session.setControllerAttached(attached); }

package/dist/session/control.d.ts

@@ -2,11 +2,13 @@ import { type Socket } from 'node:net';
 import type { ControlFailureKind, SessionHandle } from './types.js';
 import type { OwnerChannelHandle, OwnerChannelManagementRequest } from '../owner-channel/channel.js';
 import type { ScheduledLoopManagerHandle } from '../loops/manager.js';
+import type { SpawnOpts } from '../spawn.js';
+import type { ManagedFleetSpawnResult } from '../fleet-proxy.js';
 export interface ControlRequest {
-    version: 1 | 2;
+    version: 1 | 2 | 3;
     id: string;
     token: string;
-    command: 'status' | 'snapshot' | 'submit_prompt' | 'respond_permission' | 'interrupt' | 'follow' | 'events_since' | 'owner_channel_manage' | 'loop_status' | 'loop_run_now' | 'loop_disable' | 'loop_enable' | 'reload_config';
+    command: 'status' | 'snapshot' | 'submit_prompt' | 'respond_permission' | 'interrupt' | 'follow' | 'events_since' | 'owner_channel_manage' | 'loop_status' | 'loop_run_now' | 'loop_disable' | 'loop_enable' | 'reload_config' | 'conversation_page' | 'conversation_follow' | 'submit_prompt_v2' | 'interrupt_v2' | 'respond_permission_v2' | 'fleet_spawn';
     text?: string;
     permissionId?: string;
     optionId?: string;
@@ -15,6 +17,19 @@ export interface ControlRequest {
     controller?: boolean;
     ownerChannel?: OwnerChannelManagementRequest;
     loop?: string;
+    /** Conversation cursor: replay strictly after this durable seq. */
+    after?: string;
+    limit?: number;
+    /** Idempotency key for v3 mutations. */
+    commandId?: string;
+    /** Browser-session digest recorded as the acting principal. */
+    actor?: string;
+    /** Server-stamped provenance. User-controlled text cannot set this field. */
+    source?: 'owner_admin_console';
+    /** Runner generation shown with a permission card. */
+    sessionGeneration?: string;
+    /** Typed managed-spawn request accepted only over the authenticated role control plane. */
+    spawn?: SpawnOpts;
 }
 export interface ControlResponse {
     version: 1;
@@ -75,9 +90,12 @@ export declare class RoleControlServer {
     private readonly socketPath;
     private readonly token;
     private readonly sockets;
+    /** Interrupt idempotency: same command id returns the first receipt. */
+    private readonly interruptCommands;
     private ownerChannel?;
     private loopManager?;
     private reloadConfig?;
+    private fleetSpawner?;
     constructor(stateDir: string, session: SessionHandle, log: (line: string) => void);
     start(): Promise<void>;
     close(): Promise<void>;
@@ -85,8 +103,11 @@ export declare class RoleControlServer {
     setOwnerChannel(ownerChannel: OwnerChannelHandle | undefined): void;
     setLoopManager(loopManager: ScheduledLoopManagerHandle | undefined): void;
     setConfigReloader(reloadConfig: (() => Promise<unknown>) | undefined): void;
+    setFleetSpawner(fleetSpawner: ((options: SpawnOpts) => Promise<ManagedFleetSpawnResult>) | undefined): void;
     private accept;
     private handle;
+    /** Version and capability gate shared by every conversation v3 command. */
+    private requireConversation;
     private write;
 }
 /**
@@ -100,3 +121,13 @@ export declare function followControl(stateDir: string, onMessage: (message: Rec
     socket: Socket;
     send(request: Omit<ControlRequest, 'version' | 'id' | 'token'>): void;
 }>;
+/**
+ * Open a live conversation follow on the role's private control socket. The
+ * first message is the initial page + snapshot; every subsequent message is
+ * `{ version, conversationEvent }`. Closing the socket detaches the
+ * controller-presence this connection contributed.
+ */
+export declare function followConversation(stateDir: string, after: string | undefined, onMessage: (message: Record<string, unknown>) => void): Promise<{
+    socket: Socket;
+    close(): void;
+}>;

package/dist/session/control.js

@@ -4,6 +4,11 @@ import { createConnection, createServer } from 'node:net';
 import { join } from 'node:path';
 import { SessionControlError } from './types.js';
 const MAX_LINE_BYTES = 64 * 1024;
+/** Commands that require protocol version 3. */
+const V3_COMMANDS = new Set([
+    'conversation_page', 'conversation_follow', 'submit_prompt_v2', 'interrupt_v2',
+    'respond_permission_v2',
+]);
 /**
  * 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
@@ -95,9 +100,12 @@ export class RoleControlServer {
     socketPath;
     token;
     sockets = new Set();
+    /** Interrupt idempotency: same command id returns the first receipt. */
+    interruptCommands = new Map();
     ownerChannel;
     loopManager;
     reloadConfig;
+    fleetSpawner;
     constructor(stateDir, session, log) {
         this.session = session;
         this.log = log;
@@ -140,6 +148,9 @@ export class RoleControlServer {
     setConfigReloader(reloadConfig) {
         this.reloadConfig = reloadConfig;
     }
+    setFleetSpawner(fleetSpawner) {
+        this.fleetSpawner = fleetSpawner;
+    }
     accept(socket) {
         this.sockets.add(socket);
         socket.setEncoding('utf8');
@@ -192,7 +203,7 @@ export class RoleControlServer {
             this.write(socket, { version: 1, id: '?', ok: false, error: 'invalid JSON' });
             return;
         }
-        if ((request.version !== 1 && request.version !== 2) || typeof request.id !== 'string'
+        if (![1, 2, 3].includes(request.version) || typeof request.id !== 'string'
             || !sameToken(this.token, request.token ?? '')) {
             this.write(socket, { version: 1, id: request.id ?? '?', ok: false, error: 'unauthorized' });
             return;
@@ -204,8 +215,12 @@ export class RoleControlServer {
                     this.write(socket, {
                         version: 1, id: request.id, ok: true,
                         result: {
-                            ...this.session.snapshot(), protocolVersion: 2,
-                            features: ['events_since', 'observer_follow', 'retained_range'],
+                            ...this.session.snapshot(),
+                            protocolVersion: this.session.conversationPage ? 3 : 2,
+                            features: [
+                                'events_since', 'observer_follow', 'retained_range',
+                                ...(this.session.conversationPage ? ['conversation_v3'] : []),
+                            ],
                         },
                     });
                     return;
@@ -271,6 +286,15 @@ export class RoleControlServer {
                     });
                     return;
                 }
+                case 'fleet_spawn': {
+                    if (request.version !== 2 || !request.spawn || typeof request.spawn.name !== 'string')
+                        throw new SessionControlError('rejected', 'version 2 and typed spawn options are required');
+                    if (!this.fleetSpawner)
+                        throw new SessionControlError('rejected', 'managed fleet spawning is unavailable for this role');
+                    const result = await this.fleetSpawner(request.spawn);
+                    this.write(socket, { version: 1, id: request.id, ok: true, result });
+                    return;
+                }
                 case 'owner_channel_manage': {
                     if (!request.ownerChannel || typeof request.ownerChannel.action !== 'string')
                         throw new SessionControlError('rejected', 'owner-channel management action is required');
@@ -314,6 +338,90 @@ export class RoleControlServer {
                                 socket.write(JSON.stringify({ version: 1, event }) + '\n');
                         }) };
                 }
+                case 'conversation_page': {
+                    this.requireConversation(request);
+                    this.write(socket, {
+                        version: 1, id: request.id, ok: true,
+                        result: this.session.conversationPage({
+                            after: request.after, limit: request.limit,
+                        }),
+                    });
+                    return;
+                }
+                case 'conversation_follow': {
+                    this.requireConversation(request);
+                    this.write(socket, {
+                        version: 1, id: request.id, ok: true,
+                        result: this.session.conversationPage({
+                            after: request.after, limit: request.limit,
+                        }),
+                    });
+                    // A live conversation view is an attached controller: permission
+                    // requests must reach it instead of the unattended policy.
+                    const controller = request.controller !== false;
+                    if (controller)
+                        this.session.setControllerAttached(true);
+                    return { controller, stop: this.session.subscribeConversation(event => {
+                            if (!socket.destroyed)
+                                socket.write(JSON.stringify({ version: 1, conversationEvent: event }) + '\n');
+                        }) };
+                }
+                case 'submit_prompt_v2': {
+                    this.requireConversation(request);
+                    if (!request.commandId?.trim() || !request.text?.trim() || !request.actor?.trim()
+                        || request.source !== 'owner_admin_console')
+                        throw new SessionControlError('rejected', 'commandId, text, actor and authenticated source are required');
+                    if (!this.session.submitPromptBrowser)
+                        throw new SessionControlError('rejected', 'browser prompt admission is unavailable for this role');
+                    try {
+                        const receipt = await this.session.submitPromptBrowser({
+                            commandId: request.commandId, text: request.text,
+                            source: 'owner_admin_console', actorBrowserSession: request.actor,
+                        });
+                        this.write(socket, { version: 1, id: request.id, ok: true, result: receipt });
+                    }
+                    catch (error) {
+                        if (error.name === 'IdempotencyConflictError')
+                            throw new SessionControlError('rejected', 'idempotency_conflict: this command id was used with a different prompt body');
+                        throw error;
+                    }
+                    return;
+                }
+                case 'interrupt_v2': {
+                    this.requireConversation(request);
+                    if (!request.commandId?.trim())
+                        throw new SessionControlError('rejected', 'commandId is required');
+                    const existing = this.interruptCommands.get(request.commandId);
+                    if (existing) {
+                        this.write(socket, { version: 1, id: request.id, ok: true, result: existing });
+                        return;
+                    }
+                    await this.session.interrupt('local-console');
+                    const receipt = { accepted: true, commandId: request.commandId, at: new Date().toISOString() };
+                    this.interruptCommands.set(request.commandId, receipt);
+                    if (this.interruptCommands.size > 200) {
+                        const oldest = this.interruptCommands.keys().next().value;
+                        this.interruptCommands.delete(oldest);
+                    }
+                    this.write(socket, { version: 1, id: request.id, ok: true, result: receipt });
+                    return;
+                }
+                case 'respond_permission_v2': {
+                    this.requireConversation(request);
+                    if (!request.commandId?.trim() || !request.permissionId?.trim()
+                        || !request.optionId?.trim() || !request.sessionGeneration?.trim())
+                        throw new SessionControlError('rejected', 'commandId, permissionId, optionId and sessionGeneration are required');
+                    if (!this.session.respondPermissionV2)
+                        throw new SessionControlError('rejected', 'generation-bound permission responses are unavailable for this role');
+                    const result = this.session.respondPermissionV2(request.permissionId, request.optionId, request.sessionGeneration);
+                    if (result === 'stale')
+                        throw new SessionControlError('rejected', 'stale_state: permission is settled, expired, invalid, or belongs to another session generation');
+                    this.write(socket, {
+                        version: 1, id: request.id, ok: true,
+                        result: { accepted: true, commandId: request.commandId },
+                    });
+                    return;
+                }
             }
         }
         catch (error) {
@@ -328,6 +436,13 @@ export class RoleControlServer {
             });
         }
     }
+    /** Version and capability gate shared by every conversation v3 command. */
+    requireConversation(request) {
+        if (request.version !== 3)
+            throw new SessionControlError('rejected', 'protocol version 3 is required for conversation commands');
+        if (!this.session.conversationPage || !this.session.subscribeConversation)
+            throw new SessionControlError('rejected', 'this role has no conversation ledger');
+    }
     write(socket, response) {
         if (!socket.destroyed)
             socket.write(JSON.stringify(response) + '\n');
@@ -376,7 +491,7 @@ export async function controlRequest(stateDir, request, timeoutMs = 120_000) {
             socket.end();
         });
         socket.once('connect', () => socket.write(JSON.stringify({
-            version: 2, id, token, ...request,
+            version: V3_COMMANDS.has(request.command) ? 3 : 2, id, token, ...request,
         }) + '\n'));
     });
 }
@@ -401,7 +516,45 @@ export async function followControl(stateDir, onMessage) {
         socket.once('connect', resolve);
         socket.once('error', reject);
     });
-    const send = (request) => socket.write(JSON.stringify({ version: 1, id: randomUUID(), token, ...request }) + '\n');
+    const send = (request) => socket.write(JSON.stringify({
+        version: V3_COMMANDS.has(request.command) ? 3 : 1, id: randomUUID(), token, ...request,
+    }) + '\n');
     send({ command: 'follow', since: 0 });
     return { socket, send };
 }
+/**
+ * Open a live conversation follow on the role's private control socket. The
+ * first message is the initial page + snapshot; every subsequent message is
+ * `{ version, conversationEvent }`. Closing the socket detaches the
+ * controller-presence this connection contributed.
+ */
+export async function followConversation(stateDir, after, onMessage) {
+    const token = readFileSync(controlTokenPath(stateDir), 'utf8').trim();
+    const socket = createConnection(controlSocketPath(stateDir));
+    socket.setEncoding('utf8');
+    let buffer = '';
+    socket.on('data', chunk => {
+        buffer += chunk;
+        for (;;) {
+            const newline = buffer.indexOf('\n');
+            if (newline < 0)
+                break;
+            const line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            if (!line.trim())
+                continue;
+            try {
+                onMessage(JSON.parse(line));
+            }
+            catch { /* a torn frame ends this stream; the client resyncs over HTTP */ }
+        }
+    });
+    await new Promise((resolve, reject) => {
+        socket.once('connect', resolve);
+        socket.once('error', reject);
+    });
+    socket.write(JSON.stringify({
+        version: 3, id: randomUUID(), token, command: 'conversation_follow', after,
+    }) + '\n');
+    return { socket, close: () => socket.destroy() };
+}

package/dist/session/conversation-normalizer.d.ts

@@ -0,0 +1,34 @@
+import type * as acp from '@agentclientprotocol/sdk';
+import type { AdapterMeta, ConversationEventKind, ConversationPayload } from './conversation-types.js';
+/**
+ * Reduce one ACP v1 `session/update` into one conversation-domain event draft.
+ *
+ * This is the protocol seam: v1 create/update pairs (and a future v2 upsert
+ * stream) both land in the same domain shapes. The function is pure and total —
+ * it never throws, never passes raw wire objects through, caps every payload,
+ * and quarantines namespaced `_meta` so unknown extensions cannot leak into
+ * generic rendering paths.
+ */
+/** Cap for any single normalized text payload (spec §5.3). */
+export declare const MAX_TEXT_BYTES: number;
+/** Cap for one adapter `_meta` namespace value. */
+export declare const MAX_META_BYTES: number;
+/** Cap for serialized raw tool input/output retained as structured JSON. */
+export declare const MAX_RAW_JSON_BYTES: number;
+/** Cap for the sanitized preview of an unsupported update. */
+export declare const MAX_UNSUPPORTED_PREVIEW_CHARS = 2048;
+export interface NormalizeOptions {
+    /**
+     * Replace every text payload with this placeholder, keeping byte count and
+     * digest. Used for scheduled-loop turns whose output must not be retained.
+     */
+    redactText?: string;
+}
+export interface NormalizedUpdate {
+    kind: ConversationEventKind;
+    payload: ConversationPayload;
+    messageId?: string;
+    toolCallId?: string;
+    adapterMeta?: AdapterMeta[];
+}
+export declare function normalizeSessionUpdate(update: acp.SessionUpdate, options?: NormalizeOptions): NormalizedUpdate;