studiograph 1.3.46 → 1.3.48-beta.0

package/dist/services/entity-mutations.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Shared payload preparation for `create_entity` / `update_entity` across
+ * the MCP surface ([src/mcp/tools.ts](../mcp/tools.ts)) and the agent surface
+ * ([src/agent/tools/graph-tools.ts](../agent/tools/graph-tools.ts)).
+ *
+ * Owns:
+ *   - Actor identity build (`buildActor`).
+ *   - Base-field auto-stamping for create (`stampCreateBaseFields`).
+ *   - Person.status synonym normalization (`normalizePersonStatus`).
+ *   - Two composers (`prepareCreatePayload`, `prepareUpdatePayload`) that
+ *     return ready-to-pass options for `graph.create` / `graph.update`.
+ *
+ * Does NOT own surface-specific concerns: MCP keeps its allowlist check,
+ * `withAgentActivity` chip wiring, `emitEntityChange` broadcast, and rich
+ * diagnostics; the agent keeps its content sanitiser, workspace dedup
+ * warning, eager-skill permission gate, user_handle bridge checks, and
+ * `onMutation` / `onAgentActivity` callbacks.
+ *
+ * Errors from `graph.update` — including `LiveEditorPendingError` from the
+ * Phase 2 server-write live-typing guard — propagate through the composers
+ * unchanged; callers map them to their surface's error format.
+ */
+import type { AuthUser } from './auth-service.js';
+import type { GitUser } from './git.js';
+import type { CreateEntityOptions, UpdateEntityOptions, EntityFile } from '../core/graph.js';
+import type { EntityType } from '../core/validation.js';
+import type { BodyWriteResult } from '../server/body-write-coordinator.js';
+/**
+ * Person.status accepts only `current` | `former` per PersonSchema, but
+ * real-world payloads from external agents carry many synonyms. Map them
+ * to canonical before validation rejects the call. Unknown values fall
+ * through unchanged so validation surfaces them loudly.
+ *
+ * On create: defaults missing status to `current`.
+ * On update: only normalises when status is supplied — don't fabricate a
+ * field the caller didn't ask to change.
+ */
+export declare const PERSON_STATUS_ALIASES: Record<string, 'current' | 'former'>;
+/**
+ * Build the git-author / audit-trail identity for an authenticated session.
+ * `handle` is the canonical id stamped into `created_by` / `updated_by` and
+ * used as the git author; falls back to `user-<id>` if a token from before
+ * the handle backfill is still in use.
+ *
+ * Surfaces that may run without an authenticated user (CLI, server-only
+ * automations, tests) should keep their existing orchestrator `GitUser` and
+ * pass it directly to the composers — `buildActor` requires an `AuthUser`.
+ */
+export declare function buildActor(user: AuthUser): GitUser;
+/**
+ * EntityBaseSchema requires entity_id, created_at, updated_at, created_by,
+ * and updated_by. External callers (Claude Desktop, Cursor, the agent)
+ * typically pass only type-specific data plus the top-level entity_id, so
+ * the helper seeds the rest rather than forcing every caller to know the
+ * convention. Caller-supplied values for created_at / created_by / etc.
+ * win; entity_id is always overwritten to match the top-level arg (it is
+ * the lookup key and cannot diverge from the filename).
+ */
+export declare function stampCreateBaseFields(data: Record<string, unknown>, entityId: string, actorHandle: string): Record<string, unknown>;
+export declare function normalizePersonStatus(data: Record<string, unknown>, isCreate: boolean): Record<string, unknown>;
+export interface PrepareCreateInput {
+    entityType: EntityType;
+    entityId: string;
+    data: Record<string, unknown>;
+    content?: string;
+    folderPath?: string;
+    commitMessage?: string;
+}
+/**
+ * Compose the options for `graph.create`. Stamps base fields, mirrors
+ * `entity_id` from the top-level arg into frontmatter, normalises
+ * `person.status` synonyms, and threads the actor through as the git
+ * commit author. The caller still owns access checks, allowlist
+ * enforcement, content sanitisation, and broadcast/chip wiring.
+ */
+export declare function prepareCreatePayload(input: PrepareCreateInput, actor: GitUser): CreateEntityOptions;
+export interface PrepareUpdateInput {
+    entityType: EntityType;
+    entityId: string;
+    data?: Record<string, unknown>;
+    content?: string;
+    commitMessage?: string;
+}
+/**
+ * Compose the options for `graph.update`. Mirrors `entity_id` from the
+ * top-level arg into frontmatter (defensive against callers that pass a
+ * disagreeing value), normalises `person.status` synonyms when status is
+ * supplied, and declares `source: 'server-write'` whenever content is
+ * present so the body-write path engages the per-doc lock + live-editor
+ * guard. `graph.update` re-stamps `updated_at` / `updated_by` itself.
+ */
+export declare function prepareUpdatePayload(input: PrepareUpdateInput, actor: GitUser): UpdateEntityOptions;
+/**
+ * Thrown when an update wrote but produced no on-disk diff despite the
+ * caller intending a change — i.e. the validator dropped unknown fields or
+ * the supplied content matched the existing body. Carries the entity coords
+ * and which inputs were ignored so callers can map it to their surface's
+ * failure envelope (MCP `fail`, agent `{ success: false }`).
+ */
+export declare class SilentDropError extends Error {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly dropped: string[];
+    constructor(entityType: string, entityId: string, dropped: string[]);
+}
+/**
+ * Thrown when a whole-body `update_entity` would remove embedded asset
+ * references (image/attachment embeds: `![[Foo.png]]` transclusions or
+ * `![alt](/api/assets/…)` markdown images) that are present in the entity's
+ * CURRENT body but absent from the submitted content.
+ *
+ * This is the guard for the silent-image-loss incident: `get_entity` reads
+ * the last-persisted disk body, which can lag the live editor (a user's
+ * freshly-placed image lives in the Y.Doc before autosave commits it). An
+ * agent that fetched stale content, edited text, and resent the whole body
+ * would drop those embeds — and because asset binaries live outside git,
+ * the lost references aren't recoverable from history. We refuse the write
+ * (no disk mutation happens) unless the caller explicitly opts in.
+ *
+ * Carries the dropped references so callers can map it to their surface's
+ * conflict envelope and tell the agent exactly what to preserve.
+ */
+export declare class DroppedAssetError extends Error {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly dropped: string[];
+    constructor(entityType: string, entityId: string, dropped: string[]);
+}
+/** Minimal graph surface diagnosedUpdate needs. */
+export interface DiagnosedUpdateGraph {
+    get(entityType: EntityType, entityId: string): EntityFile;
+    update(options: UpdateEntityOptions): Promise<EntityFile>;
+    /** Live editor body when a seeded Y.Doc is open, else null. Optional so
+     *  coordinator-less test/CLI graphs satisfy the interface; the asset-drop
+     *  guard falls back to the on-disk body when it's absent. */
+    getLiveBody?(entityType: EntityType, entityId: string): string | null;
+}
+export interface DiagnosedUpdateResult {
+    entity: EntityFile;
+    frontmatter_changed: boolean;
+    content_changed: boolean;
+    noop: boolean;
+    /** Post-commit broadcast disposition (null on the non-coordinator path). */
+    broadcast: BodyWriteResult['broadcast'] | null;
+}
+/**
+ * Run graph.update with the c6ef9297 diagnostic contract: snapshot before,
+ * update, then report whether frontmatter / content actually changed.
+ * Throws {@link SilentDropError} when the caller intended a change that
+ * produced no diff. Captures the body-write broadcast disposition.
+ *
+ * `inputs` are the caller's RAW intent (pre-payload-prep) — used only to
+ * decide whether a no-op was actually a silent drop. graph.get may throw
+ * (entity not found); callers' existing try/catch surfaces it.
+ */
+export declare function diagnosedUpdate(graph: DiagnosedUpdateGraph, options: UpdateEntityOptions, inputs: {
+    data?: Record<string, unknown>;
+    content?: string;
+}, guard?: {
+    allowAssetRemoval?: boolean;
+}): Promise<DiagnosedUpdateResult>;

