multiclaws 0.3.0

package/dist/task/tracker.d.ts

@@ -0,0 +1,43 @@
+export type TaskStatus = "queued" | "running" | "completed" | "failed";
+export type TaskRecord = {
+    taskId: string;
+    fromPeerId: string;
+    toPeerId: string;
+    task: string;
+    context?: string;
+    status: TaskStatus;
+    createdAtMs: number;
+    updatedAtMs: number;
+    result?: string;
+    error?: string;
+};
+export declare class TaskTracker {
+    private readonly filePath;
+    private readonly ttlMs;
+    private readonly maxTasks;
+    private readonly store;
+    private pruneTimer;
+    private persistPending;
+    constructor(opts?: {
+        ttlMs?: number;
+        maxTasks?: number;
+        filePath?: string;
+    });
+    create(params: {
+        fromPeerId: string;
+        toPeerId: string;
+        task: string;
+        context?: string;
+    }): TaskRecord;
+    update(taskId: string, patch: Partial<Omit<TaskRecord, "taskId" | "createdAtMs">>): TaskRecord | null;
+    get(taskId: string): TaskRecord | null;
+    list(): TaskRecord[];
+    destroy(): void;
+    /** Sync load at startup — runs once before the event loop is busy. */
+    private loadStoreSync;
+    /** Coalesce rapid writes into a single async flush. */
+    private schedulePersist;
+    private persistAsync;
+    private prune;
+    private evictOldest;
+}

package/dist/task/tracker.js

