@moxxy/sdk 0.33.0 → 0.34.0

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":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAClF,mFAAmF;IACnF,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,qEAAqE;IACrE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IACzD,qDAAqD;IACrD,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACzE;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,CACE,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,EAC5B,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE;QACf,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACzD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACxD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACxD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;KAC1D,CAAC;IACF;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;IACrC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IAC7B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC/D;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB;IACtC,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE;+EAC2E;IAC3E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACnF,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;CACxC"}
+{"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.33.0",
+  "version": "0.34.0",
   "description": "Typed public surface for the moxxy framework: event types, define* factories, lifecycle hook signatures.",
   "keywords": [
     "moxxy",
@@ -67,14 +67,21 @@
     "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/vitest-preset": "0.0.0",
-    "@moxxy/tsconfig": "0.0.0"
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/vitest-preset": "0.0.0"
+  },
+  "peerDependenciesMeta": {
+    "undici": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

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

package/src/egress.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  hasProxy,
+  installEgressProxy,
+  parseNoProxy,
+  readProxyEnv,
+  redactProxyUrl,
+  shouldBypassProxy,
+} from './egress.js';
+
+describe('readProxyEnv', () => {
+  it('reads uppercase and lowercase forms', () => {
+    expect(readProxyEnv({ HTTPS_PROXY: 'http://p:3128' })).toEqual({ httpsProxy: 'http://p:3128' });
+    expect(readProxyEnv({ https_proxy: 'http://p:3128' })).toEqual({ httpsProxy: 'http://p:3128' });
+  });
+
+  // Lowercase wins by convention (curl, requests, Go): a shell exporting both
+  // usually set the lowercase one deliberately and more recently.
+  it('prefers the lowercase form when both are set', () => {
+    const env = { https_proxy: 'http://lower:1', HTTPS_PROXY: 'http://upper:2' };
+    expect(readProxyEnv(env).httpsProxy).toBe('http://lower:1');
+  });
+
+  it('treats blank and whitespace values as unset', () => {
+    expect(readProxyEnv({ HTTPS_PROXY: '', HTTP_PROXY: '   ' })).toEqual({});
+  });
+
+  // A plaintext-only proxy declared via http_proxy must not silently swallow
+  // TLS traffic; https origins go direct instead of failing confusingly.
+  it('does not fall back to http_proxy for https origins', () => {
+    expect(readProxyEnv({ HTTP_PROXY: 'http://p:3128' })).toEqual({ httpProxy: 'http://p:3128' });
+  });
+});
+
+describe('parseNoProxy', () => {
+  it('splits on commas and whitespace, lowercases, and drops blanks', () => {
+    expect(parseNoProxy(' localhost, .Corp.Example  10.0.0.1 ,, ')).toEqual([
+      'localhost',
+      '.corp.example',
+      '10.0.0.1',
+    ]);
+  });
+
+  it('returns an empty list for undefined', () => {
+    expect(parseNoProxy(undefined)).toEqual([]);
+  });
+});
+
+describe('shouldBypassProxy', () => {
+  const bypass = (origin: string, rules: string): boolean =>
+    shouldBypassProxy(origin, parseNoProxy(rules));
+
+  it('bypasses everything on *', () => {
+    expect(bypass('https://api.anthropic.com', '*')).toBe(true);
+  });
+
+  it('matches an exact host on any port', () => {
+    expect(bypass('http://localhost:8080/x', 'localhost')).toBe(true);
+    expect(bypass('https://localhost', 'localhost')).toBe(true);
+    expect(bypass('https://notlocalhost', 'localhost')).toBe(false);
+  });
+
+  // A leading dot covers the apex too, matching curl. Getting this wrong sends
+  // internal traffic through the proxy, which is exactly what NO_PROXY exists
+  // to prevent.
+  it('matches subdomains and the apex for a dotted rule', () => {
+    expect(bypass('https://api.corp.example', '.corp.example')).toBe(true);
+    expect(bypass('https://corp.example', '.corp.example')).toBe(true);
+    expect(bypass('https://deep.api.corp.example', '.corp.example')).toBe(true);
+    expect(bypass('https://evilcorp.example', '.corp.example')).toBe(false);
+  });
+
+  it('treats *.domain the same as .domain', () => {
+    expect(bypass('https://api.corp.example', '*.corp.example')).toBe(true);
+  });
+
+  it('honours a port qualifier', () => {
+    expect(bypass('http://registry.internal:8081/x', 'registry.internal:8081')).toBe(true);
+    expect(bypass('http://registry.internal:9999/x', 'registry.internal:8081')).toBe(false);
+  });
+
+  it('resolves the implicit port from the scheme', () => {
+    expect(bypass('https://svc.internal/x', 'svc.internal:443')).toBe(true);
+    expect(bypass('http://svc.internal/x', 'svc.internal:80')).toBe(true);
+    expect(bypass('https://svc.internal/x', 'svc.internal:80')).toBe(false);
+  });
+
+  // `::1` must not be read as host ":" on port "1".
+  it('does not mistake an IPv6 literal for a host:port rule', () => {
+    expect(bypass('http://[::1]:7000/x', '::1')).toBe(true);
+  });
+
+  it('is case-insensitive on the host', () => {
+    expect(bypass('https://API.Corp.Example', '.corp.example')).toBe(true);
+  });
+
+  it('never bypasses with no rules, or on an unparseable origin', () => {
+    expect(bypass('https://api.anthropic.com', '')).toBe(false);
+    expect(shouldBypassProxy('not a url', ['*.corp.example'])).toBe(false);
+  });
+});
+
+describe('redactProxyUrl', () => {
+  it('masks embedded credentials', () => {
+    expect(redactProxyUrl('http://alice:hunter2@proxy.corp:3128')).toBe('http://***:***@proxy.corp:3128/');
+  });
+
+  it('leaves a credential-free url intact', () => {
+    expect(redactProxyUrl('http://proxy.corp:3128')).toBe('http://proxy.corp:3128/');
+  });
+
+  // Never echo something unparseable: it might be a secret pasted by mistake.
+  it('reveals nothing for an unparseable value', () => {
+    expect(redactProxyUrl('hunter2')).toBe('<invalid proxy url>');
+  });
+});
+
+describe('installEgressProxy', () => {
+  /**
+   * Stand-in for undici. Each agent reports its own label through the dispatch
+   * handler, so `routeOf` observes WHICH agent the router picked for an origin,
+   * which is the whole contract worth testing here.
+   */
+  const fakeUndici = () => {
+    let installed: { dispatch: (o: { origin?: string }, h: unknown) => boolean } | null = null;
+    const agent = (label: string) => ({
+      dispatch: (_o: unknown, h: { onPick?: (l: string) => void }) => {
+        h.onPick?.(label);
+        return true;
+      },
+      close: async () => {},
+      destroy: async () => {},
+    });
+    return {
+      routeOf: (origin: string): string => {
+        let picked = '';
+        installed!.dispatch({ origin }, {
+          onPick: (l: string) => {
+            picked = l;
+          },
+        });
+        return picked;
+      },
+      module: {
+        Agent: function Agent() {
+          return agent('direct');
+        } as never,
+        ProxyAgent: function ProxyAgent(o: { uri: string }) {
+          return agent(`proxy:${o.uri}`);
+        } as never,
+        setGlobalDispatcher: (d: never) => {
+          installed = d;
+        },
+      },
+    };
+  };
+
+  it('no-ops when no proxy is configured', async () => {
+    const status = await installEgressProxy({});
+    expect(status).toEqual({ enabled: false, reason: 'no proxy configured' });
+  });
+
+  it('reports and skips an unparseable proxy url instead of throwing', async () => {
+    const warn = vi.fn();
+    const status = await installEgressProxy({ httpsProxy: 'not a url' }, { warn });
+    expect(status.enabled).toBe(false);
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('https_proxy is not a valid URL'));
+  });
+
+  // A proxy is configured but the dependency is missing: degrade to direct with
+  // a loud warning rather than a failed boot.
+  it('warns and degrades when undici cannot be loaded', async () => {
+    const warn = vi.fn();
+    const status = await installEgressProxy(
+      { httpsProxy: 'http://p:3128' },
+      { warn, loadUndici: () => Promise.reject(new Error('not installed')) },
+    );
+    expect(status.enabled).toBe(false);
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('`undici` package is unavailable'));
+  });
+
+  it('installs a dispatcher and redacts credentials in the reported status', async () => {
+    const u = fakeUndici();
+    const status = await installEgressProxy(
+      { httpsProxy: 'http://bob:secret@p:3128', noProxy: 'localhost' },
+      { loadUndici: async () => u.module as never },
+    );
+    expect(status.enabled).toBe(true);
+    expect(status.httpsProxy).toBe('http://***:***@p:3128/');
+    expect(status.httpsProxy).not.toContain('secret');
+    expect(status.noProxy).toEqual(['localhost']);
+  });
+
+  it('routes https through the proxy and bypassed hosts direct', async () => {
+    const u = fakeUndici();
+    await installEgressProxy(
+      { httpsProxy: 'http://p:3128', noProxy: '.corp.example' },
+      { loadUndici: async () => u.module as never },
+    );
+    expect(u.routeOf('https://api.anthropic.com')).toBe('proxy:http://p:3128');
+    expect(u.routeOf('https://git.corp.example')).toBe('direct');
+  });
+
+  // Only http_proxy set: https origins must go direct, not through it.
+  it('sends https direct when only an http proxy is configured', async () => {
+    const u = fakeUndici();
+    await installEgressProxy(
+      { httpProxy: 'http://p:3128' },
+      { loadUndici: async () => u.module as never },
+    );
+    expect(u.routeOf('http://example.com')).toBe('proxy:http://p:3128');
+    expect(u.routeOf('https://example.com')).toBe('direct');
+  });
+});
+
+describe('hasProxy', () => {
+  it('is true when either proxy is set', () => {
+    expect(hasProxy({})).toBe(false);
+    expect(hasProxy({ noProxy: 'localhost' })).toBe(false);
+    expect(hasProxy({ httpProxy: 'http://p' })).toBe(true);
+    expect(hasProxy({ httpsProxy: 'http://p' })).toBe(true);
+  });
+});
+
+describe('shouldBypassProxy IPv6 port qualifiers', () => {
+  const bypass = (origin: string, rules: string): boolean =>
+    shouldBypassProxy(origin, parseNoProxy(rules));
+
+  // A port on an IPv6 address requires brackets, exactly as in a URL.
+  it('honours a bracketed IPv6 host:port rule', () => {
+    expect(bypass('http://[::1]:7000/x', '[::1]:7000')).toBe(true);
+    expect(bypass('http://[::1]:9999/x', '[::1]:7000')).toBe(false);
+  });
+
+  it('matches a bracketed IPv6 rule on any port', () => {
+    expect(bypass('http://[::1]:7000/x', '[::1]')).toBe(true);
+  });
+});