package/dist/services/entity-mutations.js

@@ -0,0 +1,296 @@
+/**
+ * Shared payload preparation for `create_entity` / `update_entity` across
+ * the MCP surface ([src/mcp/tools.ts](../mcp/tools.ts)) and the agent surface
+ * ([src/agent/tools/graph-tools.ts](../agent/tools/graph-tools.ts)).
+ *
+ * Owns:
+ *   - Actor identity build (`buildActor`).
+ *   - Base-field auto-stamping for create (`stampCreateBaseFields`).
+ *   - Person.status synonym normalization (`normalizePersonStatus`).
+ *   - Two composers (`prepareCreatePayload`, `prepareUpdatePayload`) that
+ *     return ready-to-pass options for `graph.create` / `graph.update`.
+ *
+ * Does NOT own surface-specific concerns: MCP keeps its allowlist check,
+ * `withAgentActivity` chip wiring, `emitEntityChange` broadcast, and rich
+ * diagnostics; the agent keeps its content sanitiser, workspace dedup
+ * warning, eager-skill permission gate, user_handle bridge checks, and
+ * `onMutation` / `onAgentActivity` callbacks.
+ *
+ * Errors from `graph.update` — including `LiveEditorPendingError` from the
+ * Phase 2 server-write live-typing guard — propagate through the composers
+ * unchanged; callers map them to their surface's error format.
+ */
+import { droppedAssetEmbeds } from '../core/embeds.js';
+/**
+ * Person.status accepts only `current` | `former` per PersonSchema, but
+ * real-world payloads from external agents carry many synonyms. Map them
+ * to canonical before validation rejects the call. Unknown values fall
+ * through unchanged so validation surfaces them loudly.
+ *
+ * On create: defaults missing status to `current`.
+ * On update: only normalises when status is supplied — don't fabricate a
+ * field the caller didn't ask to change.
+ */
+export const PERSON_STATUS_ALIASES = {
+    current: 'current',
+    active: 'current',
+    prospective: 'current',
+    'prospective-contact': 'current',
+    'current-contact': 'current',
+    former: 'former',
+    'former-contact': 'former',
+    inactive: 'former',
+    past: 'former',
+};
+/**
+ * Build the git-author / audit-trail identity for an authenticated session.
+ * `handle` is the canonical id stamped into `created_by` / `updated_by` and
+ * used as the git author; falls back to `user-<id>` if a token from before
+ * the handle backfill is still in use.
+ *
+ * Surfaces that may run without an authenticated user (CLI, server-only
+ * automations, tests) should keep their existing orchestrator `GitUser` and
+ * pass it directly to the composers — `buildActor` requires an `AuthUser`.
+ */
+export function buildActor(user) {
+    const handle = user.handle || `user-${user.id}`;
+    return {
+        id: handle,
+        name: user.displayName || handle,
+        email: `${handle}@studiograph.local`,
+    };
+}
+/**
+ * EntityBaseSchema requires entity_id, created_at, updated_at, created_by,
+ * and updated_by. External callers (Claude Desktop, Cursor, the agent)
+ * typically pass only type-specific data plus the top-level entity_id, so
+ * the helper seeds the rest rather than forcing every caller to know the
+ * convention. Caller-supplied values for created_at / created_by / etc.
+ * win; entity_id is always overwritten to match the top-level arg (it is
+ * the lookup key and cannot diverge from the filename).
+ */
+export function stampCreateBaseFields(data, entityId, actorHandle) {
+    const now = new Date().toISOString();
+    return {
+        created_at: now,
+        updated_at: now,
+        created_by: actorHandle,
+        updated_by: actorHandle,
+        ...data,
+        entity_id: entityId,
+    };
+}
+export function normalizePersonStatus(data, isCreate) {
+    const raw = data.status;
+    if (raw === undefined || raw === null || raw === '') {
+        return isCreate ? { ...data, status: 'current' } : data;
+    }
+    if (typeof raw !== 'string')
+        return data;
+    const mapped = PERSON_STATUS_ALIASES[raw.toLowerCase()];
+    if (!mapped || mapped === raw)
+        return data;
+    return { ...data, status: mapped };
+}
+/**
+ * Compose the options for `graph.create`. Stamps base fields, mirrors
+ * `entity_id` from the top-level arg into frontmatter, normalises
+ * `person.status` synonyms, and threads the actor through as the git
+ * commit author. The caller still owns access checks, allowlist
+ * enforcement, content sanitisation, and broadcast/chip wiring.
+ */
+export function prepareCreatePayload(input, actor) {
+    let data = stampCreateBaseFields(input.data, input.entityId, actor.id);
+    if (input.entityType === 'person') {
+        data = normalizePersonStatus(data, true);
+    }
+    return {
+        entityType: input.entityType,
+        entityId: input.entityId,
+        data: data,
+        content: input.content,
+        folderPath: input.folderPath,
+        commitMessage: input.commitMessage,
+        user: actor,
+    };
+}
+/**
+ * Compose the options for `graph.update`. Mirrors `entity_id` from the
+ * top-level arg into frontmatter (defensive against callers that pass a
+ * disagreeing value), normalises `person.status` synonyms when status is
+ * supplied, and declares `source: 'server-write'` whenever content is
+ * present so the body-write path engages the per-doc lock + live-editor
+ * guard. `graph.update` re-stamps `updated_at` / `updated_by` itself.
+ */
+export function prepareUpdatePayload(input, actor) {
+    let mergedData;
+    if (input.data !== undefined) {
+        mergedData = { ...input.data, entity_id: input.entityId };
+        if (input.entityType === 'person') {
+            mergedData = normalizePersonStatus(mergedData, false);
+        }
+    }
+    return {
+        entityType: input.entityType,
+        entityId: input.entityId,
+        data: mergedData,
+        content: input.content,
+        source: input.content !== undefined ? 'server-write' : undefined,
+        commitMessage: input.commitMessage,
+        user: actor,
+    };
+}
+// ── Diagnosed update ─────────────────────────────────────────────────────
+//
+// commit c6ef9297 hardened MCP update_entity so an agent isn't misled by a
+// success envelope when the validator silently drops fields or the supplied
+// content matches the existing body. That guard lived only in the MCP
+// surface; the internal agent tool returned a generic success message.
+// Both surfaces now route through diagnosedUpdate so the contract is
+// surface-independent.
+/** Fields graph.update stamps on every call — they mutate even on a
+ *  content-only update, so they're excluded from the semantic diff that
+ *  decides "did the caller's intent actually land?" */
+const AUTO_STAMPED_FIELDS = new Set(['updated_at', 'updated_by']);
+function semanticFrontmatter(data) {
+    return Object.fromEntries(Object.entries(data).filter(([k]) => !AUTO_STAMPED_FIELDS.has(k)));
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== 'object')
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a)) {
+        const bArr = b;
+        if (a.length !== bArr.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, bArr[i]));
+    }
+    const aObj = a;
+    const bObj = b;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every(k => deepEqual(aObj[k], bObj[k]));
+}
+/**
+ * Thrown when an update wrote but produced no on-disk diff despite the
+ * caller intending a change — i.e. the validator dropped unknown fields or
+ * the supplied content matched the existing body. Carries the entity coords
+ * and which inputs were ignored so callers can map it to their surface's
+ * failure envelope (MCP `fail`, agent `{ success: false }`).
+ */
+export class SilentDropError extends Error {
+    entityType;
+    entityId;
+    dropped;
+    constructor(entityType, entityId, dropped) {
+        super(`update_entity wrote to ${entityType}/${entityId} but the file is byte-identical to its prior state. ` +
+            `Inputs that did not produce a diff: ${dropped.join(', ')}. ` +
+            `This usually means the schema validator silently dropped unknown fields or the supplied content matched the existing body.`);
+        this.entityType = entityType;
+        this.entityId = entityId;
+        this.dropped = dropped;
+        this.name = 'SilentDropError';
+    }
+}
+/**
+ * Thrown when a whole-body `update_entity` would remove embedded asset
+ * references (image/attachment embeds: `![[Foo.png]]` transclusions or
+ * `![alt](/api/assets/…)` markdown images) that are present in the entity's
+ * CURRENT body but absent from the submitted content.
+ *
+ * This is the guard for the silent-image-loss incident: `get_entity` reads
+ * the last-persisted disk body, which can lag the live editor (a user's
+ * freshly-placed image lives in the Y.Doc before autosave commits it). An
+ * agent that fetched stale content, edited text, and resent the whole body
+ * would drop those embeds — and because asset binaries live outside git,
+ * the lost references aren't recoverable from history. We refuse the write
+ * (no disk mutation happens) unless the caller explicitly opts in.
+ *
+ * Carries the dropped references so callers can map it to their surface's
+ * conflict envelope and tell the agent exactly what to preserve.
+ */
+export class DroppedAssetError extends Error {
+    entityType;
+    entityId;
+    dropped;
+    constructor(entityType, entityId, dropped) {
+        super(`update_entity would remove ${dropped.length} embedded asset reference(s) from ${entityType}/${entityId} ` +
+            `that are present in the current document but missing from the submitted body: ${dropped.join(', ')}. ` +
+            `Whole-body writes replace the entire body, so these images/attachments would be unlinked — and asset binaries ` +
+            `are not versioned in git, so the references cannot be recovered from history. ` +
+            `Re-fetch the entry with get_entity (which now returns live editor content), keep the embed lines you didn't ` +
+            `mean to touch, and resubmit. To delete them deliberately, set allow_image_removal: true (MCP) / ` +
+            `allowImageRemoval: true (agent). For small text edits like renaming a heading, prefer patch_entity, which ` +
+            `never rewrites the whole body.`);
+        this.entityType = entityType;
+        this.entityId = entityId;
+        this.dropped = dropped;
+        this.name = 'DroppedAssetError';
+    }
+}
+/**
+ * Run graph.update with the c6ef9297 diagnostic contract: snapshot before,
+ * update, then report whether frontmatter / content actually changed.
+ * Throws {@link SilentDropError} when the caller intended a change that
+ * produced no diff. Captures the body-write broadcast disposition.
+ *
+ * `inputs` are the caller's RAW intent (pre-payload-prep) — used only to
+ * decide whether a no-op was actually a silent drop. graph.get may throw
+ * (entity not found); callers' existing try/catch surfaces it.
+ */
+export async function diagnosedUpdate(graph, options, inputs, guard) {
+    const before = graph.get(options.entityType, options.entityId);
+    const beforeFrontmatter = semanticFrontmatter(before.data);
+    const beforeContent = before.document.content;
+    // Asset-drop guard (pre-write — nothing is mutated if this throws). A
+    // whole-body content rewrite must not silently drop image/attachment
+    // embeds that the CURRENT document carries. "Current" prefers the live
+    // editor body over disk: the user's freshly-placed image may be in the
+    // Y.Doc but not yet committed, and `before` (disk) wouldn't show it. The
+    // live-editor write guard (LiveEditorPendingError) only fires when a
+    // client is connected; this catches the closed-tab / evicted-doc case and
+    // the agent-edited-stale-content case that produced the incident.
+    if (options.content !== undefined && !guard?.allowAssetRemoval) {
+        const currentBody = graph.getLiveBody?.(options.entityType, options.entityId) ?? beforeContent;
+        const dropped = droppedAssetEmbeds(currentBody, options.content);
+        if (dropped.length > 0) {
+            throw new DroppedAssetError(options.entityType, options.entityId, dropped);
+        }
+    }
+    let broadcast = null;
+    options.onBroadcast = (b) => { broadcast = b; };
+    const entity = await graph.update(options);
+    const afterFrontmatter = semanticFrontmatter(entity.data);
+    const afterContent = entity.document.content;
+    const frontmatter_changed = !deepEqual(beforeFrontmatter, afterFrontmatter);
+    const content_changed = beforeContent !== afterContent;
+    const noop = !frontmatter_changed && !content_changed;
+    if (noop) {
+        const intendedDataChange = inputs.data !== undefined &&
+            Object.keys(inputs.data).some(k => {
+                if (AUTO_STAMPED_FIELDS.has(k))
+                    return false;
+                return !deepEqual(inputs.data[k], before.data[k]);
+            });
+        const intendedContentChange = inputs.content !== undefined && inputs.content !== beforeContent;
+        if (intendedDataChange || intendedContentChange) {
+            const dropped = [];
+            if (intendedDataChange)
+                dropped.push('data');
+            if (intendedContentChange)
+                dropped.push('content');
+            throw new SilentDropError(entity.entityType, entity.id, dropped);
+        }
+    }
+    return { entity, frontmatter_changed, content_changed, noop, broadcast };
+}
+//# sourceMappingURL=entity-mutations.js.map

