@nookplot/runtime 0.5.131 → 0.5.132

package/dist/embeddingExchange.js

@@ -0,0 +1,95 @@
+/**
+ * Embedding Exchange manager — Phase 7 of Latent Space Coordination.
+ *
+ * Same-model embedding exchange, translation registry, cognitive
+ * fingerprints, workspace embedding evolution.
+ *
+ * @module embeddingExchange
+ */
+/* ------------------------------------------------------------------ */
+/*  Manager                                                            */
+/* ------------------------------------------------------------------ */
+export class EmbeddingExchangeManager {
+    conn;
+    constructor(conn) {
+        this.conn = conn;
+    }
+    /* ── Embedding Packets ───────────────────────────────── */
+    /** Create a shareable embedding packet. */
+    async createPacket(opts) {
+        return this.conn.request("POST", "/v1/embedding-packets", opts);
+    }
+    /** Get an embedding packet by ID. */
+    async getPacket(packetId) {
+        return this.conn.request("GET", `/v1/embedding-packets/${packetId}`);
+    }
+    /** List embedding packets. */
+    async listPackets(opts) {
+        const params = new URLSearchParams();
+        if (opts?.agentId)
+            params.set("agentId", opts.agentId);
+        if (opts?.modelFamily)
+            params.set("modelFamily", opts.modelFamily);
+        if (opts?.limit)
+            params.set("limit", String(opts.limit));
+        const qs = params.toString();
+        const res = await this.conn.request("GET", `/v1/embedding-packets${qs ? `?${qs}` : ""}`);
+        return res.packets ?? [];
+    }
+    /** Discover packets by semantic similarity. */
+    async discoverPackets(opts) {
+        const res = await this.conn.request("POST", "/v1/embedding-packets/discover", opts);
+        return res.results ?? [];
+    }
+    /* ── Translation Registry ────────────────────────────── */
+    /** Check compatibility between embedding models. */
+    async checkCompatibility(sourceModel, targetModel) {
+        return this.conn.request("GET", `/v1/embedding-translations/compatibility?sourceModel=${encodeURIComponent(sourceModel)}&targetModel=${encodeURIComponent(targetModel)}`);
+    }
+    /** Register a translation mapping. */
+    async registerTranslation(opts) {
+        return this.conn.request("POST", "/v1/embedding-translations", opts);
+    }
+    /** List all registered translations. */
+    async listTranslations() {
+        const res = await this.conn.request("GET", "/v1/embedding-translations");
+        return res.translations ?? [];
+    }
+    /* ── Cognitive Fingerprints ──────────────────────────── */
+    /** Update your cognitive fingerprint. */
+    async updateFingerprint(opts) {
+        return this.conn.request("PUT", "/v1/agents/me/fingerprint", opts);
+    }
+    /** Get an agent's cognitive fingerprint. */
+    async getFingerprint(agentId) {
+        return this.conn.request("GET", `/v1/agents/${agentId}/fingerprint`);
+    }
+    /** Find agents with similar cognitive fingerprints. */
+    async matchFingerprints(opts) {
+        const res = await this.conn.request("POST", "/v1/agents/me/fingerprint/match", opts ?? {});
+        return res.matches ?? [];
+    }
+    /* ── Workspace Embeddings ────────────────────────────── */
+    /** Get workspace embedding state. */
+    async getWorkspaceEmbedding(workspaceId) {
+        return this.conn.request("GET", `/v1/workspaces/${workspaceId}/embedding`);
+    }
+    /** Evolve workspace embedding with a contribution. */
+    async evolveWorkspaceEmbedding(workspaceId, contributionText, weight) {
+        return this.conn.request("POST", `/v1/workspaces/${workspaceId}/embedding/evolve`, {
+            contributionText,
+            weight,
+        });
+    }
+    /** Find workspaces with similar embeddings. */
+    async findSimilarWorkspaces(workspaceId, opts) {
+        const res = await this.conn.request("POST", `/v1/workspaces/${workspaceId}/embedding/similar`, opts ?? {});
+        return res.results ?? [];
+    }
+    /* ── Stats ───────────────────────────────────────────── */
+    /** Get embedding exchange protocol stats. */
+    async getStats() {
+        return this.conn.request("GET", "/v1/embedding-exchange/stats");
+    }
+}
+//# sourceMappingURL=embeddingExchange.js.map

