@absolutejs/ai 0.0.39 → 0.0.41

package/dist/ai/ui/index.js

@@ -104,6 +104,12 @@ var FORM_FIELD_TYPES = [
   "checkbox",
   "password"
 ];
+var PLAN_STEP_STATUSES = [
+  "pending",
+  "active",
+  "done",
+  "error"
+];
 var CHART_MAX_SERIES = 8;
 var CHART_MAX_POINTS = 24;
 var TABLE_MAX_COLUMNS = 8;
@@ -112,14 +118,28 @@ var STAT_TILES_MAX = 6;
 var UI_ACTIONS_MAX = 3;
 var FORM_MAX_FIELDS = 8;
 var FORM_SELECT_MAX_OPTIONS = 12;
+var CHOICE_MAX_OPTIONS = 8;
+var CONFIRM_CONSEQUENCE_MAX_CHARS = 500;
+var DIFF_MAX_FILES = 6;
+var DIFF_MAX_LINES = 400;
+var PLAN_MAX_STEPS = 12;
+var CREDENTIAL_MAX_KEYS = 8;
+var CARD_ID_MAX_CHARS = 64;
 var LABEL_MAX_CHARS = 80;
 var TITLE_MAX_CHARS = 120;
 var CELL_MAX_CHARS = 160;
 var UNIT_MAX_CHARS = 8;
 var ACTION_LABEL_MAX_CHARS = 40;
 var DESCRIPTION_MAX_CHARS = 280;
+var BADGE_MAX_CHARS = 24;
+var DIFF_PATH_MAX_CHARS = 260;
+var DIFF_LINE_MAX_CHARS = 300;
+var DOCS_URL_MAX_CHARS = 300;
 var ACTION_TOOL_PATTERN = /^[a-z][a-z0-9_]{1,63}$/;
 var FIELD_NAME_PATTERN = /^[a-z][a-zA-Z0-9_]{0,63}$/;
+var CARD_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+var ENV_KEY_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
+var DOCS_URL_PATTERN = /^https?:\/\//;
 var isRecord = (value) => typeof value === "object" && value !== null;
 var cleanString = (value, maxChars) => typeof value === "string" && value.trim().length > 0 ? value.trim().slice(0, maxChars) : null;
 var cleanStringArray = (value, maxItems, maxChars) => {
@@ -143,6 +163,17 @@ var cleanNumberArray = (value, maxItems) => {
   }
   return cleaned;
 };
+var cleanId = (value) => {
+  if (typeof value !== "string")
+    return null;
+  const trimmed = value.trim().slice(0, CARD_ID_MAX_CHARS);
+  return CARD_ID_PATTERN.test(trimmed) ? trimmed : null;
+};
+var applyCardId = (spec, raw) => {
+  const cardId = cleanId(raw);
+  if (cardId)
+    spec.cardId = cardId;
+};
 var parseUiActions = (value) => {
   if (!Array.isArray(value) || value.length === 0)
     return;
@@ -177,6 +208,22 @@ var ACTIONS_SCHEMA = {
   },
   type: "array"
 };
