@moxxy/sdk 0.1.0

package/src/compactor.ts

@@ -0,0 +1,20 @@
+import type { CompactionEvent, MoxxyEvent } from './events.js';
+import type { EventLogReader } from './log.js';
+
+export interface TokenBudget {
+  readonly contextWindow: number;
+  readonly estimatedTokens: number;
+  readonly reserveForOutput: number;
+}
+
+export interface CompactContext {
+  readonly log: EventLogReader;
+  readonly budget: TokenBudget;
+  readonly signal: AbortSignal;
+}
+
+export interface CompactorDef {
+  readonly name: string;
+  shouldCompact(log: EventLogReader, budget: TokenBudget): boolean;
+  compact(events: ReadonlyArray<MoxxyEvent>, ctx: CompactContext): Promise<Omit<CompactionEvent, keyof import('./events.js').EventBase> & { ts?: number }>;
+}

package/src/define.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import {
+  defineCompactor,
+  defineMode,
+  definePermission,
+  definePlugin,
+  defineProvider,
+  defineSkill,
+  defineTool,
+  defineTranscriber,
+} from './define.js';
+
+describe('define* factories', () => {
+  it('definePlugin freezes and stamps __moxxy + version', () => {
+    const p = definePlugin({ name: 'p', tools: [] });
+    expect(p.__moxxy).toBe('plugin');
+    expect(p.version).toBe('0.0.0');
+    expect(Object.isFrozen(p)).toBe(true);
+  });
+
+  it('definePlugin preserves explicit version', () => {
+    const p = definePlugin({ name: 'p', version: '1.2.3' });
+    expect(p.version).toBe('1.2.3');
+  });
+
+  it('definePlugin defaults version when spec.version is explicitly undefined', () => {
+    // Reproduces the spread-order bug: a spec with `version: undefined`
+    // (e.g. produced by destructuring) must not erase the default.
+    const spec = { name: 'p', version: undefined as string | undefined };
+    const p = definePlugin(spec);
+    expect(p.version).toBe('0.0.0');
+  });
+
+  it('defineTool round-trips typed input', async () => {
+    const tool = defineTool({
+      name: 'echo',
+      description: 'echoes',
+      inputSchema: z.object({ msg: z.string() }),
+      handler: (input) => input.msg.toUpperCase(),
+    });
+    expect(tool.name).toBe('echo');
+    const out = await tool.handler({ msg: 'hi' }, {} as never);
+    expect(out).toBe('HI');
+  });
+
+  it('defineProvider, defineMode, defineCompactor, definePermission, defineSkill, defineTranscriber all freeze', () => {
+    const items = [
+      defineProvider({ name: 'p', models: [], createClient: () => ({}) as never }),
+      defineMode({ name: 'l', run: async function* () {} }),
+      defineCompactor({ name: 'c', shouldCompact: () => false, compact: async () => ({}) as never }),
+      definePermission({ action: 'allow' }),
+      defineSkill({ frontmatter: { name: 'foo', description: 'd' }, body: '' }),
+      defineTranscriber({
+        name: 't',
+        createClient: () => ({ name: 't', transcribe: async () => ({ text: '' }) }),
+      }),
+    ];
+    for (const item of items) expect(Object.isFrozen(item)).toBe(true);
+  });
+
+  it('defineTranscriber preserves displayName + createClient identity', () => {
+    const t = defineTranscriber({
+      name: 'whisper-fake',
+      displayName: 'Whisper (fake)',
+      createClient: (cfg) => ({
+        name: 'whisper-fake',
+        transcribe: async () => ({ text: String(cfg.echo ?? '') }),
+      }),
+    });
+    expect(t.name).toBe('whisper-fake');
+    expect(t.displayName).toBe('Whisper (fake)');
+    const client = t.createClient({ echo: 'hi' });
+    expect(client.name).toBe('whisper-fake');
+  });
+});

package/src/define.ts