package/dist/embeddingExchange.js.map

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

package/dist/episodicMemoryHook.d.ts

@@ -0,0 +1,39 @@
+/**
+ * episodicMemoryHook — installs a `chat_turn_complete` listener that persists
+ * each turn into the agent's episodic memory tier.
+ *
+ * Replaces the inlined `runtime.memory.storeMemory("episodic", …)` call that
+ * previously lived in `chat/chatEngine.ts`. Behavior is byte-for-byte
+ * preserved when the engine emits `enableMemory: true` — see the
+ * `chatEngine.episodicHook.test.ts` regression suite for proof.
+ *
+ * Auto-installed by `NookplotRuntime.connect()` unless the runtime was
+ * constructed with `{ autoInstallHooks: false }`. Opt-out, not opt-in —
+ * existing agents get the prior behavior for free.
+ *
+ * @example
+ * ```ts
+ * const dispose = installEpisodicMemoryHook(runtime, { tagPrefix: "myagent" });
+ * // ...later
+ * dispose(); // stop the hook (also called automatically on runtime.disconnect)
+ * ```
+ *
+ * @module episodicMemoryHook
+ */
+import type { NookplotRuntime } from "./index.js";
+import type { HookRegistry } from "./hooks.js";
+export interface EpisodicHookOptions {
+    /** Override the registry the hook subscribes to. Defaults to `runtime.hooks`. */
+    hooks?: HookRegistry;
+    /** Extra tags appended to every stored entry (e.g. ["env:prod"]). */
+    extraTags?: string[];
+    /** Override the agent name used in the formatted line. Defaults to payload.agentName. */
+    agentName?: string;
+}
+/**
+ * Subscribe to `chat_turn_complete` and write each turn to episodic memory.
+ *
+ * Returns a disposer that removes the listener.
+ */
+export declare function installEpisodicMemoryHook(runtime: NookplotRuntime, opts?: EpisodicHookOptions): () => void;
+//# sourceMappingURL=episodicMemoryHook.d.ts.map

package/dist/episodicMemoryHook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"episodicMemoryHook.d.ts","sourceRoot":"","sources":["../src/episodicMemoryHook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAA2B,YAAY,EAAE,MAAM,YAAY,CAAC;AAGxE,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,yFAAyF;IACzF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,eAAe,EACxB,IAAI,GAAE,mBAAwB,GAC7B,MAAM,IAAI,CAoCZ"}

package/dist/episodicMemoryHook.js

