@ours.network/fleet 0.15.1 → 0.15.4

package/dist/session/conversation-normalizer.js

@@ -0,0 +1,356 @@
+import { createHash } from 'node:crypto';
+/**
+ * Reduce one ACP v1 `session/update` into one conversation-domain event draft.
+ *
+ * This is the protocol seam: v1 create/update pairs (and a future v2 upsert
+ * stream) both land in the same domain shapes. The function is pure and total —
+ * it never throws, never passes raw wire objects through, caps every payload,
+ * and quarantines namespaced `_meta` so unknown extensions cannot leak into
+ * generic rendering paths.
+ */
+/** Cap for any single normalized text payload (spec §5.3). */
+export const MAX_TEXT_BYTES = 256 * 1024;
+/** Cap for one adapter `_meta` namespace value. */
+export const MAX_META_BYTES = 16 * 1024;
+/** Cap for serialized raw tool input/output retained as structured JSON. */
+export const MAX_RAW_JSON_BYTES = 64 * 1024;
+/** Cap for the sanitized preview of an unsupported update. */
+export const MAX_UNSUPPORTED_PREVIEW_CHARS = 2_048;
+const digest24 = (value) => createHash('sha256').update(value).digest('hex').slice(0, 24);
+const asString = (value) => typeof value === 'string' ? value : undefined;
+const asFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** Truncate to a byte budget without splitting a UTF-8 code point. */
+function truncateUtf8(text, maxBytes) {
+    if (Buffer.byteLength(text) <= maxBytes)
+        return text;
+    const buffer = Buffer.from(text).subarray(0, maxBytes);
+    return buffer.toString('utf8').replace(/�+$/u, '');
+}
+function cappedText(raw, redact) {
+    const text = asString(raw) ?? '';
+    const bytes = Buffer.byteLength(text);
+    if (redact !== undefined)
+        return { text: redact, bytes, truncated: true, digest: digest24(text) };
+    if (bytes <= MAX_TEXT_BYTES)
+        return { text, bytes };
+    return {
+        text: truncateUtf8(text, MAX_TEXT_BYTES), bytes,
+        truncated: true, digest: digest24(text),
+    };
+}
+function normalizedText(raw, redact) {
+    const text = asString(raw) ?? '';
+    const bytes = Buffer.byteLength(text);
+    if (redact !== undefined)
+        return { type: 'text', text: redact, bytes, redacted: true, digest: digest24(text) };
+    const capped = cappedText(text);
+    return {
+        type: 'text', text: capped.text, bytes,
+        ...(capped.truncated ? { truncated: true, digest: capped.digest } : {}),
+    };
+}
+function normalizeContentBlock(block, redact) {
+    if (!isRecord(block))
+        return normalizedText('', redact);
+    switch (block.type) {
+        case 'text':
+            return normalizedText(block.text, redact);
+        case 'image':
+        case 'audio':
+            // Described, not carried: media rendering has its own validation phase,
+            // and base64 payloads must never ride into the durable store unchecked.
+            return {
+                type: block.type,
+                mimeType: asString(block.mimeType) ?? 'application/octet-stream',
+                bytes: Buffer.byteLength(asString(block.data) ?? ''),
+                ...(asString(block.uri) ? { uri: asString(block.uri) } : {}),
+            };
+        case 'resource_link':
+            return {
+                type: 'resource_link',
+                uri: asString(block.uri) ?? '',
+                ...(asString(block.name) ? { name: asString(block.name) } : {}),
+                ...(asString(block.mimeType) ? { mimeType: asString(block.mimeType) } : {}),
+            };
+        case 'resource': {
+            const resource = isRecord(block.resource) ? block.resource : {};
+            const body = asString(resource.text) ?? asString(resource.blob) ?? '';
+            return {
+                type: 'resource',
+                ...(asString(resource.uri) ? { uri: asString(resource.uri) } : {}),
+                ...(asString(resource.mimeType) ? { mimeType: asString(resource.mimeType) } : {}),
+                bytes: Buffer.byteLength(body),
+            };
+        }
+        default:
+            return normalizedText(`[${asString(block.type) ?? 'unknown-content'}]`);
+    }
+}
+const SENSITIVE_JSON_KEYS = new Set([
+    'auth', 'authorization', 'cookie', 'password', 'passwd', 'secret', 'token',
+    'apikey', 'accesskey', 'privatekey',
+]);
+function redactSensitiveJson(value) {
+    const seen = new WeakSet();
+    let redacted = false;
+    const visit = (current, depth) => {
+        if (depth > 32)
+            return '[depth capped]';
+        if (Array.isArray(current)) {
+            if (seen.has(current))
+                throw new TypeError('circular JSON');
+            seen.add(current);
+            return current.map(item => visit(item, depth + 1));
+        }
+        if (!isRecord(current))
+            return current;
+        if (seen.has(current))
+            throw new TypeError('circular JSON');
+        seen.add(current);
+        const output = {};
+        for (const [key, nested] of Object.entries(current)) {
+            const compact = key.replace(/[^a-z0-9]/gi, '').toLowerCase();
+            if (compact === 'env' || compact === 'environment') {
+                redacted = true;
+                output[key] = isRecord(nested)
+                    ? Object.fromEntries(Object.keys(nested).map(name => [name, '<redacted>']))
+                    : '<redacted>';
+            }
+            else if (SENSITIVE_JSON_KEYS.has(compact)
+                || [...SENSITIVE_JSON_KEYS].some(sensitive => compact.endsWith(sensitive))) {
+                redacted = true;
+                output[key] = '<redacted>';
+            }
+            else
+                output[key] = visit(nested, depth + 1);
+        }
+        return output;
+    };
+    return { value: visit(value, 0), redacted };
+}
+function boundedJson(value) {
+    let serialized;
+    let safe;
+    let redacted = false;
+    try {
+        const result = redactSensitiveJson(value);
+        safe = result.value;
+        redacted = result.redacted;
+        serialized = JSON.stringify(safe) ?? 'null';
+    }
+    catch {
+        // Circular or otherwise unserializable: keep the fact, drop the value.
+        return { bytes: 0, truncated: true };
+    }
+    const bytes = Buffer.byteLength(serialized);
+    if (bytes <= MAX_RAW_JSON_BYTES)
+        return { json: safe, bytes, ...(redacted ? { redacted: true } : {}) };
+    return {
+        bytes, truncated: true, digest: digest24(serialized),
+        ...(redacted ? { redacted: true } : {}),
+    };
+}
+function quarantineMeta(meta) {
+    if (!isRecord(meta))
+        return undefined;
+    const entries = [];
+    for (const [namespace, value] of Object.entries(meta)) {
+        let serialized;
+        try {
+            serialized = JSON.stringify(value) ?? 'null';
+        }
+        catch {
+            entries.push({ namespace, truncated: true });
+            continue;
+        }
+        const bytes = Buffer.byteLength(serialized);
+        if (bytes <= MAX_META_BYTES)
+            entries.push({ namespace, value });
+        else
+            entries.push({ namespace, truncated: true, bytes });
+    }
+    return entries.length ? entries : undefined;
+}
+function planEntries(raw, redact) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter(isRecord).map(entry => ({
+        content: cappedText(entry.content, redact),
+        priority: entry.priority === 'high' || entry.priority === 'medium' || entry.priority === 'low'
+            ? entry.priority : 'medium',
+        status: entry.status === 'pending' || entry.status === 'in_progress' || entry.status === 'completed'
+            ? entry.status : 'pending',
+    }));
+}
+function normalizeToolContent(raw, redact) {
+    if (!Array.isArray(raw))
+        return undefined;
+    return raw.filter(isRecord).map((item) => {
+        switch (item.type) {
+            case 'diff':
+                return {
+                    type: 'diff',
+                    path: asString(item.path) ?? '',
+                    newText: cappedText(item.newText, redact),
+                    ...(item.oldText != null ? { oldText: cappedText(item.oldText, redact) } : {}),
+                };
+            case 'terminal':
+                return { type: 'terminal', terminalId: asString(item.terminalId) ?? '' };
+            case 'content':
+            default:
+                return { type: 'content', content: normalizeContentBlock(item.content, redact) };
+        }
+    });
+}
+function toolUpsert(update, snapshot, redact) {
+    const payload = {
+        toolCallId: asString(update.toolCallId) ?? '',
+        snapshot,
+    };
+    if (asString(update.title) !== undefined)
+        payload.title = redact ?? asString(update.title);
+    if (asString(update.kind) !== undefined)
+        payload.kind = asString(update.kind);
+    if (asString(update.status) !== undefined)
+        payload.status = asString(update.status);
+    const content = normalizeToolContent(update.content, redact);
+    if (content)
+        payload.content = content;
+    if (Array.isArray(update.locations)) {
+        payload.locations = update.locations.filter(isRecord).map(location => ({
+            path: asString(location.path) ?? '',
+            ...(asFiniteNumber(location.line) !== undefined ? { line: asFiniteNumber(location.line) } : {}),
+        }));
+    }
+    if (update.rawInput !== undefined)
+        payload.rawInput = boundedJson(update.rawInput);
+    if (update.rawOutput !== undefined)
+        payload.rawOutput = boundedJson(update.rawOutput);
+    return payload;
+}
+function unsupported(update) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(update) ?? String(update);
+    }
+    catch {
+        serialized = '[unserializable update]';
+    }
+    const kind = isRecord(update) ? asString(update.sessionUpdate) : undefined;
+    return {
+        sessionUpdate: kind ?? 'unknown',
+        bytes: Buffer.byteLength(serialized),
+        preview: serialized.slice(0, MAX_UNSUPPORTED_PREVIEW_CHARS),
+    };
+}
+export function normalizeSessionUpdate(update, options = {}) {
+    const redact = options.redactText;
+    const raw = update;
+    if (!isRecord(raw) || typeof raw.sessionUpdate !== 'string')
+        return { kind: 'unsupported', payload: unsupported(raw) };
+    const adapterMeta = quarantineMeta(raw._meta);
+    const withMeta = (result) => adapterMeta ? { ...result, adapterMeta } : result;
+    switch (raw.sessionUpdate) {
+        case 'user_message_chunk':
+        case 'agent_message_chunk': {
+            const payload = {
+                role: raw.sessionUpdate === 'user_message_chunk' ? 'user' : 'assistant',
+                content: normalizeContentBlock(raw.content, redact),
+            };
+            const messageId = asString(raw.messageId);
+            return withMeta({ kind: 'message.chunk', payload, ...(messageId ? { messageId } : {}) });
+        }
+        case 'agent_thought_chunk': {
+            const messageId = asString(raw.messageId);
+            return withMeta({
+                kind: 'thought.chunk',
+                payload: { content: normalizeContentBlock(raw.content, redact) },
+                ...(messageId ? { messageId } : {}),
+            });
+        }
+        case 'tool_call':
+        case 'tool_call_update': {
+            const payload = toolUpsert(raw, raw.sessionUpdate === 'tool_call', redact);
+            return withMeta({
+                kind: 'tool.upsert', payload,
+                ...(payload.toolCallId ? { toolCallId: payload.toolCallId } : {}),
+            });
+        }
+        case 'plan':
+            return withMeta({
+                kind: 'plan.replace',
+                payload: { entries: planEntries(raw.entries, redact) },
+            });
+        case 'plan_update': {
+            // Unstable representation: normalize what is structured, reference the rest.
+            const plan = isRecord(raw.plan) ? raw.plan : {};
+            const payload = {
+                ...(asString(plan.planId) ? { planId: asString(plan.planId) } : {}),
+            };
+            if (plan.type === 'items')
+                payload.entries = planEntries(plan.entries, redact);
+            else if (plan.type === 'file' && asString(plan.uri))
+                payload.file = { uri: asString(plan.uri) };
+            else if (plan.type === 'markdown')
+                payload.markdown = cappedText(plan.content, redact);
+            return withMeta({ kind: 'plan.replace', payload });
+        }
+        case 'plan_removed':
+            return withMeta({
+                kind: 'plan.replace',
+                payload: {
+                    ...(asString(raw.planId) ? { planId: asString(raw.planId) } : {}),
+                    removed: true,
+                },
+            });
+        case 'usage_update': {
+            const cost = isRecord(raw.cost)
+                && asFiniteNumber(raw.cost.amount) !== undefined && asString(raw.cost.currency)
+                ? { amount: asFiniteNumber(raw.cost.amount), currency: asString(raw.cost.currency) }
+                : undefined;
+            return withMeta({
+                kind: 'usage.updated',
+                payload: {
+                    used: asFiniteNumber(raw.used) ?? 0,
+                    size: asFiniteNumber(raw.size) ?? 0,
+                    ...(cost ? { cost } : {}),
+                },
+            });
+        }
+        case 'current_mode_update':
+            return withMeta({
+                kind: 'session.state',
+                payload: { currentModeId: asString(raw.currentModeId) },
+            });
+        case 'session_info_update':
+            return withMeta({
+                kind: 'session.info',
+                payload: {
+                    ...(raw.title !== undefined ? { title: asString(raw.title) ?? null } : {}),
+                    ...(raw.updatedAt !== undefined ? { updatedAt: asString(raw.updatedAt) ?? null } : {}),
+                },
+            });
+        case 'available_commands_update': {
+            const commands = Array.isArray(raw.availableCommands)
+                ? raw.availableCommands.filter(isRecord).map(command => ({
+                    name: asString(command.name) ?? '',
+                    description: cappedText(command.description),
+                    ...(isRecord(command.input) && asString(command.input.hint)
+                        ? { inputHint: asString(command.input.hint) } : {}),
+                }))
+                : [];
+            const payload = { commands };
+            return withMeta({ kind: 'capabilities.updated', payload });
+        }
+        case 'config_option_update':
+            // Structured but adapter-shaped: retained as bounded JSON for later,
+            // capability-gated rendering rather than trusted field-by-field today.
+            return withMeta({
+                kind: 'capabilities.updated',
+                payload: { configOptions: boundedJson(raw.configOptions) },
+            });
+        default:
+            return withMeta({ kind: 'unsupported', payload: unsupported(raw) });
+    }
+}

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

