@ours.network/fleet 0.15.1 → 0.15.4

package/dist/session/conversation-store.js

@@ -0,0 +1,347 @@
+import { createHash } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync, writeSync, } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Durable, append-only, single-writer conversation ledger for one role
+ * (spec §5.3). The per-role runner is the only writer; readers page by seq.
+ *
+ * Unlike `SessionEvents` (a bounded diagnostic projection that may drop
+ * writes silently), this store is the transcript of record: an acknowledged
+ * browser prompt exists here before the browser hears "accepted", so
+ * `append` THROWS on failure. Agent-stream normalization uses `appendSafe`,
+ * which degrades visibly instead of killing role work already in progress.
+ */
+const MANIFEST = 'manifest.json';
+const DEFAULT_SEGMENT_BYTES = 4 * 1024 * 1024;
+/** In-memory tail kept for fast paging and follow backfill. */
+const TAIL_EVENTS = 1_000;
+export class IdempotencyConflictError extends Error {
+    constructor() {
+        super('idempotency key reused with a different body');
+        this.name = 'IdempotencyConflictError';
+    }
+}
+export class ConversationEventStore {
+    dir;
+    nextSeq = 1;
+    segments = [];
+    tail = [];
+    listeners = new Set();
+    commands = new Map();
+    promptStates = new Map();
+    activeFd;
+    activeBytes = 0;
+    _degraded = false;
+    degradedReason;
+    segmentBytes;
+    roleId;
+    log;
+    constructor(dir, options) {
+        this.dir = dir;
+        this.roleId = options.roleId;
+        this.segmentBytes = options.segmentBytes ?? DEFAULT_SEGMENT_BYTES;
+        this.log = options.log ?? (() => { });
+        try {
+            mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+            this.recover();
+        }
+        catch (error) {
+            this.markDegraded(`store unavailable: ${error.message}`);
+        }
+    }
+    /** First 24 hex chars of sha-256; the idempotency body-digest convention. */
+    static bodyDigest(body) {
+        return createHash('sha256').update(body).digest('hex').slice(0, 24);
+    }
+    get degraded() { return this._degraded; }
+    get degradedDetail() { return this.degradedReason; }
+    /**
+     * Durably append one event. Throws when the record cannot be persisted —
+     * the caller must fail its command rather than acknowledge a lost prompt.
+     */
+    append(draft) {
+        const event = {
+            schemaVersion: 1,
+            roleId: this.roleId,
+            eventId: `e${this.nextSeq}`,
+            seq: this.nextSeq,
+            at: new Date().toISOString(),
+            ...draft,
+        };
+        const line = JSON.stringify(event) + '\n';
+        const fd = this.segmentFd(Buffer.byteLength(line));
+        writeSync(fd, line);
+        fsyncSync(fd);
+        this.nextSeq++;
+        this.activeBytes += Buffer.byteLength(line);
+        this.tail.push(event);
+        if (this.tail.length > TAIL_EVENTS)
+            this.tail.shift();
+        this.trackPromptState(event);
+        for (const listener of this.listeners)
+            listener(event);
+        return event;
+    }
+    /**
+     * Append an agent-stream event; on failure record degradation and keep the
+     * role alive. Conversation durability may degrade, active work must not die.
+     */
+    appendSafe(draft) {
+        try {
+            return this.append(draft);
+        }
+        catch (error) {
+            this.markDegraded(`event append failed: ${error.message}`);
+            return undefined;
+        }
+    }
+    page(request = {}) {
+        const after = cursorSeq(request.after);
+        const limit = Math.min(Math.max(request.limit ?? 200, 1), 1_000);
+        const events = this.eventsAfter(after, limit + 1);
+        const hasMore = events.length > limit;
+        const pageEvents = hasMore ? events.slice(0, limit) : events;
+        const firstStored = this.firstStoredSeq();
+        return {
+            events: pageEvents,
+            ...(firstStored !== undefined ? { firstAvailableCursor: String(firstStored) } : {}),
+            ...(pageEvents.length ? { nextCursor: String(pageEvents.at(-1).seq) } : {}),
+            hasMore,
+        };
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Store the receipt a repeated command must get back. */
+    recordReceipt(commandId, receipt, bodyDigest) {
+        this.commands.set(commandId, { receipt, bodyDigest });
+    }
+    /**
+     * The receipt for a previously accepted command, or undefined for a new one.
+     * A reused ID with a different body digest is a conflict, never a replay.
+     */
+    receiptFor(commandId, bodyDigest) {
+        const record = this.commands.get(commandId);
+        if (!record)
+            return undefined;
+        if (record.bodyDigest !== bodyDigest)
+            throw new IdempotencyConflictError();
+        return record.receipt;
+    }
+    /**
+     * Prompts with no terminal event, classified for restart recovery:
+     * `admitted` never started and is safe to restore into the FIFO;
+     * `started` may already have had side effects and must not be replayed.
+     */
+    openPrompts() {
+        return [...this.promptStates.values()];
+    }
+    lastCursor() {
+        return this.nextSeq > 1 ? String(this.nextSeq - 1) : undefined;
+    }
+    close() {
+        if (this.activeFd !== undefined) {
+            try {
+                closeSync(this.activeFd);
+            }
+            catch { /* already closed */ }
+            this.activeFd = undefined;
+        }
+        this.listeners.clear();
+    }
+    // ── recovery ───────────────────────────────────────────────────────────────
+    recover() {
+        const manifest = this.readManifest();
+        this.segments = manifest?.segments.filter(name => existsSync(join(this.dir, name))) ?? this.discoverSegments();
+        if (!this.segments.length)
+            this.segments = this.discoverSegments();
+        let maxSeq = 0;
+        for (const segment of this.segments) {
+            for (const event of this.readSegment(segment)) {
+                maxSeq = Math.max(maxSeq, event.seq);
+                this.tail.push(event);
+                if (this.tail.length > TAIL_EVENTS)
+                    this.tail.shift();
+                this.trackPromptState(event);
+                this.rebuildCommandIndex(event);
+            }
+        }
+        this.nextSeq = maxSeq + 1;
+        if (this.segments.length) {
+            const active = join(this.dir, this.segments.at(-1));
+            this.activeBytes = existsSync(active) ? statSync(active).size : 0;
+        }
+        this.writeManifest();
+    }
+    readManifest() {
+        try {
+            const parsed = JSON.parse(readFileSync(join(this.dir, MANIFEST), 'utf8'));
+            if (parsed.schemaVersion === 1 && Array.isArray(parsed.segments))
+                return parsed;
+        }
+        catch { /* recover from segments instead */ }
+        return undefined;
+    }
+    discoverSegments() {
+        try {
+            return readdirSync(this.dir)
+                .filter(name => /^events-\d{6}\.jsonl$/.test(name))
+                .sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    readSegment(name) {
+        const events = [];
+        let raw;
+        try {
+            raw = readFileSync(join(this.dir, name), 'utf8');
+        }
+        catch (error) {
+            this.markDegraded(`segment ${name} unreadable: ${error.message}`);
+            return events;
+        }
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const event = JSON.parse(line);
+                if (event.schemaVersion === 1 && typeof event.seq === 'number')
+                    events.push(event);
+                else
+                    this.markDegraded(`segment ${name} holds a record of an unknown schema`);
+            }
+            catch {
+                // A torn final line after a crash: everything before it stays readable.
+                this.markDegraded(`segment ${name} ends in a torn or corrupt line`);
+            }
+        }
+        return events;
+    }
+    rebuildCommandIndex(event) {
+        if (event.kind !== 'prompt.admitted' || !event.commandId || !event.promptId)
+            return;
+        const payload = event.payload;
+        const bodyDigest = payload.text?.text !== undefined
+            ? ConversationEventStore.bodyDigest(payload.text.text)
+            : payload.external?.digest ?? '';
+        this.commands.set(event.commandId, {
+            bodyDigest,
+            receipt: {
+                commandId: event.commandId,
+                promptId: event.promptId,
+                state: 'queued',
+                queuedBehind: payload.queuedBehind ?? 0,
+                acceptedAt: event.at,
+                eventCursor: String(event.seq),
+            },
+        });
+    }
+    trackPromptState(event) {
+        if (!event.promptId)
+            return;
+        switch (event.kind) {
+            case 'prompt.admitted': {
+                const payload = event.payload;
+                this.promptStates.set(event.promptId, {
+                    promptId: event.promptId,
+                    state: 'admitted',
+                    sessionGeneration: event.sessionGeneration,
+                    ...(payload.text?.text !== undefined ? { text: payload.text.text } : {}),
+                    ...(event.commandId ? { commandId: event.commandId } : {}),
+                });
+                return;
+            }
+            case 'prompt.started': {
+                const open = this.promptStates.get(event.promptId);
+                if (open)
+                    open.state = 'started';
+                return;
+            }
+            case 'turn.completed':
+                this.promptStates.delete(event.promptId);
+                return;
+            default:
+        }
+    }
+    // ── segment management ─────────────────────────────────────────────────────
+    segmentFd(incomingBytes) {
+        if (this.activeFd !== undefined
+            && this.activeBytes + incomingBytes > this.segmentBytes) {
+            try {
+                closeSync(this.activeFd);
+            }
+            catch { /* rotating anyway */ }
+            this.activeFd = undefined;
+        }
+        if (this.activeFd === undefined) {
+            const needsNew = !this.segments.length
+                || this.activeBytes + incomingBytes > this.segmentBytes;
+            if (needsNew) {
+                const name = `events-${String(this.segments.length + 1).padStart(6, '0')}.jsonl`;
+                this.segments.push(name);
+                this.activeBytes = 0;
+                this.writeManifest();
+            }
+            const path = join(this.dir, this.segments.at(-1));
+            this.activeFd = openSync(path, 'a', 0o600);
+            if (!this.activeBytes)
+                this.activeBytes = statSync(path).size;
+        }
+        return this.activeFd;
+    }
+    writeManifest() {
+        const manifest = {
+            schemaVersion: 1, nextSeq: this.nextSeq, segments: this.segments,
+        };
+        const tmp = join(this.dir, MANIFEST + '.tmp');
+        try {
+            writeFileSync(tmp, JSON.stringify(manifest) + '\n', { mode: 0o600 });
+            renameSync(tmp, join(this.dir, MANIFEST));
+        }
+        catch (error) {
+            // The manifest is a recovery accelerator, not the source of truth;
+            // segments alone can always rebuild it.
+            this.log(`conversation manifest write failed: ${error.message}`);
+        }
+    }
+    // ── reads ──────────────────────────────────────────────────────────────────
+    firstStoredSeq() {
+        if (this.tail.length && this.tail[0].seq === 1)
+            return 1;
+        for (const segment of this.segments) {
+            const events = this.readSegment(segment);
+            if (events.length)
+                return events[0].seq;
+        }
+        return this.tail[0]?.seq;
+    }
+    eventsAfter(after, limit) {
+        // Serve from the in-memory tail whenever the range allows it.
+        if (this.tail.length && after >= this.tail[0].seq - 1)
+            return this.tail.filter(event => event.seq > after).slice(0, limit);
+        const events = [];
+        for (const segment of this.segments) {
+            for (const event of this.readSegment(segment)) {
+                if (event.seq <= after)
+                    continue;
+                events.push(event);
+                if (events.length >= limit)
+                    return events;
+            }
+        }
+        return events;
+    }
+    markDegraded(reason) {
+        if (!this._degraded)
+            this.log(`conversation store degraded: ${reason}`);
+        this._degraded = true;
+        this.degradedReason = reason;
+    }
+}
+function cursorSeq(cursor) {
+    const value = Number(cursor);
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}

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

@@ -0,0 +1,274 @@
+import type { PromptOrigin, TurnCancellationSource, TurnOutcome } from './types.js';
+/**
+ * Durable conversation domain schema (ACP web console, spec §5.2).
+ *
+ * `SessionEvent` in ./types.js remains the compact diagnostic projection; the
+ * types here describe the durable per-role conversation ledger. Nothing in this
+ * file touches the wire: ACP updates are reduced into these shapes by the
+ * normalizer, and the store (phase 1) assigns `seq`/`eventId`/timestamps.
+ */
+export type ConversationEventKind = 'prompt.admitted' | 'prompt.started' | 'prompt.interrupt_requested' | 'message.chunk' | 'message.replace' | 'thought.chunk' | 'thought.replace' | 'plan.replace' | 'tool.upsert' | 'tool.content_chunk' | 'permission.requested' | 'permission.resolved' | 'usage.updated' | 'turn.state' | 'turn.completed' | 'session.state' | 'session.info' | 'capabilities.updated' | 'error'
+/** A well-formed ACP update this version cannot represent. Bounded, never a crash. */
+ | 'unsupported';
+/** Where a conversation record came from. Typed provenance, never prompt text. */
+export type ConversationSource = 'owner_admin_console' | 'owner_channel' | 'fleet_monitor' | 'scheduled_loop' | 'startup' | 'local_console' | 'agent' | 'agent_replay';
+export interface NormalizedText {
+    type: 'text';
+    text: string;
+    /** Byte length of the ORIGINAL text, before any cap or redaction. */
+    bytes: number;
+    truncated?: true;
+    /** Present when truncated or redacted: sha-256 (hex, first 24) of the original. */
+    digest?: string;
+    redacted?: true;
+}
+/** Media payloads are described, not carried; rendering is a later phase. */
+export interface NormalizedMedia {
+    type: 'image' | 'audio';
+    mimeType: string;
+    bytes: number;
+    uri?: string;
+}
+export interface NormalizedResourceLink {
+    type: 'resource_link';
+    uri: string;
+    name?: string;
+    mimeType?: string;
+}
+export interface NormalizedResource {
+    type: 'resource';
+    uri?: string;
+    mimeType?: string;
+    bytes: number;
+}
+export type NormalizedContentBlock = NormalizedText | NormalizedMedia | NormalizedResourceLink | NormalizedResource;
+/** A capped text fragment inside a larger payload (diff sides, previews). */
+export interface CappedText {
+    text: string;
+    bytes: number;
+    truncated?: true;
+    digest?: string;
+}
+export type NormalizedToolContent = {
+    type: 'content';
+    content: NormalizedContentBlock;
+} | {
+    type: 'diff';
+    path: string;
+    newText: CappedText;
+    oldText?: CappedText;
+}
+/** A tool-owned display terminal reference — never a PTY attachment. */
+ | {
+    type: 'terminal';
+    terminalId: string;
+};
+/**
+ * Adapter-specific `_meta`, quarantined by namespace. The UI may ignore any
+ * entry; nothing outside adapter-specific renderers may interpret `value`.
+ */
+export interface AdapterMeta {
+    namespace: string;
+    value?: unknown;
+    /** Set when the value exceeded the metadata cap and was dropped. */
+    truncated?: true;
+    bytes?: number;
+}
+export interface MessageChunkPayload {
+    role: 'user' | 'assistant';
+    content: NormalizedContentBlock;
+}
+export interface ThoughtChunkPayload {
+    content: NormalizedContentBlock;
+}
+export interface PlanEntryPayload {
+    content: CappedText;
+    priority: 'high' | 'medium' | 'low';
+    status: 'pending' | 'in_progress' | 'completed';
+}
+export interface PlanReplacePayload {
+    /** Absent for the standard whole-session plan; set for ID'd (unstable) plans. */
+    planId?: string;
+    entries?: PlanEntryPayload[];
+    /** Unstable plan representations we can reference but not structure. */
+    file?: {
+        uri: string;
+    };
+    markdown?: CappedText;
+    removed?: true;
+}
+export interface ToolUpsertPayload {
+    toolCallId: string;
+    /** True for `tool_call` (full snapshot), false for `tool_call_update` (patch). */
+    snapshot: boolean;
+    title?: string;
+    kind?: string;
+    status?: string;
+    content?: NormalizedToolContent[];
+    locations?: Array<{
+        path: string;
+        line?: number;
+    }>;
+    rawInput?: BoundedJson;
+    rawOutput?: BoundedJson;
+}
+export interface UsageUpdatedPayload {
+    used: number;
+    size: number;
+    /** Agent-reported; absence is normal and cost semantics differ per adapter. */
+    cost?: {
+        amount: number;
+        currency: string;
+    };
+}
+export interface SessionStatePayload {
+    currentModeId?: string;
+}
+export interface SessionInfoPayload {
+    title?: string | null;
+    updatedAt?: string | null;
+}
+export interface CapabilitiesUpdatedPayload {
+    commands?: Array<{
+        name: string;
+        description: CappedText;
+        inputHint?: string;
+    }>;
+    configOptions?: BoundedJson;
+}
+export interface UnsupportedPayload {
+    /** The wire discriminant (or 'unknown' when even that was absent). */
+    sessionUpdate: string;
+    bytes: number;
+    /** Sanitized JSON preview, capped; enough to diagnose, never to exhaust. */
+    preview?: string;
+}
+export interface PromptAdmittedPayload {
+    text?: NormalizedText;
+    /** Human-only display body; never used to recover or dispatch an external prompt. */
+    displayText?: NormalizedText;
+    /** External E2E bodies stay out of fleet state: digest/size only. */
+    external?: {
+        digest: string;
+        bytes: number;
+    };
+    queuedBehind: number;
+}
+export interface PromptStartedPayload {
+    queuedBehind?: number;
+}
+export interface PromptInterruptRequestedPayload {
+    commandId?: string;
+    cancellationSource?: TurnCancellationSource;
+}
+export interface PermissionRequestedPayload {
+    toolCallId?: string;
+    title?: string;
+    options: Array<{
+        optionId: string;
+        name: string;
+        kind: string;
+    }>;
+    expiresAt?: string;
+}
+export interface PermissionResolvedPayload {
+    decision: 'allowed' | 'denied' | 'cancelled' | 'expired';
+    decisionSource: 'automatic' | 'manual';
+    optionId?: string;
+    policy?: string;
+    reason?: string;
+}
+export interface TurnStatePayload {
+    state: 'queued' | 'running' | 'awaiting_permission' | 'interrupt_requested';
+}
+export interface TurnCompletedPayload {
+    outcome: TurnOutcome | 'unknown_after_restart';
+    stopReason?: string;
+    cancellationSource?: TurnCancellationSource;
+}
+export interface SessionLifecyclePayload {
+    status: 'starting' | 'idle' | 'running' | 'awaiting_permission' | 'failed' | 'offline';
+    detail?: string;
+}
+export interface ErrorPayload {
+    message: string;
+}
+/** Structured-but-untrusted JSON, serialized and capped rather than trusted. */
+export interface BoundedJson {
+    json?: unknown;
+    bytes: number;
+    truncated?: true;
+    digest?: string;
+    redacted?: true;
+}
+export type ConversationPayload = MessageChunkPayload | ThoughtChunkPayload | PlanReplacePayload | ToolUpsertPayload | UsageUpdatedPayload | SessionStatePayload | SessionInfoPayload | CapabilitiesUpdatedPayload | UnsupportedPayload | PromptAdmittedPayload | PromptStartedPayload | PromptInterruptRequestedPayload | PermissionRequestedPayload | PermissionResolvedPayload | TurnStatePayload | TurnCompletedPayload | SessionLifecyclePayload | ErrorPayload;
+export interface ConversationEventV1 {
+    schemaVersion: 1;
+    roleId: string;
+    /** Opaque, durable, unique. Browser dedupe key across replay/reconnect. */
+    eventId: string;
+    /** Durable monotonic sequence for this role's store. */
+    seq: number;
+    at: string;
+    /** Changes on every runner restart; pending IDs from prior generations are stale. */
+    sessionGeneration: string;
+    acpSessionId?: string;
+    kind: ConversationEventKind;
+    /** Fleet admission ID. */
+    promptId?: string;
+    /** Fleet turn ID; v1 turns reuse the prompt ID. */
+    turnId?: string;
+    /** Agent-owned when supplied; optional in ACP v1. */
+    messageId?: string;
+    toolCallId?: string;
+    permissionId?: string;
+    /**
+     * The idempotency key of the command that produced this record. Persisted so
+     * the command-id index can be rebuilt from segments alone on recovery.
+     */
+    commandId?: string;
+    source?: ConversationSource;
+    actor?: {
+        browserSession?: string;
+        externalSenderDigest?: string;
+    };
+    payload: ConversationPayload;
+    adapterMeta?: AdapterMeta[];
+}
+export interface SubmitPromptCommand {
+    /** Idempotency-Key / clientRequestId. Reuse with a different body is a conflict. */
+    commandId: string;
+    text: string;
+    source: 'owner_admin_console';
+    actorBrowserSession: string;
+}
+export interface PromptReceipt {
+    commandId: string;
+    promptId: string;
+    state: 'queued' | 'starting';
+    queuedBehind: number;
+    acceptedAt: string;
+    /** Cursor of the durable `prompt.admitted` event. */
+    eventCursor: string;
+}
+export interface PermissionDecisionCommand {
+    commandId: string;
+    permissionId: string;
+    sessionGeneration: string;
+    optionId: string;
+}
+export interface ConversationSnapshot {
+    sessionGeneration: string;
+    readiness: 'starting' | 'idle' | 'running' | 'awaiting_permission' | 'failed' | 'offline';
+    queueDepth: number;
+    pendingPermissionIds: string[];
+    historyDegraded?: boolean;
+}
+export interface ConversationPage {
+    events: ConversationEventV1[];
+    firstAvailableCursor?: string;
+    nextCursor?: string;
+    hasMore: boolean;
+    snapshot: ConversationSnapshot;
+}
+export type { PromptOrigin };

package/dist/session/conversation-types.js

@@ -0,0 +1 @@
+export {};