@agimon-ai/doompi-prompt 0.0.1-alpha.0

package/src/types/webPrompts.ts

@@ -0,0 +1,61 @@
+/**
+ * The vocabulary this package's HTTP API and its cockpit plugin share.
+ *
+ * DESIGN PATTERNS:
+ * - Wire JSON only, no node types, so the browser bundle can carry this module.
+ * - Route paths and URL building live here, so a page never assembles a URL of
+ *   its own and the two halves cannot drift.
+ * - Saved prompts are machine-wide, so no route names a session.
+ *
+ * AVOID:
+ * - Importing anything from src/services or src/adapters here.
+ */
+
+/** Where a host mounts this package's API; the segment after /api/plugin/. */
+export const API_BASE_PATH = 'prompts';
+
+/** The collection, relative to the API's own mount. */
+export const PROMPTS_PATH = '/prompts';
+
+/** One saved prompt, relative to the API's own mount. */
+export function promptPath(name: string): string {
+  return `${PROMPTS_PATH}/${encodeURIComponent(name)}`;
+}
+
+/** The absolute URL a page fetches for the collection. */
+export function promptsUrl(): string {
+  return `/api/plugin/${API_BASE_PATH}${PROMPTS_PATH}`;
+}
+
+/** The absolute URL a page fetches for one saved prompt. */
+export function promptUrl(name: string): string {
+  return `/api/plugin/${API_BASE_PATH}${promptPath(name)}`;
+}
+
+/** One saved prompt, as the cockpit shows it. */
+export interface SavedPromptView {
+  name: string;
+  description: string;
+  text: string;
+}
+
+/** What the collection route answers with. */
+export interface SavedPromptListResponse {
+  prompts: readonly SavedPromptView[];
+}
+
+/** What a write route answers with. */
+export interface SavedPromptWriteResponse {
+  prompt: SavedPromptView;
+  /** True when the write replaced a template that already existed. */
+  replaced: boolean;
+}
+
+/** What every route answers with when it refuses. */
+export interface PromptErrorResponse {
+  error: string;
+}
+
+export function isPromptErrorResponse(value: unknown): value is PromptErrorResponse {
+  return typeof value === 'object' && value !== null && typeof (value as PromptErrorResponse).error === 'string';
+}

package/src/web/PromptEditor.tsx