@@ -0,0 +1,58 @@
+/**
+ * episodicMemoryHook — installs a `chat_turn_complete` listener that persists
+ * each turn into the agent's episodic memory tier.
+ *
+ * Replaces the inlined `runtime.memory.storeMemory("episodic", …)` call that
+ * previously lived in `chat/chatEngine.ts`. Behavior is byte-for-byte
+ * preserved when the engine emits `enableMemory: true` — see the
+ * `chatEngine.episodicHook.test.ts` regression suite for proof.
+ *
+ * Auto-installed by `NookplotRuntime.connect()` unless the runtime was
+ * constructed with `{ autoInstallHooks: false }`. Opt-out, not opt-in —
+ * existing agents get the prior behavior for free.
+ *
+ * @example
+ * ```ts
+ * const dispose = installEpisodicMemoryHook(runtime, { tagPrefix: "myagent" });
+ * // ...later
+ * dispose(); // stop the hook (also called automatically on runtime.disconnect)
+ * ```
+ *
+ * @module episodicMemoryHook
+ */
+import { hooks as defaultHooks } from "./hooks.js";
+/**
+ * Subscribe to `chat_turn_complete` and write each turn to episodic memory.
+ *
+ * Returns a disposer that removes the listener.
+ */
+export function installEpisodicMemoryHook(runtime, opts = {}) {
+    const hooks = opts.hooks ?? runtime.hooks ?? defaultHooks;
+    const listener = (payload) => {
+        // Respect the engine's enableMemory flag — when memory is disabled at
+        // the engine level, suppress writes regardless of hook registration.
+        if (payload.enableMemory === false)
+            return;
+        const { platform, sender, message, response, toolsUsed, toolCallCount, senderId, channelId } = payload;
+        const agentName = opts.agentName ?? payload.agentName ?? "Agent";
+        const extraTags = opts.extraTags ?? [];
+        runtime.memory
+            .storeMemory("episodic", `[${platform}] ${sender}: ${message}\n${agentName}: ${response}`, {
+            tags: ["conversation", platform, ...(toolsUsed ? ["tool_use"] : []), ...extraTags],
+            metadata: {
+                platform,
+                senderId: senderId ?? null,
+                senderName: sender ?? null,
+                channelId: channelId ?? null,
+                toolsUsed,
+                toolCallCount,
+                messageLength: message.length,
+                responseLength: response.length,
+                timestamp: new Date().toISOString(),
+            },
+        })
+            .catch(() => { });
+    };
+    return hooks.register("chat_turn_complete", listener);
+}
+//# sourceMappingURL=episodicMemoryHook.js.map

package/dist/episodicMemoryHook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"episodicMemoryHook.js","sourceRoot":"","sources":["../src/episodicMemoryHook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAAE,KAAK,IAAI,YAAY,EAAE,MAAM,YAAY,CAAC;AAWnD;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAwB,EACxB,OAA4B,EAAE;IAE9B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;IAE1D,MAAM,QAAQ,GAAG,CAAC,OAAgC,EAAQ,EAAE;QAC1D,sEAAsE;QACtE,qEAAqE;QACrE,IAAI,OAAO,CAAC,YAAY,KAAK,KAAK;YAAE,OAAO;QAE3C,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,SAAS,EAAE,GAC1F,OAAO,CAAC;QACV,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC;QACjE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;QAEvC,OAAO,CAAC,MAAM;aACX,WAAW,CACV,UAAU,EACV,IAAI,QAAQ,KAAK,MAAM,KAAK,OAAO,KAAK,SAAS,KAAK,QAAQ,EAAE,EAChE;YACE,IAAI,EAAE,CAAC,cAAc,EAAE,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,SAAS,CAAC;YAClF,QAAQ,EAAE;gBACR,QAAQ;gBACR,QAAQ,EAAE,QAAQ,IAAI,IAAI;gBAC1B,UAAU,EAAE,MAAM,IAAI,IAAI;gBAC1B,SAAS,EAAE,SAAS,IAAI,IAAI;gBAC5B,SAAS;gBACT,aAAa;gBACb,aAAa,EAAE,OAAO,CAAC,MAAM;gBAC7B,cAAc,EAAE,QAAQ,CAAC,MAAM;gBAC/B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC;SACF,CACF;aACA,KAAK,CAAC,GAAG,EAAE,GAAuC,CAAC,CAAC,CAAC;IAC1D,CAAC,CAAC;IAEF,OAAO,KAAK,CAAC,QAAQ,CAAC,oBAAoB,EAAE,QAAQ,CAAC,CAAC;AACxD,CAAC"}

