neondeck 1.0.0-beta.4

package/src/modules/sessions/active-session.ts

@@ -0,0 +1,46 @@
+import { openDb } from '../../lib/sqlite';
+import {
+  type RuntimePaths,
+  ensureRuntimeHome,
+  runtimePaths,
+} from '../../runtime-home';
+import type { NeonSessionState } from './schemas';
+import { readActiveChatSession, readChatSessionRow } from './store';
+
+export async function readNeonSessionState(
+  paths: RuntimePaths = runtimePaths(),
+  surface = 'dashboard',
+): Promise<NeonSessionState> {
+  await ensureRuntimeHome(paths);
+  const database = openDb(paths.neondeckDatabase);
+
+  try {
+    const active = readActiveChatSession(database, surface);
+    const sessions = database
+      .prepare(
+        `
+        SELECT *
+        FROM chat_sessions
+        WHERE agent_name = 'display-assistant'
+        ORDER BY pinned DESC, archived_at IS NULL DESC, last_active_at DESC, created_at DESC
+        LIMIT 30;
+      `,
+      )
+      .all()
+      .map((row) => readChatSessionRow(row, database));
+
+    return {
+      ok: true,
+      action: 'session_status',
+      activeChatSession: active,
+      activeSessionId: active.id,
+      surface,
+      stale: active.staleReasons.length > 0,
+      staleReasons: active.staleReasons,
+      sessions,
+      fetchedAt: new Date().toISOString(),
+    };
+  } finally {
+    database.close();
+  }
+}

package/src/modules/sessions/agent-context.ts

@@ -0,0 +1,146 @@
+import { openDb } from '../../lib/sqlite';
+import {
+  ensureRuntimeHomeSync,
+  runtimePaths,
+  type RuntimePaths,
+} from '../../runtime-home';
+import { buildMemoryPromptSnapshotSync } from '../memory';
+import {
+  findChatSession,
+  markLoadedMemoriesUsed,
+  recordSessionAudit,
+} from './store';
+import type { ChatSessionRecord } from './schemas';
+
+const contextAuditActions = [
+  'create',
+  'reuse-linked',
+  'link_context',
+  'summary_refresh',
+];
+
+export function sessionContextInstructionsForAgentSync(
+  sessionId: string | undefined,
+  paths: RuntimePaths = runtimePaths(),
+) {
+  if (!sessionId) return '';
+  ensureRuntimeHomeSync(paths);
+  const database = openDb(paths.neondeckDatabase);
+
+  try {
+    const session = findChatSession(database, sessionId);
+    const instructions = linkedSessionContextInstructions(session);
+    if (!session || !instructions) return '';
+
+    const latestContextChangeAt = latestContextAuditAt(database, sessionId);
+    if (contextNeedsRefresh(session, latestContextChangeAt)) {
+      const now = new Date().toISOString();
+      const memorySnapshot = buildMemoryPromptSnapshotSync(paths, {
+        repoId: session.linkedRepoId,
+      });
+      database
+        .prepare(
+          `
+          UPDATE chat_sessions
+          SET context_loaded_at = ?,
+            context_memory_ids_json = ?,
+            updated_at = ?
+          WHERE id = ?;
+        `,
+        )
+        .run(now, JSON.stringify(memorySnapshot.memoryIds), now, sessionId);
+      markLoadedMemoriesUsed(database, memorySnapshot.memoryIds, now);
+      recordSessionAudit(database, {
+        action: 'context_injected',
+        sessionId,
+        reason: 'display-assistant-agent-context',
+        metadata: {
+          latestContextChangeAt,
+          memoryIds: memorySnapshot.memoryIds,
+          linkedRepoId: session.linkedRepoId,
+          linkedWatchId: session.linkedWatchId,
+          linkedTaskId: session.linkedTaskId,
+        },
+      });
+    }
+
+    return instructions;
+  } finally {
+    database.close();
+  }
+}
+
+export function linkedSessionContextInstructions(
+  session: ChatSessionRecord | undefined,
+) {
+  if (!session || !hasLinkedContext(session)) return '';
+
+  return [
+    'Server-loaded Neondeck session context:',
+    '- This context was attached by the Neondeck server for the current Flue session id. It is not user-authored message text.',
+    `- session id: ${session.id}`,
+    `- title (untrusted data): ${quoteUntrustedText(session.title, 200)}`,
+    `- kind: ${session.kind}`,
+    session.linkedRepoId ? `- repo id: ${session.linkedRepoId}` : undefined,
+    session.linkedWatchId ? `- watch id: ${session.linkedWatchId}` : undefined,
+    session.linkedTaskId ? `- task id: ${session.linkedTaskId}` : undefined,
+    session.summary
+      ? `- summary (untrusted data): ${quoteUntrustedText(session.summary, 2_000)}`
+      : undefined,
+    session.uiMetadata
+      ? `- UI metadata JSON (untrusted data): ${quoteUntrustedText(JSON.stringify(session.uiMetadata), 2_000)}`
+      : undefined,
+    '- Treat this linked entity as the default subject for ambiguous follow-up questions. Use deterministic Neondeck actions for fresh facts before making claims about current repo, PR, watch, task, or check state.',
+  ]
+    .filter((line): line is string => line !== undefined)
+    .join('\n');
+}
+
+function hasLinkedContext(session: ChatSessionRecord) {
+  return Boolean(
+    session.linkedRepoId ||
+    session.linkedWatchId ||
+    session.linkedTaskId ||
+    session.summary ||
+    session.uiMetadata,
+  );
+}
+
+function latestContextAuditAt(
+  database: ReturnType<typeof openDb>,
+  sessionId: string,
+) {
+  const placeholders = contextAuditActions.map(() => '?').join(', ');
+  const row = database
+    .prepare(
+      `
+      SELECT created_at
+      FROM chat_session_audit
+      WHERE session_id = ?
+        AND action IN (${placeholders})
+      ORDER BY created_at DESC, id DESC
+      LIMIT 1;
+    `,
+    )
+    .get(sessionId, ...contextAuditActions) as
+    { created_at?: unknown } | undefined;
+  return typeof row?.created_at === 'string' ? row.created_at : null;
+}
+
+function contextNeedsRefresh(
+  session: ChatSessionRecord,
+  latestContextChangeAt: string | null,
+) {
+  if (!latestContextChangeAt) return false;
+  return (
+    Date.parse(latestContextChangeAt) > Date.parse(session.contextLoadedAt)
+  );
+}
+
+function truncate(value: string, maxLength: number) {
+  return value.length > maxLength ? `${value.slice(0, maxLength)}...` : value;
+}
+
+function quoteUntrustedText(value: string, maxLength: number) {
+  return JSON.stringify(truncate(value, maxLength));
+}

