@ai-matrx/chat 0.1.77 → 0.2.0

package/dist/agents/ui-first-tools/tools/schemas.js

@@ -0,0 +1,183 @@
+import { z } from "zod";
+const optionInputSchema = z.union([
+  z.string().min(1),
+  z.object({
+    label: z.string().min(1),
+    description: z.string().optional(),
+    preview: z.string().optional()
+  })
+]);
+function normalizeAskOptions(raw) {
+  if (!raw) return void 0;
+  return raw.map(
+    (o) => typeof o === "string" ? { label: o } : { label: o.label, description: o.description, preview: o.preview }
+  );
+}
+const USER_ASK_TYPES = [
+  "confirm",
+  "choice",
+  "choice_many",
+  "text",
+  "secret",
+  "notify"
+];
+const USER_ASK_TYPE_SET = new Set(USER_ASK_TYPES);
+function recoverUserArgs(raw) {
+  if (raw.type === void 0 && raw.questions === void 0 && typeof raw.action === "string" && USER_ASK_TYPE_SET.has(raw.action)) {
+    const { action, ...rest } = raw;
+    return {
+      args: { ...rest, type: action },
+      recoveredAlias: "action_to_type"
+    };
+  }
+  return { args: raw, recoveredAlias: null };
+}
+const singleQuestionSchema = z.object({
+  type: z.enum(USER_ASK_TYPES),
+  question: z.string().optional(),
+  header: z.string().max(12).optional(),
+  options: z.array(optionInputSchema).optional(),
+  context: z.string().optional(),
+  message: z.string().optional(),
+  actions: z.array(z.string().min(1)).optional(),
+  level: z.enum(["info", "success", "warning", "error"]).optional(),
+  allow_other: z.boolean().optional(),
+  timeout_seconds: z.number().int().min(1).max(900).optional()
+});
+function validateSingle(v, ctx, pathPrefix) {
+  const needsQuestion = v.type === "confirm" || v.type === "choice" || v.type === "choice_many" || v.type === "text" || v.type === "secret";
+  if (needsQuestion && !v.question?.trim()) {
+    ctx.addIssue({
+      code: "custom",
+      message: `question is required when type='${v.type}'`,
+      path: [...pathPrefix, "question"]
+    });
+  }
+  if (v.type === "notify" && !v.message?.trim()) {
+    ctx.addIssue({
+      code: "custom",
+      message: "message is required when type='notify'",
+      path: [...pathPrefix, "message"]
+    });
+  }
+  if ((v.type === "choice" || v.type === "choice_many") && (!v.options || v.options.length < 2)) {
+    ctx.addIssue({
+      code: "custom",
+      message: `options must have at least 2 entries when type='${v.type}'`,
+      path: [...pathPrefix, "options"]
+    });
+  }
+}
+const userArgsSchema = z.object({
+  // Single-question fields (omit when using batched form)
+  type: z.enum(USER_ASK_TYPES).optional(),
+  question: z.string().optional(),
+  header: z.string().max(12).optional(),
+  options: z.array(optionInputSchema).optional(),
+  context: z.string().optional(),
+  message: z.string().optional(),
+  actions: z.array(z.string().min(1)).optional(),
+  level: z.enum(["info", "success", "warning", "error"]).optional(),
+  allow_other: z.boolean().optional(),
+  timeout_seconds: z.number().int().min(1).max(900).optional(),
+  // Batched form (mutually exclusive with everything above)
+  questions: z.array(singleQuestionSchema).min(1).max(4).optional()
+}).superRefine((v, ctx) => {
+  const isBatch = !!v.questions && v.questions.length > 0;
+  if (isBatch) {
+    const stray = Object.entries(v).find(
+      ([k, val]) => k !== "questions" && val !== void 0
+    );
+    if (stray) {
+      ctx.addIssue({
+        code: "custom",
+        message: `When using the batched form, only \`questions\` may be set. Saw \`${stray[0]}\`.`,
+        path: [stray[0]]
+      });
+    }
+    v.questions?.forEach((q, i) => validateSingle(q, ctx, ["questions", i]));
+    return;
+  }
+  if (!v.type) {
+    ctx.addIssue({
+      code: "custom",
+      message: "Either `type` (single question) or `questions[]` (batched) is required",
+      path: ["type"]
+    });
+    return;
+  }
+  validateSingle(v, ctx, []);
+});
+function isBatchedUserArgs(args) {
+  return !!args.questions && args.questions.length > 0;
+}
+const updatePlanArgsSchema = z.object({
+  title: z.string().optional(),
+  steps: z.array(z.string().min(1)).min(1).max(40).optional(),
+  // Aidream variants emit `approach` instead of `steps` — accept both.
+  approach: z.array(z.string().min(1)).min(1).max(40).optional(),
+  domains: z.array(z.string()).optional(),
+  reasoning: z.string().optional(),
+  estimated_minutes: z.number().int().positive().max(240).optional(),
+  timeout_seconds: z.number().int().positive().max(15 * 60).optional()
+}).refine((v) => v.steps != null || v.approach != null, {
+  message: "either steps or approach is required"
+});
+const requestTakeoverArgsSchema = z.object({
+  reason: z.string().min(1),
+  expected_action: z.string().optional(),
+  instructions: z.string().optional(),
+  // tab_id matches the DB contract (browser surfaces use it; the web app ignores it).
+  tab_id: z.string().optional(),
+  timeout_seconds: z.number().int().min(1).max(900).optional()
+});
+const taskItemInputSchema = z.object({
+  title: z.string().min(1).max(200),
+  status: z.enum(["pending", "in_progress", "done", "blocked", "skipped"]).optional(),
+  note: z.string().max(500).nullable().optional()
+});
+const userTodosArgsSchema = z.object({
+  action: z.enum([
+    "add",
+    "list",
+    "update",
+    "remove",
+    "mark_done",
+    "clear_done"
+  ]),
+  title: z.string().min(1).max(200).optional(),
+  context: z.string().max(300).nullable().optional(),
+  due: z.string().max(80).nullable().optional(),
+  id: z.string().optional(),
+  silent: z.boolean().optional(),
+  done: z.boolean().optional()
+});
+const googleEmailSendArgsSchema = z.object({
+  to: z.string().min(3).max(320),
+  cc: z.array(z.string()).max(20).optional(),
+  subject: z.string().min(1).max(998),
+  body: z.string().min(1).max(1e5)
+});
+const EMPTY_ASK_RESPONSE = {
+  answer: null,
+  selected: null,
+  confirmed: null,
+  action: null,
+  freeform: null,
+  additional_instructions: null,
+  wrote_instead: false,
+  data: null,
+  cancelled: false,
+  timed_out: false
+};
+export {
+  EMPTY_ASK_RESPONSE,
+  googleEmailSendArgsSchema,
+  isBatchedUserArgs,
+  normalizeAskOptions,
+  recoverUserArgs,
+  requestTakeoverArgsSchema,
+  updatePlanArgsSchema,
+  userArgsSchema,
+  userTodosArgsSchema
+};

