@moxxy/sdk 0.33.0 → 0.34.0

package/src/plugin.ts

@@ -17,6 +17,9 @@ import type { ViewRendererDef } from './view-renderer.js';
 import type { TunnelProviderDef } from './tunnel.js';
 import type { WorkflowExecutorDef } from './workflow.js';
 import type { EventStoreDef } from './event-store.js';
+import type { AuditSinkDef } from './audit.js';
+import type { AuditExporterDef } from './audit-export.js';
+import type { SecretProviderDef } from './secret-provider.js';
 import type { ReflectorDef } from './reflector.js';
 
 export type PluginKind = 'tools' | 'provider' | 'mode' | 'compactor' | 'cache-strategy' | 'view-renderer' | 'tunnel-provider' | 'mcp' | 'cli' | 'channel' | 'surface' | 'hooks' | 'agent' | 'command' | 'transcriber' | 'synthesizer' | 'embedder' | 'isolator' | 'workflow-executor' | 'event-store' | 'reflector';
@@ -54,6 +57,13 @@ export interface PluginSpec {
    * boundary, since the store sees every event). See {@link EventStoreDef}.
    */
   readonly eventStores?: ReadonlyArray<EventStoreDef>;
+  /** Audit-trail sinks (syslog, OTel, S3, webhook). Registered alongside the
+   *  protected local floor; never auto-activated, see registry-kinds. */
+  readonly auditSinks?: ReadonlyArray<AuditSinkDef>;
+  readonly auditExporters?: ReadonlyArray<AuditExporterDef>;
+  /** External secret stores (Vault, AWS/Azure, 1Password). Registered
+   *  alongside the vault floor; never auto-activated. */
+  readonly secretProviders?: ReadonlyArray<SecretProviderDef>;
   /**
    * Reflector backends — the learning-loop block that watches a finished turn
    * and *proposes* memory/skill improvements without silently writing. One

package/src/principal-os.ts

@@ -0,0 +1,48 @@
+import { hostname, userInfo } from 'node:os';
+import type { Principal } from './principal.js';
+
+/**
+ * The local OS account, as a {@link Principal}.
+ *
+ * This is the FLOOR identity: it is what the TUI and other local surfaces
+ * attribute to when no stronger issuer (a channel token, an OIDC assertion) is
+ * available. Its trust is exactly the trust of local account separation, which
+ * is why {@link Principal.issuer} says `os` rather than pretending to more.
+ *
+ * The id is `user@host` because a bare username is ambiguous the moment
+ * transcripts from several machines reach one audit sink.
+ */
+export function resolveOsPrincipal(): Principal {
+  const user = safeUsername();
+  const host = safeHostname();
+  return {
+    id: host ? `${user}@${host}` : user,
+    kind: 'human',
+    issuer: 'os',
+    displayName: user,
+  };
+}
+
+/**
+ * `userInfo()` throws when the uid has no passwd entry, which happens in
+ * distroless containers and some CI images. An unattributed session is worse
+ * than a coarse one, so fall back rather than fail.
+ */
+function safeUsername(): string {
+  try {
+    const name = userInfo().username.trim();
+    if (name.length > 0) return name;
+  } catch {
+    /* fall through */
+  }
+  const fromEnv = (process.env.USER ?? process.env.USERNAME ?? '').trim();
+  return fromEnv.length > 0 ? fromEnv : 'unknown';
+}
+
+function safeHostname(): string {
+  try {
+    return hostname().trim();
+  } catch {
+    return '';
+  }
+}

