@moxxy/sdk 0.1.0

package/src/plugin.ts

@@ -0,0 +1,92 @@
+import type { AgentDef } from './agent.js';
+import type { CacheStrategyDef } from './cache-strategy.js';
+import type { ChannelDef } from './channel.js';
+import type { CommandDef } from './command.js';
+import type { CompactorDef } from './compactor.js';
+import type { LifecycleHooks } from './hooks.js';
+import type { ModeDef } from './mode.js';
+import type { ProviderDef } from './provider.js';
+import type { MoxxyRequirement } from './requirements.js';
+import type { ToolDef } from './tool.js';
+import type { TranscriberDef } from './transcriber.js';
+import type { ViewRendererDef } from './view-renderer.js';
+import type { TunnelProviderDef } from './tunnel.js';
+
+export type PluginKind = 'tools' | 'provider' | 'mode' | 'compactor' | 'cache-strategy' | 'view-renderer' | 'tunnel-provider' | 'mcp' | 'cli' | 'channel' | 'hooks' | 'agent' | 'command' | 'transcriber';
+
+export interface PluginSpec {
+  readonly name: string;
+  readonly version?: string;
+  readonly tools?: ReadonlyArray<ToolDef>;
+  readonly providers?: ReadonlyArray<ProviderDef>;
+  readonly modes?: ReadonlyArray<ModeDef>;
+  readonly compactors?: ReadonlyArray<CompactorDef>;
+  /**
+   * Prompt-caching strategies contributed by the plugin. One is active per
+   * session (selected via `session.cacheStrategies.setActive(name)`); the
+   * active strategy decides where cache breakpoints go for each provider call.
+   */
+  readonly cacheStrategies?: ReadonlyArray<CacheStrategyDef>;
+  /**
+   * View-spec renderers contributed by the plugin. One is active per session
+   * (selected via `session.viewRenderers.setActive(name)`); the active renderer
+   * parses the agent's view-spec into a validated AST for `present_view`. A
+   * default renderer ships with core, so this is only for replacing it.
+   */
+  readonly viewRenderers?: ReadonlyArray<ViewRendererDef>;
+  /**
+   * Tunnel providers that expose the local web surface publicly (e.g.
+   * cloudflared). One active per session; core seeds a `localhost` no-op.
+   */
+  readonly tunnelProviders?: ReadonlyArray<TunnelProviderDef>;
+  readonly channels?: ReadonlyArray<ChannelDef>;
+  /**
+   * Speech-to-text backends contributed by the plugin. Selected by name via
+   * `session.transcribers.setActive(name)`; channels with audio input use
+   * `session.transcribers.getActive()` to convert bytes → transcript when
+   * the active provider does not advertise `supportsAudio`.
+   */
+  readonly transcribers?: ReadonlyArray<TranscriberDef>;
+  /**
+   * Typed subagent kinds the plugin contributes. Each becomes
+   * dispatchable as `dispatch_agent({ agentType: <name>, ... })`.
+   * When NO plugin registers any agents (and no plugin registers the
+   * dispatch tool itself), the model has no subagent capability and
+   * the system degrades to the normal single-loop flow.
+   */
+  readonly agents?: ReadonlyArray<AgentDef>;
+  /**
+   * Slash commands contributed to every channel — the TUI's slash
+   * menu, the Telegram bot's command list, and any future channel
+   * that consumes `session.commands`. Use this for actions that make
+   * sense regardless of UI (`/info`, `/clear`, custom domain commands
+   * like `/deploy`); leave channel-specific UI commands (overlay
+   * pickers, raw-mode toggles) inside the channel itself.
+   */
+  readonly commands?: ReadonlyArray<CommandDef>;
+  readonly hooks?: LifecycleHooks;
+  readonly skillsDir?: string;
+}
+
+export interface Plugin extends PluginSpec {
+  readonly __moxxy: 'plugin';
+  readonly version: string;
+}
+
+export interface PluginManifest {
+  readonly entry: string;
+  readonly kind?: PluginKind | ReadonlyArray<PluginKind>;
+  readonly skills?: string;
+}
+
+export interface ResolvedPluginManifest extends PluginManifest {
+  readonly packageName: string;
+  readonly packageVersion: string;
+  readonly packagePath: string;
+  /**
+   * Requirements declared at `package.json#moxxy.requirements`. Statically
+   * authored — never derived from code. Drives plugin toposort and the
+   * pre-load readiness gate.
+   */
+  readonly requirements?: ReadonlyArray<MoxxyRequirement>;
+}

