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

package/src/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/src/runtime/types/client-capability.ts

@@ -0,0 +1,178 @@
+/**
+ * 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/src/runtime/types/command-palette.ts

@@ -0,0 +1,78 @@
+/**
+ * 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/src/runtime/types/forge-action.ts

@@ -0,0 +1,166 @@
+/**
+ * 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";
+import type { PaletteAction, PaletteArgPrompt } from "./command-palette";
+
+/** 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/src/runtime/types/index.ts

@@ -0,0 +1,24 @@
+// ── Browser-side agent capabilities ─────────────────────────────────────────
+export type {
+  ClientCapabilityAnnouncement,
+  ClientCapabilityContext,
+  ClientCapabilityDescriptor,
+  ClientCapabilityLogger,
+  ClientCapabilityOrigin,
+  DefineClientCapabilityArgs,
+  DefinedClientCapability,
+} from "./client-capability";
+// ── Command palette ─────────────────────────────────────────────────────────
+export type {
+  PaletteAction,
+  PaletteArgOption,
+  PaletteArgPrompt,
+} from "./command-palette";
+// ── Unified action API ──────────────────────────────────────────────────────
+export type {
+  DefineForgeActionArgs,
+  ForgeAction,
+  ForgeActionArg,
+  ForgeActionAudience,
+  ForgeActionContext,
+} from "./forge-action";