@moxxy/sdk 0.1.0

package/src/schemas.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+
+const pluginKindSchema = z.enum([
+  'tools',
+  'provider',
+  'mode',
+  'compactor',
+  'cache-strategy',
+  'view-renderer',
+  'tunnel-provider',
+  'mcp',
+  'cli',
+  'channel',
+  'hooks',
+  'agent',
+  'command',
+  'transcriber',
+]);
+
+export const requirementSchema = z.object({
+  kind: z.enum([
+    'plugin',
+    'provider',
+    'tool',
+    'transcriber',
+    'mode',
+    'compactor',
+    'channel',
+    'agent',
+    'command',
+    'runtime',
+  ]),
+  name: z.string().min(1),
+  state: z.enum(['registered', 'active', 'ready']).optional(),
+  version: z.string().min(1).optional(),
+  optional: z.boolean().optional(),
+  reason: z.string().min(1).optional(),
+  hint: z.string().min(1).optional(),
+});
+
+/**
+ * Optional schedule block on a skill. When present, the scheduler
+ * plugin (if installed) automatically registers a recurring or one-shot
+ * trigger that runs the skill body as a prompt. Either `cron` or
+ * `runAt` must be set; supplying both is rejected by the scheduler.
+ */
+export const skillScheduleSchema = z
+  .object({
+    cron: z.string().min(1).optional(),
+    runAt: z
+      .union([z.number().int(), z.string().min(1)])
+      .optional(),
+    timeZone: z.string().min(1).optional(),
+    channel: z.string().min(1).optional(),
+    enabled: z.boolean().optional(),
+  })
+  .refine((v) => !!v.cron || v.runAt !== undefined, {
+    message: 'schedule needs either `cron` or `runAt`',
+  });
+
+export const skillFrontmatterSchema = z.object({
+  name: z.string().min(1).max(120).regex(/^[a-z0-9][a-z0-9-]*$/, 'name must be slug-like'),
+  description: z.string().min(1).max(240),
+  triggers: z.array(z.string().min(1)).optional(),
+  'allowed-tools': z.array(z.string().min(1)).optional(),
+  version: z.string().optional(),
+  tags: z.array(z.string().min(1)).optional(),
+  /** Opt the skill into automatic recurring/one-shot execution. */
+  schedule: skillScheduleSchema.optional(),
+});
+
+export const pluginManifestSchema = z.object({
+  entry: z.string().min(1),
+  kind: z
+    .union([pluginKindSchema, z.array(pluginKindSchema)])
+    .optional(),
+  skills: z.string().optional(),
+});
+
+/**
+ * Shape of a package's `moxxy` field in package.json.
+ *
+ * - `plugin` — the per-package plugin manifest (`entry`, `kind`, `skills`).
+ *   When omitted the package is not treated as a moxxy plugin.
+ * - `requirements` — declarative prerequisites that gate plugin
+ *   registration and drive load-order toposort. This is the SINGLE place
+ *   requirements may be authored; per-tool/per-transcriber/per-anything
+ *   runtime declarations were removed in favor of static analysis.
+ */
+export const moxxyPackageSchema = z.object({
+  plugin: pluginManifestSchema.optional(),
+  requirements: z.array(requirementSchema).optional(),
+});
+
+export type SkillFrontmatterInput = z.infer<typeof skillFrontmatterSchema>;
+export type PluginManifestInput = z.infer<typeof pluginManifestSchema>;
+export type MoxxyPackageInput = z.infer<typeof moxxyPackageSchema>;

package/src/session-like.ts

