fix(app-shell): ToolPreview stops rendering retired ToolSchema flags (#3236) (#3258)

The tool preview's header strip read four keys straight off the raw draft
and painted a pill for each: `requiresConfirmation`, `active`, `builtIn`
and `category`. All four were removed from `@objectstack/spec`'s
`ToolSchema` — `requiresConfirmation` in the 16.x line (objectstack#3715,
ADR-0033 §2) and the other three in 17.0.0 (objectstack#3896). The schema
is `.strict()` and rejects each by name, verified against the
`@objectstack/spec@17.0.0-rc.1` this repo depends on.

New metadata cannot reach these pills, but rows stored before the removals
still carry the keys and kept lighting them up. `Requires confirmation`
advertised a safety pause no execution path performs (the real gate is
`action.ai.requiresConfirmation` + the HITL approval queue) and `Disabled`
claimed a withdrawal while the registry kept handing the tool to the LLM —
the objectui#2962 shape of a badge advertising a capability the runtime
does not have.

Deleted the reads, the pills, and the now-callerless `tone` vocabulary on
the `Pill` helper. Added ToolPreview.test.tsx, which feeds a stale draft
carrying all four keys and asserts none of them renders.


Claude-Session: https://claude.ai/code/session_01NVPjPzmmAJ2Ngtvgg5MSRa

Co-authored-by: Claude <noreply@anthropic.com>

Author: xuyushun441-sys

.changeset/toolpreview-drop-retired-flag-pills.md

@@ -0,0 +1,39 @@
+---
+"@object-ui/app-shell": patch
+---
+
+`ToolPreview` stops advertising retired `ToolSchema` flags (objectui#3236).
+
+The metadata-admin tool preview painted a header strip of flag pills read
+straight off the raw draft: `Requires confirmation`, `Active` / `Disabled`,
+`built-in`, and the `category` tag. All four keys have been removed from
+`@objectstack/spec`'s `ToolSchema` — `requiresConfirmation` in the 16.x line
+(objectstack#3715, ADR-0033 §2) and `category` / `active` / `builtIn` in
+17.0.0 (objectstack#3896 audit close-out). The schema is `.strict()` and now
+rejects each by name with an upgrade prescription, so no newly authored tool
+can carry them; verified against the `@objectstack/spec@17.0.0-rc.1` this repo
+depends on.
+
+New metadata could not reach these pills — but rows stored before the removals
+still carry the keys, and for those the preview kept rendering. That is the
+harmful direction, not a cosmetic one:
+
+- `Requires confirmation` advertised a safety pause that no execution path has
+  ever performed. Nothing read the key — not the LLM tool set (a tool reaches
+  the model as name/description/parameters only), not `ToolRegistry.execute`,
+  not `POST /ai/tools/:name/execute`. A reviewer reading the preview saw a
+  destructive tool marked as gated when it was not. The real gate is
+  `action.ai.requiresConfirmation`, which the HITL approval queue reads.
+- `Disabled` claimed a tool had been withdrawn while `ToolRegistry.getAll()`
+  kept handing it to the LLM and the execute route kept running it.
+
+Same shape as objectui#2962: a UI badge advertising a capability the runtime
+does not have. The pills are gone; the surviving header strip shows label,
+machine name and the `objectName` pill (`objectName` is still a live spec key),
+and nothing else in the preview changed — parameters table, example LLM call
+and output schema are untouched.
+
+New tests feed the preview a stale draft that still carries all four retired
+keys and assert none of them renders, so the pills cannot grow back: the names
+survive in the spec's tombstone guidance, which gives the next reader a
+plausible-looking reason to "restore" them.

packages/app-shell/src/views/metadata-admin/previews/ToolPreview.test.tsx

@@ -0,0 +1,111 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * ToolPreview must not advertise retired `ToolSchema` flags (objectui#3236).
+ *
+ * `tool.requiresConfirmation` (objectstack#3715, ADR-0033 §2) and
+ * `tool.category` / `tool.active` / `tool.builtIn` (objectstack#3896 audit
+ * close-out) were removed from `@objectstack/spec`. `ToolSchema` is now
+ * `.strict()` and rejects each by name, so no *new* tool metadata can carry
+ * them — but stored rows authored before the removal still do, and the
+ * preview kept reading them off the raw draft and painting pills.
+ *
+ * That is the objectui#2962 shape: a UI badge advertising a capability the
+ * runtime never had. `Requires confirmation` promised a pause that no
+ * execution path performs (the real gate is `action.ai.requiresConfirmation`
+ * plus the HITL approval queue), and `Disabled` claimed a withdrawal while
+ * `ToolRegistry.getAll()` kept handing the tool to the LLM and
+ * `POST /ai/tools/:name/execute` kept running it.
+ *
+ * These tests feed the preview a STALE draft that still carries all four keys
+ * and assert nothing renders from them. They are the pin that stops the pills
+ * growing back: the names survive in the spec's tombstone guidance, so the
+ * next reader has a plausible reason to "restore" them.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, cleanup } from '@testing-library/react';
+import { ToolPreview } from './ToolPreview';
+
+afterEach(cleanup);
+
+/** A draft as an author wrote it *before* the spec removals — every retired key present. */
+const STALE_DRAFT = {
+  name: 'delete_all_orders',
+  label: 'Delete All Orders',
+  description: 'Permanently removes every order matching the filter.',
+  category: 'data',
+  active: false,
+  builtIn: true,
+  requiresConfirmation: true,
+  objectName: 'sales_order',
+  parameters: {
+    type: 'object',
+    required: ['status'],
+    properties: {
+      status: { type: 'string', description: 'Filter by status' },
+    },
+  },
+} satisfies Record<string, unknown>;
+
+function renderPreview(draft: Record<string, unknown>) {
+  return render(
+    <ToolPreview {...({ type: 'tool', name: 'delete_all_orders' } as never)} draft={draft} />,
+  );
+}
+
+describe('ToolPreview does not render retired ToolSchema flags', () => {
+  it('renders no confirmation badge for a stale draft with requiresConfirmation: true', () => {
+    renderPreview(STALE_DRAFT);
+    // The badge claimed a safety pause that no execution path has ever
+    // performed — never show it, whatever the stored row says.
+    expect(screen.queryByText(/requires confirmation/i)).toBeNull();
+    expect(screen.queryByText(/confirm/i)).toBeNull();
+  });
+
+  it('renders no Active/Disabled badge — `active` withdrew nothing', () => {
+    renderPreview(STALE_DRAFT);
+    expect(screen.queryByText(/^Disabled$/)).toBeNull();
+    expect(screen.queryByText(/^Active$/)).toBeNull();
+  });
+
+  it('renders no built-in or category badge', () => {
+    renderPreview(STALE_DRAFT);
+    expect(screen.queryByText(/built-in/i)).toBeNull();
+    expect(screen.queryByText(/^data$/)).toBeNull();
+  });
+
+  it('an `active: true` draft gets no badge either — the key is gone, not inverted', () => {
+    renderPreview({ ...STALE_DRAFT, active: true, requiresConfirmation: false, builtIn: false });
+    expect(screen.queryByText(/^Active$/)).toBeNull();
+    expect(screen.queryByText(/requires confirmation/i)).toBeNull();
+  });
+});
+
+describe('ToolPreview still renders everything the spec accepts', () => {
+  it('keeps label, machine name, description and the live objectName pill', () => {
+    renderPreview(STALE_DRAFT);
+    expect(screen.getByText('Delete All Orders')).toBeTruthy();
+    expect(screen.getByText('delete_all_orders')).toBeTruthy();
+    expect(
+      screen.getByText('Permanently removes every order matching the filter.'),
+    ).toBeTruthy();
+    // `objectName` is NOT residue — ToolSchema still accepts it.
+    expect(screen.getByText('sales_order')).toBeTruthy();
+  });
+
+  it('still renders the parameters table and the example LLM call', () => {
+    renderPreview(STALE_DRAFT);
+    expect(screen.getByText('Input Parameters')).toBeTruthy();
+    expect(screen.getByText('status')).toBeTruthy();
+    expect(screen.getByText('Example LLM Call')).toBeTruthy();
+  });
+
+  it('drops the pill row entirely when objectName is absent', () => {
+    const noObject: Record<string, unknown> = { ...STALE_DRAFT };
+    delete noObject.objectName;
+    renderPreview(noObject);
+    expect(screen.queryByText('sales_order')).toBeNull();
+    expect(screen.getByText('Delete All Orders')).toBeTruthy();
+  });
+});

packages/app-shell/src/views/metadata-admin/previews/ToolPreview.tsx

@@ -6,8 +6,7 @@
  * AI tools are LLM-callable functions whose contract is a JSON Schema
  * in `parameters`. The preview renders:
  *
- *   1. A header strip: machine name, category, target object, flags
- *      (active, requiresConfirmation, builtIn).
+ *   1. A header strip: machine name, label, target object.
  *   2. The description verbatim (this is what the LLM reads to decide
  *      when to call the tool, so authors must be able to skim it).
  *   3. An **input parameters** table extracted from the JSON Schema:
@@ -21,19 +20,30 @@
  * permission checks, and live datasource access that the preview
  * sandbox doesn't provide. Authors get an `Open in API Console` link
  * for end-to-end testing.
+ *
+ * NO FLAG PILLS — deliberate (objectstack#3715 / #3896, objectui#3236).
+ * The header strip used to render `requiresConfirmation`, `active`,
+ * `builtIn` and `category`. All four were removed from the spec's
+ * `ToolSchema`, which is now `.strict()` and rejects them by name with an
+ * upgrade prescription, so no new tool metadata can carry them. Rendering
+ * them for stale stored rows was worse than useless: `Requires
+ * confirmation` advertised a safety pause no execution path has ever
+ * performed (a real gate is `action.ai.requiresConfirmation` + the HITL
+ * approval queue), and `Disabled` claimed a tool had been withdrawn while
+ * the registry kept handing it to the LLM. Do not re-add a pill for any
+ * of these names — the "stale draft" tests in `ToolPreview.test.tsx` fail
+ * if you do. Any new pill must correspond to a key the spec still accepts
+ * AND a behavior the runtime actually performs.
  */
 
 import * as React from 'react';
 import {
-  AlertTriangle,
   Box,
   CheckCircle2,
   ChevronRight,
   Database,
   ExternalLink,
   FileJson,
-  Power,
-  Tag,
   Wrench,
 } from 'lucide-react';
 import type { MetadataPreviewProps } from '../preview-registry';
@@ -96,11 +106,7 @@ export function ToolPreview({ name, draft }: MetadataPreviewProps) {
   const toolName = String(d.name ?? name ?? '');
   const label = String(d.label ?? toolName);
   const description = String(d.description ?? '');
-  const category = (d.category as string | undefined) || undefined;
   const objectName = (d.objectName as string | undefined) || undefined;
-  const requiresConfirmation = !!d.requiresConfirmation;
-  const active = d.active !== false;
-  const builtIn = !!d.builtIn;
 
   const parameters = (d.parameters ?? {}) as JsonSchema;
   const outputSchema = (d.outputSchema ?? undefined) as JsonSchema | undefined;
@@ -161,15 +167,11 @@ export function ToolPreview({ name, draft }: MetadataPreviewProps) {
                   <span className="text-sm font-medium truncate">{label}</span>
                   <span className="font-mono text-[10px] text-muted-foreground">{toolName}</span>
                 </div>
-                <div className="mt-1 flex flex-wrap items-center gap-x-3 gap-y-1 text-[11px]">
-                  {category && <Pill icon={Tag} label={category} />}
-                  {objectName && <Pill icon={Database} label={objectName} mono />}
-                  <Pill icon={Power} label={active ? 'Active' : 'Disabled'} tone={active ? 'green' : 'gray'} />
-                  {requiresConfirmation && (
-                    <Pill icon={AlertTriangle} label="Requires confirmation" tone="amber" />
-                  )}
-                  {builtIn && <Pill label="built-in" />}
-                </div>
+                {objectName && (
+                  <div className="mt-1 flex flex-wrap items-center gap-x-3 gap-y-1 text-[11px]">
+                    <Pill icon={Database} label={objectName} mono />
+                  </div>
+                )}
               </div>
             </div>
             {description && (
@@ -295,27 +297,23 @@ function Empty({ children }: { children: React.ReactNode }) {
   return <div className="text-xs text-muted-foreground italic">{children}</div>;
 }
 
+// `tone` ('green' for Active, 'amber' for Requires confirmation) went away with
+// the flag pills themselves — the surviving caller is the neutral object-name
+// pill. A tone vocabulary kept alive with no caller is how the removed pills
+// grow back.
 function Pill({
   icon: Icon,
   label,
-  tone = 'gray',
   mono = false,
 }: {
   icon?: React.ComponentType<{ className?: string }>;
   label: string;
-  tone?: 'gray' | 'green' | 'amber';
   mono?: boolean;
 }) {
-  const cls =
-    tone === 'green'
-      ? 'text-emerald-700'
-      : tone === 'amber'
-        ? 'text-amber-700'
-        : 'text-foreground';
   return (
     <span className="inline-flex items-center gap-1">
       {Icon && <Icon className="h-3 w-3 text-muted-foreground" />}
-      <span className={`${cls} ${mono ? 'font-mono' : ''}`}>{label}</span>
+      <span className={`text-foreground ${mono ? 'font-mono' : ''}`}>{label}</span>
     </span>
   );
 }