akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

package/ui/index.ts

@@ -1,3 +1,5 @@
+export { Agent } from "./Agent";
+export { agentAttrs } from "./agentAttrs";
 export { animated } from "./animated";
 export { Badge } from "./Badge";
 export { BottomSheet, type BottomSheetRef } from "./BottomSheet";
@@ -12,7 +14,7 @@ export { DatePicker } from "./DatePicker";
 export { Dialog } from "./Dialog";
 export { DragAction } from "./DragAction";
 export { DraggableList } from "./DraggableList";
-export { Dropdown } from "./Dropdown";
+export { DROPDOWN_KEEP_OPEN_ATTR, Dropdown } from "./Dropdown";
 export { Empty } from "./Empty";
 export { Field } from "./Field";
 export { FontFace } from "./FontFace";
@@ -29,6 +31,13 @@ export { Modal } from "./Modal";
 export { Model } from "./Model";
 export { More } from "./More";
 export { ObjectId } from "./ObjectId";
+export {
+  isOwnOverlayClick,
+  OVERLAY_LAYER_ATTR,
+  OverlayOwnerProvider,
+  useOverlayLayerProps,
+  useOverlayScope,
+} from "./overlayLayer";
 export { Pagination } from "./Pagination";
 export { Popconfirm } from "./Popconfirm";
 export { Portal } from "./Portal";

package/ui/overlayLayer.ts

@@ -0,0 +1,39 @@
+"use client";
+import { createContext, useContext } from "react";
+
+/**
+ * Overlay surfaces render through `createPortal(document.body)`, so they leave the DOM subtree of the
+ * component that opened them, and a dismiss check asking `ref.current.contains(target)` reads every
+ * click inside a dialog it opened *itself* as an outside click.
+ *
+ * React context reaches through a portal where the DOM does not, so an overlay can read which
+ * dismissable scope rendered it and stamp that owner on the roots it portals out. A scope then
+ * recognises its own overlays exactly, instead of guessing from how close a dialog happens to be.
+ */
+export const OVERLAY_LAYER_ATTR = "data-akan-overlay";
+
+/** Scope that rendered the surrounding content — empty at page level. */
+const OverlayOwnerContext = createContext("");
+
+/** Wrap the content a dismissable container owns, with the scope from {@link useOverlayScope}. */
+export const OverlayOwnerProvider = OverlayOwnerContext.Provider;
+
+/** Scope a dismissable container hands to its content. Nests as a `parent/child` path. */
+export const useOverlayScope = (id: string) => {
+  const parent = useContext(OverlayOwnerContext);
+  return parent ? `${parent}/${id}` : id;
+};
+
+/** Props an overlay spreads onto every root it portals out of its own tree. */
+export const useOverlayLayerProps = () => ({ [OVERLAY_LAYER_ATTR]: useContext(OverlayOwnerContext) });
+
+/**
+ * True when the click landed in an overlay that `scope` — or a scope nested inside it — rendered.
+ * An overlay nobody owns, and one owned by an unrelated scope, both read as an ordinary outside
+ * click, so a menu does not linger behind a dialog it has nothing to do with.
+ */
+export const isOwnOverlayClick = (target: EventTarget | null, scope: string) => {
+  if (!(target instanceof Element)) return false;
+  const owner = target.closest(`[${OVERLAY_LAYER_ATTR}]`)?.getAttribute(OVERLAY_LAYER_ATTR);
+  return !!owner && (owner === scope || owner.startsWith(`${scope}/`));
+};

package/ui/recipe/badgeRecipe.ts

@@ -1,23 +1,42 @@
 import { recipe, tv } from "./factory";
 
