harnery 0.34.1 → 0.36.0

package/dist/core/inbox/lifecycle.js

@@ -0,0 +1,41 @@
+import { project } from "./service.js";
+export const HARNERY_INBOX_COMPACTION_PLAN_SCHEMA = "harnery.inbox-compaction-plan/v1";
+export function planInboxCompaction(input) {
+    const projection = project(input.records);
+    const surfacedAt = new Map();
+    for (const record of input.records) {
+        if (record.kind === "surfaced")
+            surfacedAt.set(record.message_id, Date.parse(record.surfaced_at));
+    }
+    const compactableIds = new Set([...surfacedAt]
+        .filter(([, timestamp]) => input.now.getTime() - timestamp >= input.limits.surfaced_grace_ms)
+        .map(([id]) => id));
+    const compactableRecords = input.records.filter((record) => compactableIds.has(record.message_id)).length;
+    if (input.lifecycle === "terminal") {
+        if (projection.pending.length > 0) {
+            return plan(input, "none", "pending_protected", 0, input.records.length, projection.pending.length);
+        }
+        const terminalAt = input.terminal_at ? Date.parse(input.terminal_at) : Number.NaN;
+        if (!Number.isFinite(terminalAt) ||
+            input.now.getTime() - terminalAt < input.limits.terminal_grace_ms) {
+            return plan(input, "none", "terminal_grace", 0, input.records.length, 0);
+        }
+        return plan(input, "prune-terminal", "eligible", input.records.length, 0, 0);
+    }
+    if (compactableRecords === 0) {
+        return plan(input, "none", surfacedAt.size > 0 ? "surfaced_grace" : "active_recipient", 0, input.records.length, projection.pending.length);
+    }
+    return plan(input, "compact-surfaced", "eligible", compactableRecords, input.records.length - compactableRecords, projection.pending.length);
+}
+function plan(input, action, reason_code, remove_record_count, retained_record_count, protected_pending_count) {
+    return {
+        schema: HARNERY_INBOX_COMPACTION_PLAN_SCHEMA,
+        recipient_instance_id: input.recipient_instance_id,
+        action,
+        reason_code,
+        remove_record_count,
+        retained_record_count,
+        protected_pending_count,
+        dry_run: true,
+    };
+}

package/dist/core/inbox/service.d.ts

@@ -0,0 +1,36 @@
+import { type HarneryInboxLimits, type HarneryInboxMessageRecordV1, type HarneryInboxRecordV1, type HarneryInboxStatusV1, type HarneryInboxSurfaceBudget, type HarneryInboxSurfaceResult } from "./contract.js";
+export interface HarneryInboxServiceOptions {
+    coord_root: string;
+    limits: HarneryInboxLimits;
+    now?: () => Date;
+    id?: () => string;
+}
+export interface HarneryInboxSendInput {
+    sender_instance_id: string;
+    sender_display_name: string;
+    recipient_instance_id: string;
+    recipient_display_name: string;
+    body: string;
+}
+export interface HarneryInboxSendReceipt {
+    state: "queued";
+    message_id: string;
+    body_bytes: number;
+    synced: true;
+}
+export declare class HarneryInboxService {
+    #private;
+    constructor(options: HarneryInboxServiceOptions);
+    send(input: HarneryInboxSendInput): HarneryInboxSendReceipt;
+    records(recipientInstanceId: string): HarneryInboxRecordV1[];
+    pending(recipientInstanceId: string): HarneryInboxMessageRecordV1[];
+    status(recipientInstanceId: string): HarneryInboxStatusV1;
+    surface(recipientInstanceId: string, emit: (messages: readonly HarneryInboxMessageRecordV1[]) => Promise<void> | void, budget?: HarneryInboxSurfaceBudget): Promise<HarneryInboxSurfaceResult>;
+}
+export declare function inboxPath(coordRoot: string, recipientInstanceId: string): string;
+export declare function project(records: readonly HarneryInboxRecordV1[]): {
+    pending: HarneryInboxMessageRecordV1[];
+    surfaced: ReadonlySet<string>;
+    lastSurfaceAt?: string;
+};
+//# sourceMappingURL=service.d.ts.map