package/src/provider-utils.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { zodToJsonSchema } from './provider-utils.js';
+
+/**
+ * Regression coverage for the codex `/responses` 400 we hit when a tool's
+ * input schema was `z.object(...).and(z.object(...).refine(...))`. The old
+ * converter fell through to a bare `{ type: 'object' }` (no `properties`
+ * key), and Codex rejects that. These tests pin every wrapper kind so the
+ * fix doesn't silently regress.
+ */
+describe('zodToJsonSchema', () => {
+  it('unwraps ZodEffects (.refine) to the underlying object', () => {
+    const schema = z
+      .object({ a: z.string(), b: z.number() })
+      .refine((v) => v.a.length > 0);
+    const out = zodToJsonSchema(schema) as Record<string, unknown>;
+    expect(out.type).toBe('object');
+    expect(out.properties).toEqual({
+      a: { type: 'string' },
+      b: { type: 'number' },
+    });
+    expect(out.required).toEqual(expect.arrayContaining(['a', 'b']));
+  });
+
+  it('merges ZodIntersection of two ZodObjects into one object schema', () => {
+    const left = z.object({ name: z.string() });
+    const right = z.object({ count: z.number() });
+    const out = zodToJsonSchema(left.and(right)) as Record<string, unknown>;
+    expect(out.type).toBe('object');
+    expect(out.properties).toEqual({
+      name: { type: 'string' },
+      count: { type: 'number' },
+    });
+    expect(out.required).toEqual(expect.arrayContaining(['name', 'count']));
+  });
+
+  it('matches the scheduler tool shape (object .and(object.refine))', () => {
+    // The actual shape that triggered the codex 400.
+    const cronOrTimestamp = z
+      .object({ cron: z.string().optional(), runAt: z.number().optional() })
+      .refine((v) => !!v.cron || v.runAt !== undefined);
+    const schema = z
+      .object({ name: z.string(), prompt: z.string() })
+      .and(cronOrTimestamp);
+    const out = zodToJsonSchema(schema) as Record<string, unknown>;
+    expect(out.type).toBe('object');
+    expect(out.properties).toBeDefined();
+    expect(out.properties).toMatchObject({
+      name: { type: 'string' },
+      prompt: { type: 'string' },
+      cron: { type: 'string' },
+      runAt: { type: 'number' },
+    });
+  });
+
+  it('unwraps ZodOptional / ZodDefault / ZodNullable', () => {
+    expect(zodToJsonSchema(z.string().optional())).toEqual({ type: 'string' });
+    expect(zodToJsonSchema(z.number().default(0))).toEqual({ type: 'number' });
+    expect(zodToJsonSchema(z.string().nullable())).toEqual({ type: 'string' });
+  });
+
+  it('converts ZodEnum to string + enum list', () => {
+    const out = zodToJsonSchema(z.enum(['a', 'b', 'c'])) as Record<string, unknown>;
+    expect(out).toEqual({ type: 'string', enum: ['a', 'b', 'c'] });
+  });
+
+  it('converts ZodUnion via anyOf', () => {
+    const out = zodToJsonSchema(z.union([z.string(), z.number()])) as Record<string, unknown>;
+    expect(out.anyOf).toEqual([{ type: 'string' }, { type: 'number' }]);
+  });
+
+  it('unknown schemas fall back to an object with explicit properties', () => {
+    // Synthetic "unknown" wrapper — uses a typeName the converter doesn't know.
+    const out = zodToJsonSchema({ _def: { typeName: 'ZodNeverHeardOfIt' } }) as Record<
+      string,
+      unknown
+    >;
+    // The key fix: properties is always present, even on the catch-all path,
+    // so strict validators (codex /responses) don't reject the tool.
+    expect(out).toHaveProperty('type', 'object');
+    expect(out).toHaveProperty('properties');
+  });
+});

package/src/provider-utils.ts

