@cleocode/cleo-os 2026.4.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CLEO Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/postinstall.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * CleoOS postinstall — scaffolds global XDG hub and deploys extensions.
+ *
+ * Runs automatically after `npm install -g @cleocode/cleo-os`.
+ * Creates XDG-compliant directory structure and copies the CANT bridge
+ * extension template into the extensions directory.
+ *
+ * Skips during workspace/dev installs (non-global).
+ *
+ * This file is plain JS (not compiled from src/) so it can run before
+ * the package is built, matching the @cleocode/cleo postinstall pattern.
+ */
+
+import { existsSync, mkdirSync, cpSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Detect if this is a global npm install (not a workspace/dev install).
+ */
+function isGlobalInstall() {
+  const pkgRoot = resolve(__dirname, '..');
+
+  // Signal 1: npm_config_global env var (set by npm during global installs)
+  if (process.env.npm_config_global === 'true') return true;
+
+  // Signal 2: path contains a global node_modules (npm, pnpm, yarn)
+  if (/[/\\]lib[/\\]node_modules[/\\]/.test(pkgRoot)) return true;
+
+  // Signal 3: npm_config_prefix matches the package path
+  const prefix = process.env.npm_config_prefix;
+  if (prefix && pkgRoot.startsWith(prefix)) return true;
+
+  // Signal 4: inside a pnpm workspace — definitely not global
+  const workspaceMarker = join(pkgRoot, '..', '..', 'pnpm-workspace.yaml');
+  if (existsSync(workspaceMarker)) return false;
+
+  return false;
+}
+
+/**
+ * Inline XDG path resolution (avoids importing from dist/ which may not exist).
+ */
+function resolveCleoOsPaths() {
+  const home = homedir();
+  const xdgData = process.env.XDG_DATA_HOME ?? join(home, '.local', 'share');
+  const xdgConfig = process.env.XDG_CONFIG_HOME ?? join(home, '.config');
+
+  const data = join(xdgData, 'cleo');
+  const config = join(xdgConfig, 'cleo');
+
+  return {
+    data,
+    config,
+    agentDir: data,
+    extensions: join(data, 'extensions'),
+    cant: join(data, 'cant'),
+    auth: join(config, 'auth'),
+  };
+}
+
+function main() {
+  if (!isGlobalInstall()) {
+    console.log('CleoOS: skipping postinstall (not global install)');
+    return;
+  }
+
+  const paths = resolveCleoOsPaths();
+
+  // Scaffold directories
+  for (const dir of [paths.data, paths.config, paths.extensions, paths.cant, paths.auth]) {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+      console.log(`CleoOS: created ${dir}`);
+    }
+  }
+
+  // Deploy bridge extension from package template
+  const bridgeTemplate = join(__dirname, '..', 'extensions', 'cleo-cant-bridge.js');
+  const bridgeTarget = join(paths.extensions, 'cleo-cant-bridge.js');
+  if (existsSync(bridgeTemplate)) {
+    cpSync(bridgeTemplate, bridgeTarget, { force: true });
+    console.log(`CleoOS: deployed bridge extension to ${bridgeTarget}`);
+  }
+
+  console.log('CleoOS: postinstall complete');
+}
+
+main();

package/extensions/cleo-chatroom.ts

@@ -0,0 +1,371 @@
+/**
+ * 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 {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+// ---------------------------------------------------------------------------
+// Message model
+// ---------------------------------------------------------------------------
+
+/** A single inter-agent chat message. */
+interface ChatMessage {
+  /** ISO-8601 timestamp of when the message was created. */
+  timestamp: string;
+  /** Name of the sending agent. */
+  from: string;
+  /** Name of the receiving agent or group (e.g. "team:backend"). */
+  to: string;
+  /** Message channel identifying the tool that produced this message. */
+  channel: "send_to_lead" | "broadcast_to_team" | "report_to_orchestrator" | "query_peer";
+  /** The message text. */
+  text: string;
+}
+
+// ---------------------------------------------------------------------------
+// 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: ChatMessage[] = [];
+
+/** Path to the JSONL log file (set on session_start). */
+let logPath: string | null = 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: ChatMessage): void {
+  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.
+    }
+  }
+}
+
+/**
+ * Format a chat message for TUI display.
+ *
+ * @param msg - The message to format.
+ * @returns A single-line string representation.
+ */
+function formatMessage(msg: ChatMessage): string {
+  const time = msg.timestamp.slice(11, 19);
+  return `[${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: ExtensionContext): void {
+  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" }),
+});
+
+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')" }),
+});
+
+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",
+  }),
+});
+
+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" }),
+});
+
+// ---------------------------------------------------------------------------
+// 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: ExtensionAPI): void {
+  // -------------------------------------------------------------------------
+  // session_start: initialize log directory and widget
+  // -------------------------------------------------------------------------
+  pi.on("session_start", async (_event: unknown, ctx: ExtensionContext) => {
+    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: string,
+      params: { message: string; from: string; lead: string },
+      _signal: AbortSignal,
+      _onUpdate: (text: string) => void,
+      ctx: ExtensionContext,
+    ) {
+      const msg: ChatMessage = {
+        timestamp: new Date().toISOString(),
+        from: params.from,
+        to: params.lead,
+        channel: "send_to_lead",
+        text: params.message,
+      };
+      recordMessage(msg);
+      renderWidget(ctx);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            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: string,
+      params: { message: string; from: string; group: string },
+      _signal: AbortSignal,
+      _onUpdate: (text: string) => void,
+      ctx: ExtensionContext,
+    ) {
+      const msg: ChatMessage = {
+        timestamp: new Date().toISOString(),
+        from: params.from,
+        to: `team:${params.group}`,
+        channel: "broadcast_to_team",
+        text: params.message,
+      };
+      recordMessage(msg);
+      renderWidget(ctx);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            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: string,
+      params: { message: string; from: string; orchestrator: string },
+      _signal: AbortSignal,
+      _onUpdate: (text: string) => void,
+      ctx: ExtensionContext,
+    ) {
+      const msg: ChatMessage = {
+        timestamp: new Date().toISOString(),
+        from: params.from,
+        to: params.orchestrator,
+        channel: "report_to_orchestrator",
+        text: params.message,
+      };
+      recordMessage(msg);
+      renderWidget(ctx);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            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: string,
+      params: { message: string; from: string; peer: string },
+      _signal: AbortSignal,
+      _onUpdate: (text: string) => void,
+      ctx: ExtensionContext,
+    ) {
+      const msg: ChatMessage = {
+        timestamp: new Date().toISOString(),
+        from: params.from,
+        to: params.peer,
+        channel: "query_peer",
+        text: params.message,
+      };
+      recordMessage(msg);
+      renderWidget(ctx);
+      return {
+        content: [
+          {
+            type: "text" as const,
+            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: string, ctx: ExtensionCommandContext) => {
+      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;
+  });
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@cleocode/cleo-os",
+  "version": "2026.4.12",
+  "description": "CleoOS — the batteries-included agentic development environment wrapping Pi",
+  "type": "module",
+  "main": "./dist/cli.js",
+  "bin": {
+    "cleoos": "dist/cli.js"
+  },
+  "dependencies": {
+    "@cleocode/cleo": "2026.4.12",
+    "@cleocode/cant": "2026.4.12"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": ">=0.60.0"
+  },
+  "peerDependenciesMeta": {
+    "@mariozechner/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kryptobaseddev/cleo",
+    "directory": "packages/cleo-os"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "extensions",
+    "bin"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "postinstall": "node bin/postinstall.js"
+  }
+}