@agent-relay/sdk 2.3.14 → 2.4.0

package/dist/consensus.js

@@ -0,0 +1,378 @@
+/**
+ * Consensus / voting engine for distributed agent decision-making.
+ *
+ * Runs entirely in the SDK process — no broker protocol extension needed.
+ * Proposals are broadcast and votes collected via the relay messaging layer.
+ *
+ * Consensus types:
+ * - majority   — simple >50%
+ * - supermajority — configurable threshold (default 2/3)
+ * - unanimous  — all participants must approve
+ * - weighted   — votes weighted by agent role/expertise
+ * - quorum     — minimum participation + majority
+ */
+import { randomBytes } from "node:crypto";
+import { EventEmitter } from "node:events";
+export { formatProposalMessage, formatResultMessage, parseVoteCommand, isConsensusCommand, parseProposalCommand, } from "./consensus-helpers.js";
+// ── Defaults ─────────────────────────────────────────────────────────────────
+const DEFAULT_CONFIG = {
+    defaultTimeoutMs: 5 * 60 * 1000,
+    defaultConsensusType: "majority",
+    defaultThreshold: 0.67,
+    allowVoteChange: true,
+    autoResolve: true,
+    maxRetainedProposals: 100,
+};
+// ── Engine ───────────────────────────────────────────────────────────────────
+export class ConsensusEngine extends EventEmitter {
+    config;
+    proposals = new Map();
+    expiryTimers = new Map();
+    constructor(config = {}) {
+        super();
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    // ── Proposal management ──────────────────────────────────────────────────
+    createProposal(options) {
+        const id = `prop_${Date.now()}_${randomBytes(4).toString("hex")}`;
+        const now = Date.now();
+        const timeoutMs = options.timeoutMs ?? this.config.defaultTimeoutMs;
+        const proposal = {
+            id,
+            title: options.title,
+            description: options.description,
+            proposer: options.proposer,
+            consensusType: options.consensusType ?? this.config.defaultConsensusType,
+            participants: options.participants,
+            quorum: options.quorum,
+            threshold: options.threshold ?? this.config.defaultThreshold,
+            weights: options.weights,
+            createdAt: now,
+            expiresAt: now + timeoutMs,
+            status: "pending",
+            votes: [],
+            metadata: options.metadata,
+            thread: options.thread ?? `consensus-${id}`,
+        };
+        this.proposals.set(id, proposal);
+        this.scheduleExpiry(proposal);
+        this.emit("proposal:created", proposal);
+        return proposal;
+    }
+    vote(proposalId, agent, value, reason) {
+        const proposal = this.proposals.get(proposalId);
+        if (!proposal)
+            return { success: false, error: "Proposal not found" };
+        if (proposal.status !== "pending")
+            return { success: false, error: `Proposal is ${proposal.status}` };
+        if (!proposal.participants.includes(agent))
+            return { success: false, error: "Agent not a participant" };
+        if (Date.now() > proposal.expiresAt) {
+            this.expireProposal(proposal);
+            return { success: false, error: "Proposal has expired" };
+        }
+        const existingIdx = proposal.votes.findIndex((v) => v.agent === agent);
+        if (existingIdx >= 0) {
+            if (!this.config.allowVoteChange)
+                return {
+                    success: false,
+                    error: "Vote already cast and changes not allowed",
+                };
+            proposal.votes.splice(existingIdx, 1);
+        }
+        const weight = this.getAgentWeight(proposal, agent);
+        const vote = { agent, value, weight, reason, timestamp: Date.now() };
+        proposal.votes.push(vote);
+        this.emit("proposal:voted", proposal, vote);
+        if (this.config.autoResolve) {
+            const result = this.calculateResult(proposal);
+            if (this.canResolveEarly(proposal, result)) {
+                this.resolveProposal(proposal, result);
+            }
+        }
+        return { success: true, proposal };
+    }
+    getProposal(proposalId) {
+        return this.proposals.get(proposalId) ?? null;
+    }
+    getProposalsForAgent(agent) {
+        const out = [];
+        for (const p of this.proposals.values()) {
+            if (p.proposer === agent || p.participants.includes(agent))
+                out.push(p);
+        }
+        return out;
+    }
+    getPendingVotesForAgent(agent) {
+        const out = [];
+        for (const p of this.proposals.values()) {
+            if (p.status !== "pending")
+                continue;
+            if (!p.participants.includes(agent))
+                continue;
+            if (p.votes.some((v) => v.agent === agent))
+                continue;
+            out.push(p);
+        }
+        return out;
+    }
+    cancelProposal(proposalId, agent) {
+        const proposal = this.proposals.get(proposalId);
+        if (!proposal)
+            return { success: false, error: "Proposal not found" };
+        if (proposal.proposer !== agent)
+            return { success: false, error: "Only proposer can cancel" };
+        if (proposal.status !== "pending")
+            return { success: false, error: `Proposal is ${proposal.status}` };
+        proposal.status = "cancelled";
+        this.clearExpiryTimer(proposalId);
+        this.emit("proposal:cancelled", proposal);
+        this.evictOldProposals();
+        return { success: true };
+    }
+    forceResolve(proposalId) {
+        const proposal = this.proposals.get(proposalId);
+        if (!proposal || proposal.status !== "pending")
+            return null;
+        const result = this.calculateResult(proposal);
+        this.resolveProposal(proposal, result);
+        return result;
+    }
+    // ── Calculation ──────────────────────────────────────────────────────────
+    calculateResult(proposal) {
+        let approveWeight = 0;
+        let rejectWeight = 0;
+        let abstainWeight = 0;
+        for (const v of proposal.votes) {
+            if (v.value === "approve")
+                approveWeight += v.weight;
+            else if (v.value === "reject")
+                rejectWeight += v.weight;
+            else
+                abstainWeight += v.weight;
+        }
+        const totalWeight = this.getTotalWeight(proposal);
+        const votedWeight = approveWeight + rejectWeight + abstainWeight;
+        const participation = totalWeight > 0 ? votedWeight / totalWeight : 0;
+        const voters = new Set(proposal.votes.map((v) => v.agent));
+        const nonVoters = proposal.participants.filter((p) => !voters.has(p));
+        const quorumRequired = proposal.quorum ?? Math.ceil(proposal.participants.length / 2);
+        const quorumMet = proposal.votes.length >= quorumRequired;
+        const decision = this.determineDecision(proposal, {
+            approveWeight,
+            rejectWeight,
+            votedWeight,
+            quorumMet,
+        });
+        return {
+            decision,
+            approveWeight,
+            rejectWeight,
+            abstainWeight,
+            participation,
+            quorumMet,
+            resolvedAt: Date.now(),
+            nonVoters,
+        };
+    }
+    determineDecision(proposal, counts) {
+        const { approveWeight, rejectWeight, votedWeight, quorumMet } = counts;
+        switch (proposal.consensusType) {
+            case "unanimous": {
+                if (proposal.votes.some((v) => v.value === "reject"))
+                    return "rejected";
+                if (proposal.votes.length < proposal.participants.length)
+                    return "no_consensus";
+                return proposal.votes.every((v) => v.value === "approve")
+                    ? "approved"
+                    : "rejected";
+            }
+            case "supermajority": {
+                const threshold = proposal.threshold ?? this.config.defaultThreshold;
+                if (votedWeight === 0)
+                    return "no_consensus";
+                if (approveWeight / votedWeight >= threshold)
+                    return "approved";
+                if (rejectWeight / votedWeight > 1 - threshold)
+                    return "rejected";
+                return "no_consensus";
+            }
+            case "quorum": {
+                if (!quorumMet)
+                    return "no_consensus";
+                // fall through to majority
+            }
+            // eslint-disable-next-line no-fallthrough
+            case "majority": {
+                if (votedWeight === 0)
+                    return "no_consensus";
+                if (approveWeight > rejectWeight)
+                    return "approved";
+                if (rejectWeight > approveWeight)
+                    return "rejected";
+                return "no_consensus";
+            }
+            case "weighted": {
+                if (votedWeight === 0)
+                    return "no_consensus";
+                if (approveWeight > rejectWeight)
+                    return "approved";
+                if (rejectWeight > approveWeight)
+                    return "rejected";
+                return "no_consensus";
+            }
+            default:
+                return "no_consensus";
+        }
+    }
+    canResolveEarly(proposal, result) {
+        const totalWeight = this.getTotalWeight(proposal);
+        const remainingWeight = totalWeight -
+            (result.approveWeight + result.rejectWeight + result.abstainWeight);
+        switch (proposal.consensusType) {
+            case "unanimous":
+                return (proposal.votes.some((v) => v.value === "reject") ||
+                    proposal.votes.length === proposal.participants.length);
+            case "supermajority": {
+                const threshold = proposal.threshold ?? this.config.defaultThreshold;
+                const votedWeight = result.approveWeight + result.rejectWeight + result.abstainWeight;
+                if (votedWeight > 0 &&
+                    result.approveWeight / votedWeight >= threshold) {
+                    return (result.approveWeight / (votedWeight + remainingWeight) >= threshold);
+                }
+                if (votedWeight > 0 &&
+                    result.rejectWeight / votedWeight > 1 - threshold) {
+                    return (result.rejectWeight / (votedWeight + remainingWeight) > 1 - threshold);
+                }
+                return false;
+            }
+            case "majority":
+            case "weighted":
+                return (result.approveWeight > totalWeight / 2 ||
+                    result.rejectWeight > totalWeight / 2);
+            case "quorum":
+                if (!result.quorumMet)
+                    return false;
+                return (result.approveWeight > totalWeight / 2 ||
+                    result.rejectWeight > totalWeight / 2);
+            default:
+                return false;
+        }
+    }
+    // ── Weight helpers ───────────────────────────────────────────────────────
+    getAgentWeight(proposal, agent) {
+        if (proposal.weights) {
+            const w = proposal.weights.find((w) => w.agent === agent);
+            if (w)
+                return w.weight;
+        }
+        return 1;
+    }
+    getTotalWeight(proposal) {
+        let total = 0;
+        for (const p of proposal.participants) {
+            total += this.getAgentWeight(proposal, p);
+        }
+        return total;
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────────
+    resolveProposal(proposal, result) {
+        proposal.status =
+            result.decision === "approved"
+                ? "approved"
+                : result.decision === "rejected"
+                    ? "rejected"
+                    : "rejected"; // no_consensus maps to rejected (not expired — that's for timeouts)
+        proposal.result = result;
+        this.clearExpiryTimer(proposal.id);
+        this.emit("proposal:resolved", proposal, result);
+        this.evictOldProposals();
+    }
+    expireProposal(proposal) {
+        if (proposal.status !== "pending")
+            return;
+        const result = this.calculateResult(proposal);
+        proposal.status = "expired";
+        proposal.result = result;
+        this.clearExpiryTimer(proposal.id);
+        this.emit("proposal:expired", proposal);
+        this.evictOldProposals();
+    }
+    scheduleExpiry(proposal) {
+        const timeoutMs = proposal.expiresAt - Date.now();
+        if (timeoutMs <= 0) {
+            this.expireProposal(proposal);
+            return;
+        }
+        const timer = setTimeout(() => this.expireProposal(proposal), timeoutMs);
+        timer.unref();
+        this.expiryTimers.set(proposal.id, timer);
+    }
+    clearExpiryTimer(proposalId) {
+        const timer = this.expiryTimers.get(proposalId);
+        if (timer) {
+            clearTimeout(timer);
+            this.expiryTimers.delete(proposalId);
+        }
+    }
+    /** Remove oldest resolved/expired/cancelled proposals when over the limit. */
+    evictOldProposals() {
+        const max = this.config.maxRetainedProposals;
+        if (max <= 0)
+            return; // unlimited
+        const terminal = [];
+        for (const p of this.proposals.values()) {
+            if (p.status !== "pending")
+                terminal.push(p);
+        }
+        if (terminal.length <= max)
+            return;
+        // Sort oldest-first by createdAt, evict the excess
+        terminal.sort((a, b) => a.createdAt - b.createdAt);
+        const toEvict = terminal.length - max;
+        for (let i = 0; i < toEvict; i++) {
+            this.proposals.delete(terminal[i].id);
+        }
+    }
+    cleanup() {
+        for (const timer of this.expiryTimers.values())
+            clearTimeout(timer);
+        this.expiryTimers.clear();
+    }
+    // ── Stats ────────────────────────────────────────────────────────────────
+    getStats() {
+        let pending = 0, approved = 0, rejected = 0, expired = 0, cancelled = 0;
+        let totalParticipation = 0;
+        let resolvedCount = 0;
+        for (const p of this.proposals.values()) {
+            if (p.status === "pending")
+                pending++;
+            else if (p.status === "approved")
+                approved++;
+            else if (p.status === "rejected")
+                rejected++;
+            else if (p.status === "expired")
+                expired++;
+            else if (p.status === "cancelled")
+                cancelled++;
+            if (p.result) {
+                totalParticipation += p.result.participation;
+                resolvedCount++;
+            }
+        }
+        return {
+            total: this.proposals.size,
+            pending,
+            approved,
+            rejected,
+            expired,
+            cancelled,
+            avgParticipation: resolvedCount > 0 ? totalParticipation / resolvedCount : 0,
+        };
+    }
+}
+// ── Factory ──────────────────────────────────────────────────────────────────
+export function createConsensusEngine(config) {
+    return new ConsensusEngine(config);
+}
+//# sourceMappingURL=consensus.js.map

package/dist/consensus.js.map

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

package/dist/examples/demo.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=demo.d.ts.map

package/dist/examples/demo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo.d.ts","sourceRoot":"","sources":["../../src/examples/demo.ts"],"names":[],"mappings":""}

package/dist/examples/demo.js

@@ -0,0 +1,63 @@
+/**
+ * Runnable demo — shows the full AgentRelay message flow with real output.
+ * Uses `cat` as a universally-available stand-in for agent CLIs.
+ *
+ * Run:
+ *   npm run build && npm run demo
+ */
+import { AgentRelay } from "../relay.js";
+const relay = new AgentRelay({ env: process.env });
+// ── Event hooks ─────────────────────────────────────────────────────────────
+relay.onMessageReceived = (message) => {
+    console.log(`  📨 received  │ from=${message.from}  to=${message.to}  text="${message.text}"`);
+};
+relay.onMessageSent = (message) => {
+    console.log(`  📤 sent      │ from=${message.from}  to=${message.to}  text="${message.text}"`);
+};
+relay.onAgentSpawned = (agent) => {
+    console.log(`  🟢 spawned   │ ${agent.name} (${agent.runtime})`);
+};
+relay.onAgentReleased = (agent) => {
+    console.log(`  🔴 released  │ ${agent.name}`);
+};
+relay.onAgentExited = (agent) => {
+    console.log(`  ⚪ exited    │ ${agent.name}`);
+};
+// ── Spawn agents ────────────────────────────────────────────────────────────
+console.log("\n─── Spawning agents ───\n");
+const [agentA, agentB] = await Promise.all([
+    relay.spawnPty({ name: "AgentA", cli: "claude", args: ["--print"], channels: ["general"] }),
+    relay.spawnPty({ name: "AgentB", cli: "claude", args: ["--print"], channels: ["general"] }),
+]);
+// ── Send messages ───────────────────────────────────────────────────────────
+console.log("\n─── Sending messages ───\n");
+const human = relay.human({ name: "System" });
+await human.sendMessage({ to: agentA.name, text: "Hello AgentA, welcome!" });
+await human.sendMessage({ to: agentB.name, text: "Hello AgentB, welcome!" });
+// Agent-to-agent messaging
+await agentA.sendMessage({ to: agentB.name, text: "Hey B, got a task for you" });
+await agentB.sendMessage({ to: agentA.name, text: "On it!" });
+// Threaded conversation
+const thread = await human.sendMessage({ to: agentA.name, text: "Status update?" });
+await agentA.sendMessage({ to: human.name, text: "All good!", threadId: thread.eventId });
+// Priority messages
+await human.sendMessage({ to: agentA.name, text: "Critical alert!", priority: 0 });
+await human.sendMessage({ to: agentB.name, text: "Low priority FYI", priority: 4 });
+// Small delay to let events propagate
+await new Promise((r) => setTimeout(r, 500));
+// ── List agents ─────────────────────────────────────────────────────────────
+console.log("\n─── Active agents ───\n");
+const agents = await relay.listAgents();
+for (const agent of agents) {
+    console.log(`  • ${agent.name}  runtime=${agent.runtime}  channels=[${agent.channels}]`);
+}
+// ── Release all ─────────────────────────────────────────────────────────────
+console.log("\n─── Releasing agents ───\n");
+for (const agent of agents) {
+    await agent.release();
+}
+await new Promise((r) => setTimeout(r, 300));
+// ── Shutdown ────────────────────────────────────────────────────────────────
+await relay.shutdown();
+console.log("\n─── Done ───\n");
+//# sourceMappingURL=demo.js.map

package/dist/examples/demo.js.map

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

package/dist/examples/example.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=example.d.ts.map

package/dist/examples/example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example.d.ts","sourceRoot":"","sources":["../../src/examples/example.ts"],"names":[],"mappings":""}

package/dist/examples/example.js

@@ -0,0 +1,80 @@
+import { AgentRelayClient } from "../client.js";
+function parseArgs(raw) {
+    if (!raw || raw.trim() === "") {
+        return [];
+    }
+    return raw
+        .split(" ")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+}
+function now() {
+    return new Date().toISOString();
+}
+async function main() {
+    const codexCmd = process.env.CODEX_CMD ?? "codex";
+    const codexArgs = parseArgs(process.env.CODEX_ARGS);
+    const channel = process.env.RELAY_CHANNEL ?? "general";
+    const xName = process.env.AGENT_X_NAME ?? "CodexX";
+    const oName = process.env.AGENT_O_NAME ?? "CodexO";
+    const client = await AgentRelayClient.start({
+        channels: [channel],
+    });
+    const stopLogging = client.onEvent((event) => {
+        console.log(`[${now()}] event`, JSON.stringify(event));
+    });
+    const stopStderrLogging = client.onBrokerStderr((line) => {
+        console.log(`[${now()}] broker:stderr ${line}`);
+    });
+    const cleanup = async () => {
+        console.log(`[${now()}] cleaning up agents + broker`);
+        try {
+            await client.release(xName);
+        }
+        catch {
+            // ignore
+        }
+        try {
+            await client.release(oName);
+        }
+        catch {
+            // ignore
+        }
+        await client.shutdown();
+        stopLogging();
+        stopStderrLogging();
+    };
+    process.on("SIGINT", async () => {
+        console.log(`[${now()}] SIGINT received`);
+        await cleanup();
+        process.exit(0);
+    });
+    process.on("SIGTERM", async () => {
+        console.log(`[${now()}] SIGTERM received`);
+        await cleanup();
+        process.exit(0);
+    });
+    console.log(`[${now()}] spawning ${xName} (${codexCmd} ${codexArgs.join(" ")})`);
+    await client.spawnPty({
+        name: xName,
+        cli: codexCmd,
+        args: codexArgs,
+        channels: [channel],
+    });
+    console.log(`[${now()}] spawning ${oName} (${codexCmd} ${codexArgs.join(" ")})`);
+    await client.spawnPty({
+        name: oName,
+        cli: codexCmd,
+        args: codexArgs,
+        channels: [channel],
+    });
+    console.log(`[${now()}] workers spawned. send kickoff via Relaycast (MCP relay_send) and watch events here (Ctrl+C to stop).`);
+    await new Promise(() => {
+        // keep process alive while events stream
+    });
+}
+main().catch((error) => {
+    console.error(`[${now()}] fatal`, error);
+    process.exit(1);
+});
+//# sourceMappingURL=example.js.map

package/dist/examples/example.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"example.js","sourceRoot":"","sources":["../../src/examples/example.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,SAAS,SAAS,CAAC,GAAuB;IACxC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC9B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,GAAG;SACP,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,GAAG;IACV,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAClC,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,OAAO,CAAC;IAClD,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,SAAS,CAAC;IACvD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,QAAQ,CAAC;IACnD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,QAAQ,CAAC;IAEnD,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC;QAC1C,QAAQ,EAAE,CAAC,OAAO,CAAC;KACpB,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QAC3C,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IACH,MAAM,iBAAiB,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,EAAE,EAAE;QACvD,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,mBAAmB,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,KAAK,IAAI,EAAE;QACzB,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,+BAA+B,CAAC,CAAC;QACtD,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;QACxB,WAAW,EAAE,CAAC;QACd,iBAAiB,EAAE,CAAC;IACtB,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QAC9B,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,mBAAmB,CAAC,CAAC;QAC1C,MAAM,OAAO,EAAE,CAAC;QAChB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;QAC/B,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,oBAAoB,CAAC,CAAC;QAC3C,MAAM,OAAO,EAAE,CAAC;QAChB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,cAAc,KAAK,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjF,MAAM,MAAM,CAAC,QAAQ,CAAC;QACpB,IAAI,EAAE,KAAK;QACX,GAAG,EAAE,QAAQ;QACb,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE,CAAC,OAAO,CAAC;KACpB,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,cAAc,KAAK,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjF,MAAM,MAAM,CAAC,QAAQ,CAAC;QACpB,IAAI,EAAE,KAAK;QACX,GAAG,EAAE,QAAQ;QACb,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE,CAAC,OAAO,CAAC;KACpB,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CACT,IAAI,GAAG,EAAE,wGAAwG,CAClH,CAAC;IACF,MAAM,IAAI,OAAO,CAAO,GAAG,EAAE;QAC3B,yCAAyC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,IAAI,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IACzC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/examples/quickstart.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=quickstart.d.ts.map

package/dist/examples/quickstart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quickstart.d.ts","sourceRoot":"","sources":["../../src/examples/quickstart.ts"],"names":[],"mappings":""}

package/dist/examples/quickstart.js

@@ -0,0 +1,56 @@
+/**
+ * Quickstart — shows the clean AgentRelay facade API.
+ *
+ * Run:
+ *   npm run build && npm run quickstart
+ *
+ * Environment:
+ *   RELAY_API_KEY   — Relaycast workspace key (required)
+ *   AGENT_RELAY_BIN — path to agent-relay binary (optional)
+ */
+import { AgentRelay } from "../relay.js";
+// The Relay is the communication backbone for your agents.
+// Drop it into your codebase and let your agents communicate.
+const relay = new AgentRelay();
+// ── Event hooks ─────────────────────────────────────────────────────────────
+relay.onMessageReceived = (message) => {
+    console.log(`message received  → from=${message.from} to=${message.to}`);
+};
+relay.onMessageSent = (message) => {
+    console.log(`message sent      → from=${message.from} to=${message.to}`);
+};
+relay.onAgentSpawned = (agent) => {
+    console.log(`agent spawned     → ${agent.name} (${agent.runtime})`);
+};
+relay.onAgentReleased = (agent) => {
+    console.log(`agent released    → ${agent.name}`);
+};
+relay.onAgentExited = (agent) => {
+    console.log(`agent exited      → ${agent.name}`);
+};
+// ── Create agents with sane defaults, running locally ───────────────────────
+const [codex, claude, gemini] = await Promise.all([
+    relay.codex.spawn(),
+    relay.claude.spawn(),
+    relay.gemini.spawn(),
+]);
+// ── Configure messaging with custom CLI agents ─────────────────────────────
+const worker1 = await relay.spawnPty({
+    name: "Worker1",
+    cli: "codex",
+    args: ["--model", "gpt-5"],
+    channels: ["general"],
+});
+// ── Control messaging from non-agent sources ────────────────────────────────
+const human = relay.human({ name: "System" });
+await human.sendMessage({ to: codex.name, text: "Hello, world!" });
+// ── List agents ─────────────────────────────────────────────────────────────
+const agents = await relay.listAgents();
+for (const agent of agents) {
+    console.log(`  ${agent.name}  runtime=${agent.runtime}  channels=[${agent.channels}]`);
+}
+for (const agent of agents) {
+    await agent.release();
+}
+await relay.shutdown();
+//# sourceMappingURL=quickstart.js.map

package/dist/examples/quickstart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quickstart.js","sourceRoot":"","sources":["../../src/examples/quickstart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,2DAA2D;AAC3D,8DAA8D;AAC9D,MAAM,KAAK,GAAG,IAAI,UAAU,EAAE,CAAC;AAE/B,+EAA+E;AAE/E,KAAK,CAAC,iBAAiB,GAAG,CAAC,OAAO,EAAE,EAAE;IACpC,OAAO,CAAC,GAAG,CAAC,4BAA4B,OAAO,CAAC,IAAI,OAAO,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;AAC3E,CAAC,CAAC;AAEF,KAAK,CAAC,aAAa,GAAG,CAAC,OAAO,EAAE,EAAE;IAChC,OAAO,CAAC,GAAG,CAAC,4BAA4B,OAAO,CAAC,IAAI,OAAO,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;AAC3E,CAAC,CAAC;AAEF,KAAK,CAAC,cAAc,GAAG,CAAC,KAAK,EAAE,EAAE;IAC/B,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC;AACtE,CAAC,CAAC;AAEF,KAAK,CAAC,eAAe,GAAG,CAAC,KAAK,EAAE,EAAE;IAChC,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AACnD,CAAC,CAAC;AAEF,KAAK,CAAC,aAAa,GAAG,CAAC,KAAK,EAAE,EAAE;IAC9B,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AACnD,CAAC,CAAC;AAEF,+EAA+E;AAE/E,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;IAChD,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE;IACnB,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE;IACpB,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE;CACrB,CAAC,CAAC;AAEH,8EAA8E;AAE9E,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC;IACnC,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,OAAO;IACZ,IAAI,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,CAAC,SAAS,CAAC;CACtB,CAAC,CAAC;AAEH,+EAA+E;AAE/E,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;AAC9C,MAAM,KAAK,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC;AAEnE,+EAA+E;AAE/E,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,UAAU,EAAE,CAAC;AACxC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,IAAI,aAAa,KAAK,CAAC,OAAO,eAAe,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC;AACzF,CAAC;AAED,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;IAC3B,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC"}

package/dist/examples/ralph-loop.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ralph-loop.d.ts.map

package/dist/examples/ralph-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ralph-loop.d.ts","sourceRoot":"","sources":["../../src/examples/ralph-loop.ts"],"names":[],"mappings":""}