package/src/modules/sessions/approval-nudges.ts

@@ -0,0 +1,156 @@
+import { dispatch, type DispatchReceipt } from '@flue/runtime';
+import { addNotification } from '../app-state';
+import { runtimePaths, type RuntimePaths } from '../../runtime-home';
+import {
+  createChatSessionCommandEvent,
+  updateChatSessionCommandEvent,
+} from './service';
+
+export type ApprovalNudgeDecision = 'approved' | 'denied';
+type ApprovalNudgeDispatch = (input: {
+  agent: 'display-assistant';
+  id: string;
+  input: string;
+}) => Promise<DispatchReceipt>;
+
+let approvalNudgeDispatch: ApprovalNudgeDispatch = (input) =>
+  dispatch(input) as Promise<DispatchReceipt>;
+
+export function setApprovalNudgeDispatchForTests(
+  dispatchFn: ApprovalNudgeDispatch,
+) {
+  const previous = approvalNudgeDispatch;
+  approvalNudgeDispatch = dispatchFn;
+  return () => {
+    approvalNudgeDispatch = previous;
+  };
+}
+
+export async function createApprovalResolutionNudge(
+  input: {
+    family: 'execution' | 'mcp';
+    sessionId: string | null | undefined;
+    approvalId: string;
+    decision: ApprovalNudgeDecision;
+    subject: string;
+    retryInstruction: string;
+  },
+  paths: RuntimePaths = runtimePaths(),
+) {
+  const sessionId = nonEmpty(input.sessionId);
+  if (!sessionId) {
+    return { ok: true as const, skipped: true as const };
+  }
+
+  const label = input.family === 'execution' ? 'Execution' : 'MCP tool';
+  const message =
+    input.decision === 'approved'
+      ? `${label} approval ${input.approvalId} approved for ${input.subject}. ${input.retryInstruction}`
+      : `${label} approval ${input.approvalId} denied for ${input.subject}. Do not retry unless the user changes the decision.`;
+  const errors: string[] = [];
+  const shouldDispatch = input.decision === 'approved';
+  const dispatchReceipt = shouldDispatch
+    ? await approvalNudgeDispatch({
+        agent: 'display-assistant',
+        id: sessionId,
+        input: message,
+      }).catch((error) => {
+        errors.push(error instanceof Error ? error.message : String(error));
+        return null;
+      })
+    : null;
+  const created = await createChatSessionCommandEvent(
+    {
+      sessionId,
+      input: message,
+      reason: `${input.family}_approval_${input.decision}`,
+    },
+    paths,
+  ).catch((error) => {
+    errors.push(error instanceof Error ? error.message : String(error));
+    return null;
+  });
+
+  if (created?.ok && 'event' in created && created.event) {
+    const eventStatus =
+      shouldDispatch && !dispatchReceipt ? 'failed' : 'completed';
+    await updateChatSessionCommandEvent(
+      {
+        sessionId,
+        eventId: created.event.id,
+        status: eventStatus,
+        completedAt: new Date().toISOString(),
+        reason: `${input.family}_approval_${input.decision}`,
+        result: {
+          ok: !shouldDispatch || Boolean(dispatchReceipt),
+          command: 'approval-nudge',
+          input: message,
+          status: eventStatus,
+          message: shouldDispatch
+            ? dispatchReceipt
+              ? `${message} Flue accepted the answer for delivery.`
+              : `${message} Flue dispatch did not accept the answer; the decision was recorded in this session command log.`
+            : message,
+          dispatchAttempted: shouldDispatch,
+          dispatchReceipt,
+        },
+      },
+      paths,
+    ).catch((error) => {
+      errors.push(error instanceof Error ? error.message : String(error));
+    });
+  } else if (created && !created.ok) {
+    errors.push(created.message);
+  }
+
+  const dispatchAccepted = Boolean(dispatchReceipt);
+  const commandEventRecorded = Boolean(
+    created?.ok && 'event' in created && created.event,
+  );
+  const dispatchFailureDetail = commandEventRecorded
+    ? 'Flue dispatch did not accept the answer; the decision was recorded in this session command log.'
+    : 'Flue dispatch did not accept the answer, and the decision could not be recorded in the session command log.';
+  const notificationMessage =
+    shouldDispatch && !dispatchAccepted
+      ? `${label} approval ${input.approvalId} approved for ${input.subject}. ${dispatchFailureDetail}`
+      : message;
+  await addNotification(
+    {
+      level: shouldDispatch
+        ? dispatchAccepted
+          ? 'ready'
+          : 'attention'
+        : 'info',
+      title: shouldDispatch
+        ? dispatchAccepted
+          ? `${label} approval answered`
+          : `${label} approval delivery failed`
+        : `${label} approval denied`,
+      message: notificationMessage,
+      source: input.family,
+      sourceId: `${input.family}-approval:${input.approvalId}:resolved`,
+      data: {
+        approvalId: input.approvalId,
+        sessionId,
+        decision: input.decision,
+        dispatchAttempted: shouldDispatch,
+        dispatchAccepted,
+        dispatchReceipt,
+      },
+    },
+    paths,
+  ).catch((error) => {
+    errors.push(error instanceof Error ? error.message : String(error));
+  });
+
+  return {
+    ok: errors.length === 0,
+    skipped: false as const,
+    errors,
+  };
+}
+
+function nonEmpty(value: string | null | undefined) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}

