@ours.network/fleet 1.2.0-nightly.1 → 1.2.0-nightly.11

package/dist/agent-ours/mcp-endpoint.d.ts

@@ -0,0 +1,15 @@
+import type { ApplicationIdentityStore } from '@ours.network/mcp/application-identities';
+import type { OursClient } from '@ours.network/sdk/client';
+import type { AgentOursRuntime } from './runtime.js';
+export interface EndpointOptions {
+    socket: string;
+    capability: string;
+    generation: number;
+    runtime: AgentOursRuntime;
+    client: OursClient;
+    identities: ApplicationIdentityStore;
+    remoteDaemonFiles: boolean;
+}
+export declare function startMcpEndpoint(options: EndpointOptions): Promise<{
+    close(): Promise<void>;
+}>;

package/dist/agent-ours/mcp-endpoint.js

@@ -0,0 +1,111 @@
+import { createServer } from 'node:net';
+import { chmod, unlink } from 'node:fs/promises';
+import { timingSafeEqual } from 'node:crypto';
+import { createManagedOursMcpServer } from '@ours.network/mcp/server';
+import { JSONRPCMessageSchema } from '@modelcontextprotocol/sdk/types.js';
+import { FileCallbacks } from './file-rpc.js';
+import { Wire } from './wire.js';
+export async function startMcpEndpoint(options) {
+    const sockets = new Set();
+    const server = createServer((socket) => {
+        if (sockets.size >= 4) {
+            socket.destroy();
+            return;
+        }
+        const wire = new Wire(socket);
+        sockets.add(wire);
+        const files = new FileCallbacks(wire);
+        let authenticated = false;
+        let inFlight = 0;
+        const ids = new Set();
+        const deadline = setTimeout(() => wire.close(), 5000);
+        deadline.unref();
+        const transport = {
+            start: async () => { },
+            send: async (message) => {
+                if ('id' in message &&
+                    message.id !== undefined &&
+                    ('result' in message || 'error' in message))
+                    ids.delete(message.id);
+                await wire.send({ kind: 'mcp', value: message });
+            },
+            close: async () => wire.close(),
+        };
+        const mcp = createManagedOursMcpServer(options.client, 'managed-v1', options.identities, {
+            remoteDaemonFiles: options.remoteDaemonFiles,
+            fileContext: files,
+            admit: async () => {
+                if (!authenticated || inFlight >= 32)
+                    throw Error('MCP_ADMISSION_LIMIT');
+                inFlight++;
+                try {
+                    const release = await options.runtime.admit();
+                    return () => {
+                        inFlight--;
+                        release();
+                    };
+                }
+                catch (error) {
+                    inFlight--;
+                    throw error;
+                }
+            },
+        });
+        wire.onClose = () => {
+            clearTimeout(deadline);
+            sockets.delete(wire);
+            files.close();
+            transport.onclose?.();
+        };
+        wire.onFrame = (frame) => {
+            if (!authenticated) {
+                const actual = typeof frame?.capability === 'string' ? Buffer.from(frame.capability) : Buffer.alloc(0);
+                const expected = Buffer.from(options.capability);
+                if (frame?.kind !== 'hello' ||
+                    frame.generation !== options.generation ||
+                    actual.length !== expected.length ||
+                    !timingSafeEqual(actual, expected))
+                    throw Error('UNAUTHORIZED_BRIDGE');
+                authenticated = true;
+                clearTimeout(deadline);
+                void mcp
+                    .connect(transport)
+                    .then(() => wire.send({ kind: 'ready' }))
+                    .catch(() => wire.close());
+                return;
+            }
+            if (frame?.kind === 'fs-result') {
+                files.receive(frame);
+                return;
+            }
+            if (frame?.kind !== 'mcp')
+                throw Error('UNKNOWN_BRIDGE_OPERATION');
+            const message = JSONRPCMessageSchema.parse(frame.value);
+            if ('method' in message && 'id' in message) {
+                if (ids.has(message.id) || ids.size >= 64)
+                    throw Error('MCP_REQUEST_LIMIT');
+                ids.add(message.id);
+            }
+            transport.onmessage?.(message);
+        };
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(options.socket, () => {
+            server.removeListener('error', reject);
+            resolve();
+        });
+    });
+    await chmod(options.socket, 0o600);
+    return {
+        close: async () => {
+            for (const socket of sockets)
+                socket.close();
+            await new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
+            await unlink(options.socket).catch((error) => {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            });
+        },
+    };
+}

