agent-relay 2.2.24 → 2.3.1

package/packages/sdk-ts/dist/relay.js

@@ -0,0 +1,355 @@
+/**
+ * High-level facade for the Agent Relay SDK.
+ *
+ * Provides a clean, property-based API on top of the lower-level
+ * {@link AgentRelayClient} protocol client.
+ *
+ * @example
+ * ```ts
+ * import { AgentRelay } from "@agent-relay/sdk-ts";
+ *
+ * const relay = new AgentRelay();
+ *
+ * relay.onMessageReceived = (message) => console.log(message);
+ * relay.onAgentSpawned = (agent) => console.log("spawned", agent.name);
+ *
+ * const codex = await relay.codex.spawn();
+ * const human = relay.human({ name: "System" });
+ * await human.sendMessage({ to: codex.name, text: "Hello!" });
+ *
+ * const agents = await relay.listAgents();
+ * for (const a of agents) await a.release();
+ * await relay.shutdown();
+ * ```
+ */
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { AgentRelayClient, AgentRelayProtocolError, } from "./client.js";
+import { RelaycastApi } from "./relaycast.js";
+function isUnsupportedOperation(error) {
+    return error instanceof AgentRelayProtocolError && error.code === "unsupported_operation";
+}
+function buildUnsupportedOperationMessage(from, input) {
+    return {
+        eventId: "unsupported_operation",
+        from,
+        to: input.to,
+        text: input.text,
+        threadId: input.threadId,
+    };
+}
+// ── AgentRelay facade ───────────────────────────────────────────────────────
+export class AgentRelay {
+    // Event hooks — assign a callback or null to clear.
+    onMessageReceived = null;
+    onMessageSent = null;
+    onAgentSpawned = null;
+    onAgentReleased = null;
+    onAgentExited = null;
+    onWorkerOutput = null;
+    onDeliveryUpdate = null;
+    // Shorthand spawners
+    codex;
+    claude;
+    gemini;
+    clientOptions;
+    defaultChannels;
+    client;
+    startPromise;
+    unsubEvent;
+    knownAgents = new Map();
+    exitResolvers = new Map();
+    relaycastByName = new Map();
+    constructor(options = {}) {
+        this.defaultChannels = options.channels ?? ["general"];
+        this.clientOptions = {
+            binaryPath: options.binaryPath,
+            binaryArgs: options.binaryArgs,
+            brokerName: options.brokerName,
+            channels: this.defaultChannels,
+            cwd: options.cwd,
+            env: options.env,
+            requestTimeoutMs: options.requestTimeoutMs,
+            shutdownTimeoutMs: options.shutdownTimeoutMs,
+        };
+        this.codex = this.createSpawner("codex", "Codex", "pty");
+        this.claude = this.createSpawner("claude", "Claude", "pty");
+        this.gemini = this.createSpawner("gemini", "Gemini", "pty");
+    }
+    // ── Spawning ────────────────────────────────────────────────────────────
+    async spawnPty(input) {
+        const client = await this.ensureStarted();
+        const channels = input.channels ?? ["general"];
+        const result = await client.spawnPty({
+            name: input.name,
+            cli: input.cli,
+            args: input.args,
+            channels,
+        });
+        const agent = this.makeAgent(result.name, result.runtime, channels);
+        this.knownAgents.set(agent.name, agent);
+        return agent;
+    }
+    // ── Human source ────────────────────────────────────────────────────────
+    human(opts) {
+        const relay = this;
+        return {
+            name: opts.name,
+            async sendMessage(input) {
+                const client = await relay.ensureStarted();
+                let result;
+                try {
+                    result = await client.sendMessage({
+                        to: input.to,
+                        text: input.text,
+                        from: opts.name,
+                        threadId: input.threadId,
+                        priority: input.priority,
+                    });
+                }
+                catch (error) {
+                    if (isUnsupportedOperation(error)) {
+                        return buildUnsupportedOperationMessage(opts.name, input);
+                    }
+                    throw error;
+                }
+                if (result?.event_id === "unsupported_operation") {
+                    return buildUnsupportedOperationMessage(opts.name, input);
+                }
+                const eventId = result?.event_id ?? randomBytes(8).toString("hex");
+                const msg = {
+                    eventId,
+                    from: opts.name,
+                    to: input.to,
+                    text: input.text,
+                    threadId: input.threadId,
+                };
+                relay.onMessageSent?.(msg);
+                return msg;
+            },
+        };
+    }
+    // ── Listing ─────────────────────────────────────────────────────────────
+    async listAgents() {
+        const client = await this.ensureStarted();
+        const list = await client.listAgents();
+        return list.map((entry) => {
+            const existing = this.knownAgents.get(entry.name);
+            if (existing)
+                return existing;
+            const agent = this.makeAgent(entry.name, entry.runtime, entry.channels);
+            this.knownAgents.set(agent.name, agent);
+            return agent;
+        });
+    }
+    // ── Status ────────────────────────────────────────────────────────────
+    async getStatus() {
+        const client = await this.ensureStarted();
+        return client.getStatus();
+    }
+    // ── Lifecycle ───────────────────────────────────────────────────────────
+    async shutdown() {
+        if (this.unsubEvent) {
+            this.unsubEvent();
+            this.unsubEvent = undefined;
+        }
+        if (this.client) {
+            await this.client.shutdown();
+            this.client = undefined;
+        }
+        this.knownAgents.clear();
+        for (const resolve of this.exitResolvers.values()) {
+            resolve("released");
+        }
+        this.exitResolvers.clear();
+    }
+    // ── Private helpers ─────────────────────────────────────────────────────
+    /** Resolve a target to a channel name. If `to` is `#channel`, use that
+     *  channel. If it's a known agent name, use the agent's first channel.
+     *  Otherwise fall back to the relay's default channel. */
+    resolveChannel(to) {
+        if (to.startsWith("#"))
+            return to.slice(1);
+        const agent = this.knownAgents.get(to);
+        if (agent && agent.channels.length > 0)
+            return agent.channels[0];
+        return this.defaultChannels[0];
+    }
+    ensureRelaycast(agentName) {
+        let rc = this.relaycastByName.get(agentName);
+        if (!rc) {
+            const cwd = this.clientOptions.cwd ?? process.cwd();
+            rc = new RelaycastApi({
+                agentName,
+                cachePath: path.join(cwd, ".agent-relay", "relaycast.json"),
+            });
+            this.relaycastByName.set(agentName, rc);
+        }
+        return rc;
+    }
+    async ensureStarted() {
+        if (this.client)
+            return this.client;
+        if (this.startPromise)
+            return this.startPromise;
+        this.startPromise = AgentRelayClient.start(this.clientOptions)
+            .then((c) => {
+            this.client = c;
+            this.startPromise = undefined;
+            this.wireEvents(c);
+            return c;
+        })
+            .catch((err) => {
+            this.startPromise = undefined;
+            throw err;
+        });
+        return this.startPromise;
+    }
+    wireEvents(client) {
+        this.unsubEvent = client.onEvent((event) => {
+            switch (event.kind) {
+                case "relay_inbound": {
+                    const msg = {
+                        eventId: event.event_id,
+                        from: event.from,
+                        to: event.target,
+                        text: event.body,
+                        threadId: event.thread_id,
+                    };
+                    this.onMessageReceived?.(msg);
+                    break;
+                }
+                case "agent_spawned": {
+                    let agent = this.knownAgents.get(event.name);
+                    if (!agent) {
+                        agent = this.makeAgent(event.name, event.runtime, []);
+                        this.knownAgents.set(event.name, agent);
+                    }
+                    this.onAgentSpawned?.(agent);
+                    break;
+                }
+                case "agent_released": {
+                    const agent = this.knownAgents.get(event.name) ??
+                        this.makeAgent(event.name, "pty", []);
+                    this.onAgentReleased?.(agent);
+                    this.knownAgents.delete(event.name);
+                    this.exitResolvers.get(event.name)?.("released");
+                    this.exitResolvers.delete(event.name);
+                    break;
+                }
+                case "agent_exited": {
+                    const agent = this.knownAgents.get(event.name) ??
+                        this.makeAgent(event.name, "pty", []);
+                    this.onAgentExited?.(agent);
+                    this.knownAgents.delete(event.name);
+                    this.exitResolvers.get(event.name)?.("exited");
+                    this.exitResolvers.delete(event.name);
+                    break;
+                }
+                case "worker_stream": {
+                    this.onWorkerOutput?.({
+                        name: event.name,
+                        stream: event.stream,
+                        chunk: event.chunk,
+                    });
+                    break;
+                }
+            }
+            if (event.kind.startsWith("delivery_")) {
+                this.onDeliveryUpdate?.(event);
+            }
+        });
+    }
+    makeAgent(name, runtime, channels) {
+        const relay = this;
+        return {
+            name,
+            runtime,
+            channels,
+            async release() {
+                const client = await relay.ensureStarted();
+                await client.release(name);
+            },
+            waitForExit(timeoutMs) {
+                return new Promise((resolve) => {
+                    // If already gone, resolve immediately
+                    if (!relay.knownAgents.has(name)) {
+                        resolve("exited");
+                        return;
+                    }
+                    // Non-blocking poll: timeoutMs === 0 means "check now, return immediately"
+                    if (timeoutMs === 0) {
+                        resolve("timeout");
+                        return;
+                    }
+                    let timer;
+                    relay.exitResolvers.set(name, (reason) => {
+                        if (timer)
+                            clearTimeout(timer);
+                        resolve(reason);
+                    });
+                    if (timeoutMs !== undefined) {
+                        timer = setTimeout(() => {
+                            relay.exitResolvers.delete(name);
+                            resolve("timeout");
+                        }, timeoutMs);
+                    }
+                });
+            },
+            async sendMessage(input) {
+                const client = await relay.ensureStarted();
+                let result;
+                try {
+                    result = await client.sendMessage({
+                        to: input.to,
+                        text: input.text,
+                        from: name,
+                        threadId: input.threadId,
+                        priority: input.priority,
+                    });
+                }
+                catch (error) {
+                    if (isUnsupportedOperation(error)) {
+                        return buildUnsupportedOperationMessage(name, input);
+                    }
+                    throw error;
+                }
+                if (result?.event_id === "unsupported_operation") {
+                    return buildUnsupportedOperationMessage(name, input);
+                }
+                const eventId = result?.event_id ?? randomBytes(8).toString("hex");
+                const msg = {
+                    eventId,
+                    from: name,
+                    to: input.to,
+                    text: input.text,
+                    threadId: input.threadId,
+                };
+                relay.onMessageSent?.(msg);
+                return msg;
+            },
+        };
+    }
+    createSpawner(cli, defaultName, runtime) {
+        const relay = this;
+        return {
+            async spawn(options) {
+                const client = await relay.ensureStarted();
+                const name = options?.name ?? defaultName;
+                const channels = options?.channels ?? ["general"];
+                const args = options?.args ?? [];
+                let result;
+                if (runtime === "headless_claude") {
+                    result = await client.spawnHeadlessClaude({ name, args, channels });
+                }
+                else {
+                    result = await client.spawnPty({ name, cli, args, channels });
+                }
+                const agent = relay.makeAgent(result.name, result.runtime, channels);
+                relay.knownAgents.set(agent.name, agent);
+                return agent;
+            },
+        };
+    }
+}
+//# sourceMappingURL=relay.js.map