@@ -0,0 +1,171 @@
+/**
+ * Small helpers that provider plugins share. Lives in the SDK because plugins
+ * are only allowed to depend on @moxxy/sdk, not core.
+ */
+
+import { classifyNetworkError } from './errors.js';
+
+/** Canonical stop reasons emitted on `message_end` events. */
+export type StopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'error';
+
+/**
+ * Heuristic: should a provider request retry on this error? Used by stream
+ * modes to attach a `retryable: boolean` flag to the `error` event so callers
+ * (or the loop strategy) can decide whether to back off and try again.
+ *
+ * Identical implementation across plugin-provider-anthropic and -openai;
+ * hoisted here so a new provider plugin can stay consistent.
+ */
+export function isRetryableError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  // MoxxyError-classified ones carry the verdict in the code.
+  const code = (err as { code?: unknown }).code;
+  if (typeof code === 'string') {
+    if (code === 'PROVIDER_RATE_LIMITED' || code === 'PROVIDER_SERVER_ERROR') return true;
+    if (code === 'NETWORK_TIMEOUT' || code === 'NETWORK_UNREACHABLE') return true;
+  }
+  const msg = err.message.toLowerCase();
+  if (msg.includes('rate_limit') || msg.includes('429') || msg.includes('overloaded')) return true;
+  if (msg.includes('econnreset') || msg.includes('etimedout') || msg.includes('network')) return true;
+  return false;
+}
+
+/**
+ * Build a friendly error event for `ProviderEvent` streams. Tries to classify
+ * the cause as a network failure (turning Node's "fetch failed" into something
+ * actionable) before falling back to the raw message. Providers' catch blocks
+ * yield the result via:
+ *   yield { type: 'error', ...toFriendlyError(err, { provider: this.name }) };
+ */
+export function toFriendlyError(
+  err: unknown,
+  ctx: { readonly url?: string; readonly provider?: string } = {},
+): { message: string; retryable: boolean } {
+  const classified = classifyNetworkError(err, ctx);
+  if (classified) {
+    return {
+      message: classified.message + (classified.hint ? ` — ${classified.hint}` : ''),
+      retryable: isRetryableError(classified),
+    };
+  }
+  return {
+    message: err instanceof Error ? err.message : String(err),
+    retryable: isRetryableError(err),
+  };
+}
+
+/**
+ * Best-effort zod → JSON-schema conversion for provider tool definitions.
+ * Most callers want the basic object/string/number/boolean/array coverage;
+ * for richer schemas, plugins can layer `zod-to-json-schema`.
+ *
+ * The `as unknown as { ... }` casts below probe zod's `_def` internals
+ * (`shape`, `type`) which aren't part of zod's public typed surface but are
+ * stable enough across versions to rely on for this best-effort path.
+ */
+export function zodToJsonSchema(schema: unknown): unknown {
+  const s = schema as { _def?: { typeName?: string }; toJSON?: () => unknown };
+  // Only honor a pre-serialized schema's `toJSON` for NON-zod objects (a plain
+  // JSON-schema object passed through). A real zod schema (has `_def`) MUST go
+  // through the unwrap below — short-circuiting on a zod `toJSON` (some versions
+  // add one) skips the ZodEffects/intersection handling and yields a
+  // properties-less object schema that providers like Codex reject.
+  if (!s._def && typeof s.toJSON === 'function') return s.toJSON();
+  const def = s._def;
+  const typeName = def?.typeName;
+
+  // ZodEffects (`.refine`, `.transform`, `.superRefine`) is a wrapper —
+  // the inner `schema` field holds the real type. Skipping the unwrap
+  // leaves us with a properties-less object schema, which providers like
+  // Codex's /responses validator reject ("object schema missing properties").
+  if (typeName === 'ZodEffects') {
+    const inner = (def as unknown as { schema: unknown }).schema;
+    return zodToJsonSchema(inner);
+  }
+  // ZodOptional / ZodNullable / ZodDefault / ZodBranded / ZodReadonly all
+  // wrap an inner schema we want to unwrap for JSON-schema purposes.
+  if (
+    typeName === 'ZodOptional' ||
+    typeName === 'ZodNullable' ||
+    typeName === 'ZodDefault' ||
+    typeName === 'ZodBranded' ||
+    typeName === 'ZodReadonly'
+  ) {
+    const inner = (def as unknown as { innerType: unknown }).innerType;
+    return zodToJsonSchema(inner);
+  }
+  // `.and(other)` produces a ZodIntersection. The standard JSON-schema
+  // representation is `allOf`, but strict validators (Codex again) want
+  // each branch to be a complete object schema. Easiest path that satisfies
+  // them: when both branches reduce to object schemas, merge properties
+  // and required lists into one object. Fall back to `allOf` otherwise.
+  if (typeName === 'ZodIntersection') {
+    const intersection = def as unknown as { left: unknown; right: unknown };
+    const left = zodToJsonSchema(intersection.left) as Record<string, unknown>;
+    const right = zodToJsonSchema(intersection.right) as Record<string, unknown>;
+    if (
+      left &&
+      right &&
+      left.type === 'object' &&
+      right.type === 'object' &&
+      left.properties &&
+      right.properties
+    ) {
+      return {
+        type: 'object',
+        properties: { ...(left.properties as object), ...(right.properties as object) },
+        required: Array.from(
+          new Set([
+            ...((left.required as ReadonlyArray<string>) ?? []),
+            ...((right.required as ReadonlyArray<string>) ?? []),
+          ]),
+        ),
+      };
+    }
+    return { allOf: [left, right] };
+  }
+  if (typeName === 'ZodObject') {
+    // zod's ZodObject._def has a `shape()` thunk returning the field map.
+    const shape = (def as unknown as { shape: () => Record<string, unknown> }).shape();
+    const properties: Record<string, unknown> = {};
+    const required: string[] = [];
+    for (const [key, value] of Object.entries(shape)) {
+      properties[key] = zodToJsonSchema(value);
+      const isOptional = (value as { isOptional?: () => boolean }).isOptional?.();
+      if (!isOptional) required.push(key);
+    }
+    return { type: 'object', properties, required };
+  }
+  if (typeName === 'ZodString') return { type: 'string' };
+  if (typeName === 'ZodNumber') return { type: 'number' };
+  if (typeName === 'ZodBoolean') return { type: 'boolean' };
+  if (typeName === 'ZodEnum') {
+    const values = (def as unknown as { values: ReadonlyArray<string> }).values;
+    return { type: 'string', enum: [...values] };
+  }
+  if (typeName === 'ZodNativeEnum') {
+    const values = Object.values(
+      (def as unknown as { values: Record<string, string | number> }).values,
+    );
+    const allString = values.every((v) => typeof v === 'string');
+    return { type: allString ? 'string' : 'number', enum: values };
+  }
+  if (typeName === 'ZodLiteral') {
+    const value = (def as unknown as { value: string | number | boolean | null }).value;
+    const t = value === null ? 'null' : typeof value;
+    return { type: t, enum: [value] };
+  }
+  if (typeName === 'ZodUnion' || typeName === 'ZodDiscriminatedUnion') {
+    const options = (def as unknown as { options: ReadonlyArray<unknown> }).options;
+    return { anyOf: options.map((o) => zodToJsonSchema(o)) };
+  }
+  if (typeName === 'ZodArray') {
+    // ZodArray._def.type is the element schema.
+    const items = zodToJsonSchema((def as unknown as { type: unknown }).type);
+    return { type: 'array', items };
+  }
+  // Truly unknown — fall back to a permissive "any object" but spell out
+  // `properties: {}` and `additionalProperties: true` so strict validators
+  // accept the schema instead of bailing on a missing `properties` field.
+  return { type: 'object', properties: {}, additionalProperties: true };
+}