package/dist/services/entity-mutations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-mutations.js","sourceRoot":"","sources":["../../src/services/entity-mutations.ts"],"names":[],"mappings":"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"}

package/dist/services/event-processor.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Event Processor — source-agnostic event capture processing
+ *
+ * Accepts a common MeetingPayload from any capture source (desktop client,
+ * external integrations, calendar, manual) and writes an `event` entity
+ * with `type: meeting` (the default). Handles:
+ * 1. Entity creation with proper frontmatter
+ * 2. Participant resolution to existing person entities
+ * 3. LLM-powered summary generation from transcript
+ * 4. Structured extraction (action items, decisions)
+ * 5. Task entity creation from action items
+ * 6. Body template population
+ *
+ * Today the only event capture surface is meeting recording, so the
+ * payload type is still MeetingPayload — generalizing the payload shape
+ * is a follow-up when/if other event sources land.
+ */
+import type { WorkspaceManager } from '../core/workspace-manager.js';
+import type { WsHub } from '../server/ws-hub.js';
+import type { YjsManager } from '../server/yjs-manager.js';
+import type { GitUser } from './git.js';
+export interface MeetingPayload {
+    /** Unique ID from the source (e.g., desktop session ID, calendar event ID) */
+    sourceId: string;
+    /** Source identifier: 'desktop-client', 'calendar', 'manual', or an integration ID */
+    source: string;
+    /** Meeting title */
+    title: string;
+    /** ISO datetime when the meeting started */
+    startedAt: string;
+    /** ISO datetime when the meeting ended */
+    endedAt?: string;
+    /** Duration in minutes */
+    durationMinutes?: number;
+    /** Participants */
+    participants: MeetingParticipant[];
+    /** Transcript segments (if available) */
+    transcript?: TranscriptSegment[];
+    /** Raw transcript as text (alternative to segments) */
+    transcriptText?: string;
+    /** User-written memo/notes */
+    memo?: string;
+    /** Meeting platform (e.g., 'google-meet', 'zoom', 'teams') */
+    platform?: string;
+    /** Meeting URL */
+    meetingUrl?: string;
+    /** Pre-generated summary (some sources provide their own) */
+    existingSummary?: string;
+    /** Additional metadata from the source */
+    metadata?: Record<string, any>;
+}
+export interface MeetingParticipant {
+    name: string;
+    email?: string;
+    isSelf?: boolean;
+}
+export interface TranscriptSegment {
+    speaker: string;
+    text: string;
+    timestamp: number;
+    isFinal?: boolean;
+    channel?: 'mic' | 'tab';
+}
+export interface ProcessingResult {
+    entityId: string;
+    repo: string;
+    url: string;
+    attendeeLinks: string[];
+    extractionPending: boolean;
+    tasksCreated: string[];
+}
+export declare class EventProcessor {
+    private workspaceManager;
+    private wsHub?;
+    private yjsManager?;
+    constructor(workspaceManager: WorkspaceManager, wsHub?: WsHub | undefined, yjsManager?: YjsManager | undefined);
+    /**
+     * Process a meeting payload: create entity, resolve participants,
+     * generate summary asynchronously.
+     */
+    process(payload: MeetingPayload, repo: string, user?: GitUser): Promise<ProcessingResult>;
+    /**
+     * Process a meeting for an entity that already exists (created by the web app).
+     * Meeting capture UI flow: entity was created when recording started,
+     * user typed notes in it, now we add the transcript and generate the summary.
+     */
+    processExisting(payload: MeetingPayload, repo: string, existingEntityId: string, user?: GitUser): Promise<ProcessingResult>;
+    /**
+     * Async processing: LLM summary, extraction, task creation
+     */
+    private processAsync;
+    /**
+     * Create a task entity from an action item string, linked to the event.
+     */
+    private createTask;
+    private generateEntityId;
+    resolveParticipants(participants: MeetingParticipant[], repo: string): Promise<string[]>;
+    private formatTranscript;
+    private generateSummary;
+    private extractStructuredData;
+    private getModelConfig;
+    private broadcast;
+    private slugify;
+}