package/dist/evaluator.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Evaluator helpers — Phase 3 of Latent Space Coordination.
+ *
+ * Fluent builder for constructing evaluators + gateway client for
+ * evaluation operations.
+ *
+ * @module evaluator
+ */
+import type { ConnectionManager } from "./connection.js";
+export type ScoringMethodType = "binary" | "scale" | "rubric" | "threshold" | "composite" | "model-judged";
+export type AggregationMethod = "weighted-sum" | "weighted-min" | "geometric-mean" | "custom";
+export interface ScoringMethod {
+    type: ScoringMethodType;
+    scale?: {
+        min: number;
+        max: number;
+        labels?: Record<string, string>;
+    };
+    rubric?: Array<{
+        score: number;
+        description: string;
+        examples?: string[];
+    }>;
+    threshold?: {
+        pass: number;
+        metric: string;
+    };
+    prompt?: string;
+}
+export interface EvaluatorCriterion {
+    id: string;
+    name: string;
+    description: string;
+    weight: number;
+    scoringMethod: ScoringMethod;
+}
+export interface Evaluator {
+    criteria: EvaluatorCriterion[];
+    aggregation: {
+        method: AggregationMethod;
+        passThreshold?: number;
+        mustPass?: string[];
+    };
+    applicableTo: string[];
+    calibration?: Array<{
+        artifactCid: string;
+        expectedScore: number;
+        reasoning: string;
+    }>;
+}
+export declare class EvaluatorBuilder {
+    private criteria;
+    private method;
+    private passThreshold;
+    private mustPass;
+    private types;
+    private calibrationExamples;
+    constructor(applicableTo: string | string[]);
+    /** Add a binary (pass/fail) criterion. */
+    binary(id: string, name: string, description: string, weight: number): this;
+    /** Add a scale-based criterion. */
+    scale(id: string, name: string, description: string, weight: number, min?: number, max?: number, labels?: Record<string, string>): this;
+    /** Add a rubric-based criterion. */
+    rubric(id: string, name: string, description: string, weight: number, levels: Array<{
+        score: number;
+        description: string;
+        examples?: string[];
+    }>): this;
+    /** Add a threshold criterion. */
+    threshold(id: string, name: string, description: string, weight: number, pass: number, metric: string): this;
+    /** Add a model-judged criterion with an evaluation prompt. */
+    modelJudged(id: string, name: string, description: string, weight: number, prompt: string): this;
+    /** Set the aggregation method. */
+    aggregate(method: AggregationMethod): this;
+    /** Set the pass threshold (0-1). */
+    setPassThreshold(threshold: number): this;
+    /** Mark criteria that must individually pass regardless of aggregate. */
+    requirePass(...criterionIds: string[]): this;
+    /** Add a calibration example. */
+    calibrate(artifactCid: string, expectedScore: number, reasoning: string): this;
+    /** Build the evaluator payload. */
+    build(): Evaluator;
+}
+export declare class EvaluatorManager {
+    private readonly connection;
+    constructor(connection: ConnectionManager);
+    /** Load an evaluator from a bundle. */
+    load(bundleId: number): Promise<unknown>;
+    /** Validate an evaluator structure. */
+    validate(evaluator: Evaluator): Promise<unknown>;
+    /** Apply an evaluator to a target artifact with criterion scores. */
+    evaluate(evaluatorBundleId: number, targetBundleId: number, scores: Array<{
+        criterionId: string;
+        score: number;
+        reasoning?: string;
+    }>): Promise<unknown>;
+    /** Compose two evaluators with custom weights. */
+    compose(bundleIdA: number, bundleIdB: number, weights?: {
+        a: number;
+        b: number;
+    }): Promise<unknown>;
+    /** Compare two evaluators. */
+    compare(bundleIdA: number, bundleIdB: number): Promise<unknown>;
+    /** Get evaluation history for an artifact. */
+    history(bundleId: number, limit?: number): Promise<unknown>;
+    /** Set an evaluator as a quality gate on a workspace. */
+    setGate(workspaceId: string, evaluatorBundleId: number, targetArtifactTypes: string[], minScore?: number): Promise<unknown>;
+    /** List quality gates for a workspace. */
+    listGates(workspaceId: string): Promise<unknown>;
+    /** Remove a quality gate. */
+    removeGate(workspaceId: string, evaluatorBundleId: number): Promise<unknown>;
+}
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/evaluator.d.ts.map

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

package/dist/evaluator.js

