@mounaji_npm/guided-builder

Copilot-guided entity builder: the generic pattern behind CognitionDesk's Agent Studio — a chat co-pilot that fills a creation form live while talking to the user. Reusable for any entity: assistants, workflows, squads, catalogs, appointments.

What's inside

Core (React-free, node --test covered)

• createDraftStore({ initial }) — the draft's single source of truth:
  • apply(patch, {source: 'user'|'ai'|'user-consented'|'system', toolCallId, label}) with change detection;
  • provenance per field (who wrote it last) → dirtyFields() = user-owned fields the AI must not overwrite silently;
  • bounded history with revert(entryId) (reverts are user acts);
  • digest() — compact LLM-context summary (long strings → previews, arrays → counts) so the copilot knows the form state without read round-trips;
  • subscribe/getSnapshot ready for useSyncExternalStore.
• DRAFT_TOOL_NAMES / validateToolArgs — frontend mirror of the backend draft-tool contracts (draft_read, draft_set_field, draft_write_prompt, draft_add_instruction_block, draft_update_skills, draft_grant_capabilities, draft_configure_tools).
• createToolHandlers(store, opts) — generic async handlers keyed by tool name, ready to plug into a client tool executor. Options adapt them to any entity (fields allowlist with validate/coerce, field names for prompt/blocks/skills/scopes/tools) and wire the sensitive-item consent flow:
  • classifySensitive(kind, items) → which items need consent (and why);
  • requestConsent({kind, items}) → your human-in-loop UI; approved items apply with provenance user-consented, everything else stays pendingConsent (fail-closed: no callback, error or timeout ⇒ not granted);
  • results report {applied, rejected, pendingConsent} so the LLM narrates honestly.

React

• useGuidedDraft(store) — live snapshot + bound actions.
• BuilderShell — slot layout (header / guide chat / section nav / content), side or top guide.
• GuidePanel — props-driven chat surface with streaming cursor and revertable tool-activity chips. No transport inside: the host streams however it wants.
• SectionNav — progress-circuit rail (complete/active/warning states).
• ProgressMeter — completeness meter for the header.
• AiGlow — provenance halo + "AI" chip (with revert) around any field the copilot wrote.

All components use inline styles themable via CSS variables (--gb-*).

Usage sketch

import {
  createDraftStore, createToolHandlers,
  useGuidedDraft, BuilderShell, GuidePanel, SectionNav, ProgressMeter, AiGlow,
} from '@mounaji_npm/guided-builder';

const store = createDraftStore({ initial: buildAssistantDraft() });

const handlers = createToolHandlers(store, {
  fields: { name: {}, description: {}, category: {}, model: {}, temperature: { coerce: Number } },
  resolveSkills: (ids) => api.post('/skills/resolve', { skillIds: ids }),
  classifySensitive: (kind, items) => myCatalog.sensitiveSubset(kind, items),
  requestConsent: (req) => showHumanInLoopPrompt(req), // e.g. @mounaji_npm/human-in-loop
  getQuota: () => ({ used: 3, limit: 5 }),
});

// register each handler with your client tool executor:
for (const [name, fn] of Object.entries(handlers)) registerClientTool(name, fn);

// each chat turn, give the LLM the current form state:
const systemPromptExtra = JSON.stringify(store.digest());

The backend side (tool definitions the LLM calls) lives in the consuming platform — in CognitionDesk: mounaji-backendv3/src/services/tools/definitions/studioDraftTools.js, gated to platforms: ['studio'].

Tests

npm test        # node --test over core
npm run build   # vite lib build (es + umd)