+var CARD_ID_SCHEMA = {
+  description: "Optional stable card identity (letters/digits/_/-, max 64 chars). Re-emit a card with the SAME cardId to update the earlier render in place instead of adding a new card.",
+  type: "string"
+};
+var ACTION_BINDING_SCHEMA = {
+  properties: {
+    input: {
+      description: "The exact tool input to send (real ids you looked up, never placeholders)",
+      type: "object"
+    },
+    label: { description: "Button label", type: "string" },
+    tool: { description: "The tool name to invoke", type: "string" }
+  },
+  required: ["label", "tool", "input"],
+  type: "object"
+};
 var parseChartSpec = (input) => {
   if (!isRecord(input))
     return null;
@@ -216,6 +263,7 @@ var parseChartSpec = (input) => {
   const actions = parseUiActions(input.actions);
   if (actions)
     spec.actions = actions;
+  applyCardId(spec, input.cardId);
   return spec;
 };
 var parseTableSpec = (input) => {
@@ -242,6 +290,7 @@ var parseTableSpec = (input) => {
   const actions = parseUiActions(input.actions);
   if (actions)
     spec.actions = actions;
+  applyCardId(spec, input.cardId);
   return spec;
 };
 var parseStatTilesSpec = (input) => {
@@ -270,6 +319,7 @@ var parseStatTilesSpec = (input) => {
   const actions = parseUiActions(input.actions);
   if (actions)
     spec.actions = actions;
+  applyCardId(spec, input.cardId);
   return spec;
 };
 var parseFormField = (raw) => {
@@ -322,6 +372,188 @@ var parseFormSpec = (input) => {
   const description = cleanString(input.description, DESCRIPTION_MAX_CHARS);
   if (description)
     spec.description = description;
+  applyCardId(spec, input.cardId);
+  return spec;
+};
+var parseChoiceOption = (raw) => {
+  if (!isRecord(raw))
+    return null;
+  const id = cleanId(raw.id);
+  const label = cleanString(raw.label, LABEL_MAX_CHARS);
+  if (!id || !label)
+    return null;
+  const option = { id, label };
+  const description = cleanString(raw.description, DESCRIPTION_MAX_CHARS);
+  if (description)
+    option.description = description;
+  const badge = cleanString(raw.badge, BADGE_MAX_CHARS);
+  if (badge)
+    option.badge = badge;
+  return option;
+};
+var parseChoiceSpec = (input) => {
+  if (!isRecord(input))
+    return null;
+  const title = cleanString(input.title, TITLE_MAX_CHARS);
+  const [submit] = parseUiActions([input.submit]) ?? [];
+  if (!title || !submit)
+    return null;
+  if (!Array.isArray(input.options) || input.options.length === 0)
+    return null;
+  const options = [];
+  const seen = new Set;
+  for (const raw of input.options.slice(0, CHOICE_MAX_OPTIONS)) {
+    const option = parseChoiceOption(raw);
+    if (!option || seen.has(option.id))
+      return null;
+    seen.add(option.id);
+    options.push(option);
+  }
+  const spec = { options, submit, title };
+  const description = cleanString(input.description, DESCRIPTION_MAX_CHARS);
+  if (description)
+    spec.description = description;
+  if (input.multi === true)
+    spec.multi = true;
+  applyCardId(spec, input.cardId);
+  return spec;
+};
+var parseConfirmSpec = (input) => {
+  if (!isRecord(input))
+    return null;
+  const title = cleanString(input.title, TITLE_MAX_CHARS);
+  const consequence = cleanString(input.consequence, CONFIRM_CONSEQUENCE_MAX_CHARS);
+  const confirmLabel = cleanString(input.confirmLabel, ACTION_LABEL_MAX_CHARS);
+  const [confirm] = parseUiActions([input.confirm]) ?? [];
+  if (!title || !consequence || !confirmLabel || !confirm)
+    return null;
+  const spec = { confirm, confirmLabel, consequence, title };
+  const cancelLabel = cleanString(input.cancelLabel, ACTION_LABEL_MAX_CHARS);
+  if (cancelLabel)
+    spec.cancelLabel = cancelLabel;
+  if (input.danger === true)
+    spec.danger = true;
+  applyCardId(spec, input.cardId);
+  return spec;
+};
+var parseDiffFile = (raw, budget) => {
+  if (!isRecord(raw))
+    return null;
+  const path = cleanString(raw.path, DIFF_PATH_MAX_CHARS);
+  if (!path || typeof raw.diff !== "string" || raw.diff.trim().length === 0) {
+    return null;
+  }
+  const lines = raw.diff.split(/\r?\n/).map((line) => line.slice(0, DIFF_LINE_MAX_CHARS));
+  const kept = lines.slice(0, Math.max(budget.remaining, 0));
+  budget.remaining -= kept.length;
+  const file = { diff: kept.join(`
+`), path };
+  if (raw.truncated === true || kept.length < lines.length) {
+    file.truncated = true;
+  }
+  return file;
+};
+var parseDiffSpec = (input) => {
+  if (!isRecord(input))
+    return null;
+  const title = cleanString(input.title, TITLE_MAX_CHARS);
+  const [apply] = parseUiActions([input.apply]) ?? [];
+  if (!title || !apply)
+    return null;
+  if (!Array.isArray(input.files) || input.files.length === 0)
+    return null;
+  const budget = { remaining: DIFF_MAX_LINES };
+  const files = [];
+  for (const raw of input.files.slice(0, DIFF_MAX_FILES)) {
+    const file = parseDiffFile(raw, budget);
+    if (!file)
+      return null;
+    files.push(file);
+  }
+  const spec = { apply, files, title };
+  const [reject] = parseUiActions([input.reject]) ?? [];
+  if (reject)
+    spec.reject = reject;
+  const note = cleanString(input.note, DESCRIPTION_MAX_CHARS);
+  if (note)
+    spec.note = note;
+  applyCardId(spec, input.cardId);
+  return spec;
+};
+var parsePlanStep = (raw) => {
+  if (!isRecord(raw))
+    return null;
+  const id = cleanId(raw.id);
+  const label = cleanString(raw.label, LABEL_MAX_CHARS);
+  const status = PLAN_STEP_STATUSES.find((entry) => entry === raw.status);
+  if (!id || !label || !status)
+    return null;
+  const step = { id, label, status };
+  const detail = cleanString(raw.detail, CELL_MAX_CHARS);
+  if (detail)
+    step.detail = detail;
+  return step;
+};
+var parsePlanSpec = (input) => {
+  if (!isRecord(input))
+    return null;
+  const title = cleanString(input.title, TITLE_MAX_CHARS);
+  if (!title)
+    return null;
+  if (!Array.isArray(input.steps) || input.steps.length === 0)
+    return null;
+  const steps = [];
+  const seen = new Set;
+  for (const raw of input.steps.slice(0, PLAN_MAX_STEPS)) {
+    const step = parsePlanStep(raw);
+    if (!step || seen.has(step.id))
+      return null;
+    seen.add(step.id);
+    steps.push(step);
+  }
+  const spec = { steps, title };
+  const note = cleanString(input.note, DESCRIPTION_MAX_CHARS);
+  if (note)
+    spec.note = note;
+  applyCardId(spec, input.cardId);
+  return spec;
+};
+var parseCredentialKey = (raw) => {
+  if (!isRecord(raw))
+    return null;
+  const key = typeof raw.key === "string" && ENV_KEY_PATTERN.test(raw.key) ? raw.key : null;
+  if (!key)
+    return null;
+  const entry = { key, secret: raw.secret !== false };
+  const label = cleanString(raw.label, LABEL_MAX_CHARS);
+  if (label)
+    entry.label = label;
+  const docsUrl = cleanString(raw.docsUrl, DOCS_URL_MAX_CHARS);
+  if (docsUrl && DOCS_URL_PATTERN.test(docsUrl))
+    entry.docsUrl = docsUrl;
+  if (typeof raw.isSet === "boolean")
+    entry.isSet = raw.isSet;
+  return entry;
+};
+var parseCredentialSpec = (input) => {
+  if (!isRecord(input))
+    return null;
+  const title = cleanString(input.title, TITLE_MAX_CHARS);
+  if (!title)
+    return null;
+  if (!Array.isArray(input.keys) || input.keys.length === 0)
+    return null;
+  const keys = [];
+  const seen = new Set;
+  for (const raw of input.keys.slice(0, CREDENTIAL_MAX_KEYS)) {
+    const entry = parseCredentialKey(raw);
+    if (!entry || seen.has(entry.key))
+      return null;
+    seen.add(entry.key);
+    keys.push(entry);
+  }
+  const spec = { keys, title };
+  applyCardId(spec, input.cardId);
   return spec;
 };
 var SERIES_SCHEMA = {
@@ -342,6 +574,7 @@ var chartCard = {
   inputSchema: {
     properties: {
       actions: ACTIONS_SCHEMA,
+      cardId: CARD_ID_SCHEMA,
       labels: {
         description: "Category labels — x-axis for bar/line, slice names for donut (max 24)",
         items: { type: "string" },
@@ -375,6 +608,7 @@ var tableCard = {
   inputSchema: {
     properties: {
       actions: ACTIONS_SCHEMA,
+      cardId: CARD_ID_SCHEMA,
       columns: {
         description: "Column headers (max 8)",
         items: { type: "string" },
@@ -399,6 +633,7 @@ var statTilesCard = {
   inputSchema: {
     properties: {
       actions: ACTIONS_SCHEMA,
+      cardId: CARD_ID_SCHEMA,
       tiles: {
         description: "The tiles (max 6)",
         items: {
@@ -431,6 +666,7 @@ var formCard = {
   description: `Render an inline form when you need SEVERAL structured inputs from the member before running a tool (task details, scheduling constraints, outreach parameters) — one form beats asking field-by-field in prose. Bind submit to one of YOUR tools with any values you already know pre-filled in submit.input; on submit the member's field values are merged into submit.input under each field's name and the tool runs exactly like a clicked action button. Field names must therefore be the tool's actual input property names. Never use it for values you could look up yourself. Use type "password" for sensitive values (API keys, secrets, credentials) — the host renders it masked and never pre-fill a value for it.`,
   inputSchema: {
     properties: {
+      cardId: CARD_ID_SCHEMA,
       description: {
         description: "Optional one-line helper text under the title",
         type: "string"
@@ -486,11 +722,229 @@ var formCard = {
   name: "render_form",
   parse: parseFormSpec
 };
+var choiceCard = {
+  ack: "(choice card rendered inline — the member picks an option, which runs the bound tool with their selection merged in. Do not re-ask in text; wait for the selection)",
+  description: "Render a structured choice card whenever the member must pick between concrete options (which plan, which duplicate record to keep, which time slot) — never ask them to 'reply 1 or 2' in prose. Give every option a stable id; on selection the host merges { choice: id } (or { choices: [ids] } when multi is true) into submit.input and invokes submit.tool exactly like a clicked action button, so put everything you already resolved into submit.input. Max 8 options.",
+  inputSchema: {
+    properties: {
+      cardId: CARD_ID_SCHEMA,
+      description: {
+        description: "Optional one-line helper text under the title",
+        type: "string"
+      },
+      multi: {
+        description: "Allow selecting several options — submits { choices: [ids] } instead of { choice: id }",
+        type: "boolean"
+      },
+      options: {
+        description: "The options to choose between (max 8)",
+        items: {
+          properties: {
+            badge: {
+              description: 'Tiny annotation beside the label, e.g. "recommended"',
+              type: "string"
+            },
+            description: {
+              description: "One-line explanation of the option",
+              type: "string"
+            },
+            id: {
+              description: "Stable option id merged into submit.input on selection (letters/digits/_/-)",
+              type: "string"
+            },
+            label: { description: "What the member sees", type: "string" }
+          },
+          required: ["id", "label"],
+          type: "object"
+        },
+        type: "array"
+      },
+      submit: {
+        ...ACTION_BINDING_SCHEMA,
+        description: "The submit binding: the tool to run once a choice is made. The selection is merged into input as { choice: id } (or { choices: [ids] })"
+      },
+      title: { description: "The decision being made", type: "string" }
+    },
+    required: ["title", "options", "submit"],
+    type: "object"
+  },
+  name: "render_choice",
+  parse: parseChoiceSpec
+};
+var confirmCard = {
+  ack: "(confirmation card rendered inline — NOTHING has run yet; the action only runs if the member clicks confirm. Do not claim or assume it happened; wait for the outcome)",
+  description: "Render an explicit confirmation card before any destructive or irreversible action (deleting data, sending money or bulk email, cancelling a subscription). State the consequence in plain language — exactly what will happen. TRUST CONTRACT: the host invokes confirm ONLY on a real member click, never on your say-so; hosts SHOULD mint an unforgeable server-side confirmation token at click time and require it on the downstream action, so a confirmation can never be fabricated in text. Set danger: true for destructive styling. Rendering this card is never itself consent.",
+  inputSchema: {
+    properties: {
+      cancelLabel: {
+        description: 'Optional dismiss label, e.g. "Keep project"',
+        type: "string"
+      },
+      cardId: CARD_ID_SCHEMA,
+      confirm: {
+        ...ACTION_BINDING_SCHEMA,
+        description: "The action to run ONLY when the member clicks confirm (fully-resolved input, real ids)"
+      },
+      confirmLabel: {
+        description: 'The confirm button label, e.g. "Delete project"',
+        type: "string"
+      },
+      consequence: {
+        description: "What will happen if confirmed, in plain language (max 500 chars)",
+        type: "string"
+      },
+      danger: {
+        description: "Render destructive (red) styling",
+        type: "boolean"
+      },
+      title: { description: "Short question being confirmed", type: "string" }
+    },
+    required: ["title", "consequence", "confirmLabel", "confirm"],
+    type: "object"
+  },
+  name: "render_confirm",
+  parse: parseConfirmSpec
+};
+var diffCard = {
+  ack: "(diff card rendered inline — the member reviews the changes and clicks apply or reject. Do not restate the diff in text and do not assume it was applied; wait for their decision)",
+  description: "Render proposed file changes as reviewable unified diffs before applying them (max 6 files and 400 diff lines total — oversized diffs are truncated for display with truncated: true, never rejected). The diffs are DISPLAY data: the host renders the +/- coloring and nothing executes from the text. Bind apply (and optionally reject) to YOUR tools with fully-resolved input; hosts SHOULD route apply through a click-minted server-side token exactly like a confirmation card, because applying changes is destructive.",
+  inputSchema: {
+    properties: {
+      apply: {
+        ...ACTION_BINDING_SCHEMA,
+        description: "The action that applies the changes when the member clicks it"
+      },
+      cardId: CARD_ID_SCHEMA,
+      files: {
+        description: "The changed files (max 6, 400 diff lines total)",
+        items: {
+          properties: {
+            diff: {
+              description: "Unified diff text for this file (display only)",
+              type: "string"
+            },
+            path: { description: "File path being changed", type: "string" },
+            truncated: {
+              description: "Set true if you already cut the diff for size",
+              type: "boolean"
+            }
+          },
+          required: ["path", "diff"],
+          type: "object"
+        },
+        type: "array"
+      },
+      note: {
+        description: "Optional one-line note under the diffs",
+        type: "string"
+      },
+      reject: {
+        ...ACTION_BINDING_SCHEMA,
+        description: "Optional action to run when the member rejects"
+      },
+      title: { description: "What the change set does", type: "string" }
+    },
+    required: ["title", "files", "apply"],
+    type: "object"
+  },
+  name: "render_diff",
+  parse: parseDiffSpec
+};
+var planCard = {
+  ack: "(plan rendered inline — as you work, re-emit render_plan with the SAME cardId and updated step statuses instead of narrating progress; do not restate the steps as text)",
+  description: "Render a live multi-step plan card (max 12 steps) when you start multi-step work. Display-only — it has no buttons. Set a cardId and give every step a stable id, then as you progress RE-EMIT this card with the SAME cardId and updated step statuses (pending / active / done / error): the host replaces the earlier render in place, so the member sees one live plan instead of a stack of copies.",
+  inputSchema: {
+    properties: {
+      cardId: CARD_ID_SCHEMA,
+      note: {
+        description: "Optional one-line note under the steps",
+        type: "string"
+      },
+      steps: {
+        description: "The plan steps in order (max 12)",
+        items: {
+          properties: {
+            detail: {
+              description: "One-line progress or error note under the label",
+              type: "string"
+            },
+            id: {
+              description: "Stable step id — keep it identical across re-emits (letters/digits/_/-)",
+              type: "string"
+            },
+            label: { description: "What this step does", type: "string" },
+            status: { enum: [...PLAN_STEP_STATUSES], type: "string" }
+          },
+          required: ["id", "label", "status"],
+          type: "object"
+        },
+        type: "array"
+      },
+      title: { description: "What the plan accomplishes", type: "string" }
+    },
+    required: ["title", "steps"],
+    type: "object"
+  },
+  name: "render_plan",
+  parse: parsePlanSpec
+};
+var credentialCard = {
+  ack: "(credential request rendered inline — the member enters the values in the host UI and they are stored outside this conversation; you will receive a message naming which keys were set, never the values. Do not ask for the values in text)",
+  description: "Render a credential-request card when setup needs environment values from the member (API keys, secrets, connection strings) — max 8 keys, each an ENV_STYLE name with an optional label and docs link. This card deliberately has NO submit binding and collects NOTHING through you: the host UI gathers the values and stores them outside the model loop (its own .env or secret store), then sends a continuation message naming WHICH keys were set — never the values. Never ask for secret values in plain text, and never attach values to this card (any value-like field is dropped).",
+  inputSchema: {
+    properties: {
+      cardId: CARD_ID_SCHEMA,
+      keys: {
+        description: "The environment keys to request (max 8)",
+        items: {
+          properties: {
+            docsUrl: {
+              description: "Where to obtain the credential (provider dashboard URL)",
+              type: "string"
+            },
+            isSet: {
+              description: "Already configured on the host — rendered as set, with a replace affordance",
+              type: "boolean"
+            },
+            key: {
+              description: 'Environment variable name, e.g. "STRIPE_SECRET_KEY"',
+              type: "string"
+            },
+            label: {
+              description: 'Human label, e.g. "Stripe secret key"',
+              type: "string"
+            },
+            secret: {
+              description: "Mask and never echo (default true — only set false for genuinely public values)",
+              type: "boolean"
+            }
+          },
+          required: ["key"],
+          type: "object"
+        },
+        type: "array"
+      },
+      title: {
+        description: 'What the credentials unlock, e.g. "Connect Stripe"',
+        type: "string"
+      }
+    },
+    required: ["title", "keys"],
+    type: "object"
+  },
+  name: "request_credentials",
+  parse: parseCredentialSpec
+};
 var BUILTIN_UI_CARDS = [
   chartCard,
   tableCard,
   statTilesCard,
-  formCard
+  formCard,
+  choiceCard,
+  confirmCard,
+  diffCard,
+  planCard,
+  credentialCard
 ];
 // src/ai/ui/svg.ts
 var LIGHT_UI_THEME = {
@@ -712,28 +1166,46 @@ export {
   tableCard,
   statTilesCard,
   renderChartSvg,
+  planCard,
   parseUiActions,
   parseTableSpec,
   parseStatTilesSpec,
+  parsePlanSpec,
   parseFormSpec,
+  parseDiffSpec,
+  parseCredentialSpec,
+  parseConfirmSpec,
+  parseChoiceSpec,
   parseChartSpec,
   formCard,
+  diffCard,
+  credentialCard,
   createUiCards,
+  confirmCard,
+  choiceCard,
   chartCard,
   UI_ACTIONS_MAX,
   TABLE_MAX_ROWS,
   TABLE_MAX_COLUMNS,
   STAT_TILES_MAX,
+  PLAN_STEP_STATUSES,
+  PLAN_MAX_STEPS,
   LIGHT_UI_THEME,
   FORM_SELECT_MAX_OPTIONS,
   FORM_MAX_FIELDS,
   FORM_FIELD_TYPES,
+  DIFF_MAX_LINES,
+  DIFF_MAX_FILES,
   DARK_UI_THEME,
+  CREDENTIAL_MAX_KEYS,
+  CONFIRM_CONSEQUENCE_MAX_CHARS,
+  CHOICE_MAX_OPTIONS,
   CHART_TYPES,
   CHART_MAX_SERIES,
   CHART_MAX_POINTS,
+  CARD_ID_MAX_CHARS,
   BUILTIN_UI_CARDS
 };
 
-//# debugId=7B65AC9252EAC82564756E2164756E21
+//# debugId=59E12D813D37D12064756E2164756E21
 //# sourceMappingURL=index.js.map