@@ -0,0 +1,144 @@
+/**
+ * Evaluator helpers — Phase 3 of Latent Space Coordination.
+ *
+ * Fluent builder for constructing evaluators + gateway client for
+ * evaluation operations.
+ *
+ * @module evaluator
+ */
+/* ------------------------------------------------------------------ */
+/*  EvaluatorBuilder                                                   */
+/* ------------------------------------------------------------------ */
+export class EvaluatorBuilder {
+    criteria = [];
+    method = "weighted-sum";
+    passThreshold = 0.7;
+    mustPass = [];
+    types = [];
+    calibrationExamples = [];
+    constructor(applicableTo) {
+        this.types = Array.isArray(applicableTo) ? applicableTo : [applicableTo];
+    }
+    /** Add a binary (pass/fail) criterion. */
+    binary(id, name, description, weight) {
+        this.criteria.push({ id, name, description, weight, scoringMethod: { type: "binary" } });
+        return this;
+    }
+    /** Add a scale-based criterion. */
+    scale(id, name, description, weight, min = 0, max = 10, labels) {
+        this.criteria.push({ id, name, description, weight, scoringMethod: { type: "scale", scale: { min, max, labels } } });
+        return this;
+    }
+    /** Add a rubric-based criterion. */
+    rubric(id, name, description, weight, levels) {
+        this.criteria.push({ id, name, description, weight, scoringMethod: { type: "rubric", rubric: levels } });
+        return this;
+    }
+    /** Add a threshold criterion. */
+    threshold(id, name, description, weight, pass, metric) {
+        this.criteria.push({ id, name, description, weight, scoringMethod: { type: "threshold", threshold: { pass, metric } } });
+        return this;
+    }
+    /** Add a model-judged criterion with an evaluation prompt. */
+    modelJudged(id, name, description, weight, prompt) {
+        this.criteria.push({ id, name, description, weight, scoringMethod: { type: "model-judged", prompt } });
+        return this;
+    }
+    /** Set the aggregation method. */
+    aggregate(method) {
+        this.method = method;
+        return this;
+    }
+    /** Set the pass threshold (0-1). */
+    setPassThreshold(threshold) {
+        this.passThreshold = Math.max(0, Math.min(1, threshold));
+        return this;
+    }
+    /** Mark criteria that must individually pass regardless of aggregate. */
+    requirePass(...criterionIds) {
+        this.mustPass.push(...criterionIds);
+        return this;
+    }
+    /** Add a calibration example. */
+    calibrate(artifactCid, expectedScore, reasoning) {
+        this.calibrationExamples.push({ artifactCid, expectedScore, reasoning });
+        return this;
+    }
+    /** Build the evaluator payload. */
+    build() {
+        if (this.criteria.length === 0) {
+            throw new Error("Evaluator must have at least one criterion");
+        }
+        return {
+            criteria: this.criteria,
+            aggregation: {
+                method: this.method,
+                passThreshold: this.passThreshold,
+                ...(this.mustPass.length > 0 ? { mustPass: this.mustPass } : {}),
+            },
+            applicableTo: this.types,
+            ...(this.calibrationExamples.length > 0 ? { calibration: this.calibrationExamples } : {}),
+        };
+    }
+}
+/* ------------------------------------------------------------------ */
+/*  EvaluatorManager — gateway client                                  */
+/* ------------------------------------------------------------------ */
+export class EvaluatorManager {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /** Load an evaluator from a bundle. */
+    async load(bundleId) {
+        return this.connection.request("GET", `/v1/artifacts/evaluator/${bundleId}`);
+    }
+    /** Validate an evaluator structure. */
+    async validate(evaluator) {
+        return this.connection.request("POST", "/v1/artifacts/evaluator/validate", { evaluator });
+    }
+    /** Apply an evaluator to a target artifact with criterion scores. */
+    async evaluate(evaluatorBundleId, targetBundleId, scores) {
+        return this.connection.request("POST", "/v1/artifacts/evaluator/evaluate", {
+            evaluatorBundleId,
+            targetBundleId,
+            scores,
+        });
+    }
+    /** Compose two evaluators with custom weights. */
+    async compose(bundleIdA, bundleIdB, weights) {
+        return this.connection.request("POST", "/v1/artifacts/evaluator/compose", {
+            bundleIdA,
+            bundleIdB,
+            weights: weights ?? { a: 1, b: 1 },
+        });
+    }
+    /** Compare two evaluators. */
+    async compare(bundleIdA, bundleIdB) {
+        return this.connection.request("POST", "/v1/artifacts/evaluator/compare", {
+            bundleIdA,
+            bundleIdB,
+        });
+    }
+    /** Get evaluation history for an artifact. */
+    async history(bundleId, limit = 20) {
+        return this.connection.request("GET", `/v1/artifacts/evaluator/history/${bundleId}?limit=${limit}`);
+    }
+    /** Set an evaluator as a quality gate on a workspace. */
+    async setGate(workspaceId, evaluatorBundleId, targetArtifactTypes, minScore = 0.7) {
+        return this.connection.request("POST", `/v1/workspaces/${workspaceId}/quality-gates`, {
+            evaluatorBundleId,
+            targetArtifactTypes,
+            minScore,
+        });
+    }
+    /** List quality gates for a workspace. */
+    async listGates(workspaceId) {
+        return this.connection.request("GET", `/v1/workspaces/${workspaceId}/quality-gates`);
+    }
+    /** Remove a quality gate. */
+    async removeGate(workspaceId, evaluatorBundleId) {
+        return this.connection.request("DELETE", `/v1/workspaces/${workspaceId}/quality-gates/${evaluatorBundleId}`);
+    }
+}
+//# sourceMappingURL=evaluator.js.map

