@ours.network/fleet 1.2.0-nightly.63 → 1.2.0-nightly.64

package/dist/web/conversation-stream.js

@@ -0,0 +1,231 @@
+import { encodeConversationRecord, MAX_PENDING_BYTES } from './conversation-stream-codec.js';
+/** One active logical record; only waiting encoded output consumes the pending budget. */
+export class ConversationStreamWriter {
+    output;
+    failed;
+    queue = [];
+    active;
+    waiting = false;
+    ended = false;
+    sequence = 0;
+    pendingBytes = 0;
+    get busy() { return Boolean(this.active); }
+    constructor(output, failed) {
+        this.output = output;
+        this.failed = failed;
+        output.on('drain', this.drain);
+        output.once('error', this.error);
+    }
+    error = () => this.fail('transport-error');
+    drain = () => { this.waiting = false; this.flush(); };
+    send(type, payload) {
+        if (this.ended)
+            return false;
+        const id = String(++this.sequence);
+        try {
+            if (!this.active) {
+                this.active = encodeConversationRecord(type, payload, id);
+                this.flush();
+            }
+            else {
+                let bytes = 0;
+                for (const frame of encodeConversationRecord(type, payload, id))
+                    bytes += Buffer.byteLength(frame);
+                if (this.pendingBytes + bytes > MAX_PENDING_BYTES) {
+                    this.fail('output-overflow');
+                    return false;
+                }
+                this.queue.push({ type, payload, id, bytes });
+                this.pendingBytes += bytes;
+            }
+            return !this.ended;
+        }
+        catch {
+            this.fail('record-too-large');
+            return false;
+        }
+    }
+    flush() {
+        if (this.ended || this.waiting)
+            return;
+        try {
+            while (this.active) {
+                const next = this.active.next();
+                if (!next.done) {
+                    if (!this.output.write(next.value)) {
+                        this.waiting = true;
+                        return;
+                    }
+                }
+                else {
+                    const queued = this.queue.shift();
+                    this.active = queued ? encodeConversationRecord(queued.type, queued.payload, queued.id) : undefined;
+                    if (queued)
+                        this.pendingBytes -= queued.bytes;
+                }
+            }
+        }
+        catch {
+            this.fail('record-too-large');
+        }
+    }
+    fail(reason) {
+        if (this.ended)
+            return;
+        // A resync is only useful at a frame boundary with writable capacity.
+        if (!this.waiting && !this.output.destroyed) {
+            const frame = encodeConversationRecord('resync', { reason, capability: 'degraded', retry: reason !== 'record-too-large' }, 'terminal').next().value;
+            if (frame)
+                this.output.write(frame);
+        }
+        const blocked = this.waiting;
+        this.close();
+        this.failed(reason);
+        if (blocked)
+            this.output.destroy();
+    }
+    close() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.active = undefined;
+        this.queue = [];
+        this.pendingBytes = 0;
+        this.output.off('drain', this.drain);
+        this.output.off('error', this.error);
+    }
+}
+import { FleetError } from '../application/errors.js';
+export function registerConversationStream(app, services, auth) {
+    const connections = new Set();
+    app.addHook('preClose', async () => { for (const close of connections)
+        close(); });
+    app.get('/api/v1/roles/:id/conversation/events', async (request, reply) => {
+        const browser = auth.authenticate(request);
+        const generation = request.query.expectedGeneration, rawAfter = request.query.after ?? '0', after = Number(rawAfter);
+        if (typeof generation !== 'string' || !generation.trim() || generation.length > 512 || !/^\d+$/.test(rawAfter) || !Number.isSafeInteger(after))
+            throw new FleetError('invalid_request', 'expectedGeneration and a nonnegative integer after cursor are required');
+        if (!services.observeRole)
+            throw new FleetError('capability_unavailable', 'Complete conversation observation is unavailable');
+        let ended = false, owner, follow;
+        let binding, timer;
+        let epoch = 0, revision = -1, lifetime, available = false;
+        let abort = new AbortController();
+        const close = () => {
+            if (ended)
+                return;
+            ended = true;
+            epoch++;
+            abort.abort();
+            if (timer)
+                clearInterval(timer);
+            binding?.();
+            writer.close();
+            follow?.close();
+            follow = undefined;
+            owner?.dispose();
+            connections.delete(close);
+            reply.raw.end();
+        };
+        const writer = new ConversationStreamWriter(reply.raw, close);
+        const resync = (reason, retry = true) => writer.send('resync', { reason, retry, capability: 'degraded' });
+        const valid = () => { if (auth.sessionValid(browser))
+            return true; writer.send('resync', { reason: 'auth-expired', retry: browser.rotating ? 'authenticate' : 'reauthenticate', capability: 'auth-expired' }); close(); return false; };
+        const stopFollow = () => { epoch++; abort.abort(); abort = new AbortController(); follow?.close(); follow = undefined; };
+        const open = async () => {
+            const current = ++epoch, signal = abort.signal;
+            const active = () => !ended && current === epoch && !signal.aborted;
+            try {
+                const control = await services.session(request.params.id);
+                if (!active() || !valid())
+                    return;
+                const descriptor = await control.describe(owner);
+                if (!active() || !valid())
+                    return;
+                if (!control.followConversation || !descriptor.features.includes('conversation_live_complete')) {
+                    resync('capability-unavailable', false);
+                    return;
+                }
+                const handle = await control.followConversation({ controller: false, expectedGeneration: generation, after, signal, roleObservation: owner,
+                    onReplay: page => { if (active() && valid()) {
+                        for (const event of page.events)
+                            writer.send('ledger', event);
+                        writer.send('ledger', { coveredThrough: page.coveredThrough });
+                    } },
+                    onReady: ready => {
+                        if (active() && valid()) {
+                            writer.send('state', ready.snapshot);
+                            writer.send('ready', { sessionGeneration: ready.snapshot.sessionGeneration, stateRevision: ready.snapshot.stateRevision,
+                                ledgerBarrier: ready.snapshot.ledgerBarrier, coveredThrough: ready.coveredThrough, capability: 'complete', authorizedUntil: browser.absoluteExpiresAt });
+                        }
+                    },
+                    onEvent: event => { if (active() && valid()) {
+                        writer.send('ledger', event);
+                        writer.send('ledger', { coveredThrough: event.seq });
+                    } },
+                    onState: state => { if (active() && valid())
+                        writer.send('state', state); },
+                    onClose: reason => { if (active()) {
+                        epoch++;
+                        abort.abort();
+                        follow = undefined;
+                        resync(reason ?? 'control-closed', !reason?.includes('assembly limit'));
+                    } },
+                });
+                if (!active())
+                    handle.close();
+                else
+                    follow = handle;
+            }
+            catch {
+                if (active())
+                    resync('observation-unavailable');
+            }
+        };
+        const changed = (state) => {
+            if (ended || state.roleRevision <= revision)
+                return;
+            revision = state.roleRevision;
+            const { stateDir: _private, ...publicState } = state;
+            writer.send('role', publicState);
+            const replaced = lifetime !== undefined && lifetime !== state.roleLifetime;
+            const nextAvailable = state.availability === 'available' && state.health === 'healthy';
+            if (replaced || !nextAvailable)
+                stopFollow();
+            if (state.health !== 'healthy')
+                resync(state.failure ?? 'role-observation-unavailable', false);
+            else if (replaced)
+                resync('role-replaced');
+            const shouldOpen = nextAvailable && (!available || replaced);
+            lifetime = state.roleLifetime;
+            available = nextAvailable;
+            if (shouldOpen)
+                void open();
+        };
+        reply.hijack();
+        for (const [name, value] of Object.entries(reply.getHeaders()))
+            if (value !== undefined)
+                reply.raw.setHeader(name, Array.isArray(value) ? value : String(value));
+        reply.raw.writeHead(200, { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-store', 'X-Accel-Buffering': 'no' });
+        reply.raw.flushHeaders();
+        reply.raw.once('close', close);
+        connections.add(close);
+        binding = auth.bindTransport(browser, () => { writer.send('resync', { reason: 'auth-expired', capability: 'auth-expired', retry: browser.rotating ? 'authenticate' : 'reauthenticate' }); close(); });
+        try {
+            // Factory callbacks can be synchronous; defer handling until the owner can be borrowed.
+            owner = services.observeRole(request.params.id, state => queueMicrotask(() => changed(state)));
+            if (ended) {
+                owner.dispose();
+                return;
+            }
+            changed(owner.snapshot());
+            timer = setInterval(() => { if (valid())
+                writer.send('keepalive', { at: Date.now() }); }, 1_000);
+            timer.unref();
+        }
+        catch {
+            resync('role-observation-unavailable', false);
+            close();
+        }
+    });
+}

package/dist/web/runtime.js

@@ -1,3 +1,4 @@
+import { ConversationRoleObserver } from '../application/conversation-role-observer.js';
 import { replaceFileAtomically } from '../atomic-file.js';
 import { validateAccountOrigin } from '../account-origin.js';
 import { startWorkspaceTunnel } from './workspace-tunnel.js';
@@ -110,6 +111,13 @@ export async function startWebConsole(options) {
         },
     });
     const events = new FleetEventBus();
