pi-messenger-swarm 0.24.2 → 0.25.2

package/CHANGELOG.md

@@ -2,6 +2,76 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.25.2](https://github.com/monotykamary/pi-messenger-swarm/compare/v0.25.1...v0.25.2) (2026-04-25)
+
+
+### Bug Fixes
+
+* **spawn:** always append swarm operating protocol to agent system prompt ([82e0630](https://github.com/monotykamary/pi-messenger-swarm/commit/82e0630de523acc1e8794fbfe6475be509b23e61))
+
+### [0.25.1](https://github.com/monotykamary/pi-messenger-swarm/compare/v0.25.0...v0.25.1) (2026-04-25)
+
+
+### Features
+
+* **spawn:** add --agent-file, --objective, --context CLI flags ([6c577d7](https://github.com/monotykamary/pi-messenger-swarm/commit/6c577d77a387398f8ff794c6edffccb220dcec46))
+
+## [0.25.0](https://github.com/monotykamary/pi-messenger-swarm/compare/v0.24.2...v0.25.0) (2026-04-25)
+
+
+### ⚠ BREAKING CHANGES
+
+* The pi_messenger tool has been removed. All actions
+are now dispatched through the pi-messenger-swarm CLI, which
+auto-spawns a long-lived HTTP harness server on first use. Models
+call pi-messenger-swarm join, pi-messenger-swarm task claim task-1,
+etc. instead of a tool invocation.
+
+Migration:
+- pi_messenger({ action: 'join' }) → pi-messenger-swarm join
+- pi_messenger({ action: 'task.claim', id: 'task-1' })
+  → pi-messenger-swarm task claim task-1
+- pi_messenger({ action: 'send', to: '#memory', message: '...' })
+  → pi-messenger-swarm send #memory '...'
+- JSON passthrough still works:
+  pi-messenger-swarm '{ "action": "join" }'
+
+New architecture:
+- harness/server.ts: long-lived Node.js HTTP server with
+  /action, /health, /quit endpoints
+- harness/cli.ts: natural subcommand CLI with auto-spawn,
+  process-tree identity resolution
+- index.ts: tool registration removed, extension manages
+  lifecycle/overlay only
+- Agent identity resolved via process tree (x-caller-pid
+  header) + disk-based registration lookup
+- Session ID bridged via .pi/messenger/session-id file
+  (extension writes at session_start, CLI forwards as
+  x-session-id header)
+- Shell wrapper at ~/.pi/agent/bin/pi-messenger-swarm
+  instead of symlink
+
+Fixes:
+- Tasks invisible in overlay: harness used empty sessionId
+  while extension used pi's real UUIDv7 session ID
+- Registration/channel sessionId patched on subsequent
+  requests when session-id file becomes available (race
+  condition guard)
+- renameAgent() used process.pid instead of callerPid in
+  harness context
+- Swarm operating protocol in subagent prompts updated from
+  JSON to CLI syntax
+- All hint strings across handlers, overlay, deliver-message
+  updated to CLI syntax
+- README.md and SKILL.md updated from pi_messenger() to CLI
+  examples
+- coverage/ added to .gitignore
+- knip.json updated with harness entry points
+
+### Features
+
+* replace tool-hoisting with CLI + harness server architecture ([8bf9259](https://github.com/monotykamary/pi-messenger-swarm/commit/8bf9259f1d6c60f30128ab7ece96f772b9b8fa98))
+
 ### [0.24.2](https://github.com/monotykamary/pi-messenger-swarm/compare/v0.24.1...v0.24.2) (2026-04-19)
 
 

package/README.md

@@ -49,29 +49,19 @@ From git (Pi package settings):
 
 Join the messenger and start collaborating in your session channel:
 
-```ts
-pi_messenger({ action: 'join' });
-pi_messenger({
-  action: 'send',
-  to: '#memory',
-  message: 'Investigating auth timeout in refresh flow',
-});
-pi_messenger({ action: 'task.create', title: 'Investigate auth timeout', content: 'Repro + fix' });
-pi_messenger({ action: 'task.claim', id: 'task-1' });
-pi_messenger({ action: 'task.progress', id: 'task-1', message: 'Found race in refresh flow' });
-pi_messenger({ action: 'task.done', id: 'task-1', summary: 'Fixed refresh lock + tests' });
+```bash
+pi-messenger-swarm join
+pi-messenger-swarm send #memory "Investigating auth timeout in refresh flow"
+pi-messenger-swarm task create --title "Investigate auth timeout" --content "Repro + fix"
+pi-messenger-swarm task claim task-1
+pi-messenger-swarm task progress task-1 "Found race in refresh flow"
+pi-messenger-swarm task done task-1 "Fixed refresh lock + tests"
 ```
 
 Spawn a specialized subagent:
 
-```ts
-pi_messenger({
-  action: 'spawn',
-  role: 'Packaging Gap Analyst',
-  persona: 'Skeptical market researcher',
-  message: 'Find productization gaps in idea aggregation tools',
-  content: 'Focus on onboarding, monetization, and UX friction',
-});
+```bash
+pi-messenger-swarm spawn --role "Packaging Gap Analyst" --persona "Skeptical market researcher" "Find productization gaps in idea aggregation tools"
 ```
 
 ## Channel Model
@@ -171,33 +161,29 @@ Compatibility aliases:
 
 ### Direct message an agent
 
-```ts
-pi_messenger({ action: 'send', to: 'OtherAgent', message: 'Need your API shape before I commit' });
+```bash
+pi-messenger-swarm send OtherAgent "Need your API shape before I commit"
 ```
 
 ### Post durably to a channel
 
-```ts
-pi_messenger({
-  action: 'send',
-  to: '#memory',
-  message: 'Claimed task-4, touching src/auth/session.ts',
-});
-pi_messenger({ action: 'send', to: '#memory', message: 'Nightly sync complete' });
+```bash
+pi-messenger-swarm send #memory "Claimed task-4, touching src/auth/session.ts"
+pi-messenger-swarm send #memory "Nightly sync complete"
 ```
 
 ### Switch channels explicitly
 
-```ts
-pi_messenger({ action: 'join', channel: 'memory' });
-pi_messenger({ action: 'join', channel: 'architecture', create: true });
+```bash
+pi-messenger-swarm join --channel memory
+pi-messenger-swarm join --channel architecture --create
 ```
 
 ### Read a channel feed
 
-```ts
-pi_messenger({ action: 'feed', limit: 20 });
-pi_messenger({ action: 'feed', channel: 'memory', limit: 20 });
+```bash
+pi-messenger-swarm feed --limit 20
+pi-messenger-swarm feed --channel memory --limit 20
 ```
 
 ### Notes
@@ -294,9 +280,9 @@ This design intentionally breaks older messaging assumptions.
 
 Use these patterns instead:
 
-```ts
-pi_messenger({ action: 'send', to: 'AgentName', message: '...' });
-pi_messenger({ action: 'send', to: '#channel', message: '...' });
+```bash
+pi-messenger-swarm send AgentName "..."
+pi-messenger-swarm send #channel "..."
 ```
 
 ## Environment Variables

package/action-types.ts

@@ -39,6 +39,7 @@ export interface MessengerActionParams {
   // Spawn
   role?: string;
   persona?: string;
+  objective?: string;
   context?: string;
   model?: string;
   agentFile?: string;

package/channel.ts

@@ -268,6 +268,36 @@ export function writeChannel(dirs: Dirs, record: ChannelRecord): ChannelRecord {
   return record;
 }
 
+/**
+ * Patch the sessionId on a channel's metadata header if it's currently empty.
+ * Used by the harness server when it discovers the session ID after the channel
+ * was already created (race condition with session-id file).
+ * Returns true if the channel was patched, false if no change was needed.
+ */
+export function patchChannelSessionId(dirs: Dirs, channelId: string, sessionId: string): boolean {
+  if (!sessionId) return false;
+  const header = readChannelHeader(dirs, channelId);
+  if (!header || header.sessionId) return false; // already set or missing
+
+  const filePath = channelPath(dirs, channelId);
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+    if (lines.length === 0) return false;
+
+    const meta = JSON.parse(lines[0]) as ChannelMetaHeader;
+    meta.sessionId = sessionId;
+    lines[0] = JSON.stringify(meta);
+
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmp, lines.join('\n'));
+    fs.renameSync(tmp, filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function ensureNamedChannel(
   dirs: Dirs,
   channelId: string,

package/dist/action-types.js

@@ -0,0 +1 @@
+export {};

package/dist/channel.js

@@ -0,0 +1,353 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { generateMemorableName } from './lib.js';
+export const CHANNEL_META_VERSION = 1;
+export const MEMORY_CHANNEL_ID = 'memory';
+export const DEFAULT_NAMED_CHANNELS = [
+    { id: MEMORY_CHANNEL_ID, description: 'Cross-session knowledge and insights' },
+];
+function ensureDir(dir) {
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+}
+export function getChannelsDir(dirs) {
+    return path.join(dirs.base, 'channels');
+}
+export function normalizeChannelId(value) {
+    const trimmed = value.trim();
+    const withoutHash = trimmed.startsWith('#') ? trimmed.slice(1) : trimmed;
+    return (withoutHash || value).toLowerCase();
+}
+export function isValidChannelId(value) {
+    if (!value)
+        return false;
+    return /^[a-z0-9][a-z0-9._-]{0,79}$/.test(normalizeChannelId(value));
+}
+export function isSessionChannelId(value) {
+    return normalizeChannelId(value).startsWith('session-');
+}
+export function displayChannelLabel(channelId) {
+    const normalized = normalizeChannelId(channelId);
+    return `#${normalized}`;
+}
+/** Returns the path to the unified channel JSONL file (metadata + feed) */
+export function channelPath(dirs, channelId) {
+    return path.join(getChannelsDir(dirs), `${normalizeChannelId(channelId)}.jsonl`);
+}
+function createMetaHeader(record) {
+    return {
+        _meta: true,
+        v: CHANNEL_META_VERSION,
+        id: record.id,
+        type: record.type,
+        createdAt: record.createdAt,
+        createdBy: record.createdBy,
+        sessionId: record.sessionId,
+        description: record.description,
+    };
+}
+export function isMetaHeader(obj) {
+    if (!obj || typeof obj !== 'object')
+        return false;
+    const o = obj;
+    return o._meta === true && typeof o.v === 'number' && typeof o.id === 'string';
+}
+function metaHeaderToRecord(header) {
+    return {
+        id: header.id,
+        type: header.type,
+        createdAt: header.createdAt,
+        createdBy: header.createdBy,
+        sessionId: header.sessionId,
+        description: header.description,
+    };
+}
+function normalizeChannelRecord(raw, fallbackId) {
+    const id = normalizeChannelId(raw?.id || fallbackId);
+    if (!isValidChannelId(id))
+        return null;
+    const type = raw?.type === 'session' || raw?.type === 'named'
+        ? raw.type
+        : raw?.sessionId
+            ? 'session'
+            : isSessionChannelId(id)
+                ? 'session'
+                : 'named';
+    return {
+        id,
+        type,
+        createdAt: raw?.createdAt || new Date(0).toISOString(),
+        createdBy: raw?.createdBy,
+        sessionId: raw?.sessionId,
+        description: raw?.description,
+    };
+}
+/**
+ * Read the metadata header from a channel JSONL file.
+ * Returns null if file doesn't exist or has invalid header.
+ */
+export function readChannelHeader(dirs, channelId) {
+    const filePath = channelPath(dirs, channelId);
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const firstLine = content.split('\n')[0];
+        if (!firstLine)
+            return null;
+        const parsed = JSON.parse(firstLine);
+        if (isMetaHeader(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Ignore parse errors
+    }
+    return null;
+}
+/**
+ * Read all event lines from a channel JSONL file (skips the metadata header).
+ * Returns raw JSON strings, not parsed objects.
+ */
+export function readChannelEventLines(dirs, channelId) {
+    const filePath = channelPath(dirs, channelId);
+    if (!fs.existsSync(filePath))
+        return [];
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8').trim();
+        if (!content)
+            return [];
+        const lines = content.split('\n');
+        // Skip first line (metadata header)
+        return lines.slice(1).filter((line) => line.trim());
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Append a single event line to a channel JSONL file.
+ * Creates the file with metadata header if it doesn't exist.
+ */
+export function appendChannelEventLine(dirs, channelId, eventLine, meta) {
+    const filePath = channelPath(dirs, channelId);
+    try {
+        ensureDir(getChannelsDir(dirs));
+        if (!fs.existsSync(filePath)) {
+            // Create new file with minimal metadata header
+            const header = {
+                _meta: true,
+                v: CHANNEL_META_VERSION,
+                id: normalizeChannelId(channelId),
+                type: isSessionChannelId(channelId) ? 'session' : 'named',
+                createdAt: new Date().toISOString(),
+                createdBy: meta?.createdBy,
+                sessionId: meta?.sessionId,
+                description: meta?.description,
+            };
+            fs.writeFileSync(filePath, JSON.stringify(header) + '\n' + eventLine + '\n');
+        }
+        else {
+            fs.appendFileSync(filePath, eventLine + '\n');
+        }
+    }
+    catch {
+        // Best effort
+    }
+}
+/**
+ * Prune events in a channel JSONL file to keep only the last N events.
+ * Preserves the metadata header.
+ */
+export function pruneChannelEvents(dirs, channelId, maxEvents) {
+    const filePath = channelPath(dirs, channelId);
+    if (!fs.existsSync(filePath))
+        return;
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const lines = content.split('\n');
+        if (lines.length <= 1)
+            return; // Only header or empty
+        const header = lines[0];
+        const events = lines.slice(1).filter((line) => line.trim());
+        if (events.length <= maxEvents)
+            return;
+        const pruned = events.slice(-maxEvents);
+        fs.writeFileSync(filePath, header + '\n' + pruned.join('\n') + '\n');
+    }
+    catch {
+        // Best effort
+    }
+}
+export function getChannel(dirs, channelId) {
+    const header = readChannelHeader(dirs, channelId);
+    if (header) {
+        return metaHeaderToRecord(header);
+    }
+    return null;
+}
+export function listChannels(dirs) {
+    const dir = getChannelsDir(dirs);
+    if (!fs.existsSync(dir))
+        return [];
+    const items = [];
+    for (const file of fs.readdirSync(dir)) {
+        if (!file.endsWith('.jsonl'))
+            continue;
+        const filePath = path.join(dir, file);
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const firstLine = content.split('\n')[0];
+            if (!firstLine)
+                continue;
+            const parsed = JSON.parse(firstLine);
+            if (isMetaHeader(parsed)) {
+                items.push(metaHeaderToRecord(parsed));
+            }
+        }
+        catch {
+            // Ignore malformed channel files
+        }
+    }
+    return items.sort((a, b) => a.id.localeCompare(b.id));
+}
+export function writeChannel(dirs, record) {
+    ensureDir(getChannelsDir(dirs));
+    const filePath = channelPath(dirs, record.id);
+    const metaHeader = createMetaHeader(record);
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    // Write metadata header as first line, preserving any existing events
+    let existingEvents = [];
+    if (fs.existsSync(filePath)) {
+        try {
+            existingEvents = readChannelEventLines(dirs, record.id);
+        }
+        catch {
+            // Ignore read errors, start fresh
+        }
+    }
+    const lines = [JSON.stringify(metaHeader), ...existingEvents];
+    fs.writeFileSync(tmp, lines.join('\n') + '\n');
+    fs.renameSync(tmp, filePath);
+    return record;
+}
+/**
+ * Patch the sessionId on a channel's metadata header if it's currently empty.
+ * Used by the harness server when it discovers the session ID after the channel
+ * was already created (race condition with session-id file).
+ * Returns true if the channel was patched, false if no change was needed.
+ */
+export function patchChannelSessionId(dirs, channelId, sessionId) {
+    if (!sessionId)
+        return false;
+    const header = readChannelHeader(dirs, channelId);
+    if (!header || header.sessionId)
+        return false; // already set or missing
+    const filePath = channelPath(dirs, channelId);
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const lines = content.split('\n');
+        if (lines.length === 0)
+            return false;
+        const meta = JSON.parse(lines[0]);
+        meta.sessionId = sessionId;
+        lines[0] = JSON.stringify(meta);
+        const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+        fs.writeFileSync(tmp, lines.join('\n'));
+        fs.renameSync(tmp, filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function ensureNamedChannel(dirs, channelId, createdBy, description) {
+    const normalized = normalizeChannelId(channelId);
+    const existing = getChannel(dirs, normalized);
+    if (existing)
+        return existing;
+    return writeChannel(dirs, {
+        id: normalized,
+        type: 'named',
+        createdAt: new Date().toISOString(),
+        createdBy,
+        description,
+    });
+}
+export function ensureDefaultNamedChannels(dirs, createdBy) {
+    return DEFAULT_NAMED_CHANNELS.map((channel) => ensureNamedChannel(dirs, channel.id, createdBy, channel.description));
+}
+function toKebabCase(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+        .toLowerCase();
+}
+function allocateSessionChannelId(dirs, baseId) {
+    const normalizedBase = normalizeChannelId(baseId);
+    if (!getChannel(dirs, normalizedBase))
+        return normalizedBase;
+    for (let i = 2; i <= 99; i++) {
+        const candidate = `${normalizedBase}-${i}`;
+        if (!getChannel(dirs, candidate))
+            return candidate;
+    }
+    const suffix = Math.random().toString(36).slice(2, 6);
+    return `${normalizedBase}-${suffix}`;
+}
+export function generateSessionChannelId() {
+    const generated = generateMemorableName();
+    return toKebabCase(generated);
+}
+export function findChannelBySessionId(dirs, sessionId) {
+    if (!sessionId)
+        return null;
+    for (const channel of listChannels(dirs)) {
+        if (channel.type === 'session' && channel.sessionId === sessionId)
+            return channel;
+    }
+    return null;
+}
+export function createSessionChannel(dirs, sessionId, createdBy) {
+    return writeChannel(dirs, {
+        id: allocateSessionChannelId(dirs, generateSessionChannelId()),
+        type: 'session',
+        createdAt: new Date().toISOString(),
+        createdBy,
+        sessionId,
+    });
+}
+export function ensureSessionChannel(dirs, sessionId, createdBy) {
+    if (sessionId) {
+        const existing = findChannelBySessionId(dirs, sessionId);
+        if (existing)
+            return existing;
+    }
+    return createSessionChannel(dirs, sessionId, createdBy);
+}
+export function ensureExistingOrCreateChannel(dirs, channelId, options) {
+    const normalized = normalizeChannelId(channelId);
+    if (!isValidChannelId(normalized))
+        return null;
+    const existing = getChannel(dirs, normalized);
+    if (existing)
+        return existing;
+    if (DEFAULT_NAMED_CHANNELS.some((channel) => channel.id === normalized)) {
+        const preset = DEFAULT_NAMED_CHANNELS.find((channel) => channel.id === normalized);
+        return ensureNamedChannel(dirs, normalized, options?.createdBy, preset.description);
+    }
+    if (!options?.create)
+        return null;
+    if (isSessionChannelId(normalized)) {
+        return writeChannel(dirs, {
+            id: normalized,
+            type: 'session',
+            createdAt: new Date().toISOString(),
+            createdBy: options.createdBy,
+            description: options.description,
+        });
+    }
+    return ensureNamedChannel(dirs, normalized, options.createdBy, options.description);
+}