@pellux/goodvibes-sdk 0.38.0 → 1.1.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-branching.d.ts

@@ -0,0 +1,66 @@
+/**
+ * companion-chat-branching.ts
+ *
+ * The honest-lineage core for the two conversation-forking operations the chat
+ * web UI needs: regenerate a response, and edit an earlier message and branch
+ * from it. Split out of companion-chat-manager.ts (see CHANGELOG) so the manager
+ * stays under the hand-authored file-size cap.
+ *
+ * THE HONESTY CONTRACT (this is the whole point of the module):
+ * neither operation ever deletes or overwrites message history. A regenerate or
+ * an edit marks the affected messages as SUPERSEDED — they stay in the message
+ * list and on disk, flagged with `supersededAt`/`supersededReason` — and then a
+ * fresh turn runs from the fork point. The "active" conversation is the chain of
+ * messages WITHOUT a `supersededAt`; everything behind a fork remains
+ * retrievable. Nothing is silently lost, mirroring the delete-means-delete
+ * discipline: a regenerate is a new turn, an edit is a new branch, and the old
+ * branch is kept as visible history rather than thrown away.
+ *
+ * These functions mutate the passed session's `messages` array in place and
+ * return a plan; the caller (the manager) is responsible for rebuilding the
+ * LLM-facing conversation from the active chain, persisting, and running the new
+ * turn. Errors are thrown with `{ code, status }` so the route layer maps them
+ * to honest machine codes.
+ */
+import type { CompanionChatMessage, EditCompanionChatMessageInput } from './companion-chat-types.js';
+import { type CompanionChatArtifactStore } from './companion-chat-attachments.js';
+/** The mutable session shape these helpers operate on (subset of the manager's InternalSession). */
+export interface BranchingSession {
+    messages: CompanionChatMessage[];
+    lastActivityAt: number;
+}
+/** The active (non-superseded) messages, in order — the live conversation chain. */
+export declare function activeMessages(messages: readonly CompanionChatMessage[]): CompanionChatMessage[];
+export interface RegeneratePlan {
+    readonly regeneratedFrom: string;
+    readonly supersededMessageIds: readonly string[];
+    /** The user message the re-run turn is anchored on. */
+    readonly anchorUserMessageId: string;
+}
+/**
+ * Plan a regenerate: pick the target assistant message (an explicit id, or the
+ * latest active assistant message), supersede it and everything after it, and
+ * return the preceding active user message as the anchor for the new turn.
+ *
+ * Throws when the session has no assistant message to regenerate, when an
+ * explicit id is unknown or is not an active assistant message, or when there is
+ * no user message preceding the target to re-run from.
+ */
+export declare function planRegenerate(session: BranchingSession, targetMessageId: string | undefined, now: number): RegeneratePlan;
+export interface EditBranchPlan {
+    readonly editedFrom: string;
+    readonly newMessageId: string;
+    readonly supersededMessageIds: readonly string[];
+}
+/**
+ * Apply an edit-and-branch: the target must be an active user message. It and
+ * everything after it are superseded (retained), then a new user message with
+ * the edited content — carrying `revisionOf` back to the original — is appended.
+ * The caller then rebuilds the conversation from the active chain and runs a
+ * turn.
+ *
+ * Throws when the target id is unknown, is not a user message, is already
+ * superseded history, or the edited message has neither content nor attachments.
+ */
+export declare function applyEditBranch(session: BranchingSession, sessionId: string, input: EditCompanionChatMessageInput, artifactStore: CompanionChatArtifactStore | null, now: number): EditBranchPlan;
+//# sourceMappingURL=companion-chat-branching.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"companion-chat-branching.d.ts","sourceRoot":"","sources":["../../../src/platform/companion/companion-chat-branching.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EACV,oBAAoB,EAEpB,6BAA6B,EAC9B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,iCAAiC,CAAC;AAEzC,oGAAoG;AACpG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC,cAAc,EAAE,MAAM,CAAC;CACxB;AAwBD,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,GAAG,oBAAoB,EAAE,CAEhG;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,uDAAuD;IACvD,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,gBAAgB,EACzB,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,GAAG,EAAE,MAAM,GACV,cAAc,CA4DhB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;CAClD;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,gBAAgB,EACzB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,6BAA6B,EACpC,aAAa,EAAE,0BAA0B,GAAG,IAAI,EAChD,GAAG,EAAE,MAAM,GACV,cAAc,CAwChB"}

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