package/src/principal.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { formatPrincipal, samePrincipal, type Principal } from './principal.js';
+import { resolveOsPrincipal } from './principal-os.js';
+
+const alice: Principal = { id: 'alice', kind: 'human', issuer: 'os' };
+
+describe('samePrincipal', () => {
+  // An id is only unique inside its issuer's namespace. Collapsing that would
+  // let a weakly-issued identity impersonate a strongly-issued one of the same
+  // name, which is the whole reason `issuer` exists.
+  it('requires the issuer to match, not just the id', () => {
+    expect(samePrincipal(alice, { ...alice, issuer: 'oidc' })).toBe(false);
+    expect(samePrincipal(alice, { ...alice, displayName: 'Alice A.' })).toBe(true);
+  });
+
+  it('treats undefined as unattributed, not as a wildcard', () => {
+    expect(samePrincipal(undefined, alice)).toBe(false);
+    expect(samePrincipal(alice, undefined)).toBe(false);
+    expect(samePrincipal(undefined, undefined)).toBe(true);
+  });
+});
+
+describe('formatPrincipal', () => {
+  it('renders issuer:id, never the display name', () => {
+    expect(formatPrincipal({ ...alice, displayName: 'Alice A.' })).toBe('os:alice');
+  });
+
+  it('names the absent case explicitly', () => {
+    expect(formatPrincipal(undefined)).toBe('unattributed');
+  });
+});
+
+describe('resolveOsPrincipal', () => {
+  it('issues a human principal scoped to the host', () => {
+    const p = resolveOsPrincipal();
+    expect(p.kind).toBe('human');
+    expect(p.issuer).toBe('os');
+    expect(p.id.length).toBeGreaterThan(0);
+    expect(p.displayName).toBeTruthy();
+  });
+
+  // A bare username collides the moment transcripts from several machines land
+  // in one audit sink.
+  it('qualifies the id with the hostname', () => {
+    expect(resolveOsPrincipal().id).toContain('@');
+  });
+});

package/src/principal.ts