package/dist/agent-ours/runtime.d.ts

@@ -0,0 +1,53 @@
+import type { OursClient } from '@ours.network/sdk/client';
+import { RuntimeJournal, type RuntimeState } from './state.js';
+export interface AssignedIdentity {
+    instance: string;
+    generation: number;
+    daemon: string;
+    name: string;
+    lifetime: 'permanent' | 'temporary';
+    action: string;
+    expectedCid?: string;
+    allowCreate: boolean;
+    bio: string;
+}
+export interface RoomAdmission {
+    id: string;
+    cid: string;
+    seat: string;
+    action: string;
+    /** The secret stays in trusted storage and is never returned to the child. */
+    redeem(client: OursClient): Promise<{
+        cid: string;
+    }>;
+    observe(agentCid: string): Promise<'pending' | 'established' | 'mismatch'>;
+    discardSecret(): Promise<void>;
+}
+export interface RuntimeDependencies {
+    journal: RuntimeJournal;
+    /** Client is already attached to the pinned daemon with its durable external owner. */
+    client: OursClient;
+    /** Checked before every operation; tied to the cross-process controller lock. */
+    assertFence(): void;
+    sleep(ms: number): Promise<void>;
+    now(): number;
+}
+/** A bridge never owns this object or its client; EOF never releases its lease. */
+export declare class AgentOursRuntime {
+    readonly assignment: AssignedIdentity;
+    private readonly deps;
+    private inFlight;
+    private drain?;
+    private accepting;
+    private state;
+    constructor(assignment: AssignedIdentity, deps: RuntimeDependencies);
+    get snapshot(): Readonly<RuntimeState>;
+    private transition;
+    private verify;
+    prepare(room?: RoomAdmission, timeoutMs?: number): Promise<void>;
+    /** Admission covers SDK calls, response rendering and agent filesystem callbacks. */
+    admit(): Promise<() => void>;
+    startHarness<T>(start: () => Promise<T>): Promise<T>;
+    suspend(): Promise<void>;
+    terminal(): Promise<void>;
+}

package/dist/agent-ours/runtime.js