package/packages/sdk-ts/dist/relay.js.map

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

package/packages/sdk-ts/dist/relaycast.d.ts

@@ -0,0 +1,57 @@
+export interface RelaycastCredentials {
+    workspace_id: string;
+    agent_id: string;
+    api_key: string;
+    agent_name?: string;
+}
+export interface RelaycastWorkspace {
+    workspaceId: string;
+    apiKey: string;
+}
+export interface RelaycastApiOptions {
+    /** Workspace API key. If provided, skips reading from the cache file. */
+    apiKey?: string;
+    baseUrl?: string;
+    cachePath?: string;
+    /** Agent name to register with. Defaults to a unique "sdk-<hex>" name. */
+    agentName?: string;
+}
+/**
+ * Convenience wrapper around `@relaycast/sdk` that manages workspace
+ * creation, agent registration, and message sending.
+ */
+export declare class RelaycastApi {
+    private readonly baseUrl;
+    private readonly cachePath;
+    private readonly agentName;
+    private readonly apiKeyOverride?;
+    private agentClient?;
+    constructor(options?: RelaycastApiOptions);
+    /**
+     * Create a new Relaycast workspace. Returns the workspace ID and API key.
+     * No authentication required — this is the bootstrap entry point.
+     */
+    static createWorkspace(name: string, baseUrl?: string): Promise<RelaycastWorkspace>;
+    /** Resolve the workspace API key from explicit option, env, or cache file. */
+    private resolveApiKey;
+    /** Lazily register and return an authenticated AgentClient. */
+    private ensure;
+    /** Send a direct message to a named agent. */
+    sendDm(to: string, text: string): Promise<void>;
+    /** Send a message to a channel (without the leading #). */
+    sendToChannel(channel: string, text: string): Promise<void>;
+    /** Send to a target — prefixed with # for channel, otherwise DM. */
+    send(to: string, text: string): Promise<void>;
+    /** Fetch message history from a channel. */
+    getMessages(channel: string, opts?: {
+        limit?: number;
+        before?: string;
+        after?: string;
+    }): Promise<Array<{
+        id: string;
+        agent_name: string;
+        text: string;
+        created_at: string;
+    }>>;
+}
+//# sourceMappingURL=relaycast.d.ts.map