-/** 뱃지 look — 시맨틱 variant. `<Badge>` 가 소비하며, recipes.badge 슬롯으로 교체 가능. */
+/** 뱃지 look — 시맨틱 variant × size, outline 플래그는 색을 유지한 외곽선 스타일. `<Badge>` 가 소비하며, recipes.badge 슬롯으로 교체 가능. */
 export const badgeRecipe = recipe(
   tv({
-    base: "inline-flex items-center gap-1 rounded-full border px-2.5 py-0.5 font-medium text-xs",
+    base: "inline-flex items-center gap-1 rounded-full border font-medium",
     variants: {
       variant: {
         default: "border-transparent bg-muted text-foreground",
         primary: "border-transparent bg-primary text-primary-foreground",
         secondary: "border-transparent bg-secondary text-secondary-foreground",
         accent: "border-transparent bg-accent text-accent-foreground",
+        neutral: "border-transparent bg-neutral text-neutral-foreground",
         success: "border-transparent bg-success text-success-foreground",
         warning: "border-transparent bg-warning text-warning-foreground",
         info: "border-transparent bg-info text-info-foreground",
         error: "border-transparent bg-destructive text-destructive-foreground",
         outline: "border-border text-foreground",
       },
+      size: {
+        xs: "px-1.5 py-0 text-[0.625rem]",
+        sm: "px-2 py-0.5 text-xs",
+        md: "px-2.5 py-0.5 text-xs",
+        lg: "px-3 py-1 text-sm",
+      },
+
+      outline: { true: "border-current bg-transparent" },
     },
-    defaultVariants: { variant: "default" },
+    compoundVariants: [
+      { variant: "primary", outline: true, class: "text-primary" },
+      { variant: "secondary", outline: true, class: "text-secondary" },
+      { variant: "accent", outline: true, class: "text-accent" },
+      { variant: "neutral", outline: true, class: "text-neutral" },
+      { variant: "success", outline: true, class: "text-success" },
+      { variant: "warning", outline: true, class: "text-warning" },
+      { variant: "info", outline: true, class: "text-info" },
+      { variant: "error", outline: true, class: "text-destructive" },
+    ],
+    defaultVariants: { variant: "default", size: "md" },
   }),
 );
 export type BadgeVariants = NonNullable<Parameters<typeof badgeRecipe>[0]>;

package/ui/recipe/buttonRecipe.ts

@@ -1,15 +1,18 @@
 import { recipe, tv } from "./factory";
 