@@ -0,0 +1,247 @@
+/** A bridge never owns this object or its client; EOF never releases its lease. */
+export class AgentOursRuntime {
+    assignment;
+    deps;
+    inFlight = 0;
+    drain;
+    accepting = false;
+    state;
+    constructor(assignment, deps) {
+        this.assignment = assignment;
+        this.deps = deps;
+        const existing = deps.journal.read();
+        if (existing) {
+            if (existing.instance !== assignment.instance ||
+                existing.daemon !== assignment.daemon ||
+                existing.name !== assignment.name ||
+                existing.lifetime !== assignment.lifetime ||
+                existing.generation !== assignment.generation ||
+                existing.action !== assignment.action ||
+                (assignment.expectedCid !== undefined &&
+                    existing.cid !== undefined &&
+                    existing.cid !== assignment.expectedCid))
+                throw Error('RUNTIME_ASSIGNMENT_MISMATCH');
+            this.state = existing;
+        }
+        else {
+            // Deliberately serialize only the public ownership facts, never credentials.
+            const { instance, generation, daemon, name, lifetime, action } = assignment;
+            this.state = {
+                version: 1,
+                instance,
+                generation,
+                daemon,
+                name,
+                lifetime,
+                action,
+                phase: 'PREPARING',
+                revision: 0,
+                updatedAt: '',
+            };
+            deps.assertFence();
+            deps.journal.commit(this.state);
+            this.state = deps.journal.read();
+        }
+    }
+    get snapshot() {
+        return structuredClone(this.state);
+    }
+    transition(phase, patch = {}) {
+        this.deps.assertFence();
+        this.deps.journal.commit({ ...this.state, ...patch, phase }, this.state.revision);
+        this.state = this.deps.journal.read();
+    }
+    async verify() {
+        this.deps.assertFence();
+        if (this.assignment.expectedCid && this.state.cid !== this.assignment.expectedCid)
+            throw Error('PINNED_CID_MISMATCH');
+        const actual = await this.deps.client.currentIdentity();
+        if (actual.cid !== this.state.cid ||
+            actual.name !== this.state.name ||
+            actual.temporary !== (this.state.lifetime === 'temporary') ||
+            actual.isRoot)
+            throw Error('IDENTITY_PROOF_MISMATCH');
+        this.deps.assertFence();
+    }
+    async prepare(room, timeoutMs = 30_000) {
+        if (['TERMINAL_INTENT', 'CLEANUP_PENDING', 'RELEASED', 'FAILED', 'QUIESCING'].includes(this.state.phase))
+            throw Error('RUNTIME_NOT_RESUMABLE');
+        this.deps.assertFence();
+        if (!this.state.cid) {
+            // An existing PREPARING journal is an uncertain create, never evidence of absence.
+            if (this.state.phase === 'RECOVERING')
+                throw Error('UNCERTAIN_PROVISIONING');
+            const rows = await this.deps.client.listIdentities();
+            const row = rows.find((r) => r.name === this.state.name);
+            if (row) {
+                if (!('cid' in row) ||
+                    this.state.lifetime === 'temporary' ||
+                    !this.assignment.expectedCid ||
+                    row.cid !== this.assignment.expectedCid ||
+                    row.kind === 'root' ||
+                    row.temp)
+                    throw Error('IDENTITY_COLLISION');
+                this.transition('RECOVERING');
+                await this.deps.client.chooseIdentity({ name: this.state.name, force: false });
+                this.transition('OWNED', { cid: row.cid });
+            }
+            else {
+                if (!this.assignment.allowCreate || this.assignment.expectedCid)
+                    throw Error('IDENTITY_ABSENT');
+                // Persist uncertainty before the non-idempotent call. Crash recovery requires owner proof.
+                this.transition('RECOVERING');
+                const args = {
+                    name: this.state.name,
+                    bio: this.assignment.bio,
+                    exposeLocal: false,
+                    localAutoAccept: true,
+                };
+                const created = this.state.lifetime === 'temporary'
+                    ? await this.deps.client.createTemporaryIdentity(args)
+                    : await this.deps.client.createIdentity(args);
+                if (created.hierarchy !== 'role')
+                    throw Error('ROOT_PROVISIONING_FORBIDDEN');
+                this.transition('OWNED', { cid: created.info.cid });
+            }
+        }
+        await this.verify();
+        if (!room && (this.state.room || this.state.admissionIntent))
+            throw Error('ROOM_DESCRIPTOR_REQUIRED');
+        if (room) {
+            if (this.state.room &&
+                (this.state.room.id !== room.id ||
+                    this.state.room.cid !== room.cid ||
+                    this.state.room.seat !== room.seat ||
+                    this.state.room.agentCid !== this.state.cid ||
+                    this.state.room.action !== room.action))
+                throw Error('ROOM_ASSIGNMENT_MISMATCH');
+            const intent = this.state.admissionIntent;
+            if (intent &&
+                (intent.id !== room.id ||
+                    intent.cid !== room.cid ||
+                    intent.seat !== room.seat ||
+                    intent.action !== room.action ||
+                    intent.agentCid !== this.state.cid))
+                throw Error('ROOM_INTENT_MISMATCH');
+            if (!this.state.room && !intent) {
+                // A permanent identity may already occupy its seat after a clean supervisor stop.
+                const existing = await room.observe(this.state.cid);
+                if (existing === 'mismatch') {
+                    this.transition('FAILED');
+                    throw Error('WRONG_ROOM_SEAT');
+                }
+                this.transition('ROOM_PENDING', {
+                    admissionIntent: {
+                        id: room.id,
+                        cid: room.cid,
+                        seat: room.seat,
+                        action: room.action,
+                        agentCid: this.state.cid,
+                    },
+                });
+                if (existing !== 'established') {
+                    const result = await room.redeem(this.deps.client);
+                    if (result.cid !== room.cid) {
+                        this.transition('FAILED');
+                        throw Error('WRONG_ROOM_CID');
+                    }
+                }
+            }
+            const deadline = this.deps.now() + timeoutMs;
+            for (;;) {
+                this.deps.assertFence();
+                const observation = await room.observe(this.state.cid);
+                if (observation === 'mismatch') {
+                    this.transition('FAILED');
+                    throw Error('WRONG_ROOM_SEAT');
+                }
+                if (observation === 'established')
+                    break;
+                if (this.deps.now() >= deadline)
+                    throw Error('ROOM_PENDING');
+                await this.deps.sleep(Math.min(250, deadline - this.deps.now()));
+            }
+            this.transition('READY', {
+                room: {
+                    id: room.id,
+                    cid: room.cid,
+                    seat: room.seat,
+                    agentCid: this.state.cid,
+                    action: room.action,
+                },
+            });
+            await room.discardSecret();
+        }
+        else
+            this.transition('READY');
+        this.accepting = true;
+    }
+    /** Admission covers SDK calls, response rendering and agent filesystem callbacks. */
+    async admit() {
+        this.deps.assertFence();
+        if (!this.accepting || !['READY', 'SERVING'].includes(this.state.phase))
+            throw Error('RUNTIME_NOT_READY');
+        this.inFlight++;
+        let released = false;
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            if (--this.inFlight === 0)
+                this.drain?.();
+        };
+        try {
+            await this.verify();
+            if (!this.accepting)
+                throw Error('RUNTIME_QUIESCING');
+            return release;
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
+    }
+    async startHarness(start) {
+        if (!this.accepting || this.state.phase !== 'READY')
+            throw Error('RUNTIME_NOT_READY');
+        await this.verify();
+        this.transition('SERVING');
+        return start();
+    }
+    async suspend() {
+        this.accepting = false;
+        if (this.inFlight)
+            await new Promise((resolve) => {
+                this.drain = resolve;
+            });
+        this.transition('RECOVERING');
+    }
+    async terminal() {
+        this.accepting = false;
+        if (this.state.phase === 'RELEASED')
+            return;
+        if (!['TERMINAL_INTENT', 'CLEANUP_PENDING'].includes(this.state.phase))
+            this.transition('QUIESCING');
+        if (this.inFlight)
+            await new Promise((resolve) => {
+                this.drain = resolve;
+            });
+        this.transition('TERMINAL_INTENT');
+        try {
+            this.deps.assertFence();
+            const ack = await this.deps.client.releaseLease();
+            if (!ack ||
+                !Array.isArray(ack.released) ||
+                !Array.isArray(ack.closed) ||
+                [...ack.released, ...ack.closed].some((name) => typeof name !== 'string') ||
+                [ack.attempted, ack.notified, ack.failed].some((n) => !Number.isSafeInteger(n) || n < 0) ||
+                ack.notified + ack.failed !== ack.attempted)
+                throw Error('INVALID_RELEASE_ACK');
+            this.transition('RELEASED', { releaseAck: ack });
+        }
+        catch (error) {
+            this.transition('CLEANUP_PENDING');
+            throw error;
+        }
+    }
+}

