@moxxy/sdk 0.33.0 → 0.34.0

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <a href="https://moxxy.ai">
-    <img src="https://moxxy.ai/moxxy-head-256.png" alt="moxxy" width="128" />
+    <img src="https://raw.githubusercontent.com/moxxy-ai/moxxy/main/assets/brand/png/moxxy-mark-256.png" alt="moxxy" width="128" />
   </a>
 </p>
 

package/dist/audit-export.d.ts

@@ -0,0 +1,51 @@
+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 declare function defineAuditExporter(def: AuditExporterDef): AuditExporterDef;
+//# sourceMappingURL=audit-export.d.ts.map

package/dist/audit-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-export.d.ts","sourceRoot":"","sources":["../src/audit-export.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;CACxC;AAED,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;OASG;IACH,IAAI,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,gBAAgB,GAAG,gBAAgB,CAE3E"}

package/dist/audit-export.js

@@ -0,0 +1,4 @@
+export function defineAuditExporter(def) {
+    return def;
+}
+//# sourceMappingURL=audit-export.js.map

package/dist/audit-export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-export.js","sourceRoot":"","sources":["../src/audit-export.ts"],"names":[],"mappings":"AAsDA,MAAM,UAAU,mBAAmB,CAAC,GAAqB;IACvD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/audit.d.ts

@@ -0,0 +1,86 @@
+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 declare function defineAuditSink(def: AuditSinkDef): AuditSinkDef;
+/** The audit category for an event, or null when it is conversation only. */
+export declare function auditActionOf(event: MoxxyEvent): AuditAction | null;
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AAEH;kFACkF;AAClF,MAAM,MAAM,WAAW;AACrB;;mEAEmE;AACjE,QAAQ,GACR,QAAQ,GACR,cAAc,GACd,eAAe,GACf,aAAa,GACb,aAAa,GACb,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,qBAAqB,GACrB,OAAO;AACT;;oBAEoB;GAClB,OAAO,GACP,OAAO,GACP,OAAO,CAAC;AAEZ;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,qDAAqD;AACrD,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,UAAU,GAAG,MAAM,CAAC,CAAC;AAElF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtD,wDAAwD;IACxD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB,CAAC;CAC/C;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAE/D;AA6BD,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CAEnE"}

package/dist/audit.js

@@ -0,0 +1,35 @@
+/** Freeze an audit-sink spec, mirroring the other `defineX` factories. */
+export function defineAuditSink(def) {
+    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 = {
+    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) {
+    return AUDITED[event.type] ?? null;
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAqGA,0EAA0E;AAC1E,MAAM,UAAU,eAAe,CAAC,GAAiB;IAC/C,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,GAAiD;IAC5D,WAAW,EAAE,QAAQ;IACrB,mBAAmB,EAAE,cAAc;IACnC,kBAAkB,EAAE,eAAe;IACnC,gBAAgB,EAAE,aAAa;IAC/B,WAAW,EAAE,aAAa;IAC1B,aAAa,EAAE,eAAe;IAC9B,aAAa,EAAE,eAAe;IAC9B,iBAAiB,EAAE,mBAAmB;IACtC,mBAAmB,EAAE,qBAAqB;IAC1C,KAAK,EAAE,OAAO;IACd,iBAAiB,EAAE,OAAO;IAC1B,KAAK,EAAE,OAAO;CACf,CAAC;AAEF,6EAA6E;AAC7E,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AACrC,CAAC"}

package/dist/define.d.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';
@@ -35,6 +36,7 @@ export declare 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;
 export declare function defineProvider(spec: ProviderDef): ProviderDef;

package/dist/define.d.ts.map

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

package/dist/define.js

@@ -26,6 +26,7 @@ export function defineTool(spec) {
         permission: spec.permission,
         handler: spec.handler,
         compact: spec.compact,
+        icon: spec.icon,
         isolation: spec.isolation,
     });
 }

package/dist/define.js.map