-/** 버튼 look — 시맨틱 variant × size. `<Button>` 이 소비하며, `_overrides.tsx` 의 recipes.button 슬롯으로 교체 가능. */
+/** 버튼 look — 시맨틱 variant × size × shape, outline 플래그는 색을 유지한 외곽선 스타일. `<Button>` 이 소비하며, `_overrides.tsx` 의 recipes.button 슬롯으로 교체 가능. */
 export const buttonRecipe = recipe(
   tv({
 
     base: "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-field font-medium transition active:scale-95 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
     variants: {
       variant: {
+
+        default: "bg-muted text-foreground hover:bg-muted/80",
         primary: "bg-primary text-primary-foreground hover:bg-primary/90",
         secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
         accent: "bg-accent text-accent-foreground hover:bg-accent/90",
+        neutral: "bg-neutral text-neutral-foreground hover:bg-neutral/90",
         outline: "border border-input bg-background hover:bg-muted hover:text-foreground",
         ghost: "hover:bg-muted hover:text-foreground",
         destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
@@ -25,8 +28,54 @@ export const buttonRecipe = recipe(
         lg: "h-12 px-6 text-lg",
         icon: "h-10 w-10",
       },
+
+      shape: {
+        default: "",
+        square: "aspect-square px-0",
+        circle: "aspect-square rounded-full px-0",
+      },
+
+      outline: { true: "border bg-transparent" },
     },
-    defaultVariants: { variant: "primary", size: "md" },
+    compoundVariants: [
+      {
+        variant: "primary",
+        outline: true,
+        class: "border-primary text-primary hover:bg-primary hover:text-primary-foreground",
+      },
+      {
+        variant: "secondary",
+        outline: true,
+        class: "border-secondary text-secondary hover:bg-secondary hover:text-secondary-foreground",
+      },
+      {
+        variant: "accent",
+        outline: true,
+        class: "border-accent text-accent hover:bg-accent hover:text-accent-foreground",
+      },
+      {
+        variant: "neutral",
+        outline: true,
+        class: "border-neutral text-neutral hover:bg-neutral hover:text-neutral-foreground",
+      },
+      {
+        variant: "destructive",
+        outline: true,
+        class: "border-destructive text-destructive hover:bg-destructive hover:text-destructive-foreground",
+      },
+      {
+        variant: "success",
+        outline: true,
+        class: "border-success text-success hover:bg-success hover:text-success-foreground",
+      },
+      {
+        variant: "warning",
+        outline: true,
+        class: "border-warning text-warning hover:bg-warning hover:text-warning-foreground",
+      },
+      { variant: "info", outline: true, class: "border-info text-info hover:bg-info hover:text-info-foreground" },
+    ],
+    defaultVariants: { variant: "primary", size: "md", shape: "default" },
   }),
 );
 export type ButtonVariants = NonNullable<Parameters<typeof buttonRecipe>[0]>;

package/ui/recipe/factory.ts

@@ -1,6 +1,6 @@
 import type { ClassNameValue as ClassValue } from "tailwind-merge";
 import { createTV } from "tailwind-variants";
-import { colorTokens } from "../../client/cn";
+import { colorTokens, radiusTokens } from "../../client/cn";
 
 /**
  * recipe 팩토리 모듈 — 변형 팩토리를 만드는 **인프라**. **서버-안전** (절대 `"use client"` 금지).
@@ -8,7 +8,7 @@ import { colorTokens } from "../../client/cn";
  * 각 앱은 `apps/<app>/ui/Recipe/<name>.ts`.
  */
 
-export const tv = createTV({ twMergeConfig: { extend: { theme: { color: colorTokens } } } });
+export const tv = createTV({ twMergeConfig: { extend: { theme: { color: colorTokens, radius: radiusTokens } } } });
 
 /**
  * recipe 팩토리 — `tv({...})` 인스턴스를 받아 겉을 `(변형, className?)` 2-인자로 노출하고,

package/ui/recipe/inputRecipe.ts

@@ -1,13 +1,27 @@
 import { recipe, tv } from "./factory";
 
-/** 입력 표면 look — Input/TextArea 가 공유하는 필드 셸. kind 로 한 줄 필드(field)/멀티라인(area)을 고른다. */
+/** 입력 표면 look — Input/TextArea/Select 가 공유하는 필드 셸. kind 로 한 줄 필드(field)/멀티라인(area), tone 으로 강조/오류 상태를 고른다. */
 export const inputRecipe = recipe(
   tv({
-    base: "w-full rounded-field border border-input bg-background text-foreground text-sm focus:border-primary focus:outline-none",
+    base: "w-full rounded-field border border-input bg-background text-foreground focus:border-primary focus:outline-none",
     variants: {
-      kind: { field: "h-10 px-3", area: "p-3" },
+      kind: { field: "px-3", area: "p-3" },
+      size: { xs: "text-xs", sm: "text-sm", md: "text-sm", lg: "text-base", xl: "text-lg" },
+      tone: {
+        default: "",
+        primary: "border-primary",
+        error: "border-destructive focus:border-destructive",
+      },
     },
-    defaultVariants: { kind: "field" },
+
+    compoundVariants: [
+      { kind: "field", size: "xs", class: "h-6" },
+      { kind: "field", size: "sm", class: "h-8" },
+      { kind: "field", size: "md", class: "h-10" },
+      { kind: "field", size: "lg", class: "h-12" },
+      { kind: "field", size: "xl", class: "h-14" },
+    ],
+    defaultVariants: { kind: "field", size: "md", tone: "default" },
   }),
 );
 export type InputSurfaceVariants = NonNullable<Parameters<typeof inputRecipe>[0]>;

package/vendor/use-agentic/AgentProvider.tsx

@@ -0,0 +1,39 @@
+"use client";
+import { type ReactNode, useRef } from "react";
+import { AgenticSurface } from "./AgenticSurface";
+import { AgentSession, type AgentSessionOptions } from "./AgentSession";
+import { SurfaceContext } from "./surfaceContext";
+import type { AgentRunner } from "./types";
+import { SessionContext } from "./useAgent";
+
+interface AgentProviderProps extends AgentSessionOptions {
+  surface?: AgenticSurface;
+  session?: AgentSession;
+  runner?: AgentRunner;
+  children: ReactNode;
+}
+
+/**
+ * Scopes a subtree onto one surface and, when a runner or session is given, one conversation.
+ *
+ * Without a provider, hooks land on `AgenticSurface.shared` — a provider exists to isolate, or to hold the session
+ * `useAgent` reads.
+ */
+export const AgentProvider = ({ surface, session, runner, children, ...options }: AgentProviderProps) => {
+  const held = useRef<{ surface: AgenticSurface; session: AgentSession | null } | null>(null);
+  if (!held.current) {
+    const sessionSurface = session?.surface;
+    
+    const heldSurface =
+      surface ?? (sessionSurface instanceof AgenticSurface ? sessionSurface : undefined) ?? new AgenticSurface();
+    held.current = {
+      surface: heldSurface,
+      session: session ?? (runner ? new AgentSession(heldSurface, runner, options) : null),
+    };
+  }
+  return (
+    <SurfaceContext.Provider value={held.current.surface}>
+      <SessionContext.Provider value={held.current.session}>{children}</SessionContext.Provider>
+    </SurfaceContext.Provider>
+  );
+};

package/vendor/use-agentic/AgentScope.tsx

@@ -0,0 +1,20 @@
+"use client";
+import { type ReactNode, useEffect, useMemo } from "react";
+import { AgenticSurface } from "./AgenticSurface";
+import { ScopeContext, useScopePath, useSurface } from "./surfaceContext";
+
+export interface AgentScopeProps {
+  id: string;
+  label?: string;
+  kind?: string;
+  children: ReactNode;
+}
+
+/** Namespaces every tool and resource registered below it, so list items can reuse local names. */
+export const AgentScope = ({ id, label, kind, children }: AgentScopeProps) => {
+  const surface = useSurface();
+  const parent = useScopePath();
+  const path = useMemo(() => AgenticSurface.childPath(parent, id), [parent, id]);
+  useEffect(() => surface.openScope(parent, { id, label, kind }), [surface, path.join("."), label, kind]);
+  return <ScopeContext.Provider value={path}>{children}</ScopeContext.Provider>;
+};

package/vendor/use-agentic/AgentSession.ts

@@ -0,0 +1,292 @@
+import type {
+  AgentRunner,
+  ChatMessage,
+  ContextBlock,
+  RunnerRequest,
+  SurfaceView,
+  ToolCallRequest,
+  ToolCallResult,
+  ToolEntry,
+} from "./types";
+
+export interface PendingApproval {
+  callId: string;
+  name: string;
+  args: Record<string, unknown>;
+  message: string;
+  approve: () => void;
+  reject: (reason?: string) => void;
+}
+
+/** Where a session keeps its transcript across page loads. Storage-neutral: the host decides what backs it. */
+export interface SessionHistory {
+  load(): ChatMessage[] | null;
+  save(messages: readonly ChatMessage[]): void;
+  clear(): void;
+}
+
+export interface AgentSessionOptions {
+  instructions?: string;
+  buildContext?: (surface: SurfaceView) => ContextBlock[];
+  /** Assistant turns per send before the session stops the loop. */
+  maxTurns?: number;
+  /** Restores settled messages at construction and saves after every change, debounced. Failures are silent. */
+  history?: SessionHistory;
+}
+
+/**
+ * The client-side conversation loop: send → model turn → tool calls → approval gate → execute → report diffs → next
+ * turn. The loop lives here rather than on a server because the tools do — the runner is one stateless model turn,
+ * so any backend that answers it works and none has to hold a session.
+ *
+ * Failures land in the transcript instead of being thrown past it: a refused guard, a rejected approval, and an
+ * unknown tool are all things the agent did, and the model reads them as tool results the same way a person reads
+ * them in the chat.
+ */
+export class AgentSession {
+  readonly #surface: SurfaceView;
+  readonly #runner: AgentRunner;
+  readonly #options: AgentSessionOptions;
+  #messages: ChatMessage[] = [];
+  #running = false;
+  #pending: PendingApproval | null = null;
+  #controller: AbortController | null = null;
+  #version = 0;
+  #listeners = new Set<() => void>();
+  #saveTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(surface: SurfaceView, runner: AgentRunner, options: AgentSessionOptions = {}) {
+    this.#surface = surface;
+    this.#runner = runner;
+    this.#options = options;
+    this.#messages = AgentSession.#restored(options.history);
+  }
+
+  get surface(): SurfaceView {
+    return this.#surface;
+  }
+
+  get messages(): readonly ChatMessage[] {
+    return this.#messages;
+  }
+
+  get isRunning() {
+    return this.#running;
+  }
+
+  get pendingApproval(): PendingApproval | null {
+    return this.#pending;
+  }
+
+  /** Bumped on every change, so a store binding can use it as the snapshot. */
+  get version() {
+    return this.#version;
+  }
+
+  subscribe = (listener: () => void) => {
+    this.#listeners.add(listener);
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  };
+
+  /** A user's text, or prewritten messages — how a host injects a prompt's result as the user's turn. */
+  send = async (input: string | ChatMessage[]) => {
+    if (this.#running) throw new Error("A turn is already running.");
+    this.#running = true;
+    const controller = new AbortController();
+    this.#controller = controller;
+    if (typeof input === "string") this.#append({ role: "user", text: input });
+    else for (const message of input) this.#append(message);
+    const maxTurns = this.#options.maxTurns ?? 8;
+    try {
+      for (let turn = 0; turn < maxTurns; turn += 1) {
+        if (controller.signal.aborted) return;
+        const { toolCalls, stop } = await this.#assistantTurn(controller.signal);
+        if (controller.signal.aborted || stop !== "toolUse" || !toolCalls.length) return;
+        const toolResults: ToolCallResult[] = [];
+        for (const call of toolCalls) {
+          if (controller.signal.aborted) break;
+          toolResults.push(await this.#execute(call, controller.signal));
+        }
+        this.#append({ role: "tool", toolResults });
+      }
+      this.#fail(`Stopped after ${maxTurns} assistant turns without a final answer.`);
+    } catch (error) {
+      if (!controller.signal.aborted) this.#fail(error instanceof Error ? error.message : String(error));
+    } finally {
+      this.#running = false;
+      this.#controller = null;
+      this.#pending = null;
+      this.#notify();
+    }
+  };
+
+  abort = () => {
+    this.#controller?.abort();
+  };
+
+  /** Empties the transcript and the persisted history. A running turn keeps its transcript. */
+  reset = () => {
+    if (this.#running) return;
+    this.#messages = [];
+    
+    if (this.#saveTimer) {
+      clearTimeout(this.#saveTimer);
+      this.#saveTimer = null;
+    }
+    try {
+      this.#options.history?.clear();
+    } catch {
+    }
+    this.#version += 1;
+    for (const listener of this.#listeners) listener();
+  };
+
+  /** Records a host-side failure (a prompt fetch, an upload) in the transcript, where every other failure lands. */
+  report = (error: string) => {
+    this.#append({ role: "assistant", error });
+  };
+
+  async #assistantTurn(signal: AbortSignal): Promise<{ toolCalls: ToolCallRequest[]; stop: "end" | "toolUse" }> {
+    const { tools, guides } = this.#surface.snapshot();
+    const instructions = [this.#options.instructions, ...guides].filter(Boolean).join("\n\n");
+    const request: RunnerRequest = {
+      messages: this.#messages,
+      tools,
+      context: this.#options.buildContext?.(this.#surface) ?? AgentSession.#defaultContext(this.#surface),
+      ...(instructions ? { instructions } : {}),
+      signal,
+    };
+    this.#append({ role: "assistant" });
+    let text = "";
+    const toolCalls: ToolCallRequest[] = [];
+    let stop: "end" | "toolUse" = "end";
+    for await (const event of this.#runner.run(request)) {
+      if (signal.aborted) break;
+      if (event.type === "text") {
+        text += event.delta;
+        this.#patchLast({ text });
+      } else if (event.type === "toolCall") toolCalls.push({ id: event.id, name: event.name, args: event.args });
+      else if (event.type === "done") stop = event.stop;
+      else throw new Error(event.message);
+    }
+    if (toolCalls.length) this.#patchLast({ toolCalls });
+    return { toolCalls, stop };
+  }
+
+  async #execute(call: ToolCallRequest, signal: AbortSignal): Promise<ToolCallResult> {
+    const base = { id: call.id, name: call.name };
+    const entry = this.#surface.tool(call.name);
+    if (!entry) return { ...base, error: `Unknown tool: ${call.name}` };
+    const message = AgentSession.#confirmMessage(call.name, entry, call.args);
+    if (message) {
+      const approved = await this.#awaitApproval(call, message, signal);
+      if (approved !== true) return { ...base, error: approved };
+    }
+    const before = this.#surface.snapshot();
+    try {
+      const result = await this.#surface.call(call.name, call.args);
+      const changes = this.#surface.diffSince(before);
+      return {
+        ...base,
+        ...(result !== undefined ? { result } : {}),
+        ...(changes.length ? { changes } : {}),
+      };
+    } catch (error) {
+      return { ...base, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
+  #awaitApproval(call: ToolCallRequest, message: string, signal: AbortSignal): Promise<true | string> {
+    return new Promise((resolve) => {
+      const settle = (value: true | string) => {
+        this.#pending = null;
+        signal.removeEventListener("abort", onAbort);
+        this.#notify();
+        resolve(value);
+      };
+      const onAbort = () => settle("The user aborted the turn.");
+      signal.addEventListener("abort", onAbort);
+      this.#pending = {
+        callId: call.id,
+        name: call.name,
+        args: call.args,
+        message,
+        approve: () => settle(true),
+        reject: (reason) => settle(reason ?? "The user declined."),
+      };
+      this.#notify();
+    });
+  }
+
+  static #confirmMessage(name: string, entry: ToolEntry, args: Record<string, unknown>): string | null {
+    const confirm = entry.confirm;
+    if (confirm === undefined || confirm === false) return null;
+    if (typeof confirm === "string") return confirm;
+    const verdict = confirm === true ? true : confirm(args);
+    if (verdict === false) return null;
+    return verdict === true ? `Run ${name}?` : verdict;
+  }
+
+  static #defaultContext(surface: SurfaceView): ContextBlock[] {
+    const { resources, scopes } = surface.snapshot();
+    return [
+      ...(scopes.length ? [{ kind: "screen", scopes }] : []),
+      ...(resources.length ? [{ kind: "resources", resources }] : []),
+    ];
+  }
+
+  /** Recorded on the open assistant draft when there is one, so a failed turn reads as that turn failing. */
+  #fail(message: string) {
+    const last = this.#messages[this.#messages.length - 1];
+    if (last?.role === "assistant" && !last.error) this.#patchLast({ error: message });
+    else this.#append({ role: "assistant", error: message });
+  }
+
+  #append(message: ChatMessage) {
+    this.#messages = [...this.#messages, message];
+    this.#notify();
+  }
+
+  #patchLast(patch: Partial<ChatMessage>) {
+    const last = this.#messages[this.#messages.length - 1];
+    if (!last) return;
+    this.#messages = [...this.#messages.slice(0, -1), { ...last, ...patch }];
+    this.#notify();
+  }
+
+  #notify() {
+    this.#version += 1;
+    for (const listener of this.#listeners) listener();
+    this.#schedulePersist();
+  }
+
+  /** Debounced: streaming patches the last message on every delta, and a save per delta would thrash storage. */
+  #schedulePersist() {
+    const history = this.#options.history;
+    if (!history) return;
+    if (this.#saveTimer) clearTimeout(this.#saveTimer);
+    this.#saveTimer = setTimeout(() => {
+      this.#saveTimer = null;
+      try {
+        history.save(this.#messages);
+      } catch {
+      }
+    }, 300);
+  }
+
+  static #restored(history: SessionHistory | undefined): ChatMessage[] {
+    if (!history) return [];
+    try {
+      const messages = history.load();
+      if (!Array.isArray(messages)) return [];
+      
+      return messages.filter(
+        (message) => message.role !== "assistant" || !!message.text || !!message.toolCalls?.length || !!message.error,
+      );
+    } catch {
+      return [];
+    }
+  }
+}