package/dist/agents/ui-first-tools/tools/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Row types and result envelopes for the UI-first tools system.
+ *
+ * Row types mirror the `chat` schema shapes. Hand-typed (rather than pulled
+ * from `database.types.ts`) because `steps`/`value` come back as `Json` from
+ * the generator and every consumer here wants the narrowed shape. Because
+ * they are hand-mirrored, the type gate does NOT catch column renames —
+ * compare against the live table whenever the schema changes.
+ *
+ * Ownership is `created_by` (canonical, stamped by the `_stamp_actor`
+ * trigger). `chat.agent_task` has no owner uuid of its own: it is owned
+ * through its parent conversation, and its `creator_kind` enum records who
+ * AUTHORED the task (agent vs user), never who owns it.
+ */
+import type { TaskStatus } from "./schemas.js";
+export type CxPlanStatus = "proposed" | "approved" | "rejected" | "superseded";
+export type CxAgentTaskStatus = NonNullable<TaskStatus>;
+export type CxAgentTaskCreator = "agent" | "user";
+export interface CxAgentPlanRow {
+    id: string;
+    conversation_id: string;
+    created_by: string | null;
+    title: string;
+    steps: string[];
+    reasoning: string | null;
+    domains: string[] | null;
+    estimated_minutes: number | null;
+    status: CxPlanStatus;
+    created_at: string;
+    updated_at: string;
+}
+export interface CxAgentTaskRow {
+    id: string;
+    conversation_id: string;
+    plan_id: string | null;
+    title: string;
+    status: CxAgentTaskStatus;
+    note: string | null;
+    position: number;
+    /** Who authored the task — NOT an owner. Owner is the parent conversation. */
+    creator_kind: CxAgentTaskCreator | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface CxUserTodoRow {
+    id: string;
+    conversation_id: string;
+    created_by: string | null;
+    title: string;
+    context: string | null;
+    due: string | null;
+    done: boolean;
+    done_at: string | null;
+    ctx_task_id: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface TasksResult {
+    ok: boolean;
+    action: string;
+    tasks: Array<{
+        id: string;
+        title: string;
+        status: CxAgentTaskStatus;
+        note: string | null;
+    }>;
+    created?: Array<{
+        id: string;
+        title: string;
+        status: CxAgentTaskStatus;
+    }>;
+    removed?: string[];
+    message?: string;
+}
+export interface UserTodosResult {
+    ok: boolean;
+    action: string;
+    open: Array<{
+        id: string;
+        title: string;
+        context: string | null;
+        due: string | null;
+    }>;
+    recent_done: Array<{
+        id: string;
+        title: string;
+        done_at: string;
+    }>;
+    created?: Array<{
+        id: string;
+        title: string;
+    }>;
+    removed?: string[];
+    message?: string;
+}
+export interface PlanResultEnvelope {
+    ok: boolean;
+    plan: {
+        id: string;
+        title: string;
+        steps: string[];
+        status: CxPlanStatus;
+        reasoning: string | null;
+    } | null;
+    status: CxPlanStatus | null;
+    cancelled: boolean;
+    timed_out: boolean;
+}

package/dist/agents/ui-first-tools/ui/AgentCardShell.d.ts

@@ -0,0 +1,66 @@
+/**
+ * AgentCardShell — the shared chrome for every inline agent card (asks +
+ * approvals) that sits above the chat input.
+ *
+ * One look, applied everywhere: a rounded-2xl elevated card, a tone-tinted top
+ * accent, a compact header row (plain tinted icon + eyebrow + badge + dismiss ×)
+ * with the title on its OWN full-width row below by default (so a long question
+ * spans the whole card instead of being squeezed into a middle column), plus an
+ * opt-in inline-title header for compact approval labels. It also owns a subtitle,
+ * body slot, optional muted footer band, and bottom countdown slot. `<AskCard>` and
+ * `<ApprovalCard>` both render through this, so they share spacing, rounding,
+ * elevation, and hierarchy — each card supplies its own content and density.
+ *
+ * Scroll behavior (Arman, 2026-08-15): the QUESTION and the ANSWERS share ONE
+ * scroll region — never two. The old design gave the title its own capped scroll
+ * and the body another, so a long question starved the answers into a tiny slot.
+ * Now:
+ *   - Mobile: the card flows at natural height and the host bottom-drawer owns the
+ *     single scroll, so the whole question+answers scroll as one and the user
+ *     spends the space however they want.
+ *   - Desktop: the card caps itself (so the chat input stays reachable) and
+ *     scrolls its own question+answers region as one, with a soft edge fade
+ *     (useScrollFade) cueing that there's more above/below.
+ * Only the small meta row (icon/eyebrow/dismiss), the footer action band, and the
+ * countdown stay pinned.
+ *
+ * Tone drives the accent strip + icon color; "neutral" hides the strip. The icon
+ * carries no chip background/padding — the tone reads via the strip + icon tint.
+ */
+import type { ReactNode } from "react";
+import type { LucideIcon } from "lucide-react";
+export type AccentTone = "neutral" | "primary" | "info" | "success" | "warning" | "danger" | "violet";
+export interface AgentCardShellProps {
+    tone?: AccentTone;
+    icon?: LucideIcon;
+    /** Small uppercase label above the title (kind / verb / context). */
+    eyebrow?: ReactNode;
+    /** The prominent line (the question, or the entity headline). */
+    title?: ReactNode;
+    /** Muted secondary line under the title. */
+    subtitle?: ReactNode;
+    /** Top-right pill (e.g. batch "2 of 3"). */
+    badge?: ReactNode;
+    /** Optional control beside the badge / dismiss action. */
+    headerAction?: ReactNode;
+    /** Keep the eyebrow and title in one compact header row when the title is short. */
+    titleInline?: boolean;
+    /** Shows the dismiss × when provided. */
+    onDismiss?: () => void;
+    dismissLabel?: string;
+    /** Action row, rendered in a muted footer band with a top border. */
+    footer?: ReactNode;
+    /** Density override for the footer band. */
+    footerClassName?: string;
+    /** Body content. When falsy, the body region is omitted entirely. */
+    children?: ReactNode;
+    /** Density override for the body wrapper. */
+    contentClassName?: string;
+    /** Dim + disable once resolved. */
+    pending?: boolean;
+    /** Bottom-edge slot (the countdown bar). */
+    bottomSlot?: ReactNode;
+    className?: string;
+    "aria-label"?: string;
+}
+export declare function AgentCardShell({ tone, icon: Icon, eyebrow, title, subtitle, badge, headerAction, titleInline, onDismiss, dismissLabel, footer, footerClassName, children, contentClassName, pending, bottomSlot, className, "aria-label": ariaLabel, }: AgentCardShellProps): import("react").JSX.Element;

package/dist/agents/ui-first-tools/ui/AgentCardShell.js

@@ -0,0 +1,144 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { X } from "lucide-react";
+import { cn } from "@ai-matrx/design-system";
+import { useIsMobile } from "@ai-matrx/kit/media-query";
+import { useScrollFade } from "../../../ui/scroll-fade.js";
+import { Button } from "@ai-matrx/design-system/controls";
+const ICON_TONE = {
+  neutral: "text-muted-foreground",
+  primary: "text-primary",
+  info: "text-sky-600 dark:text-sky-400",
+  success: "text-emerald-600 dark:text-emerald-400",
+  warning: "text-amber-600 dark:text-amber-400",
+  danger: "text-red-600 dark:text-red-400",
+  violet: "text-violet-600 dark:text-violet-400"
+};
+const STRIP = {
+  neutral: "from-border",
+  primary: "from-primary/60",
+  info: "from-sky-500/60",
+  success: "from-emerald-500/60",
+  warning: "from-amber-500/60",
+  danger: "from-red-500/60",
+  violet: "from-violet-500/60"
+};
+function AgentCardShell({
+  tone = "neutral",
+  icon: Icon,
+  eyebrow,
+  title,
+  subtitle,
+  badge,
+  headerAction,
+  titleInline = false,
+  onDismiss,
+  dismissLabel = "Dismiss",
+  footer,
+  footerClassName,
+  children,
+  contentClassName,
+  pending,
+  bottomSlot,
+  className,
+  "aria-label": ariaLabel
+}) {
+  const isMobile = useIsMobile();
+  const cardScrolls = !isMobile;
+  const fade = useScrollFade();
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cn(
+        // overflow-hidden always clips to the rounded corners. On desktop the
+        // card also caps its height so it can never outgrow the viewport; on
+        // mobile it flows at natural height and the host drawer scrolls it.
+        "group relative flex flex-col overflow-hidden rounded-2xl border border-border/70 bg-card text-card-foreground",
+        cardScrolls && "max-h-[70dvh]",
+        "shadow-[0_10px_30px_-14px_rgb(0_0_0/0.45)] ring-1 ring-black/[0.03] dark:ring-white/[0.04]",
+        "animate-in fade-in slide-in-from-bottom-2 duration-300",
+        pending && "opacity-50 pointer-events-none",
+        className
+      ),
+      role: "region",
+      "aria-label": ariaLabel,
+      children: [
+        tone !== "neutral" && /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: cn(
+              "h-0.5 w-full shrink-0 bg-gradient-to-r to-transparent",
+              STRIP[tone]
+            )
+          }
+        ),
+        /* @__PURE__ */ jsxs(
+          "div",
+          {
+            className: cn(
+              "flex shrink-0 items-center gap-2",
+              titleInline ? "px-3 py-2" : "px-4 pt-3"
+            ),
+            children: [
+              Icon && /* @__PURE__ */ jsx(
+                Icon,
+                {
+                  className: cn("size-[18px] shrink-0", ICON_TONE[tone]),
+                  strokeWidth: 2.25
+                }
+              ),
+              titleInline ? /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 flex-1 flex-wrap items-baseline gap-x-1.5 gap-y-0.5", children: [
+                eyebrow && /* @__PURE__ */ jsx("span", { className: "text-[10px] font-medium uppercase tracking-wide text-muted-foreground", children: eyebrow }),
+                eyebrow && title && /* @__PURE__ */ jsx("span", { "aria-hidden": "true", className: "text-muted-foreground/50", children: "\xB7" }),
+                title && /* @__PURE__ */ jsx("span", { className: "min-w-0 text-sm font-semibold leading-snug text-foreground", children: title })
+              ] }) : eyebrow ? /* @__PURE__ */ jsx("div", { className: "min-w-0 flex-1 truncate text-[11px] font-medium uppercase tracking-wide text-muted-foreground", children: eyebrow }) : null,
+              badge && /* @__PURE__ */ jsx(
+                "span",
+                {
+                  className: cn(
+                    "shrink-0 rounded-full bg-muted px-1.5 py-0.5 text-[10px] font-medium tabular-nums text-muted-foreground",
+                    !eyebrow && "ml-auto"
+                  ),
+                  children: badge
+                }
+              ),
+              headerAction,
+              onDismiss && /* @__PURE__ */ jsx(Button, { variant: "quiet", icon: /* @__PURE__ */ jsx(X, {}), onClick: onDismiss, title: dismissLabel, "aria-label": dismissLabel, className: "-mr-1 shrink-0" })
+            ]
+          }
+        ),
+        /* @__PURE__ */ jsxs(
+          "div",
+          {
+            ref: cardScrolls ? fade.ref : void 0,
+            style: cardScrolls ? fade.style : void 0,
+            className: cn(
+              "flex flex-col",
+              cardScrolls ? "min-h-0 flex-1 overflow-y-auto overscroll-contain" : "",
+              !footer && "pb-3.5"
+            ),
+            children: [
+              !titleInline && title && /* @__PURE__ */ jsx("div", { className: "mt-1.5 whitespace-pre-wrap px-4 text-[15px] font-semibold leading-snug text-foreground", children: title }),
+              subtitle && /* @__PURE__ */ jsx("div", { className: "mt-1 px-4 text-xs text-muted-foreground", children: subtitle }),
+              children ? /* @__PURE__ */ jsx("div", { className: contentClassName ?? "px-4 pt-3", children }) : null
+            ]
+          }
+        ),
+        footer && /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: cn(
+              "shrink-0 border-t border-border/60 bg-muted/30",
+              footerClassName ?? "px-4 py-3"
+            ),
+            children: footer
+          }
+        ),
+        bottomSlot
+      ]
+    }
+  );
+}
+export {
+  AgentCardShell
+};