package/packages/sdk-ts/dist/relaycast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relaycast.d.ts","sourceRoot":"","sources":["../src/relaycast.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAS;IACzC,OAAO,CAAC,WAAW,CAAC,CAAc;gBAEtB,OAAO,GAAE,mBAAwB;IAO7C;;;OAGG;WACU,eAAe,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,SAAmB,GACzB,OAAO,CAAC,kBAAkB,CAAC;IAmB9B,8EAA8E;YAChE,aAAa;IAQ3B,+DAA+D;YACjD,MAAM;IAwBpB,8CAA8C;IACxC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrD,2DAA2D;IACrD,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjE,oEAAoE;IAC9D,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnD,4CAA4C;IACtC,WAAW,CACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACzD,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAUxF"}

package/packages/sdk-ts/dist/relaycast.js

@@ -0,0 +1,110 @@
+import { randomBytes } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Relay, RelayError } from "@relaycast/sdk";
+const DEFAULT_BASE_URL = "https://api.relaycast.dev";
+/**
+ * Convenience wrapper around `@relaycast/sdk` that manages workspace
+ * creation, agent registration, and message sending.
+ */
+export class RelaycastApi {
+    baseUrl;
+    cachePath;
+    agentName;
+    apiKeyOverride;
+    agentClient;
+    constructor(options = {}) {
+        this.baseUrl = options.baseUrl ?? process.env.RELAYCAST_BASE_URL ?? DEFAULT_BASE_URL;
+        this.cachePath = options.cachePath ?? join(homedir(), ".agent-relay", "relaycast.json");
+        this.agentName = options.agentName ?? `sdk-${randomBytes(4).toString("hex")}`;
+        this.apiKeyOverride = options.apiKey;
+    }
+    /**
+     * Create a new Relaycast workspace. Returns the workspace ID and API key.
+     * No authentication required — this is the bootstrap entry point.
+     */
+    static async createWorkspace(name, baseUrl = DEFAULT_BASE_URL) {
+        const res = await fetch(`${baseUrl}/v1/workspaces`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ name }),
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to create workspace: ${res.status} ${await res.text()}`);
+        }
+        const body = await res.json();
+        const data = body.data ?? body;
+        const workspaceId = data.workspace_id ?? data.id;
+        const apiKey = data.api_key;
+        if (!workspaceId || !apiKey) {
+            throw new Error("Workspace response missing workspace_id or api_key");
+        }
+        return { workspaceId, apiKey };
+    }
+    /** Resolve the workspace API key from explicit option, env, or cache file. */
+    async resolveApiKey() {
+        if (this.apiKeyOverride)
+            return this.apiKeyOverride;
+        if (process.env.RELAY_API_KEY)
+            return process.env.RELAY_API_KEY;
+        const raw = await readFile(this.cachePath, "utf-8");
+        const creds = JSON.parse(raw);
+        return creds.api_key;
+    }
+    /** Lazily register and return an authenticated AgentClient. */
+    async ensure() {
+        if (this.agentClient)
+            return this.agentClient;
+        const apiKey = await this.resolveApiKey();
+        const relay = new Relay({ apiKey, baseUrl: this.baseUrl });
+        // Register — retry with a suffixed name on 409 conflict.
+        let name = this.agentName;
+        let registration;
+        try {
+            registration = await relay.agents.register({ name, type: "agent" });
+        }
+        catch (err) {
+            if (err instanceof RelayError && err.code === "agent_already_exists") {
+                name = `${this.agentName}-${randomBytes(4).toString("hex")}`;
+                registration = await relay.agents.register({ name, type: "agent" });
+            }
+            else {
+                throw err;
+            }
+        }
+        this.agentClient = relay.as(registration.token);
+        return this.agentClient;
+    }
+    /** Send a direct message to a named agent. */
+    async sendDm(to, text) {
+        const agent = await this.ensure();
+        await agent.dm(to, text);
+    }
+    /** Send a message to a channel (without the leading #). */
+    async sendToChannel(channel, text) {
+        const agent = await this.ensure();
+        await agent.send(channel, text);
+    }
+    /** Send to a target — prefixed with # for channel, otherwise DM. */
+    async send(to, text) {
+        if (to.startsWith("#")) {
+            await this.sendToChannel(to.slice(1), text);
+        }
+        else {
+            await this.sendDm(to, text);
+        }
+    }
+    /** Fetch message history from a channel. */
+    async getMessages(channel, opts) {
+        const agent = await this.ensure();
+        const messages = await agent.messages(channel, opts);
+        return messages.map((m) => ({
+            id: m.id,
+            agent_name: m.agent_name,
+            text: m.text,
+            created_at: m.created_at,
+        }));
+    }
+}
+//# sourceMappingURL=relaycast.js.map

package/packages/sdk-ts/dist/relaycast.js.map

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

package/packages/sdk-ts/dist/shadow.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Shadow agent support for the broker SDK.
+ *
+ * A shadow agent monitors all messages to/from a primary agent.
+ * Implemented SDK-side using the event hook system — no broker
+ * protocol extension required.
+ *
+ * @example
+ * ```ts
+ * import { AgentRelay, ShadowManager } from "agent-relay/broker";
+ *
+ * const relay = new AgentRelay();
+ * const shadows = new ShadowManager();
+ *
+ * // Bind "Reviewer" as shadow of "Worker1"
+ * shadows.bind("Reviewer", "Worker1");
+ *
+ * // Wire into relay events
+ * relay.onMessageReceived = (msg) => {
+ *   const copies = shadows.intercept(msg.from, msg.to, msg);
+ *   for (const copy of copies) {
+ *     // Forward shadow copies to the shadow agent
+ *     relay.human({ name: "system" }).sendMessage({
+ *       to: copy.shadowAgent,
+ *       text: `[Shadow of ${copy.primaryAgent}] ${msg.text}`,
+ *     });
+ *   }
+ * };
+ * ```
+ */
+export type SpeakOnTrigger = "ALL_MESSAGES" | "EXPLICIT_ASK" | "SESSION_END" | "CODE_WRITTEN" | "REVIEW_REQUEST";
+export interface ShadowConfig {
+    primaryAgent: string;
+    speakOn: SpeakOnTrigger[];
+    receiveIncoming: boolean;
+    receiveOutgoing: boolean;
+}
+export interface ShadowRelationship extends ShadowConfig {
+    shadowAgent: string;
+}
+export interface ShadowCopy {
+    shadowAgent: string;
+    primaryAgent: string;
+    direction: "incoming" | "outgoing";
+}
+export declare class ShadowManager {
+    /** primaryAgent → list of shadow relationships */
+    private shadowsByPrimary;
+    /** shadowAgent → primaryAgent (reverse lookup) */
+    private primaryByShadow;
+    /**
+     * Bind a shadow agent to monitor a primary agent.
+     */
+    bind(shadowAgent: string, primaryAgent: string, options?: {
+        speakOn?: SpeakOnTrigger[];
+        receiveIncoming?: boolean;
+        receiveOutgoing?: boolean;
+    }): void;
+    /**
+     * Unbind a shadow from its primary.
+     */
+    unbind(shadowAgent: string): void;
+    /**
+     * Get all shadows for a primary agent.
+     */
+    getShadowsFor(primaryAgent: string): ShadowRelationship[];
+    /**
+     * Get the primary agent a shadow is bound to.
+     */
+    getPrimaryFor(shadowAgent: string): string | undefined;
+    /**
+     * Check whether a shadow should speak for a given trigger.
+     */
+    shouldSpeak(shadowAgent: string, trigger: SpeakOnTrigger): boolean;
+    /**
+     * Determine which shadows should receive a copy of a message
+     * between `from` and `to`. Returns a list of shadow copies to deliver.
+     *
+     * Call this from your `onMessageReceived` / `onMessageSent` hooks
+     * to fan out shadow copies.
+     */
+    intercept(from: string, to: string): ShadowCopy[];
+    /**
+     * Emit a trigger event and return shadow agents that should be notified.
+     *
+     * Use this to implement `speakOn` behavior — when a trigger fires
+     * (e.g. CODE_WRITTEN, REVIEW_REQUEST), call this to find which
+     * shadows should receive a notification.
+     */
+    emitTrigger(primaryAgent: string, trigger: SpeakOnTrigger): string[];
+    /**
+     * List all current shadow bindings.
+     */
+    listBindings(): ShadowRelationship[];
+    /**
+     * Remove all bindings (for shutdown).
+     */
+    clear(): void;
+}
+//# sourceMappingURL=shadow.d.ts.map

package/packages/sdk-ts/dist/shadow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadow.d.ts","sourceRoot":"","sources":["../src/shadow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,MAAM,MAAM,cAAc,GACtB,cAAc,GACd,cAAc,GACd,aAAa,GACb,cAAc,GACd,gBAAgB,CAAC;AAErB,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACtD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;CACpC;AAID,qBAAa,aAAa;IACxB,kDAAkD;IAClD,OAAO,CAAC,gBAAgB,CAA2C;IACnE,kDAAkD;IAClD,OAAO,CAAC,eAAe,CAA6B;IAEpD;;OAEG;IACH,IAAI,CACF,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE;QACP,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;QAC3B,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;KACtB,GACL,IAAI;IAqBP;;OAEG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAgBjC;;OAEG;IACH,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAIzD;;OAEG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAItD;;OAEG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO;IAelE;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,UAAU,EAAE;IAoCjD;;;;;;OAMG;IACH,WAAW,CACT,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,cAAc,GACtB,MAAM,EAAE;IAUX;;OAEG;IACH,YAAY,IAAI,kBAAkB,EAAE;IAQpC;;OAEG;IACH,KAAK,IAAI,IAAI;CAId"}