package/vendor/use-agentic/Agentic.tsx

@@ -0,0 +1,44 @@
+"use client";
+import { Children, type ReactElement, useEffect, useRef } from "react";
+import { useScopePath, useSurface } from "./surfaceContext";
+import type { ToolConfirm, ToolEffect } from "./types";
+
+interface AgenticProps {
+  name: string;
+  description?: string;
+  effect?: ToolEffect;
+  confirm?: ToolConfirm;
+  children: ReactElement<{ onClick?: () => unknown }>;
+}
+
+/**
+ * Registers the child's `onClick` as a no-argument tool and renders the child untouched.
+ *
+ * The first-class path is passing a hook-made tool by reference as the handler itself; this wrapper is for
+ * elements whose handler you do not own — third-party components and embeds.
+ */
+export const Agentic = ({ name, description, effect, confirm, children }: AgenticProps) => {
+  const surface = useSurface();
+  const scope = useScopePath();
+  const child = Children.only(children);
+  const live = useRef({ onClick: child.props.onClick, confirm });
+  live.current = { onClick: child.props.onClick, confirm };
+  const scopeKey = scope.join(".");
+  useEffect(() => {
+    return surface.registerTool(scope, {
+      name,
+      description,
+      effect,
+      ...(confirm === undefined
+        ? {}
+        : {
+            confirm: (args: Record<string, unknown>) => {
+              const latest = live.current.confirm;
+              return typeof latest === "function" ? latest(args) : (latest ?? false);
+            },
+          }),
+      run: () => live.current.onClick?.(),
+    });
+  }, [surface, scopeKey, name]);
+  return children;
+};