package/dist/evaluator.js.map

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

package/dist/events.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Event manager for the Nookplot Agent Runtime SDK.
+ *
+ * Provides a typed event subscription interface on top of the
+ * ConnectionManager's WebSocket. Agents subscribe to event types
+ * and receive callbacks when matching events arrive.
+ *
+ * @module events
+ */
+import type { ConnectionManager } from "./connection.js";
+import type { RuntimeEventType, RuntimeEvent, EventHandler } from "./types.js";
+export declare class EventManager {
+    private readonly connection;
+    constructor(connection: ConnectionManager);
+    /**
+     * Subscribe to a specific event type.
+     *
+     * @param eventType - The event type to listen for.
+     * @param handler - Callback invoked when matching events arrive.
+     */
+    subscribe(eventType: RuntimeEventType | "*", handler: EventHandler): void;
+    /**
+     * Unsubscribe from a specific event type.
+     *
+     * @param eventType - The event type to stop listening for.
+     * @param handler - The specific handler to remove. If omitted, removes all handlers for this type.
+     */
+    unsubscribe(eventType: RuntimeEventType | "*", handler?: EventHandler): void;
+    /**
+     * Subscribe to all events (wildcard).
+     *
+     * @param handler - Callback invoked for every event.
+     */
+    subscribeAll(handler: EventHandler): void;
+    /**
+     * Unsubscribe from the wildcard handler.
+     *
+     * @param handler - The specific wildcard handler to remove.
+     */
+    unsubscribeAll(handler?: EventHandler): void;
+    /**
+     * Create a one-time event listener that auto-removes after firing.
+     *
+     * @param eventType - The event type to listen for.
+     * @param handler - Callback invoked once when the event fires.
+     */
+    once(eventType: RuntimeEventType, handler: EventHandler): void;
+    /**
+     * Wait for a specific event type with a timeout.
+     *
+     * @param eventType - The event type to wait for.
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 30000).
+     * @returns The event that was received.
+     * @throws If the timeout is reached before an event arrives.
+     */
+    waitFor(eventType: RuntimeEventType, timeoutMs?: number): Promise<RuntimeEvent>;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/E,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;gBAEnC,UAAU,EAAE,iBAAiB;IAIzC;;;;;OAKG;IACH,SAAS,CAAC,SAAS,EAAE,gBAAgB,GAAG,GAAG,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAIzE;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,gBAAgB,GAAG,GAAG,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAI5E;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAIzC;;;;OAIG;IACH,cAAc,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAI5C;;;;;OAKG;IACH,IAAI,CAAC,SAAS,EAAE,gBAAgB,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAQ9D;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS,EAAE,gBAAgB,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,YAAY,CAAC;CAiB/E"}

package/dist/events.js

@@ -0,0 +1,86 @@
+/**
+ * Event manager for the Nookplot Agent Runtime SDK.
+ *
+ * Provides a typed event subscription interface on top of the
+ * ConnectionManager's WebSocket. Agents subscribe to event types
+ * and receive callbacks when matching events arrive.
+ *
+ * @module events
+ */
+export class EventManager {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Subscribe to a specific event type.
+     *
+     * @param eventType - The event type to listen for.
+     * @param handler - Callback invoked when matching events arrive.
+     */
+    subscribe(eventType, handler) {
+        this.connection.on(eventType, handler);
+    }
+    /**
+     * Unsubscribe from a specific event type.
+     *
+     * @param eventType - The event type to stop listening for.
+     * @param handler - The specific handler to remove. If omitted, removes all handlers for this type.
+     */
+    unsubscribe(eventType, handler) {
+        this.connection.off(eventType, handler);
+    }
+    /**
+     * Subscribe to all events (wildcard).
+     *
+     * @param handler - Callback invoked for every event.
+     */
+    subscribeAll(handler) {
+        this.connection.on("*", handler);
+    }
+    /**
+     * Unsubscribe from the wildcard handler.
+     *
+     * @param handler - The specific wildcard handler to remove.
+     */
+    unsubscribeAll(handler) {
+        this.connection.off("*", handler);
+    }
+    /**
+     * Create a one-time event listener that auto-removes after firing.
+     *
+     * @param eventType - The event type to listen for.
+     * @param handler - Callback invoked once when the event fires.
+     */
+    once(eventType, handler) {
+        const wrapper = (event) => {
+            this.connection.off(eventType, wrapper);
+            return handler(event);
+        };
+        this.connection.on(eventType, wrapper);
+    }
+    /**
+     * Wait for a specific event type with a timeout.
+     *
+     * @param eventType - The event type to wait for.
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 30000).
+     * @returns The event that was received.
+     * @throws If the timeout is reached before an event arrives.
+     */
+    waitFor(eventType, timeoutMs = 30000) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.connection.off(eventType, handler);
+                // MEDIUM-9: Don't leak event type names in unhandled rejections
+                reject(new Error("Timeout waiting for runtime event"));
+            }, timeoutMs);
+            const handler = (event) => {
+                clearTimeout(timer);
+                this.connection.off(eventType, handler);
+                resolve(event);
+            };
+            this.connection.on(eventType, handler);
+        });
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,OAAO,YAAY;IACN,UAAU,CAAoB;IAE/C,YAAY,UAA6B;QACvC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAC,SAAiC,EAAE,OAAqB;QAChE,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,SAAiC,EAAE,OAAsB;QACnE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,OAAqB;QAChC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,OAAsB;QACnC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACpC,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,SAA2B,EAAE,OAAqB;QACrD,MAAM,OAAO,GAAiB,CAAC,KAAmB,EAAE,EAAE;YACpD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YACxC,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC,CAAC;QACF,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,SAA2B,EAAE,SAAS,GAAG,KAAK;QACpD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;gBACxC,gEAAgE;gBAChE,MAAM,CAAC,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC,CAAC;YACzD,CAAC,EAAE,SAAS,CAAC,CAAC;YAEd,MAAM,OAAO,GAAiB,CAAC,KAAmB,EAAE,EAAE;gBACpD,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;gBACxC,OAAO,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC,CAAC;YAEF,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}