Action Manifest

An action is something the AI can do, like Improve or Shorten. The action manifest is a list of every action and its rules: whether it needs selected text, what it can read, and what it can change. emend checks every request against this list.

import { DEFAULT_ACTION_MANIFEST, getAction, validateAction } from "@emend/ai"

Built-in actions

Every built-in action can read the selection, the current paragraph, or the whole document. custom needs an instruction, such as "make this friendlier". If you use custom to edit, you must also say what it may change.

Shape of an action

interface EmendActionManifestEntry {
  readonly actionId: EmendActionId
  readonly label: string
  readonly description: string
  readonly allowedInteractionModes: readonly EmendInteractionMode[]
  readonly allowedTargetScopes: readonly EmendTargetScope[]
  readonly allowedContextScopes: readonly EmendContextScope[]
  readonly allowedMutationOperations: readonly EmendMutationOperation[]
  readonly selectionRequirement: "any" | "non-empty" | "collapsed"
  readonly instructionRequirement: "optional" | "required"
  readonly informational: boolean
}

Allow only some actions on your server

Pass a shorter list to createEmendAiHandler. Requests for any other action are rejected.

import { DEFAULT_ACTION_MANIFEST } from "@emend/ai"
import { createEmendAiHandler } from "@emend/ai/server"

const allowed = new Set(["improve", "fix-grammar", "summarize"])
const manifest = DEFAULT_ACTION_MANIFEST.filter((action) =>
  allowed.has(action.actionId)
)

export const POST = createEmendAiHandler({
  manifest,
  generate,
})

getAction(actionId, manifest?)

Finds an action by ID, or returns undefined. Searches the built-in list unless you pass your own.

const action = getAction("improve")

validateAction(input, manifest?)

Checks whether a request follows an action's rules. Returns { ok: true, action } if it does, or { ok: false, reason } if not.

The possible reasons are:

• unknown-action
• interaction-mode-not-allowed
• target-scope-not-allowed
• context-scope-not-allowed
• mutation-operation-not-allowed
• selection-requirement-not-met
• instruction-required

The server handler runs this check on every request for you.