@moxxy/sdk 0.1.0 → 0.1.3

package/dist/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../src/workflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,8EAA8E;IAC9E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACxD,8EAA8E;IAC9E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACtD,iEAAiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,gFAAgF;AAChF,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;AAElE;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACnD,QAAQ,CAAC,EAAE,CAAC,EAAE,eAAe,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;CAC7C;AAED,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IACvC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9E;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;CAC9C;AAED,gFAAgF;AAChF,MAAM,MAAM,oBAAoB,GAC5B,kBAAkB,GAClB,uBAAuB,GACvB,yBAAyB,GACzB,uBAAuB,GACvB,sBAAsB,GACtB,oBAAoB,GACpB,iBAAiB,CAAC;AAEtB;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACzD,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;KAC1D,CAAC;IACF,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEpE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAClD,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC5E"}

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,7 +1,42 @@
 {
   "name": "@moxxy/sdk",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Typed public surface for the moxxy framework: event types, define* factories, lifecycle hook signatures.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "agents",
+    "agent-framework",
+    "ai",
+    "llm",
+    "anthropic",
+    "claude",
+    "openai",
+    "gpt",
+    "plugin",
+    "plugin-sdk",
+    "sdk",
+    "tools",
+    "tool-use",
+    "mcp",
+    "typescript",
+    "zero-deps"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/sdk"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.10.0"
+  },
+  "sideEffects": false,
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -13,7 +48,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"

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);
+  });
+});

package/src/fs-utils.ts