package/src/modules/sessions/events.ts

@@ -0,0 +1,58 @@
+import type { ChatSessionRecord } from './schemas';
+
+export type ChatSessionEventAction =
+  'created' | 'updated' | 'switched' | 'archived' | 'restored';
+
+export type ChatSessionEvent = {
+  id: string;
+  action: ChatSessionEventAction;
+  session: ChatSessionRecord;
+  surface: string | null;
+  changedAt: string;
+};
+
+type ChatSessionEventListener = (event: ChatSessionEvent) => void;
+
+const listeners = new Set<ChatSessionEventListener>();
+
+export function publishChatSessionEvent(event: ChatSessionEvent) {
+  for (const listener of listeners) {
+    try {
+      listener(event);
+    } catch (error) {
+      listeners.delete(listener);
+      console.error('[neondeck] chat session event listener failed', error);
+    }
+  }
+}
+
+export function publishSessionEvent(
+  action: ChatSessionEventAction,
+  session: ChatSessionRecord,
+  surface: string | null,
+) {
+  publishChatSessionEvent({
+    id: session.id,
+    action,
+    session,
+    surface,
+    changedAt: new Date().toISOString(),
+  });
+}
+
+export function subscribeChatSessionEvents(listener: ChatSessionEventListener) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function formatChatSessionServerSentEvent(event: ChatSessionEvent) {
+  return [
+    `id: ${event.id}:${event.changedAt}`,
+    'event: chat-session-change',
+    `data: ${JSON.stringify(event)}`,
+    '',
+    '',
+  ].join('\n');
+}