package/dist/core/inbox/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/service.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,kBAAkB,EACvB,KAAK,2BAA2B,EAChC,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,QAAQ,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,IAAI,CAAC;CACd;AAED,qBAAa,mBAAmB;;gBAGlB,OAAO,EAAE,0BAA0B;IAK/C,IAAI,CAAC,KAAK,EAAE,qBAAqB,GAAG,uBAAuB;IA2C3D,OAAO,CAAC,mBAAmB,EAAE,MAAM,GAAG,oBAAoB,EAAE;IAO5D,OAAO,CAAC,mBAAmB,EAAE,MAAM,GAAG,2BAA2B,EAAE;IAInE,MAAM,CAAC,mBAAmB,EAAE,MAAM,GAAG,oBAAoB;IA0BnD,OAAO,CACX,mBAAmB,EAAE,MAAM,EAC3B,IAAI,EAAE,CAAC,QAAQ,EAAE,SAAS,2BAA2B,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,EAChF,MAAM,GAAE,yBAIP,GACA,OAAO,CAAC,yBAAyB,CAAC;CAoCtC;AAED,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAG,MAAM,CAGhF;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,SAAS,oBAAoB,EAAE,GAAG;IACjE,OAAO,EAAE,2BAA2B,EAAE,CAAC;IACvC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAsBA"}

package/dist/core/inbox/service.js