@@ -0,0 +1,186 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskTracker = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = __importDefault(require("node:fs"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_TASKS = 10_000;
+const PRUNE_INTERVAL_MS = 60 * 60 * 1000;
+function emptyStore() {
+    return {
+        version: 1,
+        tasks: [],
+    };
+}
+function normalizeTask(task) {
+    if (!task ||
+        typeof task.taskId !== "string" ||
+        typeof task.fromPeerId !== "string" ||
+        typeof task.toPeerId !== "string" ||
+        typeof task.task !== "string" ||
+        typeof task.status !== "string" ||
+        typeof task.createdAtMs !== "number" ||
+        typeof task.updatedAtMs !== "number") {
+        return null;
+    }
+    return {
+        taskId: task.taskId,
+        fromPeerId: task.fromPeerId,
+        toPeerId: task.toPeerId,
+        task: task.task,
+        context: typeof task.context === "string" ? task.context : undefined,
+        status: task.status,
+        createdAtMs: task.createdAtMs,
+        updatedAtMs: task.updatedAtMs,
+        result: typeof task.result === "string" ? task.result : undefined,
+        error: typeof task.error === "string" ? task.error : undefined,
+    };
+}
+function normalizeStore(raw) {
+    if (raw.version !== 1 || !Array.isArray(raw.tasks)) {
+        return emptyStore();
+    }
+    const tasks = [];
+    for (const task of raw.tasks) {
+        const normalized = normalizeTask(task);
+        if (normalized) {
+            tasks.push(normalized);
+        }
+    }
+    return {
+        version: 1,
+        tasks,
+    };
+}
+class TaskTracker {
+    filePath;
+    ttlMs;
+    maxTasks;
+    store;
+    pruneTimer = null;
+    persistPending = false;
+    constructor(opts) {
+        this.ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
+        this.maxTasks = opts?.maxTasks ?? MAX_TASKS;
+        this.filePath = opts?.filePath ?? ".openclaw/multiclaws/tasks.json";
+        // Sync load at startup is acceptable (runs once)
+        this.store = this.loadStoreSync();
+        this.pruneTimer = setInterval(() => this.prune(), PRUNE_INTERVAL_MS);
+        if (this.pruneTimer && typeof this.pruneTimer === "object" && "unref" in this.pruneTimer) {
+            this.pruneTimer.unref();
+        }
+    }
+    create(params) {
+        if (this.store.tasks.length >= this.maxTasks) {
+            this.prune();
+        }
+        if (this.store.tasks.length >= this.maxTasks) {
+            this.evictOldest();
+        }
+        const now = Date.now();
+        const record = {
+            taskId: (0, node_crypto_1.randomUUID)(),
+            fromPeerId: params.fromPeerId,
+            toPeerId: params.toPeerId,
+            task: params.task,
+            context: params.context,
+            status: "queued",
+            createdAtMs: now,
+            updatedAtMs: now,
+        };
+        this.store.tasks.push(record);
+        this.schedulePersist();
+        return record;
+    }
+    update(taskId, patch) {
+        const index = this.store.tasks.findIndex((entry) => entry.taskId === taskId);
+        if (index < 0) {
+            return null;
+        }
+        const next = {
+            ...this.store.tasks[index],
+            ...patch,
+            updatedAtMs: Date.now(),
+        };
+        this.store.tasks[index] = next;
+        this.schedulePersist();
+        return next;
+    }
+    get(taskId) {
+        return this.store.tasks.find((entry) => entry.taskId === taskId) ?? null;
+    }
+    list() {
+        return [...this.store.tasks].sort((a, b) => b.updatedAtMs - a.updatedAtMs);
+    }
+    destroy() {
+        if (this.pruneTimer) {
+            clearInterval(this.pruneTimer);
+            this.pruneTimer = null;
+        }
+    }
+    /** Sync load at startup — runs once before the event loop is busy. */
+    loadStoreSync() {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(this.filePath), { recursive: true });
+        try {
+            const raw = JSON.parse(node_fs_1.default.readFileSync(this.filePath, "utf8"));
+            return normalizeStore(raw);
+        }
+        catch {
+            const store = emptyStore();
+            node_fs_1.default.writeFileSync(this.filePath, JSON.stringify(store, null, 2), "utf8");
+            return store;
+        }
+    }
+    /** Coalesce rapid writes into a single async flush. */
+    schedulePersist() {
+        if (this.persistPending)
+            return;
+        this.persistPending = true;
+        queueMicrotask(() => {
+            this.persistPending = false;
+            void this.persistAsync();
+        });
+    }
+    async persistAsync() {
+        try {
+            await promises_1.default.mkdir(node_path_1.default.dirname(this.filePath), { recursive: true });
+            const tmp = `${this.filePath}.${process.pid}.${Date.now()}.tmp`;
+            await promises_1.default.writeFile(tmp, JSON.stringify(this.store, null, 2), "utf8");
+            await promises_1.default.rename(tmp, this.filePath);
+        }
+        catch {
+            // best-effort persistence — in-memory state is authoritative
+        }
+    }
+    prune() {
+        const cutoff = Date.now() - this.ttlMs;
+        const before = this.store.tasks.length;
+        this.store.tasks = this.store.tasks.filter((task) => {
+            if (task.updatedAtMs >= cutoff) {
+                return true;
+            }
+            return task.status !== "completed" && task.status !== "failed";
+        });
+        if (this.store.tasks.length !== before) {
+            this.schedulePersist();
+        }
+    }
+    evictOldest() {
+        const removable = [...this.store.tasks]
+            .filter((task) => task.status === "completed" || task.status === "failed")
+            .sort((a, b) => a.updatedAtMs - b.updatedAtMs)
+            .slice(0, Math.max(1, Math.floor(this.maxTasks / 4)));
+        if (removable.length === 0) {
+            return;
+        }
+        const removeIds = new Set(removable.map((entry) => entry.taskId));
+        this.store.tasks = this.store.tasks.filter((entry) => !removeIds.has(entry.taskId));
+        this.schedulePersist();
+    }
+}
+exports.TaskTracker = TaskTracker;

package/dist/team/team-store.d.ts

@@ -0,0 +1,39 @@
+export type TeamMember = {
+    url: string;
+    name: string;
+    description?: string;
+    joinedAtMs: number;
+};
+export type TeamRecord = {
+    teamId: string;
+    teamName: string;
+    selfUrl: string;
+    members: TeamMember[];
+    createdAtMs: number;
+};
+export type InvitePayload = {
+    /** teamId */
+    t: string;
+    /** seed URL */
+    u: string;
+};
+export declare function encodeInvite(teamId: string, seedUrl: string): string;
+export declare function decodeInvite(code: string): InvitePayload;
+export declare class TeamStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    private readStore;
+    createTeam(params: {
+        teamName: string;
+        selfUrl: string;
+        selfName: string;
+        selfDescription?: string;
+    }): Promise<TeamRecord>;
+    getTeam(teamId: string): Promise<TeamRecord | null>;
+    listTeams(): Promise<TeamRecord[]>;
+    getFirstTeam(): Promise<TeamRecord | null>;
+    addMember(teamId: string, member: TeamMember): Promise<boolean>;
+    removeMember(teamId: string, memberUrl: string): Promise<boolean>;
+    deleteTeam(teamId: string): Promise<boolean>;
+    saveTeam(team: TeamRecord): Promise<void>;
+}