@@ -0,0 +1,118 @@
+import type { MoxxyEvent, UserPromptAttachment } from './events.js';
+import type { SessionId, TurnId } from './ids.js';
+import type { EventLogReader } from './log.js';
+import type { ApprovalResolver } from './mode.js';
+import type { PermissionResolver } from './permission.js';
+import type { ModelDescriptor } from './provider.js';
+import type { ToolCompactPresentation } from './tool.js';
+
+/**
+ * Options accepted by `SessionLike.runTurn`. Defined here (rather than in
+ * `@moxxy/core`) so the runner client and any consumer can reference it
+ * without importing the runtime. `@moxxy/core` re-exports it.
+ */
+export interface RunTurnOptions {
+  readonly model?: string;
+  readonly systemPrompt?: string;
+  readonly maxIterations?: number;
+  /**
+   * Per-turn abort signal. Aborting it cancels this turn without tainting
+   * the session's own controller (e.g. "user hit Esc on a runaway loop").
+   */
+  readonly signal?: AbortSignal;
+  /** Inline attachments shipped alongside the prompt (images, audio, stdin). */
+  readonly attachments?: ReadonlyArray<UserPromptAttachment>;
+  /**
+   * Pre-minted turn id. When omitted, `runTurn` mints one. The runner passes
+   * this so it can return the id to the client *before* the turn starts and
+   * associate per-turn permission prompts with the originating client.
+   */
+  readonly turnId?: TurnId;
+}
+
+/**
+ * The read side of the event log plus the live subscription a channel needs
+ * to render in real time. A `RemoteSession` backs this with a local mirror
+ * fed by the runner's event stream; a local `Session` backs it with the real
+ * `EventLog`.
+ */
+export interface SessionLogReader extends EventLogReader {
+  subscribe(fn: (event: MoxxyEvent) => void | Promise<void>): () => void;
+}
+
+/** Serializable provider metadata (models + context windows) for display. */
+export interface ProviderInfo {
+  readonly name: string;
+  readonly models: ReadonlyArray<ModelDescriptor>;
+}
+
+/** Serializable tool metadata for status lines / slash menus / compact rendering. */
+export interface ToolInfo {
+  readonly name: string;
+  readonly description: string;
+  /** Compact presentation hint (plain data - crosses the wire intact). */
+  readonly compact?: ToolCompactPresentation;
+}
+
+/** Serializable skill metadata. */
+export interface SkillInfo {
+  readonly id: string;
+  readonly name: string;
+}
+
+/** Serializable slash-command metadata for the picker / `/help`. */
+export interface CommandInfo {
+  readonly name: string;
+  readonly description: string;
+  readonly aliases?: ReadonlyArray<string>;
+  readonly channels?: ReadonlyArray<string>;
+  readonly pendingNotice?: string;
+}
+
+/**
+ * A wire-friendly snapshot of a session's registries - everything a channel
+ * needs to *render* (status line, pickers, slash suggestions) without
+ * reaching into live registry objects (`LLMProvider`, `ModeDef`, `ToolDef`)
+ * whose methods can't cross a transport. A local `Session` builds it from its
+ * registries; a `RemoteSession` fetches it from the runner and refreshes it
+ * when the runner reports `info.changed`.
+ */
+export interface SessionInfo {
+  readonly sessionId: SessionId;
+  readonly cwd: string;
+  readonly activeProvider: string | null;
+  readonly providers: ReadonlyArray<ProviderInfo>;
+  readonly activeMode: string | null;
+  readonly modes: ReadonlyArray<string>;
+  readonly tools: ReadonlyArray<ToolInfo>;
+  readonly skills: ReadonlyArray<SkillInfo>;
+  readonly commands: ReadonlyArray<CommandInfo>;
+  /** Provider names the runner has activated (credentials resolved). */
+  readonly readyProviders: ReadonlyArray<string>;
+  readonly hasTranscriber: boolean;
+  /** Name of the active transcriber, or null. Lets a thin client proxy STT. */
+  readonly activeTranscriber: string | null;
+}
+
+/**
+ * The session surface a `Channel` depends on, decoupled from whether the
+ * session runs in-process (`@moxxy/core`'s `Session`) or is a thin-client
+ * proxy (`RemoteSession` from `@moxxy/runner`). The same channel code drives
+ * both - the runner/thin-client split hinges on this interface.
+ *
+ * Behavioral methods (`runTurn`, resolvers, `close`) and the live event log
+ * are the contract; richer registry *behavior* (executing a tool, streaming a
+ * provider) stays server-side and is never exposed here. For display, use the
+ * serializable `getInfo()` snapshot instead of live registry objects.
+ */
+export interface SessionLike {
+  readonly id: SessionId;
+  readonly cwd: string;
+  readonly log: SessionLogReader;
+  runTurn(prompt: string, opts?: RunTurnOptions): AsyncIterable<MoxxyEvent>;
+  setPermissionResolver(resolver: PermissionResolver): void;
+  setApprovalResolver(resolver: ApprovalResolver | null): void;
+  /** Wire-friendly registry snapshot for rendering. */
+  getInfo(): SessionInfo;
+  close(reason?: string): Promise<void>;
+}

