@ours.network/fleet 1.2.0-nightly.6 → 1.2.0-nightly.60

package/dist/application/room-layout-definitions.js

@@ -0,0 +1,130 @@
+/** Web authoring of `fleet/room_layouts/<name>.yaml`.
+ * Writes are revision-guarded (sha256 of the file bytes) and validated with the
+ * same parser the CLI uses. Retained layout runs keep their own snapshots, so
+ * editing or deleting a definition never changes an existing run.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { stringify } from 'yaml';
+import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
+import { parseFleetDocument } from '../config-yaml.js';
+import { defaultConfigPath } from '../paths.js';
+import { loadConfig, splitRootFor } from '../config.js';
+import { assertLayoutFile, validLayoutKey, validateRoomLayout } from '../rooms-tasks/layout-config.js';
+import { FleetError } from './errors.js';
+import { layoutDefinitionHash } from './task-layouts.js';
+export const ABSENT_REVISION = 'absent';
+const revisionOf = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export class RoomLayoutDefinitions {
+    configPath;
+    deps;
+    constructor(configPath, deps = {}) {
+        this.configPath = configPath;
+        this.deps = deps;
+    }
+    root() { return join(splitRootFor(this.configPath ?? defaultConfigPath()), 'room_layouts'); }
+    pathFor(name) {
+        if (!validLayoutKey(name))
+            throw new FleetError('invalid_request', 'layout name must start with a letter and use letters, digits, - or _');
+        return join(this.root(), `${name}.yaml`);
+    }
+    currentRevision(path) {
+        if (!existsSync(path))
+            return ABSENT_REVISION;
+        assertLayoutFile(path);
+        return revisionOf(readFileSync(path));
+    }
+    /** Agent-template references that do not resolve in the current Fleet configuration. */
+    templateIssues(definition) {
+        let templates = {};
+        try {
+            templates = (this.deps.loadConfiguration ?? loadConfig)(this.configPath).agentTemplates ?? {};
+        }
+        catch (error) {
+            return [`fleet configuration unavailable: ${error.message}`];
+        }
+        return Object.entries(definition.participants).flatMap(([key, participant]) => participant.agent_template && !Object.hasOwn(templates, participant.agent_template)
+            ? [`participant ${key}: agent template not found: ${participant.agent_template}`] : []);
+    }
+    /** The configured default (`rooms.defaults.template`, else `tasks.default_room_template`) when it names a usable layout. */
+    defaultLayout(entries = this.list()) {
+        let name;
+        try {
+            const config = (this.deps.loadConfiguration ?? loadConfig)(this.configPath);
+            name = config.rooms?.defaults?.template ?? config.tasks?.default_room_template;
+        }
+        catch {
+            return undefined;
+        }
+        const entry = entries.find(e => e.name === name);
+        return entry && !('error' in entry) && !entry.issues.length ? entry.name : undefined;
+    }
+    list() {
+        const root = this.root();
+        if (!existsSync(root))
+            return [];
+        assertLayoutFile(root, true);
+        return readdirSync(root).filter(file => /\.ya?ml$/.test(file)).sort().map(file => {
+            const name = basename(file, extname(file)), path = join(root, file);
+            try {
+                if (!validLayoutKey(name))
+                    throw Error(`invalid room layout id: ${name}`);
+                assertLayoutFile(path);
+                const bytes = readFileSync(path);
+                const definition = validateRoomLayout(parseFleetDocument(path, bytes.toString('utf8'), 'strict').value, file);
+                return { name, file, revision: revisionOf(bytes), definition, issues: this.templateIssues(definition), definition_hash: layoutDefinitionHash(definition) };
+            }
+            catch (error) {
+                // Only a trusted regular file may be read to offer an overwrite revision.
+                let revision = ABSENT_REVISION;
+                try {
+                    assertLayoutFile(path);
+                    revision = revisionOf(readFileSync(path));
+                }
+                catch { /* not trusted: never read */ }
+                return { name, file, revision, error: error.message };
+            }
+        });
+    }
+    validate(raw) {
+        let definition;
+        try {
+            definition = validateRoomLayout(raw, 'room layout');
+        }
+        catch (error) {
+            return { issues: [error.message] };
+        }
+        return { definition, issues: this.templateIssues(definition) };
+    }
+    async save(name, expectedRevision, raw) {
+        const path = this.pathFor(name);
+        const { definition, issues } = this.validate(raw);
+        if (!definition || issues.length)
+            throw new FleetError('invalid_request', issues.join('; '));
+        const root = this.root();
+        mkdirSync(root, { recursive: true, mode: 0o700 });
+        assertLayoutFile(root, true);
+        return withFileLock(`${path}.lock`, async () => {
+            const current = this.currentRevision(path);
+            if (current !== expectedRevision)
+                throw new FleetError('stale_state', 'room layout changed since it was loaded; reload before saving');
+            const { description, participants, rooms } = definition;
+            const text = stringify({ version: 1, ...(description ? { description } : {}), participants, rooms });
+            replaceFileAtomically(path, text, 0o600);
+            return { name, revision: revisionOf(text), definition };
+        });
+    }
+    async remove(name, expectedRevision) {
+        const path = this.pathFor(name);
+        return withFileLock(`${path}.lock`, async () => {
+            const current = this.currentRevision(path);
+            if (current === ABSENT_REVISION)
+                return { name, deleted: false };
+            if (current !== expectedRevision)
+                throw new FleetError('stale_state', 'room layout changed since it was loaded; reload before deleting');
+            unlinkSync(path);
+            return { name, deleted: true };
+        });
+    }
+}