package/src/provider.ts

@@ -0,0 +1,195 @@
+import type { ToolDef } from './tool.js';
+
+export interface ProviderMessage {
+  readonly role: 'system' | 'user' | 'assistant' | 'tool_result';
+  readonly content: ReadonlyArray<ContentBlock>;
+}
+
+export type ContentBlock =
+  | { readonly type: 'text'; readonly text: string }
+  | { readonly type: 'tool_use'; readonly id: string; readonly name: string; readonly input: unknown }
+  | { readonly type: 'tool_result'; readonly toolUseId: string; readonly content: string; readonly isError?: boolean }
+  | { readonly type: 'image'; readonly mediaType: string; readonly data: string }
+  | { readonly type: 'audio'; readonly mediaType: string; readonly data: string };
+
+/**
+ * Provider-neutral instruction for where a prompt-cache breakpoint should be
+ * placed. A {@link CacheStrategyDef} emits these; providers that support
+ * caching (e.g. Anthropic via `cache_control`) translate them into their
+ * native marker, and providers that don't simply ignore them.
+ *
+ * `tools` / `system` mark the end of those (session-stable) regions;
+ * `{ messageIndex }` marks the end of the message at that index in the
+ * request's `messages` array (used for the rolling prefix breakpoint).
+ * Anthropic honors at most 4 breakpoints per request.
+ */
+export interface CacheHint {
+  readonly target: 'tools' | 'system' | { readonly messageIndex: number };
+}
+
+export interface ProviderRequest {
+  readonly model: string;
+  readonly system?: string;
+  readonly messages: ReadonlyArray<ProviderMessage>;
+  readonly tools?: ReadonlyArray<ToolDef>;
+  readonly maxTokens?: number;
+  readonly temperature?: number;
+  readonly signal?: AbortSignal;
+  /** Where to place prompt-cache breakpoints. Set by the active CacheStrategy. */
+  readonly cacheHints?: ReadonlyArray<CacheHint>;
+}
+
+export type ProviderEvent =
+  | { readonly type: 'message_start'; readonly model: string }
+  | { readonly type: 'text_delta'; readonly delta: string }
+  | { readonly type: 'tool_use_start'; readonly id: string; readonly name: string }
+  | { readonly type: 'tool_use_delta'; readonly id: string; readonly partialInput: string }
+  | { readonly type: 'tool_use_end'; readonly id: string; readonly input: unknown }
+  | { readonly type: 'message_end'; readonly stopReason: 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'error'; readonly usage?: TokenUsage }
+  | { readonly type: 'error'; readonly message: string; readonly retryable: boolean };
+
+export interface TokenUsage {
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly cacheReadTokens?: number;
+  readonly cacheCreationTokens?: number;
+}
+
+export interface ModelDescriptor {
+  readonly id: string;
+  readonly contextWindow: number;
+  readonly maxOutputTokens?: number;
+  readonly supportsTools: boolean;
+  readonly supportsStreaming: boolean;
+  /**
+   * Whether this model accepts `image` ContentBlocks in user messages.
+   * Channels gate image attachments on this flag — if a user drops an
+   * image while a non-vision model is active, the channel either
+   * refuses or warns instead of silently dropping the bytes.
+   */
+  readonly supportsImages?: boolean;
+  /**
+   * Whether this model accepts `audio` ContentBlocks in user messages
+   * (GPT-4o, Gemini-Live-class models). When false, channels with audio
+   * input route through the session's active `Transcriber` and forward
+   * the transcript as text instead.
+   */
+  readonly supportsAudio?: boolean;
+}
+
+export interface LLMProvider {
+  readonly name: string;
+  readonly models: ReadonlyArray<ModelDescriptor>;
+  stream(req: ProviderRequest): AsyncIterable<ProviderEvent>;
+  countTokens(req: Pick<ProviderRequest, 'model' | 'messages' | 'system' | 'tools'>): Promise<number>;
+}
+
+export type ProviderKeyValidation =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly message: string };
+
+/**
+ * Minimal vault interface exposed to provider auth flows. Implementations
+ * (typically `@moxxy/plugin-vault`) supply encrypted storage; the auth
+ * descriptor doesn't need anything richer, so we keep the contract small
+ * and SDK-Node-free.
+ */
+export interface ProviderVault {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, tags?: ReadonlyArray<string>): Promise<void>;
+  delete?(key: string): Promise<boolean>;
+}
+
+/**
+ * Runtime supplied to a provider's OAuth `login(ctx)` callback. The host
+ * (e.g. `moxxy init`, `moxxy login <provider>`) constructs this and hands
+ * it off; the provider plugin runs the flow end-to-end and persists
+ * credentials via `ctx.vault`.
+ */
+export interface ProviderAuthContext {
+  readonly vault: ProviderVault;
+  /**
+   * True when there is no usable browser or interactive TTY. OAuth flows
+   * should fall back to device-code (or equivalent) in this mode rather
+   * than spawning a local callback server / opening a browser.
+   */
+  readonly headless: boolean;
+  /**
+   * Progress-message sink. The host wires this to its preferred renderer
+   * (clack `log.*`, plain stdout, …) so providers don't have to know
+   * whether they're running inside a wizard or a one-shot command.
+   */
+  readonly write: (chunk: string) => void;
+}
+
+export interface ProviderOAuthResult {
+  /** Human-readable account identifier shown in the success message. */
+  readonly accountId?: string | null;
+  /** UNIX-ms expiry of the persisted credential; surfaced to users. */
+  readonly expiresAt?: number;
+}
+
+/**
+ * Self-describing auth metadata a provider plugin attaches to its
+ * `ProviderDef`. Lets the CLI's setup wizard and `moxxy login` operate
+ * generically over any installed provider — no CLI-side branch table.
+ *
+ * `apiKey`  : the host prompts for a key and calls `validateKey` (if any).
+ * `oauth`   : the host hands the provider a `ProviderAuthContext`; the
+ *             provider drives the full OAuth dance, including any local
+ *             callback server, and persists tokens to `ctx.vault`.
+ */
+export type ProviderAuthDescriptor =
+  | {
+      readonly kind: 'apiKey';
+      /** Canonical env-var name (e.g. `ANTHROPIC_API_KEY`). Inferred when omitted. */
+      readonly envVar?: string;
+      /** Short hint shown next to the prompt (e.g. "starts with `sk-ant-`"). */
+      readonly hint?: string;
+    }
+  | {
+      readonly kind: 'oauth';
+      /** Human-readable name of the upstream service (e.g. "ChatGPT Pro/Plus"). */
+      readonly serviceName?: string;
+      /**
+       * Drive the OAuth flow and persist credentials. Throws on failure /
+       * user cancellation; the host typically offers a retry prompt.
+       */
+      login(ctx: ProviderAuthContext): Promise<ProviderOAuthResult>;
+      /**
+       * Optional logout — remove persisted credentials from the vault.
+       * Returns true if anything was removed, false if there was nothing
+       * stored. Used by `moxxy login logout <provider>`.
+       */
+      logout?(ctx: ProviderAuthContext): Promise<boolean>;
+      /**
+       * Optional status probe — returns a brief description of the stored
+       * credential, or null if none. Used by `moxxy login status`.
+       */
+      status?(ctx: ProviderAuthContext): Promise<ProviderOAuthStatus | null>;
+    };
+
+export interface ProviderOAuthStatus {
+  readonly accountId?: string | null;
+  readonly expiresAt?: number;
+  /** Vault key the credentials are stored under (informational). */
+  readonly vaultKey?: string;
+}
+
+export interface ProviderDef {
+  readonly name: string;
+  readonly models: ReadonlyArray<ModelDescriptor>;
+  createClient(config: Record<string, unknown>): LLMProvider;
+  /**
+   * Optional check that the given key is actually accepted by the vendor.
+   * Implementations should be cheap (a free metadata call or a 1-token
+   * completion). Used by `moxxy init` to verify keys before persisting.
+   */
+  validateKey?(apiKey: string): Promise<ProviderKeyValidation>;
+  /**
+   * Optional auth descriptor. When omitted, the host treats the provider
+   * as `{ kind: 'apiKey' }` — i.e. prompt for a key, call `validateKey`
+   * if defined, store under the canonical vault entry.
+   */
+  readonly auth?: ProviderAuthDescriptor;
+}

