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

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @skaile/forge-app-actions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browser-declared app actions for Skaile forge apps, as a Nuxt module.
+
+One `defineForgeAction` declaration is both a command-palette row and an agent capability. The package ships
+
+- `defineForgeAction`, `useForgeActions`, `defineClientCapability` (auto-imported in a Nuxt app, or imported from `@skaile/forge-app-actions/client-capabilities`),
+- `useAgentCapabilities` (announce) and `useCapabilityInvocations` (handle `capability_invoked` from the app's SSE and post the result),
+- `useCapabilityApproval` + `<ForgeCapabilityApproval />` (approval dialog),
+- `useCommandPalette` + `<ForgeCommandPalette />`,
+- the Nitro-side bridge (`clientCapabilityBridge`, `capabilityRegistry`) via `@skaile/forge-app-actions/server`.
+
+## Install
+
+```ts
+// nuxt.config.ts — @nuxt/ui must come first
+export default defineNuxtConfig({
+  modules: ['@nuxt/ui', '@skaile/forge-app-actions'],
+})
+```
+
+Peers: `@nuxt/ui ^4.11`, `nuxt`, `vue`; `@skaile/workspaces ^6` is an optional peer (type-only imports from `@skaile/workspaces/sdk/types`).
+
+`@skaile/forge-common` installs this module for you.
+
+## Exports
+
+| Subpath | Contents |
+|---|---|
+| `.` | the Nuxt module (`forgeAppActions` config key) |
+| `./client-capabilities` | browser-side API, explicit-import entry for tests and non-auto-import contexts |
+| `./server` | `clientCapabilityBridge`, `capabilityRegistry`, `routeCapabilityInvocation`, … |
+| `./types` | `ClientCapability*`, `ForgeAction*`, `Palette*` types |
+
+Moved here from `@skaile-ai/forge-common` 9.x (`./client-capabilities` and the capability parts of `./server` and `./types`).

package/dist/module.d.mts

@@ -0,0 +1,23 @@
+import { NuxtModule } from '@nuxt/schema';
+
+interface ForgeAppActionsOptions {
+    /** Disable server-side auto-imports (use explicit imports via the `./server` subpath instead). */
+    serverAutoImport?: boolean;
+    /** Disable component auto-registration. */
+    componentAutoRegister?: boolean;
+    /** Disable composable auto-imports. */
+    composableAutoImport?: boolean;
+}
+/**
+ * Nuxt module for browser-declared app actions: `defineForgeAction` /
+ * `defineClientCapability`, the agent capability bridge, the command palette
+ * and the approval dialog.
+ *
+ * Requires `@nuxt/ui` (^4.11) registered BEFORE this module in `modules`; the
+ * components render Nuxt UI primitives (<UModal>, <UButton>, <UInput>) and the
+ * host root must be wrapped in `<UApp>`.
+ */
+declare const forgeAppActionsModule: NuxtModule<ForgeAppActionsOptions>;
+
+export { forgeAppActionsModule as default };
+export type { ForgeAppActionsOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@skaile/forge-app-actions",
+  "configKey": "forgeAppActions",
+  "version": "0.1.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,37 @@
+import { defineNuxtModule, createResolver, hasNuxtModule, addServerImportsDir, addComponentsDir, addImportsDir } from '@nuxt/kit';
+
+const forgeAppActionsModule = defineNuxtModule({
+  meta: {
+    name: "@skaile/forge-app-actions",
+    configKey: "forgeAppActions"
+  },
+  defaults: {
+    serverAutoImport: true,
+    componentAutoRegister: true,
+    composableAutoImport: true
+  },
+  async setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+    if (!nuxt.options._prepare && !hasNuxtModule("@nuxt/ui", nuxt)) {
+      throw new Error(
+        "[@skaile/forge-app-actions] requires the '@nuxt/ui' module, but it was not registered before '@skaile/forge-app-actions'. Add '@nuxt/ui' to the `modules` array in your nuxt.config *before* '@skaile/forge-app-actions' (and install it as a dependency): the command palette and approval dialog render Nuxt UI primitives (<UModal>, <UButton>, \u2026)."
+      );
+    }
+    if (options.serverAutoImport) {
+      addServerImportsDir(resolve("./runtime/server/utils"));
+    }
+    if (options.componentAutoRegister) {
+      addComponentsDir({
+        path: resolve("./runtime/components-nuxt-ui"),
+        prefix: "Forge",
+        global: false,
+        pathPrefix: false
+      });
+    }
+    if (options.composableAutoImport) {
+      addImportsDir(resolve("./runtime/composables"));
+    }
+  }
+});
+
+export { forgeAppActionsModule as default };

package/dist/runtime/client-capabilities.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Explicit entry point for the browser-side agent capability API.
+ *
+ * In a Nuxt consumer both symbols are auto-imported (the module's
+ * `addImportsDir` on `runtime/composables`), so application code needs no
+ * import at all. This subpath exists for the contexts auto-imports do not
+ * reach: vitest specs, plain `.ts` modules outside the Nuxt app dir, and
+ * non-Nuxt consumers.
+ *
+ *   import { defineClientCapability } from "@skaile/forge-app-actions/client-capabilities"
+ *
+ * Since ticket 07 this is also where the *unified* action API lives —
+ * `defineForgeAction` / `useForgeActions`, plus `useCommandPalette` itself, so a
+ * consumer's tests can reach both halves of one declaration without relying on
+ * Nuxt's auto-imports.
+ *
+ * The Nitro-side counterpart (`ClientCapabilityBridge`) is server-only and
+ * ships through the `./server` subpath instead.
+ */
+export { defineClientCapability, deprecatedClientCapabilityAlias, } from "./composables/defineClientCapability.js";
+export { DEFAULT_FORGE_ACTION_AUDIENCE, defineForgeAction, type UseForgeActionsReturn, useForgeActions, } from "./composables/defineForgeAction.js";
+export { type AnnounceOptions, type AnnounceResult, type CapabilityAnnounceFetcher, type UseAgentCapabilitiesReturn, useAgentCapabilities, } from "./composables/useAgentCapabilities.js";
+export { type CapabilityApprovalDecision, type CapabilityApprovalOptions, type CapabilityApprovalRequest, DEFAULT_APPROVAL_TIMEOUT_MS, type UseCapabilityApprovalReturn, useCapabilityApproval, } from "./composables/useCapabilityApproval.js";
+export { type CapabilityInvokedEvent, type HandleInvocationOptions, type InvocationFailure, type InvocationOutcome, type UseCapabilityInvocationsReturn, useCapabilityInvocations, } from "./composables/useCapabilityInvocations.js";
+export { type UseCommandPaletteReturn, useCommandPalette, } from "./composables/useCommandPalette.js";
+export { type UsePaletteArgStepReturn, usePaletteArgStep, } from "./composables/usePaletteArgStep.js";
+export type { ClientCapabilityAnnouncement, ClientCapabilityContext, ClientCapabilityDescriptor, ClientCapabilityLogger, ClientCapabilityOrigin, DefineClientCapabilityArgs, DefinedClientCapability, } from "./types/client-capability.js";
+export type { PaletteAction, PaletteArgOption, PaletteArgPrompt, } from "./types/command-palette.js";
+export type { DefineForgeActionArgs, ForgeAction, ForgeActionArg, ForgeActionAudience, ForgeActionContext, } from "./types/forge-action.js";

package/dist/runtime/client-capabilities.js

@@ -0,0 +1,25 @@
+export {
+  defineClientCapability,
+  deprecatedClientCapabilityAlias
+} from "./composables/defineClientCapability.js";
+export {
+  DEFAULT_FORGE_ACTION_AUDIENCE,
+  defineForgeAction,
+  useForgeActions
+} from "./composables/defineForgeAction.js";
+export {
+  useAgentCapabilities
+} from "./composables/useAgentCapabilities.js";
+export {
+  DEFAULT_APPROVAL_TIMEOUT_MS,
+  useCapabilityApproval
+} from "./composables/useCapabilityApproval.js";
+export {
+  useCapabilityInvocations
+} from "./composables/useCapabilityInvocations.js";
+export {
+  useCommandPalette
+} from "./composables/useCommandPalette.js";
+export {
+  usePaletteArgStep
+} from "./composables/usePaletteArgStep.js";

package/dist/runtime/components-nuxt-ui/ForgeCapabilityApproval.d.vue.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/components-nuxt-ui/ForgeCapabilityApproval.vue

@@ -0,0 +1,125 @@
+<script setup>
+import { computed, onMounted, onUnmounted, ref } from "vue";
+import { useCapabilityApproval } from "../composables/useCapabilityApproval";
+const { current, approve, decline } = useCapabilityApproval();
+const title = computed(() => current.value?.displayName || current.value?.name || "");
+const argumentRows = computed(() => {
+  const input = current.value?.input;
+  if (input === void 0 || input === null) return [];
+  if (typeof input === "object" && !Array.isArray(input)) {
+    return Object.entries(input).map(([key, value]) => ({
+      key,
+      value: format(value)
+    }));
+  }
+  return [{ key: "", value: format(input) }];
+});
+function format(value) {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+const now = ref(Date.now());
+let ticker;
+onMounted(() => {
+  ticker = setInterval(() => {
+    now.value = Date.now();
+  }, 500);
+});
+onUnmounted(() => clearInterval(ticker));
+const secondsLeft = computed(() => {
+  const request = current.value;
+  if (request?.expiresAt === void 0) return null;
+  const remaining = Math.min(
+    request.expiresAt - now.value,
+    request.timeoutMs ?? Number.MAX_SAFE_INTEGER
+  );
+  return Math.max(0, Math.ceil(remaining / 1e3));
+});
+function onApprove() {
+  const id = current.value?.id;
+  if (id) approve(id);
+}
+function onDecline() {
+  const id = current.value?.id;
+  if (id) decline(id);
+}
+</script>
+
+<template>
+  <UModal
+    :open="current !== null"
+    title="Allow this action?"
+    :ui="{ content: 'max-w-[480px] w-[95vw]' }"
+    @update:open="(v) => !v && onDecline()"
+  >
+    <template #content>
+      <div class="forge-capability-approval" data-testid="capability-approval" @keydown.esc.prevent="onDecline">
+        <h2 class="forge-capability-approval__heading">Allow this action?</h2>
+
+        <template v-if="current">
+          <p class="forge-capability-approval__intro">
+            The agent wants to run
+            <strong data-testid="capability-approval-title">{{ title }}</strong>
+          </p>
+
+          <code class="forge-capability-approval__name" data-testid="capability-approval-name">{{
+            current.name
+          }}</code>
+
+          <p
+            v-if="current.description"
+            class="forge-capability-approval__description"
+            data-testid="capability-approval-description"
+          >
+            {{ current.description }}
+          </p>
+
+          <div class="forge-capability-approval__args" data-testid="capability-approval-args">
+            <div class="forge-capability-approval__args-label">Arguments</div>
+            <div v-if="argumentRows.length === 0" class="forge-capability-approval__arg-empty">
+              none
+            </div>
+            <div
+              v-for="row in argumentRows"
+              :key="row.key"
+              class="forge-capability-approval__arg"
+            >
+              <span v-if="row.key" class="forge-capability-approval__arg-key">{{ row.key }}</span>
+              <span class="forge-capability-approval__arg-value">{{ row.value }}</span>
+            </div>
+          </div>
+
+          <p
+            v-if="secondsLeft !== null"
+            class="forge-capability-approval__countdown"
+            data-testid="capability-approval-countdown"
+          >
+            Expires in {{ secondsLeft }}s if unanswered.
+          </p>
+        </template>
+
+        <div class="forge-capability-approval__actions">
+          <!-- Decline is focused first on purpose: this dialog can appear while
+               the user is typing, and a stray Enter must not approve an action. -->
+          <UButton
+            label="Decline"
+            color="neutral"
+            variant="subtle"
+            autofocus
+            data-testid="capability-approval-decline"
+            @click="onDecline"
+          />
+          <UButton label="Allow" data-testid="capability-approval-approve" @click="onApprove" />
+        </div>
+      </div>
+    </template>
+  </UModal>
+</template>
+
+<style scoped>
+.forge-capability-approval{display:flex;flex-direction:column;font-size:.9rem;gap:10px;padding:16px}.forge-capability-approval__heading{font-size:1rem;font-weight:600;margin:0}.forge-capability-approval__intro{margin:0}.forge-capability-approval__name{align-self:flex-start;background:#f1f5f9;border-radius:4px;color:#475569;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.8rem;padding:2px 6px}.forge-capability-approval__description{color:#64748b;margin:0}.forge-capability-approval__args{background:#f8fafc;border:1px solid #e2e8f0;border-radius:6px;display:flex;flex-direction:column;gap:4px;padding:8px 10px}.forge-capability-approval__args-label{color:#94a3b8;font-size:.7rem;font-weight:700;letter-spacing:.08em;text-transform:uppercase}.forge-capability-approval__arg{align-items:baseline;display:flex;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.8rem;gap:8px;word-break:break-all}.forge-capability-approval__arg-key{color:#64748b;flex-shrink:0}.forge-capability-approval__arg-key:after{content:":"}.forge-capability-approval__arg-empty{color:#94a3b8;font-size:.8rem}.forge-capability-approval__countdown{color:#94a3b8;font-size:.75rem;margin:0}.forge-capability-approval__actions{display:flex;gap:8px;justify-content:flex-end;margin-top:4px}
+</style>

package/dist/runtime/components-nuxt-ui/ForgeCapabilityApproval.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/components-nuxt-ui/ForgeCommandPalette.d.vue.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/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
+  };
+}