package/dist/application/session-control.d.ts

@@ -1,3 +1,5 @@
+import { type ConversationTailPage } from './conversation-history.js';
+import type { AgentHistoryQuery } from '../agent-ours/correspondence.js';
 import { controlRequest } from '../session/control.js';
 import type { ConversationEventV1, ConversationSnapshot, PromptReceipt } from '../session/conversation-types.js';
 import type { SessionSnapshot } from '../session/types.js';
@@ -23,6 +25,8 @@ export interface InterruptReceipt {
     reasonCode?: string;
 }
 export interface RoleSessionControl {
+    agentContacts?(): Promise<unknown>;
+    agentHistory?(request: AgentHistoryQuery): Promise<unknown>;
     describe(): Promise<SessionDescriptor>;
     snapshot(): Promise<SessionSnapshot>;
     recentOutput(request?: {
@@ -41,12 +45,24 @@ export interface RoleSessionControl {
         after?: string;
         limit?: number;
     }): Promise<ConversationPageView>;
+    /** The newest visible events (or those before `before`), read backwards from the ledger. */
+    conversationTail?(request: {
+        before?: string;
+        limit?: number;
+    }): Promise<ConversationTailPage>;
     submitPromptV2?(request: {
         commandId: string;
         text: string;
         actorBrowserSession: string;
+        expectedSessionGeneration?: string;
+        requireIdle?: boolean;
         source: 'owner_admin_console';
     }): Promise<PromptReceipt>;
+    interruptPromptV2?(request: {
+        commandId: string;
+        expectedSessionGeneration: string;
+        promptId: string;
+    }): Promise<InterruptReceipt>;
     interruptV2?(commandId: string): Promise<InterruptReceipt & {
         commandId: string;
     }>;
@@ -75,6 +91,9 @@ export declare class RoleSessionControlAdapter implements RoleSessionControl {
     private readonly stateDir;
     private readonly request;
     constructor(stateDir: string, request?: typeof controlRequest);
+    agentContacts(): Promise<unknown>;
+    agentHistory(request: AgentHistoryQuery): Promise<unknown>;
+    private requireCorrespondence;
     describe(): Promise<SessionDescriptor>;
     snapshot(): Promise<SessionSnapshot>;
     recentOutput(request?: {
@@ -87,12 +106,23 @@ export declare class RoleSessionControlAdapter implements RoleSessionControl {
         after?: string;
         limit?: number;
     }): Promise<ConversationPageView>;
+    conversationTail(request?: {
+        before?: string;
+        limit?: number;
+    }): Promise<ConversationTailPage>;
     submitPromptV2(request: {
         commandId: string;
         text: string;
         actorBrowserSession: string;
+        expectedSessionGeneration?: string;
+        requireIdle?: boolean;
         source: 'owner_admin_console';
     }): Promise<PromptReceipt>;
+    interruptPromptV2(request: {
+        commandId: string;
+        expectedSessionGeneration: string;
+        promptId: string;
+    }): Promise<InterruptReceipt>;
     interruptV2(commandId: string): Promise<InterruptReceipt & {
         commandId: string;
     }>;

package/dist/application/session-control.js

@@ -1,3 +1,6 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { conversationTailPage, resumedConversationPage } from './conversation-history.js';
 import { controlRequest, followConversation } from '../session/control.js';
 import { FleetError, normalizeError } from './errors.js';
 const visibleEvents = (events) => events.filter(event => event.kind !== 'thought');
@@ -8,6 +11,10 @@ export class RoleSessionControlAdapter {
         this.stateDir = stateDir;
         this.request = request;
     }
+    async agentContacts() { await this.requireCorrespondence(); return this.call('agent_contacts'); }
+    async agentHistory(request) { await this.requireCorrespondence(); return this.call('agent_history', { agentHistory: request }); }
+    async requireCorrespondence() { if (!(await this.describe()).features.includes('agent_correspondence'))
+        throw new FleetError('capability_unavailable', 'This session needs an updated supervisor to show contacts and history.'); }
     async describe() {
         const response = await this.call('snapshot');
         const result = response;
@@ -58,28 +65,90 @@ export class RoleSessionControlAdapter {
         };
     }
     async conversationPage(request = {}) {
-        return await this.call('conversation_page', {
+        const live = await this.call('conversation_page', {
             after: request.after, limit: request.limit,
         });
+        const snapshot = await this.snapshot();
+        if (snapshot.backend !== 'acp' || !snapshot.sessionId)
+            return live;
+        try {
+            const history = await resumedConversationPage(this.stateDir, request, live, snapshot.sessionId);
+            const check = await this.call('conversation_page', { limit: 1 });
+            return check.snapshot.sessionGeneration === live.snapshot.sessionGeneration ? history : await this.call('conversation_page', request);
+        }
+        catch {
+            return live;
+        }
+    }
+    async conversationTail(request = {}) {
+        const live = await this.call('conversation_page', { limit: 1 });
+        const snapshot = await this.snapshot();
+        let resumed;
+        if (snapshot.backend === 'acp' && snapshot.sessionId) {
+            try {
+                if ((await readFile(join(this.stateDir, '.acp-session-id'), 'utf8')).trim() === snapshot.sessionId)
+                    resumed = snapshot.sessionId;
+            }
+            catch { /* no resumed history: live generation only */ }
+        }
+        try {
+            return await conversationTailPage(this.stateDir, request, live.snapshot, resumed);
+        }
+        catch (error) {
+            throw new FleetError('invalid_request', error.message);
+        }
     }
     async submitPromptV2(request) {
         if (!request.text.trim())
             throw new FleetError('invalid_request', 'text is required');
         if (Buffer.byteLength(request.text) > 32 * 1024)
             throw new FleetError('invalid_request', 'text exceeds 32 KiB');
+        // A prompt bound to a session generation (voice or attachments) is checked atomically by supervisors that
+        // support it. Older supervisors do not know that command and never answer, so check the generation here
+        // and submit an ordinary prompt; its command id keeps retries idempotent either way.
+        const features = request.requireIdle ? (await this.describe()).features : undefined;
+        if (request.requireIdle && (!request.expectedSessionGeneration || !features?.includes('idle_bound_prompts')))
+            throw new FleetError('capability_unavailable', 'Live voice requires an updated supervisor.');
+        let command = 'submit_prompt_v2';
+        if (request.expectedSessionGeneration) {
+            if ((await this.describe()).features.includes('generation_bound_prompts'))
+                command = 'submit_voice_prompt';
+            else {
+                const live = await this.call('conversation_page', { limit: 1 });
+                if (live.snapshot?.sessionGeneration !== request.expectedSessionGeneration)
+                    throw new FleetError('stale_state', 'Agent session changed. Record a new voice message.');
+            }
+        }
         try {
-            return await this.call('submit_prompt_v2', {
+            return await this.call(command, {
                 commandId: request.commandId, text: request.text, actor: request.actorBrowserSession,
-                source: request.source,
+                source: request.source, expectedSessionGeneration: request.expectedSessionGeneration, requireIdle: request.requireIdle,
             });
         }
         catch (error) {
             const fleetError = normalizeError(error);
+            if (fleetError.message.includes('session_changed:'))
+                throw new FleetError('stale_state', 'Agent session changed. Record a new voice message.');
+            if (fleetError.message.includes('voice_busy:'))
+                throw new FleetError('conflict', 'Agent is already working. Wait for the current turn.');
             if (fleetError.message.includes('idempotency_conflict'))
                 throw new FleetError('idempotency_conflict', 'this command id was already used with a different prompt body');
             throw fleetError;
         }
     }
+    async interruptPromptV2(request) {
+        if (!(await this.describe()).features.includes('targeted_voice_interrupt'))
+            throw new FleetError('capability_unavailable', 'Live voice requires an updated supervisor.');
+        try {
+            return await this.call('interrupt_voice_v2', request);
+        }
+        catch (error) {
+            const failure = normalizeError(error);
+            if (failure.message.includes('session_changed:'))
+                throw new FleetError('stale_state', 'Agent session changed.');
+            throw failure;
+        }
+    }
     async interruptV2(commandId) {
         const receipt = await this.call('interrupt_v2', { commandId });
         return {

package/dist/application/supervisor-ours-tools.d.ts

@@ -0,0 +1,159 @@
+export interface SupervisorToolRequest {
+    tool: string;
+    arguments?: Record<string, unknown>;
+}
+/** CLI and REST use the same fixed-identity MCP server as the agent harness. */
+export declare class SupervisorOursTools {
+    private withClient;
+    list(role: string): Promise<{
+        tools: {
+            inputSchema: {
+                [x: string]: unknown;
+                type: "object";
+                properties?: Record<string, object> | undefined;
+                required?: string[] | undefined;
+            };
+            name: string;
+            description?: string | undefined;
+            outputSchema?: {
+                [x: string]: unknown;
+                type: "object";
+                properties?: Record<string, object> | undefined;
+                required?: string[] | undefined;
+            } | undefined;
+            annotations?: {
+                title?: string | undefined;
+                readOnlyHint?: boolean | undefined;
+                destructiveHint?: boolean | undefined;
+                idempotentHint?: boolean | undefined;
+                openWorldHint?: boolean | undefined;
+            } | undefined;
+            execution?: {
+                taskSupport?: "optional" | "required" | "forbidden" | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        }[];
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        nextCursor?: string | undefined;
+        agent: string;
+        identity: {
+            name: string;
+            cid: string;
+            generation: number;
+        };
+    }>;
+    call(role: string, request: SupervisorToolRequest): Promise<{
+        agent: string;
+        identity: {
+            name: string;
+            cid: string;
+            generation: number;
+        };
+        result: {
+            [x: string]: unknown;
+            content: ({
+                type: "text";
+                text: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                type: "image";
+                data: string;
+                mimeType: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                type: "audio";
+                data: string;
+                mimeType: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                type: "resource";
+                resource: {
+                    uri: string;
+                    text: string;
+                    mimeType?: string | undefined;
+                    _meta?: Record<string, unknown> | undefined;
+                } | {
+                    uri: string;
+                    blob: string;
+                    mimeType?: string | undefined;
+                    _meta?: Record<string, unknown> | undefined;
+                };
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                uri: string;
+                name: string;
+                type: "resource_link";
+                description?: string | undefined;
+                mimeType?: string | undefined;
+                size?: number | undefined;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                icons?: {
+                    src: string;
+                    mimeType?: string | undefined;
+                    sizes?: string[] | undefined;
+                    theme?: "light" | "dark" | undefined;
+                }[] | undefined;
+                title?: string | undefined;
+            })[];
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+            structuredContent?: Record<string, unknown> | undefined;
+            isError?: boolean | undefined;
+        } | {
+            [x: string]: unknown;
+            toolResult: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        };
+    }>;
+}

package/dist/application/supervisor-ours-tools.js

@@ -0,0 +1,115 @@
+import { socketPath } from '../socket-path.js';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { agentDir } from '../paths.js';
+import { ROLE_NAME_RE } from '../config.js';
+import { legacySupervisorIdentity } from './legacy-supervisor-identity.js';
+import { FleetError } from './errors.js';
+/** CLI and REST use the same fixed-identity MCP server as the agent harness. */
+export class SupervisorOursTools {
+    async withClient(role, work) {
+        if (!ROLE_NAME_RE.test(role))
+            throw new FleetError('invalid_request', 'invalid agent name');
+        const findCandidates = () => [false, true].map(temporary => ({ temporary, dir: agentDir(role, temporary) }))
+            .map(row => ({ ...row, path: join(row.dir, '.ours-bridge', 'descriptor.json') }))
+            .filter(row => existsSync(row.path));
+        const candidates = findCandidates();
+        if (candidates.length !== 1)
+            throw new FleetError('capability_unavailable', 'agent supervisor endpoint is missing or ambiguous');
+        const selected = candidates[0];
+        let descriptor;
+        let identityName;
+        try {
+            descriptor = JSON.parse(readFileSync(selected.path, 'utf8'));
+            identityName = readFileSync(join(selected.dir, '.identity'), 'utf8').trim();
+            if (!descriptor || typeof descriptor !== 'object')
+                throw new Error();
+        }
+        catch {
+            throw new FleetError('capability_unavailable', 'supervisor identity metadata cannot be read');
+        }
+        const legacy = ['role', 'identity', 'cid'].every(key => descriptor[key] === undefined);
+        const identity = legacy
+            ? legacySupervisorIdentity(role, identityName, selected.temporary, descriptor.generation)
+            : { name: identityName, cid: descriptor.cid, generation: descriptor.generation };
+        const legacySocket = join(selected.dir, '.ours-bridge', `g${descriptor.generation}.sock`);
+        if (legacy && descriptor.socket !== legacySocket && descriptor.socket !== socketPath(legacySocket))
+            throw new FleetError('capability_unavailable', 'legacy supervisor socket does not match the selected agent');
+        if ((!legacy && (descriptor.role !== role || descriptor.identity !== identityName))
+            || !/^[a-f0-9]{64}$/i.test(identity.cid ?? '') || !Number.isSafeInteger(descriptor.generation) || descriptor.generation < 1)
+            throw new FleetError('capability_unavailable', 'supervisor identity metadata is unavailable or mismatched');
+        const verifySelection = () => {
+            try {
+                const current = findCandidates();
+                const freshDescriptor = JSON.parse(readFileSync(selected.path, 'utf8'));
+                if (current.length !== 1 || current[0].path !== selected.path
+                    || readFileSync(join(selected.dir, '.identity'), 'utf8').trim() !== identityName
+                    || ['role', 'identity', 'cid', 'socket', 'capability', 'generation']
+                        .some(key => freshDescriptor[key] !== descriptor[key]))
+                    throw new Error();
+            }
+            catch {
+                throw new FleetError('capability_unavailable', 'selected supervisor assignment changed');
+            }
+        };
+        const client = new Client({ name: 'ours-fleet-supervisor-tools', version: '1' });
+        const transport = new StdioClientTransport({
+            command: process.execPath,
+            args: [fileURLToPath(new URL('../agent-ours/bridge.js', import.meta.url))],
+            env: { ...Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined)),
+                FLEET_OURS_BRIDGE_DESCRIPTOR: selected.path,
+                FLEET_OURS_BRIDGE_EXPECTED: JSON.stringify({ role: descriptor.role, identity: descriptor.identity, cid: descriptor.cid, generation: descriptor.generation,
+                    transportDigest: createHash('sha256').update(JSON.stringify([descriptor.socket, descriptor.capability, descriptor.generation])).digest('hex') }) },
+            stderr: 'pipe',
+        });
+        try {
+            await client.connect(transport);
+            const verify = async () => {
+                if (!legacy) {
+                    verifySelection();
+                    return;
+                }
+                // The supervisor owns the binding. The authenticated bridge and pinned local
+                // assignment are authoritative; current_identity is display text, not a protocol.
+                const fresh = legacySupervisorIdentity(role, identityName, selected.temporary, descriptor.generation);
+                if (!('proof' in identity) || fresh.proof !== identity.proof)
+                    throw new FleetError('capability_unavailable', 'legacy supervisor identity changed');
+                verifySelection();
+            };
+            await verify();
+            return await work(client, { name: identity.name, cid: identity.cid, generation: identity.generation }, verify);
+        }
+        catch (error) {
+            if (error instanceof FleetError)
+                throw error;
+            // Do not leak arguments, invites, capabilities, or raw transport errors.
+            throw new FleetError('control_unavailable', 'supervisor tool request failed; its outcome may be unknown, do not retry a mutation automatically', { retryable: false });
+        }
+        finally {
+            await client.close().catch(() => { });
+            await transport.close().catch(() => { });
+        }
+    }
+    list(role) {
+        return this.withClient(role, async (client, identity) => ({
+            agent: role, identity, ...(await client.listTools()),
+        }));
+    }
+    call(role, request) {
+        if (!request || typeof request.tool !== 'string'
+            || (request.arguments !== undefined && (!request.arguments || typeof request.arguments !== 'object' || Array.isArray(request.arguments))))
+            throw new FleetError('invalid_request', 'tool and object arguments are required');
+        return this.withClient(role, async (client, identity, verify) => {
+            const { tools } = await client.listTools();
+            if (!tools.some(tool => tool.name === request.tool))
+                throw new FleetError('forbidden', 'tool is not exposed by the fixed-identity supervisor');
+            await verify();
+            const result = await client.callTool({ name: request.tool, arguments: request.arguments ?? {} });
+            return { agent: role, identity, result };
+        });
+    }
+}