@@ -0,0 +1,60 @@
+/**
+ * Who an action was taken on behalf of.
+ *
+ * Until this existed the event log recorded `source` (a CATEGORY: user, model,
+ * tool, plugin, system, compactor) but never a subject, so a transcript proved
+ * that a machine did something, not that a person did. That makes audit,
+ * role-based policy, and cost attribution impossible to build on top, and all
+ * three are table stakes for a shared or managed deployment.
+ *
+ * A `Principal` is deliberately small and provider-neutral: the identity blocks
+ * that will issue it (OS user, channel bearer token, OAuth/OIDC subject, a
+ * GitHub App installation) agree on this shape and nothing more.
+ */
+export interface Principal {
+  /**
+   * Stable identifier within {@link issuer}'s namespace. Only meaningful when
+   * paired with the issuer: `alice` from `os` and `alice` from `oidc` are not
+   * the same subject, so consumers comparing identities must compare both.
+   */
+  readonly id: string;
+  /**
+   * `human` when a person is behind the action, `service` for an unattended
+   * runner (a schedule, a webhook, a CI job). The distinction matters to policy:
+   * "a human approved this" is a different claim from "a daemon did it".
+   */
+  readonly kind: 'human' | 'service';
+  /**
+   * What vouched for the identity: `os`, `channel-token`, `oauth`, or the name
+   * of the plugin that resolved it. Records HOW MUCH the identity is worth. An
+   * `os` principal is only as trustworthy as local account separation; an
+   * `oidc` one carries a verified assertion.
+   */
+  readonly issuer: string;
+  /** Human-readable label for surfaces. Never used for comparison. */
+  readonly displayName?: string;
+  /**
+   * Additional verified attributes (email, groups, tenant). Kept flat and
+   * stringly-typed so it survives JSON round-trips through the event log and
+   * the runner wire protocol without a schema per issuer.
+   */
+  readonly claims?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Whether two principals denote the same subject. Compares issuer AND id: an id
+ * is only unique inside its issuer's namespace (see {@link Principal.id}).
+ */
+export function samePrincipal(a: Principal | undefined, b: Principal | undefined): boolean {
+  if (!a || !b) return a === b;
+  return a.issuer === b.issuer && a.id === b.id;
+}
+
+/**
+ * Compact `issuer:id` label for logs and status lines. Deliberately NOT the
+ * display name: an audit line has to be unambiguous, and display names are
+ * neither unique nor stable.
+ */
+export function formatPrincipal(principal: Principal | undefined): string {
+  return principal ? `${principal.issuer}:${principal.id}` : 'unattributed';
+}

package/src/redact.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import { isSecretKey, redactSecretText, redactSecrets } from './redact.js';
+
+describe('isSecretKey', () => {
+  it('recognises the common secret-bearing field names', () => {
+    for (const key of ['apiKey', 'api_key', 'SECRET', 'authToken', 'privateKey', 'Authorization']) {
+      expect(isSecretKey(key)).toBe(true);
+    }
+  });
+
+  it('does not flag ordinary fields', () => {
+    for (const key of ['command', 'path', 'name', 'monkey']) expect(isSecretKey(key)).toBe(false);
+  });
+});
+
+describe('redactSecretText', () => {
+  // The motivating case: the carrier field is `command`, so key-name redaction
+  // alone prints the token verbatim.
+  it('masks a bearer token inside a shell command', () => {
+    const out = redactSecretText('curl -H "Authorization: Bearer sk-ant-api03-XYZ123456789" https://api');
+    expect(out).not.toContain('XYZ123456789');
+    expect(out).toContain('[redacted]');
+    // The attempt itself must stay visible: an auditor needs to see a header
+    // was sent, not just that something was hidden.
+    expect(out).toContain('curl');
+    expect(out.toLowerCase()).toContain('authorization');
+  });
+
+  it('masks vendor key formats wherever they appear', () => {
+    const cases: ReadonlyArray<[string, string]> = [
+      ['sk-ant-api03-ABCDEFGHIJKLMNOP', 'ABCDEFGHIJKLMNOP'],
+      ['ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ012345', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'],
+      ['xoxb-1234567890-ABCDEFGH', 'ABCDEFGH'],
+      ['AKIAIOSFODNN7EXAMPLE', 'IOSFODNN7EXAMPLE'],
+      ['AIzaSyA1234567890abcdefghijklmnop', 'SyA1234567890abcdefghijklmnop'],
+    ];
+    for (const [input, secret] of cases) {
+      expect(redactSecretText(`value=${input}`)).not.toContain(secret);
+    }
+  });
+
+  it('masks a JWT', () => {
+    const jwt = 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NX0.SflKxwRJSMeKKF2QT4fwpMeJf36P';
+    expect(redactSecretText(`token ${jwt}`)).toContain('[redacted-jwt]');
+  });
+
+  it('masks credentials embedded in a URL', () => {
+    const out = redactSecretText('https://alice:hunter2@proxy.corp:3128/path');
+    expect(out).not.toContain('hunter2');
+    expect(out).toContain('proxy.corp');
+  });
+
+  it('masks KEY=value style assignments', () => {
+    const out = redactSecretText('export GITHUB_TOKEN=abcdef123456 && run');
+    expect(out).not.toContain('abcdef123456');
+    expect(out).toContain('GITHUB_TOKEN');
+  });
+
+  it('leaves ordinary text alone', () => {
+    const text = 'ls -la /home/alice && grep -r "monkey" src/';
+    expect(redactSecretText(text)).toBe(text);
+  });
+});
+
+describe('redactSecrets', () => {
+  it('drops the value of a secret-named field entirely', () => {
+    expect(redactSecrets({ apiKey: 'sk-whatever' })).toEqual({ apiKey: '[redacted]' });
+  });
+
+  it('scans ordinary string fields for secret shapes', () => {
+    const out = redactSecrets({ command: 'curl -H "Authorization: Bearer sk-ant-ABCDEFGH12345678"' });
+    expect(JSON.stringify(out)).not.toContain('ABCDEFGH12345678');
+  });
+
+  it('walks arrays and nested objects', () => {
+    const out = redactSecrets({ steps: [{ env: { TOKEN: 'ghp_ABCDEFGHIJKLMNOPQRSTUV' } }] });
+    expect(JSON.stringify(out)).not.toContain('ABCDEFGHIJKLMNOPQRSTUV');
+  });
+
+  it('bounds the walk so a pathological input cannot blow the stack', () => {
+    let deep: Record<string, unknown> = { apiKey: 'sk-deep' };
+    for (let i = 0; i < 500; i++) deep = { nested: deep };
+    expect(() => redactSecrets(deep)).not.toThrow();
+  });
+
+  it('passes non-objects through unchanged', () => {
+    expect(redactSecrets(42)).toBe(42);
+    expect(redactSecrets(null)).toBe(null);
+    expect(redactSecrets(undefined)).toBe(undefined);
+  });
+});

package/src/redact.ts

@@ -0,0 +1,91 @@
+/**
+ * Secret redaction for anything that leaves the process: an audit record, a
+ * terminal prompt, a support paste.
+ *
+ * Two independent passes, because they catch different things and either alone
+ * leaves a real hole:
+ *
+ *   - by KEY NAME, for `{ apiKey: 'sk-…' }`, where the value is opaque.
+ *   - by VALUE SHAPE, for a secret embedded in an ordinary-looking field. The
+ *     motivating case is a Bash tool call: its `command` is not a secret-named
+ *     key, so a key-name pass alone prints
+ *     `curl -H "Authorization: Bearer sk-ant-…"` verbatim.
+ *
+ * Deliberately NOT a guarantee. A redactor that claims completeness invites
+ * treating redacted output as safe to publish; treat it as reducing accidental
+ * exposure, not as sanitisation.
+ */
+
+/** Field names whose VALUES are secret material regardless of shape. */
+const SECRET_KEY =
+  /(?:api[_-]?key|secret|token|password|passwd|passphrase|authorization|auth[_-]?token|bearer|credential|private[_-]?key|access[_-]?key)/i;
+
+/**
+ * Value shapes that are secrets wherever they appear. Ordered vendor prefixes
+ * first (precise, no false positives) then generic bearer/assignment forms.
+ *
+ * Each pattern keeps any leading context in a capture group so the replacement
+ * can preserve it: masking `Authorization: Bearer X` down to just `[redacted]`
+ * would lose the fact that a header was there at all, which matters when the
+ * point is auditing what was attempted.
+ */
+const SECRET_VALUE_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
+  // Vendor-issued key formats.
+  [/\b(sk-ant-)[A-Za-z0-9_-]{8,}/g, '$1[redacted]'],
+  [/\b(sk-)[A-Za-z0-9_-]{16,}/g, '$1[redacted]'],
+  [/\b(gh[pousr]_)[A-Za-z0-9]{16,}/g, '$1[redacted]'],
+  [/\b(xox[baprs]-)[A-Za-z0-9-]{8,}/g, '$1[redacted]'],
+  [/\b(AKIA)[0-9A-Z]{12,}/g, '$1[redacted]'],
+  [/\b(AIza)[A-Za-z0-9_-]{20,}/g, '$1[redacted]'],
+  // JWTs: three base64url segments.
+  [/\b(ey[A-Za-z0-9_-]{8,})\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, 'eyJ[redacted-jwt]'],
+  // `Authorization: Bearer <anything>` in a header or a shell command.
+  [/\b(authorization\s*[:=]\s*(?:bearer|basic|token)\s+)\S+/gi, '$1[redacted]'],
+  [/\b(bearer\s+)[A-Za-z0-9._~+/=-]{12,}/gi, '$1[redacted]'],
+  // `FOO_TOKEN=value` / `--api-key value` style assignments.
+  [
+    /\b([A-Za-z0-9_-]*(?:key|token|secret|password|passwd)[A-Za-z0-9_-]*\s*[:=]\s*)(?!\s)["']?[^\s"'&;|]{6,}["']?/gi,
+    '$1[redacted]',
+  ],
+  // Credentials embedded in a URL.
+  [/\b([a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:)[^\s@]+(@)/gi, '$1[redacted]$2'],
+];
+
+export const REDACTED_PLACEHOLDER = '[redacted]';
+
+/** True when a field name reads as secret-bearing. */
+export function isSecretKey(key: string): boolean {
+  return SECRET_KEY.test(key);
+}
+
+/**
+ * Mask secret-shaped substrings inside a free-text value. This is the pass that
+ * covers shell commands, URLs, and headers, where the carrier field has an
+ * innocuous name.
+ */
+export function redactSecretText(text: string): string {
+  let out = text;
+  for (const [pattern, replacement] of SECRET_VALUE_PATTERNS) {
+    out = out.replace(pattern, replacement);
+  }
+  return out;
+}
+
+/**
+ * Redact a structured value: secret-named fields lose their value entirely,
+ * every other string is scanned for secret-shaped content.
+ *
+ * `maxDepth` bounds the walk so a pathologically nested input cannot blow the
+ * stack; anything deeper is returned unredacted, which is why callers that
+ * accept untrusted shapes should also cap size before display.
+ */
+export function redactSecrets(value: unknown, maxDepth = 6, depth = 0): unknown {
+  if (typeof value === 'string') return redactSecretText(value);
+  if (depth >= maxDepth || value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map((v) => redactSecrets(v, maxDepth, depth + 1));
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    out[k] = SECRET_KEY.test(k) ? REDACTED_PLACEHOLDER : redactSecrets(v, maxDepth, depth + 1);
+  }
+  return out;
+}

package/src/secret-provider.ts

@@ -0,0 +1,84 @@
+/**
+ * Where a named secret comes from: a swappable block, like every other.
+ *
+ * The built-in vault (AES-256-GCM under `~/.moxxy/vault.json`, unlocked via the
+ * OS keychain) is a good design for one machine and unusable for a fleet: there
+ * is no central issuance, no rotation, and no way to revoke a single
+ * workstation. Every organisation already runs something that does those three
+ * things, so the answer is to let them plug it in rather than to reimplement it.
+ *
+ * Deliberately ONE block rather than two. A host-scoped credential (a token for
+ * an internal registry or a GitHub Enterprise host) is a named secret with a
+ * naming convention on top; splitting it into a second `CredentialProvider`
+ * registry would leave two overlapping abstractions to keep in sync for no
+ * gain.
+ */
+
+export interface SecretProviderScope {
+  readonly cwd: string;
+}
+
+export interface SecretProviderSession {
+  /**
+   * Resolve a secret by name, or null when this provider does not hold it.
+   *
+   * Returning null rather than throwing is what makes providers composable: the
+   * host tries the active provider and falls back to the local vault, so
+   * adopting an external store does not require migrating every secret on day
+   * one.
+   *
+   * MUST NOT throw for an ordinary miss. A genuine failure (the store is
+   * unreachable, the token expired) SHOULD throw, because silently reporting
+   * "no such secret" for an outage would send the caller down a
+   * missing-credential path and hide the real cause.
+   */
+  get(name: string): Promise<string | null>;
+  close(): Promise<void>;
+}
+
+export interface SecretProviderDef {
+  readonly name: string;
+  readonly description?: string;
+  open(scope: SecretProviderScope): SecretProviderSession;
+}
+
+/** Freeze a secret-provider spec, mirroring the other `defineX` factories. */
+export function defineSecretProvider(def: SecretProviderDef): SecretProviderDef {
+  return Object.freeze({ ...def });
+}
+
+/**
+ * The canonical secret name holding a credential for `host`.
+ *
+ * A host credential is a named secret plus a convention, which is exactly why
+ * there is no separate `CredentialProvider` registry: whatever store an
+ * organisation already plugged in for secrets serves these too.
+ *
+ * `github.example.com` becomes `MOXXY_CREDENTIAL_GITHUB_EXAMPLE_COM`. The
+ * derivation mirrors the provider-key convention (upper-snake, non-alphanumerics
+ * to `_`) so an operator who has seen one can predict the other, and a port is
+ * dropped because a credential belongs to the host, not to a socket.
+ *
+ * Accepts a bare host or a full URL; anything unparseable yields null rather
+ * than a name derived from garbage, so a caller cannot accidentally look up a
+ * secret keyed on a typo.
+ */
+export function hostCredentialName(hostOrUrl: string): string | null {
+  const raw = hostOrUrl.trim();
+  if (raw.length === 0) return null;
+  let host = raw;
+  if (raw.includes('://')) {
+    try {
+      host = new URL(raw).hostname;
+    } catch {
+      return null;
+    }
+  } else {
+    // Strip a port or a path if the caller passed `host:443/x`.
+    host = raw.split('/')[0]!.split(':')[0]!;
+  }
+  host = host.replace(/^\[|\]$/g, '').trim();
+  if (host.length === 0 || /\s/.test(host)) return null;
+  const slug = host.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+  return slug.length > 0 ? `MOXXY_CREDENTIAL_${slug}` : null;
+}

package/src/server.ts

@@ -20,7 +20,24 @@ export {
   writeFileAtomicSync,
   moxxyHome,
   moxxyPath,
+  ensurePrivateDir,
+  ensurePrivateFile,
+  pruneStaleTempFiles,
+  PRIVATE_DIR_MODE,
+  PRIVATE_FILE_MODE,
 } from './fs-utils.js';
+// The local OS account as a Principal (node:os). The type and its pure helpers
+// ride the main barrel.
+export { resolveOsPrincipal } from './principal-os.js';
+// Outbound proxy support for global `fetch` (dynamic `undici` import). Node-only.
+export {
+  installEgressProxy,
+  readProxyEnv,
+  parseNoProxy,
+  shouldBypassProxy,
+  redactProxyUrl,
+  hasProxy,
+} from './egress.js';
 // Cross-process "fire exactly once" lock (node:fs). Value lives here; its
 // options type is re-exported from the main barrel like other erased types.
 export { CrossProcessFireLock } from './cross-process-lock.js';

package/src/session-like.ts

@@ -6,6 +6,7 @@ import type { ApprovalResolver, ModeBadge } from './mode.js';
 import type { PermissionResolver } from './permission.js';
 import type { ModelDescriptor, ProviderKeyValidation } from './provider.js';
 import type { PluginSetupSpec } from './schemas.js';
+import type { ToolIcon } from './tool-icon.js';
 import type { ToolCompactPresentation } from './tool.js';
 
 /**
@@ -80,6 +81,8 @@ export interface ToolInfo {
   readonly description: string;
   /** Compact presentation hint (plain data - crosses the wire intact). */
   readonly compact?: ToolCompactPresentation;
+  /** Declared icon, so a surface renders the tool's own choice, not a guess. */
+  readonly icon?: ToolIcon;
 }
 
 /** Serializable skill metadata. */

package/src/signature.ts

@@ -0,0 +1,34 @@
+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: Uint8Array,
+  signatureB64: string,
+  publicKeyPem: string,
+): boolean {
+  if (!publicKeyPem || !signatureB64) return false;
+  try {
+    const key = createPublicKey(publicKeyPem);
+    return cryptoVerify(null, Buffer.from(bytes), key, Buffer.from(signatureB64, 'base64'));
+  } catch {
+    return false;
+  }
+}

