@moxxy/sdk 0.1.2 → 0.1.3

package/dist/voice.js

@@ -0,0 +1,82 @@
+/**
+ * Voice / transcription helpers shared across surfaces.
+ *
+ * The TUI's voice-input infrastructure used to inline the same logic
+ * with a `Codex`-specific name baked in. Pulled out here as
+ * *agnostic* helpers that take a transcriber name as input, so the
+ * desktop, TUI, and any future channel can mirror the same flow:
+ *
+ *   - Is the session ready to transcribe? Check via the requirements
+ *     API for a named transcriber. (`checkTranscriberReady`)
+ *   - Activate any registered transcriber lazily. Returns the active
+ *     transcriber instance. (`resolveTranscriber`)
+ *   - "Just give me whatever works" — try a list of candidates in
+ *     order, or fall back to the first registered one. (`pickFirstAvailableTranscriber`)
+ */
+/** Probe whether a *named* transcriber is ready: registered, with any
+ *  declared upstream requirements satisfied. The optional `requires`
+ *  list lets channels gate on additional provider / auth runtimes
+ *  (the Codex transcriber e.g. depends on the `openai-codex` provider
+ *  + its OAuth runtime). */
+export function checkTranscriberReady(session, transcriberName, requires = []) {
+    const baseline = [
+        { kind: 'transcriber', name: transcriberName },
+        ...requires,
+    ];
+    const check = session.requirements.check(baseline);
+    const activeName = session.transcribers.getActiveName();
+    if (!activeName || activeName === transcriberName)
+        return check;
+    const conflict = {
+        requirement: {
+            kind: 'transcriber',
+            name: transcriberName,
+            state: 'active',
+            hint: `Switch active transcriber to ${transcriberName}.`,
+        },
+        code: 'inactive',
+        message: `Required active transcriber ${transcriberName}; active is ${activeName}`,
+        hint: `Switch active transcriber to ${transcriberName}.`,
+    };
+    return { ready: false, issues: [conflict, ...check.issues] };
+}
+/** Activate a transcriber by name, lazily. Returns the active instance
+ *  ready to `.transcribe(...)`. Throws if no such transcriber is
+ *  registered, or a *different* one is already active. */
+export function resolveTranscriber(session, transcriberName) {
+    const activeName = session.transcribers.getActiveName();
+    if (activeName && activeName !== transcriberName) {
+        throw new Error(`Another transcriber is already active: ${activeName}.`);
+    }
+    if (activeName === transcriberName)
+        return session.transcribers.getActive();
+    if (session.transcribers.has(transcriberName)) {
+        return session.transcribers.setActive(transcriberName);
+    }
+    throw new Error(`No transcriber registered as ${transcriberName}. Configure one via your moxxy plugins.`);
+}
+/** "Just pick a transcriber that works."
+ *
+ *  Tries each name in `candidates` in order — first one that can be
+ *  activated wins. Returns null if none can be activated, so callers
+ *  can degrade gracefully (hide their mic button, show a "no voice
+ *  configured" tip, …) instead of throwing. */
+export function pickFirstAvailableTranscriber(session, candidates) {
+    // If something's already active, just hand that back — never fight
+    // a user-chosen activation.
+    const existing = session.transcribers.tryGetActive();
+    if (existing)
+        return existing;
+    for (const name of candidates) {
+        try {
+            return resolveTranscriber(session, name);
+        }
+        catch {
+            // Wrong-active errors don't apply here (we just returned early),
+            // so any throw is "this candidate isn't registered" — keep
+            // trying.
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=voice.js.map

package/dist/voice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice.js","sourceRoot":"","sources":["../src/voice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH;;;;4BAI4B;AAC5B,MAAM,UAAU,qBAAqB,CACnC,OAAsB,EACtB,eAAuB,EACvB,WAA4C,EAAE;IAE9C,MAAM,QAAQ,GAAoC;QAChD,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,eAAe,EAAE;QAC9C,GAAG,QAAQ;KACZ,CAAC;IACF,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACnD,MAAM,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,aAAa,EAAE,CAAC;IACxD,IAAI,CAAC,UAAU,IAAI,UAAU,KAAK,eAAe;QAAE,OAAO,KAAK,CAAC;IAEhE,MAAM,QAAQ,GAAqB;QACjC,WAAW,EAAE;YACX,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,eAAe;YACrB,KAAK,EAAE,QAAQ;YACf,IAAI,EAAE,gCAAgC,eAAe,GAAG;SACzD;QACD,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,+BAA+B,eAAe,eAAe,UAAU,EAAE;QAClF,IAAI,EAAE,gCAAgC,eAAe,GAAG;KACzD,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;AAC/D,CAAC;AAED;;0DAE0D;AAC1D,MAAM,UAAU,kBAAkB,CAChC,OAAsB,EACtB,eAAuB;IAEvB,MAAM,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,aAAa,EAAE,CAAC;IACxD,IAAI,UAAU,IAAI,UAAU,KAAK,eAAe,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CACb,0CAA0C,UAAU,GAAG,CACxD,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,KAAK,eAAe;QAAE,OAAO,OAAO,CAAC,YAAY,CAAC,SAAS,EAAE,CAAC;IAC5E,IAAI,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC;QAC9C,OAAO,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;IACzD,CAAC;IACD,MAAM,IAAI,KAAK,CACb,gCAAgC,eAAe,yCAAyC,CACzF,CAAC;AACJ,CAAC;AAED;;;;;+CAK+C;AAC/C,MAAM,UAAU,6BAA6B,CAC3C,OAAsB,EACtB,UAAiC;IAEjC,mEAAmE;IACnE,4BAA4B;IAC5B,MAAM,QAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,YAAY,EAAE,CAAC;IACrD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,OAAO,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,iEAAiE;YACjE,2DAA2D;YAC3D,UAAU;QACZ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/workflow.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Workflows — saved, parameterized, schedulable/event-triggered DAGs whose
+ * steps run a skill, a free-form prompt, a tool, or a nested workflow, piping
+ * each step's output into the next. A workflow is an *artifact* (authored like
+ * a skill, discovered from disk); the strategy that *executes* it is a
+ * swappable block — {@link WorkflowExecutorDef} — registered into the
+ * `WorkflowExecutorRegistry` and selected by name, mirroring modes/compactors.
+ *
+ * These are the shared structural types. The zod schema that validates
+ * on-disk YAML lives in `@moxxy/plugin-workflows`; its parsed output is
+ * assignable to {@link Workflow}.
+ */
+import type { Skill } from './skill.js';
+import type { SubagentSpawner } from './subagent.js';
+/** What fires a workflow. Omit `on` entirely for an on-demand-only workflow. */
+export interface WorkflowTrigger {
+    /** Cron / one-shot time trigger, dispatched by `@moxxy/plugin-scheduler`. */
+    readonly schedule?: {
+        readonly cron?: string;
+        readonly runAt?: number | string;
+        readonly timeZone?: string;
+    };
+    /** Run when the named workflow(s) complete successfully (EventLog-driven). */
+    readonly afterWorkflow?: string | ReadonlyArray<string>;
+    /** Run when files matching the glob(s) under cwd change (fs.watch-driven). */
+    readonly fileChanged?: string | ReadonlyArray<string>;
+    /** Named webhook provider whose delivery fires this workflow. */
+    readonly webhook?: string;
+}
+/** How a failed step is handled: abort the workflow, skip past it, or retry. */
+export type WorkflowStepErrorMode = 'fail' | 'continue' | 'retry';
+/**
+ * One node in the DAG. Exactly one *action* key is set
+ * (`skill` | `prompt` | `tool` | `workflow`). `input` is the templated prompt
+ * for skill/prompt actions; `args` are the templated arguments for
+ * tool/workflow actions. `needs` are the upstream step ids this step depends on.
+ */
+export interface WorkflowStep {
+    readonly id: string;
+    readonly skill?: string;
+    readonly prompt?: string;
+    readonly tool?: string;
+    readonly workflow?: string;
+    readonly input?: string;
+    readonly args?: Record<string, unknown>;
+    readonly needs: ReadonlyArray<string>;
+    /** Condition DSL; when it evaluates false the step is skipped. */
+    readonly when?: string;
+    readonly onError: WorkflowStepErrorMode;
+    readonly retries: number;
+    readonly label?: string;
+}
+export interface WorkflowInputSpec {
+    readonly default?: unknown;
+    readonly description?: string;
+}
+export interface WorkflowDelivery {
+    /** Soft hint for delivery target — e.g. "telegram", "inbox". */
+    readonly channel?: string;
+    /** Also drop the final output into `~/.moxxy/inbox/`. Default true. */
+    readonly inbox: boolean;
+}
+export interface Workflow {
+    readonly name: string;
+    readonly description: string;
+    readonly version: number;
+    /**
+     * When false the workflow is inert: triggers (schedule/event) never fire it
+     * and it is excluded from auto-runs, but it stays listable and can still be
+     * run explicitly. Toggled from the `/workflows` command.
+     */
+    readonly enabled: boolean;
+    readonly inputs: Record<string, WorkflowInputSpec>;
+    readonly on?: WorkflowTrigger;
+    readonly delivery?: WorkflowDelivery;
+    /** Max steps to run concurrently in one ready-set round. */
+    readonly concurrency: number;
+    readonly steps: ReadonlyArray<WorkflowStep>;
+}
+/** Minimal tool surface a step needs — structurally a subset of `ToolRegistry`. */
+export interface WorkflowToolRunner {
+    get(name: string): unknown | undefined;
+    execute(name: string, input: unknown, signal: AbortSignal): Promise<unknown>;
+}
+/** Look up sibling artifacts by name during a run. */
+export interface WorkflowLookup {
+    skill(name: string): Skill | undefined;
+    workflow(name: string): Workflow | undefined;
+}
+/** Lifecycle subtypes an executor emits as `plugin_event`s (mirrors plan_*). */
+export type WorkflowEventSubtype = 'workflow_started' | 'workflow_step_started' | 'workflow_step_completed' | 'workflow_step_skipped' | 'workflow_step_failed' | 'workflow_completed' | 'workflow_failed';
+/**
+ * Everything an executor needs to run a workflow, supplied by the caller.
+ * The in-turn `workflow_run` tool wires `spawner` from `ctx.subagents`; the
+ * autonomous runner builds one from an isolated session. Kept free of core
+ * imports so the executor stays in a plugin.
+ */
+export interface WorkflowRunDeps {
+    readonly spawner: SubagentSpawner;
+    readonly tools: WorkflowToolRunner;
+    readonly lookup: WorkflowLookup;
+    readonly signal: AbortSignal;
+    /** Resolved input values (defaults already applied) for this run. */
+    readonly inputs?: Record<string, unknown>;
+    /** Free-form description of what fired the run (for `{{ trigger }}`). */
+    readonly trigger?: string;
+    /** Wall-clock source. Injected so tests are deterministic. */
+    readonly now?: () => number;
+    /** Emit a workflow lifecycle event. No-op when omitted. */
+    readonly emit?: (subtype: WorkflowEventSubtype, payload: unknown) => void | Promise<void>;
+    readonly logger?: {
+        warn?(msg: string, meta?: Record<string, unknown>): void;
+        info?(msg: string, meta?: Record<string, unknown>): void;
+    };
+    /** Nested-workflow recursion depth; executors guard against runaway nesting. */
+    readonly depth?: number;
+}
+export type WorkflowStepStatus = 'completed' | 'skipped' | 'failed';
+export interface WorkflowStepResult {
+    readonly id: string;
+    readonly status: WorkflowStepStatus;
+    readonly output: string;
+    readonly error?: string;
+    readonly startedAt: number;
+    readonly endedAt: number;
+}
+export interface WorkflowRunResult {
+    readonly ok: boolean;
+    readonly steps: ReadonlyArray<WorkflowStepResult>;
+    /** Output of the terminal (sink) step(s) — what delivery sends. */
+    readonly output: string;
+    readonly error?: string;
+}
+/**
+ * A swappable workflow-execution strategy. v1 ships one (`dag`); a plugin can
+ * register alternatives (parallel-heavy, dry-run, …) and the active one is
+ * selected by name via `session.workflowExecutors.setActive(name)`.
+ */
+export interface WorkflowExecutorDef {
+    readonly name: string;
+    readonly description?: string;
+    run(workflow: Workflow, deps: WorkflowRunDeps): Promise<WorkflowRunResult>;
+}
+//# sourceMappingURL=workflow.d.ts.map

package/dist/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../src/workflow.ts"],"names":[],"mappings":"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"}

package/dist/workflow.js

@@ -0,0 +1,14 @@
+/**
+ * Workflows — saved, parameterized, schedulable/event-triggered DAGs whose
+ * steps run a skill, a free-form prompt, a tool, or a nested workflow, piping
+ * each step's output into the next. A workflow is an *artifact* (authored like
+ * a skill, discovered from disk); the strategy that *executes* it is a
+ * swappable block — {@link WorkflowExecutorDef} — registered into the
+ * `WorkflowExecutorRegistry` and selected by name, mirroring modes/compactors.
+ *
+ * These are the shared structural types. The zod schema that validates
+ * on-disk YAML lives in `@moxxy/plugin-workflows`; its parsed output is
+ * assignable to {@link Workflow}.
+ */
+export {};
+//# sourceMappingURL=workflow.js.map

package/dist/workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../src/workflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moxxy/sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Typed public surface for the moxxy framework: event types, define* factories, lifecycle hook signatures.",
   "keywords": [
     "moxxy",
@@ -24,11 +24,11 @@
   ],
   "homepage": "https://moxxy.ai",
   "bugs": {
-    "url": "https://github.com/moxxy-ai/new_moxxy/issues"
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/moxxy-ai/new_moxxy.git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
     "directory": "packages/sdk"
   },
   "author": "Michal Makowski <michal.makowski97@gmail.com>",
@@ -54,21 +54,21 @@
   "publishConfig": {
     "access": "public"
   },
+  "peerDependencies": {
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "zod": "^3.24.0",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/vitest-preset": "0.0.0"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
     "clean": "rm -rf dist .turbo"
-  },
-  "peerDependencies": {
-    "zod": "catalog:"
-  },
-  "devDependencies": {
-    "@moxxy/tsconfig": "workspace:*",
-    "@moxxy/vitest-preset": "workspace:*",
-    "typescript": "catalog:",
-    "vitest": "catalog:",
-    "zod": "catalog:"
   }
-}
+}