@@ -1 +1 @@
-{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAoBA,MAAM,UAAU,YAAY,CAAC,IAAgB;IAC3C,mEAAmE;IACnE,2EAA2E;IAC3E,sBAAsB;IACtB,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,IAAI;QACP,OAAO,EAAE,QAAiB;QAC1B,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,OAAO;KACjC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAsC,IAW/D;IACC,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,OAAO,EAAE,IAAI,CAAC,OAA2E;QACzF,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAC;AACL,CAAC;AAED,wEAAwE;AACxE,sEAAsE;AACtE,6DAA6D;AAC7D,+DAA+D;AAE/D,MAAM,UAAU,cAAc,CAAC,IAAiB;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAkB;IAChD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAsB;IACxD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAqB;IACtD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAAuB;IAC1D,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,IAA4B;IAE5B,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAoB;IACnD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAqD;IAC/E,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAoB;IACpD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAoB;IACpD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAiB;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAgB;IAC5C,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAc;IACxC,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,IAAyB;IAC9D,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC"}
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAqBA,MAAM,UAAU,YAAY,CAAC,IAAgB;IAC3C,mEAAmE;IACnE,2EAA2E;IAC3E,sBAAsB;IACtB,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,IAAI;QACP,OAAO,EAAE,QAAiB;QAC1B,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,OAAO;KACjC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAsC,IAY/D;IACC,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,eAAe,EAAE,IAAI,CAAC,eAAe;QACrC,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,OAAO,EAAE,IAAI,CAAC,OAA2E;QACzF,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAC;AACL,CAAC;AAED,wEAAwE;AACxE,sEAAsE;AACtE,6DAA6D;AAC7D,+DAA+D;AAE/D,MAAM,UAAU,cAAc,CAAC,IAAiB;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAkB;IAChD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAsB;IACxD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAqB;IACtD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAAuB;IAC1D,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,IAA4B;IAE5B,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAoB;IACnD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAqD;IAC/E,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAoB;IACpD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAoB;IACpD,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAiB;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAgB;IAC5C,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAc;IACxC,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,IAAyB;IAC9D,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/dist/egress.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Outbound HTTP egress: corporate proxy support for everything moxxy fetches.
+ *
+ * Node's global `fetch` ignores `HTTPS_PROXY` entirely, and every provider
+ * reaches its API through it (`@anthropic-ai/sdk`, `openai`, and the plain
+ * `fetch` calls in tools). On a network that requires an outbound proxy that
+ * means the first provider call fails with an opaque network error and there is
+ * no setting that fixes it. Installing a global undici dispatcher is the only
+ * way to route global `fetch` through a proxy.
+ *
+ * `undici` is imported DYNAMICALLY and only when a proxy is actually configured,
+ * so `@moxxy/sdk` keeps zero hard runtime dependencies and a host with no proxy
+ * pays nothing. The package is a real dependency of `@moxxy/cli`.
+ *
+ * Not handled here, on purpose: a corporate TLS-terminating CA is Node's job,
+ * via `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` in the environment before Node
+ * starts. There is no in-process equivalent, so the doctor surfaces whether it
+ * is set rather than pretending to configure it.
+ */
+/** Proxy inputs, already resolved from env and/or config. */
+export interface EgressProxySettings {
+    /** Proxy for `http:` origins. */
+    readonly httpProxy?: string;
+    /** Proxy for `https:` origins. */
+    readonly httpsProxy?: string;
+    /** Raw `NO_PROXY` value: comma/whitespace separated bypass rules. */
+    readonly noProxy?: string;
+}
+export interface EgressStatus {
+    /** True when a global dispatcher was installed. */
+    readonly enabled: boolean;
+    /** Credential-redacted proxy in use for `http:`, when set. */
+    readonly httpProxy?: string;
+    /** Credential-redacted proxy in use for `https:`, when set. */
+    readonly httpsProxy?: string;
+    /** Parsed bypass rules. */
+    readonly noProxy?: ReadonlyArray<string>;
+    /** Why nothing was installed, or why installation failed. */
+    readonly reason?: string;
+}
+/**
+ * Read proxy settings from an environment. Lowercase wins over uppercase, which
+ * is the de-facto convention (curl, requests, Go): a shell that exports both
+ * usually means the lowercase one was set deliberately and more recently.
+ *
+ * `http_proxy` is deliberately NOT used as a fallback for https origins. Some
+ * environments set only `http_proxy` for a plaintext-only proxy, and silently
+ * tunnelling TLS through it would fail confusingly rather than going direct.
+ */
+export declare function readProxyEnv(env?: Readonly<Record<string, string | undefined>>): EgressProxySettings;
+/** Split a `NO_PROXY` value into normalized rules. Separators are commas and
+ *  whitespace; empty entries are dropped and matching is case-insensitive. */
+export declare function parseNoProxy(value: string | undefined): string[];
+/**
+ * Whether `origin` bypasses the proxy under `rules` (already parsed by
+ * {@link parseNoProxy}).
+ *
+ * Follows the de-facto `NO_PROXY` convention rather than inventing one:
+ *   - `*` bypasses everything.
+ *   - a bare host matches that host exactly, on any port.
+ *   - a leading `.` or `*.` matches the domain and every subdomain, so
+ *     `.corp.example` covers `api.corp.example` AND `corp.example`.
+ *   - an entry carrying `:port` matches only that port; the origin's port is
+ *     resolved from the scheme when the URL omits it.
+ *
+ * A malformed origin never bypasses: failing closed here sends the request
+ * through the proxy, which an operator can observe, rather than silently
+ * leaking it direct.
+ */
+export declare function shouldBypassProxy(origin: string, rules: ReadonlyArray<string>): boolean;
+/**
+ * A proxy URL with any embedded credentials masked, safe to log or show in
+ * `moxxy doctor`. Proxy URLs routinely carry `user:password@`, and this string
+ * ends up on terminals and in support pastes.
+ */
+export declare function redactProxyUrl(value: string): string;
+/** True when at least one proxy is configured, i.e. there is work to do. */
+export declare function hasProxy(settings: EgressProxySettings): boolean;
+interface UndiciModule {
+    readonly Agent: new (opts?: unknown) => UndiciDispatcher;
+    readonly ProxyAgent: new (opts: {
+        uri: string;
+    }) => UndiciDispatcher;
+    readonly setGlobalDispatcher: (dispatcher: UndiciDispatcher) => void;
+}
+interface UndiciDispatcher {
+    dispatch(opts: {
+        origin?: string | URL;
+    }, handler: unknown): boolean;
+    close(): Promise<void>;
+    destroy(): Promise<void>;
+}
+export interface InstallEgressProxyOptions {
+    /** Surface for the "configured but unusable" case. Defaults to stderr. */
+    readonly warn?: (message: string) => void;
+    /** Injectable module loader for tests. */
+    readonly loadUndici?: () => Promise<UndiciModule>;
+}
+/**
+ * Install a global dispatcher routing outbound requests through the configured
+ * proxy, honouring the bypass rules. No-ops (and reports why) when no proxy is
+ * configured, so this is safe to call unconditionally at boot.
+ *
+ * Never throws: a broken proxy setting must degrade to a loud warning plus
+ * direct connections, not a failed boot.
+ */
+export declare function installEgressProxy(settings: EgressProxySettings, opts?: InstallEgressProxyOptions): Promise<EgressStatus>;
+export {};
+//# sourceMappingURL=egress.d.ts.map

package/dist/egress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"egress.d.ts","sourceRoot":"","sources":["../src/egress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB;IAClC,iCAAiC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kCAAkC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,GAAG,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,GAC9D,mBAAmB,CAarB;AAED;8EAC8E;AAC9E,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAMhE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CA+BvF;AA4BD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWpD;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAE/D;AAED,UAAU,YAAY;IACpB,QAAQ,CAAC,KAAK,EAAE,KAAK,IAAI,CAAC,EAAE,OAAO,KAAK,gBAAgB,CAAC;IACzD,QAAQ,CAAC,UAAU,EAAE,KAAK,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,gBAAgB,CAAC;IACrE,QAAQ,CAAC,mBAAmB,EAAE,CAAC,UAAU,EAAE,gBAAgB,KAAK,IAAI,CAAC;CACtE;AAED,UAAU,gBAAgB;IACxB,QAAQ,CAAC,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;IACrE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,yBAAyB;IACxC,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;CACnD;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,mBAAmB,EAC7B,IAAI,GAAE,yBAA8B,GACnC,OAAO,CAAC,YAAY,CAAC,CA8DvB"}

package/dist/egress.js

@@ -0,0 +1,228 @@
+/**
+ * Outbound HTTP egress: corporate proxy support for everything moxxy fetches.
+ *
+ * Node's global `fetch` ignores `HTTPS_PROXY` entirely, and every provider
+ * reaches its API through it (`@anthropic-ai/sdk`, `openai`, and the plain
+ * `fetch` calls in tools). On a network that requires an outbound proxy that
+ * means the first provider call fails with an opaque network error and there is
+ * no setting that fixes it. Installing a global undici dispatcher is the only
+ * way to route global `fetch` through a proxy.
+ *
+ * `undici` is imported DYNAMICALLY and only when a proxy is actually configured,
+ * so `@moxxy/sdk` keeps zero hard runtime dependencies and a host with no proxy
+ * pays nothing. The package is a real dependency of `@moxxy/cli`.
+ *
+ * Not handled here, on purpose: a corporate TLS-terminating CA is Node's job,
+ * via `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` in the environment before Node
+ * starts. There is no in-process equivalent, so the doctor surfaces whether it
+ * is set rather than pretending to configure it.
+ */
+/**
+ * Read proxy settings from an environment. Lowercase wins over uppercase, which
+ * is the de-facto convention (curl, requests, Go): a shell that exports both
+ * usually means the lowercase one was set deliberately and more recently.
+ *
+ * `http_proxy` is deliberately NOT used as a fallback for https origins. Some
+ * environments set only `http_proxy` for a plaintext-only proxy, and silently
+ * tunnelling TLS through it would fail confusingly rather than going direct.
+ */
+export function readProxyEnv(env = process.env) {
+    const pick = (lower, upper) => {
+        const value = (env[lower] ?? env[upper] ?? '').trim();
+        return value.length > 0 ? value : undefined;
+    };
+    const httpProxy = pick('http_proxy', 'HTTP_PROXY');
+    const httpsProxy = pick('https_proxy', 'HTTPS_PROXY');
+    const noProxy = pick('no_proxy', 'NO_PROXY');
+    return {
+        ...(httpProxy ? { httpProxy } : {}),
+        ...(httpsProxy ? { httpsProxy } : {}),
+        ...(noProxy ? { noProxy } : {}),
+    };
+}
+/** Split a `NO_PROXY` value into normalized rules. Separators are commas and
+ *  whitespace; empty entries are dropped and matching is case-insensitive. */
+export function parseNoProxy(value) {
+    if (!value)
+        return [];
+    return value
+        .split(/[,\s]+/)
+        .map((rule) => rule.trim().toLowerCase())
+        .filter((rule) => rule.length > 0);
+}
+/**
+ * Whether `origin` bypasses the proxy under `rules` (already parsed by
+ * {@link parseNoProxy}).
+ *
+ * Follows the de-facto `NO_PROXY` convention rather than inventing one:
+ *   - `*` bypasses everything.
+ *   - a bare host matches that host exactly, on any port.
+ *   - a leading `.` or `*.` matches the domain and every subdomain, so
+ *     `.corp.example` covers `api.corp.example` AND `corp.example`.
+ *   - an entry carrying `:port` matches only that port; the origin's port is
+ *     resolved from the scheme when the URL omits it.
+ *
+ * A malformed origin never bypasses: failing closed here sends the request
+ * through the proxy, which an operator can observe, rather than silently
+ * leaking it direct.
+ */
+export function shouldBypassProxy(origin, rules) {
+    if (rules.length === 0)
+        return false;
+    if (rules.includes('*'))
+        return true;
+    let url;
+    try {
+        url = new URL(origin);
+    }
+    catch {
+        return false;
+    }
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    const port = url.port || (url.protocol === 'https:' ? '443' : '80');
+    for (const rule of rules) {
+        const { host: ruleHost, port: rulePort } = splitRule(rule);
+        if (rulePort !== undefined && rulePort !== port)
+            continue;
+        if (ruleHost.length === 0)
+            continue;
+        const suffix = ruleHost.startsWith('*.')
+            ? ruleHost.slice(1)
+            : ruleHost.startsWith('.')
+                ? ruleHost
+                : undefined;
+        if (suffix) {
+            // `.corp.example` covers the apex too, matching curl.
+            if (host === suffix.slice(1) || host.endsWith(suffix))
+                return true;
+            continue;
+        }
+        if (host === ruleHost)
+            return true;
+    }
+    return false;
+}
+/**
+ * Split a bypass rule into host and optional port.
+ *
+ * A bare IPv6 literal contains colons of its own, so `::1` must not be read as
+ * host `:` on port `1`. As in a URL, a port qualifier on an IPv6 address
+ * requires brackets (`[::1]:7000`); an unbracketed rule with more than one
+ * colon is therefore an address, never a host:port pair.
+ */
+function splitRule(rule) {
+    if (rule.startsWith('[')) {
+        const end = rule.indexOf(']');
+        if (end === -1)
+            return { host: rule.slice(1) };
+        const host = rule.slice(1, end);
+        const rest = rule.slice(end + 1);
+        return rest.startsWith(':') && /^\d+$/.test(rest.slice(1))
+            ? { host, port: rest.slice(1) }
+            : { host };
+    }
+    const first = rule.indexOf(':');
+    if (first === -1 || first !== rule.lastIndexOf(':'))
+        return { host: rule };
+    const maybePort = rule.slice(first + 1);
+    return /^\d+$/.test(maybePort)
+        ? { host: rule.slice(0, first), port: maybePort }
+        : { host: rule };
+}
+/**
+ * A proxy URL with any embedded credentials masked, safe to log or show in
+ * `moxxy doctor`. Proxy URLs routinely carry `user:password@`, and this string
+ * ends up on terminals and in support pastes.
+ */
+export function redactProxyUrl(value) {
+    try {
+        const url = new URL(value);
+        if (!url.username && !url.password)
+            return url.toString();
+        url.username = url.username ? '***' : '';
+        url.password = url.password ? '***' : '';
+        return url.toString();
+    }
+    catch {
+        // Unparseable: reveal nothing rather than echoing a possible secret.
+        return '<invalid proxy url>';
+    }
+}
+/** True when at least one proxy is configured, i.e. there is work to do. */
+export function hasProxy(settings) {
+    return Boolean(settings.httpProxy ?? settings.httpsProxy);
+}
+/**
+ * Install a global dispatcher routing outbound requests through the configured
+ * proxy, honouring the bypass rules. No-ops (and reports why) when no proxy is
+ * configured, so this is safe to call unconditionally at boot.
+ *
+ * Never throws: a broken proxy setting must degrade to a loud warning plus
+ * direct connections, not a failed boot.
+ */
+export async function installEgressProxy(settings, opts = {}) {
+    if (!hasProxy(settings))
+        return { enabled: false, reason: 'no proxy configured' };
+    const warn = opts.warn ?? ((m) => process.stderr.write(`[moxxy] ${m}\n`));
+    for (const [label, value] of [
+        ['http_proxy', settings.httpProxy],
+        ['https_proxy', settings.httpsProxy],
+    ]) {
+        if (value === undefined)
+            continue;
+        try {
+            new URL(value);
+        }
+        catch {
+            const reason = `${label} is not a valid URL; continuing without a proxy`;
+            warn(reason);
+            return { enabled: false, reason };
+        }
+    }
+    let undici;
+    try {
+        undici = await (opts.loadUndici ?? defaultLoadUndici)();
+    }
+    catch {
+        const reason = 'a proxy is configured but the `undici` package is unavailable; ' +
+            'outbound requests will bypass it and may fail';
+        warn(reason);
+        return { enabled: false, reason };
+    }
+    const rules = parseNoProxy(settings.noProxy);
+    const direct = new undici.Agent();
+    const httpProxy = settings.httpProxy ? new undici.ProxyAgent({ uri: settings.httpProxy }) : undefined;
+    const httpsProxy = settings.httpsProxy
+        ? new undici.ProxyAgent({ uri: settings.httpsProxy })
+        : undefined;
+    const route = (origin) => {
+        if (origin === undefined)
+            return direct;
+        const href = typeof origin === 'string' ? origin : origin.href;
+        if (shouldBypassProxy(href, rules))
+            return direct;
+        const secure = href.startsWith('https:');
+        return (secure ? httpsProxy : httpProxy) ?? direct;
+    };
+    const all = [direct, httpProxy, httpsProxy].filter(Boolean);
+    const router = {
+        dispatch: (dispatchOpts, handler) => route(dispatchOpts.origin).dispatch(dispatchOpts, handler),
+        close: async () => {
+            await Promise.all(all.map((d) => d.close()));
+        },
+        destroy: async () => {
+            await Promise.all(all.map((d) => d.destroy()));
+        },
+    };
+    undici.setGlobalDispatcher(router);
+    return {
+        enabled: true,
+        ...(settings.httpProxy ? { httpProxy: redactProxyUrl(settings.httpProxy) } : {}),
+        ...(settings.httpsProxy ? { httpsProxy: redactProxyUrl(settings.httpsProxy) } : {}),
+        ...(rules.length > 0 ? { noProxy: rules } : {}),
+    };
+}
+async function defaultLoadUndici() {
+    return (await import('undici'));
+}
+//# sourceMappingURL=egress.js.map

package/dist/egress.js.map

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

package/dist/events.d.ts

@@ -1,4 +1,5 @@
 import type { EventId, PluginId, SessionId, SkillId, ToolCallId, TurnId } from './ids.js';
+import type { Principal } from './principal.js';
 export type EventSource = 'user' | 'model' | 'tool' | 'plugin' | 'system' | 'compactor';
 export interface EventBase {
     readonly id: EventId;
@@ -8,6 +9,23 @@ export interface EventBase {
     readonly turnId: TurnId;
     readonly causationId?: EventId;
     readonly source: EventSource;
+    /**
+     * Who the action was taken on behalf of. `source` is a CATEGORY (user, model,
+     * tool, …); this is the SUBJECT, and without it a transcript proves a machine
+     * did something rather than that a person did.
+     *
+     * Stamped on EVERY event, not only turn boundaries, and carrying the whole
+     * principal rather than a reference. That repeats ~55 bytes per event, which
+     * is small against an envelope that already carries three ULIDs, and it buys
+     * the property an audit sink needs: a single record is self-attributing, so
+     * shipping one line to a SIEM requires no fold and no join. This is the same
+     * trade CloudTrail and the Kubernetes audit log make.
+     *
+     * OPTIONAL because the log is append-only and persisted: sessions recorded
+     * before identity existed replay with no actor, and must keep replaying.
+     * Treat absent as "unattributed", never as an error.
+     */
+    readonly actor?: Principal;
 }
 export interface UserPromptAttachment {
     readonly kind: 'stdin' | 'file' | 'image' | 'document' | 'audio';