multiclaws 0.3.0

package/dist/infra/logger.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStructuredLogger = createStructuredLogger;
+/**
+ * Creates a structured logger that delegates to OpenClaw's base logger.
+ * Only outputs via baseLogger to avoid duplicate stdout writes.
+ */
+function createStructuredLogger(baseLogger, _name = "multiclaws") {
+    const bridge = {
+        info: (message) => baseLogger.info(message),
+        warn: (message) => baseLogger.warn(message),
+        error: (message) => baseLogger.error(message),
+        debug: (message) => baseLogger.debug?.(message),
+    };
+    return {
+        logger: bridge,
+    };
+}

package/dist/infra/rate-limiter.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Simple sliding-window rate limiter keyed by peer ID.
+ * Returns true if the request should be allowed, false if rate-limited.
+ * Periodically prunes empty/stale keys to prevent unbounded memory growth.
+ */
+export declare class RateLimiter {
+    private readonly windowMs;
+    private readonly maxRequests;
+    private readonly windows;
+    private pruneTimer;
+    constructor(opts?: {
+        windowMs?: number;
+        maxRequests?: number;
+    });
+    allow(key: string): boolean;
+    reset(key: string): void;
+    destroy(): void;
+    private pruneStaleKeys;
+}

package/dist/infra/rate-limiter.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = void 0;
+/**
+ * Simple sliding-window rate limiter keyed by peer ID.
+ * Returns true if the request should be allowed, false if rate-limited.
+ * Periodically prunes empty/stale keys to prevent unbounded memory growth.
+ */
+class RateLimiter {
+    windowMs;
+    maxRequests;
+    windows = new Map();
+    pruneTimer = null;
+    constructor(opts) {
+        this.windowMs = opts?.windowMs ?? 60_000;
+        this.maxRequests = opts?.maxRequests ?? 60;
+        // Prune stale keys every 5 minutes
+        this.pruneTimer = setInterval(() => this.pruneStaleKeys(), 5 * 60_000);
+        if (this.pruneTimer && typeof this.pruneTimer === "object" && "unref" in this.pruneTimer) {
+            this.pruneTimer.unref();
+        }
+    }
+    allow(key) {
+        const now = Date.now();
+        const cutoff = now - this.windowMs;
+        let timestamps = this.windows.get(key);
+        if (!timestamps) {
+            timestamps = [];
+            this.windows.set(key, timestamps);
+        }
+        // Binary search for the first timestamp within the window, then
+        // bulk-remove all expired entries in one splice (O(log n) + O(k)).
+        let lo = 0;
+        let hi = timestamps.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            if (timestamps[mid] < cutoff)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        if (lo > 0)
+            timestamps.splice(0, lo);
+        if (timestamps.length >= this.maxRequests) {
+            return false;
+        }
+        timestamps.push(now);
+        return true;
+    }
+    reset(key) {
+        this.windows.delete(key);
+    }
+    destroy() {
+        if (this.pruneTimer) {
+            clearInterval(this.pruneTimer);
+            this.pruneTimer = null;
+        }
+        this.windows.clear();
+    }
+    pruneStaleKeys() {
+        const cutoff = Date.now() - this.windowMs;
+        for (const [key, timestamps] of this.windows) {
+            if (timestamps.length === 0 || timestamps[timestamps.length - 1] < cutoff) {
+                this.windows.delete(key);
+            }
+        }
+    }
+}
+exports.RateLimiter = RateLimiter;

package/dist/infra/tailscale.d.ts

@@ -0,0 +1,19 @@
+export type TailscaleStatus = {
+    status: "ready";
+    ip: string;
+} | {
+    status: "needs_auth";
+    authUrl: string;
+} | {
+    status: "not_installed";
+} | {
+    status: "unavailable";
+    reason: string;
+};
+/** Check network interfaces for a Tailscale IP (100.x.x.x) — exported for fast-path checks */
+export declare function getTailscaleIpFromInterfaces(): string | null;
+/**
+ * Detect Tailscale status — does NOT install or modify system state.
+ * Returns one of: ready | needs_auth | not_installed | unavailable
+ */
+export declare function detectTailscale(): Promise<TailscaleStatus>;

