@cleocode/cleo-os 2026.4.13 → 2026.4.17

package/extensions/cleo-chatroom.js

@@ -0,0 +1,344 @@
+/**
+ * CleoOS chat room — inter-agent messaging TUI.
+ *
+ * Installed to: $CLEO_HOME/pi-extensions/cleo-chatroom.ts
+ * Loaded by:    Pi via `-e <path>` or settings.json extensions array
+ *
+ * Wave 7 — surfaces inter-agent traffic as a TUI panel per ULTRAPLAN
+ * section 13. Agents communicate through four tools:
+ *
+ *   - `send_to_lead`            — worker sends a message to their lead.
+ *   - `broadcast_to_team`       — lead broadcasts to all group workers.
+ *   - `report_to_orchestrator`  — lead reports status to the orchestrator.
+ *   - `query_peer`              — worker queries another worker in the same group.
+ *
+ * Each tool appends a structured JSONL entry to the Pi session's message
+ * log. A TUI widget (registered on `session_start`) renders the last N
+ * messages in a scrollable panel below the editor.
+ *
+ * This is a TEMPLATE extension — it uses `import type` for Pi types and
+ * mirrors the patterns established by the existing extensions in
+ * `packages/cleo/templates/cleoos-hub/pi-extensions/`.
+ *
+ * @packageDocumentation
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { Type } from "@sinclair/typebox";
+// ---------------------------------------------------------------------------
+// Module state
+// ---------------------------------------------------------------------------
+const WIDGET_KEY = "cleo-chatroom";
+const STATUS_KEY = "cleo-chatroom";
+const MAX_DISPLAY_MESSAGES = 15;
+/** In-memory message buffer for the current session. */
+const messages = [];
+/** Path to the JSONL log file (set on session_start). */
+let logPath = null;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Record a chat message: push to the in-memory buffer and append to the
+ * JSONL log file. The log file is created lazily on first write.
+ *
+ * @param msg - The chat message to record.
+ */
+function recordMessage(msg) {
+    messages.push(msg);
+    if (logPath) {
+        try {
+            appendFileSync(logPath, JSON.stringify(msg) + "\n", "utf-8");
+        }
+        catch {
+            // Best-effort: never crash Pi over a log write failure.
+        }
+    }
+}
+/**
+ * Return the single-character tier prefix for a chat message row.
+ *
+ * - `[O]` orchestrator (green in ANSI-capable terminals)
+ * - `[L]` lead         (yellow)
+ * - `[W]` worker       (blue, default)
+ *
+ * @param role - The sending agent's tier role, or `undefined` to default to worker.
+ * @returns The three-character prefix string.
+ */
+export function tierPrefix(role) {
+    switch (role) {
+        case "orchestrator":
+            return "[O]";
+        case "lead":
+            return "[L]";
+        default:
+            return "[W]";
+    }
+}
+/**
+ * Format a chat message for TUI display.
+ *
+ * Each row is prefixed with a tier indicator ([O]/[L]/[W]) so orchestrator,
+ * lead, and worker traffic is visually distinct in the chat panel (ULTRAPLAN §13).
+ *
+ * @param msg - The message to format.
+ * @returns A single-line string representation.
+ */
+export function formatMessage(msg) {
+    const time = msg.timestamp.slice(11, 19);
+    const prefix = tierPrefix(msg.role);
+    return `${prefix} [${time}] ${msg.from} -> ${msg.to}: ${msg.text}`;
+}
+/**
+ * Render the chat room widget with the latest messages.
+ *
+ * @param ctx - The Pi extension context.
+ */
+function renderWidget(ctx) {
+    if (!ctx.hasUI)
+        return;
+    const tail = messages.slice(-MAX_DISPLAY_MESSAGES);
+    if (tail.length === 0) {
+        ctx.ui.setWidget(WIDGET_KEY, ["(no messages yet)"], {
+            placement: "belowEditor",
+        });
+        return;
+    }
+    const lines = tail.map(formatMessage);
+    ctx.ui.setWidget(WIDGET_KEY, lines, { placement: "belowEditor" });
+    ctx.ui.setStatus(STATUS_KEY, `Chat: ${messages.length} msg(s)`);
+}
+// ---------------------------------------------------------------------------
+// Tool parameter schemas (TypeBox)
+// ---------------------------------------------------------------------------
+const SendToLeadParams = Type.Object({
+    message: Type.String({ description: "Message to send to your team lead" }),
+    from: Type.String({ description: "Your agent name" }),
+    lead: Type.String({ description: "Name of the lead agent" }),
+    role: Type.Optional(Type.Union([
+        Type.Literal("orchestrator"),
+        Type.Literal("lead"),
+        Type.Literal("worker"),
+    ], { description: "Tier role of the sending agent for TUI row styling" })),
+});
+const BroadcastToTeamParams = Type.Object({
+    message: Type.String({ description: "Message to broadcast to the team" }),
+    from: Type.String({ description: "Your agent name (lead)" }),
+    group: Type.String({ description: "Team group name (e.g. 'backend')" }),
+    role: Type.Optional(Type.Union([
+        Type.Literal("orchestrator"),
+        Type.Literal("lead"),
+        Type.Literal("worker"),
+    ], { description: "Tier role of the sending agent for TUI row styling" })),
+});
+const ReportToOrchestratorParams = Type.Object({
+    message: Type.String({ description: "Status report for the orchestrator" }),
+    from: Type.String({ description: "Your agent name (lead)" }),
+    orchestrator: Type.String({
+        description: "Name of the orchestrator agent",
+    }),
+    role: Type.Optional(Type.Union([
+        Type.Literal("orchestrator"),
+        Type.Literal("lead"),
+        Type.Literal("worker"),
+    ], { description: "Tier role of the sending agent for TUI row styling" })),
+});
+const QueryPeerParams = Type.Object({
+    message: Type.String({ description: "Query for your peer worker" }),
+    from: Type.String({ description: "Your agent name" }),
+    peer: Type.String({ description: "Name of the peer worker to query" }),
+    role: Type.Optional(Type.Union([
+        Type.Literal("orchestrator"),
+        Type.Literal("lead"),
+        Type.Literal("worker"),
+    ], { description: "Tier role of the sending agent for TUI row styling" })),
+});
+// ---------------------------------------------------------------------------
+// Pi extension factory
+// ---------------------------------------------------------------------------
+/**
+ * Pi extension factory for the CleoOS chat room.
+ *
+ * Registers four inter-agent communication tools and a TUI widget that
+ * displays the message stream. Also registers `/cleo:chat-info` for
+ * introspection and clears state on session shutdown.
+ *
+ * @param pi - The Pi extension API instance.
+ */
+export default function (pi) {
+    // -------------------------------------------------------------------------
+    // session_start: initialize log directory and widget
+    // -------------------------------------------------------------------------
+    pi.on("session_start", async (_event, ctx) => {
+        messages.length = 0;
+        logPath = null;
+        try {
+            const chatDir = join(ctx.cwd, ".cleo", "chat");
+            mkdirSync(chatDir, { recursive: true });
+            const sessionTs = new Date().toISOString().replace(/[:.]/g, "-");
+            logPath = join(chatDir, `chatroom-${sessionTs}.jsonl`);
+        }
+        catch {
+            // Best-effort: widget still works without persistent logging.
+        }
+        renderWidget(ctx);
+        if (ctx.hasUI) {
+            ctx.ui.setStatus(STATUS_KEY, "Chat: ready");
+        }
+    });
+    // -------------------------------------------------------------------------
+    // Tools: send_to_lead
+    // -------------------------------------------------------------------------
+    pi.registerTool({
+        name: "send_to_lead",
+        label: "Send to Lead",
+        description: "Send a message from a worker agent to their team lead. " +
+            "Used for status updates, questions, and escalations.",
+        parameters: SendToLeadParams,
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const msg = {
+                timestamp: new Date().toISOString(),
+                from: params.from,
+                to: params.lead,
+                channel: "send_to_lead",
+                text: params.message,
+                role: params.role,
+            };
+            recordMessage(msg);
+            renderWidget(ctx);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Message sent to lead ${params.lead}: ${params.message}`,
+                    },
+                ],
+            };
+        },
+    });
+    // -------------------------------------------------------------------------
+    // Tools: broadcast_to_team
+    // -------------------------------------------------------------------------
+    pi.registerTool({
+        name: "broadcast_to_team",
+        label: "Broadcast to Team",
+        description: "Broadcast a message from a lead to all workers in their group. " +
+            "Used for coordination directives and status announcements.",
+        parameters: BroadcastToTeamParams,
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const msg = {
+                timestamp: new Date().toISOString(),
+                from: params.from,
+                to: `team:${params.group}`,
+                channel: "broadcast_to_team",
+                text: params.message,
+                role: params.role,
+            };
+            recordMessage(msg);
+            renderWidget(ctx);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Broadcast to team:${params.group}: ${params.message}`,
+                    },
+                ],
+            };
+        },
+    });
+    // -------------------------------------------------------------------------
+    // Tools: report_to_orchestrator
+    // -------------------------------------------------------------------------
+    pi.registerTool({
+        name: "report_to_orchestrator",
+        label: "Report to Orchestrator",
+        description: "Send a status report from a lead to the orchestrator. " +
+            "Used for task completion reports, blockers, and escalations.",
+        parameters: ReportToOrchestratorParams,
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const msg = {
+                timestamp: new Date().toISOString(),
+                from: params.from,
+                to: params.orchestrator,
+                channel: "report_to_orchestrator",
+                text: params.message,
+                role: params.role,
+            };
+            recordMessage(msg);
+            renderWidget(ctx);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Report sent to orchestrator ${params.orchestrator}: ${params.message}`,
+                    },
+                ],
+            };
+        },
+    });
+    // -------------------------------------------------------------------------
+    // Tools: query_peer
+    // -------------------------------------------------------------------------
+    pi.registerTool({
+        name: "query_peer",
+        label: "Query Peer",
+        description: "Send a query from one worker to a peer worker in the same group. " +
+            "Used for cross-agent information sharing and coordination.",
+        parameters: QueryPeerParams,
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            const msg = {
+                timestamp: new Date().toISOString(),
+                from: params.from,
+                to: params.peer,
+                channel: "query_peer",
+                text: params.message,
+                role: params.role,
+            };
+            recordMessage(msg);
+            renderWidget(ctx);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Query sent to peer ${params.peer}: ${params.message}`,
+                    },
+                ],
+            };
+        },
+    });
+    // -------------------------------------------------------------------------
+    // Command: /cleo:chat-info — introspection
+    // -------------------------------------------------------------------------
+    pi.registerCommand("cleo:chat-info", {
+        description: "Show chat room status and recent messages",
+        handler: async (_args, ctx) => {
+            const tail = messages.slice(-5);
+            const lines = [
+                `Chat Room: ${messages.length} total message(s)`,
+                `Log: ${logPath ?? "(none)"}`,
+                "",
+                "Recent messages:",
+                ...tail.map(formatMessage),
+            ];
+            if (tail.length === 0) {
+                lines.push("  (no messages yet)");
+            }
+            pi.sendMessage({
+                customType: "cleo-chatroom-info",
+                content: lines.join("\n"),
+                display: true,
+            }, { triggerTurn: false });
+            if (ctx.hasUI) {
+                ctx.ui.notify(`Chat room: ${messages.length} messages`, "info");
+            }
+        },
+    });
+    // -------------------------------------------------------------------------
+    // session_shutdown: clear state
+    // -------------------------------------------------------------------------
+    pi.on("session_shutdown", async () => {
+        messages.length = 0;
+        logPath = null;
+    });
+}
+//# sourceMappingURL=cleo-chatroom.js.map