package/src/skill.ts

@@ -0,0 +1,34 @@
+import type { SkillId } from './ids.js';
+
+export interface SkillSchedule {
+  readonly cron?: string;
+  readonly runAt?: number | string;
+  readonly timeZone?: string;
+  readonly channel?: string;
+  readonly enabled?: boolean;
+}
+
+export interface SkillFrontmatter {
+  readonly name: string;
+  readonly description: string;
+  readonly triggers?: ReadonlyArray<string>;
+  readonly 'allowed-tools'?: ReadonlyArray<string>;
+  readonly version?: string;
+  readonly tags?: ReadonlyArray<string>;
+  readonly schedule?: SkillSchedule;
+}
+
+export type SkillScope = 'project' | 'user' | 'plugin' | 'builtin';
+
+export interface Skill {
+  readonly id: SkillId;
+  readonly path: string;
+  readonly scope: SkillScope;
+  readonly frontmatter: SkillFrontmatter;
+  readonly body: string;
+}
+
+export interface SkillDef {
+  readonly frontmatter: SkillFrontmatter;
+  readonly body: string;
+}

package/src/subagent.ts

@@ -0,0 +1,46 @@
+/**
+ * Subagent primitives — let a running loop strategy or tool spawn one or
+ * more child agents that share the parent's tools / skills / providers /
+ * permissions but have an isolated event log and (typically) a focused
+ * task prompt. Children stream their work back to the parent log as
+ * `plugin_event` records with `subagent_*` subtypes, so the TUI and other
+ * subscribers can render progress live without waiting for the final
+ * message.
+ */
+
+import type { SessionId } from './ids.js';
+import type { StopReason } from './provider-utils.js';
+
+export interface SubagentSpec {
+  /** The user message the child sees as its prompt. */
+  readonly prompt: string;
+  /** Optional system prompt override for the child. */
+  readonly systemPrompt?: string;
+  /** Override model id; defaults to the parent's active model. */
+  readonly model?: string;
+  /** Mode name to run inside the child (default: `'tool-use'`). */
+  readonly mode?: string;
+  /** Per-child iteration cap (default 50). */
+  readonly maxIterations?: number;
+  /** Restrict the child to these tools by name. Omit for full inheritance. */
+  readonly allowedTools?: ReadonlyArray<string>;
+  /** Human-readable label surfaced in `subagent_*` event payloads. */
+  readonly label?: string;
+}
+
+export interface SubagentResult {
+  readonly label: string;
+  readonly childSessionId: SessionId;
+  /** The child's final assistant text (or last non-empty text if it ended on a tool call). */
+  readonly text: string;
+  readonly stopReason: StopReason;
+  /** Populated when the child loop errored fatally or threw. */
+  readonly error?: { readonly message: string };
+}
+
+export interface SubagentSpawner {
+  /** Run a single child to completion. */
+  spawn(spec: SubagentSpec): Promise<SubagentResult>;
+  /** Run N children in parallel; resolves with results in input order. */
+  spawnAll(specs: ReadonlyArray<SubagentSpec>): Promise<ReadonlyArray<SubagentResult>>;
+}