+    const roleMutations = new Set();
+    const signalRoleMutation = () => { for (const listener of roleMutations)
+        listener(); };
+    const observeRole = (roleId, listener) => new ConversationRoleObserver({
+        roleId, configPath: options.configPath,
+        subscribeMutations: changed => { roleMutations.add(changed); return () => { roleMutations.delete(changed); }; },
+    }, listener);
     const audit = new AuditSink();
     const watchdogConfigProvider = cachedConfigProvider(options.configPath);
     const log = options.log ?? (() => { });
@@ -149,6 +157,7 @@ export async function startWebConsole(options) {
                 ? 'ready' : detail?.status.overall === 'attention' ? 'attention' : 'unknown';
         },
         onProgress: action => {
+            signalRoleMutation();
             events.publish('creation.changed', action, action.roleId);
             void audit.record({
                 roleId: action.roleId, action: `creation.${action.state}`,
@@ -164,6 +173,7 @@ export async function startWebConsole(options) {
         repository, ops, configPath: options.configPath,
         status: async (roleId) => (await query.detail(roleId)).status,
         onProgress: receipt => {
+            signalRoleMutation();
             events.publish('action.changed', receipt, receipt.roleId);
             void audit.record({
                 roleId: receipt.roleId, action: `lifecycle.${receipt.action}`,
@@ -185,7 +195,7 @@ export async function startWebConsole(options) {
     let server;
     try {
         server = await buildWebServer({
-            query, repository, logs, commands, creation, removal, audit, events, watchdogs, configuration,
+            query, repository, logs, commands, creation, removal, audit, events, watchdogs, configuration, observeRole,
             taskRooms: new TaskRoomApplicationService(options.configPath, { binPath: () => options.binPath }),
             roomLayouts: new RoomLayoutDefinitions(options.configPath),
             layoutBindings: new LayoutBindingGrants(new RoomLayoutService(options.configPath).supervisor()),
@@ -218,7 +228,7 @@ export async function startWebConsole(options) {
                     const dir = repository.stateDir(role);
                     if (!dir)
                         throw new FleetError('control_unavailable', 'role state directory is unavailable');
-                    return new RoleSessionControlAdapter(dir);
+                    return new RoleSessionControlAdapter(dir, undefined, undefined, listener => observeRole(roleId, listener));
                 }
                 throw new FleetError('capability_unavailable', 'role session backend is unavailable');
             },

package/dist/web/server.d.ts

@@ -1,3 +1,4 @@
+import type { ConversationRoleObservation, ConversationRoleState } from '../application/conversation-role-observer.js';
 import { type InitAnswers } from '../init-wizard.js';
 import { SupervisorOursTools } from '../application/supervisor-ours-tools.js';
 import { type FastifyInstance } from 'fastify';
@@ -23,6 +24,7 @@ import type { OfferedModels } from '../subscriptions/cli.js';
 import type { SubscriptionService } from '../subscriptions/service.js';
 import type { LayoutBindingGrants } from '../rooms-tasks/layout-binding-grants.js';
 export interface WebServices {
+    observeRole?(roleId: string, listener: (state: ConversationRoleState) => void): ConversationRoleObservation;
     layoutBindings?: Pick<LayoutBindingGrants, 'control'>;
     query: FleetQueryService;
     repository: RoleRepository;

package/dist/web/server.js

@@ -1,3 +1,4 @@
+import { registerConversationStream } from './conversation-stream.js';
 import { conversationHasAttachment } from '../application/conversation-history.js';
 import { readDeliveredFile } from '../file-delivery/store.js';
 import { WorkspaceDeviceAuthError } from './workspace-devices.js';
@@ -88,6 +89,7 @@ export async function buildWebServer(services, boundary, options = {}) {
             reply.header('X-Ours-Request-Id', request.id);
         reply.code(statusFor(fleetError.code)).send({ error: fleetError.toJSON() });
     });
+    registerConversationStream(app, services, auth);
     app.post('/api/v1/auth/exchange', async (request, reply) => {
         const { session, device } = auth.exchange(request);
         setAuthCookies(reply, session.id, device.token, auth.secureCookies);

package/docs/conversation-stream.md

@@ -0,0 +1,176 @@
+# Conversation event stream (wire version 1)
+
+`GET /api/v1/roles/:id/conversation/events?expectedGeneration=GENERATION&after=CURSOR`
+uses the existing Fleet route boundary, including `/fleet/api/v1/...` through the
+prefix gateway. Use authenticated `fetch`, then read the response body. Cookies
+work for standalone and same-origin frame access; the hosted App sends its current
+workspace access bearer in `Authorization`. Query parameters are data, never
+credentials. `after` is a nonnegative safe integer; generation is required.
+No new WebSocket path, controller lease, notification acknowledgement, work
+submission, or read receipt is introduced.
+
+## Framing
+
+Content type is `text/event-stream; charset=utf-8`, with `Cache-Control: no-store`
+and `X-Accel-Buffering: no`. Every frame is exactly:
+
+```text
+event: conversation
+data: {"version":1,"type":"TYPE","payload":...}
+
+```
+
+The six logical types are:
+
+- `role`: complete public role replacement (`roleId`, `roleRevision`,
+  `roleLifetime`, `availability`, `health`, optional backend/fallback/failure).
+  Local state paths are omitted. This ordering is independent of session state.
+- `ledger`: either a single durable conversation event, or a coverage marker
+  `{coveredThrough:number}`. All events covered by a marker precede it. Replay
+  can legitimately advance coverage without visible events. Never advance a
+  recovery cursor from maximum rendered event sequence alone.
+- `ready`: `{sessionGeneration,stateRevision,ledgerBarrier,coveredThrough,
+  capability:"complete",authorizedUntil}`. The coherent initial snapshot arrives
+  as a preceding `state` record, keeping its full 16 MiB payload budget. Hold
+  initial state/replay as provisional until matching ready; validate generation,
+  stateRevision and ledgerBarrier against the staged state and coverage against
+  delivered replay. Only successful private replay certifies `coveredThrough`;
+  the snapshot barrier alone does not. Disconnect between state and ready must
+  not publish live initial state or advance the certified cursor. Reconnect with
+  same-generation certified coverage. State revision and event sequence differ.
+- `state`: complete conversation observation replacement, including
+  `sessionGeneration`, `stateRevision` and `ledgerBarrier`. Do not merge it as a
+  patch or use its barrier as coverage.
+- `resync`: `{reason,retry,capability}`. Clear partial assembly and resynchronize
+  explicitly or enter supported fallback. `retry:false` means persistent
+  unsupported/oversize observation: do not loop reconnects. `capability` is
+  `degraded`, except `auth-expired` below.
+- `keepalive`: `{at:number}`. Transport liveness only; it cannot certify role,
+  session, replay, or private-control health.
+
+A large logical payload uses `start`, ordered `chunk`, then `commit` frames,
+without the `payload` field:
+
+```json
+{"version":1,"type":"start","id":"3","recordType":"state","totalBytes":1048576,"generation":"g","revision":7}
+{"version":1,"type":"chunk","id":"3","index":0,"data":"a slice of the serialized payload JSON"}
+{"version":1,"type":"commit","id":"3","totalBytes":1048576,"generation":"g","revision":7}
+```
+
+Chunks contain JSON text, **not base64**. Concatenate `data`, UTF-8 count it,
+then JSON-parse only after commit. The optional generation/revision are derived
+from payload sessionGeneration/stateRevision or roleRevision;
+commit and reconstructed payload must match start. Reject duplicate/out-of-order
+chunks, empty chunks, mismatched identities/revisions/lengths, overlapping assemblies, invalid
+UTF-8, over-budget frames, and an incomplete end. Never publish partial snapshots.
+`ConversationStreamDecoder` implements these framing checks without Node APIs.
+It is not a domain reducer: consumers must additionally enforce current workspace,
+generation and monotonic state/role revisions before applying records.
+
+## Limits and ownership
+
+Encoded frames, including SSE and JSON overhead, are at most 512 KiB. Payload JSON
+is at most 16 MiB; one assembly is allowed at a time. The encoder splits at safe
+UTF-16 boundaries into at most 48 Ki code units, so JSON escaping still fits the
+encoded-frame bound. The active logical record is streamed progressively while
+waiting encoded records are capped at 8 MiB per web connection. A valid 16 MiB
+ledger event is sent independently of its coverage marker so the page envelope
+does not consume its logical-record budget. Oversize records explicitly degrade.
+The writer waits for socket drain before writing another frame; overflow sends a
+resync when writable, otherwise closes. Ledger delivery has no batching delay
+(therefore no intentional wait beyond the required 50 ms); network backpressure
+can delay actual receipt.
+
+The private supervisor separately owns its 8 MiB live replay backlog and writes
+64 KiB slices under socket backpressure. The adapter bounds each raw NDJSON line
+at 16 MiB plus the maximum computed serialized replay/ready/state/event envelope
+(replay has an empty events array; ready omits its null placeholder; coverage uses
+`Number.MAX_SAFE_INTEGER`). This admits one exact 16 MiB event;
+malformed or oversized passive input closes the stream. The receiving browser
+owns its 16 MiB assembly limit. A parsed record, serialized UTF-16 string, encoded
+frame, and socket buffers can coexist: these are logical budgets, not an RSS cap.
+Aggregate memory scales with connections, as do role watchers and private sockets.
+There is no global subscriber cap. HTTP/1 browsers commonly share about six
+connections per origin; multiple tabs, pane consumers and voice can exhaust that
+pool. Dispose surplus consumers; HTTP/2 deployment and browser pooling vary.
+
+Each web connection owns one role observer, including while the role is missing.
+Session describe/follow borrow it. Missing/replaced roles stop the old follow;
+reappearance can open another follow, still bound to the requested generation.
+Abort, revocation, server shutdown and late connector completion release owners
+idempotently. Pane observation does not acquire or release voice's independent
+controller. Private heartbeats remain serialized every two seconds; six seconds
+without one ends private health even if SSE keepalives continue.
+
+Fleet emits browser keepalives every second. Each App pane/voice attempt independently
+bounds opening through complete ready to ten seconds, regardless of incoming activity.
+After ready, nonempty byte chunks (including keepalives/comments and partial records)
+reset a ten-second silence deadline. Elapsed checks before activity and on browser
+visibility/pageshow resume give no hidden grace; suspended code expires at its first
+subsequent check. Expiry retires health and aborts the old attempt before bounded
+recovery/fallback. These browser clocks do not renew or replace credential deadlines.
+Comment-only/blank SSE frames are transport activity and publish no domain record.
+
+## Authentication, fallback and filesystem assumptions
+
+The stream is bound to its **opening** credential deadline. Rotating access lasts
+at most five minutes; it is not renewable in place. On `auth-expired`, obtain the
+renewed access credential and reconnect using only same-generation certified
+coverage. Count this normal auth reconnect separately from degraded operation.
+Fixed credentials use their device/sunset deadline. Cookie idle expiry is checked
+without updating lastSeenAt, including the exact 30-minute boundary; ordinary
+requests still update activity. Absolute expiry and revocation also end streams.
+The terminal resync uses `capability:"auth-expired"`, with retry `"authenticate"`
+for rotating credentials or `"reauthenticate"` for cookies/fixed credentials.
+Actions after expiry must reauthenticate; heartbeats cannot refresh session policy.
+
+`conversation_live_complete` describes current intersection of healthy role
+observation and private replay/heartbeat capability. It never certifies requested
+history. REST remains for initial latest history, user-requested older pages,
+explicit recovery, and older/unsupported/degraded server fallback. Healthy active
+consumers must not periodically fetch role details or history.
+
+Complete role delivery relies on native directory notifications for fleet config,
+role manifests and session files. Qualified native host filesystems are the
+intended deployment (macOS local APFS or Linux local filesystems with functional
+inotify). Watch errors, unexpected closure, unsupported watching, or invalid
+current role reads withdraw completeness. Silent event loss is not detectable
+without polling and is not promised away. Docker must expose the same state files
+and private socket to the Fleet process, with working directory-change delivery
+across the selected bind mount/volume. Docker Desktop host-to-VM mounts, network
+filesystems and remote/FUSE mounts require deployment-specific notification tests;
+use degraded REST fallback when those assumptions cannot be established. No ACP
+library changes are required.
+
+## Admission receipt provenance
+
+Prompt admission responses additionally expose optional `sessionGeneration`: the
+original durable admission generation. Both backend session generations are immutable
+for the admitting lifetime. Cached receipts retain that generation, and reopened command
+indexes derive it from the original `prompt.admitted` event, never a replacement session.
+Historical receipts without provable generation leave the field absent.
+
+This permits an explicitly retried pre-change `{text, commandId}` browser draft to settle
+only when matching receipt identity and original generation validate against its captured
+current owner. Missing/old provenance keeps a visible unresolved draft and its idempotency
+ID. Existing generation-bound drafts retain their original fences. `eventCursor` and causal
+coverage/inventory settlement remain unchanged; provenance is not a new settlement watermark.
+
+## Cross-repository qualification
+
+`test/web/fixtures/conversation-stack.ts` shares the real HTTP and private-control
+stack with the legacy conversation tests and the matching App checkout's optional
+`tests/fleet-live-data.integration.mjs`. ACP uses the existing child-process protocol
+fixture; native Codex uses the existing app-server protocol driver. Both exercise
+actual session, ledger, control adapter, HTTP framing and App decoder/reconciler/UI.
+Role availability changes are controlled fixture inputs; this does not qualify native
+filesystem event delivery on an arbitrary mount.
+
+Run Fleet's full tests and typecheck after integrated changes. Retain the SSE,
+workspace-auth-provenance and workspace-tunnel suites for frame/hosted authentication,
+expiry/revocation, delayed-open disposal and bounded slow consumers. App reports
+healthy content requests separately from bootstrap, paging, credential reconnect,
+explicit recovery and unsupported-host fallback. DOM mutation and fixture latency
+measurements have no claim about real-provider inference or physical-device audio.
+The App and Fleet changes require coordinated upstream delivery; source qualification
+does not establish that installed or serving packages contain them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet",
-  "version": "1.2.0-nightly.63",
+  "version": "1.2.0-nightly.64",
   "description": "Harness-agnostic fleet of persistent, identity-bound AI agents. Declarative fleet.yaml, managed native/ACP sessions, supervision, and ours.network messaging.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",
@@ -20,6 +20,7 @@
     "README.md",
     "docs/task-workspaces.md",
     "docs/live-voice.md",
+    "docs/conversation-stream.md",
     "docs/room-layouts.md",
     "docs/validation/managed-cli-permissions.md",
     "docs/fleet-migration.md",