@@ -0,0 +1,88 @@
+import type { ConversationEventV1, PromptReceipt } from './conversation-types.js';
+export interface ConversationStoreOptions {
+    roleId: string;
+    segmentBytes?: number;
+    log?(line: string): void;
+}
+export interface OpenPrompt {
+    promptId: string;
+    state: 'admitted' | 'started';
+    /** The prompt body, when it was persisted (browser/local sources). */
+    text?: string;
+    commandId?: string;
+    sessionGeneration: string;
+}
+export interface ConversationPageRequest {
+    after?: string;
+    limit?: number;
+}
+export interface ConversationStorePage {
+    events: ConversationEventV1[];
+    firstAvailableCursor?: string;
+    nextCursor?: string;
+    hasMore: boolean;
+}
+export declare class IdempotencyConflictError extends Error {
+    constructor();
+}
+type EventDraft = Omit<ConversationEventV1, 'schemaVersion' | 'roleId' | 'eventId' | 'seq' | 'at'>;
+export declare class ConversationEventStore {
+    private readonly dir;
+    private nextSeq;
+    private segments;
+    private tail;
+    private readonly listeners;
+    private readonly commands;
+    private readonly promptStates;
+    private activeFd?;
+    private activeBytes;
+    private _degraded;
+    private degradedReason?;
+    private readonly segmentBytes;
+    private readonly roleId;
+    private readonly log;
+    constructor(dir: string, options: ConversationStoreOptions);
+    /** First 24 hex chars of sha-256; the idempotency body-digest convention. */
+    static bodyDigest(body: string): string;
+    get degraded(): boolean;
+    get degradedDetail(): string | undefined;
+    /**
+     * 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: EventDraft): ConversationEventV1;
+    /**
+     * 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: EventDraft): ConversationEventV1 | undefined;
+    page(request?: ConversationPageRequest): ConversationStorePage;
+    subscribe(listener: (event: ConversationEventV1) => void): () => void;
+    /** Store the receipt a repeated command must get back. */
+    recordReceipt(commandId: string, receipt: PromptReceipt, bodyDigest: string): void;
+    /**
+     * 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: string, bodyDigest: string): PromptReceipt | undefined;
+    /**
+     * 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(): OpenPrompt[];
+    lastCursor(): string | undefined;
+    close(): void;
+    private recover;
+    private readManifest;
+    private discoverSegments;
+    private readSegment;
+    private rebuildCommandIndex;
+    private trackPromptState;
+    private segmentFd;
+    private writeManifest;
+    private firstStoredSeq;
+    private eventsAfter;
+    private markDegraded;
+}
+export {};