package/src/token-accounting.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest';
+import {
+  addModelTotals,
+  asEventId,
+  asSessionId,
+  asTurnId,
+  summarizeTokensByModel,
+  type ModelUsageTotals,
+  type MoxxyEvent,
+} from './index.js';
+
+const sid = asSessionId('s1');
+const t1 = asTurnId('t1');
+
+function resp(seq: number, partial: Partial<Extract<MoxxyEvent, { type: 'provider_response' }>>): MoxxyEvent {
+  return {
+    id: asEventId(`e${seq}`),
+    seq,
+    ts: seq,
+    sessionId: sid,
+    turnId: t1,
+    source: 'system',
+    type: 'provider_response',
+    provider: 'anthropic',
+    model: 'claude-opus-4-7',
+    ...partial,
+  } as MoxxyEvent;
+}
+
+describe('summarizeTokensByModel', () => {
+  it('groups usage by provider/model and sums fields', () => {
+    const byModel = summarizeTokensByModel([
+      resp(0, { provider: 'anthropic', model: 'opus', inputTokens: 100, outputTokens: 10 }),
+      resp(1, {
+        provider: 'anthropic',
+        model: 'opus',
+        inputTokens: 50,
+        outputTokens: 5,
+        cacheReadTokens: 200,
+        cacheCreationTokens: 30,
+      }),
+      resp(2, { provider: 'openai', model: 'gpt-5', inputTokens: 80, outputTokens: 8 }),
+    ]);
+
+    expect(Object.keys(byModel).sort()).toEqual(['anthropic/opus', 'openai/gpt-5']);
+    expect(byModel['anthropic/opus']).toEqual<ModelUsageTotals>({
+      calls: 2,
+      inputTokens: 150,
+      outputTokens: 15,
+      cacheReadTokens: 200,
+      cacheCreationTokens: 30,
+    });
+    expect(byModel['openai/gpt-5']!.calls).toBe(1);
+  });
+
+  it('keeps the same model id under different providers separate', () => {
+    const byModel = summarizeTokensByModel([
+      resp(0, { provider: 'a', model: 'm', inputTokens: 1 }),
+      resp(1, { provider: 'b', model: 'm', inputTokens: 2 }),
+    ]);
+    expect(byModel['a/m']!.inputTokens).toBe(1);
+    expect(byModel['b/m']!.inputTokens).toBe(2);
+  });
+
+  it('skips provider_response events that reported no usage', () => {
+    const byModel = summarizeTokensByModel([
+      resp(0, { provider: 'a', model: 'm' }), // no token fields
+    ]);
+    expect(byModel).toEqual({});
+  });
+
+  it('ignores non provider_response events', () => {
+    const byModel = summarizeTokensByModel([
+      { id: asEventId('u'), seq: 0, ts: 0, sessionId: sid, turnId: t1, source: 'user', type: 'user_prompt', text: 'hi' } as MoxxyEvent,
+      resp(1, { inputTokens: 5 }),
+    ]);
+    expect(byModel['anthropic/claude-opus-4-7']!.inputTokens).toBe(5);
+  });
+});
+
+describe('addModelTotals', () => {
+  it('adds field-wise', () => {
+    const a: ModelUsageTotals = { calls: 1, inputTokens: 10, outputTokens: 2, cacheReadTokens: 3, cacheCreationTokens: 4 };
+    const b: ModelUsageTotals = { calls: 2, inputTokens: 20, outputTokens: 5, cacheReadTokens: 1, cacheCreationTokens: 0 };
+    expect(addModelTotals(a, b)).toEqual<ModelUsageTotals>({
+      calls: 3,
+      inputTokens: 30,
+      outputTokens: 7,
+      cacheReadTokens: 4,
+      cacheCreationTokens: 4,
+    });
+  });
+});

package/src/token-accounting.ts

