@startsimpli/integrations 0.1.4 → 0.1.6

package/src/components/Markdown.tsx

@@ -0,0 +1,193 @@
+/**
+ * The small amount of Markdown that actually arrives in a corpus, rendered.
+ *
+ * WHY THIS EXISTS. Sources write Markdown and the corpus stores it verbatim —
+ * Granola's summary is `## Decisions` and `**$4,800 per month**`, and a model
+ * asked for prose answers in the same dialect. Rendering that as plain text puts
+ * literal hashes and asterisks on the screen, which reads as a bug in the
+ * product rather than as punctuation from the source.
+ *
+ * WHY IT IS ~100 LINES AND NOT A DEPENDENCY. A Markdown library is a peer
+ * dependency every consuming app has to install and a sanitiser decision every
+ * consuming app has to get right. This renders to REACT ELEMENTS — there is no
+ * `dangerouslySetInnerHTML` anywhere below, so untrusted document text cannot
+ * become markup, which is the property that actually matters for a surface whose
+ * whole job is displaying text somebody else wrote.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO. No tables, no block quotes, no images, no
+ * single-asterisk emphasis (`*` appears in real prose far more often than it
+ * means italics, and a false positive silently eats characters out of a
+ * contract). Anything unrecognised falls through as its own literal text, which
+ * is the same thing the screen showed before — never worse.
+ */
+import * as React from 'react';
+
+/**
+ * Markdown reduced to the text a human would read aloud.
+ *
+ * For places that need a STRING rather than elements — a truncated one-line
+ * preview, a title, an `aria-label`. Same syntax coverage as the renderer.
+ */
+export function stripMarkdown(text: string): string {
+  if (!text) return '';
+  return text
+    .replace(/```[\s\S]*?```/g, (block) => block.replace(/```[^\n]*\n?/g, ''))
+    .replace(/^\s{0,3}#{1,6}\s+/gm, '')
+    .replace(/^\s{0,3}([-*_])\s*\1\s*\1[-*_\s]*$/gm, '')
+    .replace(/^\s{0,3}[-*+]\s+/gm, '')
+    .replace(/^\s{0,3}>\s?/gm, '')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/\*\*([^*]+)\*\*/g, '$1')
+    .replace(/__([^_]+)__/g, '$1')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/[ \t]+\n/g, '\n')
+    .trim();
+}
+
+/** `**bold**`, `` `code` `` and `[text](url)` inside one line of text. */
+function inline(text: string, keyPrefix: string): React.ReactNode[] {
+  const nodes: React.ReactNode[] = [];
+  // One pass, one regex: whichever construct starts first wins, so a link whose
+  // label contains asterisks is still a link.
+  const pattern = /(\*\*|__)([\s\S]+?)\1|`([^`]+)`|\[([^\]]+)\]\(([^)\s]+)[^)]*\)/g;
+  let cursor = 0;
+  let match: RegExpExecArray | null;
+  let index = 0;
+
+  while ((match = pattern.exec(text)) !== null) {
+    if (match.index > cursor) nodes.push(text.slice(cursor, match.index));
+    index += 1;
+    const key = `${keyPrefix}-${index}`;
+    if (match[2] !== undefined) {
+      nodes.push(<strong key={key}>{match[2]}</strong>);
+    } else if (match[3] !== undefined) {
+      nodes.push(
+        <code key={key} className="rounded bg-black/5 px-1 py-0.5 text-[0.9em]">
+          {match[3]}
+        </code>,
+      );
+    } else if (match[4] !== undefined) {
+      const href = match[5] ?? '';
+      const safe = /^(https?:|mailto:)/i.test(href);
+      nodes.push(
+        safe ? (
+          <a key={key} href={href} target="_blank" rel="noreferrer" className="underline">
+            {match[4]}
+          </a>
+        ) : (
+          // A `javascript:` or otherwise unrecognised scheme keeps its LABEL and
+          // loses its link. Silently dropping the text would edit the document.
+          <React.Fragment key={key}>{match[4]}</React.Fragment>
+        ),
+      );
+    }
+    cursor = pattern.lastIndex;
+  }
+  if (cursor < text.length) nodes.push(text.slice(cursor));
+  return nodes.length ? nodes : [text];
+}
+
+const HEADING_CLASS = ['font-semibold', 'font-semibold', 'font-medium'];
+
+/**
+ * Block-level Markdown as React elements.
+ *
+ * `className` lands on the wrapper so an app's theme slot still styles the whole
+ * block exactly as it did when this was a `<p>` of raw text.
+ */
+export function Markdown({ text, className }: { text: string; className?: string }) {
+  const blocks = React.useMemo(() => parseBlocks(text ?? ''), [text]);
+  if (!text) return null;
+  return (
+    <div className={className}>
+      {blocks.map((block, blockIndex) => {
+        const key = `b${blockIndex}`;
+        if (block.kind === 'heading') {
+          const level = Math.min(block.level ?? 3, 3);
+          return (
+            <p
+              key={key}
+              className={`${HEADING_CLASS[level - 1] ?? 'font-medium'} ${blockIndex ? 'mt-3' : ''}`}
+            >
+              {inline(block.lines[0] ?? '', key)}
+            </p>
+          );
+        }
+        if (block.kind === 'list') {
+          return (
+            <ul key={key} className={`list-disc space-y-1 pl-5 ${blockIndex ? 'mt-2' : ''}`}>
+              {block.lines.map((line, lineIndex) => (
+                <li key={`${key}-${lineIndex}`}>{inline(line, `${key}-${lineIndex}`)}</li>
+              ))}
+            </ul>
+          );
+        }
+        if (block.kind === 'rule') {
+          return <hr key={key} className="my-3 border-black/10" />;
+        }
+        return (
+          <p key={key} className={`whitespace-pre-wrap ${blockIndex ? 'mt-2' : ''}`}>
+            {inline(block.lines.join('\n'), key)}
+          </p>
+        );
+      })}
+    </div>
+  );
+}
+
+interface Block {
+  kind: 'paragraph' | 'heading' | 'list' | 'rule';
+  lines: string[];
+  level?: number;
+}
+
+function parseBlocks(text: string): Block[] {
+  const blocks: Block[] = [];
+  let paragraph: string[] = [];
+  let list: string[] = [];
+
+  const flushParagraph = () => {
+    if (paragraph.length) blocks.push({ kind: 'paragraph', lines: paragraph });
+    paragraph = [];
+  };
+  const flushList = () => {
+    if (list.length) blocks.push({ kind: 'list', lines: list });
+    list = [];
+  };
+
+  for (const raw of text.replace(/\r\n/g, '\n').split('\n')) {
+    const line = raw.replace(/\s+$/, '');
+    const heading = /^\s{0,3}(#{1,6})\s+(.*)$/.exec(line);
+    const bullet = /^\s{0,3}[-*+]\s+(.*)$/.exec(line);
+    const numbered = /^\s{0,3}\d+[.)]\s+(.*)$/.exec(line);
+    const rule = /^\s{0,3}([-*_])\s*\1\s*\1[-*_\s]*$/.test(line);
+
+    if (!line.trim()) {
+      flushList();
+      flushParagraph();
+      continue;
+    }
+    if (rule) {
+      flushList();
+      flushParagraph();
+      blocks.push({ kind: 'rule', lines: [] });
+      continue;
+    }
+    if (heading) {
+      flushList();
+      flushParagraph();
+      blocks.push({ kind: 'heading', lines: [heading[2] ?? ''], level: heading[1].length });
+      continue;
+    }
+    if (bullet || numbered) {
+      flushParagraph();
+      list.push((bullet ? bullet[1] : numbered?.[1]) ?? '');
+      continue;
+    }
+    flushList();
+    paragraph.push(line);
+  }
+  flushList();
+  flushParagraph();
+  return blocks;
+}

package/src/components/index.ts

@@ -3,6 +3,7 @@ export * from './ConnectAccountCard';
 export * from './EmailList';
 export * from './EventList';
 export * from './EventListItem';
+export * from './Markdown';
 export * from './ReconsentPromptCard';
 
 // The connections layer (bd startsim-768w.22.3.4): ONE schema-driven form and
@@ -24,3 +25,8 @@ export type {
   ConnectionInvokeResult,
   ConnectionRun,
 } from './pages/types';
+
+// The corpus layer (bd startsim-768w.38.6, startsim-768w.38.7): the READ side of
+// connections. Same rule as above — the page composers ship, not just the parts.
+export * from './pages/LibraryPage';
+export * from './pages/AskPage';

package/src/components/pages/AskPage.tsx

@@ -0,0 +1,409 @@
+/**
+ * Ask & Generate — AI over your own documents, with citations back to the
+ * records (bd startsim-768w.38.7). The headline surface of the epic.
+ *
+ * `<AskPage api={askApi} scope={scope} />`, same injected shape as
+ * `ConnectionsPage` and `LibraryPage`. The app owns theme classNames and a
+ * wrapper; the LLM call happens behind `api.ask`, server-side, where the key is.
+ * Nothing in this file imports a provider.
+ *
+ * TWO MODES, ONE SURFACE. ASK answers a question from the corpus. GENERATE
+ * drafts a document — a contract, a follow-up, a summary — from a prompt plus
+ * the corpus. Same retrieval, same citation rules; the only difference is what
+ * the model is asked to emit and whether the result can be saved back as a
+ * record, so that the draft is part of the corpus next time.
+ *
+ * CITATIONS ARE NOT A NICE-TO-HAVE, AND THIS FILE IS WHERE THAT IS ENFORCED
+ * VISIBLY:
+ *
+ *   • every answer renders the records it used, each one clicking through to
+ *     that record's detail in the Library;
+ *   • an answer with NO resolvable citation renders under a warning and is
+ *     never presented as sourced — an answer you cannot trace is one you cannot
+ *     trust with a contract;
+ *   • an id the model cited that retrieval never supplied is displayed as an
+ *     invented source rather than dropped quietly;
+ *   • the provider that actually answered is named, and a run that came from a
+ *     stub says so, because a fake model behind real-looking citations is worse
+ *     than no answer at all;
+ *   • stale or failing sources are repeated here, because the honest caveat on
+ *     any answer is "…from a corpus that last synced on Tuesday".
+ */
+import * as React from 'react';
+
+import { Markdown, stripMarkdown } from '../Markdown';
+import type {
+  AskMode,
+  AskRequest,
+  AskResult,
+  CorpusAskApi,
+  CorpusScope,
+  SourceFreshness,
+} from '../../corpus/types';
+
+export interface AskPageProps {
+  api: CorpusAskApi;
+  scope: CorpusScope;
+  /** Click-through from a citation to the record, normally the Library route. */
+  onOpenDocument?: (documentId: string) => void;
+  /** Prefill, e.g. from a `?q=` param. */
+  initialQuestion?: string;
+  initialMode?: AskMode;
+  classNames?: Partial<Record<AskSlot, string>>;
+}
+
+type AskSlot =
+  | 'root' | 'section' | 'heading' | 'card' | 'badge' | 'button' | 'secondaryButton'
+  | 'input' | 'textarea' | 'muted' | 'error' | 'warning' | 'answer';
+
+const DEFAULTS: Record<AskSlot, string> = {
+  root: 'space-y-6',
+  section: 'space-y-3',
+  heading: 'text-lg font-semibold text-gray-900',
+  card: 'rounded-lg border border-gray-200 p-4',
+  badge: 'inline-flex items-center rounded-full border border-gray-300 px-2 py-0.5 text-xs text-gray-700',
+  button: 'rounded-md bg-gray-900 px-3 py-1.5 text-sm font-medium text-white disabled:opacity-50',
+  secondaryButton: 'rounded-md border border-gray-300 px-3 py-1.5 text-sm font-medium text-gray-800 disabled:opacity-50',
+  input: 'w-full rounded-md border border-gray-300 px-3 py-2 text-sm',
+  textarea: 'w-full rounded-md border border-gray-300 px-3 py-2 text-sm',
+  muted: 'text-sm text-gray-500',
+  error: 'text-sm text-red-600',
+  warning: 'rounded-md border border-amber-300 bg-amber-50 p-3 text-sm text-amber-900',
+  answer: 'whitespace-pre-wrap rounded-md bg-gray-50 p-3 text-sm text-gray-900',
+};
+
+const MODE_LABELS: Record<AskMode, { tab: string; prompt: string; action: string; placeholder: string }> = {
+  ask: {
+    tab: 'Ask',
+    prompt: 'Question',
+    action: 'Ask',
+    placeholder: 'What did we agree with Acme Robotics on renewal?',
+  },
+  generate: {
+    tab: 'Generate',
+    prompt: 'What should be drafted',
+    action: 'Generate draft',
+    placeholder: 'Draft a renewal letter for Acme Robotics using the agreed terms.',
+  },
+};
+
+function failureMessage(err: unknown): string {
+  const status = (err as { status?: number })?.status;
+  if (status === 403) return 'You do not have access to this workspace’s records.';
+  if (status === 401) return 'Your session has expired. Sign in again.';
+  return (err as { message?: string })?.message || 'That question could not be answered right now.';
+}
+
+export function AskPage({
+  api,
+  scope,
+  onOpenDocument,
+  initialQuestion = '',
+  initialMode = 'ask',
+  classNames = {},
+}: AskPageProps) {
+  const cn = { ...DEFAULTS, ...classNames };
+
+  const [mode, setMode] = React.useState<AskMode>(initialMode);
+  const [question, setQuestion] = React.useState(initialQuestion);
+  const [instructions, setInstructions] = React.useState('');
+  const [result, setResult] = React.useState<AskResult | null>(null);
+  const [busy, setBusy] = React.useState(false);
+  const [error, setError] = React.useState('');
+  const [saveState, setSaveState] = React.useState<'idle' | 'saving' | 'saved'>('idle');
+
+  const submit = React.useCallback(async () => {
+    const trimmed = question.trim();
+    if (!trimmed) return;
+    setBusy(true);
+    setError('');
+    setSaveState('idle');
+    try {
+      const request: AskRequest = {
+        question: trimmed,
+        mode,
+        scope,
+        ...(mode === 'generate' && instructions.trim() ? { instructions: instructions.trim() } : {}),
+      };
+      setResult(await api.ask(request));
+    } catch (err) {
+      setResult(null);
+      setError(failureMessage(err));
+    } finally {
+      setBusy(false);
+    }
+  }, [api, instructions, mode, question, scope]);
+
+  const canSave = Boolean(api.saveDraft) && mode === 'generate' && result?.status === 'answered';
+
+  return (
+    <div className={cn.root}>
+      <section className={cn.section}>
+        <div className="flex gap-2" role="tablist" aria-label="Ask or generate">
+          {(['ask', 'generate'] as const).map((value) => (
+            <button
+              key={value}
+              type="button"
+              role="tab"
+              aria-selected={mode === value}
+              className={mode === value ? cn.button : cn.secondaryButton}
+              onClick={() => { setMode(value); setResult(null); setError(''); }}
+            >
+              {MODE_LABELS[value].tab}
+            </button>
+          ))}
+        </div>
+
+        <form
+          className="space-y-2"
+          onSubmit={(event) => { event.preventDefault(); void submit(); }}
+        >
+          <label className="block space-y-1">
+            <span className="text-sm font-medium text-gray-900">{MODE_LABELS[mode].prompt}</span>
+            <textarea
+              className={cn.textarea}
+              rows={3}
+              value={question}
+              placeholder={MODE_LABELS[mode].placeholder}
+              onChange={(event) => setQuestion(event.target.value)}
+            />
+          </label>
+
+          {mode === 'generate' ? (
+            <label className="block space-y-1">
+              <span className="text-sm font-medium text-gray-900">Tone or format (optional)</span>
+              <input
+                className={cn.input}
+                value={instructions}
+                placeholder="Formal letter, one page, ready to sign"
+                onChange={(event) => setInstructions(event.target.value)}
+              />
+            </label>
+          ) : null}
+
+          <button type="submit" className={cn.button} disabled={busy || !question.trim()}>
+            {busy ? 'Reading your records…' : MODE_LABELS[mode].action}
+          </button>
+        </form>
+
+        {error ? <p className={cn.error} role="alert">{error}</p> : null}
+      </section>
+
+      {result ? (
+        <AnswerPanel
+          result={result}
+          classNames={cn}
+          onOpenDocument={onOpenDocument}
+          canSave={canSave}
+          saveState={saveState}
+          onSave={async () => {
+            if (!api.saveDraft || !result) return;
+            setSaveState('saving');
+            try {
+              await api.saveDraft({
+                title: question.trim().slice(0, 120) || 'Generated draft',
+                body: result.answer,
+                citations: result.citations.map((citation) => citation.documentId),
+                scope,
+              });
+              setSaveState('saved');
+            } catch (err) {
+              setSaveState('idle');
+              setError(failureMessage(err));
+            }
+          }}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+
+function AnswerPanel({
+  result, classNames: cn, onOpenDocument, canSave, saveState, onSave,
+}: {
+  result: AskResult;
+  classNames: Record<AskSlot, string>;
+  onOpenDocument?: (documentId: string) => void;
+  canSave: boolean;
+  saveState: 'idle' | 'saving' | 'saved';
+  onSave: () => void;
+}) {
+  const unhealthy = (result.freshness ?? []).filter((source) => source.status !== 'ok');
+
+  if (result.status === 'no_evidence') {
+    return (
+      <section className={cn.card} aria-label="Answer">
+        <h2 className={cn.heading}>No answer from your records</h2>
+        {/* The correct outcome of a cross-workspace question. Saying "nothing"
+            is the whole point: the alternative is someone else's documents. */}
+        <p className="mt-2 text-sm text-gray-700">{result.answer}</p>
+        <ProvenanceFooter result={result} classNames={cn} />
+      </section>
+    );
+  }
+
+  return (
+    <section className={cn.card} aria-label="Answer">
+      {result.status === 'uncited' ? (
+        <p className={cn.warning} role="alert">
+          This answer could not be traced to any of your records, so it is shown as unsourced.
+          Do not rely on it for anything you would sign.
+        </p>
+      ) : null}
+
+      {unhealthy.length ? (
+        <p className={cn.warning} role="status">
+          Answered from a corpus that is not fully current:{' '}
+          {unhealthy.map((source) => `${source.label} (${source.status})`).join(', ')}.
+        </p>
+      ) : null}
+
+      {/* A model asked for prose answers in Markdown. Rendering it as literal
+          text puts "**$4,800**" on the screen, which reads as the product
+          failing rather than as the model emphasising the number. */}
+      <Markdown text={result.answer} className={`mt-3 ${cn.answer}`} />
+
+      {canSave ? (
+        <button
+          type="button"
+          className={`mt-3 ${cn.button}`}
+          disabled={saveState !== 'idle'}
+          onClick={onSave}
+        >
+          {/* Saving the draft back makes it part of the corpus next time — the
+              output of the system is also an input to it. */}
+          {saveState === 'saved' ? 'Saved to your library' : saveState === 'saving' ? 'Saving…' : 'Save to library'}
+        </button>
+      ) : null}
+
+      <div className="mt-4 space-y-2">
+        <h3 className="text-sm font-medium text-gray-900">
+          {result.citations.length} source{result.citations.length === 1 ? '' : 's'}
+        </h3>
+        {result.citations.map((citation) => (
+          <div key={citation.documentId} className="border-t pt-2">
+            <div className="flex flex-wrap items-center gap-2">
+              <span className={cn.badge}>
+                {citation.document.sourceLabel || citation.document.source}
+              </span>
+              <button
+                type="button"
+                className="text-sm font-medium text-blue-700 underline"
+                onClick={() => onOpenDocument?.(citation.documentId)}
+              >
+                {citation.document.title}
+              </button>
+              <span className={cn.muted}>
+                {citation.document.occurredAt
+                  ? new Date(citation.document.occurredAt).toLocaleDateString()
+                  : 'No date'}
+              </span>
+            </div>
+            {/* The model's own quote, so the claim can be checked against the
+                record without opening it. */}
+            {citation.quote ? (
+              // Flattened, not rendered: a quotation is a span of the record's
+              // own words, and it should read as one line inside the quote
+              // marks rather than re-opening as a heading or a bullet.
+              <p className="mt-1 text-sm italic text-gray-600">“{stripMarkdown(citation.quote)}”</p>
+            ) : null}
+          </div>
+        ))}
+      </div>
+
+      {result.unresolvedCitations.length ? (
+        <p className={`mt-3 ${cn.warning}`} role="alert">
+          The model also cited {result.unresolvedCitations.length} record
+          {result.unresolvedCitations.length === 1 ? '' : 's'} that were never given to it
+          ({result.unresolvedCitations.join(', ')}). Those were discarded — treat the answer with care.
+        </p>
+      ) : null}
+
+      <ConsideredList result={result} classNames={cn} onOpenDocument={onOpenDocument} />
+      <ProvenanceFooter result={result} classNames={cn} />
+    </section>
+  );
+}
+
+/**
+ * Everything retrieval offered the model, cited or not — so "why did it not use
+ * the contract?" is answerable without reading a log.
+ */
+function ConsideredList({
+  result, classNames: cn, onOpenDocument,
+}: {
+  result: AskResult;
+  classNames: Record<AskSlot, string>;
+  onOpenDocument?: (documentId: string) => void;
+}) {
+  const cited = new Set(result.citations.map((citation) => citation.documentId));
+  const unused = result.considered.filter((item) => !cited.has(item.document.id));
+  if (unused.length === 0) return null;
+  return (
+    <details className="mt-3">
+      <summary className="cursor-pointer text-sm text-gray-600">
+        {unused.length} more record{unused.length === 1 ? ' was' : 's were'} searched but not cited
+      </summary>
+      <div className="mt-2 space-y-1">
+        {unused.map((item) => (
+          <div key={item.document.id} className="flex flex-wrap items-center gap-2">
+            <span className={cn.badge}>{item.document.sourceLabel || item.document.source}</span>
+            <button
+              type="button"
+              className="text-sm text-blue-700 underline"
+              onClick={() => onOpenDocument?.(item.document.id)}
+            >
+              {item.document.title}
+            </button>
+            {item.matchedTerms.length ? (
+              <span className={cn.muted}>matched: {item.matchedTerms.join(', ')}</span>
+            ) : null}
+          </div>
+        ))}
+      </div>
+    </details>
+  );
+}
+
+/**
+ * Who answered, said plainly.
+ *
+ * THREE CASES, not two (bd startsim-768w.38.21). A live model names itself. A
+ * STUB says it is a stub. And a workspace with NO provider configured is not a
+ * stub at all — "Answered by a none stub ((provider default))" was neither
+ * English nor true. Every branch keeps the `live: false` honesty; the point is
+ * to say the true thing clearly, not to soften it.
+ */
+function providerSentence(provider: AskResult['provider']): string {
+  const model = provider.model?.trim() ?? '';
+  if (provider.live) {
+    return model ? `Answered by ${provider.provider} · ${model}` : `Answered by ${provider.provider}`;
+  }
+  if (!provider.provider || provider.provider === 'none') {
+    return 'No model is configured for this workspace — no live model was called.';
+  }
+  return model
+    ? `Answered by a ${provider.provider} stub (${model}) — no live model was called`
+    : `Answered by a ${provider.provider} stub — no live model was called`;
+}
+
+function ProvenanceFooter({
+  result, classNames: cn,
+}: { result: AskResult; classNames: Record<AskSlot, string> }) {
+  return (
+    <div className="mt-4 border-t pt-2">
+      <p className={cn.muted}>{providerSentence(result.provider)}</p>
+      {/* A non-zero drop means something upstream returned rows from another
+          workspace. It is stated rather than swallowed, because the guard
+          catching it is good news about the guard and bad news about the API. */}
+      {result.droppedOutOfScope > 0 ? (
+        <p className={cn.error} role="status">
+          {result.droppedOutOfScope} record{result.droppedOutOfScope === 1 ? '' : 's'} from another
+          workspace were returned by the data API and excluded before answering.
+        </p>
+      ) : null}
+    </div>
+  );
+}