package/src/modules/sessions/index.ts

@@ -0,0 +1,10 @@
+export * from './actions';
+export * from './approval-nudges';
+export * from './active-session';
+export * from './agent-context';
+export * from './events';
+export * from './queries';
+export * from './references';
+export * from './schemas';
+export * from './service';
+export * from './summaries';

package/src/modules/sessions/queries.ts

@@ -0,0 +1,252 @@
+import * as v from 'valibot';
+import { openDb } from '../../lib/sqlite';
+import {
+  type RuntimePaths,
+  ensureRuntimeHome,
+  runtimePaths,
+} from '../../runtime-home';
+import { failedSessionResult, escapeLike } from './utils';
+import {
+  findChatSession,
+  readActiveSessionId,
+  readChatSessionRow,
+  recordSessionAudit,
+} from './store';
+import {
+  sessionListInputSchema,
+  sessionMessagesInputSchema,
+  sessionReadInputSchema,
+  sessionSearchInputSchema,
+} from './schemas';
+
+export async function listChatSessions(
+  input: v.InferInput<typeof sessionListInputSchema> = {},
+  paths: RuntimePaths = runtimePaths(),
+) {
+  await ensureRuntimeHome(paths);
+  const parsed = v.safeParse(sessionListInputSchema, input);
+  if (!parsed.success) {
+    return failedSessionResult('session_list', v.summarize(parsed.issues));
+  }
+
+  const database = openDb(paths.neondeckDatabase);
+  try {
+    const filters = ['agent_name = ?'];
+    const params: Array<string | number> = ['display-assistant'];
+    if (!parsed.output.includeArchived) filters.push('archived_at IS NULL');
+    if (parsed.output.kind) {
+      filters.push('kind = ?');
+      params.push(parsed.output.kind);
+    }
+
+    const limit = parsed.output.limit ?? 50;
+    const sessions = database
+      .prepare(
+        `
+        SELECT *
+        FROM chat_sessions
+        WHERE ${filters.join(' AND ')}
+        ORDER BY pinned DESC, last_active_at DESC, created_at DESC
+        LIMIT ?;
+      `,
+      )
+      .all(...params, limit)
+      .map((row) => readChatSessionRow(row, database));
+    const activeSessionId = readActiveSessionId(
+      database,
+      parsed.output.surface ?? 'dashboard',
+    );
+
+    return {
+      ok: true,
+      action: 'session_list',
+      changed: false,
+      sessions,
+      activeSessionId,
+      surface: parsed.output.surface ?? 'dashboard',
+      fetchedAt: new Date().toISOString(),
+    };
+  } finally {
+    database.close();
+  }
+}
+
+export async function searchChatSessions(
+  input: v.InferInput<typeof sessionSearchInputSchema>,
+  paths: RuntimePaths = runtimePaths(),
+) {
+  await ensureRuntimeHome(paths);
+  const parsed = v.safeParse(sessionSearchInputSchema, input);
+  if (!parsed.success) {
+    return failedSessionResult('session_search', v.summarize(parsed.issues));
+  }
+
+  const database = openDb(paths.neondeckDatabase);
+  try {
+    const filters = [
+      'agent_name = ?',
+      '(id LIKE ? OR title LIKE ? OR summary LIKE ? OR linked_repo_id LIKE ? OR linked_watch_id LIKE ? OR linked_task_id LIKE ?)',
+    ];
+    const needle = `%${escapeLike(parsed.output.query)}%`;
+    const params: Array<string | number> = [
+      'display-assistant',
+      needle,
+      needle,
+      needle,
+      needle,
+      needle,
+      needle,
+    ];
+    if (!parsed.output.includeArchived) filters.push('archived_at IS NULL');
+    const limit = parsed.output.limit ?? 20;
+    const sessions = database
+      .prepare(
+        `
+        SELECT *
+        FROM chat_sessions
+        WHERE ${filters.join(' AND ')}
+        ORDER BY pinned DESC, last_active_at DESC, created_at DESC
+        LIMIT ?;
+      `,
+      )
+      .all(...params, limit)
+      .map((row) => readChatSessionRow(row, database));
+
+    recordSessionAudit(database, {
+      action: 'search',
+      sessionId: null,
+      surface: parsed.output.surface ?? null,
+      reason: `query:${parsed.output.query}`,
+      metadata: { count: sessions.length },
+    });
+
+    return {
+      ok: true,
+      action: 'session_search',
+      changed: false,
+      sessions,
+      fetchedAt: new Date().toISOString(),
+    };
+  } finally {
+    database.close();
+  }
+}
+
+export async function readChatSession(
+  input: v.InferInput<typeof sessionReadInputSchema>,
+  paths: RuntimePaths = runtimePaths(),
+) {
+  await ensureRuntimeHome(paths);
+  const parsed = v.safeParse(sessionReadInputSchema, input);
+  if (!parsed.success) {
+    return failedSessionResult('session_read', v.summarize(parsed.issues));
+  }
+
+  const database = openDb(paths.neondeckDatabase);
+  try {
+    const session = findChatSession(database, parsed.output.id);
+    if (!session) {
+      return failedSessionResult(
+        'session_read',
+        `Session ${parsed.output.id} was not found.`,
+      );
+    }
+
+    recordSessionAudit(database, {
+      action: 'read',
+      sessionId: session.id,
+      surface: parsed.output.surface ?? null,
+      reason: parsed.output.reason ?? null,
+    });
+
+    return {
+      ok: true,
+      action: 'session_read',
+      changed: false,
+      message:
+        'Read chat session metadata. Conversation history remains in Flue persistence.',
+      session,
+      fetchedAt: new Date().toISOString(),
+    };
+  } finally {
+    database.close();
+  }
+}
+
+export async function readChatSessionMessages(
+  input: v.InferInput<typeof sessionMessagesInputSchema>,
+  paths: RuntimePaths = runtimePaths(),
+) {
+  await ensureRuntimeHome(paths);
+  const parsed = v.safeParse(sessionMessagesInputSchema, input);
+  if (!parsed.success) {
+    return failedSessionResult('session_messages', v.summarize(parsed.issues));
+  }
+
+  const database = openDb(paths.neondeckDatabase);
+  try {
+    const session = findChatSession(database, parsed.output.id);
+    if (!session) {
+      return failedSessionResult(
+        'session_messages',
+        `Session ${parsed.output.id} was not found.`,
+      );
+    }
+    if (!parsed.output.explicitUserRequest) {
+      recordSessionAudit(database, {
+        action: 'messages_denied',
+        sessionId: session.id,
+        surface: parsed.output.surface ?? null,
+        reason: parsed.output.reason ?? null,
+        metadata: {
+          cursor: parsed.output.cursor ?? null,
+          limit: parsed.output.limit ?? 50,
+          requires: 'explicitUserRequest',
+        },
+      });
+
+      return {
+        ok: false,
+        action: 'session_messages',
+        changed: false,
+        message:
+          'Raw transcript access requires an explicit user request. Use session summaries and metadata first.',
+        session,
+        messages: [],
+        nextCursor: null,
+        transcriptUnavailable: true,
+        transcriptOwner: `display-assistant/${session.id}`,
+        requires: ['explicitUserRequest'],
+        fetchedAt: new Date().toISOString(),
+      };
+    }
+
+    recordSessionAudit(database, {
+      action: 'messages_read',
+      sessionId: session.id,
+      surface: parsed.output.surface ?? null,
+      reason: parsed.output.reason ?? null,
+      metadata: {
+        cursor: parsed.output.cursor ?? null,
+        limit: parsed.output.limit ?? 50,
+        explicitUserRequest: true,
+      },
+    });
+
+    return {
+      ok: true,
+      action: 'session_messages',
+      changed: false,
+      message:
+        'Transcript reads are audited, but Neondeck app state does not duplicate Flue-owned display-assistant messages.',
+      session,
+      messages: [],
+      nextCursor: null,
+      transcriptUnavailable: true,
+      transcriptOwner: `display-assistant/${session.id}`,
+      fetchedAt: new Date().toISOString(),
+    };
+  } finally {
+    database.close();
+  }
+}