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

package/dist/runtime/shims-vue.d.ts

@@ -0,0 +1,8 @@
+// Ambient module declaration so `tsc --noEmit` resolves `*.vue` imports.
+// Runtime resolution is handled by Vite / @vitejs/plugin-vue at build time.
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+  // biome-ignore lint/suspicious/noExplicitAny: catch-all for SFC components
+  const component: DefineComponent<object, object, any>;
+  export default component;
+}

package/dist/runtime/types/client-capability.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Types for the **forge app channel** — capabilities that are declared in the
+ * browser, announced upward through Nitro, and (from ticket 04 onward) invoked
+ * by the agent with the handler running where the state actually lives.
+ *
+ * The authoring shape deliberately mirrors `@skaile/workspaces/app-sdk`'s
+ * `defineAppCapability` field-for-field, so that a second transport (registering
+ * into the *platform's* session agent when a forge app is embedded as a
+ * `protocol: true` preview app) becomes a transport swap rather than a rewrite.
+ * See `docs/superpowers/specs/2026-08-22-forge-app-channel-design.md` §2.1.
+ *
+ * Two deliberate divergences from `defineAppCapability`, both forced by the
+ * protocol version forge pins:
+ *
+ * - `side` is `"client"`, not `"app"`. The `Capability.side` union in the
+ *   `@skaile/workspaces` releases forge pins (0.13.0 … 0.48.1) is
+ *   `"client" | "agent"`; `"app"` only exists on the 3.x line that also ships
+ *   `app-sdk`. Forge's own agent treats the browser as the *client* side, which
+ *   is what `"client"` already means on the wire.
+ * - `origin` is not authored here. `defineAppCapability` has the SDK stamp it at
+ *   registration time because only the SDK knows the `appId`; forge has no
+ *   `appId`, so {@link ClientCapabilityBridge} stamps `{ kind: "client" }` when
+ *   the announcement reaches Nitro. Same split, different stamper.
+ */
+import type { CapabilityAudience, CapabilityOrigin, RenderSpec } from "@skaile/workspaces/sdk/types";
+import type * as z from "zod";
+/**
+ * Logger handed to a client capability handler. Structural subset of `console`
+ * (and of consola), so either can be passed without an adapter.
+ */
+export interface ClientCapabilityLogger {
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Per-invocation context passed to a client capability handler.
+ *
+ * The analogue of `app-sdk`'s `AppHandlerContext`. It carries the bridge's
+ * opaque {@link ClientCapabilityContext.sessionKey} instead of a platform
+ * `sessionId`, and has no `appId` (forge apps are not registered platform apps).
+ */
+export interface ClientCapabilityContext {
+    /**
+     * The opaque session key this invocation was routed under — the same string
+     * the SPA announced with. See the bridge's session-key contract.
+     */
+    sessionKey: string;
+    /** Correlation token of the originating `capability_invoked` event. */
+    callId: string;
+    /** The capability name as invoked (useful when one handler serves aliases). */
+    name: string;
+    /** Logger to emit through; defaults to `console`. */
+    log: ClientCapabilityLogger;
+}
+/**
+ * Author-facing arguments to `defineClientCapability`.
+ *
+ * Field names are identical to `app-sdk`'s `DefineAppCapabilityArgs`, minus
+ * `side` (fixed) and `origin` (stamped by the bridge).
+ */
+export interface DefineClientCapabilityArgs<T extends z.ZodType, R extends z.ZodType | undefined = undefined> {
+    /**
+     * Stable, session-unique name. Convention: `app.<sector>.<verb>` — e.g.
+     * `app.workspace.open_file`. The platform rejects registrations outside the
+     * `app.` namespace; forge's own agent does not, but the convention is adopted
+     * now so a later embed costs no rename.
+     */
+    name: string;
+    /** Human-readable label for user-facing surfaces; falls back to `name`. */
+    displayName?: string;
+    /** Human/LLM-readable summary; shown to the agent at tool registration. */
+    description: string;
+    /** Zod schema validating the invocation arguments. Converted to JSON Schema. */
+    input: T;
+    /** Optional Zod schema for the return value. */
+    output?: R;
+    /** Lifetime: `session` survives the whole session, `turn` is dropped at end-of-turn. */
+    scope?: "session" | "turn";
+    /**
+     * When true, the invocation must be confirmed before the handler runs. Forge
+     * has no platform approval gate — spec §L7 puts the confirm in the browser
+     * wrapper. Declared here so the field survives a transport swap.
+     */
+    requiresApproval?: boolean;
+    /** Documentation hint: side-effect, render, or pure query. */
+    kind?: "effect" | "render" | "query";
+    /** Audience scoping. Omit for the wire default (`['llm','user']`). */
+    audience?: CapabilityAudience[];
+    /** Appended to the system prompt's `<CAPABILITIES>` section. */
+    promptFragment?: string;
+    /** Per-capability override for the result round-trip timeout. */
+    callTimeoutMs?: number;
+    /** Render contract for capabilities that produce a UI surface. */
+    render?: RenderSpec;
+    /**
+     * The handler — runs in the browser. Receives validated input plus a
+     * {@link ClientCapabilityContext}.
+     *
+     * Not invoked by this ticket: the announce half only makes the agent's tool
+     * list truthful. Dispatch lands in ticket 04.
+     */
+    handler: (args: z.infer<T>, ctx: ClientCapabilityContext) => Promise<R extends z.ZodType ? z.infer<R> : unknown>;
+}
+/**
+ * A defined client capability: the wire fields the bridge announces, plus the
+ * Zod schemas and type-erased handler kept browser-side for runtime validation
+ * and inbound dispatch.
+ *
+ * `inputZod` / `outputZod` / `handler` never cross the wire — see
+ * {@link ClientCapabilityDescriptor}.
+ */
+export interface DefinedClientCapability {
+    name: string;
+    displayName?: string;
+    description: string;
+    /** Derived from `input` via `z.toJSONSchema()` — never hand-written. */
+    inputSchema: Record<string, unknown>;
+    /** Derived from `output` via `z.toJSONSchema()` when `output` is declared. */
+    outputSchema?: Record<string, unknown>;
+    /** Always `"client"` — the handler runs in the browser. */
+    side: "client";
+    scope?: "session" | "turn";
+    requiresApproval?: boolean;
+    kind?: "effect" | "render" | "query";
+    audience?: CapabilityAudience[];
+    promptFragment?: string;
+    callTimeoutMs?: number;
+    render?: RenderSpec;
+    /** Original Zod schema for runtime input validation. Not serialized. */
+    readonly inputZod: z.ZodType;
+    /** Original Zod schema for the optional output, if declared. Not serialized. */
+    readonly outputZod?: z.ZodType;
+    /** Type-erased handler, dispatched on an inbound `capability_invoked`. */
+    handler: (args: unknown, ctx: ClientCapabilityContext) => Promise<unknown>;
+}
+/**
+ * The JSON-serialisable half of a {@link DefinedClientCapability} — exactly what
+ * the SPA POSTs upward in an announcement. `origin` is absent: the bridge stamps
+ * it (see the module docblock).
+ */
+export type ClientCapabilityDescriptor = Omit<DefinedClientCapability, "inputZod" | "outputZod" | "handler">;
+/**
+ * Body of an upward announcement POST, minus whatever session-identifying
+ * fields the consuming app's route adds (forge-workspace adds `mode`).
+ */
+export interface ClientCapabilityAnnouncement {
+    /**
+     * Stable per-tab token. The bridge records it as the session's owner so
+     * spec §L4's last-writer-wins routing has something to compare (ticket 05).
+     */
+    subscriberId?: string;
+    /** The full registry, always sent whole — announcements are not deltas. */
+    capabilities: ClientCapabilityDescriptor[];
+}
+/** Origin kind a client capability always carries once stamped by the bridge. */
+export type ClientCapabilityOrigin = Extract<CapabilityOrigin, {
+    kind: "client";
+}>;

package/dist/runtime/types/command-palette.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Types for the forge command palette (Cmd+K / Ctrl+K global action menu).
+ */
+/** One candidate value offered while the palette collects an action's argument. */
+export interface PaletteArgOption {
+    /** The value handed to the action's handler when this row is picked. */
+    value: string;
+    /** Display label shown in the list. */
+    label: string;
+    /** Optional secondary line. */
+    description?: string;
+    /** Iconify icon name, e.g. `"lucide:file"`. */
+    icon?: string;
+}
+/**
+ * Declares that an action needs **one string argument** before it can run, and
+ * how the palette should collect it.
+ *
+ * Selecting such an action does not close the palette: it switches into an
+ * argument step (breadcrumb + a fresh input), and only the second Enter runs
+ * the handler. Escape returns to the action list.
+ *
+ * This exists because {@link https://github.com/skaile-ai/forge-app-actions | forge}
+ * actions are declared once for two audiences (see `defineForgeAction`): the
+ * agent supplies `{ path }` as structured input, and the user needs somewhere
+ * to type it. Without this seam a palette entry for an action with required
+ * input could only ever fail on Enter.
+ */
+export interface PaletteArgPrompt {
+    /** Breadcrumb shown during the argument step. Defaults to the action label. */
+    label?: string;
+    /** Placeholder for the argument input. */
+    placeholder?: string;
+    /**
+     * Candidate values for the current query — a file search, a list of models,
+     * whatever the argument ranges over. Omit for a free-text argument.
+     *
+     * Called on every keystroke; implementations should debounce or abort their
+     * own I/O (see `useFileSearch`). A rejected promise is treated as "no
+     * candidates", never as a palette error.
+     */
+    options?: (query: string) => PaletteArgOption[] | Promise<PaletteArgOption[]>;
+    /**
+     * Accept a value the user typed that is not among `options`. Defaults to
+     * `true` when `options` is absent (free text), `false` when it is present
+     * (pick-from-list).
+     */
+    allowCustom?: boolean;
+}
+export interface PaletteAction {
+    /** Unique stable identifier, e.g. `"workspace.open-file"`. */
+    id: string;
+    /** Display label shown in the list. */
+    label: string;
+    /** Optional secondary line (hint, shortcut, description). */
+    description?: string;
+    /** Iconify icon name, e.g. `"lucide:file"`. */
+    icon?: string;
+    /**
+     * Called when the user selects this action.
+     *
+     * Receives the collected string when {@link PaletteAction.arg} is declared,
+     * and nothing otherwise — a zero-argument handler stays valid.
+     */
+    handler: (arg?: string) => void | Promise<void>;
+    /** Extra search terms that do not appear in the UI. */
+    keywords?: string[];
+    /** Display group header (e.g. `"Files"`, `"Agent"`). Optional. */
+    group?: string;
+    /**
+     * When present, the palette collects one string before calling
+     * {@link PaletteAction.handler}. See {@link PaletteArgPrompt}.
+     */
+    arg?: PaletteArgPrompt;
+}

package/dist/runtime/types/forge-action.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Types for **forge actions** — one declaration that serves both the Cmd+K
+ * command palette and the agent.
+ *
+ * See `docs/superpowers/specs/2026-08-22-forge-app-channel-design.md` §2.3.
+ * The short version: forge already had two registries for what is really one
+ * concept. `useCommandPalette()` holds things a *user* can trigger;
+ * `useAgentCapabilities()` holds things an *agent* can trigger. A capability is
+ * a palette action with a typed input and a different audience, so a
+ * {@link ForgeAction} is authored once and *written through* to whichever of
+ * those two registries its `audience` names. There is no third registry.
+ */
+import type * as z from "zod";
+import type { ClientCapabilityLogger, DefineClientCapabilityArgs, DefinedClientCapability } from "./client-capability.js";
+import type { PaletteAction, PaletteArgPrompt } from "./command-palette.js";
+/** Who may trigger an action. `'user'` → Cmd+K, `'llm'` → agent capability. */
+export type ForgeActionAudience = "user" | "llm";
+/**
+ * Per-run context handed to a forge action's `run`.
+ *
+ * A superset of `ClientCapabilityContext`: the agent path fills every field,
+ * the palette path fills what it can. `source` is what an action checks when it
+ * genuinely needs to behave differently — most do not.
+ */
+export interface ForgeActionContext {
+    /** Which surface triggered this run. */
+    source: ForgeActionAudience;
+    /** The capability name as invoked (a deprecated alias reports the alias). */
+    name: string;
+    /** Opaque session key. Empty string on the palette path. */
+    sessionKey: string;
+    /** Correlation token of the agent's call. `undefined` on the palette path. */
+    callId?: string;
+    /** Logger to emit through; defaults to `console`. */
+    log: ClientCapabilityLogger;
+}
+/**
+ * How Cmd+K collects the single string an action needs before it can run, plus
+ * how to turn that string into the action's declared input.
+ */
+export interface ForgeActionArg<T extends z.ZodType> extends PaletteArgPrompt {
+    /**
+     * Turn the collected string into the action's input. Its result is parsed
+     * through the action's zod schema exactly like the agent's input is, so a
+     * mistake here fails the same way and in the same place.
+     */
+    toInput: (value: string) => z.input<T>;
+}
+/**
+ * Author-facing arguments to `defineForgeAction`.
+ *
+ * The palette-shaped fields (`id`, `label`, `icon`, `keywords`, `group`) are
+ * exactly `PaletteAction`'s. The agent-shaped fields (`kind`, `promptFragment`,
+ * `requiresApproval`, `callTimeoutMs`, `scope`, `render`) are exactly
+ * `defineClientCapability`'s, which in turn mirror `@skaile/workspaces/app-sdk`
+ * field-for-field (spec §2.1). Nothing is renamed on the way through.
+ */
+export interface DefineForgeActionArgs<T extends z.ZodType> extends Pick<DefineClientCapabilityArgs<z.ZodType>, "kind" | "promptFragment" | "requiresApproval" | "callTimeoutMs" | "scope" | "render"> {
+    /**
+     * Palette id, **without** the `app.` prefix — e.g. `workspace.open_file`.
+     *
+     * The capability name is derived from it as `app.<id>`, because the platform
+     * rejects any registration outside the `app.` namespace (spec §2.2) while the
+     * palette has always used bare ids. One id, two namespaces, no drift. Pass
+     * {@link DefineForgeActionArgs.name} to override the derived name; passing an
+     * id that already starts with `app.` throws.
+     */
+    id: string;
+    /** Display label for the palette row. Also the capability's `displayName`. */
+    label: string;
+    /**
+     * Secondary line in the palette **and** the description the model reads at
+     * tool registration. Required when the audience includes `'llm'` — a tool
+     * with no description is a tool the model cannot use correctly.
+     */
+    description?: string;
+    /**
+     * Short secondary line for the palette row. Defaults to
+     * {@link DefineForgeActionArgs.description}, which is written for the model
+     * and is usually far too long for a list row — an action visible on both
+     * surfaces normally wants both.
+     */
+    hint?: string;
+    /** Iconify icon name for the palette row, e.g. `"lucide:file"`. */
+    icon?: string;
+    /** Extra palette search terms that do not appear in the UI. */
+    keywords?: string[];
+    /** Palette group header (e.g. `"Files"`, `"Agent"`). */
+    group?: string;
+    /**
+     * Who may trigger this. Defaults to **both** (`['user', 'llm']`) — that
+     * default is the point of the whole helper: agent-controllability is what you
+     * get unless you opt out. Narrow to `['user']` for something the model has no
+     * business driving, `['llm']` for something with no sensible UI affordance.
+     */
+    audience?: ForgeActionAudience[];
+    /** Zod schema for the run arguments. Defaults to `z.object({})`. */
+    input?: T;
+    /** Optional zod schema for the return value. Validated advisory-only. */
+    output?: z.ZodType;
+    /**
+     * Override the derived capability name. Only for a name that cannot be
+     * expressed as `app.<palette id>`; prefer letting it derive.
+     */
+    name?: string;
+    /**
+     * Old capability names to keep answering, registered as deprecated aliases
+     * sharing this action's handler instance (spec §2.2). Agent-side only — a
+     * deprecated duplicate has no business appearing in Cmd+K.
+     */
+    deprecatedNames?: string[];
+    /**
+     * How Cmd+K collects the input. Required when the audience includes `'user'`
+     * and the input schema does not accept `{}` — otherwise the palette row would
+     * exist only to fail on Enter, and `defineForgeAction` throws at define time
+     * rather than letting you ship that.
+     */
+    arg?: ForgeActionArg<T>;
+    /** The implementation. One function, both surfaces. */
+    run: (input: z.infer<T>, ctx: ForgeActionContext) => unknown | Promise<unknown>;
+}
+/**
+ * A defined forge action: the two registry-shaped projections of one
+ * declaration, plus the pieces a caller may want directly.
+ *
+ * `paletteAction` is `undefined` when the audience omits `'user'`;
+ * `capability` is `undefined` when it omits `'llm'`. That absence *is* the
+ * enforcement — a user-only action has nothing to announce upward, and an
+ * llm-only action has nothing to put in the palette.
+ */
+export interface ForgeAction {
+    /** The palette id, as authored. */
+    id: string;
+    /** The derived (or overridden) `app.`-namespaced capability name. */
+    name: string;
+    label: string;
+    audience: ForgeActionAudience[];
+    /** The input schema, defaulted to `z.object({})` when none was declared. */
+    readonly inputZod: z.ZodType;
+    /** The Cmd+K projection. Absent unless the audience includes `'user'`. */
+    paletteAction?: PaletteAction;
+    /** The agent projection. Absent unless the audience includes `'llm'`. */
+    capability?: DefinedClientCapability;
+    /** Deprecated-alias capabilities, if any. Empty when none were declared. */
+    aliases: DefinedClientCapability[];
+    /**
+     * Run the action directly, bypassing both surfaces. Input is parsed through
+     * the declared schema first, so this is not a way around validation. Handy
+     * for a button that triggers the same behaviour as its palette entry.
+     */
+    run(input?: unknown, ctx?: Partial<ForgeActionContext>): Promise<unknown>;
+}

package/dist/runtime/types/index.d.ts

@@ -0,0 +1,3 @@
+export type { ClientCapabilityAnnouncement, ClientCapabilityContext, ClientCapabilityDescriptor, ClientCapabilityLogger, ClientCapabilityOrigin, DefineClientCapabilityArgs, DefinedClientCapability, } from "./client-capability.js";
+export type { PaletteAction, PaletteArgOption, PaletteArgPrompt, } from "./command-palette.js";
+export type { DefineForgeActionArgs, ForgeAction, ForgeActionArg, ForgeActionAudience, ForgeActionContext, } from "./forge-action.js";

package/dist/types.d.mts

@@ -0,0 +1,9 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module.mjs'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module.mjs'
+
+export { type ForgeAppActionsOptions } from './module.mjs'

package/package.json

@@ -1,6 +1,96 @@
 {
   "name": "@skaile/forge-app-actions",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Browser-declared app actions for Skaile forge apps: defineForgeAction / defineClientCapability, the agent capability bridge, command palette and approval dialog, as a Nuxt module.",
+  "type": "module",
+  "packageManager": "bun@1.3.9",
+  "main": "./dist/module.mjs",
+  "types": "./dist/types.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./client-capabilities": {
+      "types": "./dist/runtime/client-capabilities.d.ts",
+      "import": "./dist/runtime/client-capabilities.js"
+    },
+    "./chat": {
+      "types": "./dist/runtime/chat/index.d.ts",
+      "import": "./dist/runtime/chat/index.js"
+    },
+    "./chat/server": {
+      "types": "./dist/runtime/chat/server.d.ts",
+      "import": "./dist/runtime/chat/server.js"
+    },
+    "./server": {
+      "types": "./dist/runtime/server/index.d.ts",
+      "import": "./dist/runtime/server/index.js"
+    },
+    "./types": {
+      "types": "./dist/runtime/types/index.d.ts",
+      "import": "./dist/runtime/types/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/runtime",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skaile-ai/forge-app-actions.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepare": "nuxt-module-build prepare",
+    "dev:prepare": "nuxt-module-build build --stub",
+    "build": "nuxt-module-build build",
+    "prepublishOnly": "bun run build",
+    "test": "bun x --bun vitest run",
+    "typecheck": "tsc --noEmit",
+    "check": "bun run format && bun run lint",
+    "format": "biome format --write src tests",
+    "lint": "biome lint --fix --unsafe src tests"
+  },
+  "peerDependencies": {
+    "@nuxt/ui": "^4.11.1",
+    "@skaile/forge-chat": "^0.2.0",
+    "@skaile/workspaces": "^6.0.0",
+    "nuxt": ">=3.0.0",
+    "vue": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@skaile/forge-chat": {
+      "optional": true
+    },
+    "@skaile/workspaces": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.9",
+    "@nuxt/module-builder": "^1.0.0",
+    "@nuxt/schema": "^4.0.0",
+    "@nuxt/ui": "^4.11.1",
+    "@skaile/forge-chat": "^0.2.0",
+    "@skaile/workspaces": "^6.0.0",
+    "@types/bun": "^1.2.0",
+    "@types/node": "^22.0.0",
+    "@vitejs/plugin-vue": "^6.0.5",
+    "bun-types": "^1.3.11",
+    "happy-dom": "^20.9.0",
+    "nuxt": "^4.0.0",
+    "typescript": "^5.0.0",
+    "unbuild": "^3.6.0",
+    "vitest": "^3.2.0",
+    "vue": "^3.5.28",
+    "vue-tsc": "^2.1.0"
+  }
+}