@kywk/open-slide-core 2.3.1 → 2.3.2

package/src/agent/prompt.ts

@@ -0,0 +1,141 @@
+import { UNTITLED_SLIDE_ID_RE } from '../editing/placeholder-id.ts';
+import { parseQuestions } from './provider.ts';
+import type { AgentQuestion, AgentTurnContext } from './types.ts';
+
+const PAGE_BY_PAGE =
+  'Write a new deck page by page so the user can follow along on the canvas: first replace the file with the imports, meta (keeping its existing createdAt), design and the cover page only, then add each remaining page with its own separate edit, keeping the file compiling after every write.';
+
+const DECK_SLUG =
+  "This deck's folder still has a placeholder name. Never rename or move the folder yourself: once the deck has content, end your final reply with a slug for it on a line of its own as <deck-slug>short-kebab-case-english-slug</deck-slug>, and open-slide renames the folder from it.";
+
+export function systemPromptAppend(askInstruction: string): string {
+  return [
+    'You are running inside the open-slide dev server, driven from its in-app agent panel in the browser rather than a terminal.',
+    'The workspace is an open-slide project: decks live under slides/<id>/index.tsx and the dev server hot-reloads every edit, so the user sees changes immediately.',
+    'Use the project skills: create-slide to draft a new deck, apply-comments to resolve @slide-comment markers left by the inspector, create-theme for themes, and slide-authoring as the technical reference before writing a page.',
+    PAGE_BY_PAGE,
+    'Keep replies short and concrete: the panel is narrow. Prefer doing the work over describing it, and finish with a one-line summary of what changed.',
+    askInstruction,
+  ].join(' ');
+}
+
+export function buildTurnPrompt(text: string, context: AgentTurnContext | undefined): string {
+  const lines = contextLines(context);
+  if (lines.length === 0) return text;
+  return `${text}\n\n<open-slide-context>\n${lines.join('\n')}\n</open-slide-context>`;
+}
+
+// Slide titles and selected text come from deck content, so they sit in their
+// own tags with `<` escaped and can't close the context block.
+const escapeTag = (s: string) => s.replace(/</g, '&lt;');
+
+function contextLines(context: AgentTurnContext | undefined): string[] {
+  if (!context?.slideId) return [];
+  const file = `slides/${context.slideId}/index.tsx`;
+  const lines: string[] = [];
+  if (context.newDeck) {
+    lines.push(
+      `${file} is a blank deck created for this request. Draft the deck the user describes into it with the create-slide skill: replace the placeholder page, keep the slide id, and do not create another folder.`,
+      'Ask the create-slide scoping questions in a single round, only for what the request leaves unclear; skip any it already answers.',
+      PAGE_BY_PAGE,
+      DECK_SLUG,
+    );
+    return lines;
+  }
+  lines.push(`The user is viewing slide "${context.slideId}": ${file}.`);
+  if (UNTITLED_SLIDE_ID_RE.test(context.slideId)) lines.push(DECK_SLUG);
+  if (context.slideTitle) {
+    lines.push(`<slide-title>${escapeTag(context.slideTitle)}</slide-title>`);
+  }
+  if (context.pageNumber && context.totalPages) {
+    lines.push(
+      `They are on page ${context.pageNumber} of ${context.totalPages} (0-based index ${context.pageNumber - 1} in the default export array).`,
+    );
+  }
+  if (context.selection) {
+    const { line, column, tagName, text } = context.selection;
+    lines.push(
+      `They have selected a <${escapeTag(tagName)}> element at ${file}:${line}:${column}.${text ? ' Its text is in <selected-text>.' : ''} "This element" refers to it.`,
+    );
+    if (text) lines.push(`<selected-text>${escapeTag(text)}</selected-text>`);
+  }
+  if (context.pendingComments) {
+    lines.push(
+      `There are ${context.pendingComments} pending @slide-comment markers in this slide's source.`,
+    );
+  }
+  return lines;
+}
+
+const DECK_SLUG_RE = /\s*<deck-slug>\s*([^<]*?)\s*<\/deck-slug>\s*/gi;
+
+export function extractDeckSlug(text: string): string | null {
+  let slug: string | null = null;
+  for (const match of text.matchAll(DECK_SLUG_RE)) slug = match[1] || slug;
+  return slug;
+}
+
+// Also drops a tag that is still streaming in, so the marker never flashes
+// in the transcript.
+export function stripDeckSlug(text: string): string {
+  return text
+    .replace(DECK_SLUG_RE, '\n')
+    .replace(/\s*<deck-slug>[^<]*$/i, '')
+    .trimEnd();
+}
+
+export function applyCommentsPrompt(slideId: string): string {
+  return `Use the apply-comments skill to apply every pending @slide-comment marker in slides/${slideId}/index.tsx, then remove the markers.`;
+}
+
+const QUESTIONS_RE = /<open-slide-questions>([\s\S]*?)<\/open-slide-questions>/i;
+
+export const TEXT_QUESTIONS_INSTRUCTION =
+  'You cannot ask the user anything interactively here, and nothing you print in the middle of a turn can be answered. When you need answers before continuing, stop working and end your turn with a final message holding only an <open-slide-questions> block: a JSON array of at most 4 questions shaped like [{"header":"Pages","question":"How many pages?","multiSelect":false,"options":[{"label":"6-10 (Recommended)","description":"Standard length"}]}], each with 2 to 4 options, written in the user\'s language. The panel shows them as a form and sends the answers back as your next message. Write nothing after the block and do not continue the task in the same turn.';
+
+// Splits a reply written under TEXT_QUESTIONS_INSTRUCTION into its prose and
+// questions. Returns null when the reply holds no usable block.
+export function extractQuestionBlock(
+  text: string,
+): { text: string; questions: AgentQuestion[] } | null {
+  const match = QUESTIONS_RE.exec(text);
+  if (!match) return null;
+  const body = match[1]
+    .trim()
+    .replace(/^```(?:json)?\s*/i, '')
+    .replace(/\s*```$/, '');
+  let raw: unknown;
+  try {
+    raw = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  const questions = parseQuestions({
+    questions: Array.isArray(raw) ? raw : (raw as { questions?: unknown } | null)?.questions,
+  });
+  if (questions.length === 0) return null;
+  return { text: text.replace(QUESTIONS_RE, '').trim(), questions };
+}
+
+export function answersPrompt(
+  questions: AgentQuestion[],
+  answers: Record<string, string> | null,
+): string {
+  if (!answers) {
+    return 'I skipped your questions. Continue the task with your best judgement and sensible defaults.';
+  }
+  const lines = questions.map((q) => `- ${q.question} ${answers[q.question] || '(no answer)'}`);
+  return `My answers:\n${lines.join('\n')}\n\nContinue the task with these answers.`;
+}
+
+// For agents whose history can't be rewound: the edited message goes on top
+// of the old conversation, so the agent is told to set that part aside.
+export function editedPrompt(original: string, text: string): string {
+  return `I went back and edited an earlier message of mine. Treat everything after it in this conversation, including your replies, as discarded, and respond to the edited version instead. Files keep whatever changes were already made.\n\n<original-message>\n${escapeTag(original)}\n</original-message>\n\n${text}`;
+}
+
+// For agents rewound to before the edited message: their history forgets the
+// later turns, but the files on disk still hold what those turns wrote.
+export function rewoundPrompt(text: string): string {
+  return `${text}\n\n<open-slide-note>I went back and edited this message. Files keep the changes made after it in the discarded part of this conversation, so read the current files before editing them.</open-slide-note>`;
+}

package/src/agent/provider.ts

@@ -0,0 +1,123 @@
+import path from 'node:path';
+import type { AgentEffort, AgentModelOption, AgentProviderId, AgentQuestion } from './types.ts';
+
+export type ProviderEvent =
+  | { type: 'session-id'; id: string }
+  // A point in the provider's own history that a later edit can rewind to.
+  | { type: 'checkpoint'; id: string }
+  | { type: 'text-start'; id: string }
+  | { type: 'text-delta'; id: string; text: string }
+  | { type: 'text-end'; id: string; text: string | null }
+  | { type: 'tool-start'; id: string; name: string; title: string; detail: string | null }
+  | { type: 'tool-end'; id: string; ok: boolean }
+  | { type: 'error'; text: string }
+  | { type: 'result'; durationMs: number | null; costUsd: number | null }
+  // Questions the agent wrote into its reply instead of asking through a
+  // tool: the turn ends, and the answers arrive as the next prompt.
+  | { type: 'questions'; questions: AgentQuestion[] };
+
+export type PermissionRequest = { tool: string; title: string; detail: string | null };
+
+export type ProviderRunOptions = {
+  cwd: string;
+  // Directories the agent may write to without asking: the deck and asset
+  // folders. Edits anywhere else (configs, package.json) need approval.
+  writableRoots: string[];
+  prompt: string;
+  systemPromptAppend: string;
+  resume: string | null;
+  resumeAt: string | null;
+  model: string | null;
+  effort: AgentEffort | null;
+  signal: AbortSignal;
+  emit: (event: ProviderEvent) => void;
+  askUser: (questions: AgentQuestion[]) => Promise<Record<string, string> | null>;
+  requestPermission: (request: PermissionRequest) => Promise<boolean>;
+};
+
+export interface AgentProvider {
+  id: AgentProviderId;
+  name: string;
+  sdkPackage: string;
+  cliCommand: string;
+  askInstruction: string;
+  canRewind: boolean;
+  models(): Promise<AgentModelOption[]>;
+  run(opts: ProviderRunOptions): Promise<void>;
+}
+
+export class ProviderUnavailableError extends Error {
+  constructor(provider: AgentProvider) {
+    super(
+      `${provider.name} is not connected: install ${provider.sdkPackage} in this workspace to use it from the agent panel.`,
+    );
+    this.name = 'ProviderUnavailableError';
+  }
+}
+
+const DETAIL_MAX = 400;
+
+export function clipDetail(value: unknown): string | null {
+  if (value === undefined || value === null) return null;
+  const text = typeof value === 'string' ? value : safeJson(value);
+  if (!text) return null;
+  const oneLine = text.replace(/\s+/g, ' ').trim();
+  return oneLine.length > DETAIL_MAX ? `${oneLine.slice(0, DETAIL_MAX - 1)}…` : oneLine;
+}
+
+function safeJson(value: unknown): string {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+export function isInsideRoots(cwd: string, file: unknown, roots: string[]): boolean {
+  if (typeof file !== 'string' || !file) return false;
+  const resolved = path.resolve(cwd, file);
+  return roots.some((root) => {
+    const rel = path.relative(root, resolved);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+  });
+}
+
+export function relativeToCwd(cwd: string, file: unknown): string | null {
+  if (typeof file !== 'string' || !file) return null;
+  const normalizedCwd = cwd.replace(/[\\/]+$/, '');
+  if (file.startsWith(normalizedCwd)) {
+    const rest = file.slice(normalizedCwd.length).replace(/^[\\/]+/, '');
+    return rest || '.';
+  }
+  return file;
+}
+
+export function parseQuestions(input: Record<string, unknown>): AgentQuestion[] {
+  const raw = Array.isArray(input.questions) ? input.questions : [];
+  const questions: AgentQuestion[] = [];
+  for (const q of raw) {
+    if (!q || typeof q !== 'object') continue;
+    const r = q as Record<string, unknown>;
+    const options = Array.isArray(r.options)
+      ? r.options
+          .map((o) => {
+            if (!o || typeof o !== 'object') return null;
+            const opt = o as Record<string, unknown>;
+            if (typeof opt.label !== 'string') return null;
+            return {
+              label: opt.label,
+              description: typeof opt.description === 'string' ? opt.description : undefined,
+            };
+          })
+          .filter((o): o is { label: string; description: string | undefined } => o !== null)
+      : [];
+    if (typeof r.question !== 'string') continue;
+    questions.push({
+      header: typeof r.header === 'string' ? r.header : '',
+      question: r.question,
+      options,
+      multiSelect: r.multiSelect === true,
+    });
+  }
+  return questions;
+}

package/src/agent/types.ts

@@ -0,0 +1,151 @@
+export const AGENT_PROVIDER_IDS = ['claude', 'codex'] as const;
+
+export type AgentProviderId = (typeof AGENT_PROVIDER_IDS)[number];
+
+export const AGENT_EFFORTS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const;
+
+export type AgentEffort = (typeof AGENT_EFFORTS)[number];
+
+export function isAgentProviderId(value: unknown): value is AgentProviderId {
+  return typeof value === 'string' && (AGENT_PROVIDER_IDS as readonly string[]).includes(value);
+}
+
+export function isAgentEffort(value: unknown): value is AgentEffort {
+  return typeof value === 'string' && (AGENT_EFFORTS as readonly string[]).includes(value);
+}
+
+export type AgentModelOption = {
+  // Empty when the option stands for the CLI's own default model.
+  id: string;
+  label: string;
+  efforts: AgentEffort[];
+};
+
+export type AgentProviderStatus = {
+  id: AgentProviderId;
+  name: string;
+  sdkPackage: string;
+  sdkVersion: string | null;
+  cliCommand: string;
+  cliFound: boolean;
+  cliVersion: string | null;
+  ready: boolean;
+  models: AgentModelOption[];
+};
+
+export type AgentStatus = {
+  enabled: boolean;
+  packageManager: string;
+  providers: AgentProviderStatus[];
+};
+
+type AgentQuestionOption = { label: string; description?: string };
+
+export type AgentQuestion = {
+  header: string;
+  question: string;
+  options: AgentQuestionOption[];
+  multiSelect: boolean;
+};
+
+export type AgentItem =
+  | {
+      kind: 'user';
+      id: string;
+      ts: string;
+      text: string;
+      // The provider history point just before this message, so editing it
+      // can rewind the agent's conversation there.
+      resumeAt?: string;
+      newDeck?: boolean;
+    }
+  | { kind: 'assistant'; id: string; ts: string; text: string; streaming: boolean }
+  | {
+      kind: 'tool';
+      id: string;
+      ts: string;
+      name: string;
+      title: string;
+      detail: string | null;
+      status: 'running' | 'done' | 'error';
+    }
+  | {
+      kind: 'question';
+      id: string;
+      ts: string;
+      questions: AgentQuestion[];
+      answers: Record<string, string> | null;
+      status: 'pending' | 'answered' | 'cancelled';
+    }
+  | {
+      kind: 'permission';
+      id: string;
+      ts: string;
+      tool: string;
+      title: string;
+      detail: string | null;
+      status: 'pending' | 'allowed' | 'denied';
+    }
+  | { kind: 'error'; id: string; ts: string; text: string }
+  | {
+      kind: 'result';
+      id: string;
+      ts: string;
+      durationMs: number | null;
+      costUsd: number | null;
+      aborted: boolean;
+    };
+
+type AgentSessionStatus = 'idle' | 'running';
+
+export type AgentSessionSummary = {
+  id: string;
+  provider: AgentProviderId;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+  status: AgentSessionStatus;
+  slideId: string | null;
+};
+
+export type AgentSession = AgentSessionSummary & {
+  providerSessionId: string | null;
+  providerCheckpoint?: string | null;
+  // Set once the oldest items were dropped to stay under the item cap.
+  trimmed?: boolean;
+  items: AgentItem[];
+};
+
+export type AgentTurnContext = {
+  slideId?: string;
+  slideTitle?: string;
+  pageNumber?: number;
+  totalPages?: number;
+  pendingComments?: number;
+  selection?: { line: number; column: number; tagName: string; text: string } | null;
+  newDeck?: boolean;
+};
+
+export type RespondPayload =
+  | { answers: Record<string, string> }
+  | { allow: boolean }
+  | { cancel: true };
+
+export type AgentStreamEvent =
+  | { type: 'session'; session: AgentSessionSummary }
+  | { type: 'session-removed'; sessionId: string }
+  | { type: 'item'; sessionId: string; item: AgentItem }
+  | { type: 'delta'; sessionId: string; itemId: string; text: string }
+  | { type: 'truncate'; sessionId: string; itemId: string }
+  | { type: 'slide-renamed'; from: string; to: string };
+
+export function sessionSummary(session: AgentSession): AgentSessionSummary {
+  const {
+    providerSessionId: _p,
+    providerCheckpoint: _c,
+    trimmed: _t,
+    items: _i,
+    ...summary
+  } = session;
+  return summary;
+}

package/src/app/components/agent/agent-dock.tsx

@@ -0,0 +1,35 @@
+import { Sparkles } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { useAgentDock, useAgentStatus } from '@/lib/agent/use-agent';
+import { useLocale } from '@/lib/use-locale';
+import { ProviderLogo } from './provider-logo';
+
+export const AGENT_DOCK_W = 380;
+
+export function AgentToggleButton() {
+  const t = useLocale();
+  const { open, toggle } = useAgentDock();
+  const { provider } = useAgentStatus();
+  if (import.meta.env.PROD) return null;
+  return (
+    <Button
+      size="sm"
+      variant={open ? 'default' : 'ghost'}
+      onClick={toggle}
+      aria-pressed={open}
+      aria-label={t.agent.openTitle}
+      title={t.agent.openTitle}
+      data-agent-ui
+    >
+      {provider ? (
+        <ProviderLogo provider={provider.id} className="size-3.5" />
+      ) : (
+        <Sparkles className="size-3.5" />
+      )}
+      <span className="hidden lg:inline">{t.agent.open}</span>
+      <kbd className="ml-1 hidden rounded-[3px] bg-foreground/10 px-1 font-mono text-[9.5px] tracking-[0.04em] lg:inline">
+        A
+      </kbd>
+    </Button>
+  );
+}

package/src/app/components/agent/agent-markdown.tsx

@@ -0,0 +1,45 @@
+import { useMemo } from 'react';
+import { NoteMarkdown } from '@/components/note-markdown';
+
+type Segment = { type: 'text'; text: string } | { type: 'code'; code: string };
+
+const FENCE = /^```[^\n]*\n([\s\S]*?)\n?```\s*$/m;
+
+function splitFences(text: string): Segment[] {
+  const segments: Segment[] = [];
+  let rest = text;
+  while (rest) {
+    const m = FENCE.exec(rest);
+    if (!m) {
+      segments.push({ type: 'text', text: rest });
+      break;
+    }
+    const before = rest.slice(0, m.index);
+    if (before.trim()) segments.push({ type: 'text', text: before });
+    segments.push({ type: 'code', code: m[1] });
+    rest = rest.slice(m.index + m[0].length);
+  }
+  return segments;
+}
+
+export function AgentMarkdown({ text }: { text: string }) {
+  const segments = useMemo(() => splitFences(text), [text]);
+  return (
+    <div className="space-y-2 text-[12.5px] leading-[1.55] [&_ol]:my-1 [&_ul]:my-1">
+      {segments.map((segment, i) =>
+        segment.type === 'code' ? (
+          <pre
+            // biome-ignore lint/suspicious/noArrayIndexKey: static parse output, never reordered
+            key={i}
+            className="overflow-x-auto rounded-[6px] border border-hairline bg-muted/60 px-2.5 py-2 font-mono text-[11px] leading-relaxed"
+          >
+            <code>{segment.code}</code>
+          </pre>
+        ) : (
+          // biome-ignore lint/suspicious/noArrayIndexKey: static parse output, never reordered
+          <NoteMarkdown key={i} text={segment.text} />
+        ),
+      )}
+    </div>
+  );
+}