package/dist/infra/tailscale.js

@@ -0,0 +1,120 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTailscaleIpFromInterfaces = getTailscaleIpFromInterfaces;
+exports.detectTailscale = detectTailscale;
+const node_child_process_1 = require("node:child_process");
+const node_os_1 = __importDefault(require("node:os"));
+function run(cmd, timeoutMs = 5_000) {
+    return (0, node_child_process_1.execSync)(cmd, { timeout: timeoutMs, stdio: ["ignore", "pipe", "pipe"] })
+        .toString()
+        .trim();
+}
+function commandExists(cmd) {
+    try {
+        run(`which ${cmd}`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Check network interfaces for a Tailscale IP (100.x.x.x) — exported for fast-path checks */
+function getTailscaleIpFromInterfaces() {
+    const interfaces = node_os_1.default.networkInterfaces();
+    for (const addrs of Object.values(interfaces)) {
+        if (!addrs)
+            continue;
+        for (const addr of addrs) {
+            if (addr.family === "IPv4" && addr.address.startsWith("100.")) {
+                return addr.address;
+            }
+        }
+    }
+    return null;
+}
+/** Ask tailscale CLI for the IP */
+function getTailscaleIpFromCli() {
+    try {
+        const ip = run("tailscale ip -4").split("\n")[0];
+        return ip || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Check if tailscale daemon is running and authenticated */
+function isAuthenticated() {
+    try {
+        const out = run("tailscale status --json");
+        const json = JSON.parse(out);
+        return json.BackendState === "Running";
+    }
+    catch {
+        return false;
+    }
+}
+/** Get auth URL from `tailscale up` output (non-blocking, reads stderr/stdout for a few seconds) */
+async function getAuthUrl() {
+    return new Promise((resolve) => {
+        try {
+            // tailscale up prints the auth URL to stderr
+            const { spawn } = require("node:child_process");
+            const proc = spawn("tailscale", ["up"], { stdio: ["ignore", "pipe", "pipe"] });
+            let output = "";
+            let resolved = false;
+            const tryResolve = (text) => {
+                const match = text.match(/https:\/\/login\.tailscale\.com\/[^\s]+/);
+                if (match && !resolved) {
+                    resolved = true;
+                    proc.kill();
+                    resolve(match[0]);
+                }
+            };
+            proc.stdout?.on("data", (d) => { output += d.toString(); tryResolve(output); });
+            proc.stderr?.on("data", (d) => { output += d.toString(); tryResolve(output); });
+            proc.on("close", () => { if (!resolved) {
+                resolved = true;
+                resolve(null);
+            } });
+            setTimeout(() => { if (!resolved) {
+                resolved = true;
+                proc.kill();
+                resolve(null);
+            } }, 8_000);
+        }
+        catch {
+            resolve(null);
+        }
+    });
+}
+/**
+ * Detect Tailscale status — does NOT install or modify system state.
+ * Returns one of: ready | needs_auth | not_installed | unavailable
+ */
+async function detectTailscale() {
+    // Fast path: check network interfaces first (no subprocess)
+    const ifaceIp = getTailscaleIpFromInterfaces();
+    if (ifaceIp) {
+        return { status: "ready", ip: ifaceIp };
+    }
+    // Not installed
+    if (!commandExists("tailscale")) {
+        return { status: "not_installed" };
+    }
+    // Installed but check auth
+    if (isAuthenticated()) {
+        const ip = getTailscaleIpFromCli();
+        if (ip)
+            return { status: "ready", ip };
+        return { status: "unavailable", reason: "authenticated but no IP assigned" };
+    }
+    // Needs auth — try to get login URL
+    const authUrl = await getAuthUrl();
+    if (authUrl) {
+        return { status: "needs_auth", authUrl };
+    }
+    return { status: "unavailable", reason: "could not determine auth URL" };
+}

package/dist/infra/telemetry.d.ts

@@ -0,0 +1,3 @@
+export declare function initializeTelemetry(params?: {
+    enableConsoleExporter?: boolean;
+}): void;

package/dist/infra/telemetry.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeTelemetry = initializeTelemetry;
+const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
+const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
+let initialized = false;
+function initializeTelemetry(params) {
+    if (initialized) {
+        return;
+    }
+    const spanProcessors = (params?.enableConsoleExporter || process.env.MULTICLAWS_OTEL_CONSOLE === "1")
+        ? [new sdk_trace_base_1.SimpleSpanProcessor(new sdk_trace_base_1.ConsoleSpanExporter())]
+        : [];
+    const provider = new sdk_trace_node_1.NodeTracerProvider({ spanProcessors });
+    provider.register();
+    initialized = true;
+}

package/dist/service/a2a-adapter.d.ts

@@ -0,0 +1,44 @@
+import type { AgentExecutor, ExecutionEventBus, RequestContext } from "@a2a-js/sdk/server";
+import { type GatewayConfig } from "../infra/gateway-client";
+import type { TaskTracker } from "../task/tracker";
+export type A2AAdapterOptions = {
+    gatewayConfig: GatewayConfig | null;
+    taskTracker: TaskTracker;
+    logger: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+};
+/**
+ * Bridges the A2A protocol to OpenClaw's sessions_spawn gateway tool.
+ *
+ * When a remote agent sends a task via A2A `message/send`,
+ * this executor:
+ * 1. Records the task via TaskTracker
+ * 2. Calls OpenClaw's `sessions_spawn` (run mode) to start execution
+ * 3. Polls `sessions_history` until the subagent completes
+ * 4. Returns the final result as a Message
+ */
+export declare class OpenClawAgentExecutor implements AgentExecutor {
+    private gatewayConfig;
+    private readonly taskTracker;
+    private readonly logger;
+    constructor(options: A2AAdapterOptions);
+    execute(context: RequestContext, eventBus: ExecutionEventBus): Promise<void>;
+    /**
+     * Poll sessions_history until the subagent produces a final assistant message.
+     * Uses backoff: 2s, 3s, 4s, then 5s intervals.
+     */
+    private waitForCompletion;
+    /**
+     * Extract the final assistant response from session history.
+     * Returns null if the session is still running.
+     *
+     * Gateway /tools/invoke returns: { content: [...], details: { messages: [...], isComplete?: boolean } }
+     */
+    private extractCompletedResult;
+    cancelTask(taskId: string, eventBus: ExecutionEventBus): Promise<void>;
+    updateGatewayConfig(config: GatewayConfig): void;
+    private publishMessage;
+}

package/dist/service/a2a-adapter.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenClawAgentExecutor = void 0;
+const gateway_client_1 = require("../infra/gateway-client");
+function extractTextFromMessage(message) {
+    if (!message.parts)
+        return "";
+    return message.parts
+        .filter((p) => p.kind === "text")
+        .map((p) => p.text)
+        .join("\n");
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Extract the details object from a gateway /tools/invoke result.
+ * The result shape is: { content: [...], details: { ...actual data... } }
+ */
+function extractDetails(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const r = result;
+    // Direct details from /tools/invoke
+    if (r.details && typeof r.details === "object") {
+        return r.details;
+    }
+    // Fallback: result itself might be the details
+    return r;
+}
+/**
+ * Bridges the A2A protocol to OpenClaw's sessions_spawn gateway tool.
+ *
+ * When a remote agent sends a task via A2A `message/send`,
+ * this executor:
+ * 1. Records the task via TaskTracker
+ * 2. Calls OpenClaw's `sessions_spawn` (run mode) to start execution
+ * 3. Polls `sessions_history` until the subagent completes
+ * 4. Returns the final result as a Message
+ */
+class OpenClawAgentExecutor {
+    gatewayConfig;
+    taskTracker;
+    logger;
+    constructor(options) {
+        this.gatewayConfig = options.gatewayConfig;
+        this.taskTracker = options.taskTracker;
+        this.logger = options.logger;
+    }
+    async execute(context, eventBus) {
+        const taskText = extractTextFromMessage(context.userMessage);
+        const taskId = context.taskId;
+        if (!taskText.trim()) {
+            this.publishMessage(eventBus, "Error: empty task received.");
+            eventBus.finished();
+            return;
+        }
+        const fromAgent = context.userMessage.metadata?.agentUrl ?? "unknown";
+        this.taskTracker.create({
+            fromPeerId: fromAgent,
+            toPeerId: "local",
+            task: taskText,
+        });
+        if (!this.gatewayConfig) {
+            this.logger.error("[a2a-adapter] gateway config not available, cannot execute task");
+            this.taskTracker.update(taskId, { status: "failed", error: "gateway config not available" });
+            this.publishMessage(eventBus, "Error: gateway config not available, cannot execute task.");
+            eventBus.finished();
+            return;
+        }
+        try {
+            this.logger.info(`[a2a-adapter] executing task ${taskId}: ${taskText.slice(0, 100)}`);
+            // 1. Spawn the subagent
+            const spawnResult = await (0, gateway_client_1.invokeGatewayTool)({
+                gateway: this.gatewayConfig,
+                tool: "sessions_spawn",
+                args: {
+                    task: taskText,
+                    mode: "run",
+                },
+                timeoutMs: 15_000,
+            });
+            // Extract details from gateway response: { content: [...], details: { childSessionKey, ... } }
+            const details = extractDetails(spawnResult);
+            const childSessionKey = details?.childSessionKey;
+            if (!childSessionKey) {
+                throw new Error("sessions_spawn did not return a childSessionKey");
+            }
+            // 2. Poll for completion
+            this.logger.info(`[a2a-adapter] task ${taskId} spawned as ${childSessionKey}, waiting for result...`);
+            const output = await this.waitForCompletion(childSessionKey, 180_000);
+            // 3. Return result
+            this.taskTracker.update(taskId, { status: "completed", result: output });
+            this.logger.info(`[a2a-adapter] task ${taskId} completed`);
+            this.publishMessage(eventBus, output || "Task completed with no output.");
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            this.logger.error(`[a2a-adapter] task execution failed: ${errorMsg}`);
+            this.taskTracker.update(taskId, { status: "failed", error: errorMsg });
+            this.publishMessage(eventBus, `Error: ${errorMsg}`);
+        }
+        eventBus.finished();
+    }
+    /**
+     * Poll sessions_history until the subagent produces a final assistant message.
+     * Uses backoff: 2s, 3s, 4s, then 5s intervals.
+     */
+    async waitForCompletion(sessionKey, timeoutMs) {
+        const gateway = this.gatewayConfig;
+        const startTime = Date.now();
+        let attempt = 0;
+        // Aggressive early polls, then back off: 300ms, 500ms, 1s, 2s, 3s, 3s...
+        const pollDelays = [300, 500, 1000, 2000, 3000];
+        while (Date.now() - startTime < timeoutMs) {
+            const delay = pollDelays[Math.min(attempt, pollDelays.length - 1)];
+            await sleep(delay);
+            attempt++;
+            try {
+                const histResult = await (0, gateway_client_1.invokeGatewayTool)({
+                    gateway,
+                    tool: "sessions_history",
+                    args: {
+                        sessionKey,
+                        limit: 20,
+                        includeTools: false,
+                    },
+                    timeoutMs: 8_000,
+                });
+                const result = this.extractCompletedResult(histResult);
+                if (result !== null) {
+                    return result;
+                }
+                this.logger.info(`[a2a-adapter] poll attempt ${attempt}: session ${sessionKey} still running...`);
+            }
+            catch (err) {
+                this.logger.warn(`[a2a-adapter] poll attempt ${attempt} error: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        throw new Error(`task timed out after ${Math.round(timeoutMs / 1000)}s waiting for subagent`);
+    }
+    /**
+     * Extract the final assistant response from session history.
+     * Returns null if the session is still running.
+     *
+     * Gateway /tools/invoke returns: { content: [...], details: { messages: [...], isComplete?: boolean } }
+     */
+    extractCompletedResult(histResult) {
+        const details = extractDetails(histResult);
+        if (!details)
+            return null;
+        // Respect explicit completion flag from gateway
+        if (details.isComplete === false)
+            return null;
+        const messages = (details.messages ?? []);
+        if (messages.length === 0)
+            return null;
+        // If no explicit flag, check the last message for signs of ongoing execution
+        if (details.isComplete === undefined) {
+            const lastMsg = messages[messages.length - 1];
+            if (lastMsg && Array.isArray(lastMsg.content)) {
+                const content = lastMsg.content;
+                const hasToolCalls = content.some((c) => c?.type === "toolCall" || c?.type === "tool_use");
+                const hasText = content.some((c) => c?.type === "text" && typeof c.text === "string" && c.text.trim());
+                if (hasToolCalls && !hasText)
+                    return null;
+            }
+        }
+        // Walk backwards to find the last assistant message with text content
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const msg = messages[i];
+            if (msg.role !== "assistant")
+                continue;
+            const content = msg.content;
+            if (typeof content === "string" && content.trim()) {
+                return content;
+            }
+            if (Array.isArray(content)) {
+                const parts = content;
+                const textParts = parts
+                    .filter((c) => c?.type === "text" && typeof c.text === "string" && c.text.trim())
+                    .map((c) => c.text);
+                if (textParts.length > 0) {
+                    return textParts.join("\n");
+                }
+            }
+        }
+        return null;
+    }
+    async cancelTask(taskId, eventBus) {
+        this.taskTracker.update(taskId, { status: "failed", error: "canceled" });
+        this.publishMessage(eventBus, "Task was canceled.");
+        eventBus.finished();
+    }
+    updateGatewayConfig(config) {
+        this.gatewayConfig = config;
+    }
+    publishMessage(eventBus, text) {
+        const message = {
+            kind: "message",
+            role: "agent",
+            messageId: `msg-${Date.now()}`,
+            parts: [{ kind: "text", text }],
+        };
+        eventBus.publish(message);
+    }
+}
+exports.OpenClawAgentExecutor = OpenClawAgentExecutor;

package/dist/service/agent-profile.d.ts

@@ -0,0 +1,13 @@
+export type AgentProfile = {
+    ownerName: string;
+    /** Free-form markdown describing this agent: role, capabilities, data sources, etc. */
+    bio: string;
+};
+export declare function renderProfileDescription(profile: AgentProfile): string;
+export declare class ProfileStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    load(): Promise<AgentProfile>;
+    save(profile: AgentProfile): Promise<void>;
+    update(patch: Partial<AgentProfile>): Promise<AgentProfile>;
+}

package/dist/service/agent-profile.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProfileStore = void 0;
+exports.renderProfileDescription = renderProfileDescription;
+const json_store_1 = require("../infra/json-store");
+function emptyProfile() {
+    return { ownerName: "", bio: "" };
+}
+function renderProfileDescription(profile) {
+    const parts = [];
+    if (profile.ownerName)
+        parts.push(profile.ownerName);
+    if (profile.bio)
+        parts.push(profile.bio);
+    return parts.join("\n\n") || "OpenClaw agent";
+}
+class ProfileStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async load() {
+        return await (0, json_store_1.readJsonWithFallback)(this.filePath, emptyProfile());
+    }
+    async save(profile) {
+        await (0, json_store_1.writeJsonAtomically)(this.filePath, profile);
+    }
+    async update(patch) {
+        const profile = await this.load();
+        if (patch.ownerName !== undefined)
+            profile.ownerName = patch.ownerName;
+        if (patch.bio !== undefined)
+            profile.bio = patch.bio;
+        await this.save(profile);
+        return profile;
+    }
+}
+exports.ProfileStore = ProfileStore;

package/dist/service/agent-registry.d.ts

@@ -0,0 +1,26 @@
+export type AgentRecord = {
+    url: string;
+    name: string;
+    description: string;
+    skills: string[];
+    apiKey?: string;
+    addedAtMs: number;
+    lastSeenAtMs: number;
+};
+export declare class AgentRegistry {
+    private readonly filePath;
+    constructor(filePath: string);
+    private readStore;
+    add(params: {
+        url: string;
+        name: string;
+        description?: string;
+        skills?: string[];
+        apiKey?: string;
+    }): Promise<AgentRecord>;
+    remove(url: string): Promise<boolean>;
+    list(): Promise<AgentRecord[]>;
+    get(url: string): Promise<AgentRecord | null>;
+    updateDescription(url: string, description: string): Promise<void>;
+    updateLastSeen(url: string): Promise<void>;
+}