package/src/compactor-helpers.test.ts

@@ -4,6 +4,7 @@ import {
   asSessionId,
   asTurnId,
   estimateContextTokens,
+  isContextOverflowError,
   runCompactionIfNeeded,
   type CompactorDef,
   type EmittedEvent,
@@ -129,6 +130,46 @@ describe('runCompactionIfNeeded', () => {
     expect(ctx.emitted).toHaveLength(1);
     expect(ctx.emitted[0]).toMatchObject({ type: 'error', kind: 'retryable' });
   });
+
+  it('force compacts even when shouldCompact returns false', async () => {
+    const compact = vi.fn(async () => ({
+      type: 'compaction' as const,
+      replacedRange: [0, 1] as [number, number],
+      summary: 'summary',
+      tokensSaved: 500,
+    }));
+    const compactor: CompactorDef = {
+      name: 'gated',
+      shouldCompact: () => false, // gate says no…
+      compact,
+    };
+    const ctx = makeCtx({ compactor });
+    const did = await runCompactionIfNeeded(ctx, { force: true }); // …but force overrides
+    expect(did).toBe(true);
+    expect(compact).toHaveBeenCalledOnce();
+    expect(ctx.emitted.some((e) => e.type === 'compaction')).toBe(true);
+  });
+});
+
+describe('isContextOverflowError', () => {
+  it('matches common provider context-overflow phrasings', () => {
+    for (const msg of [
+      'input exceeds context window',
+      "This model's maximum context length is 200000 tokens",
+      'context_length_exceeded',
+      'prompt is too long: 250000 tokens > 200000 maximum',
+      'Please reduce the length of the messages',
+      'too many input tokens',
+    ]) {
+      expect(isContextOverflowError(msg)).toBe(true);
+    }
+  });
+
+  it('does not match unrelated errors', () => {
+    for (const msg of ['rate limit exceeded', 'network timeout', '500 internal server error', 'invalid api key']) {
+      expect(isContextOverflowError(msg)).toBe(false);
+    }
+  });
 });
 
 interface MakeCtxOpts {

package/src/compactor-helpers.ts

@@ -96,19 +96,22 @@ function safeJsonLen(v: unknown): number {
  * compactor bug can't kill the turn. Failures emit a non-fatal
  * `error` event for observability.
  */
-export async function runCompactionIfNeeded(ctx: ModeContext): Promise<void> {
+export async function runCompactionIfNeeded(
+  ctx: ModeContext,
+  opts: { readonly force?: boolean } = {},
+): Promise<boolean> {
   const compactor = ctx.compactor;
-  if (!compactor) return;
+  if (!compactor) return false;
 
   // Resolve the active model's descriptor so we use the *real* context
   // window. `Number.MAX_SAFE_INTEGER` (the old /compact behavior) made
   // threshold-based compactors always look comfortable, even at 99%.
   const descriptor = ctx.provider.models.find((m) => m.id === ctx.model);
   const contextWindow = descriptor?.contextWindow;
-  if (!contextWindow || contextWindow <= 0) return;
+  if (!contextWindow || contextWindow <= 0) return false;
 
   const events = ctx.log.slice();
-  if (events.length === 0) return;
+  if (events.length === 0) return false;
 
   const budget = {
     contextWindow,
@@ -116,21 +119,27 @@ export async function runCompactionIfNeeded(ctx: ModeContext): Promise<void> {
     reserveForOutput: descriptor?.maxOutputTokens ?? 0,
   } as const;
 
-  let shouldRun = false;
-  try {
-    shouldRun = compactor.shouldCompact(ctx.log, budget);
-  } catch (err) {
-    await ctx.emit({
-      type: 'error',
-      sessionId: ctx.sessionId,
-      turnId: ctx.turnId,
-      source: 'system',
-      kind: 'retryable',
-      message: `compactor.shouldCompact threw: ${err instanceof Error ? err.message : String(err)}`,
-    });
-    return;
+  // `force` skips the threshold gate — used reactively after the provider
+  // rejects a request for being over the context window (our estimate can
+  // lag the provider's real tokenizer), so we compact and retry rather than
+  // failing the turn.
+  if (!opts.force) {
+    let shouldRun = false;
+    try {
+      shouldRun = compactor.shouldCompact(ctx.log, budget);
+    } catch (err) {
+      await ctx.emit({
+        type: 'error',
+        sessionId: ctx.sessionId,
+        turnId: ctx.turnId,
+        source: 'system',
+        kind: 'retryable',
+        message: `compactor.shouldCompact threw: ${err instanceof Error ? err.message : String(err)}`,
+      });
+      return false;
+    }
+    if (!shouldRun) return false;
   }
-  if (!shouldRun) return;
 
   try {
     const result = await compactor.compact(events, {
@@ -138,7 +147,7 @@ export async function runCompactionIfNeeded(ctx: ModeContext): Promise<void> {
       budget,
       signal: ctx.signal,
     });
-    if (result.tokensSaved <= 0 || result.summary.trim().length === 0) return;
+    if (result.tokensSaved <= 0 || result.summary.trim().length === 0) return false;
     // `compactor.compact` declares `Omit<CompactionEvent, keyof EventBase>`,
     // but every shipped compactor (and the SDK examples) fills sessionId /
     // turnId / source. Defensive-fill from ctx so a compactor that obeyed
@@ -150,6 +159,7 @@ export async function runCompactionIfNeeded(ctx: ModeContext): Promise<void> {
       ...result,
     } as EmittedEvent;
     await ctx.emit(emittable);
+    return true;
   } catch (err) {
     await ctx.emit({
       type: 'error',
@@ -159,5 +169,29 @@ export async function runCompactionIfNeeded(ctx: ModeContext): Promise<void> {
       kind: 'retryable',
       message: `compactor.compact threw: ${err instanceof Error ? err.message : String(err)}`,
     });
+    return false;
   }
 }
+
+/**
+ * Heuristic: does this provider error mean "the request was too big for the
+ * model's context window"? Providers phrase it many ways (OpenAI "maximum
+ * context length is N tokens", Anthropic "prompt is too long", the runner's
+ * own "input exceeds context window"), and it usually arrives as a
+ * non-retryable 400 — so the turn loop matches on it to compact + retry
+ * instead of dying.
+ */
+const CONTEXT_OVERFLOW_PATTERNS: ReadonlyArray<RegExp> = [
+  /context[\s_-]{0,2}(window|length)/i,
+  /maximum context/i,
+  /context_length_exceeded/i,
+  /exceeds?\b[^.]{0,24}context/i,
+  /input[^.]{0,24}(exceeds|too long|too large|too many)/i,
+  /too many (input )?tokens/i,
+  /prompt is too long/i,
+  /reduce the length/i,
+];
+
+export function isContextOverflowError(message: string): boolean {
+  return CONTEXT_OVERFLOW_PATTERNS.some((re) => re.test(message));
+}

package/src/define.ts

@@ -3,6 +3,7 @@ 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 { EmbedderDef } from './embedding.js';
 import type { ModeDef } from './mode.js';
 import type { PermissionRule } from './permission.js';
 import type { Plugin, PluginSpec } from './plugin.js';
@@ -13,6 +14,7 @@ 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 { WorkflowExecutorDef } from './workflow.js';
 import type { z } from 'zod';
 
 export function definePlugin(spec: PluginSpec): Plugin {
@@ -104,6 +106,10 @@ export function defineTranscriber(spec: TranscriberDef): TranscriberDef {
   return Object.freeze(spec);
 }
 
+export function defineEmbedder(spec: EmbedderDef): EmbedderDef {
+  return Object.freeze(spec);
+}
+
 export function defineCommand(spec: CommandDef): CommandDef {
   return Object.freeze(spec);
 }
@@ -111,3 +117,7 @@ export function defineCommand(spec: CommandDef): CommandDef {
 export function defineAgent(spec: AgentDef): AgentDef {
   return Object.freeze(spec);
 }
+
+export function defineWorkflowExecutor(spec: WorkflowExecutorDef): WorkflowExecutorDef {
+  return Object.freeze(spec);
+}

package/src/embedding.ts

@@ -20,3 +20,21 @@ export interface EmbeddingProvider {
   /** Embed a batch of strings. Returns vectors in input order. */
   embed(texts: ReadonlyArray<string>): Promise<ReadonlyArray<ReadonlyArray<number>>>;
 }
+
+/**
+ * Plugin-side definition of an embedder. Mirrors `TranscriberDef` / `ProviderDef`:
+ * a `createClient(config)` factory the `EmbedderRegistry` calls when the user
+ * activates this embedder by name. Plugins contribute these via
+ * `PluginSpec.embedders`, so a user can install a new embedder package and
+ * select it by config without forking the host.
+ *
+ * `createClient` MUST be cheap — defer heavy model loading (onnx, transformers,
+ * network clients) into the returned provider's `embed()` so that merely
+ * registering a discovered embedder plugin never pulls its runtime in.
+ */
+export interface EmbedderDef {
+  readonly name: string;
+  /** Optional human-readable label for UI surfaces. */
+  readonly displayName?: string;
+  createClient(config: Record<string, unknown>): EmbeddingProvider;
+}

package/src/errors.ts

@@ -49,6 +49,9 @@ export type MoxxyErrorCode =
   | 'CONFIG_INVALID'
   | 'PLUGIN_LOAD_FAILED'
   | 'UNKNOWN_COMMAND'
+  // --- Tool / runtime ---
+  | 'TOOL_ERROR'               // a tool handler failed (bad input, not-found, exec error)
+  | 'ABORTED'                  // operation cancelled — turn abort signal or timeout kill
   // --- Catch-all ---
   | 'INTERNAL';
 

package/src/fs-utils.test.ts

@@ -0,0 +1,61 @@
+import { mkdtemp, readFile, readdir, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { moxxyHome, moxxyPath, writeFileAtomic } from './fs-utils.js';
+
+describe('writeFileAtomic', () => {
+  let dir: string;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'moxxy-fs-'));
+  });
+
+  it('writes content and creates missing parent dirs', async () => {
+    const target = join(dir, 'nested', 'deep', 'file.json');
+    await writeFileAtomic(target, '{"a":1}');
+    expect(await readFile(target, 'utf8')).toBe('{"a":1}');
+  });
+
+  it('overwrites an existing file and leaves no temp file behind', async () => {
+    const target = join(dir, 'file.txt');
+    await writeFileAtomic(target, 'first');
+    await writeFileAtomic(target, 'second');
+    expect(await readFile(target, 'utf8')).toBe('second');
+    const leftovers = (await readdir(dir)).filter((n) => n.includes('.tmp'));
+    expect(leftovers).toEqual([]);
+  });
+
+  it('enforces the requested mode past umask', async () => {
+    const target = join(dir, 'secret.json');
+    await writeFileAtomic(target, 'shh', { mode: 0o600 });
+    const mode = (await stat(target)).mode & 0o777;
+    expect(mode).toBe(0o600);
+  });
+
+  it('writes binary data unchanged', async () => {
+    const target = join(dir, 'bytes.bin');
+    const bytes = new Uint8Array([0, 1, 2, 255]);
+    await writeFileAtomic(target, bytes);
+    const read = await readFile(target);
+    expect(Array.from(read)).toEqual([0, 1, 2, 255]);
+  });
+});
+
+describe('moxxyHome / moxxyPath', () => {
+  const original = process.env.MOXXY_HOME;
+  afterEach(() => {
+    if (original === undefined) delete process.env.MOXXY_HOME;
+    else process.env.MOXXY_HOME = original;
+  });
+
+  it('honors MOXXY_HOME when set', () => {
+    process.env.MOXXY_HOME = '/custom/moxxy';
+    expect(moxxyHome()).toBe('/custom/moxxy');
+    expect(moxxyPath('vault.json')).toBe('/custom/moxxy/vault.json');
+  });
+
+  it('falls back to ~/.moxxy when unset', () => {
+    delete process.env.MOXXY_HOME;
+    expect(moxxyHome().endsWith('/.moxxy')).toBe(true);
+  });
+});