package/dist/agent-ours/service.d.ts

@@ -0,0 +1,23 @@
+import type { ResolvedRole } from '../config.js';
+import { AgentOursRuntime } from './runtime.js';
+export declare const privateRuntimeRoot: () => string;
+export interface ManagedAgentService {
+    runtime: AgentOursRuntime;
+    descriptor: string;
+    privatePaths: string[];
+    close(terminal: boolean): Promise<void>;
+}
+/** Only trusted launch orchestration may write this descriptor, never the child. */
+export declare function storeRoomSecret(role: ResolvedRole): void;
+export declare function storeTemporaryLaunch(role: ResolvedRole, action: string): void;
+export declare function prepareManagedAgent(role: ResolvedRole, stateDir: string, temporary: boolean): Promise<ManagedAgentService>;
+/** Explicit trusted inventory migration: read and pin existing permanent CID, never bind. */
+export declare function preparePermanentAssignment(role: ResolvedRole): Promise<'verified' | 'unverified'>;
+export declare function readRoomReadiness(roomCid: string, name: string): {
+    room: string;
+    invite: string;
+    cid: string;
+    generation: number;
+} | undefined;
+/** Explicit logical-instance termination, independent of harness/bridge transport. */
+export declare function releaseManagedAgent(role: ResolvedRole): Promise<void>;