@@ -0,0 +1,57 @@
+import { Button, Input, Textarea } from '@agimon-ai/doompi-web-components';
+import { canSaveDraft, type DraftState } from './promptsActions.ts';
+
+/**
+ * The create and edit form for one saved prompt.
+ *
+ * DESIGN PATTERNS:
+ * - Presentational: the draft and every action come from props, so the panel
+ *   owns the state and this file stays a form.
+ * - Save stays disabled until the draft could actually be written, which keeps
+ *   the obvious mistakes off the network without duplicating the server rule.
+ *
+ * AVOID:
+ * - Validating the name shape here. The API owns that rule and reports it.
+ */
+
+export interface PromptEditorProps {
+  draft: DraftState;
+  busy: boolean;
+  onChange: (draft: DraftState) => void;
+  onSave: () => void;
+  onCancel: () => void;
+}
+
+export function PromptEditor({ draft, busy, onChange, onSave, onCancel }: PromptEditorProps) {
+  return (
+    <div data-testid="prompts-editor" className="flex flex-col gap-2 rounded-[5px] border border-doom-border p-2">
+      <Input
+        data-testid="prompts-name"
+        value={draft.name}
+        placeholder="name, lowercase letters, digits and dashes"
+        onChange={(event) => onChange({ ...draft, name: event.target.value })}
+      />
+      <Textarea
+        data-testid="prompts-text"
+        rows={8}
+        value={draft.text}
+        placeholder="the prompt text"
+        onChange={(event) => onChange({ ...draft, text: event.target.value })}
+      />
+      <div className="flex items-center gap-2">
+        <Button
+          size="xs"
+          className="text-[9px]"
+          data-testid="prompts-save"
+          disabled={busy || !canSaveDraft(draft)}
+          onClick={onSave}
+        >
+          save
+        </Button>
+        <Button variant="ghost" size="xs" className="text-[9px]" data-testid="prompts-cancel" onClick={onCancel}>
+          cancel
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/web/PromptPickerList.tsx

@@ -0,0 +1,108 @@
+import { Button, Input } from '@agimon-ai/doompi-web-components';
+import type { SavedPromptView } from '../types/webPrompts.ts';
+import { PromptEditor } from './PromptEditor.tsx';
+import type { DraftState } from './promptsActions.ts';
+import { filterPrompts } from './promptsActions.ts';
+
+/**
+ * The body of the prompt dialog: filter, rows, and the editor when one is open.
+ *
+ * DESIGN PATTERNS:
+ * - Presentational and outside the dialog chrome, so it renders without a DOM
+ *   portal and the tests can see it.
+ * - Sending is the row's primary action; managing sits to its right.
+ *
+ * AVOID:
+ * - Fetching here. The dialog owns the calls, this owns the markup.
+ */
+
+export interface PromptPickerListProps {
+  prompts: readonly SavedPromptView[];
+  filter: string;
+  draft: DraftState | undefined;
+  busy: boolean;
+  error: string;
+  onFilterChange: (filter: string) => void;
+  onSend: (prompt: SavedPromptView) => void;
+  onEdit: (prompt: SavedPromptView) => void;
+  onDelete: (name: string) => void;
+  onDraftChange: (draft: DraftState) => void;
+  onSave: () => void;
+  onCancelDraft: () => void;
+}
+
+export function PromptPickerList(props: PromptPickerListProps) {
+  const visible = filterPrompts(props.prompts, props.filter);
+
+  return (
+    <div data-testid="prompts-picker" className="flex flex-col gap-2">
+      <Input
+        data-testid="prompts-filter"
+        value={props.filter}
+        placeholder="filter"
+        onChange={(event) => props.onFilterChange(event.target.value)}
+      />
+
+      {props.error === '' ? null : (
+        <span className="text-[10px] text-doom-red" data-testid="prompts-error">
+          {props.error}
+        </span>
+      )}
+
+      {visible.length === 0 ? (
+        <p data-testid="prompts-empty" className="text-[11px] text-doom-faint">
+          {props.prompts.length === 0 ? 'no saved prompts yet' : 'nothing matches that filter'}
+        </p>
+      ) : null}
+
+      {visible.map((prompt) => (
+        <div
+          key={prompt.name}
+          data-testid={`prompts-item-${prompt.name}`}
+          className="flex items-center gap-2 rounded-[5px] px-2 py-1 text-[11px] text-doom-text hover:bg-doom-panel"
+        >
+          <Button
+            variant="ghost"
+            size="xs"
+            className="min-w-0 flex-1 justify-start text-left text-[11px]"
+            data-testid={`prompts-send-${prompt.name}`}
+            title="send this prompt to the focused session"
+            onClick={() => props.onSend(prompt)}
+          >
+            <span className="min-w-0 flex-1 truncate font-bold">/{prompt.name}</span>
+            <span className="min-w-0 flex-1 truncate text-[9px] text-doom-faint">{prompt.description}</span>
+          </Button>
+          <Button
+            variant="ghost"
+            size="xs"
+            className="text-[9px]"
+            data-testid={`prompts-edit-${prompt.name}`}
+            onClick={() => props.onEdit(prompt)}
+          >
+            edit
+          </Button>
+          <Button
+            variant="ghost"
+            size="xs"
+            className="text-[9px]"
+            data-testid={`prompts-delete-${prompt.name}`}
+            disabled={props.busy}
+            onClick={() => props.onDelete(prompt.name)}
+          >
+            delete
+          </Button>
+        </div>
+      ))}
+
+      {props.draft === undefined ? null : (
+        <PromptEditor
+          draft={props.draft}
+          busy={props.busy}
+          onChange={props.onDraftChange}
+          onSave={props.onSave}
+          onCancel={props.onCancelDraft}
+        />
+      )}
+    </div>
+  );
+}

package/src/web/PromptsActivitySection.tsx

@@ -0,0 +1,69 @@
+import { Button } from '@agimon-ai/doompi-web-components';
+import type { WebPluginSlotProps } from '@agimon-ai/doompi-web-contracts';
+import { useEffect, useState } from 'react';
+import type { SavedPromptView } from '../types/webPrompts.ts';
+import { PromptsDialog } from './PromptsDialog.tsx';
+import { fetchSavedPrompts } from './promptsApi.ts';
+
+/**
+ * The prompts group's body in the activity dock.
+ *
+ * DESIGN PATTERNS:
+ * - One line and one action, like the agents and workflows groups: the dock is
+ *   a status surface, so the library itself opens in a dialog over the
+ *   conversation rather than pushing the reader into another page.
+ * - The count is read once on mount and again whenever the dialog closes,
+ *   because a write inside it is the only thing that changes the number.
+ *
+ * AVOID:
+ * - Rendering the library here. A dock group is a summary.
+ */
+
+export function PromptsActivitySection({ sessionId, sendSessionFrame }: WebPluginSlotProps) {
+  const [prompts, setPrompts] = useState<readonly SavedPromptView[]>([]);
+  const [open, setOpen] = useState(false);
+  const [error, setError] = useState('');
+
+  useEffect(() => {
+    if (open) return undefined;
+    const controller = new AbortController();
+    void fetchSavedPrompts(controller.signal).then((result) => {
+      if (controller.signal.aborted) return;
+      if ('error' in result) setError(result.error);
+      else {
+        setError('');
+        setPrompts(result.prompts);
+      }
+    });
+    return () => controller.abort();
+  }, [open]);
+
+  const summary = error !== '' ? error : prompts.length === 0 ? 'idle' : `${String(prompts.length)} saved`;
+
+  return (
+    <div data-testid="activity-section-prompts" className="flex flex-col gap-0.5">
+      <div className="flex items-center gap-2 px-1">
+        <p data-testid="activity-summary-prompts" className="text-[10px] text-doom-faint">
+          {summary}
+        </p>
+        <Button
+          variant="link"
+          size="xs"
+          data-testid="activity-prompts-open"
+          className="px-0"
+          onClick={() => setOpen(true)}
+        >
+          send a prompt
+        </Button>
+      </div>
+
+      <PromptsDialog
+        open={open}
+        prompts={prompts}
+        sessionId={sessionId}
+        onOpenChange={setOpen}
+        onSend={sendSessionFrame}
+      />
+    </div>
+  );
+}

package/src/web/PromptsDialog.tsx

@@ -0,0 +1,111 @@
+import {
+  Button,
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@agimon-ai/doompi-web-components';
+import type { SessionFrameSender } from '@agimon-ai/doompi-web-contracts';
+import { useState } from 'react';
+import type { SavedPromptView } from '../types/webPrompts.ts';
+import { PromptPickerList } from './PromptPickerList.tsx';
+import { commitDraft, type DraftState, draftOf, EMPTY_DRAFT, promptFrame } from './promptsActions.ts';
+import { deleteSavedPrompt, saveSavedPrompt } from './promptsApi.ts';
+
+/**
+ * The prompt picker, opened from the activity dock.
+ *
+ * DESIGN PATTERNS:
+ * - Picking sends. A saved prompt is a message the reader already wrote, so the
+ *   primary action submits it to the focused session and closes the dialog.
+ * - Managing is secondary and lives in the same dialog, because a library with
+ *   no way to fix an entry is a library nobody trusts.
+ * - This file is chrome and state; the rows are PromptPickerList.
+ *
+ * AVOID:
+ * - Sending with no session focused. There would be nowhere for it to land.
+ */
+
+const MUTATION_API = { save: saveSavedPrompt, remove: deleteSavedPrompt };
+const NO_SESSION = 'Focus a session first: a prompt has to be sent somewhere.';
+
+export interface PromptsDialogProps {
+  open: boolean;
+  prompts: readonly SavedPromptView[];
+  sessionId: string | null;
+  onOpenChange: (open: boolean) => void;
+  onSend: SessionFrameSender;
+}
+
+export function PromptsDialog({ open, prompts, sessionId, onOpenChange, onSend }: PromptsDialogProps) {
+  const [filter, setFilter] = useState('');
+  const [draft, setDraft] = useState<DraftState | undefined>(undefined);
+  const [error, setError] = useState('');
+  const [busy, setBusy] = useState(false);
+
+  const send = (prompt: SavedPromptView): void => {
+    if (sessionId === null) {
+      setError(NO_SESSION);
+      return;
+    }
+    onSend(sessionId, promptFrame(prompt.text));
+    onOpenChange(false);
+  };
+
+  const runMutation = async (mutation: Promise<{ error: string } | undefined>): Promise<void> => {
+    setBusy(true);
+    const failure = await mutation;
+    setBusy(false);
+    if (failure) {
+      setError(failure.error);
+      return;
+    }
+    setDraft(undefined);
+    // The activity section reloads the library whenever this dialog closes.
+    onOpenChange(false);
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent data-testid="prompts-dialog">
+        <DialogHeader>
+          <DialogTitle>prompts</DialogTitle>
+          <DialogDescription>pick one to send it to this session</DialogDescription>
+        </DialogHeader>
+
+        <DialogBody>
+          <PromptPickerList
+            prompts={prompts}
+            filter={filter}
+            draft={draft}
+            busy={busy}
+            error={error}
+            onFilterChange={setFilter}
+            onSend={send}
+            onEdit={(prompt) => setDraft(draftOf(prompt))}
+            onDelete={(name) => void runMutation(deleteSavedPrompt(name))}
+            onDraftChange={setDraft}
+            onSave={() => void runMutation(draft ? commitDraft(draft, MUTATION_API) : Promise.resolve(undefined))}
+            onCancelDraft={() => setDraft(undefined)}
+          />
+        </DialogBody>
+
+        <DialogFooter>
+          <Button
+            variant="ghost"
+            size="xs"
+            className="text-[9px]"
+            data-testid="prompts-new"
+            disabled={busy}
+            onClick={() => setDraft(EMPTY_DRAFT)}
+          >
+            new
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/web/index.ts

@@ -0,0 +1,32 @@
+import { defineWebPlugin } from '@agimon-ai/doompi-web-contracts';
+import { PromptsActivitySection } from './PromptsActivitySection.tsx';
+
+/**
+ * This package's cockpit presence: one activity group.
+ *
+ * No tab. The library is not a place to sit in, it is something reached for
+ * mid-conversation, so it lives in the activity dock next to agents, runners
+ * and workflows, and the picking happens in a dialog over the conversation.
+ *
+ * The group is always visible and never claims background work: saving a
+ * prompt is not a running job, and an empty library still needs the entry
+ * point that fills it.
+ */
+const promptsActivitySource = {
+  subscribe: () => () => undefined,
+  isActive: () => false,
+};
+
+export const webPlugin = defineWebPlugin({
+  id: 'prompts',
+  activityGroups: [
+    {
+      name: 'prompts',
+      // The TUI's SPC e p, so the two surfaces are reached the same way.
+      keys: 'e p',
+      activeSource: promptsActivitySource,
+      order: 40,
+    },
+  ],
+  activitySections: [{ id: 'prompts', component: PromptsActivitySection }],
+});

package/src/web/promptsActions.ts

@@ -0,0 +1,72 @@
+import type { SavedPromptView } from '../types/webPrompts.ts';
+
+/**
+ * What the panel does to the library, independent of how it is drawn.
+ *
+ * DESIGN PATTERNS:
+ * - The API is a parameter, so the ordering rules here are testable without a
+ *   transport, and the panel keeps only state and markup.
+ * - A rename is a write followed by a delete of the old template, never the
+ *   other way round: a failed write must not lose the original.
+ *
+ * AVOID:
+ * - Reporting success when the cleanup delete failed. The library would then
+ *   hold two copies and the page would show a state nobody chose.
+ */
+
+export interface DraftState {
+  name: string;
+  text: string;
+  /** The name being replaced, or '' while creating. */
+  original: string;
+}
+
+export interface PromptsMutationApi {
+  save(name: string, text: string): Promise<{ error: string } | undefined>;
+  remove(name: string): Promise<{ error: string } | undefined>;
+}
+
+/** The frame the cockpit sends to submit a message to a session. */
+export function promptFrame(text: string): Record<string, unknown> {
+  return { type: 'prompt', message: text };
+}
+
+/** Substring matching over the two columns a row shows. */
+export function filterPrompts(prompts: readonly SavedPromptView[], filter: string): readonly SavedPromptView[] {
+  const needle = filter.trim().toLowerCase();
+  if (needle === '') return prompts;
+  return prompts.filter(
+    (prompt) => prompt.name.toLowerCase().includes(needle) || prompt.description.toLowerCase().includes(needle),
+  );
+}
+
+export const EMPTY_DRAFT: DraftState = { name: '', text: '', original: '' };
+
+export function draftOf(prompt: SavedPromptView): DraftState {
+  return { name: prompt.name, text: prompt.text, original: prompt.name };
+}
+
+/** Whether the draft is complete enough to send. */
+export function canSaveDraft(draft: DraftState): boolean {
+  return draft.name.trim().length > 0 && draft.text.trim().length > 0;
+}
+
+/** The template a rename leaves behind, or undefined when nothing was renamed. */
+export function renamedFrom(draft: DraftState): string | undefined {
+  const name = draft.name.trim();
+  return draft.original !== '' && draft.original !== name ? draft.original : undefined;
+}
+
+/** Writes the draft, then clears the template a rename orphaned. */
+export async function commitDraft(draft: DraftState, api: PromptsMutationApi): Promise<{ error: string } | undefined> {
+  const name = draft.name.trim();
+  const failure = await api.save(name, draft.text);
+  if (failure) return failure;
+
+  const orphan = renamedFrom(draft);
+  if (orphan === undefined) return undefined;
+
+  const cleanup = await api.remove(orphan);
+  if (cleanup) return { error: `Saved /${name}, but /${orphan} could not be removed: ${cleanup.error}` };
+  return undefined;
+}

package/src/web/promptsApi.ts

@@ -0,0 +1,88 @@
+import { sealedTransport } from '@agimon-ai/doompi-web-security/browser';
+import {
+  isPromptErrorResponse,
+  promptsUrl,
+  promptUrl,
+  type SavedPromptListResponse,
+  type SavedPromptView,
+} from '../types/webPrompts.ts';
+
+/**
+ * The browser half of the prompt library API.
+ *
+ * DESIGN PATTERNS:
+ * - Every call goes through the sealed transport, like every other cockpit
+ *   plugin, so a remote listener gets the same protection the host expects.
+ * - Failures come back as values, never thrown: the panel shows one message
+ *   next to the thing that failed instead of losing the page to an error.
+ * - URLs are built by src/types, never assembled here.
+ *
+ * AVOID:
+ * - Caching answers in this module. The panel owns state.
+ */
+
+const UNREACHABLE = 'The hub did not answer.';
+const ABORT_ERROR = 'AbortError';
+
+interface Failure {
+  error: string;
+}
+
+function isAbort(error: unknown): boolean {
+  return error instanceof DOMException && error.name === ABORT_ERROR;
+}
+
+async function readError(response: Response): Promise<string> {
+  try {
+    const body: unknown = await response.json();
+    if (isPromptErrorResponse(body)) return body.error;
+  } catch {
+    // A body that is not JSON tells the reader nothing useful; the status does.
+  }
+  return `The hub answered ${String(response.status)}.`;
+}
+
+export async function fetchSavedPrompts(
+  signal?: AbortSignal,
+): Promise<{ prompts: readonly SavedPromptView[] } | Failure> {
+  let response: Response;
+  try {
+    response = await sealedTransport.fetch(promptsUrl(), signal ? { signal } : {});
+  } catch (error) {
+    // An aborted request is the caller replacing it, not a failure to report.
+    if (isAbort(error)) return { error: '' };
+    return { error: UNREACHABLE };
+  }
+
+  if (!response.ok) return { error: await readError(response) };
+  try {
+    const body = (await response.json()) as SavedPromptListResponse;
+    return { prompts: body.prompts ?? [] };
+  } catch {
+    return { error: 'The hub sent a malformed prompt list.' };
+  }
+}
+
+export async function saveSavedPrompt(name: string, text: string): Promise<Failure | undefined> {
+  let response: Response;
+  try {
+    response = await sealedTransport.fetch(promptUrl(name), {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ text }),
+    });
+  } catch {
+    return { error: UNREACHABLE };
+  }
+  return response.ok ? undefined : { error: await readError(response) };
+}
+
+export async function deleteSavedPrompt(name: string): Promise<Failure | undefined> {
+  let response: Response;
+  try {
+    response = await sealedTransport.fetch(promptUrl(name), { method: 'DELETE' });
+  } catch {
+    return { error: UNREACHABLE };
+  }
+  return response.ok ? undefined : { error: await readError(response) };
+}

package/src/web/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noImplicitAny": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [".", "../types", "../exports/webClient.ts", "../../tests/web"]
+}