package/src/tool-icon.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { TOOL_ICONS, isToolIcon } from './tool-icon.js';
+import { defineTool } from './define.js';
+import { z } from 'zod';
+
+describe('tool icons', () => {
+  it('is a closed vocabulary, so a surface can map it exhaustively', () => {
+    expect(isToolIcon('terminal')).toBe(true);
+    // The whole reason the field is not a free string: a name no surface owns
+    // would render as nothing anywhere.
+    expect(isToolIcon('sparkles-v2')).toBe(false);
+    expect(isToolIcon('')).toBe(false);
+    expect(isToolIcon(undefined)).toBe(false);
+  });
+
+  it('has no duplicates, which would make a surface map ambiguous', () => {
+    expect(new Set(TOOL_ICONS).size).toBe(TOOL_ICONS.length);
+  });
+
+  it('always offers a neutral choice for a tool that fits nothing else', () => {
+    expect(TOOL_ICONS).toContain('wrench');
+  });
+
+  it('carries a declared icon through defineTool onto the def', () => {
+    const tool = defineTool({
+      name: 'thing',
+      description: 'does a thing',
+      icon: 'workflow',
+      inputSchema: z.object({}),
+      handler: () => undefined,
+    });
+
+    expect(tool.icon).toBe('workflow');
+  });
+
+  it('leaves icon undefined when a tool does not declare one', () => {
+    const tool = defineTool({
+      name: 'thing',
+      description: 'does a thing',
+      inputSchema: z.object({}),
+      handler: () => undefined,
+    });
+
+    expect(tool.icon).toBeUndefined();
+  });
+});

package/src/tool-icon.ts

@@ -0,0 +1,46 @@
+/**
+ * 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',
+] as const;
+
+export type ToolIcon = (typeof TOOL_ICONS)[number];
+
+export function isToolIcon(value: unknown): value is ToolIcon {
+  return typeof value === 'string' && (TOOL_ICONS as ReadonlyArray<string>).includes(value);
+}

package/src/tool.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';
@@ -191,6 +192,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`