API reference

Entries

The package also ships the moku bin. See cli.

Signatures below are simplified for reading. The installed dist/index.d.mts is the source.

createApp

function createApp<const ExtraPlugins extends readonly AnyPluginInstance[] = readonly []>(options?: {
  plugins?: ExtraPlugins;
  config?: {};
  pluginConfigs?: { [pluginName: string]: Partial<PluginConfig> };
  onReady?: (ctx: AppCallbackContext) => void;
  onError?: (error: Error, ctx: AppCallbackContext) => void;
  onStart?: (ctx: AppCallbackContext) => void | Promise<void>;
  onStop?: (ctx: AppCallbackContext) => void | Promise<void>;
}): App;

Creates the app with every plugin. It is synchronous. Providers register their handlers here, so app.registry is full when it returns. The global config is empty: all settings are per plugin.

journal, store and limits read pluginConfigs like any other plugin.

createPlugin

function createPlugin<const Name extends string>(name: Name, spec: {
  depends?: readonly AnyPluginInstance[];
  config?: Config;
  createState?: (ctx) => State;
  api?: (ctx) => Api;
  events?: (register) => Events;
  hooks?: (ctx) => EventHandlers;
  onInit?: (ctx) => void;
  onStart?: (ctx) => void | Promise<void>;
  onStop?: (ctx) => void | Promise<void>;
}): PluginInstance;

The factory for your own plugins, bound to this framework. Its ctx has journal, store, limits, log and env. Add a handler with Add a provider or a task.

defineBuild

function defineBuild(spec: BuildSpec): BuildSpec;

Validates a TypeScript build file through the YAML loader's schema. Throws [ai] Build file "<inline>" is invalid. See buildfile.

defineConfig

function defineConfig<const P extends readonly AnyPluginInstance[] = readonly []>(config: ProjectConfig<P>): ProjectConfig<P>;

Types moku.config.ts and returns its argument. ProjectConfig is the plugins and pluginConfigs of createApp. See cli.

Plugin instances

Pass these to ctx.require(...) and to depends.

Tool loop

function runToolLoop(options: RunToolLoopOptions): Promise<RunToolLoopResult>;
function isPromptGenUnavailable(error: unknown): boolean;
class PromptGenUnavailableError extends Error {
  readonly unavailable: true;
  readonly reason: "missing" | "auth" | "limit" | "unsupported";
}
class ToolArgumentsError extends Error {
  readonly toolName: string;
  readonly raw: string;
}

runToolLoop runs a tool loop that the caller journals. PromptGenUnavailableError makes promptGen try the next provider in its fallback. See Tool loop.

Assets

const ASSET_MIME = "application/vnd.moku.asset+json";
function encodeAssetRecord(record: AssetRecord): Uint8Array;
function parseAssetRecord(bytes: Uint8Array): AssetRecord;

An asset artifact is a JSON record, not a picture. AssetRecord is { assetId, provider, account, groupId, registeredAt }. See asset.

Type namespaces

Each plugin's types are one namespace: Runner.RunResult, Voiceover.VoiceoverHandler, Cli.EXIT_CODES. Most hold Config and the plugin's API type.

Error namespaces

Each provider's error classes are one namespace. Most have RetryableProviderError, TerminalProviderError and FlaggedProviderError. CodexErrors and ClaudeErrors have no flagged class.

Environment

Keys are read when a request runs, from the shell or from .env.local in the working directory. The shell wins. Estimates and validation need none. codex and claude find their CLI on PATH.