@@ -0,0 +1,142 @@
+/**
+ * companion-chat-branching.ts
+ *
+ * The honest-lineage core for the two conversation-forking operations the chat
+ * web UI needs: regenerate a response, and edit an earlier message and branch
+ * from it. Split out of companion-chat-manager.ts (see CHANGELOG) so the manager
+ * stays under the hand-authored file-size cap.
+ *
+ * THE HONESTY CONTRACT (this is the whole point of the module):
+ * neither operation ever deletes or overwrites message history. A regenerate or
+ * an edit marks the affected messages as SUPERSEDED — they stay in the message
+ * list and on disk, flagged with `supersededAt`/`supersededReason` — and then a
+ * fresh turn runs from the fork point. The "active" conversation is the chain of
+ * messages WITHOUT a `supersededAt`; everything behind a fork remains
+ * retrievable. Nothing is silently lost, mirroring the delete-means-delete
+ * discipline: a regenerate is a new turn, an edit is a new branch, and the old
+ * branch is kept as visible history rather than thrown away.
+ *
+ * These functions mutate the passed session's `messages` array in place and
+ * return a plan; the caller (the manager) is responsible for rebuilding the
+ * LLM-facing conversation from the active chain, persisting, and running the new
+ * turn. Errors are thrown with `{ code, status }` so the route layer maps them
+ * to honest machine codes.
+ */
+import { randomUUID } from 'node:crypto';
+import { resolveAttachments, } from './companion-chat-attachments.js';
+/** Build a `{ code, status }`-carrying error the route layer turns into a machine code. */
+function branchError(message, code, status) {
+    return Object.assign(new Error(message), { code, status });
+}
+/** Mark messages[fromIndex..] as superseded in place, returning the ids touched. */
+function supersedeFrom(session, fromIndex, reason, now) {
+    const superseded = [];
+    for (let i = fromIndex; i < session.messages.length; i++) {
+        const msg = session.messages[i];
+        if (msg.supersededAt !== undefined)
+            continue; // already retained history — leave as-is
+        session.messages[i] = { ...msg, supersededAt: now, supersededReason: reason };
+        superseded.push(msg.id);
+    }
+    return superseded;
+}
+/** The active (non-superseded) messages, in order — the live conversation chain. */
+export function activeMessages(messages) {
+    return messages.filter((m) => m.supersededAt === undefined);
+}
+/**
+ * Plan a regenerate: pick the target assistant message (an explicit id, or the
+ * latest active assistant message), supersede it and everything after it, and
+ * return the preceding active user message as the anchor for the new turn.
+ *
+ * Throws when the session has no assistant message to regenerate, when an
+ * explicit id is unknown or is not an active assistant message, or when there is
+ * no user message preceding the target to re-run from.
+ */
+export function planRegenerate(session, targetMessageId, now) {
+    const messages = session.messages;
+    let targetIndex;
+    if (targetMessageId !== undefined) {
+        targetIndex = messages.findIndex((m) => m.id === targetMessageId);
+        if (targetIndex === -1) {
+            throw branchError(`Message not found: ${targetMessageId}`, 'MESSAGE_NOT_FOUND', 404);
+        }
+        const target = messages[targetIndex];
+        if (target.supersededAt !== undefined) {
+            throw branchError('That message is already superseded history; regenerate the active response instead.', 'MESSAGE_SUPERSEDED', 409);
+        }
+        if (target.role !== 'assistant') {
+            throw branchError('Only an assistant message can be regenerated; edit a user message to branch instead.', 'NOT_AN_ASSISTANT_MESSAGE', 400);
+        }
+    }
+    else {
+        targetIndex = -1;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const m = messages[i];
+            if (m.supersededAt === undefined && m.role === 'assistant') {
+                targetIndex = i;
+                break;
+            }
+        }
+        if (targetIndex === -1) {
+            throw branchError('No assistant response to regenerate.', 'NO_ASSISTANT_MESSAGE', 409);
+        }
+    }
+    const regeneratedFrom = messages[targetIndex].id;
+    // The anchor is the nearest active user message before the target assistant.
+    let anchorUserMessageId = null;
+    for (let i = targetIndex - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.supersededAt === undefined && m.role === 'user') {
+            anchorUserMessageId = m.id;
+            break;
+        }
+    }
+    if (anchorUserMessageId === null) {
+        throw branchError('No user message precedes that response to regenerate from.', 'NO_ANCHOR_MESSAGE', 409);
+    }
+    const supersededMessageIds = supersedeFrom(session, targetIndex, 'regenerate', now);
+    session.lastActivityAt = now;
+    return { regeneratedFrom, supersededMessageIds, anchorUserMessageId };
+}
+/**
+ * Apply an edit-and-branch: the target must be an active user message. It and
+ * everything after it are superseded (retained), then a new user message with
+ * the edited content — carrying `revisionOf` back to the original — is appended.
+ * The caller then rebuilds the conversation from the active chain and runs a
+ * turn.
+ *
+ * Throws when the target id is unknown, is not a user message, is already
+ * superseded history, or the edited message has neither content nor attachments.
+ */
+export function applyEditBranch(session, sessionId, input, artifactStore, now) {
+    const attachments = resolveAttachments(input.attachments ?? [], artifactStore);
+    if (!input.content.trim() && attachments.length === 0) {
+        throw branchError('content or attachments are required', 'INVALID_INPUT', 400);
+    }
+    const targetIndex = session.messages.findIndex((m) => m.id === input.messageId);
+    if (targetIndex === -1) {
+        throw branchError(`Message not found: ${input.messageId}`, 'MESSAGE_NOT_FOUND', 404);
+    }
+    const target = session.messages[targetIndex];
+    if (target.supersededAt !== undefined) {
+        throw branchError('That message is already superseded history; edit the active message instead.', 'MESSAGE_SUPERSEDED', 409);
+    }
+    if (target.role !== 'user') {
+        throw branchError('Only a user message can be edited and branched from.', 'NOT_A_USER_MESSAGE', 400);
+    }
+    const supersededMessageIds = supersedeFrom(session, targetIndex, 'edit', now);
+    const replacement = {
+        id: randomUUID(),
+        sessionId,
+        role: 'user',
+        content: input.content,
+        attachments,
+        ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+        createdAt: now,
+        revisionOf: input.messageId,
+    };
+    session.messages.push(replacement);
+    session.lastActivityAt = now;
+    return { editedFrom: input.messageId, newMessageId: replacement.id, supersededMessageIds };
+}

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 (see CHANGELOG 1.0.0: 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,6HAA6H;IAC7H,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 {};