@@ -0,0 +1,210 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { readCrashSafeJsonlFile, updateCrashSafeJsonlFile } from "../storage/durable-history.js";
+import { HARNERY_INBOX_RECORD_SCHEMA, HARNERY_INBOX_STATUS_SCHEMA, HarneryInboxCapacityError, } from "./contract.js";
+export class HarneryInboxService {
+    #options;
+    constructor(options) {
+        validateLimits(options.limits);
+        this.#options = options;
+    }
+    send(input) {
+        const recipient = opaqueId(input.recipient_instance_id, "recipient instance");
+        const bodyBytes = Buffer.byteLength(input.body);
+        const limits = this.#options.limits;
+        if (bodyBytes === 0 || bodyBytes > limits.max_message_body_bytes) {
+            throw new HarneryInboxCapacityError("message_body_limit", bodyBytes, limits.max_message_body_bytes);
+        }
+        const record = {
+            schema: HARNERY_INBOX_RECORD_SCHEMA,
+            kind: "message",
+            message_id: `msg_${this.#options.id?.() ?? randomUUID()}`,
+            sender_instance_id: opaqueId(input.sender_instance_id, "sender instance"),
+            sender_display_name: boundedDisplay(input.sender_display_name),
+            recipient_instance_id: recipient,
+            recipient_display_name: boundedDisplay(input.recipient_display_name),
+            created_at: now(this.#options).toISOString(),
+            body: input.body,
+            body_bytes: bodyBytes,
+        };
+        const path = inboxPath(this.#options.coord_root, recipient);
+        return updateCrashSafeJsonlFile(path, readOptions(limits), (records) => {
+            const projection = project(records);
+            capacityCheck(projection, record, path, limits);
+            return {
+                append: [record],
+                result: {
+                    state: "queued",
+                    message_id: record.message_id,
+                    body_bytes: bodyBytes,
+                    synced: true,
+                },
+            };
+        });
+    }
+    records(recipientInstanceId) {
+        return readCrashSafeJsonlFile(inboxPath(this.#options.coord_root, opaqueId(recipientInstanceId, "recipient instance")), readOptions(this.#options.limits));
+    }
+    pending(recipientInstanceId) {
+        return project(this.records(recipientInstanceId)).pending;
+    }
+    status(recipientInstanceId) {
+        const recipient = opaqueId(recipientInstanceId, "recipient instance");
+        const path = inboxPath(this.#options.coord_root, recipient);
+        const projection = project(this.records(recipient));
+        const pendingBytes = projection.pending.reduce((sum, record) => sum + record.body_bytes, 0);
+        const ratio = Math.max(projection.pending.length / this.#options.limits.max_pending_count, pendingBytes / this.#options.limits.max_pending_bytes);
+        return {
+            schema: HARNERY_INBOX_STATUS_SCHEMA,
+            recipient_instance_id: recipient,
+            pending_count: projection.pending.length,
+            pending_bytes: pendingBytes,
+            total_history_bytes: existsSync(path) ? statSync(path).size : 0,
+            ...(projection.pending[0] ? { oldest_pending_at: projection.pending[0].created_at } : {}),
+            pressure: ratio >= 1
+                ? "exhausted"
+                : ratio >= this.#options.limits.warning_pressure_ratio
+                    ? "warning"
+                    : "normal",
+            ...(projection.lastSurfaceAt ? { last_surface_at: projection.lastSurfaceAt } : {}),
+        };
+    }
+    async surface(recipientInstanceId, emit, budget = {
+        max_count: this.#options.limits.max_surface_count,
+        max_bytes: this.#options.limits.max_surface_bytes,
+        max_tokens: this.#options.limits.max_surface_tokens,
+    }) {
+        validateSurfaceBudget(budget);
+        const recipient = opaqueId(recipientInstanceId, "recipient instance");
+        const selected = selectOldestFitting(this.pending(recipient), budget);
+        await emit(selected);
+        if (selected.length > 0) {
+            const surfacedAt = now(this.#options).toISOString();
+            updateCrashSafeJsonlFile(inboxPath(this.#options.coord_root, recipient), readOptions(this.#options.limits), (records) => {
+                const stillPending = new Set(project(records).pending.map(({ message_id }) => message_id));
+                return {
+                    append: selected
+                        .filter(({ message_id }) => stillPending.has(message_id))
+                        .map(({ message_id }) => ({
+                        schema: HARNERY_INBOX_RECORD_SCHEMA,
+                        kind: "surfaced",
+                        message_id,
+                        surfaced_at: surfacedAt,
+                    })),
+                    result: undefined,
+                };
+            });
+        }
+        const remaining = this.pending(recipient);
+        return {
+            emitted: selected,
+            remaining_pending_count: remaining.length,
+            remaining_pending_bytes: remaining.reduce((sum, record) => sum + record.body_bytes, 0),
+            repeated_after_crash_possible: true,
+        };
+    }
+}
+export function inboxPath(coordRoot, recipientInstanceId) {
+    const id = opaqueId(recipientInstanceId, "recipient instance");
+    return join(resolve(coordRoot), ".harnery", "inbox", `${id}.jsonl`);
+}
+export function project(records) {
+    const messages = new Map();
+    const surfaced = new Set();
+    let lastSurfaceAt;
+    for (const record of records) {
+        validateRecord(record);
+        if (record.kind === "message") {
+            if (messages.has(record.message_id))
+                throw new Error(`duplicate inbox message ${record.message_id}`);
+            messages.set(record.message_id, record);
+        }
+        else {
+            if (!messages.has(record.message_id))
+                throw new Error(`surfaced marker precedes ${record.message_id}`);
+            surfaced.add(record.message_id);
+            if (!lastSurfaceAt || record.surfaced_at > lastSurfaceAt)
+                lastSurfaceAt = record.surfaced_at;
+        }
+    }
+    return {
+        pending: [...messages.values()].filter(({ message_id }) => !surfaced.has(message_id)),
+        surfaced,
+        ...(lastSurfaceAt ? { lastSurfaceAt } : {}),
+    };
+}
+function selectOldestFitting(pending, budget) {
+    const selected = [];
+    let bytes = 0;
+    let tokens = 0;
+    for (const record of pending) {
+        const recordTokens = Math.ceil(record.body_bytes / 4);
+        if (selected.length >= budget.max_count ||
+            bytes + record.body_bytes > budget.max_bytes ||
+            tokens + recordTokens > budget.max_tokens) {
+            break;
+        }
+        selected.push(record);
+        bytes += record.body_bytes;
+        tokens += recordTokens;
+    }
+    return selected;
+}
+function capacityCheck(projection, record, path, limits) {
+    const pendingBytes = projection.pending.reduce((sum, item) => sum + item.body_bytes, 0);
+    if (projection.pending.length + 1 > limits.max_pending_count) {
+        throw new HarneryInboxCapacityError("pending_count_limit", projection.pending.length, limits.max_pending_count);
+    }
+    if (pendingBytes + record.body_bytes > limits.max_pending_bytes) {
+        throw new HarneryInboxCapacityError("pending_bytes_limit", pendingBytes, limits.max_pending_bytes);
+    }
+    const nextHistoryBytes = (existsSync(path) ? statSync(path).size : 0) + Buffer.byteLength(`${JSON.stringify(record)}\n`);
+    if (nextHistoryBytes > limits.max_history_bytes) {
+        throw new HarneryInboxCapacityError("history_bytes_limit", nextHistoryBytes, limits.max_history_bytes);
+    }
+}
+function readOptions(limits) {
+    return {
+        max_record_bytes: Math.max(limits.max_message_body_bytes * 2, 4_096),
+        max_records: limits.max_history_records,
+    };
+}
+function now(options) {
+    return options.now?.() ?? new Date();
+}
+function opaqueId(value, field) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value))
+        throw new Error(`invalid ${field} id`);
+    return value;
+}
+function boundedDisplay(value) {
+    const result = value.trim();
+    if (result.length === 0 || Buffer.byteLength(result) > 256)
+        throw new Error("invalid display name");
+    return result;
+}
+function validateRecord(record) {
+    if (record.schema !== HARNERY_INBOX_RECORD_SCHEMA)
+        throw new Error("unknown inbox record schema");
+    if (record.kind === "message" && Buffer.byteLength(record.body) !== record.body_bytes) {
+        throw new Error(`inbox message ${record.message_id} has invalid body_bytes`);
+    }
+}
+function validateLimits(limits) {
+    for (const [field, value] of Object.entries(limits)) {
+        if (field === "warning_pressure_ratio")
+            continue;
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new Error(`invalid inbox limit ${field}`);
+    }
+    if (limits.warning_pressure_ratio <= 0 || limits.warning_pressure_ratio >= 1) {
+        throw new Error("warning_pressure_ratio must be between zero and one");
+    }
+}
+function validateSurfaceBudget(budget) {
+    for (const value of Object.values(budget)) {
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new Error("invalid inbox surface budget");
+    }
+}

package/dist/core/inbox/watcher.d.ts

@@ -0,0 +1,7 @@
+import type { HarneryInboxMessageRecordV1 } from "./contract.js";
+import type { HarneryInboxService } from "./service.js";
+export declare function watchInbox(service: HarneryInboxService, recipientInstanceId: string, options: {
+    signal: AbortSignal;
+    poll_ms?: number;
+}): AsyncGenerator<HarneryInboxMessageRecordV1>;
+//# sourceMappingURL=watcher.d.ts.map

package/dist/core/inbox/watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../../../src/core/inbox/watcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,wBAAuB,UAAU,CAC/B,OAAO,EAAE,mBAAmB,EAC5B,mBAAmB,EAAE,MAAM,EAC3B,OAAO,EAAE;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD,cAAc,CAAC,2BAA2B,CAAC,CAc7C"}

package/dist/core/inbox/watcher.js

@@ -0,0 +1,26 @@
+export async function* watchInbox(service, recipientInstanceId, options) {
+    const seen = new Set();
+    while (!options.signal.aborted) {
+        try {
+            for (const message of service.pending(recipientInstanceId)) {
+                if (seen.has(message.message_id))
+                    continue;
+                seen.add(message.message_id);
+                yield message;
+            }
+        }
+        catch {
+            // A transient missing or incomplete source is retried; no cursor is advanced.
+        }
+        await delay(options.poll_ms ?? 250, options.signal);
+    }
+}
+function delay(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}

package/dist/core/presence/codec-digest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codec-digest.d.ts","sourceRoot":"","sources":["../../../src/core/presence/codec-digest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAGxD,MAAM,MAAM,qBAAqB,GAC7B,UAAU,GACV,YAAY,GACZ,OAAO,GACP,MAAM,GACN,MAAM,GACN,YAAY,GACZ,OAAO,CAAC;AAEZ,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,OAAO,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,CAAC,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE;QACV,QAAQ,EAAE,qBAAqB,CAAC;QAChC,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,OAAO,GAAG,UAAU,GAAG,WAAW,CAAC;QAC/C,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,cAAc,EAAE,mBAAmB,EAAE,CAAC;CACvC;AAYD,+EAA+E;AAC/E,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAI7F;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,SAAS,OAAO,EAAE,GACzB,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAoHlC"}
+{"version":3,"file":"codec-digest.d.ts","sourceRoot":"","sources":["../../../src/core/presence/codec-digest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAGxD,MAAM,MAAM,qBAAqB,GAC7B,UAAU,GACV,YAAY,GACZ,OAAO,GACP,MAAM,GACN,MAAM,GACN,YAAY,GACZ,OAAO,CAAC;AAEZ,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,OAAO,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,CAAC,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE;QACV,QAAQ,EAAE,qBAAqB,CAAC;QAChC,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,OAAO,GAAG,UAAU,GAAG,WAAW,CAAC;QAC/C,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,cAAc,EAAE,mBAAmB,EAAE,CAAC;CACvC;AAYD,+EAA+E;AAC/E,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAI7F;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,SAAS,OAAO,EAAE,GACzB,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CA0HlC"}

package/dist/core/presence/codec-digest.js

@@ -85,10 +85,21 @@ export function projectPresenceCodecDigests(events) {
                 break;
             case "context.observed": {
                 const measurement = event.payload.measurement;
-                if (measurement.state === "observed" && measurement.value.limit_tokens > 0) {
+                if (measurement.state === "observed") {
+                    const usedPercent = "used_percent" in measurement.value
+                        ? measurement.value.used_percent
+                        : measurement.value.limit_tokens > 0
+                            ? (measurement.value.used_tokens / measurement.value.limit_tokens) * 100
+                            : undefined;
+                    if (usedPercent === undefined)
+                        break;
                     slot.context = {
-                        used_percent: Math.min(100, Math.max(0, Math.round((measurement.value.used_tokens / measurement.value.limit_tokens) * 100))),
-                        confidence: measurement.confidence === "exact" ? "exact" : "reported",
+                        used_percent: Math.min(100, Math.max(0, Math.round(usedPercent))),
+                        confidence: measurement.attestation === "inferred"
+                            ? "estimated"
+                            : measurement.confidence === "exact"
+                                ? "exact"
+                                : "reported",
                         event_id: event.event_id,
                         observed_at: event.time.observed_at,
                     };

package/dist/core/presence/relay-client.d.ts

@@ -29,6 +29,7 @@
 export declare function ensureRelayDaemon(coordRoot: string): void;
 /** Foreground daemon loop (spawned detached by ensureRelayDaemon). */
 export declare function runRelayDaemon(coordRoot: string): Promise<number>;
+export declare function appendPresenceRelayDiagnostic(coordRoot: string, event: string, fields?: Record<string, unknown>): "shared" | "legacy";
 /** Daemon status for `presence peers`/doctor surfaces. */
 export declare function relayDaemonStatus(coordRoot: string): {
     running: boolean;

package/dist/core/presence/relay-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relay-client.d.ts","sourceRoot":"","sources":["../../../src/core/presence/relay-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAyFH;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAwBzD;AAED,sEAAsE;AACtE,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAoKvE;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAMA"}
+{"version":3,"file":"relay-client.d.ts","sourceRoot":"","sources":["../../../src/core/presence/relay-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA6FH;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CA0BzD;AAED,sEAAsE;AACtE,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuLvE;AAED,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,QAAQ,GAAG,QAAQ,CAiBrB;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAMA"}

package/dist/core/presence/relay-client.js

@@ -22,11 +22,14 @@
  * daemon refuses to start and presence stays on git-refs.
  */
 import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, watch, writeFileSync, } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, watch, writeFileSync, } from "node:fs";
 import { join } from "node:path";
+import { coordEnv } from "../../lib/env.js";
 import { resolveMachineLabel } from "../../lib/machine.js";
 import { presenceRelayUrl } from "../config.js";
 import { eventV3ActiveWatchPath } from "../events/v3/reader.js";
+import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.js";
+import { RotatingTextSink } from "../storage/process-log.js";
 import { buildPresenceBlob } from "./blob.js";
 import { originUrl, rootCommitSha, sanitizeRefComponent } from "./git.js";
 import { computeSenderId, decryptPayload, deriveRoomCredentials, encryptPayload, parseRelayFrame, } from "./relay-protocol.js";
@@ -99,13 +102,16 @@ export function ensureRelayDaemon(coordRoot) {
         if (!existsSync(harnBin))
             return;
         mkdirSync(presenceDir(coordRoot), { recursive: true });
-        const log = openSync(logFilePath(coordRoot), "a");
+        const sharedLogs = coordEnv("SHARED_LOGS") !== "0";
+        const log = sharedLogs ? undefined : openSync(logFilePath(coordRoot), "a");
         const child = spawn(harnBin, ["presence", "relay-daemon"], {
             cwd: coordRoot,
             detached: true,
-            stdio: ["ignore", log, log],
+            stdio: log === undefined ? ["ignore", "ignore", "ignore"] : ["ignore", log, log],
             env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
         });
+        if (log !== undefined)
+            closeSync(log);
         child.unref();
     }
     catch {
@@ -116,17 +122,32 @@ export function ensureRelayDaemon(coordRoot) {
 export async function runRelayDaemon(coordRoot) {
     const url = presenceRelayUrl(coordRoot);
     if (!url) {
-        console.error("relay-daemon: no relay configured (presence.relay)");
+        const message = "relay-daemon: no relay configured (presence.relay)";
+        console.error(message);
+        if (coordEnv("SHARED_LOGS") !== "0") {
+            appendPresenceRelayDiagnostic(coordRoot, "relay.configuration_error", { message });
+        }
+        await closeProcessLoggers();
         return 2;
     }
     if (typeof WebSocket === "undefined") {
-        console.error("relay-daemon: no global WebSocket in this runtime (need Bun or Node >= 21)");
+        const message = "relay-daemon: no global WebSocket in this runtime (need Bun or Node >= 21)";
+        console.error(message);
+        if (coordEnv("SHARED_LOGS") !== "0") {
+            appendPresenceRelayDiagnostic(coordRoot, "relay.runtime_error", { message });
+        }
+        await closeProcessLoggers();
         return 2;
     }
     const sha = rootCommitSha(coordRoot);
     const origin = originUrl(coordRoot);
     if (!sha || !origin) {
-        console.error("relay-daemon: repo has no commits or no origin remote");
+        const message = "relay-daemon: repo has no commits or no origin remote";
+        console.error(message);
+        if (coordEnv("SHARED_LOGS") !== "0") {
+            appendPresenceRelayDiagnostic(coordRoot, "relay.repository_error", { message });
+        }
+        await closeProcessLoggers();
         return 2;
     }
     // Take (or take over) the pid file. A superseded daemon notices and exits.
@@ -152,6 +173,9 @@ export async function runRelayDaemon(coordRoot) {
     let shuttingDown = false;
     const log = (msg) => {
         console.log(`[${new Date().toISOString()}] ${msg}`);
+        if (coordEnv("SHARED_LOGS") !== "0") {
+            appendPresenceRelayDiagnostic(coordRoot, "relay.lifecycle", { message: msg });
+        }
     };
     const publishNow = async (force = false) => {
         if (!ws || ws.readyState !== WebSocket.OPEN)
@@ -265,7 +289,8 @@ export async function runRelayDaemon(coordRoot) {
             catch {
                 /* ignore */
             }
-            process.exit(0);
+            void closeProcessLoggers().finally(() => process.exit(0));
+            return;
         }
         // Idle machine (no live sessions for a while) → exit; hooks restart us.
         if (idleSince && Date.now() - idleSince > IDLE_EXIT_MS) {
@@ -279,12 +304,31 @@ export async function runRelayDaemon(coordRoot) {
             catch {
                 /* ignore */
             }
-            process.exit(0);
+            void closeProcessLoggers().finally(() => process.exit(0));
         }
     }, KEEPALIVE_MS);
     // Never resolves in normal operation; exits happen above.
     return await new Promise(() => { });
 }
+export function appendPresenceRelayDiagnostic(coordRoot, event, fields = {}) {
+    if (coordEnv("SHARED_LOGS") !== "0") {
+        try {
+            const logger = processLogger(coordRoot, "presence-relay");
+            if (event.includes("error"))
+                logger.error(event, legacyLogFields(fields));
+            else
+                logger.info(event, legacyLogFields(fields));
+            return "shared";
+        }
+        catch {
+            // Bootstrap failures retain a bounded text file for process diagnostics.
+        }
+    }
+    const sink = new RotatingTextSink({ path: logFilePath(coordRoot), max_bytes: 512 * 1_024 });
+    sink.append(`${JSON.stringify({ schema_version: 1, ts: new Date().toISOString(), event, ...fields })}\n`);
+    sink.close();
+    return "legacy";
+}
 /** Daemon status for `presence peers`/doctor surfaces. */
 export function relayDaemonStatus(coordRoot) {
     const rec = readPidRecord(coordRoot);

package/dist/core/semantic/adapters.d.ts

@@ -0,0 +1,37 @@
+import type { TSchema } from "@sinclair/typebox";
+import { type SemanticHarness, type SemanticUsageReceiptV1 } from "./contract.js";
+import { type SemanticReaderRoute } from "./routes.js";
+import type { SemanticReaderResolution } from "./storage.js";
+export interface SemanticAdapterSuccess {
+    ok: true;
+    text: string;
+    resolved_model_id: string;
+    model_attestation: "verified" | "requested-only";
+    duration_ms: number;
+    output_bytes: number;
+    usage: SemanticUsageReceiptV1;
+}
+export interface SemanticAdapterFailure {
+    ok: false;
+    reason_code: "harness_unavailable" | "authentication_unavailable" | "model_unavailable" | "model_mismatch";
+    resolved_model_id?: string;
+    model_attestation?: "verified" | "requested-only";
+    duration_ms: number;
+    usage: SemanticUsageReceiptV1;
+}
+export type SemanticAdapterResult = SemanticAdapterSuccess | SemanticAdapterFailure;
+export interface SemanticAdapter {
+    readonly route: SemanticReaderRoute;
+    discover(now?: () => Date): SemanticReaderResolution;
+    invoke(prompt: string, timeoutMs?: number, responseSchema?: TSchema): Promise<SemanticAdapterResult>;
+}
+export { SEMANTIC_READER_ROUTES, type SemanticReaderRoute } from "./routes.js";
+export declare function createSemanticAdapters(): Record<SemanticHarness, SemanticAdapter>;
+export declare function discoverSemanticReaders(adapters?: Record<SemanticHarness, SemanticAdapter>): Record<SemanticHarness, SemanticReaderResolution>;
+export interface ParsedSemanticHarnessOutput {
+    text: string;
+    executedModelId?: string;
+    usage?: SemanticUsageReceiptV1;
+}
+export declare function parseSemanticHarnessOutput(harness: SemanticHarness, stdout: string, outputFileText?: string): ParsedSemanticHarnessOutput;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/core/semantic/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/adapters.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,sBAAsB,EAC5B,MAAM,eAAe,CAAC;AACvB,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAW7D,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,UAAU,GAAG,gBAAgB,CAAC;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,sBAAsB,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,KAAK,CAAC;IACV,WAAW,EACP,qBAAqB,GACrB,4BAA4B,GAC5B,mBAAmB,GACnB,gBAAgB,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,UAAU,GAAG,gBAAgB,CAAC;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,sBAAsB,CAAC;CAC/B;AAED,MAAM,MAAM,qBAAqB,GAAG,sBAAsB,GAAG,sBAAsB,CAAC;AAEpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,GAAG,wBAAwB,CAAC;IACrD,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,OAAO,GACvB,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACnC;AAED,OAAO,EAAE,sBAAsB,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAE/E,wBAAgB,sBAAsB,IAAI,MAAM,CAAC,eAAe,EAAE,eAAe,CAAC,CAMjF;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,GAAE,MAAM,CAAC,eAAe,EAAE,eAAe,CAA4B,GAC5E,MAAM,CAAC,eAAe,EAAE,wBAAwB,CAAC,CAMnD;AAwKD,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,MAAM,EACd,cAAc,CAAC,EAAE,MAAM,GACtB,2BAA2B,CAsC7B"}