@@ -0,0 +1,202 @@
+import type { MoxxyEvent, ProviderResponseEvent } from './events.js';
+import type { EventLogReader } from './log.js';
+import type { TokenUsage } from './provider.js';
+
+/**
+ * Token accounting derived from the event log. The single source of truth is
+ * the stream of `provider_response` events (each carries the provider-reported
+ * usage for one call); cumulative session totals are just a fold over them, so
+ * there is no separate mutable counter to keep in sync.
+ *
+ * Anthropic usage semantics (which this models): `inputTokens` is the
+ * NON-cached portion of the prompt; cache reads and cache writes are reported
+ * separately and are NOT included in `inputTokens`. So the full prompt size of
+ * a call is `input + cacheRead + cacheCreation`.
+ */
+
+// Relative price multipliers vs. an uncached input token (Anthropic ephemeral
+// cache pricing). Kept here so the savings math is explicit and tweakable.
+const CACHE_READ_MULT = 0.1;
+const CACHE_WRITE_MULT = 1.25;
+
+/** Partial `provider_response` fields for a given usage; `{}` when usage is absent. */
+export function usageEventFields(usage?: TokenUsage): {
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadTokens?: number;
+  cacheCreationTokens?: number;
+} {
+  if (!usage) return {};
+  return {
+    inputTokens: usage.inputTokens,
+    outputTokens: usage.outputTokens,
+    ...(usage.cacheReadTokens !== undefined ? { cacheReadTokens: usage.cacheReadTokens } : {}),
+    ...(usage.cacheCreationTokens !== undefined
+      ? { cacheCreationTokens: usage.cacheCreationTokens }
+      : {}),
+  };
+}
+
+export interface SessionTokenSummary {
+  /** Number of provider calls that reported usage. */
+  readonly calls: number;
+  /** Sum of non-cached input tokens (billed 1.0x). */
+  readonly totalInput: number;
+  /** Sum of cache-read tokens (billed 0.1x). */
+  readonly totalCacheRead: number;
+  /** Sum of cache-creation/write tokens (billed 1.25x). */
+  readonly totalCacheCreation: number;
+  /** Sum of output tokens. */
+  readonly totalOutput: number;
+  /** Total prompt tokens fed to the model across the session (input + reads + writes). */
+  readonly totalPrompt: number;
+  /** cacheRead / totalPrompt — fraction of prompt served from cache. */
+  readonly cacheHitRate: number;
+  /** Billed-equivalent input cost (read 0.1x + write 1.25x + plain 1.0x), in token units. */
+  readonly billedInputEq: number;
+  /** What the input would cost with no caching (every prompt token at 1.0x). */
+  readonly uncachedInputEq: number;
+  /** 1 - billedInputEq/uncachedInputEq — fraction of input cost saved by caching. */
+  readonly savedRatio: number;
+  /**
+   * False only when caching is clearly broken: across enough calls the provider
+   * is *writing* cache (cacheCreation > 0) but almost never *reading* it back —
+   * the signature of an unstable prefix silently paying the 1.25x write tax.
+   * True when caching works OR is simply off (no writes) — so this never
+   * false-alarms a deliberately disabled cache.
+   */
+  readonly cacheEffective: boolean;
+}
+
+/** Fold `provider_response` events into cumulative per-session token totals. */
+export function summarizeSessionTokens(log: EventLogReader): SessionTokenSummary {
+  return foldResponses(log.ofType('provider_response'));
+}
+
+/**
+ * Same as {@link summarizeSessionTokens} but over a raw event array — for
+ * channels (e.g. the TUI) that hold the materialized event stream rather than
+ * an `EventLogReader`.
+ */
+export function summarizeSessionTokensFromEvents(
+  events: ReadonlyArray<MoxxyEvent>,
+): SessionTokenSummary {
+  return foldResponses(
+    events.filter((e): e is ProviderResponseEvent => e.type === 'provider_response'),
+  );
+}
+
+/**
+ * Raw per-model token totals — the shape persisted to the cross-session usage
+ * aggregate (`~/.moxxy/usage.json`). Unlike {@link SessionTokenSummary} this
+ * carries no derived/cost fields: it's a plain additive counter so totals from
+ * many sessions can be summed without re-deriving ratios.
+ */
+export interface ModelUsageTotals {
+  /** Provider calls that reported usage for this model. */
+  readonly calls: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly cacheReadTokens: number;
+  readonly cacheCreationTokens: number;
+}
+
+const ZERO_TOTALS: ModelUsageTotals = {
+  calls: 0,
+  inputTokens: 0,
+  outputTokens: 0,
+  cacheReadTokens: 0,
+  cacheCreationTokens: 0,
+};
+
+/** Add two {@link ModelUsageTotals} field-wise (for merging session deltas into the aggregate). */
+export function addModelTotals(a: ModelUsageTotals, b: ModelUsageTotals): ModelUsageTotals {
+  return {
+    calls: a.calls + b.calls,
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+    cacheCreationTokens: a.cacheCreationTokens + b.cacheCreationTokens,
+  };
+}
+
+/** A `provider_response` reported usage iff any token field is present. */
+function hasUsage(e: ProviderResponseEvent): boolean {
+  return (
+    e.inputTokens !== undefined ||
+    e.outputTokens !== undefined ||
+    e.cacheReadTokens !== undefined ||
+    e.cacheCreationTokens !== undefined
+  );
+}
+
+/**
+ * Fold `provider_response` events into per-model token totals, keyed by
+ * `"<provider>/<model>"` (the same model id can be served by more than one
+ * provider, so both pin the key). Used by the usage-stats plugin to compute a
+ * session's contribution and by the `/usage` panel to render the lifetime
+ * breakdown.
+ */
+export function summarizeTokensByModel(
+  events: ReadonlyArray<MoxxyEvent>,
+): Record<string, ModelUsageTotals> {
+  const byModel: Record<string, ModelUsageTotals> = {};
+  for (const e of events) {
+    if (e.type !== 'provider_response') continue;
+    if (!hasUsage(e)) continue;
+    const key = `${e.provider}/${e.model}`;
+    byModel[key] = addModelTotals(byModel[key] ?? ZERO_TOTALS, {
+      calls: 1,
+      inputTokens: e.inputTokens ?? 0,
+      outputTokens: e.outputTokens ?? 0,
+      cacheReadTokens: e.cacheReadTokens ?? 0,
+      cacheCreationTokens: e.cacheCreationTokens ?? 0,
+    });
+  }
+  return byModel;
+}
+
+function foldResponses(responses: ReadonlyArray<ProviderResponseEvent>): SessionTokenSummary {
+  let calls = 0;
+  let totalInput = 0;
+  let totalCacheRead = 0;
+  let totalCacheCreation = 0;
+  let totalOutput = 0;
+
+  for (const e of responses) {
+    // Count a call only when it reported any token data.
+    if (
+      e.inputTokens === undefined &&
+      e.outputTokens === undefined &&
+      e.cacheReadTokens === undefined &&
+      e.cacheCreationTokens === undefined
+    ) {
+      continue;
+    }
+    calls += 1;
+    totalInput += e.inputTokens ?? 0;
+    totalCacheRead += e.cacheReadTokens ?? 0;
+    totalCacheCreation += e.cacheCreationTokens ?? 0;
+    totalOutput += e.outputTokens ?? 0;
+  }
+
+  const totalPrompt = totalInput + totalCacheRead + totalCacheCreation;
+  const billedInputEq =
+    totalInput + totalCacheRead * CACHE_READ_MULT + totalCacheCreation * CACHE_WRITE_MULT;
+  const uncachedInputEq = totalPrompt;
+  const cacheHitRate = totalPrompt > 0 ? totalCacheRead / totalPrompt : 0;
+  return {
+    calls,
+    totalInput,
+    totalCacheRead,
+    totalCacheCreation,
+    totalOutput,
+    totalPrompt,
+    cacheHitRate,
+    billedInputEq,
+    uncachedInputEq,
+    savedRatio: uncachedInputEq > 0 ? 1 - billedInputEq / uncachedInputEq : 0,
+    // Broken = writing cache but not reading it back, over enough calls.
+    cacheEffective: !(calls >= 5 && totalCacheCreation > 0 && cacheHitRate < 0.05),
+  };
+}