@@ -0,0 +1,113 @@
+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 { ModeDef } from './mode.js';
+import type { PermissionRule } from './permission.js';
+import type { Plugin, PluginSpec } from './plugin.js';
+import type { ProviderDef } from './provider.js';
+import type { SkillDef, SkillFrontmatter } from './skill.js';
+import type { ToolCompactPresentation, ToolContext, ToolDef } from './tool.js';
+import type { ToolIsolationSpec } from './isolation.js';
+import type { TranscriberDef } from './transcriber.js';
+import type { ViewRendererDef } from './view-renderer.js';
+import type { TunnelProviderDef } from './tunnel.js';
+import type { z } from 'zod';
+
+export function definePlugin(spec: PluginSpec): Plugin {
+  // Spread spec first so the defaults below can't be clobbered by an
+  // explicit `version: undefined` in the spec (which violates Plugin.version
+  // typed as `string`).
+  return Object.freeze({
+    ...spec,
+    __moxxy: 'plugin' as const,
+    version: spec.version ?? '0.0.0',
+  });
+}
+
+/**
+ * `defineTool` carries an extra generic `<S, O>` so the `handler`'s `input`
+ * parameter is typed as `z.output<S>` rather than `unknown` — that's the
+ * authoring-ergonomics benefit. The returned `ToolDef` widens the handler
+ * to the runtime contract `(unknown, ToolContext) => unknown` because the
+ * registry parses input via `inputSchema` before calling.
+ */
+export function defineTool<S extends z.ZodTypeAny, O = unknown>(spec: {
+  name: string;
+  description: string;
+  inputSchema: S;
+  inputJsonSchema?: unknown;
+  outputSchema?: z.ZodType<O>;
+  permission?: PermissionRule;
+  handler: (input: z.output<S>, ctx: ToolContext) => Promise<O> | O;
+  compact?: ToolCompactPresentation;
+  isolation?: ToolIsolationSpec;
+}): ToolDef {
+  return Object.freeze({
+    name: spec.name,
+    description: spec.description,
+    inputSchema: spec.inputSchema,
+    inputJsonSchema: spec.inputJsonSchema,
+    outputSchema: spec.outputSchema,
+    permission: spec.permission,
+    handler: spec.handler as (input: unknown, ctx: ToolContext) => Promise<unknown> | unknown,
+    compact: spec.compact,
+    isolation: spec.isolation,
+  });
+}
+
+// Every other `defineX` follows the same `(spec: XDef): XDef` shape: it
+// freezes the spec and hands it back. The compile-time win is a clean
+// "this is how you author one" signature; the runtime win is
+// Object.freeze so plugin authors can't mutate published defs.
+
+export function defineProvider(spec: ProviderDef): ProviderDef {
+  return Object.freeze(spec);
+}
+
+export function defineMode(spec: ModeDef): ModeDef {
+  return Object.freeze(spec);
+}
+
+export function defineCompactor(spec: CompactorDef): CompactorDef {
+  return Object.freeze(spec);
+}
+
+export function defineCacheStrategy(spec: CacheStrategyDef): CacheStrategyDef {
+  return Object.freeze(spec);
+}
+
+export function defineViewRenderer(spec: ViewRendererDef): ViewRendererDef {
+  return Object.freeze(spec);
+}
+
+export function defineTunnelProvider(spec: TunnelProviderDef): TunnelProviderDef {
+  return Object.freeze(spec);
+}
+
+export function defineChannel<TStartOpts = unknown>(
+  spec: ChannelDef<TStartOpts>,
+): ChannelDef<TStartOpts> {
+  return Object.freeze(spec);
+}
+
+export function definePermission(spec: PermissionRule): PermissionRule {
+  return Object.freeze(spec);
+}
+
+export function defineSkill(spec: { frontmatter: SkillFrontmatter; body: string }): SkillDef {
+  return Object.freeze(spec);
+}
+
+export function defineTranscriber(spec: TranscriberDef): TranscriberDef {
+  return Object.freeze(spec);
+}
+
+export function defineCommand(spec: CommandDef): CommandDef {
+  return Object.freeze(spec);
+}
+
+export function defineAgent(spec: AgentDef): AgentDef {
+  return Object.freeze(spec);
+}

