Skip to content

armgit / orca

Public Imported from GitHub
0

Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.

10.1 KB
Raw Blame
import { z } from 'zod'
import type { PluginCapabilityKind } from '../capabilities/plugin-capabilities'
import type { PluginSurface } from '../frames/plugin-protocol'

/**
 * Host API 1 (`pluginApi: 1`) — the separately-versioned public facade plugins call. Every
 * method carries params AND result schemas plus capability/mutation metadata;
 * handlers (bound in main) delegate to runtime services. The raw runtime-RPC
 * registry is never exposed: its methods have no result schemas and evolve at
 * internal velocity.
 *
 * This table is the single source of truth for the capability gate, which surfaces
 * (worker, panel, editor) may call what, the generated reference and the plugin SDK.
 * Every params schema is strict: an older host refuses a newer flag with `invalid_params`
 * instead of running the call without it. Electron-free by design: desktop
 * main, headless serve, the relay conformance path, and tests all import it.
 *
 * Frozen within major 1: additive only. The policy that binds this
 * table is in docs/reference/plugin-host-api.md, generated from it.
 */

export const PANEL_ACTION_TEXT_MAX_LENGTH = 4096
export const PLUGIN_WORKSPACE_TERMINAL_LIMIT = 50
export const PLUGIN_WORKSPACE_LABEL_MAX_LENGTH = 512
export const PLUGIN_TERMINAL_ID_MAX_LENGTH = 1024

const workspaceReadContextParams = z.strictObject({}).optional()
const workspaceReadContextResult = z
  .object({
    branch: z.string().max(PLUGIN_WORKSPACE_LABEL_MAX_LENGTH),
    displayName: z.string().max(PLUGIN_WORKSPACE_LABEL_MAX_LENGTH),
    /** Terminals of the focused workspace, so callers can address a specific
     *  terminal id — the API has no "active terminal" write target. */
    terminals: z
      .array(
        z
          .object({
            id: z.string().min(1).max(PLUGIN_TERMINAL_ID_MAX_LENGTH)
          })
          .strict()
      )
      .max(PLUGIN_WORKSPACE_TERMINAL_LIMIT)
  })
  .strict()
  .nullable()

const terminalSendTextParams = z.strictObject({
  /** Explicit target prevents delayed writes following focus changes into another pane. */
  terminalId: z.string().min(1).max(PLUGIN_TERMINAL_ID_MAX_LENGTH),
  text: z.string().min(1).max(PANEL_ACTION_TEXT_MAX_LENGTH),
  enter: z.boolean().default(false)
})
const terminalSendTextResult = z.object({ accepted: z.boolean() })

const notificationsShowParams = z.strictObject({
  title: z.string().min(1).max(120),
  body: z.string().max(1000).optional()
})
const notificationsShowResult = z.object({ delivered: z.boolean() })

const RESERVED_STORAGE_KEYS = new Set(['__proto__', 'prototype', 'constructor'])
const storageKeySchema = z
  .string()
  .min(1)
  .max(256)
  .refine((key) => !RESERVED_STORAGE_KEYS.has(key), 'reserved storage key')
const pluginJsonValueSchema = z.json()
export type PluginJsonValue = z.infer<typeof pluginJsonValueSchema>
/** Caps keep per-plugin storage an honest key-value store, not a database. */
export const PLUGIN_STORAGE_VALUE_MAX_BYTES = 256 * 1024
export const PLUGIN_STORAGE_TOTAL_MAX_BYTES = 5 * 1024 * 1024
export const PLUGIN_STORAGE_KEY_LIMIT = 1024

const storageGetParams = z.strictObject({ key: storageKeySchema })
const storageGetResult = z.object({ value: pluginJsonValueSchema })
const storageSetParams = z.strictObject({ key: storageKeySchema, value: pluginJsonValueSchema })
const storageSetResult = z.object({ ok: z.literal(true) })
const storageDeleteParams = z.strictObject({ key: storageKeySchema })
const storageDeleteResult = z.object({ ok: z.literal(true) })
const storageKeysParams = z.strictObject({}).optional()
const storageKeysResult = z.object({ keys: z.array(z.string()).max(PLUGIN_STORAGE_KEY_LIMIT) })

const secretsGetParams = z.strictObject({ key: storageKeySchema })
const secretsGetResult = z.object({ value: z.string().nullable() })
const secretsSetParams = z.strictObject({ key: storageKeySchema, value: z.string().max(64 * 1024) })
const secretsSetResult = z.object({ ok: z.literal(true) })
const secretsDeleteParams = z.strictObject({ key: storageKeySchema })
const secretsDeleteResult = z.object({ ok: z.literal(true) })

const settingsGetParams = z.strictObject({}).optional()
const settingsGetResult = z.object({ settings: z.record(z.string(), pluginJsonValueSchema) })
const settingsSetParams = z.strictObject({ key: storageKeySchema, value: pluginJsonValueSchema })
const settingsSetResult = z.object({ ok: z.literal(true) })

export type PluginHostMethodSpec<
  P extends z.ZodType = z.ZodType,
  R extends z.ZodType = z.ZodType
> = {
  /** One line for the generated reference. */
  summary: string
  /** Host API minor the method appeared in (`0` for the first set); `api.minor` is the highest. */
  since: number
  /** Minor that deprecated it; it keeps working until the next major. */
  deprecatedSince?: number
  /** Machine-readable resource boundary enforced by the host binding. */
  scope: 'active-workspace' | 'explicit-terminal' | 'plugin-private' | 'desktop'
  capability: PluginCapabilityKind
  /** Mutations are audit-logged with actor `plugin:<id>`. */
  mutation: boolean
  /** Where plugin code may call it; any other surface gets `not_permitted`. */
  surfaces: readonly PluginSurface[]
  params: P
  result: R
}