package/extensions/cleo-chatroom.js.map

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

package/extensions/cleo-chatroom.ts

@@ -36,8 +36,14 @@ import { Type } from "@sinclair/typebox";
 // Message model
 // ---------------------------------------------------------------------------
 
+/**
+ * Tier role of an agent in the 3-tier hierarchy (ULTRAPLAN §10).
+ * Used to apply distinct TUI styling per tier.
+ */
+export type AgentTierRole = "orchestrator" | "lead" | "worker";
+
 /** A single inter-agent chat message. */
-interface ChatMessage {
+export interface ChatMessage {
   /** ISO-8601 timestamp of when the message was created. */
   timestamp: string;
   /** Name of the sending agent. */
@@ -48,6 +54,14 @@ interface ChatMessage {
   channel: "send_to_lead" | "broadcast_to_team" | "report_to_orchestrator" | "query_peer";
   /** The message text. */
   text: string;
+  /**
+   * Optional tier role of the sending agent.
+   *
+   * When present, the TUI row is prefixed and (if ANSI is available)
+   * coloured by tier: orchestrator = green ([O]), lead = yellow ([L]),
+   * worker = blue ([W]).  Defaults to "worker" when absent.
+   */
+  role?: AgentTierRole;
 }
 
 // ---------------------------------------------------------------------------
@@ -85,15 +99,40 @@ function recordMessage(msg: ChatMessage): void {
   }
 }
 
+/**
+ * Return the single-character tier prefix for a chat message row.
+ *
+ * - `[O]` orchestrator (green in ANSI-capable terminals)
+ * - `[L]` lead         (yellow)
+ * - `[W]` worker       (blue, default)
+ *
+ * @param role - The sending agent's tier role, or `undefined` to default to worker.
+ * @returns The three-character prefix string.
+ */
+export function tierPrefix(role: AgentTierRole | undefined): string {
+  switch (role) {
+    case "orchestrator":
+      return "[O]";
+    case "lead":
+      return "[L]";
+    default:
+      return "[W]";
+  }
+}
+
 /**
  * Format a chat message for TUI display.
  *
+ * Each row is prefixed with a tier indicator ([O]/[L]/[W]) so orchestrator,
+ * lead, and worker traffic is visually distinct in the chat panel (ULTRAPLAN §13).
+ *
  * @param msg - The message to format.
  * @returns A single-line string representation.
  */
-function formatMessage(msg: ChatMessage): string {
+export function formatMessage(msg: ChatMessage): string {
   const time = msg.timestamp.slice(11, 19);
-  return `[${time}] ${msg.from} -> ${msg.to}: ${msg.text}`;
+  const prefix = tierPrefix(msg.role);
+  return `${prefix} [${time}] ${msg.from} -> ${msg.to}: ${msg.text}`;
 }
 
 /**
@@ -123,12 +162,26 @@ const SendToLeadParams = Type.Object({
   message: Type.String({ description: "Message to send to your team lead" }),
   from: Type.String({ description: "Your agent name" }),
   lead: Type.String({ description: "Name of the lead agent" }),
+  role: Type.Optional(
+    Type.Union([
+      Type.Literal("orchestrator"),
+      Type.Literal("lead"),
+      Type.Literal("worker"),
+    ], { description: "Tier role of the sending agent for TUI row styling" }),
+  ),
 });
 
 const BroadcastToTeamParams = Type.Object({
   message: Type.String({ description: "Message to broadcast to the team" }),
   from: Type.String({ description: "Your agent name (lead)" }),
   group: Type.String({ description: "Team group name (e.g. 'backend')" }),
+  role: Type.Optional(
+    Type.Union([
+      Type.Literal("orchestrator"),
+      Type.Literal("lead"),
+      Type.Literal("worker"),
+    ], { description: "Tier role of the sending agent for TUI row styling" }),
+  ),
 });
 
 const ReportToOrchestratorParams = Type.Object({
@@ -137,12 +190,26 @@ const ReportToOrchestratorParams = Type.Object({
   orchestrator: Type.String({
     description: "Name of the orchestrator agent",
   }),
+  role: Type.Optional(
+    Type.Union([
+      Type.Literal("orchestrator"),
+      Type.Literal("lead"),
+      Type.Literal("worker"),
+    ], { description: "Tier role of the sending agent for TUI row styling" }),
+  ),
 });
 
 const QueryPeerParams = Type.Object({
   message: Type.String({ description: "Query for your peer worker" }),
   from: Type.String({ description: "Your agent name" }),
   peer: Type.String({ description: "Name of the peer worker to query" }),
+  role: Type.Optional(
+    Type.Union([
+      Type.Literal("orchestrator"),
+      Type.Literal("lead"),
+      Type.Literal("worker"),
+    ], { description: "Tier role of the sending agent for TUI row styling" }),
+  ),
 });
 
 // ---------------------------------------------------------------------------
@@ -194,7 +261,7 @@ export default function (pi: ExtensionAPI): void {
     parameters: SendToLeadParams,
     async execute(
       _id: string,
-      params: { message: string; from: string; lead: string },
+      params: { message: string; from: string; lead: string; role?: AgentTierRole },
       _signal: AbortSignal,
       _onUpdate: (text: string) => void,
       ctx: ExtensionContext,
@@ -205,6 +272,7 @@ export default function (pi: ExtensionAPI): void {
         to: params.lead,
         channel: "send_to_lead",
         text: params.message,
+        role: params.role,
       };
       recordMessage(msg);
       renderWidget(ctx);
@@ -231,7 +299,7 @@ export default function (pi: ExtensionAPI): void {
     parameters: BroadcastToTeamParams,
     async execute(
       _id: string,
-      params: { message: string; from: string; group: string },
+      params: { message: string; from: string; group: string; role?: AgentTierRole },
       _signal: AbortSignal,
       _onUpdate: (text: string) => void,
       ctx: ExtensionContext,
@@ -242,6 +310,7 @@ export default function (pi: ExtensionAPI): void {
         to: `team:${params.group}`,
         channel: "broadcast_to_team",
         text: params.message,
+        role: params.role,
       };
       recordMessage(msg);
       renderWidget(ctx);
@@ -268,7 +337,7 @@ export default function (pi: ExtensionAPI): void {
     parameters: ReportToOrchestratorParams,
     async execute(
       _id: string,
-      params: { message: string; from: string; orchestrator: string },
+      params: { message: string; from: string; orchestrator: string; role?: AgentTierRole },
       _signal: AbortSignal,
       _onUpdate: (text: string) => void,
       ctx: ExtensionContext,
@@ -279,6 +348,7 @@ export default function (pi: ExtensionAPI): void {
         to: params.orchestrator,
         channel: "report_to_orchestrator",
         text: params.message,
+        role: params.role,
       };
       recordMessage(msg);
       renderWidget(ctx);
@@ -305,7 +375,7 @@ export default function (pi: ExtensionAPI): void {
     parameters: QueryPeerParams,
     async execute(
       _id: string,
-      params: { message: string; from: string; peer: string },
+      params: { message: string; from: string; peer: string; role?: AgentTierRole },
       _signal: AbortSignal,
       _onUpdate: (text: string) => void,
       ctx: ExtensionContext,
@@ -316,6 +386,7 @@ export default function (pi: ExtensionAPI): void {
         to: params.peer,
         channel: "query_peer",
         text: params.message,
+        role: params.role,
       };
       recordMessage(msg);
       renderWidget(ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cleo-os",
-  "version": "2026.4.13",
+  "version": "2026.4.17",
   "description": "CleoOS — the batteries-included agentic development environment wrapping Pi",
   "type": "module",
   "main": "./dist/cli.js",
@@ -8,8 +8,8 @@
     "cleoos": "dist/cli.js"
   },
   "dependencies": {
-    "@cleocode/cleo": "2026.4.13",
-    "@cleocode/cant": "2026.4.13"
+    "@cleocode/cant": "2026.4.17",
+    "@cleocode/cleo": "2026.4.17"
   },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": ">=0.60.0"
@@ -20,8 +20,8 @@
     }
   },
   "devDependencies": {
-    "typescript": "^5.9.0",
-    "vitest": "^4.1.0"
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -41,8 +41,11 @@
     "bin"
   ],
   "scripts": {
-    "build": "tsc",
-    "typecheck": "tsc --noEmit",
+    "build": "tsc && tsc -p tsconfig.extensions.json || true && tsc -p tsconfig.postinstall.json",
+    "build:src": "tsc",
+    "build:extensions": "tsc -p tsconfig.extensions.json || true",
+    "build:postinstall": "tsc -p tsconfig.postinstall.json",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.extensions.json --noEmit && tsc -p tsconfig.postinstall.json --noEmit",
     "test": "vitest run",
     "postinstall": "node bin/postinstall.js"
   }