package/src/elision-helpers.ts

@@ -0,0 +1,143 @@
+import { estimateContextTokens } from './compactor-helpers.js';
+import { toolResultBytes } from './elision-state.js';
+import type { EmittedEvent, MoxxyEvent } from './events.js';
+import type { ElisionSettings, ModeContext } from './mode.js';
+
+/**
+ * Turn-boundary elision (context-on-demand). Called once per loop iteration by
+ * every mode, right next to `runCompactionIfNeeded`. When the recent window
+ * exceeds `keepRecentTurns` AND the context is at least `minContextRatioToElide`
+ * full, it advances a high-water mark (in whole-turn steps) by appending an
+ * `ElisionEvent`. `projectMessagesFromLog` then renders events at or below that
+ * mark as compact stubs the model can expand via the `recall` tool.
+ *
+ * Hard invariants (independent of config): never elide the in-progress turn,
+ * never elide the first user_prompt (task anchor — enforced in projection),
+ * and degrade to a no-op on any internal error so an elision bug can't kill a
+ * turn. The mark only advances on completed-turn boundaries, which keeps the
+ * elided prefix byte-stable across a turn's iterations so caching still hits.
+ */
+export interface ResolvedElisionSettings {
+  readonly enabled: boolean;
+  readonly keepRecentTurns: number;
+  readonly minContextRatioToElide: number;
+  readonly elideConversational: boolean;
+  readonly conversationalRecallThreshold: number;
+  readonly maxRecallBytes: number;
+  readonly neverElideTools: ReadonlyArray<string>;
+}
+
+const DEFAULTS: ResolvedElisionSettings = {
+  enabled: true,
+  keepRecentTurns: 4,
+  minContextRatioToElide: 0.3,
+  // User-selected default: aggressive context-on-demand (collapse old text
+  // turns too), but with adaptive auto-disable below.
+  elideConversational: true,
+  // After this many seq-based recalls, conversational elision switches off for
+  // the session (the model is clearly leaning on elided text turns).
+  conversationalRecallThreshold: 4,
+  maxRecallBytes: 32_768,
+  neverElideTools: [],
+};
+
+export function resolveElisionSettings(s?: ElisionSettings): ResolvedElisionSettings {
+  return {
+    enabled: s?.enabled ?? DEFAULTS.enabled,
+    // Hard floor: never keep fewer than 2 recent turns verbatim.
+    keepRecentTurns: Math.max(2, s?.keepRecentTurns ?? DEFAULTS.keepRecentTurns),
+    minContextRatioToElide: s?.minContextRatioToElide ?? DEFAULTS.minContextRatioToElide,
+    elideConversational: s?.elideConversational ?? DEFAULTS.elideConversational,
+    conversationalRecallThreshold:
+      s?.conversationalRecallThreshold ?? DEFAULTS.conversationalRecallThreshold,
+    maxRecallBytes: s?.maxRecallBytes ?? DEFAULTS.maxRecallBytes,
+    neverElideTools: s?.neverElideTools ?? DEFAULTS.neverElideTools,
+  };
+}
+
+export async function runElisionIfNeeded(ctx: ModeContext): Promise<void> {
+  try {
+    const s = resolveElisionSettings(ctx.elision);
+    if (!s.enabled) return;
+
+    const descriptor = ctx.provider.models.find((m) => m.id === ctx.model);
+    const contextWindow = descriptor?.contextWindow;
+    if (!contextWindow || contextWindow <= 0) return;
+
+    // Gate: below this fill the whole history fits comfortably — eliding would
+    // only add missed-context risk for no token benefit.
+    if (estimateContextTokens(ctx.log) < s.minContextRatioToElide * contextWindow) return;
+
+    const events = ctx.log.slice();
+    if (events.length === 0) return;
+
+    const priorHWM = events.reduce(
+      (max, e) => (e.type === 'elision' ? Math.max(max, e.elidedThrough) : max),
+      -1,
+    );
+
+    // Distinct COMPLETED turns in order (exclude the in-progress turn).
+    const turnOrder: string[] = [];
+    const seen = new Set<string>();
+    for (const e of events) {
+      if (e.turnId === ctx.turnId) continue;
+      if (!seen.has(e.turnId)) {
+        seen.add(e.turnId);
+        turnOrder.push(e.turnId);
+      }
+    }
+    if (turnOrder.length <= s.keepRecentTurns) return;
+
+    // Elide every completed turn before the recent window.
+    const elideTurns = new Set(turnOrder.slice(0, turnOrder.length - s.keepRecentTurns));
+    let to = -1;
+    for (const e of events) {
+      if (elideTurns.has(e.turnId)) to = Math.max(to, e.seq);
+    }
+    if (to <= priorHWM) return; // nothing new to elide
+
+    const from = priorHWM + 1;
+    const tokensSaved = estimateElisionSavings(events, from, to, s.neverElideTools);
+
+    const emittable: EmittedEvent = {
+      type: 'elision',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'system',
+      elidedThrough: to,
+      stubbedRanges: [[from, to]],
+      elideConversational: s.elideConversational,
+      conversationalRecallThreshold: s.conversationalRecallThreshold,
+      maxRecallBytes: s.maxRecallBytes,
+      neverElideTools: s.neverElideTools,
+      tokensSaved,
+    };
+    await ctx.emit(emittable);
+  } catch {
+    // Elision is best-effort; a bug here must never kill the turn.
+  }
+}
+
+function estimateElisionSavings(
+  events: ReadonlyArray<MoxxyEvent>,
+  from: number,
+  to: number,
+  neverElide: ReadonlyArray<string>,
+): number {
+  const neverSet = new Set(neverElide);
+  const toolNameByCall = new Map<string, string>();
+  for (const e of events) {
+    if (e.type === 'tool_call_requested') toolNameByCall.set(e.callId, e.name);
+  }
+  let savedChars = 0;
+  for (const e of events) {
+    if (e.seq < from || e.seq > to) continue;
+    if (e.type === 'tool_result' && !e.error) {
+      const name = toolNameByCall.get(e.callId);
+      if (name && neverSet.has(name)) continue;
+      const bytes = toolResultBytes(e.output);
+      savedChars += Math.max(0, bytes - 60); // stub is ~60 chars
+    }
+  }
+  return Math.ceil(savedChars / 4);
+}