const ALL_SURFACES = ['worker', 'panel', 'editor'] as const
const WORKER_ONLY = ['worker'] as const

const spec = <P extends z.ZodType, R extends z.ZodType>(
  entry: PluginHostMethodSpec<P, R>
): PluginHostMethodSpec<P, R> => entry

export const PLUGIN_HOST_API = {
  'workspace.readContext': spec({
    summary:
      'Branch, name and terminal ids of the focused workspace, or null when none is focused.',
    since: 0,
    scope: 'active-workspace',
    capability: 'workspace:read',
    mutation: false,
    surfaces: ALL_SURFACES,
    params: workspaceReadContextParams,
    result: workspaceReadContextResult
  }),
  'terminal.sendText': spec({
    summary: 'Types text into one terminal named by id, optionally pressing Enter.',
    since: 0,
    scope: 'explicit-terminal',
    capability: 'terminal:send',
    mutation: true,
    // Why: text plus Enter runs shell commands (local or SSH), so only full-access workers get it.
    surfaces: WORKER_ONLY,
    params: terminalSendTextParams,
    result: terminalSendTextResult
  }),
  'notifications.show': spec({
    summary: 'Shows a desktop notification.',
    since: 0,
    scope: 'desktop',
    capability: 'notifications:show',
    mutation: true,
    surfaces: ALL_SURFACES,
    params: notificationsShowParams,
    result: notificationsShowResult
  }),
  'storage.get': spec({
    summary: "Reads a JSON value from the plugin's private store; null when absent.",
    since: 0,
    scope: 'plugin-private',
    capability: 'storage:own',
    mutation: false,
    surfaces: WORKER_ONLY,
    params: storageGetParams,
    result: storageGetResult
  }),
  'storage.set': spec({
    summary: "Writes a JSON value to the plugin's private store.",
    since: 0,
    scope: 'plugin-private',
    capability: 'storage:own',
    mutation: true,
    surfaces: WORKER_ONLY,
    params: storageSetParams,
    result: storageSetResult
  }),
  'storage.delete': spec({
    summary: "Removes a key from the plugin's private store.",
    since: 0,
    scope: 'plugin-private',
    capability: 'storage:own',
    mutation: true,
    surfaces: WORKER_ONLY,
    params: storageDeleteParams,
    result: storageDeleteResult
  }),
  'storage.keys': spec({
    summary: "Lists the keys in the plugin's private store.",
    since: 0,
    scope: 'plugin-private',
    capability: 'storage:own',
    mutation: false,
    surfaces: WORKER_ONLY,
    params: storageKeysParams,
    result: storageKeysResult
  }),
  'secrets.get': spec({
    summary: "Reads a secret from the plugin's encrypted secrets file; null when absent.",
    since: 0,
    scope: 'plugin-private',
    capability: 'secrets:own',
    mutation: false,
    surfaces: WORKER_ONLY,
    params: secretsGetParams,
    result: secretsGetResult
  }),
  'secrets.set': spec({
    summary: "Stores a secret in the plugin's encrypted secrets file.",
    since: 0,
    scope: 'plugin-private',
    capability: 'secrets:own',
    mutation: true,
    surfaces: WORKER_ONLY,
    params: secretsSetParams,
    result: secretsSetResult
  }),
  'secrets.delete': spec({
    summary: "Removes a secret from the plugin's encrypted secrets file.",
    since: 0,
    scope: 'plugin-private',
    capability: 'secrets:own',
    mutation: true,
    surfaces: WORKER_ONLY,
    params: secretsDeleteParams,
    result: secretsDeleteResult
  }),
  'settings.get': spec({
    summary: 'Reads every setting the plugin owns.',
    since: 0,
    scope: 'plugin-private',
    capability: 'settings:own',
    mutation: false,
    surfaces: WORKER_ONLY,
    params: settingsGetParams,
    result: settingsGetResult
  }),
  'settings.set': spec({
    summary: 'Writes one setting the plugin owns.',
    since: 0,
    scope: 'plugin-private',
    capability: 'settings:own',
    mutation: true,
    surfaces: WORKER_ONLY,
    params: settingsSetParams,
    result: settingsSetResult
  })
}

export type PluginHostApi = typeof PLUGIN_HOST_API
export type PluginHostMethodName = keyof PluginHostApi
/** What a plugin passes; what a handler receives is `z.output` of the same schema. */
export type PluginHostParams<M extends PluginHostMethodName> = z.input<PluginHostApi[M]['params']>
export type PluginHostResult<M extends PluginHostMethodName> = z.output<PluginHostApi[M]['result']>

export const PLUGIN_HOST_METHOD_NAMES = Object.keys(PLUGIN_HOST_API).filter(isPluginHostMethodName)

export function isPluginHostMethodName(name: string): name is PluginHostMethodName {
  return Object.hasOwn(PLUGIN_HOST_API, name)
}

export function getPluginHostMethodSpec(name: string): PluginHostMethodSpec | null {
  return isPluginHostMethodName(name) ? PLUGIN_HOST_API[name] : null
}

/** The minor this host implements: the newest `since` in the table. */
export const PLUGIN_HOST_API_MINOR = Math.max(
  ...PLUGIN_HOST_METHOD_NAMES.map((name) => PLUGIN_HOST_API[name].since)
)

/** Methods a surface may call, for `hello` and `host.has`. */
export function pluginHostMethodsFor(surface: PluginSurface): PluginHostMethodName[] {
  return PLUGIN_HOST_METHOD_NAMES.filter((name) => PLUGIN_HOST_API[name].surfaces.includes(surface))
}