package/dist/agents/ui-first-tools/ui/ApprovalCard.d.ts

@@ -0,0 +1,70 @@
+/**
+ * ApprovalCard — the agent-edit approval surface (kind:"approval").
+ *
+ * States the change ONCE: a compact "{Verb} · {title}" header, optional details,
+ * a fully reviewable before→after diff body, and one compact action row
+ * (Apply · Keep as is · Respond) with an opt-in "always approve {noun}". Built
+ * on the shared `<AgentCardShell>` + `<ChangeDiff>`, so it shares its look with
+ * every other inline agent card and its diff with every other change surface.
+ *
+ * Resolution mirrors <AskCard>: it routes through the same ask-resolver registry
+ * + pendingAsks slice, so the war-room dispatcher's awaiting promise unblocks
+ * exactly once. Apply packs `confirmed:true` (and the REMEMBER_SENTINEL when
+ * "always approve" is on); Keep as is packs `confirmed:false`; Respond packs the
+ * typed `freeform`; the × minimizes without resolving the tool call.
+ *
+ * ONE CARD, TWO KINDS OF WAIT. A client-delegated tool is SUSPENDED while this
+ * card is on screen, and the registry above is how it resumes. A change the
+ * SERVER already refused has no suspended call to resume — the `records` tool
+ * answered `awaiting_approval` and returned — so its producer hands `onDecide`
+ * instead and applies the change itself
+ * (`features/record-change-approvals`). Everything a person reads and every
+ * gesture they make is the same in both, which is the point: there is one
+ * approval grammar on this platform, not one per place a write happens.
+ */
+import { type ReactNode } from "react";
+import type { PendingAsk } from "../redux/pending-asks.slice.js";
+interface ApprovalCardProps {
+    ask: PendingAsk;
+    /**
+     * Standalone mode: take the decision instead of resolving a delegated tool
+     * call. Set by a producer whose write is its own to make (a server-side
+     * change a person is approving after the fact).
+     */
+    onDecide?: (decision: "approve" | "decline", options?: {
+        remember: boolean;
+    }) => void;
+    /**
+     * What the card says once the decision has been taken — the outcome replaces
+     * the action row, so a decided card never offers the decision again.
+     */
+    outcome?: ReactNode;
+    /**
+     * Offer "Respond". A suspended tool call can be redirected with a sentence;
+     * a change that has already come back from the server cannot, so its producer
+     * turns this off rather than showing a box that would go nowhere.
+     */
+    allowRespond?: boolean;
+    /**
+     * A sentence shown ALWAYS, above the diff — not behind Details.
+     *
+     * `description` is supporting detail a person may open; a reason a change is
+     * waiting, and the one setting that governs it, is not detail. A card that
+     * hid WHY behind a toggle would be asking for a decision while withholding
+     * the fact the decision turns on.
+     */
+    note?: ReactNode;
+    /**
+     * The words on the two decision buttons. A suspended tool call is "Apply /
+     * Keep as is"; a write the store HOLDS for a person is "Approve / Refuse",
+     * because that is the decision the queue records.
+     */
+    labels?: {
+        approve?: string;
+        decline?: string;
+    };
+    /** One extra control in the action row — e.g. "Open the table". */
+    secondaryAction?: ReactNode;
+}
+export declare function ApprovalCard({ ask, onDecide, outcome, allowRespond, note, labels, secondaryAction, }: ApprovalCardProps): import("react").JSX.Element | null;
+export {};