@skaile/forge-app-actions 0.0.0-stage → 0.2.0

package/dist/runtime/components-nuxt-ui/ForgeCommandPalette.vue

@@ -0,0 +1,218 @@
+<script setup>
+import { computed, nextTick, onMounted, onUnmounted, ref, watch } from "vue";
+import { useCommandPalette } from "../composables/useCommandPalette";
+import { usePaletteArgStep } from "../composables/usePaletteArgStep";
+const { queryActions, isOpen, open, close } = useCommandPalette();
+const search = ref("");
+const selectedIndex = ref(0);
+const searchInputRef = ref(null);
+const argStep = usePaletteArgStep();
+const filteredActions = computed(() => argStep.active.value ? [] : queryActions(search.value));
+const rowCount = computed(
+  () => argStep.active.value ? argStep.options.value.length : filteredActions.value.length
+);
+watch(filteredActions, () => {
+  selectedIndex.value = 0;
+});
+watch(search, (value) => {
+  if (!argStep.active.value) return;
+  selectedIndex.value = 0;
+  void argStep.query(value);
+});
+watch(isOpen, (open2) => {
+  if (!open2) {
+    search.value = "";
+    selectedIndex.value = 0;
+    argStep.cancel();
+  } else {
+    nextTick(() => focusSearch());
+  }
+});
+function focusSearch() {
+  searchInputRef.value?.inputRef?.focus();
+}
+function getGroupHeader(index) {
+  const action = filteredActions.value[index];
+  if (!action?.group) return null;
+  if (index === 0) return action.group;
+  const prev = filteredActions.value[index - 1];
+  if (prev?.group !== action.group) return action.group;
+  return null;
+}
+function handleDialogKeydown(e) {
+  if (e.key === "Escape") {
+    e.preventDefault();
+    if (argStep.active.value) {
+      argStep.cancel();
+      search.value = "";
+      selectedIndex.value = 0;
+      return;
+    }
+    close();
+    return;
+  }
+  const count = rowCount.value;
+  if (e.key === "ArrowDown") {
+    if (count === 0) return;
+    e.preventDefault();
+    selectedIndex.value = (selectedIndex.value + 1) % count;
+  } else if (e.key === "ArrowUp") {
+    if (count === 0) return;
+    e.preventDefault();
+    selectedIndex.value = (selectedIndex.value - 1 + count) % count;
+  } else if (e.key === "Enter") {
+    e.preventDefault();
+    if (argStep.active.value) {
+      void submitArg();
+    } else {
+      void selectAction(filteredActions.value[selectedIndex.value]);
+    }
+  }
+}
+async function runAction(action, value) {
+  try {
+    await action.handler(value);
+  } catch (err) {
+    console.error(`[ForgeCommandPalette] action "${action.id}" failed:`, err);
+  }
+}
+async function selectAction(action) {
+  if (!action) return;
+  if (argStep.begin(action)) {
+    search.value = "";
+    selectedIndex.value = 0;
+    nextTick(() => focusSearch());
+    return;
+  }
+  close();
+  await runAction(action);
+}
+async function submitArg() {
+  const action = argStep.action.value;
+  if (!action) return;
+  const value = argStep.valueFor(search.value, selectedIndex.value);
+  if (value === null) return;
+  argStep.cancel();
+  close();
+  await runAction(action, value);
+}
+async function selectArgOption(index) {
+  selectedIndex.value = index;
+  await submitArg();
+}
+function handleGlobalKeydown(e) {
+  if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+    e.preventDefault();
+    open();
+  }
+}
+onMounted(() => {
+  document.addEventListener("keydown", handleGlobalKeydown);
+});
+onUnmounted(() => {
+  document.removeEventListener("keydown", handleGlobalKeydown);
+});
+</script>
+
+<template>
+  <!-- Nuxt UI Modal as the palette backdrop. #content gives full control of the
+       panel (no default header/footer). -->
+  <UModal
+    :open="isOpen"
+    :ui="{ content: 'max-w-[560px] w-[95vw] p-0' }"
+    @update:open="(v) => !v && close()"
+  >
+    <template #content>
+      <div class="forge-command-palette" @keydown="handleDialogKeydown">
+        <div v-if="argStep.active.value" class="forge-command-palette__breadcrumb">
+          {{ argStep.prompt.value?.label ?? argStep.action.value?.label }}
+        </div>
+
+        <!-- Search input -->
+        <div class="forge-command-palette__search">
+          <UInput
+            ref="searchInputRef"
+            v-model="search"
+            :placeholder="argStep.active.value ? argStep.prompt.value?.placeholder ?? 'Type a value\u2026' : 'Search commands\u2026'"
+            variant="none"
+            autofocus
+            :ui="{ root: 'w-full' }"
+            class="forge-command-palette__input"
+          />
+        </div>
+
+        <!-- Results list -->
+        <div class="forge-command-palette__list" role="listbox">
+          <!-- Argument step: the pending action's candidates -->
+          <template v-if="argStep.active.value">
+            <div v-if="argStep.options.value.length === 0" class="forge-command-palette__empty">
+              {{ argStep.loading.value ? "Searching\u2026" : "Type a value and press Enter" }}
+            </div>
+            <button
+              v-for="(option, index) in argStep.options.value"
+              :key="option.value"
+              type="button"
+              class="forge-command-palette__item"
+              :class="{ 'forge-command-palette__item--selected': index === selectedIndex }"
+              role="option"
+              :aria-selected="index === selectedIndex"
+              @click="selectArgOption(index)"
+              @mouseenter="selectedIndex = index"
+            >
+              <span v-if="option.icon" class="forge-command-palette__icon">
+                <Icon :name="option.icon" />
+              </span>
+              <span class="forge-command-palette__text">
+                <span class="forge-command-palette__label">{{ option.label }}</span>
+                <span
+                  v-if="option.description"
+                  class="forge-command-palette__description"
+                >{{ option.description }}</span>
+              </span>
+            </button>
+          </template>
+
+          <template v-if="!argStep.active.value && filteredActions.length === 0">
+            <div class="forge-command-palette__empty">No commands found</div>
+          </template>
+
+          <template v-for="(action, index) in filteredActions" :key="action.id">
+            <!-- Group header -->
+            <div
+              v-if="getGroupHeader(index)"
+              class="forge-command-palette__group"
+            >
+              {{ getGroupHeader(index) }}
+            </div>
+
+            <!-- Action row -->
+            <button
+              type="button"
+              class="forge-command-palette__item"
+              :class="{ 'forge-command-palette__item--selected': index === selectedIndex }"
+              role="option"
+              :aria-selected="index === selectedIndex"
+              @click="selectAction(action)"
+              @mouseenter="selectedIndex = index"
+            >
+              <span v-if="action.icon" class="forge-command-palette__icon">
+                <Icon :name="action.icon" />
+              </span>
+              <span class="forge-command-palette__text">
+                <span class="forge-command-palette__label">{{ action.label }}</span>
+                <span
+                  v-if="action.description"
+                  class="forge-command-palette__description"
+                >{{ action.description }}</span>
+              </span>
+            </button>
+          </template>
+        </div>
+      </div>
+    </template>
+  </UModal>
+</template>
+
+<style scoped>
+.forge-command-palette__breadcrumb{color:#64748b;font-size:.75rem;font-weight:600;padding:10px 12px 0}.forge-command-palette{border-radius:8px;display:flex;flex-direction:column;overflow:hidden}.forge-command-palette__search{border-bottom:1px solid #e2e8f0;padding:12px}.forge-command-palette__input{font-size:.95rem;width:100%}.forge-command-palette__list{max-height:360px;overflow-y:auto;padding:6px}.forge-command-palette__empty{color:#94a3b8;font-size:.875rem;padding:16px;text-align:center}.forge-command-palette__group{color:#94a3b8;font-size:.7rem;font-weight:700;letter-spacing:.08em;margin-top:4px;padding:4px 8px 2px;text-transform:uppercase}.forge-command-palette__item{align-items:center;background:transparent;border:none;border-radius:6px;color:inherit;cursor:pointer;display:flex;font:inherit;gap:10px;padding:8px 10px;text-align:left;transition:background .1s ease;width:100%}.forge-command-palette__item--selected{background:#f1f5f9}.forge-command-palette__icon{color:#64748b;flex-shrink:0;width:20px}.forge-command-palette__text{display:flex;flex-direction:column;gap:1px;min-width:0}.forge-command-palette__label{font-size:.875rem;font-weight:500}.forge-command-palette__description{color:#94a3b8;font-size:.775rem;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+</style>

package/dist/runtime/components-nuxt-ui/ForgeCommandPalette.vue.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/runtime/composables/defineClientCapability.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `defineClientCapability` — authoring helper for a browser-side agent
+ * capability. Mirrors `@skaile/workspaces/app-sdk`'s `defineAppCapability`
+ * field-for-field; see `../types/client-capability` for the two deliberate
+ * divergences (`side`, `origin`).
+ *
+ * Auto-imported in consumer apps via the module's `addImportsDir` on
+ * `runtime/composables`. Also reachable explicitly through the
+ * `@skaile/forge-app-actions/client-capabilities` subpath.
+ */
+import * as z from "zod";
+import type { DefineClientCapabilityArgs, DefinedClientCapability } from "../types/client-capability.js";
+/**
+ * Build a {@link DefinedClientCapability} from author-friendly Zod-typed args.
+ *
+ * The wire `inputSchema` / `outputSchema` are **derived** from the Zod schemas
+ * via `z.toJSONSchema()` (zod v4 only) — they are never hand-written, which is
+ * what buys the validation the raw-JSON-Schema capabilities never had.
+ *
+ * `side` is fixed to `"client"`. `origin` is stamped by `ClientCapabilityBridge`
+ * when the announcement reaches Nitro.
+ *
+ * @example
+ * ```ts
+ * export const openFile = defineClientCapability({
+ *   name: "app.workspace.open_file",
+ *   displayName: "Open file in viewer",
+ *   description: "Open a file in the user's file viewer.",
+ *   kind: "effect",
+ *   audience: ["llm", "user"],
+ *   input: z.object({ path: z.string().min(1), line: z.number().optional() }),
+ *   output: z.object({ opened: z.boolean(), path: z.string() }),
+ *   handler: async ({ path, line }) => ({ opened: await openInViewer(path, line), path }),
+ * })
+ * ```
+ */
+export declare function defineClientCapability<T extends z.ZodType, R extends z.ZodType | undefined = undefined>(args: DefineClientCapabilityArgs<T, R>): DefinedClientCapability;
+/**
+ * Register an old capability name as a **deprecated alias** of a defined one.
+ *
+ * Renaming a capability is not free: `promptFragment` text names the old name
+ * literally, and agent definitions in the wild may too (spec §2.2). The alias is
+ * a second registry entry — same `inputZod`, same `outputZod`, same handler
+ * *instance* — so an invocation of either name runs exactly the same code, and
+ * the alias needs no separate maintenance.
+ *
+ * Two deliberate differences from the capability it aliases:
+ *  - `audience` is narrowed to `["llm"]`. The alias exists only for callers that
+ *    already know the old name; a deprecated duplicate has no business appearing
+ *    in a user-facing surface like Cmd+K.
+ *  - `description` and `promptFragment` are prefixed with a deprecation notice
+ *    naming the replacement, because the wire `Capability` type has no
+ *    `deprecated` flag — the model reads prose or it reads nothing.
+ *
+ * @param capability the current definition, which owns the handler
+ * @param name the old name to keep answering
+ *
+ * @example
+ * ```ts
+ * export const openFile = defineClientCapability({ name: "app.workspace.open_file", … })
+ * export const openFileAlias = deprecatedClientCapabilityAlias(openFile, "forge.open_file")
+ * ```
+ */
+export declare function deprecatedClientCapabilityAlias(capability: DefinedClientCapability, name: string): DefinedClientCapability;

package/dist/runtime/composables/defineClientCapability.js

@@ -0,0 +1,40 @@
+import * as z from "zod";
+export function defineClientCapability(args) {
+  const inputSchema = z.toJSONSchema(args.input, {
+    target: "draft-07",
+    io: "input"
+  });
+  const outputSchema = args.output ? z.toJSONSchema(args.output, {
+    target: "draft-07",
+    io: "output"
+  }) : void 0;
+  return {
+    name: args.name,
+    displayName: args.displayName,
+    description: args.description,
+    inputSchema,
+    outputSchema,
+    side: "client",
+    scope: args.scope,
+    requiresApproval: args.requiresApproval,
+    kind: args.kind,
+    audience: args.audience,
+    promptFragment: args.promptFragment,
+    callTimeoutMs: args.callTimeoutMs,
+    render: args.render,
+    inputZod: args.input,
+    outputZod: args.output,
+    handler: args.handler
+  };
+}
+export function deprecatedClientCapabilityAlias(capability, name) {
+  const notice = `DEPRECATED: use \`${capability.name}\` instead. This name still works but will be removed.`;
+  return {
+    ...capability,
+    name,
+    description: `${notice} ${capability.description}`,
+    audience: ["llm"],
+    promptFragment: capability.promptFragment ? `${notice}
+${capability.promptFragment}` : void 0
+  };
+}

package/dist/runtime/composables/defineForgeAction.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `defineForgeAction` — one declaration for Cmd+K and the agent.
+ *
+ * Spec: `docs/superpowers/specs/2026-08-22-forge-app-channel-design.md` §2.3,
+ * which adopts the platform's rule verbatim — *"All user-facing functionality is
+ * a command-palette action; register it so it is discoverable via Cmd+K **and**
+ * usable by the AI agent"*.
+ *
+ * ```ts
+ * export const openFile = defineForgeAction({
+ *   id: "workspace.open_file",           // → capability `app.workspace.open_file`
+ *   label: "Open file…",
+ *   description: "Open a file in the user's file viewer.",
+ *   input: z.object({ path: z.string().min(1) }),
+ *   arg: { placeholder: "path/to/file", toInput: (path) => ({ path }) },
+ *   run: async ({ path }) => { await useFileViewer().openFile(path); return { opened: true, path } },
+ * })
+ * ```
+ *
+ * `audience` defaults to `['user', 'llm']`. That default is the whole point:
+ * a new UI feature is agent-controllable unless its author opts out, instead of
+ * agent-controllability being a bespoke per-feature integration.
+ *
+ * ## No third registry
+ *
+ * This does not store anything. It *projects* one declaration into the two
+ * registries forge already had — `useCommandPalette()` (idempotent by id) and
+ * `useAgentCapabilities()` (idempotent by name) — and `useForgeActions()`
+ * writes through to both. Those remain the single sources of truth for "what is
+ * in the palette" and "what may the agent call", so nothing can drift.
+ *
+ * ## The id/name seam
+ *
+ * The palette has always used bare ids (`workspace.open_file`); the platform
+ * **rejects** capability registrations outside the `app.` namespace (spec §2.2).
+ * The rule is therefore: **author the palette id, and the capability name is
+ * `app.<id>`.** An id that already carries the prefix is a mistake and throws,
+ * because otherwise `app.app.workspace.open_file` would ship silently.
+ */
+import * as z from "zod";
+import type { DefineForgeActionArgs, ForgeAction, ForgeActionAudience } from "../types/forge-action.js";
+/** The default when `audience` is omitted: reachable from both surfaces. */
+export declare const DEFAULT_FORGE_ACTION_AUDIENCE: ForgeActionAudience[];
+/**
+ * Build a {@link ForgeAction} from one declaration.
+ *
+ * Throws — at define time, i.e. on the first import in dev — for the four
+ * declarations that could only fail later and further away:
+ *  - an `id` that already starts with `app.` (see the id/name seam above),
+ *  - an llm-audience action with no `description` (the model reads nothing),
+ *  - an llm-audience `id` that is not `<sector>.<verb>` (spec §2.2's namespace),
+ *  - a user-audience action whose input needs arguments but declares no `arg`
+ *    (a palette row that exists only to fail on Enter).
+ */
+export declare function defineForgeAction<T extends z.ZodType = z.ZodObject<Record<string, never>>>(args: DefineForgeActionArgs<T>): ForgeAction;
+export interface UseForgeActionsReturn {
+    /**
+     * Write one action through to the registries its audience names. Idempotent:
+     * the palette replaces by id and the capability registry replaces by name,
+     * exactly as they already did, so re-registering on HMR or a remount is a
+     * no-op rather than a duplicate.
+     */
+    register(action: ForgeAction): ForgeAction;
+    /** Register several, in order. */
+    registerAll(actions: ForgeAction[]): void;
+    /**
+     * Remove an action from both registries, aliases included. Takes the action
+     * itself rather than an id — the aliases it owns cannot be derived from one.
+     */
+    unregister(action: ForgeAction): void;
+}
+/**
+ * Register forge actions into the palette and the agent capability registry.
+ *
+ * ```ts
+ * export default defineNuxtPlugin(() => {
+ *   useForgeActions().registerAll([openFile, toggleSidebar])
+ *   // then announce upward once — see the app-channel wiring
+ * })
+ * ```
+ */
+export declare function useForgeActions(): UseForgeActionsReturn;

package/dist/runtime/composables/defineForgeAction.js

@@ -0,0 +1,147 @@
+import * as z from "zod";
+import { defineClientCapability, deprecatedClientCapabilityAlias } from "./defineClientCapability.js";
+import { useAgentCapabilities } from "./useAgentCapabilities.js";
+import { useCommandPalette } from "./useCommandPalette.js";
+export const DEFAULT_FORGE_ACTION_AUDIENCE = ["user", "llm"];
+const ID_PATTERN = /^[a-z0-9][a-z0-9_-]*(?:\.[a-z0-9][a-z0-9_-]*)+$/;
+const defaultLog = {
+  info: (message, ...args) => console.log(message, ...args),
+  warn: (message, ...args) => console.warn(message, ...args),
+  error: (message, ...args) => console.error(message, ...args)
+};
+function fail(id, message) {
+  throw new Error(`[defineForgeAction] ${id}: ${message}`);
+}
+export function defineForgeAction(args) {
+  const { id } = args;
+  if (!id || id.trim().length === 0) fail("<empty>", "an action needs a non-empty id.");
+  const audience = args.audience ?? DEFAULT_FORGE_ACTION_AUDIENCE;
+  if (audience.length === 0) {
+    fail(id, "audience is empty \u2014 an action nobody can trigger is not an action.");
+  }
+  const forUser = audience.includes("user");
+  const forLlm = audience.includes("llm");
+  if (id.startsWith("app.")) {
+    fail(
+      id,
+      `the id is the PALETTE id and must not carry the \`app.\` prefix \u2014 it is added automatically to derive the capability name. Use "${id.slice(4)}".`
+    );
+  }
+  const name = args.name ?? `app.${id}`;
+  if (forLlm) {
+    if (!args.description) {
+      fail(id, "an action with audience 'llm' must declare a description \u2014 the model reads it.");
+    }
+    if (!args.name && !ID_PATTERN.test(id)) {
+      fail(
+        id,
+        `an agent-visible id must be lowercase \`<sector>.<verb>\` (spec \xA72.2), so the derived capability name lands in the platform's \`app.\` namespace as \`app.${id}\`.`
+      );
+    }
+    if (!name.startsWith("app.")) {
+      fail(
+        id,
+        `capability name "${name}" is outside the \`app.\` namespace, which the platform rejects.`
+      );
+    }
+  }
+  const inputZod = args.input ?? z.object({});
+  const acceptsNoArgs = inputZod.safeParse({}).success;
+  if (forUser && !acceptsNoArgs && !args.arg) {
+    fail(
+      id,
+      "the input schema requires arguments but no `arg` was declared, so the Cmd+K entry could never run. Declare `arg: { placeholder, toInput }` (and optionally `options` for a picker), or narrow the audience to ['llm']."
+    );
+  }
+  async function run(rawInput, ctxIn) {
+    const parsed = inputZod.parse(rawInput ?? {});
+    const ctx = {
+      source: ctxIn?.source ?? "user",
+      name: ctxIn?.name ?? name,
+      sessionKey: ctxIn?.sessionKey ?? "",
+      callId: ctxIn?.callId,
+      log: ctxIn?.log ?? defaultLog
+    };
+    return await args.run(parsed, ctx);
+  }
+  let paletteAction;
+  if (forUser) {
+    paletteAction = {
+      id,
+      label: args.label,
+      // The model's description is written to be exhaustive; a palette row is
+      // one line. `hint` is where an action visible on both surfaces says the
+      // short version.
+      description: args.hint ?? args.description,
+      icon: args.icon,
+      keywords: args.keywords,
+      group: args.group,
+      // `arg` carries `toInput`, which is this module's business, not the
+      // palette's — project down to the prompt half the component consumes.
+      arg: args.arg ? {
+        label: args.arg.label,
+        placeholder: args.arg.placeholder,
+        options: args.arg.options,
+        allowCustom: args.arg.allowCustom
+      } : void 0,
+      handler: async (value) => {
+        const input = args.arg ? args.arg.toInput(value ?? "") : {};
+        await run(input, { source: "user" });
+      }
+    };
+  }
+  const capability = forLlm ? defineClientCapability({
+    name,
+    displayName: args.label,
+    description: args.description,
+    input: inputZod,
+    output: args.output,
+    kind: args.kind,
+    audience,
+    scope: args.scope,
+    requiresApproval: args.requiresApproval,
+    promptFragment: args.promptFragment,
+    callTimeoutMs: args.callTimeoutMs,
+    render: args.render,
+    // Input arrives already parsed by `useCapabilityInvocations`; re-parsing
+    // here would only pay the cost twice.
+    handler: async (input, capCtx) => await args.run(input, {
+      source: "llm",
+      name: capCtx.name,
+      sessionKey: capCtx.sessionKey,
+      callId: capCtx.callId,
+      log: capCtx.log
+    })
+  }) : void 0;
+  const aliases = capability && args.deprecatedNames ? args.deprecatedNames.map((old) => deprecatedClientCapabilityAlias(capability, old)) : [];
+  return {
+    id,
+    name,
+    label: args.label,
+    audience,
+    inputZod,
+    paletteAction,
+    capability,
+    aliases,
+    run
+  };
+}
+export function useForgeActions() {
+  const palette = useCommandPalette();
+  const capabilities = useAgentCapabilities();
+  function register(action) {
+    if (action.paletteAction) palette.registerAction(action.paletteAction);
+    if (action.capability) capabilities.register(action.capability);
+    for (const alias of action.aliases) capabilities.register(alias);
+    return action;
+  }
+  function registerAll(actions) {
+    for (const action of actions) register(action);
+  }
+  function unregister(action) {
+    palette.unregisterAction(action.id);
+    capabilities.unregister(action.name);
+    for (const alias of action.aliases) capabilities.unregister(alias.name);
+  }
+  return { register, registerAll, unregister };
+}

package/dist/runtime/composables/useAgentCapabilities.d.ts

@@ -0,0 +1,78 @@
+import { type ShallowRef } from "vue";
+import type { ClientCapabilityDescriptor, DefinedClientCapability } from "../types/client-capability.js";
+/** Minimal `fetch` shape the announce transport needs. Injectable for tests. */
+export type CapabilityAnnounceFetcher = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+}>;
+export interface AnnounceOptions {
+    /**
+     * The upward POST endpoint, e.g. `/api/agent/capabilities`. The consuming app
+     * owns this route (spec §2) — forge-app-actions never assumes a path.
+     */
+    endpoint: string;
+    /**
+     * Extra fields merged into the JSON body. This is where the app supplies
+     * whatever identifies the session to its own route — a single-session app
+     * sends nothing; a multi-user app would send the parts of its
+     * `userId:slug:mode` key. Never send the derived key from the browser if the
+     * server can derive it itself.
+     */
+    body?: Record<string, unknown>;
+    /** Override the fetcher. Defaults to `globalThis.fetch`. */
+    fetcher?: CapabilityAnnounceFetcher;
+}
+export interface AnnounceResult {
+    ok: boolean;
+    /** How many capability descriptors were sent. `0` for a withdrawal. */
+    sent: number;
+    /** Present when `ok` is false. */
+    error?: string;
+}
+export interface UseAgentCapabilitiesReturn {
+    /** Register a capability. Idempotent by name — replaces an existing entry. */
+    register(capability: DefinedClientCapability): void;
+    /** Register several at once. Idempotent by name, in order. */
+    registerAll(capabilities: DefinedClientCapability[]): void;
+    /** Remove a previously registered capability. No-op if the name is unknown. */
+    unregister(name: string): void;
+    /** Look up one registered capability by name. */
+    get(name: string): DefinedClientCapability | undefined;
+    /** Snapshot of every registered capability (schemas and handlers included). */
+    list(): DefinedClientCapability[];
+    /** The JSON-serialisable projection announced upward. */
+    toWire(): ClientCapabilityDescriptor[];
+    /** Reactive list of registered capabilities. */
+    capabilities: Readonly<ShallowRef<DefinedClientCapability[]>>;
+    /** Stable per-tab token sent with every announcement. */
+    subscriberId: string;
+    /**
+     * POST the whole registry upward. Announcements are never deltas — the bridge
+     * replaces its stored list, so a reconnect re-announce is naturally idempotent
+     * (spec §L5).
+     *
+     * Never throws: a failed announce logs a warning and returns `ok: false`, so a
+     * dead route cannot break app mount.
+     */
+    announce(options: AnnounceOptions): Promise<AnnounceResult>;
+    /**
+     * POST an empty registry upward — the explicit withdrawal seam for spec §L1's
+     * "no browser, no capability". Ticket 05 adds the SSE-disconnect grace period
+     * that calls this from the server side; this is the voluntary client-side path.
+     */
+    withdraw(options: AnnounceOptions): Promise<AnnounceResult>;
+    /** Test-only: empty the singleton. Not for application code. */
+    reset(): void;
+}
+/**
+ * Browser-side agent capability registry.
+ *
+ * Components and plugins call `register()` to declare what the agent may invoke
+ * in this tab, then `announce()` once on mount so Nitro — and through it the
+ * agent's `capability_register` — reflects that a UI actually exists.
+ */
+export declare function useAgentCapabilities(): UseAgentCapabilitiesReturn;