package/dist/team/team-store.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TeamStore = void 0;
+exports.encodeInvite = encodeInvite;
+exports.decodeInvite = decodeInvite;
+const node_crypto_1 = require("node:crypto");
+const json_store_1 = require("../infra/json-store");
+function emptyStore() {
+    return { version: 1, teams: [] };
+}
+function normalizeStore(raw) {
+    if (raw.version !== 1 || !Array.isArray(raw.teams)) {
+        return emptyStore();
+    }
+    return {
+        version: 1,
+        teams: raw.teams.filter((t) => t &&
+            typeof t.teamId === "string" &&
+            typeof t.teamName === "string" &&
+            Array.isArray(t.members)),
+    };
+}
+// ── Invite code helpers ──────────────────────────────────────────────
+const INVITE_PREFIX = "mc:";
+function encodeInvite(teamId, seedUrl) {
+    const payload = { t: teamId, u: seedUrl };
+    return INVITE_PREFIX + Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+function decodeInvite(code) {
+    const trimmed = code.trim();
+    const body = trimmed.startsWith(INVITE_PREFIX)
+        ? trimmed.slice(INVITE_PREFIX.length)
+        : trimmed;
+    try {
+        const json = Buffer.from(body, "base64url").toString("utf8");
+        const parsed = JSON.parse(json);
+        if (typeof parsed.t !== "string" || typeof parsed.u !== "string") {
+            throw new Error("invalid invite payload");
+        }
+        return parsed;
+    }
+    catch {
+        throw new Error("invalid invite code");
+    }
+}
+// ── TeamStore ────────────────────────────────────────────────────────
+class TeamStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async readStore() {
+        const store = await (0, json_store_1.readJsonWithFallback)(this.filePath, emptyStore());
+        return normalizeStore(store);
+    }
+    async createTeam(params) {
+        return await (0, json_store_1.withJsonLock)(this.filePath, emptyStore(), async () => {
+            const store = await this.readStore();
+            const now = Date.now();
+            const record = {
+                teamId: (0, node_crypto_1.randomUUID)(),
+                teamName: params.teamName,
+                selfUrl: params.selfUrl,
+                members: [{ url: params.selfUrl, name: params.selfName, description: params.selfDescription, joinedAtMs: now }],
+                createdAtMs: now,
+            };
+            store.teams.push(record);
+            await (0, json_store_1.writeJsonAtomically)(this.filePath, store);
+            return record;
+        });
+    }
+    async getTeam(teamId) {
+        const store = await this.readStore();
+        return store.teams.find((t) => t.teamId === teamId) ?? null;
+    }
+    async listTeams() {
+        const store = await this.readStore();
+        return [...store.teams];
+    }
+    async getFirstTeam() {
+        const store = await this.readStore();
+        return store.teams[0] ?? null;
+    }
+    async addMember(teamId, member) {
+        return await (0, json_store_1.withJsonLock)(this.filePath, emptyStore(), async () => {
+            const store = await this.readStore();
+            const team = store.teams.find((t) => t.teamId === teamId);
+            if (!team)
+                return false;
+            const normalizedUrl = member.url.replace(/\/+$/, "");
+            const existing = team.members.findIndex((m) => m.url.replace(/\/+$/, "") === normalizedUrl);
+            if (existing >= 0) {
+                team.members[existing].name = member.name;
+                if (member.description !== undefined) {
+                    team.members[existing].description = member.description;
+                }
+                team.members[existing].joinedAtMs = member.joinedAtMs;
+            }
+            else {
+                team.members.push({ ...member, url: normalizedUrl });
+            }
+            await (0, json_store_1.writeJsonAtomically)(this.filePath, store);
+            return true;
+        });
+    }
+    async removeMember(teamId, memberUrl) {
+        return await (0, json_store_1.withJsonLock)(this.filePath, emptyStore(), async () => {
+            const store = await this.readStore();
+            const team = store.teams.find((t) => t.teamId === teamId);
+            if (!team)
+                return false;
+            const normalizedUrl = memberUrl.replace(/\/+$/, "");
+            const before = team.members.length;
+            team.members = team.members.filter((m) => m.url.replace(/\/+$/, "") !== normalizedUrl);
+            if (team.members.length === before)
+                return false;
+            await (0, json_store_1.writeJsonAtomically)(this.filePath, store);
+            return true;
+        });
+    }
+    async deleteTeam(teamId) {
+        return await (0, json_store_1.withJsonLock)(this.filePath, emptyStore(), async () => {
+            const store = await this.readStore();
+            const before = store.teams.length;
+            store.teams = store.teams.filter((t) => t.teamId !== teamId);
+            if (store.teams.length === before)
+                return false;
+            await (0, json_store_1.writeJsonAtomically)(this.filePath, store);
+            return true;
+        });
+    }
+    async saveTeam(team) {
+        await (0, json_store_1.withJsonLock)(this.filePath, emptyStore(), async () => {
+            const store = await this.readStore();
+            const idx = store.teams.findIndex((t) => t.teamId === team.teamId);
+            if (idx >= 0) {
+                store.teams[idx] = team;
+            }
+            else {
+                store.teams.push(team);
+            }
+            await (0, json_store_1.writeJsonAtomically)(this.filePath, store);
+        });
+    }
+}
+exports.TeamStore = TeamStore;