package/src/requirements.ts

@@ -0,0 +1,35 @@
+export type RequirementKind =
+  | 'plugin'
+  | 'provider'
+  | 'tool'
+  | 'transcriber'
+  | 'mode'
+  | 'compactor'
+  | 'channel'
+  | 'agent'
+  | 'command'
+  | 'runtime';
+
+export type RequirementState = 'registered' | 'active' | 'ready';
+
+export interface MoxxyRequirement {
+  readonly kind: RequirementKind;
+  readonly name: string;
+  readonly state?: RequirementState;
+  readonly version?: string;
+  readonly optional?: boolean;
+  readonly reason?: string;
+  readonly hint?: string;
+}
+
+export interface RequirementIssue {
+  readonly requirement: MoxxyRequirement;
+  readonly code: 'missing' | 'inactive' | 'not_ready' | 'version_mismatch';
+  readonly message: string;
+  readonly hint?: string;
+}
+
+export interface RequirementCheck {
+  readonly ready: boolean;
+  readonly issues: ReadonlyArray<RequirementIssue>;
+}

package/src/schemas.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+import { moxxyPackageSchema, pluginManifestSchema, skillFrontmatterSchema } from './schemas.js';
+
+describe('skillFrontmatterSchema', () => {
+  it('accepts minimal valid frontmatter', () => {
+    const parsed = skillFrontmatterSchema.parse({
+      name: 'refactor-component',
+      description: 'Splits a large React component into smaller files.',
+    });
+    expect(parsed.name).toBe('refactor-component');
+  });
+
+  it('accepts optional fields', () => {
+    const parsed = skillFrontmatterSchema.parse({
+      name: 'deploy',
+      description: 'Deploy to staging.',
+      triggers: ['deploy', 'ship'],
+      'allowed-tools': ['Bash'],
+      version: '1.0.0',
+      tags: ['ops'],
+    });
+    expect(parsed.triggers).toEqual(['deploy', 'ship']);
+  });
+
+  it('rejects non-slug names', () => {
+    expect(() =>
+      skillFrontmatterSchema.parse({ name: 'Refactor Component', description: 'x' }),
+    ).toThrow(/slug-like/);
+    expect(() =>
+      skillFrontmatterSchema.parse({ name: '-bad', description: 'x' }),
+    ).toThrow();
+  });
+
+  it('rejects names exceeding length cap', () => {
+    expect(() =>
+      skillFrontmatterSchema.parse({ name: 'a'.repeat(121), description: 'x' }),
+    ).toThrow();
+  });
+
+  it('rejects empty description', () => {
+    expect(() => skillFrontmatterSchema.parse({ name: 'x', description: '' })).toThrow();
+  });
+});
+
+describe('pluginManifestSchema', () => {
+  it('accepts minimal manifest', () => {
+    const parsed = pluginManifestSchema.parse({ entry: './src/index.ts' });
+    expect(parsed.entry).toBe('./src/index.ts');
+  });
+
+  it('accepts kind as scalar or array', () => {
+    expect(pluginManifestSchema.parse({ entry: 'a', kind: 'tools' }).kind).toBe('tools');
+    expect(pluginManifestSchema.parse({ entry: 'a', kind: ['tools', 'hooks'] }).kind).toEqual([
+      'tools',
+      'hooks',
+    ]);
+  });
+
+  it('accepts every public plugin kind, including transcriber/agent/command', () => {
+    expect(pluginManifestSchema.parse({ entry: 'a', kind: 'transcriber' }).kind).toBe(
+      'transcriber',
+    );
+    expect(pluginManifestSchema.parse({ entry: 'a', kind: ['agent', 'command'] }).kind).toEqual([
+      'agent',
+      'command',
+    ]);
+  });
+
+  it('rejects unknown kind', () => {
+    expect(() => pluginManifestSchema.parse({ entry: 'a', kind: 'weird' })).toThrow();
+  });
+});
+
+describe('moxxyPackageSchema', () => {
+  it('accepts the full moxxy package block with plugin + requirements', () => {
+    const parsed = moxxyPackageSchema.parse({
+      plugin: { entry: './dist/index.js', kind: 'transcriber' },
+      requirements: [
+        {
+          kind: 'plugin',
+          name: '@moxxy/plugin-provider-openai-codex',
+          state: 'registered',
+          hint: 'Enable @moxxy/plugin-provider-openai-codex.',
+        },
+      ],
+    });
+
+    expect(parsed.plugin?.entry).toBe('./dist/index.js');
+    expect(parsed.requirements).toEqual([
+      {
+        kind: 'plugin',
+        name: '@moxxy/plugin-provider-openai-codex',
+        state: 'registered',
+        hint: 'Enable @moxxy/plugin-provider-openai-codex.',
+      },
+    ]);
+  });
+
+  it('accepts a moxxy block with only requirements (no plugin entry)', () => {
+    const parsed = moxxyPackageSchema.parse({
+      requirements: [{ kind: 'plugin', name: 'base' }],
+    });
+    expect(parsed.plugin).toBeUndefined();
+    expect(parsed.requirements).toHaveLength(1);
+  });
+});