@@ -0,0 +1,55 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export interface WriteFileAtomicOptions {
+  /** Mode for the final file, e.g. `0o600` for secrets. Enforced past umask. */
+  readonly mode?: number;
+  /** Encoding when `data` is a string. Defaults to `'utf8'`. Ignored for bytes. */
+  readonly encoding?: BufferEncoding;
+}
+
+/**
+ * Crash-atomic file write: write a unique sibling temp file, then `rename` it
+ * over the target. POSIX `rename` is atomic on the same filesystem, so a crash
+ * (or full disk) mid-write leaves the previous file intact rather than a
+ * truncated one. The temp name carries pid + a random UUID so concurrent
+ * writers to the same target never collide on the temp path.
+ *
+ * This is the single home for the framework's "persist atomically" invariant —
+ * every file-state writer (vault, memory, permissions, sessions, the Write/Edit
+ * tools) should call this instead of hand-rolling tmp+rename or writing in place.
+ */
+export async function writeFileAtomic(
+  target: string,
+  data: string | Uint8Array,
+  opts: WriteFileAtomicOptions = {},
+): Promise<void> {
+  await mkdir(dirname(target), { recursive: true });
+  const tmp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmp, data, { encoding: opts.encoding ?? 'utf8' });
+    // chmod explicitly: writeFile's mode option is masked by umask, but a
+    // 0o600 secret file must be exactly 0o600 regardless of the host umask.
+    if (opts.mode != null) await chmod(tmp, opts.mode);
+    await rename(tmp, target);
+  } catch (err) {
+    await rm(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+/**
+ * The moxxy home directory: `$MOXXY_HOME` when set, else `~/.moxxy`. Single
+ * source of truth so the env override is honored uniformly — previously half
+ * the plugins inlined `~/.moxxy` and ignored `MOXXY_HOME`.
+ */
+export function moxxyHome(): string {
+  return process.env.MOXXY_HOME ?? join(homedir(), '.moxxy');
+}
+
+/** Join path segments under {@link moxxyHome}. */
+export function moxxyPath(...segments: string[]): string {
+  return join(moxxyHome(), ...segments);
+}

package/src/http-utils.test.ts

@@ -0,0 +1,36 @@
+import type { IncomingMessage } from 'node:http';
+import { Readable } from 'node:stream';
+import { describe, expect, it } from 'vitest';
+import { bearerTokenMatches, readRequestBody } from './http-utils.js';
+
+function fakeReq(body: string | Buffer): IncomingMessage {
+  return Readable.from([Buffer.from(body)]) as unknown as IncomingMessage;
+}
+
+describe('bearerTokenMatches', () => {
+  it('matches an identical token', () => {
+    expect(bearerTokenMatches('s3cret', 's3cret')).toBe(true);
+  });
+  it('rejects a different token of equal length', () => {
+    expect(bearerTokenMatches('aaaaaa', 'bbbbbb')).toBe(false);
+  });
+  it('rejects a length mismatch without throwing', () => {
+    expect(bearerTokenMatches('short', 'longer-token')).toBe(false);
+  });
+  it('rejects empty/missing presented tokens', () => {
+    expect(bearerTokenMatches(undefined, 'x')).toBe(false);
+    expect(bearerTokenMatches(null, 'x')).toBe(false);
+    expect(bearerTokenMatches('', 'x')).toBe(false);
+  });
+});
+
+describe('readRequestBody', () => {
+  it('reads the full body', async () => {
+    const buf = await readRequestBody(fakeReq('hello world'), 1024);
+    expect(buf.toString('utf8')).toBe('hello world');
+  });
+
+  it('rejects when the body exceeds maxBytes', async () => {
+    await expect(readRequestBody(fakeReq('x'.repeat(100)), 10)).rejects.toThrow(/exceeds 10 bytes/);
+  });
+});

package/src/http-utils.ts

@@ -0,0 +1,40 @@
+import { timingSafeEqual } from 'node:crypto';
+import type { IncomingMessage } from 'node:http';
+
+/**
+ * Read a request body into a Buffer, rejecting (and destroying the socket) once
+ * `maxBytes` is exceeded. Bounds in-memory buffering so a malicious or runaway
+ * client can't exhaust the host's memory. Shared by every HTTP channel/listener.
+ */
+export async function readRequestBody(req: IncomingMessage, maxBytes: number): Promise<Buffer> {
+  return new Promise<Buffer>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > maxBytes) {
+        reject(new Error(`request body exceeds ${maxBytes} bytes`));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Constant-time comparison of a presented bearer token against the expected
+ * value. A length mismatch returns false WITHOUT calling `timingSafeEqual`
+ * (which throws on unequal lengths and would leak the length); equal-length
+ * inputs are compared in constant time so an attacker can't recover the token
+ * byte-by-byte via response timing.
+ */
+export function bearerTokenMatches(presented: string | undefined | null, expected: string): boolean {
+  if (!presented) return false;
+  const a = Buffer.from(presented);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}

package/src/index.ts

@@ -47,6 +47,12 @@ export type {
   ToolInfo,
   SkillInfo,
   CommandInfo,
+  CredentialResolver,
+  McpAdminView,
+  McpServerStatusView,
+  WorkflowsView,
+  WorkflowSummaryView,
+  WorkflowRunView,
 } from './session-like.js';
 
 export type {
@@ -135,7 +141,22 @@ export type {
 } from './view-renderer.js';
 export { VIEW_PRIMITIVES, VIEW_COMPONENTS, DEFAULT_VIEW_TAGS } from './view-renderer.js';
 export type { TunnelProviderDef, TunnelHandle, TunnelOpenOptions } from './tunnel.js';
-export { isRetryableError, toFriendlyError, zodToJsonSchema, type StopReason } from './provider-utils.js';
+export { isRetryableError, toFriendlyError, zodToJsonSchema, estimateTextTokens, type StopReason } from './provider-utils.js';
+export { writeFileAtomic, moxxyHome, moxxyPath, type WriteFileAtomicOptions } from './fs-utils.js';
+export { createMutex, type Mutex } from './mutex.js';
+export { readRequestBody, bearerTokenMatches } from './http-utils.js';
+export {
+  autoAllowResolver,
+  denyByDefaultResolver,
+  createCallbackResolver,
+  createAllowListResolver,
+  createDeferredPermissionResolver,
+  evaluateToolRule,
+  type CallbackResolverOptions,
+  type PermissionPromptHandler,
+  type DeferredPermissionResolver,
+  type DeferredPermissionResolverOptions,
+} from './resolvers.js';
 export {
   MoxxyError,
   classifyHttpStatus,
@@ -145,18 +166,27 @@ export {
 } from './errors.js';
 export {
   collectProviderStream,
+  runSingleShotTurn,
   projectMessagesFromLog,
   projectMessages,
   buildSystemPromptWithSkills,
+  createStuckLoopDetector,
+  stableHash,
   type CollectedToolUse,
   type StreamResult,
   type ProjectMessagesOptions,
   type ProjectedMessages,
+  type StuckLoopDetector,
+  type StuckSignal,
 } from './mode-helpers.js';
 export { dispatchToolCall } from './tool-dispatch.js';
 
 export type { TokenBudget, CompactContext, CompactorDef } from './compactor.js';
-export { estimateContextTokens, runCompactionIfNeeded } from './compactor-helpers.js';
+export {
+  estimateContextTokens,
+  runCompactionIfNeeded,
+  isContextOverflowError,
+} from './compactor-helpers.js';
 export {
   runElisionIfNeeded,
   resolveElisionSettings,
@@ -192,6 +222,23 @@ export {
 
 export type { Skill, SkillDef, SkillFrontmatter, SkillScope, SkillSchedule } from './skill.js';
 
+export type {
+  Workflow,
+  WorkflowStep,
+  WorkflowTrigger,
+  WorkflowStepErrorMode,
+  WorkflowInputSpec,
+  WorkflowDelivery,
+  WorkflowToolRunner,
+  WorkflowLookup,
+  WorkflowEventSubtype,
+  WorkflowRunDeps,
+  WorkflowStepStatus,
+  WorkflowStepResult,
+  WorkflowRunResult,
+  WorkflowExecutorDef,
+} from './workflow.js';
+
 export type { AgentDef } from './agent.js';
 
 export type {
@@ -245,7 +292,7 @@ export type {
   ChannelSubcommandContext,
   ChannelCommandArgs,
 } from './channel.js';
-export type { EmbeddingProvider } from './embedding.js';
+export type { EmbeddingProvider, EmbedderDef } from './embedding.js';
 export { CachedEmbeddingProvider } from './embedding-cache.js';
 
 export type {
@@ -281,8 +328,10 @@ export {
   definePermission,
   defineSkill,
   defineTranscriber,
+  defineEmbedder,
   defineCommand,
   defineAgent,
+  defineWorkflowExecutor,
 } from './define.js';
 
 export {
@@ -301,4 +350,10 @@ export {
   type InstallTarget,
 } from './install-hints.js';
 
+export {
+  checkTranscriberReady,
+  pickFirstAvailableTranscriber,
+  resolveTranscriber,
+} from './voice.js';
+
 export { z } from 'zod';