@moxxy/sdk 0.32.0 → 0.34.0

package/dist/signature.js

@@ -0,0 +1,32 @@
+import { createPublicKey, verify as cryptoVerify } from 'node:crypto';
+/**
+ * Ed25519 detached-signature verification over exact bytes.
+ *
+ * Lives in the SDK rather than beside its first caller because two different
+ * things now depend on it, and one of them is policy. Policy has to bind on a
+ * machine with no plugins installed at all, so the verifier it uses cannot sit
+ * inside a plugin: a control that a user can disable by uninstalling something
+ * is not a control.
+ *
+ * Verifies over the bytes as received, never over a re-serialisation of the
+ * parsed object. Canonicalising first would let two different documents share a
+ * signature whenever the parser and the serialiser disagree about anything,
+ * which is how signature-verification bypasses usually happen.
+ *
+ * Returns false rather than throwing on a malformed key or signature: to a
+ * caller "this did not verify" and "this could not be parsed" warrant the same
+ * response, and a throw here would tempt a try/catch that swallows both into a
+ * success path.
+ */
+export function verifyEd25519(bytes, signatureB64, publicKeyPem) {
+    if (!publicKeyPem || !signatureB64)
+        return false;
+    try {
+        const key = createPublicKey(publicKeyPem);
+        return cryptoVerify(null, Buffer.from(bytes), key, Buffer.from(signatureB64, 'base64'));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=signature.js.map

package/dist/signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.js","sourceRoot":"","sources":["../src/signature.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,aAAa,CAAC;AAEtE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAiB,EACjB,YAAoB,EACpB,YAAoB;IAEpB,IAAI,CAAC,YAAY,IAAI,CAAC,YAAY;QAAE,OAAO,KAAK,CAAC;IACjD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,eAAe,CAAC,YAAY,CAAC,CAAC;QAC1C,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC1F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/tool-icon.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What a tool looks like, as a semantic name rather than a glyph.
+ *
+ * A CLOSED vocabulary on purpose. Surfaces render wildly differently: the
+ * desktop draws SVG, the TUI prints a character, a future web surface might do
+ * something else again. If this were a free string, a plugin could name an icon
+ * no surface owns and every surface would have to guess, so in practice
+ * everything would fall back and the field would be decorative. A fixed set
+ * means each surface maps it exhaustively and a plugin's choice actually
+ * survives to the screen.
+ *
+ * The names describe WHAT THE TOOL TOUCHES, not what it looks like, so a
+ * surface is free to change its artwork without every plugin becoming wrong.
+ *
+ * Adding a member is a breaking change for surfaces (their maps stop being
+ * exhaustive and stop compiling), which is the intended cost: a new icon should
+ * be a deliberate decision across surfaces, not a silent fallback to a wrench.
+ */
+export declare const TOOL_ICONS: readonly ["file", "folder", "search", "edit", "diff", "terminal", "globe", "chat", "workflow", "agent", "settings", "lock", "plug", "mic", "speaker", "smartphone", "workspace", "clipboard", "spark", "wrench"];
+export type ToolIcon = (typeof TOOL_ICONS)[number];
+export declare function isToolIcon(value: unknown): value is ToolIcon;
+//# sourceMappingURL=tool-icon.d.ts.map

package/dist/tool-icon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-icon.d.ts","sourceRoot":"","sources":["../src/tool-icon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,kNAqBb,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D"}

package/dist/tool-icon.js

@@ -0,0 +1,44 @@
+/**
+ * What a tool looks like, as a semantic name rather than a glyph.
+ *
+ * A CLOSED vocabulary on purpose. Surfaces render wildly differently: the
+ * desktop draws SVG, the TUI prints a character, a future web surface might do
+ * something else again. If this were a free string, a plugin could name an icon
+ * no surface owns and every surface would have to guess, so in practice
+ * everything would fall back and the field would be decorative. A fixed set
+ * means each surface maps it exhaustively and a plugin's choice actually
+ * survives to the screen.
+ *
+ * The names describe WHAT THE TOOL TOUCHES, not what it looks like, so a
+ * surface is free to change its artwork without every plugin becoming wrong.
+ *
+ * Adding a member is a breaking change for surfaces (their maps stop being
+ * exhaustive and stop compiling), which is the intended cost: a new icon should
+ * be a deliberate decision across surfaces, not a silent fallback to a wrench.
+ */
+export const TOOL_ICONS = [
+    'file',
+    'folder',
+    'search',
+    'edit',
+    'diff',
+    'terminal',
+    'globe',
+    'chat',
+    'workflow',
+    'agent',
+    'settings',
+    'lock',
+    'plug',
+    'mic',
+    'speaker',
+    'smartphone',
+    'workspace',
+    'clipboard',
+    'spark',
+    'wrench',
+];
+export function isToolIcon(value) {
+    return typeof value === 'string' && TOOL_ICONS.includes(value);
+}
+//# sourceMappingURL=tool-icon.js.map

package/dist/tool-icon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-icon.js","sourceRoot":"","sources":["../src/tool-icon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,MAAM;IACN,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,MAAM;IACN,UAAU;IACV,OAAO;IACP,MAAM;IACN,UAAU;IACV,OAAO;IACP,UAAU;IACV,MAAM;IACN,MAAM;IACN,KAAK;IACL,SAAS;IACT,YAAY;IACZ,WAAW;IACX,WAAW;IACX,OAAO;IACP,QAAQ;CACA,CAAC;AAIX,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,UAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5F,CAAC"}

package/dist/tool.d.ts

@@ -1,5 +1,6 @@
 import type { z } from 'zod';
 import type { EventLogReader } from './log.js';
+import type { ToolIcon } from './tool-icon.js';
 import type { PermissionRule } from './permission.js';
 import type { SessionId, ToolCallId, TurnId } from './ids.js';
 import type { SubagentSpawner } from './subagent.js';
@@ -182,6 +183,13 @@ export interface ToolDef {
     readonly handler: (input: unknown, ctx: ToolContext) => Promise<unknown> | unknown;
     /** Opt-in presentation hint. See `ToolCompactPresentation`. */
     readonly compact?: ToolCompactPresentation;
+    /**
+     * What this tool touches, so surfaces can show it. Without this a surface can
+     * only guess from the NAME, which works for the handful of built-ins it was
+     * written against and gives every plugin-contributed tool the same generic
+     * fallback. See {@link ToolIcon}.
+     */
+    readonly icon?: ToolIcon;
     /**
      * Optional capability declaration. Advisory unless the user enables
      * `@moxxy/plugin-security`, at which point the active `Isolator`

package/dist/tool.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moxxy/sdk",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Typed public surface for the moxxy framework: event types, define* factories, lifecycle hook signatures.",
   "keywords": [
     "moxxy",
@@ -67,15 +67,22 @@
     "access": "public"
   },
   "peerDependencies": {
-    "zod": "^3.24.0"
+    "zod": "^3.24.0",
+    "undici": "^6.21.0"
   },
   "devDependencies": {
     "typescript": "^5.7.3",
+    "undici": "^6.21.0",
     "vitest": "^2.1.8",
     "zod": "^3.24.0",
     "@moxxy/tsconfig": "0.0.0",
     "@moxxy/vitest-preset": "0.0.0"
   },
+  "peerDependenciesMeta": {
+    "undici": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",

package/src/audit-export.ts

@@ -0,0 +1,57 @@
+import type { AuditRecord } from './audit.js';
+import type { Principal } from './principal.js';
+
+/**
+ * Shipping the local audit trail somewhere central.
+ *
+ * Separate from `AuditSinkDef` on purpose. A sink is the WRITE path: it is
+ * handed each record as it happens. An exporter is a READER of the trail that
+ * has already been durably written, driven by a checkpoint.
+ *
+ * That split is what makes shipping survivable. A network sink has to decide,
+ * while a turn is running, what to do when the collector is down: block the
+ * turn, drop the record, or buffer it in memory and lose it on exit. An
+ * exporter has no such dilemma, because the record is already on disk in a
+ * hash-chained file. A failed export is retried from the checkpoint, and the
+ * worst case is that central visibility lags, never that the record is gone.
+ */
+export interface AuditExportResource {
+  /** Which machine. The whole point of central collection is telling them apart. */
+  readonly host: string;
+  readonly cliVersion: string;
+  /** Whoever the surface could establish was acting; absent on an unattributed host. */
+  readonly principal?: Principal;
+}
+
+export interface AuditExportBatch {
+  readonly records: ReadonlyArray<AuditRecord>;
+  readonly resource: AuditExportResource;
+}
+
+export interface AuditExportContext {
+  /** Destination, as configured. Exporter-defined; an endpoint URL for OTLP. */
+  readonly endpoint: string;
+  /** Exporter-specific settings from `audit.export`, already placeholder-resolved. */
+  readonly settings: Readonly<Record<string, unknown>>;
+  readonly signal?: AbortSignal;
+}
+
+export interface AuditExporterDef {
+  readonly name: string;
+  readonly description?: string;
+  /**
+   * Ship one batch.
+   *
+   * THE CONTRACT: resolving means the destination has DURABLY accepted these
+   * records, because the checkpoint advances on resolve and those records are
+   * never offered again. An exporter that resolves on "request sent" turns a
+   * collector-side rejection into silent data loss. When in doubt, throw:
+   * re-sending a batch is cheap and records carry a hash the collector can
+   * deduplicate on, whereas a skipped batch is unrecoverable.
+   */
+  send(batch: AuditExportBatch, ctx: AuditExportContext): Promise<void>;
+}
+
+export function defineAuditExporter(def: AuditExporterDef): AuditExporterDef {
+  return def;
+}

package/src/audit.ts

@@ -0,0 +1,137 @@
+import type { MoxxyEvent, MoxxyEventType } from './events.js';
+import type { SessionId, TurnId } from './ids.js';
+import type { Principal } from './principal.js';
+
+/**
+ * The audit trail: a tamper-evident record of what the agent did, who it acted
+ * for, and what was allowed or denied, in a form that can LEAVE the machine.
+ *
+ * Distinct from the event log, and the distinction is the whole point. The
+ * event log is the conversation: complete, replayable, local, and full of
+ * payloads nobody wants shipped to a SIEM. An audit record is the receipt:
+ * bounded, redacted, hash-chained, and self-attributing, so one line is
+ * meaningful on its own without replaying a session to interpret it.
+ *
+ * A swappable block like every other, mirroring `EventStoreDef`: core seeds a
+ * protected local floor, plugins register alternatives (syslog, OTel, S3,
+ * webhook), and the operator activates one by name.
+ */
+
+/** What kind of thing happened. Coarser than `MoxxyEventType` on purpose: an
+ *  auditor reasons about categories of action, not about the loop's internals. */
+export type AuditAction =
+  /** The security-relevant config in force, recorded once per session. Without
+   *  it a trail says what was done but not what the rules were at the time,
+   *  which is the first question asked when reviewing a past run. */
+  | 'policy'
+  | 'prompt'
+  | 'tool.request'
+  | 'tool.approved'
+  | 'tool.denied'
+  | 'tool.result'
+  | 'skill.invoked'
+  | 'skill.created'
+  | 'plugin.registered'
+  | 'plugin.unregistered'
+  | 'abort'
+  /** Token counts for one provider call. Metadata only, never content, which
+   *  is what makes cost attribution auditable without the trail carrying the
+   *  conversation. */
+  | 'usage'
+  | 'error'
+  | 'other';
+
+/**
+ * One record. Every field is either metadata or already-redacted, so the whole
+ * object is safe to forward.
+ */
+export interface AuditRecord {
+  /** Position in this sink's chain. Contiguous from 0; a gap is evidence. */
+  readonly seq: number;
+  readonly ts: number;
+  readonly sessionId: SessionId;
+  readonly turnId: TurnId;
+  readonly action: AuditAction;
+  /** The underlying event type, kept so a record can be traced back. */
+  readonly eventType: MoxxyEventType;
+  /**
+   * Who it was done for. Absent means unattributed, which is itself worth
+   * auditing: it says the surface could not establish an identity.
+   */
+  readonly actor?: Principal;
+  /** Bounded, redacted, action-specific detail. Never raw payloads. */
+  readonly detail?: Readonly<Record<string, unknown>>;
+  /** Hash of the previous record, or null for the first. */
+  readonly prevHash: string | null;
+  /** Hash over this record's own fields plus {@link prevHash}. */
+  readonly hash: string;
+}
+
+/** A record before the chain fields are computed. */
+export type UnchainedAuditRecord = Omit<AuditRecord, 'seq' | 'prevHash' | 'hash'>;
+
+export interface AuditSinkScope {
+  readonly sessionId: SessionId;
+  readonly cwd: string;
+}
+
+export interface AuditSinkSession {
+  /**
+   * Append one record.
+   *
+   * Takes an UNCHAINED record: sequencing and any tamper-evidence are the
+   * sink's own concern, because each sink has its own ordering. The local file
+   * chains by day; a syslog sink has no chain at all; a remote service assigns
+   * its own sequence. Handing every sink a pre-sealed `seq`/`hash` would be a
+   * lie for all but one of them.
+   *
+   * MUST NOT throw: a failing audit sink degrades loudly, it never takes down
+   * the turn it is recording. Report failure by returning false.
+   */
+  write(record: UnchainedAuditRecord): Promise<boolean>;
+  /** Flush anything buffered. Called on session close. */
+  close(): Promise<void>;
+}
+
+export interface AuditSinkDef {
+  readonly name: string;
+  readonly description?: string;
+  open(scope: AuditSinkScope): AuditSinkSession;
+}
+
+/** Freeze an audit-sink spec, mirroring the other `defineX` factories. */
+export function defineAuditSink(def: AuditSinkDef): AuditSinkDef {
+  return Object.freeze({ ...def });
+}
+
+/**
+ * Which event types produce an audit record, and under what category.
+ *
+ * Everything absent from this map is conversation, not audit: assistant text,
+ * reasoning, provider request/response, compaction, elision, mode iterations.
+ * They belong in the event log and would only bloat a trail an auditor has to
+ * read. Tool and permission traffic is what actually gets reviewed, so it is
+ * named precisely.
+ *
+ * An exhaustive map rather than a `default:` so adding an event type is a
+ * deliberate decision about whether it is auditable, not a silent 'other'.
+ */
+const AUDITED: Partial<Record<MoxxyEventType, AuditAction>> = {
+  user_prompt: 'prompt',
+  tool_call_requested: 'tool.request',
+  tool_call_approved: 'tool.approved',
+  tool_call_denied: 'tool.denied',
+  tool_result: 'tool.result',
+  skill_invoked: 'skill.invoked',
+  skill_created: 'skill.created',
+  plugin_registered: 'plugin.registered',
+  plugin_unregistered: 'plugin.unregistered',
+  abort: 'abort',
+  provider_response: 'usage',
+  error: 'error',
+};
+
+/** The audit category for an event, or null when it is conversation only. */
+export function auditActionOf(event: MoxxyEvent): AuditAction | null {
+  return AUDITED[event.type] ?? null;
+}

package/src/cross-process-lock.test.ts

@@ -1,11 +1,9 @@
-import { mkdtemp, rm, readdir } from 'node:fs/promises';
+import { mkdtemp, rm, readdir, utimes } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import path from 'node:path';
+import path, { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { CrossProcessFireLock } from './cross-process-lock.js';
 
-const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
-
 describe('CrossProcessFireLock', () => {
   let dir: string;
   beforeEach(async () => {
@@ -40,23 +38,34 @@ describe('CrossProcessFireLock', () => {
   });
 
   it('reclaims a stale marker once its TTL elapses (crashed holder)', async () => {
-    const lock = new CrossProcessFireLock({ dir, ttlMs: 15 });
+    const ttlMs = 1_000;
+    const lock = new CrossProcessFireLock({ dir, ttlMs });
     expect(await lock.claim('k@1')).toBe(true);
     expect(await lock.claim('k@1')).toBe(false);
-    await sleep(40);
-    // The previous holder "crashed"; the marker is now stale and reclaimable.
-    expect(await lock.claim('k@1')).toBe(true);
+    // The previous holder "crashed": advance the CLOCK past the TTL rather than
+    // sleeping, so the test asserts the staleness rule and not the accuracy of
+    // a timer on a loaded machine.
+    expect(await lock.claim('k@1', Date.now() + ttlMs * 5)).toBe(true);
   });
 
+  // Age is set on the FILES and the clock is passed in, rather than produced by
+  // sleeping. Expiry is `now - mtime > ttlMs`, so a sleep-based version races
+  // the scheduler: any pause between claiming the fresh marker and sweeping
+  // that exceeds the TTL expires it too, and a short TTL makes that pause
+  // trivial to hit on a loaded machine.
   it('sweep removes expired markers and leaves fresh ones', async () => {
-    const lock = new CrossProcessFireLock({ dir, ttlMs: 15 });
+    const ttlMs = 1_000;
+    const lock = new CrossProcessFireLock({ dir, ttlMs });
     await lock.claim('old@1');
-    await sleep(40);
     await lock.claim('fresh@1');
-    const removed = await lock.sweep();
-    expect(removed).toBe(1);
-    const remaining = await readdir(dir);
-    expect(remaining).toEqual(['fresh@1.lock']);
+
+    const now = Date.now();
+    const stale = new Date(now - ttlMs * 5);
+    await utimes(join(dir, 'old@1.lock'), stale, stale);
+    await utimes(join(dir, 'fresh@1.lock'), new Date(now), new Date(now));
+
+    expect(await lock.sweep(now)).toBe(1);
+    expect(await readdir(dir)).toEqual(['fresh@1.lock']);
   });
 
   it('sanitizes unsafe key characters into a single marker file', async () => {

package/src/define.ts

@@ -9,6 +9,7 @@ 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 { ToolIcon } from './tool-icon.js';
 import type { HostedTool, ToolCompactPresentation, ToolContext, ToolDef } from './tool.js';
 import type { ToolIsolationSpec } from './isolation.js';
 import type { TranscriberDef } from './transcriber.js';
@@ -46,6 +47,7 @@ export function defineTool<S extends z.ZodTypeAny, O = unknown>(spec: {
   permission?: PermissionRule;
   handler: (input: z.output<S>, ctx: ToolContext) => Promise<O> | O;
   compact?: ToolCompactPresentation;
+  icon?: ToolIcon;
   isolation?: ToolIsolationSpec;
 }): ToolDef {
   return Object.freeze({
@@ -58,6 +60,7 @@ export function defineTool<S extends z.ZodTypeAny, O = unknown>(spec: {
     permission: spec.permission,
     handler: spec.handler as (input: unknown, ctx: ToolContext) => Promise<unknown> | unknown,
     compact: spec.compact,
+    icon: spec.icon,
     isolation: spec.isolation,
   });
 }