package/dist/types/openclaw.d.ts

@@ -0,0 +1,86 @@
+export type GatewayRespond = (ok: boolean, payload?: unknown, error?: {
+    code?: string;
+    message?: string;
+    details?: unknown;
+}) => void;
+export type GatewayRequestHandler = (opts: {
+    params: Record<string, unknown>;
+    respond: GatewayRespond;
+}) => void | Promise<void>;
+export type PluginServiceContext = {
+    stateDir: string;
+    logger: {
+        info: (message: string) => void;
+        warn: (message: string) => void;
+        error: (message: string) => void;
+        debug?: (message: string) => void;
+    };
+};
+export type PluginService = {
+    id: string;
+    start: (ctx: PluginServiceContext) => void | Promise<void>;
+    stop?: (ctx?: PluginServiceContext) => void | Promise<void>;
+};
+export type PluginHookMessageContext = {
+    channelId: string;
+    accountId?: string;
+    conversationId?: string;
+};
+export type PluginHookMessageEvent = {
+    from: string;
+    content: string;
+    timestamp?: number;
+    metadata?: Record<string, unknown>;
+};
+export type PluginHookGatewayStartEvent = {
+    port: number;
+};
+export type PluginHookGatewayStopEvent = {
+    reason?: string;
+};
+export type PluginTool = {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (toolCallId: string, args: Record<string, unknown>) => Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        details?: unknown;
+    }>;
+};
+export type OpenClawGatewayConfig = {
+    port?: number;
+    auth?: {
+        mode?: string;
+        token?: string;
+        password?: string;
+    };
+};
+export type OpenClawPluginApi = {
+    config?: {
+        plugins?: Record<string, unknown>;
+        gateway?: OpenClawGatewayConfig;
+        [key: string]: unknown;
+    };
+    pluginConfig?: Record<string, unknown>;
+    logger: {
+        info: (message: string) => void;
+        warn: (message: string) => void;
+        error: (message: string) => void;
+        debug?: (message: string) => void;
+    };
+    registerService: (service: PluginService) => void;
+    registerGatewayMethod: (method: string, handler: GatewayRequestHandler) => void;
+    registerTool: (tool: PluginTool) => void;
+    registerHttpRoute: (route: {
+        path: string;
+        auth?: "plugin" | "gateway";
+        handler: (req: unknown, res: {
+            statusCode: number;
+            end: (body?: string) => void;
+        }) => void;
+    }) => void;
+    on: <K extends "message_received" | "gateway_start" | "gateway_stop">(name: K, handler: K extends "message_received" ? (event: PluginHookMessageEvent, ctx: PluginHookMessageContext) => void | Promise<void> : K extends "gateway_start" ? (event: PluginHookGatewayStartEvent) => void | Promise<void> : (event: PluginHookGatewayStopEvent) => void | Promise<void>) => void;
+};

package/dist/types/openclaw.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/openclaw.plugin.json

@@ -0,0 +1,34 @@
+{
+  "id": "multiclaws",
+  "name": "MultiClaws",
+  "description": "MultiClaws plugin for multi-instance collaboration using A2A protocol",
+  "version": "0.3.0",
+  "skills": ["./skills/multiclaws"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "port": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 65535,
+        "default": 3100
+      },
+      "displayName": {
+        "type": "string",
+        "minLength": 1
+      },
+      "selfUrl": {
+        "type": "string",
+        "description": "Publicly reachable URL for this agent. Auto-detected from hostname if not set."
+      },
+      "telemetry": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "consoleExporter": { "type": "boolean", "default": false }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "multiclaws",
+  "version": "0.3.0",
+  "description": "MultiClaws plugin for OpenClaw collaboration via A2A protocol",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "files": [
+    "dist",
+    "skills",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "multiclaws",
+    "a2a",
+    "collaboration"
+  ],
+  "author": "Eric Sun",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/EricSun0218/multiclaws.git"
+  },
+  "dependencies": {
+    "@a2a-js/sdk": "^0.3.10",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.6.0",
+    "@opentelemetry/sdk-trace-node": "^2.6.0",
+    "express": "^5.2.1",
+    "opossum": "^9.0.0",
+    "p-retry": "^7.1.1",
+    "proper-lockfile": "^4.1.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^24.3.0",
+    "@types/opossum": "^8.1.9",
+    "@types/proper-lockfile": "^4.1.4",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}