@pellux/goodvibes-sdk 0.37.2 → 1.0.0

package/dist/platform/calendar/types.d.ts

@@ -0,0 +1,170 @@
+/**
+ * types.ts — the shared type surface for the calendar-connectivity module.
+ *
+ * Pure data shapes only. The module reads external calendars two ways — parsing
+ * .ics text (a file or a fetched feed body) into typed events, and managing named
+ * feed subscriptions with honest per-subscription status — and every value a
+ * caller sees is described here.
+ *
+ * Honesty contract (see docs/decisions/2026-07-05-calendar-connectivity-sdk-extraction.md):
+ *  - date-time zone handling is stated, never faked. A DTSTART with a TZID is kept
+ *    as its wall-clock value with the TZID recorded; NO offset conversion is applied
+ *    (this build ships no tz database), so `zone: 'tzid'` means "local wall time in
+ *    the named zone, not converted to UTC". A trailing-Z value is real UTC
+ *    (`zone: 'utc'`); a bare date-time with neither is floating (`zone: 'floating'`).
+ *  - recurrence is either fully expanded or explicitly not. A VEVENT whose RRULE
+ *    uses only the supported subset expands to real occurrences; anything else keeps
+ *    the seed event and carries an explicit `expansion: 'unsupported'` marker naming
+ *    the part we declined to expand. Occurrences are never fabricated from a rule we
+ *    do not fully honor.
+ */
+/** How a date/date-time value is anchored in time. */
+export type EventZone = 'utc' | 'floating' | 'tzid';
+/** A parsed DTSTART/DTEND value with its honest time anchoring. */
+export interface EventDateTime {
+    /**
+     * The as-parsed value:
+     *  - `kind: 'date'`      => 'YYYY-MM-DD'
+     *  - `kind: 'date-time'` => 'YYYY-MM-DDTHH:mm:ss' (floating/tzid) or the same
+     *                           with a trailing 'Z' (utc).
+     */
+    readonly value: string;
+    readonly kind: 'date' | 'date-time';
+    readonly zone: EventZone;
+    /** Present only when `zone === 'tzid'`; the raw TZID as written in the feed. */
+    readonly tzid?: string;
+}
+/** Whether a VEVENT's RRULE was fully expanded, and why not when it was not. */
+export type RecurrenceExpansion = 'full' | 'unsupported';
+/** The honest recurrence descriptor attached to a recurring VEVENT. */
+export interface RecurrenceInfo {
+    /** The raw RRULE line value, e.g. 'FREQ=WEEKLY;BYDAY=MO,WE;COUNT=10'. */
+    readonly rule: string;
+    readonly expansion: RecurrenceExpansion;
+    /**
+     * When `expansion === 'unsupported'`, a plain-language reason naming the part
+     * this build does not expand (e.g. 'RRULE part BYMONTHDAY is not expanded by
+     * this build'). Absent when `expansion === 'full'`.
+     */
+    readonly unsupportedReason?: string;
+}
+/** A single calendar event parsed from a VEVENT. */
+export interface CalendarEvent {
+    /** The VEVENT UID; a stable synthetic id is assigned when the feed omits one. */
+    readonly uid: string;
+    readonly summary: string;
+    readonly location?: string;
+    readonly description?: string;
+    readonly start: EventDateTime;
+    /** DTEND when present; a VEVENT may legitimately omit it (e.g. a reminder). */
+    readonly end?: EventDateTime;
+    /** Present when the VEVENT carried an RRULE. */
+    readonly recurrence?: RecurrenceInfo;
+}
+/** A non-fatal problem encountered while parsing, tied to the source when known. */
+export interface ParseDiagnostic {
+    /** 1-based line number in the (unfolded) source, when attributable. */
+    readonly line?: number;
+    /** The offending component/property name, when attributable (e.g. 'DTSTART'). */
+    readonly component?: string;
+    readonly message: string;
+}
+/** The full result of parsing .ics text. */
+export interface ParsedCalendar {
+    /** Calendar name from X-WR-CALNAME, when the feed supplied one. */
+    readonly calendarName?: string;
+    readonly events: readonly CalendarEvent[];
+    /**
+     * Events that were recognised as VEVENTs but could not be turned into a usable
+     * event (e.g. no DTSTART). Never silently dropped — surfaced here with a reason.
+     */
+    readonly skipped: readonly ParseDiagnostic[];
+    /** Non-fatal notes (unsupported recurrence, unknown TZID kept as-is, etc.). */
+    readonly diagnostics: readonly ParseDiagnostic[];
+}
+/** One concrete occurrence produced by expanding a (possibly recurring) event. */
+export interface EventOccurrence {
+    readonly event: CalendarEvent;
+    /** Occurrence start as 'YYYY-MM-DD' or 'YYYY-MM-DDTHH:mm:ss[Z]', mirroring start.kind/zone. */
+    readonly start: string;
+    /** True only for the seed occurrence of a recurring event. */
+    readonly isSeed: boolean;
+}
+/** An inclusive [from, to] window for occurrence expansion, as 'YYYY-MM-DD' strings. */
+export interface DateWindow {
+    readonly from: string;
+    readonly to: string;
+}
+/** Honest health of a named feed subscription. */
+export type SubscriptionHealth = 'never-fetched' | 'ok' | 'stale' | 'unreachable' | 'parse-error';
+/** A named external-calendar feed subscription and its current status. */
+export interface CalendarSubscription {
+    readonly name: string;
+    /** The feed URL. Treat as secrets-adjacent: a Google "secret address" grants read access. */
+    readonly url: string;
+    /** How often a refresh becomes due, in milliseconds. Bounded by the store. */
+    readonly refreshIntervalMs: number;
+    /** Epoch ms of the last fetch ATTEMPT (success or failure), if any. */
+    readonly lastFetchedAt?: number;
+    /** Epoch ms of the last SUCCESSFUL parse, if any. */
+    readonly lastSucceededAt?: number;
+    /** HTTP validators for conditional refresh, when the server supplied them. */
+    readonly etag?: string;
+    readonly lastModified?: string;
+    readonly health: SubscriptionHealth;
+    /** Plain-language elaboration of a non-ok health (http status, parse line, age). */
+    readonly detail?: string;
+    /** Count of events from the most recent successful parse. */
+    readonly eventCount?: number;
+}
+/** A conditional-fetch request the injected fetcher receives. */
+export interface FeedFetchRequest {
+    readonly url: string;
+    readonly etag?: string;
+    readonly lastModified?: string;
+}
+/** The result the injected fetcher returns. Tests supply this from fake feeds. */
+export type FeedFetchResult = {
+    readonly kind: 'ok';
+    readonly body: string;
+    readonly etag?: string;
+    readonly lastModified?: string;
+} | {
+    readonly kind: 'not-modified';
+    readonly etag?: string;
+    readonly lastModified?: string;
+} | {
+    readonly kind: 'error';
+    readonly status?: number;
+    readonly message: string;
+};
+/** Injected network boundary — the ONLY way this module reaches the network. */
+export type FeedFetcher = (req: FeedFetchRequest) => Promise<FeedFetchResult>;
+/** Injected clock, so refresh/staleness timing is deterministic in tests. */
+export type Clock = () => number;
+/** The per-refresh report a caller can turn into an honest status line. */
+export interface RefreshReport {
+    readonly name: string;
+    /**
+     *  - 'updated'      — fetched fresh body, parsed, events replaced.
+     *  - 'not-modified' — server said 304; kept prior events, refreshed timestamp.
+     *  - 'skipped'      — not due yet and not forced.
+     *  - 'unreachable'  — fetch failed at the network stage.
+     *  - 'parse-error'  — fetched, but the body could not be parsed.
+     */
+    readonly outcome: 'updated' | 'not-modified' | 'skipped' | 'unreachable' | 'parse-error';
+    readonly health: SubscriptionHealth;
+    readonly eventCount?: number;
+    readonly detail?: string;
+}
+/** Serialisable subscription metadata for a caller that persists across restarts. */
+export interface SubscriptionSnapshot {
+    readonly name: string;
+    readonly url: string;
+    readonly refreshIntervalMs: number;
+    readonly lastFetchedAt?: number;
+    readonly lastSucceededAt?: number;
+    readonly etag?: string;
+    readonly lastModified?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/platform/calendar/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/platform/calendar/types.ts"],"names":[],"mappings":"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"}

package/dist/platform/calendar/types.js

@@ -0,0 +1,21 @@
+/**
+ * types.ts — the shared type surface for the calendar-connectivity module.
+ *
+ * Pure data shapes only. The module reads external calendars two ways — parsing
+ * .ics text (a file or a fetched feed body) into typed events, and managing named
+ * feed subscriptions with honest per-subscription status — and every value a
+ * caller sees is described here.
+ *
+ * Honesty contract (see docs/decisions/2026-07-05-calendar-connectivity-sdk-extraction.md):
+ *  - date-time zone handling is stated, never faked. A DTSTART with a TZID is kept
+ *    as its wall-clock value with the TZID recorded; NO offset conversion is applied
+ *    (this build ships no tz database), so `zone: 'tzid'` means "local wall time in
+ *    the named zone, not converted to UTC". A trailing-Z value is real UTC
+ *    (`zone: 'utc'`); a bare date-time with neither is floating (`zone: 'floating'`).
+ *  - recurrence is either fully expanded or explicitly not. A VEVENT whose RRULE
+ *    uses only the supported subset expands to real occurrences; anything else keeps
+ *    the seed event and carries an explicit `expansion: 'unsupported'` marker naming
+ *    the part we declined to expand. Occurrences are never fabricated from a rule we
+ *    do not fully honor.
+ */
+export {};

package/dist/platform/companion/companion-chat-attachments.d.ts

@@ -0,0 +1,29 @@
+/**
+ * companion-chat-attachments.ts
+ *
+ * Pure attachment-resolution + provider-content helpers for CompanionChatManager.
+ * Extracted so the manager file stays within its line budget; behaviour is
+ * unchanged — every function takes the artifact store explicitly instead of
+ * reaching through `this`.
+ */
+import { Buffer } from 'node:buffer';
+import type { ContentPart } from '../providers/interface.js';
+import type { ArtifactDescriptor } from '../artifacts/index.js';
+import type { CompanionChatMessageAttachment, CompanionChatMessageAttachmentInput, CompanionChatMessage } from './companion-chat-types.js';
+export declare const MAX_ATTACHMENTS_PER_MESSAGE = 8;
+export interface CompanionChatArtifactStore {
+    get(artifactId: string): ArtifactDescriptor | null;
+    readContent(artifactId: string): Promise<{
+        readonly record: {
+            readonly mimeType: string;
+            readonly filename?: string | undefined;
+        };
+        readonly buffer: ArrayBuffer | Uint8Array | Buffer;
+    }>;
+}
+export declare function toNodeBuffer(buffer: ArrayBuffer | Uint8Array | Buffer): Buffer;
+export declare function resolveAttachments(inputs: readonly CompanionChatMessageAttachmentInput[], artifactStore: CompanionChatArtifactStore | null): CompanionChatMessageAttachment[];
+export declare function formatAttachmentSummary(attachments: readonly CompanionChatMessageAttachment[]): string;
+export declare function buildReplayUserContent(message: CompanionChatMessage): string;
+export declare function buildProviderUserContent(content: string, attachments: readonly CompanionChatMessageAttachment[], artifactStore: CompanionChatArtifactStore | null): Promise<string | ContentPart[]>;
+//# sourceMappingURL=companion-chat-attachments.d.ts.map

package/dist/platform/companion/companion-chat-attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"companion-chat-attachments.d.ts","sourceRoot":"","sources":["../../../src/platform/companion/companion-chat-attachments.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EACV,8BAA8B,EAC9B,mCAAmC,EACnC,oBAAoB,EACrB,MAAM,2BAA2B,CAAC;AAInC,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAI7C,MAAM,WAAW,0BAA0B;IACzC,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAAC;IACnD,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QACvC,QAAQ,CAAC,MAAM,EAAE;YAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;SAAE,CAAC;QACvF,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,MAAM,CAAC;KACpD,CAAC,CAAC;CACJ;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAI9E;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,mCAAmC,EAAE,EACtD,aAAa,EAAE,0BAA0B,GAAG,IAAI,GAC/C,8BAA8B,EAAE,CAwClC;AAED,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,SAAS,8BAA8B,EAAE,GAAG,MAAM,CAOtG;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAE5E;AAqBD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,SAAS,8BAA8B,EAAE,EACtD,aAAa,EAAE,0BAA0B,GAAG,IAAI,GAC/C,OAAO,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC,CAmCjC"}

package/dist/platform/companion/companion-chat-attachments.js

@@ -0,0 +1,121 @@
+/**
+ * companion-chat-attachments.ts
+ *
+ * Pure attachment-resolution + provider-content helpers for CompanionChatManager.
+ * Extracted so the manager file stays within its line budget; behaviour is
+ * unchanged — every function takes the artifact store explicitly instead of
+ * reaching through `this`.
+ */
+import { Buffer } from 'node:buffer';
+import { summarizeError } from '../utils/error-display.js';
+import { logger } from '../utils/logger.js';
+export const MAX_ATTACHMENTS_PER_MESSAGE = 8;
+const MAX_INLINE_IMAGE_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+const MAX_INLINE_TEXT_ATTACHMENT_BYTES = 200 * 1024;
+export function toNodeBuffer(buffer) {
+    if (Buffer.isBuffer(buffer))
+        return buffer;
+    if (buffer instanceof ArrayBuffer)
+        return Buffer.from(new Uint8Array(buffer));
+    return Buffer.from(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+}
+export function resolveAttachments(inputs, artifactStore) {
+    if (inputs.length === 0)
+        return [];
+    if (inputs.length > MAX_ATTACHMENTS_PER_MESSAGE) {
+        throw Object.assign(new Error(`A companion chat message can include at most ${MAX_ATTACHMENTS_PER_MESSAGE} attachments.`), { code: 'TOO_MANY_ATTACHMENTS', status: 400 });
+    }
+    if (!artifactStore) {
+        throw Object.assign(new Error('Companion chat attachments require an artifact store.'), { code: 'ATTACHMENTS_UNAVAILABLE', status: 501 });
+    }
+    return inputs.map((input) => {
+        const artifactId = input.artifactId.trim();
+        if (!artifactId) {
+            throw Object.assign(new Error('Attachment artifactId is required.'), {
+                code: 'INVALID_ATTACHMENT',
+                status: 400,
+            });
+        }
+        const artifact = artifactStore.get(artifactId);
+        if (!artifact) {
+            throw Object.assign(new Error(`Unknown attachment artifact: ${artifactId}`), {
+                code: 'UNKNOWN_ARTIFACT',
+                status: 404,
+            });
+        }
+        return {
+            ...artifact,
+            artifactId: artifact.id,
+            ...(input.label?.trim() ? { label: input.label.trim() } : {}),
+            metadata: {
+                ...artifact.metadata,
+                ...(input.metadata ?? {}),
+            },
+        };
+    });
+}
+export function formatAttachmentSummary(attachments) {
+    if (attachments.length === 0)
+        return '';
+    const lines = attachments.map((attachment, index) => {
+        const name = attachment.label ?? attachment.filename ?? attachment.artifactId;
+        return `${index + 1}. ${name} (${attachment.mimeType}, ${attachment.sizeBytes} bytes, artifact ${attachment.artifactId})`;
+    });
+    return `\n\nAttached file${attachments.length === 1 ? '' : 's'}:\n${lines.join('\n')}`;
+}
+export function buildReplayUserContent(message) {
+    return `${message.content}${formatAttachmentSummary(message.attachments ?? [])}`;
+}
+function isInlineTextAttachment(attachment) {
+    const lower = attachment.mimeType.toLowerCase();
+    return attachment.sizeBytes <= MAX_INLINE_TEXT_ATTACHMENT_BYTES
+        && (lower.startsWith('text/')
+            || lower === 'application/json'
+            || lower === 'application/xml'
+            || lower === 'application/yaml'
+            || lower === 'text/csv');
+}
+function isInlineImageAttachment(attachment) {
+    const lower = attachment.mimeType.toLowerCase();
+    return attachment.sizeBytes <= MAX_INLINE_IMAGE_ATTACHMENT_BYTES
+        && (lower === 'image/png'
+            || lower === 'image/jpeg'
+            || lower === 'image/gif'
+            || lower === 'image/webp');
+}
+export async function buildProviderUserContent(content, attachments, artifactStore) {
+    if (attachments.length === 0)
+        return content;
+    const textSections = [content.trim() ? content : 'Please review the attached file(s).'];
+    const imageParts = [];
+    for (const attachment of attachments) {
+        if (!artifactStore)
+            continue;
+        try {
+            if (isInlineTextAttachment(attachment)) {
+                const { buffer } = await artifactStore.readContent(attachment.artifactId);
+                const text = toNodeBuffer(buffer).toString('utf-8');
+                textSections.push(`\n\n--- Attachment: ${attachment.label ?? attachment.filename ?? attachment.artifactId} ---\n${text}`);
+                continue;
+            }
+            if (isInlineImageAttachment(attachment)) {
+                const { buffer } = await artifactStore.readContent(attachment.artifactId);
+                imageParts.push({
+                    type: 'image',
+                    mediaType: attachment.mimeType,
+                    data: toNodeBuffer(buffer).toString('base64'),
+                });
+            }
+        }
+        catch (error) {
+            logger.warn('[companion-chat] failed to inline attachment for provider prompt', {
+                artifactId: attachment.artifactId,
+                error: summarizeError(error),
+            });
+        }
+    }
+    textSections.push(formatAttachmentSummary(attachments));
+    if (imageParts.length === 0)
+        return textSections.join('');
+    return [{ type: 'text', text: textSections.join('') }, ...imageParts];
+}

package/dist/platform/companion/companion-chat-broker-bridge.d.ts

@@ -0,0 +1,40 @@
+/**
+ * companion-chat-broker-bridge.ts
+ *
+ * The narrow, structural view of the SharedSessionBroker that CompanionChatManager
+ * uses to register companion sessions INTO the one shared session store at write
+ * time (S1 item D: companion registers into the broker). Defined structurally so
+ * the companion package does not take a hard dependency on the control-plane
+ * broker's full surface — the real SharedSessionBroker satisfies this shape.
+ *
+ * Live registration is the fast path (a created/closed companion session is
+ * visible to /api/sessions immediately, same-process); the boot-time importer
+ * fold remains the reconciliation path for files written by other instances.
+ */
+/** Participant identity for a companion session in the shared store. */
+export interface CompanionBrokerParticipant {
+    readonly surfaceKind: 'companion';
+    readonly surfaceId: string;
+    readonly lastSeenAt: number;
+}
+export interface CompanionBrokerRegisterInput {
+    readonly sessionId: string;
+    readonly kind: 'companion-chat';
+    readonly project?: string | undefined;
+    readonly title?: string | undefined;
+    readonly participant: CompanionBrokerParticipant;
+    /** Reopen a closed shared record; companion mirrors its own live state. */
+    readonly reopen?: boolean | undefined;
+}
+/**
+ * Structural subset of SharedSessionBroker. Return types are intentionally
+ * `unknown` — the companion manager fires these for their effect on the store,
+ * not for their result.
+ */
+export interface CompanionSessionBrokerBridge {
+    register(input: CompanionBrokerRegisterInput): Promise<unknown>;
+    closeSession(sessionId: string): Promise<unknown>;
+    /** Hard-remove the mirrored shared-session record (W5-S1: companion delete is a real removal, not a close). */
+    deleteSession(sessionId: string): Promise<unknown>;
+}
+//# sourceMappingURL=companion-chat-broker-bridge.d.ts.map

package/dist/platform/companion/companion-chat-broker-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"companion-chat-broker-bridge.d.ts","sourceRoot":"","sources":["../../../src/platform/companion/companion-chat-broker-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,wEAAwE;AACxE,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAAC;IACjD,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,KAAK,EAAE,4BAA4B,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChE,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,+GAA+G;IAC/G,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpD"}

package/dist/platform/companion/companion-chat-broker-bridge.js

@@ -0,0 +1,14 @@
+/**
+ * companion-chat-broker-bridge.ts
+ *
+ * The narrow, structural view of the SharedSessionBroker that CompanionChatManager
+ * uses to register companion sessions INTO the one shared session store at write
+ * time (S1 item D: companion registers into the broker). Defined structurally so
+ * the companion package does not take a hard dependency on the control-plane
+ * broker's full surface — the real SharedSessionBroker satisfies this shape.
+ *
+ * Live registration is the fast path (a created/closed companion session is
+ * visible to /api/sessions immediately, same-process); the boot-time importer
+ * fold remains the reconciliation path for files written by other instances.
+ */
+export {};

package/dist/platform/companion/companion-chat-broker-sync.d.ts

@@ -0,0 +1,38 @@
+/**
+ * companion-chat-broker-sync.ts
+ *
+ * Owns the live mirror of companion sessions into the shared
+ * `SharedSessionBroker` store (S1 item D: companion registers into the
+ * broker at write time), chaining register/close/delete ops per session so
+ * they never race (order = call order), and exposing `flush()` so the
+ * companion HTTP routes can await in-flight ops before responding
+ * (deterministic for tests).
+ *
+ * Split out of CompanionChatManager (W5-S1) to stay under the repo's
+ * grandfathered line-cap ceiling (see scripts/check-line-cap.ts) — a pure
+ * file-organization move, not a behavior change: same chaining, same
+ * best-effort swallow-and-log-on-failure semantics.
+ */
+import type { CompanionChatSession } from './companion-chat-types.js';
+import type { CompanionSessionBrokerBridge } from './companion-chat-broker-bridge.js';
+export declare class CompanionBrokerSync {
+    private readonly broker;
+    private readonly pendingOps;
+    constructor(broker: CompanionSessionBrokerBridge | null);
+    /**
+     * Await all in-flight best-effort broker-sync operations. The daemon's
+     * companion HTTP routes call this before responding so `/api/sessions`
+     * reflects the change synchronously; tests use it to make the mirror
+     * deterministic. A no-op when no broker bridge is configured.
+     */
+    flush(): Promise<void>;
+    /** Chain a broker op AFTER any prior op for the same session so register and
+     * close/delete never race (order = call order). Best-effort; errors are
+     * swallowed (logged, never thrown into the caller's write path). */
+    track(sessionId: string, run: () => Promise<void>): void;
+    registerSession(meta: CompanionChatSession): Promise<void>;
+    closeSession(sessionId: string): Promise<void>;
+    /** Hard-remove the mirrored shared-session record (W5-S1: companion delete is a real removal). */
+    deleteSession(sessionId: string): Promise<void>;
+}
+//# sourceMappingURL=companion-chat-broker-sync.d.ts.map

package/dist/platform/companion/companion-chat-broker-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"companion-chat-broker-sync.d.ts","sourceRoot":"","sources":["../../../src/platform/companion/companion-chat-broker-sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AAItF,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAC7D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;gBAEnD,MAAM,EAAE,4BAA4B,GAAG,IAAI;IAIvD;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;wEAEoE;IACpE,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IASlD,eAAe,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB1D,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAapD,kGAAkG;IAC5F,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAYtD"}

package/dist/platform/companion/companion-chat-broker-sync.js

@@ -0,0 +1,80 @@
+import { summarizeError } from '../utils/error-display.js';
+import { logger } from '../utils/logger.js';
+export class CompanionBrokerSync {
+    broker;
+    pendingOps = new Map();
+    constructor(broker) {
+        this.broker = broker;
+    }
+    /**
+     * Await all in-flight best-effort broker-sync operations. The daemon's
+     * companion HTTP routes call this before responding so `/api/sessions`
+     * reflects the change synchronously; tests use it to make the mirror
+     * deterministic. A no-op when no broker bridge is configured.
+     */
+    async flush() {
+        await Promise.all([...this.pendingOps.values()]);
+    }
+    /** Chain a broker op AFTER any prior op for the same session so register and
+     * close/delete never race (order = call order). Best-effort; errors are
+     * swallowed (logged, never thrown into the caller's write path). */
+    track(sessionId, run) {
+        if (!this.broker)
+            return;
+        const prior = this.pendingOps.get(sessionId) ?? Promise.resolve();
+        const next = prior.catch(() => { }).then(run).catch(() => { });
+        this.pendingOps.set(sessionId, next.finally(() => {
+            if (this.pendingOps.get(sessionId) === next)
+                this.pendingOps.delete(sessionId);
+        }));
+    }
+    async registerSession(meta) {
+        const broker = this.broker;
+        if (!broker)
+            return;
+        try {
+            await broker.register({
+                sessionId: meta.id,
+                kind: 'companion-chat',
+                project: 'unknown',
+                title: meta.title,
+                participant: { surfaceKind: 'companion', surfaceId: meta.id, lastSeenAt: Date.now() },
+            });
+        }
+        catch (error) {
+            logger.warn('[companion-chat] broker registration failed', {
+                sessionId: meta.id,
+                error: summarizeError(error),
+            });
+        }
+    }
+    async closeSession(sessionId) {
+        const broker = this.broker;
+        if (!broker)
+            return;
+        try {
+            await broker.closeSession(sessionId);
+        }
+        catch (error) {
+            logger.warn('[companion-chat] broker close failed', {
+                sessionId,
+                error: summarizeError(error),
+            });
+        }
+    }
+    /** Hard-remove the mirrored shared-session record (W5-S1: companion delete is a real removal). */
+    async deleteSession(sessionId) {
+        const broker = this.broker;
+        if (!broker)
+            return;
+        try {
+            await broker.deleteSession(sessionId);
+        }
+        catch (error) {
+            logger.warn('[companion-chat] broker delete failed', {
+                sessionId,
+                error: summarizeError(error),
+            });
+        }
+    }
+}

package/dist/platform/companion/companion-chat-gc.d.ts

@@ -0,0 +1,63 @@
+/**
+ * companion-chat-gc.ts
+ *
+ * Pure GC-sweep planning for CompanionChatManager. Kept separate from the
+ * manager so the deletion-authority split (charter: closed sessions are HISTORY)
+ * is expressed as data — one decision per session — and unit-testable without a
+ * live manager or disk.
+ *
+ * Two distinct authorities, deliberately decoupled:
+ *  - MEMORY eviction: cheap and aggressive. After a short grace past `closedAt`
+ *    a closed session's heavy in-memory handles (the ConversationManager replay
+ *    state and message bodies) are dropped so the resident footprint stays
+ *    bounded no matter how much history is on disk. The session META stays in
+ *    the map and remains listable (includeClosed) — only the bodies leave RAM.
+ *  - PERSISTENT deletion: rare and explicit. The on-disk session file is removed
+ *    ONLY when the caller opted into a finite retention window (or, in future, an
+ *    explicit delete verb). The default is `undefined` = retain indefinitely, so
+ *    a closed session is never deleted off disk by the periodic sweep.
+ */
+export type CompanionSweepAction = 
+/** Active session past its idle TTL → close it (GC-initiated close). */
+{
+    readonly kind: 'close-idle';
+}
+/** Closed session past the memory grace → drop bodies from RAM, keep meta. */
+ | {
+    readonly kind: 'evict-memory';
+}
+/** Closed session past an explicit finite retention window → delete off disk. */
+ | {
+    readonly kind: 'delete-persistent';
+}
+/** Nothing to do this sweep. */
+ | {
+    readonly kind: 'retain';
+};
+export interface CompanionSweepSessionView {
+    readonly status: 'active' | 'closed';
+    readonly closedAt: number | null | undefined;
+    /** epoch ms of last activity (idle measured from here for active sessions). */
+    readonly lastActivityAt: number;
+    /** whether the session currently holds message bodies in memory. */
+    readonly hasMessagesInMemory: boolean;
+    /** whether the session is empty (no messages) — selects the idle TTL. */
+    readonly isEmpty: boolean;
+}
+export interface CompanionSweepPolicy {
+    readonly now: number;
+    readonly idleActiveMs: number;
+    readonly idleEmptyMs: number;
+    /**
+     * Age past `closedAt` at which heavy in-memory handles are evicted while meta
+     * stays listable. Bounds resident memory for long-closed history.
+     */
+    readonly closedMemoryGraceMs: number;
+    /**
+     * Age past `closedAt` at which the persisted session file is permanently
+     * deleted. `undefined` = retain indefinitely (never delete via the sweep).
+     */
+    readonly closedRetentionMs: number | undefined;
+}
+export declare function planCompanionSweep(session: CompanionSweepSessionView, policy: CompanionSweepPolicy): CompanionSweepAction;
+//# sourceMappingURL=companion-chat-gc.d.ts.map

package/dist/platform/companion/companion-chat-gc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"companion-chat-gc.d.ts","sourceRoot":"","sources":["../../../src/platform/companion/companion-chat-gc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,MAAM,oBAAoB;AAC9B,wEAAwE;AACtE;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE;AACjC,8EAA8E;GAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE;AACnC,iFAAiF;GAC/E;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;CAAE;AACxC,gCAAgC;GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEhC,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC7C,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,oEAAoE;IACpE,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;CAChD;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,EAClC,MAAM,EAAE,oBAAoB,GAC3B,oBAAoB,CAmBtB"}

package/dist/platform/companion/companion-chat-gc.js

@@ -0,0 +1,38 @@
+/**
+ * companion-chat-gc.ts
+ *
+ * Pure GC-sweep planning for CompanionChatManager. Kept separate from the
+ * manager so the deletion-authority split (charter: closed sessions are HISTORY)
+ * is expressed as data — one decision per session — and unit-testable without a
+ * live manager or disk.
+ *
+ * Two distinct authorities, deliberately decoupled:
+ *  - MEMORY eviction: cheap and aggressive. After a short grace past `closedAt`
+ *    a closed session's heavy in-memory handles (the ConversationManager replay
+ *    state and message bodies) are dropped so the resident footprint stays
+ *    bounded no matter how much history is on disk. The session META stays in
+ *    the map and remains listable (includeClosed) — only the bodies leave RAM.
+ *  - PERSISTENT deletion: rare and explicit. The on-disk session file is removed
+ *    ONLY when the caller opted into a finite retention window (or, in future, an
+ *    explicit delete verb). The default is `undefined` = retain indefinitely, so
+ *    a closed session is never deleted off disk by the periodic sweep.
+ */
+export function planCompanionSweep(session, policy) {
+    if (session.status === 'closed') {
+        const closedAt = session.closedAt ?? policy.now;
+        const closedFor = policy.now - closedAt;
+        // Explicit finite retention is the ONLY authority for persistent deletion.
+        if (policy.closedRetentionMs !== undefined && closedFor >= policy.closedRetentionMs) {
+            return { kind: 'delete-persistent' };
+        }
+        // Otherwise evict heavy handles once past the memory grace, but only if
+        // there is still something resident to evict (idempotent across sweeps).
+        if (closedFor >= policy.closedMemoryGraceMs && session.hasMessagesInMemory) {
+            return { kind: 'evict-memory' };
+        }
+        return { kind: 'retain' };
+    }
+    const idleMs = policy.now - session.lastActivityAt;
+    const ttl = session.isEmpty ? policy.idleEmptyMs : policy.idleActiveMs;
+    return idleMs >= ttl ? { kind: 'close-idle' } : { kind: 'retain' };
+}