package/src/elision-state.ts

@@ -0,0 +1,170 @@
+import type { MoxxyEvent } from './events.js';
+
+/**
+ * Shared elision decision logic — the single source of truth for "is this event
+ * stubbed, and to what size", consumed by BOTH `projectMessagesFromLog` (what we
+ * send) and `estimateContextTokens` (what we think we send). Keeping them in one
+ * leaf module guarantees the estimate matches reality (no overflow from
+ * undercounting pinned recalls) and avoids a circular import between the
+ * projection and the estimate.
+ */
+
+/** Below this size, eliding a turn/result saves nothing — keep it verbatim. */
+export const TINY_TURN_CHARS = 200;
+
+/** Bytes of a tool_result payload (for stub labels + the recall cap). */
+export function toolResultBytes(output: unknown, errorMessage?: string): number {
+  if (errorMessage !== undefined) return errorMessage.length;
+  if (typeof output === 'string') return output.length;
+  try {
+    return JSON.stringify(output ?? '').length;
+  } catch {
+    return 0;
+  }
+}
+
+/** Deterministic stub for an elided tool result. Stable bytes → cache-safe. */
+export function toolResultStub(callId: string, bytes: number, recalled: boolean): string {
+  if (recalled) return `[output elided — already recalled below · call "${callId}"]`;
+  const label = bytes >= 1024 ? `${(Math.round(bytes / 102.4) / 10).toFixed(1)} KB` : `${bytes} B`;
+  return `[output elided — ${label} · recall("${callId}") to view]`;
+}
+
+/** Deterministic stub for an elided conversational (user/assistant) turn. */
+export function conversationalStub(role: 'user' | 'assistant', seq: number): string {
+  return `[elided ${role} turn · recall({ seq: ${seq} }) to view]`;
+}
+
+export interface ElisionState {
+  /** Inclusive seq high-water mark; -1 when no elision is active. */
+  readonly hwm: number;
+  /** Conversational elision after the adaptive auto-disable check. */
+  readonly effectiveElideConversational: boolean;
+  readonly neverElide: ReadonlySet<string>;
+  readonly toolNameByCall: ReadonlyMap<string, string>;
+  /** callIds an earlier `recall` referenced (their stub says "already recalled"). */
+  readonly recalledCallIds: ReadonlySet<string>;
+  readonly recalledSeqs: ReadonlySet<number>;
+  /** callIds whose tool_result IS a recall's output — pinned verbatim... */
+  readonly recallResultCallIds: ReadonlySet<string>;
+  /** ...except these, which exceeded `maxRecallBytes` and get stubbed. */
+  readonly unpinnedRecallCallIds: ReadonlySet<string>;
+  /** Seq of the first user_prompt (task anchor) — never elided. */
+  readonly firstUserPromptSeq: number;
+}
+
+const EMPTY_STATE: ElisionState = {
+  hwm: -1,
+  effectiveElideConversational: false,
+  neverElide: new Set(),
+  toolNameByCall: new Map(),
+  recalledCallIds: new Set(),
+  recalledSeqs: new Set(),
+  recallResultCallIds: new Set(),
+  unpinnedRecallCallIds: new Set(),
+  firstUserPromptSeq: -1,
+};
+
+/**
+ * Derive elision state purely from the log: the active high-water mark + flags
+ * (from the latest ElisionEvent), the callId→tool map, recall bookkeeping, the
+ * adaptive conversational auto-disable, and which pinned recalls exceed the cap.
+ */
+export function computeElisionState(events: ReadonlyArray<MoxxyEvent>): ElisionState {
+  let hwm = -1;
+  let elideConversational = false;
+  let conversationalRecallThreshold = Number.POSITIVE_INFINITY;
+  let maxRecallBytes = Number.POSITIVE_INFINITY;
+  let neverElide: ReadonlyArray<string> = [];
+  for (const e of events) {
+    if (e.type === 'elision' && e.elidedThrough > hwm) {
+      hwm = e.elidedThrough;
+      elideConversational = e.elideConversational;
+      conversationalRecallThreshold = e.conversationalRecallThreshold;
+      maxRecallBytes = e.maxRecallBytes;
+      neverElide = e.neverElideTools;
+    }
+  }
+  if (hwm < 0) return EMPTY_STATE;
+
+  const toolNameByCall = new Map<string, string>();
+  const recalledCallIds = new Set<string>();
+  const recalledSeqs = new Set<number>();
+  const recallResultCallIds = new Set<string>();
+  let seqRecalls = 0;
+  let firstUserPromptSeq = -1;
+
+  for (const e of events) {
+    if (e.type === 'tool_call_requested') {
+      toolNameByCall.set(e.callId, e.name);
+      if (e.name === 'recall') {
+        recallResultCallIds.add(e.callId);
+        const input = e.input as { callId?: unknown; seq?: unknown } | null | undefined;
+        if (input && typeof input === 'object') {
+          if (typeof input.callId === 'string') recalledCallIds.add(input.callId);
+          if (typeof input.seq === 'number') {
+            recalledSeqs.add(input.seq);
+            seqRecalls += 1; // seq-recalls = signal that TEXT elision is hurting
+          }
+        }
+      }
+    } else if (e.type === 'user_prompt' && firstUserPromptSeq < 0) {
+      firstUserPromptSeq = e.seq;
+    }
+  }
+
+  // Cap pinned recalls: keep the newest recall outputs within maxRecallBytes
+  // verbatim, stub the rest. Only matters once a recall result ages below HWM.
+  const unpinnedRecallCallIds = new Set<string>();
+  const agedRecalls = events
+    .filter(
+      (e): e is Extract<MoxxyEvent, { type: 'tool_result' }> =>
+        e.type === 'tool_result' && recallResultCallIds.has(e.callId) && e.seq <= hwm,
+    )
+    .sort((a, b) => b.seq - a.seq); // newest first
+  let pinned = 0;
+  for (const e of agedRecalls) {
+    pinned += toolResultBytes(e.output, e.error?.message);
+    if (pinned > maxRecallBytes) unpinnedRecallCallIds.add(e.callId);
+  }
+
+  return {
+    hwm,
+    effectiveElideConversational: elideConversational && seqRecalls < conversationalRecallThreshold,
+    neverElide: new Set(neverElide),
+    toolNameByCall,
+    recalledCallIds,
+    recalledSeqs,
+    recallResultCallIds,
+    unpinnedRecallCallIds,
+    firstUserPromptSeq,
+  };
+}
+
+/** Is this tool_result sent as a stub? (Shared by projection + estimate.) */
+export function toolResultStubbed(
+  e: Extract<MoxxyEvent, { type: 'tool_result' }>,
+  state: ElisionState,
+): boolean {
+  if (e.seq > state.hwm || e.error) return false;
+  const name = state.toolNameByCall.get(e.callId);
+  if (name !== undefined && state.neverElide.has(name)) return false;
+  if (state.recallResultCallIds.has(e.callId)) {
+    // Recall outputs are pinned verbatim unless they blew the cap.
+    return state.unpinnedRecallCallIds.has(e.callId);
+  }
+  if (toolResultBytes(e.output) <= TINY_TURN_CHARS) return false; // tiny: keep full
+  return true;
+}
+
+/** Is this user/assistant turn collapsed to a conversational stub? */
+export function conversationalStubbed(
+  e: Extract<MoxxyEvent, { type: 'user_prompt' | 'assistant_message' }>,
+  state: ElisionState,
+): boolean {
+  if (e.seq > state.hwm || !state.effectiveElideConversational) return false;
+  if (e.type === 'user_prompt' && e.seq === state.firstUserPromptSeq) return false; // anchor
+  const len = e.type === 'user_prompt' ? e.text.length : e.content.length;
+  if (len <= TINY_TURN_CHARS) return false;
+  return true;
+}

package/src/embedding.ts

@@ -0,0 +1,22 @@
+/**
+ * Provider of dense vector embeddings for text. Used by @moxxy/plugin-memory
+ * for semantic recall. Implementations might call OpenAI, Voyage, Anthropic
+ * (when available), or run a local model via transformers.js.
+ *
+ * @moxxy/plugin-memory ships a built-in TF-IDF embedder for zero-dep operation
+ * — set `mode: 'auto'` (default) and it picks the registered provider when
+ * available, else TF-IDF.
+ */
+export interface EmbeddingProvider {
+  /** Short stable name, e.g. 'openai-text-embedding-3-small'. */
+  readonly name: string;
+
+  /**
+   * Vector dimensionality. Consumers may verify this matches their stored
+   * index. For TF-IDF this is the vocab size (dynamic).
+   */
+  readonly dim: number | 'dynamic';
+
+  /** Embed a batch of strings. Returns vectors in input order. */
+  embed(texts: ReadonlyArray<string>): Promise<ReadonlyArray<ReadonlyArray<number>>>;
+}