@ours.network/fleet 0.11.1 → 0.13.0

package/dist/owner-channel/mcp.d.ts

@@ -0,0 +1,24 @@
+export declare class OursMcpError extends Error {
+}
+export interface OursToolClient {
+    start(): Promise<void>;
+    callTool(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    close(): Promise<void>;
+}
+/** Minimal MCP stdio client. One instance owns exactly one ours identity binding. */
+export declare class OursMcpClient implements OursToolClient {
+    private readonly command;
+    private readonly env;
+    private readonly log;
+    private child?;
+    private nextId;
+    private tail;
+    constructor(command?: string, env?: Record<string, string>, log?: (line: string) => void);
+    start(): Promise<void>;
+    callTool(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    close(): Promise<void>;
+    private request;
+    private requestNow;
+    private notify;
+    private write;
+}

package/dist/owner-channel/mcp.js

@@ -0,0 +1,123 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { createInterface } from 'node:readline';
+export class OursMcpError extends Error {
+}
+/** Minimal MCP stdio client. One instance owns exactly one ours identity binding. */
+export class OursMcpClient {
+    command;
+    env;
+    log;
+    child;
+    nextId = 0;
+    tail = Promise.resolve();
+    constructor(command = 'ours-mcp', env = {}, log = () => undefined) {
+        this.command = command;
+        this.env = env;
+        this.log = log;
+    }
+    async start() {
+        if (this.child && this.child.exitCode === null)
+            return;
+        const child = spawn(this.command, ['proxy'], {
+            env: {
+                ...process.env,
+                ...this.env,
+                // Bindings are keyed by this value. Sharing it would silently rebind a
+                // role's normal mailbox or another owner channel.
+                CLAUDE_CODE_SESSION_ID: `ours-fleet-owner-${process.pid}-${randomUUID()}`,
+            },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        await new Promise((resolve, reject) => {
+            child.once('spawn', resolve);
+            child.once('error', reject);
+        });
+        this.child = child;
+        child.stdin.on('error', error => this.log(`ours-mcp stdin: ${error.message}`));
+        createInterface({ input: child.stderr }).on('line', line => this.log(`ours-mcp: ${line}`));
+        try {
+            await this.request('initialize', {
+                protocolVersion: '2025-03-26', capabilities: {},
+                clientInfo: { name: 'ours-fleet-owner-channel', version: '1' },
+            });
+            await this.notify('notifications/initialized', {});
+        }
+        catch (error) {
+            await this.close();
+            throw error;
+        }
+    }
+    async callTool(name, args = {}) {
+        const result = await this.request('tools/call', { name, arguments: args });
+        const text = (result.content ?? [])
+            .filter(item => item.type === 'text').map(item => item.text ?? '').join('\n').trim();
+        if (result.isError)
+            throw new OursMcpError(text || `ours tool ${name} failed`);
+        if (result.structuredContent !== undefined)
+            return result.structuredContent;
+        if (!text)
+            return {};
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    async close() {
+        const child = this.child;
+        this.child = undefined;
+        if (!child || child.exitCode !== null)
+            return;
+        child.kill('SIGTERM');
+        await new Promise(resolve => {
+            const timer = setTimeout(() => { child.kill('SIGKILL'); resolve(); }, 5_000);
+            child.once('exit', () => { clearTimeout(timer); resolve(); });
+        });
+    }
+    request(method, params) {
+        const run = this.tail.then(() => this.requestNow(method, params));
+        this.tail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async requestNow(method, params) {
+        const child = this.child;
+        if (!child || child.exitCode !== null)
+            throw new OursMcpError('ours-mcp proxy is not running');
+        const id = ++this.nextId;
+        await this.write(child, { jsonrpc: '2.0', id, method, params });
+        const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+        try {
+            for await (const line of lines) {
+                let response;
+                try {
+                    response = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (response.id !== id)
+                    continue;
+                if (response.error !== undefined)
+                    throw new OursMcpError(JSON.stringify(response.error));
+                return response.result ?? {};
+            }
+            throw new OursMcpError('ours-mcp proxy closed its output');
+        }
+        finally {
+            lines.close();
+        }
+    }
+    async notify(method, params) {
+        const child = this.child;
+        if (!child || child.exitCode !== null)
+            throw new OursMcpError('ours-mcp proxy is not running');
+        await this.write(child, { jsonrpc: '2.0', method, params });
+    }
+    write(child, value) {
+        return new Promise((resolve, reject) => {
+            child.stdin.write(JSON.stringify(value) + '\n', error => error ? reject(error) : resolve());
+        });
+    }
+}

package/dist/owner-channel/notices.d.ts

@@ -0,0 +1,21 @@
+import type { SessionSnapshot, TurnOutcome } from '../session/types.js';
+import type { OwnerTaskPhase } from './tasks.js';
+export type OwnerUpdatePhase = 'working' | 'approval' | 'blocked';
+export type OwnerProgressPhase = 'starting request' | 'waiting behind earlier requests' | 'working on request' | 'planning next step' | 'using tools' | 'reviewing tool results' | 'drafting response' | 'waiting for approval' | 'resuming after permission decision' | 'recovering from session error';
+export declare const ownerNotices: {
+    receivedStarted: () => string;
+    receivedQueued: (queuedBehind: number) => string;
+    receivedInterrupting: () => string;
+    status: (role: string, snapshot: SessionSnapshot) => string;
+    interrupted: (role: string) => string;
+    interruptFailed: (role: string) => string;
+    attachmentRejected: (reason: string) => string;
+    attachmentFailed: () => string;
+    deliveryFailed: (role: string) => string;
+    progress: (elapsedMs: number, phase: OwnerProgressPhase, started: number, completed: number, activityUpdates?: number) => string;
+    authoredUpdate: (phase: OwnerUpdatePhase, message: string) => string;
+    taskReport: (phase: OwnerTaskPhase, message: string) => string;
+    completedWithoutText: () => string;
+    terminal: (outcome: TurnOutcome) => "✅ Request completed." | "🛑 Request was cancelled before completion." | "⚠️ The agent declined this request." | "⚠️ Request failed before completion." | "⚠️ Request ended without a confirmed completion.";
+    chunk: (part: number, total: number) => string;
+};

package/dist/owner-channel/notices.js

@@ -0,0 +1,66 @@
+const duration = (elapsedMs) => {
+    const seconds = Math.max(0, Math.floor(elapsedMs / 1_000));
+    const hours = Math.floor(seconds / 3_600);
+    const minutes = Math.floor((seconds % 3_600) / 60);
+    const remainder = seconds % 60;
+    return [hours ? `${hours}h` : '', minutes ? `${minutes}m` : '', remainder ? `${remainder}s` : '']
+        .filter(Boolean).join(' ') || '0s';
+};
+const count = (value, singular, plural = `${singular}s`) => `${value} ${value === 1 ? singular : plural}`;
+const joinCounts = (parts) => parts.length < 2
+    ? parts[0] ?? ''
+    : `${parts.slice(0, -1).join(', ')} and ${parts.at(-1)}`;
+export const ownerNotices = {
+    receivedStarted: () => 'ℹ️ Message received. The agent has started working on this request now. '
+        + 'The response will arrive in this channel when ready.',
+    receivedQueued: (queuedBehind) => `ℹ️ Message received. The agent is finishing ${queuedBehind} earlier request(s) first; `
+        + 'this request will start as soon as they complete. '
+        + 'The response will arrive in this channel when ready.',
+    receivedInterrupting: () => "ℹ️ Message received. The agent's previous task was interrupted to prioritize "
+        + 'this request, and it is now working on a response. '
+        + 'The response will arrive in this channel when ready.',
+    status: (role, snapshot) => `📊 ${role} status: ${snapshot.readiness}; session is ${snapshot.alive ? 'online' : 'offline'}.`,
+    interrupted: (role) => `🛑 Interrupt sent to ${role}'s active turn.`,
+    interruptFailed: (role) => `⚠️ Could not interrupt ${role}'s active turn.`,
+    attachmentRejected: (reason) => `⚠️ Attachment rejected: ${reason}.`,
+    attachmentFailed: () => '⚠️ Could not securely retrieve or admit this attachment request.',
+    deliveryFailed: (role) => `⚠️ Could not deliver this request to ${role}.`,
+    progress: (elapsedMs, phase, started, completed, activityUpdates = 0) => {
+        const counts = [];
+        if (started)
+            counts.push(`${count(started, 'tool action')} started`);
+        if (completed)
+            counts.push(`${count(completed, 'tool action')} completed`);
+        if (activityUpdates)
+            counts.push(`${count(activityUpdates, counts.length ? 'additional activity update' : 'activity update')} observed`);
+        const activity = counts.length
+            ? `${joinCounts(counts)} since the last update.`
+            : 'no new reportable activity since the last update.';
+        return `⏳ Working for ${duration(elapsedMs)} · ${phase} · ${activity}`;
+    },
+    authoredUpdate: (phase, message) => {
+        switch (phase) {
+            case 'working': return `🔄 Update: ${message}`;
+            case 'approval': return `🔐 Approval needed: ${message}`;
+            case 'blocked': return `🚧 Blocked: ${message}`;
+        }
+    },
+    taskReport: (phase, message) => {
+        switch (phase) {
+            case 'progress': return `🔄 Follow-up: ${message}`;
+            case 'done': return `✅ Follow-up complete: ${message}`;
+            case 'blocked': return `🚧 Follow-up blocked: ${message}`;
+        }
+    },
+    completedWithoutText: () => '✅ Request completed, but the agent returned no text.',
+    terminal: (outcome) => {
+        switch (outcome) {
+            case 'completed': return '✅ Request completed.';
+            case 'cancelled': return '🛑 Request was cancelled before completion.';
+            case 'refused': return '⚠️ The agent declined this request.';
+            case 'failed': return '⚠️ Request failed before completion.';
+            case 'inconclusive': return '⚠️ Request ended without a confirmed completion.';
+        }
+    },
+    chunk: (part, total) => `ℹ️ Response part ${part} of ${total}:\n`,
+};

package/dist/owner-channel/state.d.ts

@@ -0,0 +1,44 @@
+/** Durable bounded dedupe containing wire IDs only — never message or reply plaintext. */
+export declare class OwnerChannelState {
+    private readonly path;
+    private readonly limit;
+    private handled;
+    private readonly seen;
+    constructor(path: string, limit?: number);
+    has(wireId: string): boolean;
+    remember(wireId: string): void;
+}
+export type OwnerSource = 'baseline' | 'dynamic';
+export interface OwnerEntry {
+    cid: string;
+    source: OwnerSource;
+    effective: boolean;
+}
+/**
+ * Configured owners remain the declared baseline. This durable overlay adds
+ * owners or revokes either source without rewriting fleet.yaml. A corrupt
+ * overlay authorizes nobody and refuses mutation until the operator repairs or
+ * removes the bad file; silently falling back could resurrect a revoked owner.
+ */
+export declare class OwnerAuthorizationState {
+    private readonly path;
+    private readonly baseline;
+    private added;
+    private revoked;
+    private audit;
+    private corruptReason?;
+    constructor(path: string, baseline: string[]);
+    integrity(): {
+        ok: boolean;
+        error?: string;
+    };
+    effective(): Set<string>;
+    entries(): OwnerEntry[];
+    authorize(cid: string): OwnerEntry;
+    revoke(cid: string): OwnerEntry;
+    private assertHealthy;
+    private record;
+    private snapshot;
+    private restore;
+    private persist;
+}

package/dist/owner-channel/state.js

@@ -0,0 +1,184 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { replaceFileAtomically } from '../atomic-file.js';
+/** Durable bounded dedupe containing wire IDs only — never message or reply plaintext. */
+export class OwnerChannelState {
+    path;
+    limit;
+    handled = [];
+    seen = new Set();
+    constructor(path, limit = 5_000) {
+        this.path = path;
+        this.limit = limit;
+        try {
+            if (!existsSync(path))
+                return;
+            const state = JSON.parse(readFileSync(path, 'utf8'));
+            if (state.version !== 1 || !Array.isArray(state.handled))
+                return;
+            this.handled = state.handled.filter(id => typeof id === 'string').slice(-limit);
+            for (const id of this.handled)
+                this.seen.add(id);
+        }
+        catch { /* a corrupt cache safely degrades to at-least-once delivery */ }
+    }
+    has(wireId) { return this.seen.has(wireId); }
+    remember(wireId) {
+        if (this.seen.has(wireId))
+            return;
+        this.handled.push(wireId);
+        this.seen.add(wireId);
+        while (this.handled.length > this.limit)
+            this.seen.delete(this.handled.shift());
+        mkdirSync(dirname(this.path), { recursive: true });
+        const tmp = `${this.path}.tmp-${process.pid}`;
+        writeFileSync(tmp, JSON.stringify({ version: 1, handled: this.handled }) + '\n', { mode: 0o600 });
+        renameSync(tmp, this.path);
+    }
+}
+const MAX_OVERLAY_CIDS = 1_000;
+const MAX_AUDIT_ENTRIES = 500;
+/**
+ * Configured owners remain the declared baseline. This durable overlay adds
+ * owners or revokes either source without rewriting fleet.yaml. A corrupt
+ * overlay authorizes nobody and refuses mutation until the operator repairs or
+ * removes the bad file; silently falling back could resurrect a revoked owner.
+ */
+export class OwnerAuthorizationState {
+    path;
+    baseline;
+    added = new Set();
+    revoked = new Set();
+    audit = [];
+    corruptReason;
+    constructor(path, baseline) {
+        this.path = path;
+        this.baseline = new Set(baseline);
+        if (!existsSync(path))
+            return;
+        try {
+            const raw = JSON.parse(readFileSync(path, 'utf8'));
+            if (raw.version !== 1 || !Array.isArray(raw.added) || !Array.isArray(raw.revoked)
+                || !Array.isArray(raw.audit))
+                throw new Error('unsupported or incomplete state');
+            const validCid = (cid) => typeof cid === 'string' && /^[A-Fa-f0-9]{64}$/.test(cid);
+            if (!raw.added.every(validCid) || !raw.revoked.every(validCid)
+                || raw.added.length + raw.revoked.length > MAX_OVERLAY_CIDS
+                || raw.audit.length > MAX_AUDIT_ENTRIES
+                || raw.audit.some(entry => !entry || typeof entry !== 'object'
+                    || !validCid(entry.cid)
+                    || !['authorize', 'revoke'].includes(entry.action)
+                    || typeof entry.at !== 'string'))
+                throw new Error('invalid or unbounded state');
+            this.added = new Set(raw.added);
+            this.revoked = new Set(raw.revoked);
+            this.audit = raw.audit;
+            if (this.added.size !== raw.added.length || this.revoked.size !== raw.revoked.length)
+                throw new Error('duplicate overlay CID');
+            if ([...this.added].some(cid => this.revoked.has(cid)))
+                throw new Error('CID appears in both added and revoked overlays');
+            chmodSync(path, 0o600);
+        }
+        catch {
+            this.corruptReason = 'invalid persisted authorization overlay';
+            this.added.clear();
+            this.revoked.clear();
+            this.audit = [];
+            try {
+                chmodSync(path, 0o600);
+            }
+            catch { /* still fail closed */ }
+        }
+    }
+    integrity() {
+        return this.corruptReason ? { ok: false, error: this.corruptReason } : { ok: true };
+    }
+    effective() {
+        if (this.corruptReason)
+            return new Set();
+        const effective = new Set([...this.baseline, ...this.added]);
+        for (const cid of this.revoked)
+            effective.delete(cid);
+        return effective;
+    }
+    entries() {
+        const effective = this.effective();
+        return [...new Set([...this.baseline, ...this.added, ...this.revoked])]
+            .sort().map(cid => ({
+            cid,
+            source: this.baseline.has(cid) ? 'baseline' : 'dynamic',
+            effective: effective.has(cid),
+        }));
+    }
+    authorize(cid) {
+        this.assertHealthy();
+        if (this.effective().has(cid))
+            throw new Error(`owner '${cid}' is already authorized`);
+        const rollback = this.snapshot();
+        if (this.baseline.has(cid))
+            this.revoked.delete(cid);
+        else {
+            if (this.added.size + this.revoked.size >= MAX_OVERLAY_CIDS)
+                throw new Error(`owner authorization overlay is limited to ${MAX_OVERLAY_CIDS} CIDs`);
+            this.added.add(cid);
+            this.revoked.delete(cid);
+        }
+        this.record('authorize', cid);
+        try {
+            this.persist();
+        }
+        catch (error) {
+            this.restore(rollback);
+            throw error;
+        }
+        return { cid, source: this.baseline.has(cid) ? 'baseline' : 'dynamic', effective: true };
+    }
+    revoke(cid) {
+        this.assertHealthy();
+        const effective = this.effective();
+        if (!effective.has(cid))
+            throw new Error(`owner '${cid}' is not authorized`);
+        if (effective.size === 1)
+            throw new Error('refusing to revoke the last effective owner');
+        const rollback = this.snapshot();
+        if (this.baseline.has(cid))
+            this.revoked.add(cid);
+        else
+            this.added.delete(cid);
+        this.record('revoke', cid);
+        try {
+            this.persist();
+        }
+        catch (error) {
+            this.restore(rollback);
+            throw error;
+        }
+        return { cid, source: this.baseline.has(cid) ? 'baseline' : 'dynamic', effective: false };
+    }
+    assertHealthy() {
+        if (this.corruptReason)
+            throw new Error(`owner authorization state is corrupt; refusing mutation: ${this.corruptReason}`);
+    }
+    record(action, cid) {
+        this.audit.push({ at: new Date().toISOString(), action, cid });
+        this.audit = this.audit.slice(-MAX_AUDIT_ENTRIES);
+    }
+    snapshot() {
+        return { added: new Set(this.added), revoked: new Set(this.revoked), audit: [...this.audit] };
+    }
+    restore(snapshot) {
+        this.added = snapshot.added;
+        this.revoked = snapshot.revoked;
+        this.audit = snapshot.audit;
+    }
+    persist() {
+        const state = {
+            version: 1,
+            added: [...this.added].sort(),
+            revoked: [...this.revoked].sort(),
+            audit: this.audit,
+        };
+        replaceFileAtomically(this.path, JSON.stringify(state) + '\n', 0o600);
+        chmodSync(this.path, 0o600);
+    }
+}

package/dist/owner-channel/tasks.d.ts

@@ -0,0 +1,62 @@
+export type OwnerTaskPhase = 'progress' | 'done' | 'blocked';
+export type OwnerTaskTerminalState = 'closed' | 'expired' | 'revoked';
+export interface OwnerTaskRoute {
+    requestId: string;
+    contact: string;
+    wireId: string;
+}
+interface PendingReport {
+    digest: string;
+    phase: OwnerTaskPhase;
+    chars: number;
+    bytes: number;
+}
+export interface OwnerTaskRecord extends OwnerTaskRoute {
+    id: string;
+    createdAt: number;
+    expiresAt: number;
+    status: 'open' | 'sending' | 'uncertain';
+    sequence: number;
+    reportCount: number;
+    lastReportAt?: number;
+    digests: string[];
+    pending?: PendingReport;
+}
+export declare const OWNER_TASK_TTL_MS: number;
+export declare const OWNER_TASK_MAX_OPEN = 32;
+export declare const OWNER_TASK_MAX_PER_OWNER = 8;
+export declare const OWNER_TASK_MAX_REPORTS = 20;
+export declare const OWNER_TASK_REPORT_MIN_INTERVAL_MS = 5000;
+/**
+ * Durable proactive-task routing. It deliberately stores no report body: only
+ * the authenticated route, bounded hashes/counters, and delivery state.
+ */
+export declare class OwnerTaskState {
+    private readonly path;
+    private tasks;
+    private tombstones;
+    private corruptReason?;
+    constructor(path: string);
+    integrity(): {
+        ok: boolean;
+        error?: string;
+    };
+    open(route: OwnerTaskRoute, now?: number): OwnerTaskRecord;
+    route(taskId: string, now?: number): OwnerTaskRecord;
+    beginReport(taskId: string, phase: OwnerTaskPhase, digest: string, chars: number, bytes: number, now?: number): OwnerTaskRecord;
+    delivered(taskId: string, digest: string, terminal: boolean, now?: number): number;
+    uncertain(taskId: string, digest: string): void;
+    revoke(contact: string, now?: number): number;
+    cleanup(now?: number, effectiveOwners?: Set<string>): number;
+    private findOpen;
+    private remove;
+    private mutate;
+    private persist;
+    private assertHealthy;
+    private validTask;
+    private validPending;
+    private validTombstone;
+}
+export declare const ownerTaskDigest: (phase: OwnerTaskPhase, message: string) => string;
+export declare const ownerTaskAuditId: (value: string) => string;
+export {};