@covibes/zeroshot 1.0.1

package/lib/stream-json-parser.js

@@ -0,0 +1,236 @@
+/**
+ * Stream JSON Parser for Claude Code output
+ *
+ * Parses NDJSON (newline-delimited JSON) streaming output from Claude Code.
+ * Extracts: text output, tool calls, tool results, thinking, errors.
+ *
+ * Event types from Claude Code stream-json format:
+ * - system: Session initialization
+ * - stream_event: Real-time streaming (content_block_start, content_block_delta, etc.)
+ * - assistant: Complete assistant message with content array
+ * - user: Tool results
+ * - result: Final task result
+ */
+
+/**
+ * Parse a single JSON line and extract displayable content
+ * @param {string} line - Single line of NDJSON
+ * @returns {Object|null} Parsed event with type and content, or null if not displayable
+ */
+function parseStreamLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed || !trimmed.startsWith('{') || !trimmed.endsWith('}')) {
+    return null;
+  }
+
+  let event;
+  try {
+    event = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+
+  // stream_event - real-time streaming updates
+  if (event.type === 'stream_event' && event.event) {
+    return parseStreamEvent(event.event);
+  }
+
+  // assistant - complete message with content blocks
+  if (event.type === 'assistant' && event.message?.content) {
+    return parseAssistantMessage(event.message);
+  }
+
+  // user - tool result
+  if (event.type === 'user' && event.message?.content) {
+    return parseUserMessage(event.message);
+  }
+
+  // result - final task result
+  if (event.type === 'result') {
+    return {
+      type: 'result',
+      success: event.subtype === 'success',
+      result: event.result,
+      error: event.is_error ? event.result : null,
+      cost: event.total_cost_usd,
+      duration: event.duration_ms,
+    };
+  }
+
+  // system - session init (skip, not user-facing)
+  if (event.type === 'system') {
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Parse stream_event inner event
+ */
+function parseStreamEvent(inner) {
+  // content_block_start - tool use or text block starting
+  if (inner.type === 'content_block_start' && inner.content_block) {
+    const block = inner.content_block;
+
+    if (block.type === 'tool_use') {
+      return {
+        type: 'tool_start',
+        toolName: block.name,
+        toolId: block.id,
+      };
+    }
+
+    if (block.type === 'thinking') {
+      return {
+        type: 'thinking_start',
+      };
+    }
+
+    // text block start - usually empty, skip
+    return null;
+  }
+
+  // content_block_delta - incremental content
+  if (inner.type === 'content_block_delta' && inner.delta) {
+    const delta = inner.delta;
+
+    if (delta.type === 'text_delta' && delta.text) {
+      return {
+        type: 'text',
+        text: delta.text,
+      };
+    }
+
+    if (delta.type === 'thinking_delta' && delta.thinking) {
+      return {
+        type: 'thinking',
+        text: delta.thinking,
+      };
+    }
+
+    if (delta.type === 'input_json_delta' && delta.partial_json) {
+      return {
+        type: 'tool_input',
+        json: delta.partial_json,
+      };
+    }
+  }
+
+  // content_block_stop - block ended
+  if (inner.type === 'content_block_stop') {
+    return {
+      type: 'block_end',
+      index: inner.index,
+    };
+  }
+
+  // message_start - skip text extraction here since it will come via text_delta events
+  // (extracting here causes duplicate text output)
+
+  return null;
+}
+
+/**
+ * Parse assistant message content blocks
+ * NOTE: Skip text blocks here since they were already streamed via text_delta events.
+ * Extracting text here would cause duplicate output.
+ */
+function parseAssistantMessage(message) {
+  const results = [];
+
+  for (const block of message.content) {
+    // Skip text blocks - already streamed via text_delta events
+    // Extracting here causes duplicate output
+
+    if (block.type === 'tool_use') {
+      results.push({
+        type: 'tool_call',
+        toolName: block.name,
+        toolId: block.id,
+        input: block.input,
+      });
+    }
+
+    if (block.type === 'thinking' && block.thinking) {
+      // Skip thinking blocks too - already streamed via thinking_delta
+      // But keep for non-streaming contexts (direct API responses)
+      // Only emit if we haven't seen streaming deltas (detected by having results already)
+    }
+  }
+
+  if (results.length === 1) {
+    return results[0];
+  }
+
+  if (results.length > 1) {
+    return {
+      type: 'multi',
+      events: results,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Parse user message (tool results)
+ */
+function parseUserMessage(message) {
+  const results = [];
+
+  for (const block of message.content) {
+    if (block.type === 'tool_result') {
+      results.push({
+        type: 'tool_result',
+        toolId: block.tool_use_id,
+        content: typeof block.content === 'string' ? block.content : JSON.stringify(block.content),
+        isError: block.is_error || false,
+      });
+    }
+  }
+
+  if (results.length === 1) {
+    return results[0];
+  }
+
+  if (results.length > 1) {
+    return {
+      type: 'multi',
+      events: results,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Parse multiple lines of NDJSON
+ * @param {string} chunk - Chunk of text potentially containing multiple JSON lines
+ * @returns {Array} Array of parsed events
+ */
+function parseChunk(chunk) {
+  const events = [];
+  const lines = chunk.split('\n');
+
+  for (const line of lines) {
+    const event = parseStreamLine(line);
+    if (event) {
+      if (event.type === 'multi') {
+        events.push(...event.events);
+      } else {
+        events.push(event);
+      }
+    }
+  }
+
+  return events;
+}
+
+module.exports = {
+  parseStreamLine,
+  parseChunk,
+  parseStreamEvent,
+  parseAssistantMessage,
+  parseUserMessage,
+};

package/package.json

@@ -0,0 +1,121 @@
+{
+  "name": "@covibes/zeroshot",
+  "version": "1.0.1",
+  "description": "Multi-agent orchestration engine for Claude - cluster coordinator and CLI",
+  "main": "src/orchestrator.js",
+  "bin": {
+    "zeroshot": "./cli/index.js"
+  },
+  "directories": {
+    "example": "examples",
+    "test": "tests"
+  },
+  "scripts": {
+    "test": "mocha 'tests/**/*.test.js'",
+    "test:coverage": "c8 npm test",
+    "test:coverage:report": "c8 --reporter=html npm test && echo 'Coverage report generated at coverage/index.html'",
+    "start": "node cli/index.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "deadcode": "ts-prune --skip node_modules",
+    "deadcode:files": "unimported",
+    "deadcode:deps": "depcheck",
+    "deadcode:all": "npm run deadcode && npm run deadcode:files && npm run deadcode:deps",
+    "check": "npm run typecheck && npm run lint",
+    "check:all": "npm run check && npm run deadcode:all",
+    "release": "semantic-release",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm test"
+  },
+  "c8": {
+    "reporter": [
+      "text",
+      "lcov",
+      "html"
+    ],
+    "include": [
+      "src/**/*.js",
+      "lib/**/*.js",
+      "cli/**/*.js"
+    ],
+    "exclude": [
+      "**/*.test.js",
+      "**/tests/**"
+    ],
+    "all": true
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "multi-agent",
+    "orchestration",
+    "claude",
+    "automation"
+  ],
+  "author": "Covibes",
+  "license": "MIT",
+  "homepage": "https://github.com/covibes/zeroshot",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/covibes/zeroshot.git"
+  },
+  "bugs": {
+    "url": "https://github.com/covibes/zeroshot/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "src/",
+    "lib/",
+    "cli/",
+    "cluster-templates/",
+    "hooks/",
+    "docker/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ansi-to-html": "^0.7.2",
+    "better-sqlite3": "^12.5.0",
+    "blessed": "^0.1.81",
+    "blessed-contrib": "^4.11.0",
+    "chalk": "^4.1.2",
+    "commander": "^14.0.2",
+    "md-to-pdf": "^5.2.5",
+    "node-pty": "^1.0.0",
+    "omelette": "^0.4.17",
+    "pidusage": "^4.0.1",
+    "proper-lockfile": "^4.1.2"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.6",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.0.3",
+    "c8": "^10.1.3",
+    "chai": "^6.2.1",
+    "depcheck": "^1.4.7",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-unused-imports": "^4.3.0",
+    "mocha": "^11.7.5",
+    "semantic-release": "^25.0.2",
+    "sinon": "^21.0.0",
+    "ts-prune": "^0.10.3",
+    "typescript": "^5.9.3",
+    "unimported": "^1.31.0"
+  },
+  "overrides": {
+    "xml2js": "^0.5.0"
+  }
+}

package/src/agent/agent-config.js

@@ -0,0 +1,121 @@
+/**
+ * AgentConfig - Agent configuration validation and defaults
+ *
+ * Provides:
+ * - Config validation and normalization
+ * - Default values for optional fields
+ * - Model configuration setup
+ * - Safety checks for test mode
+ */
+
+// Default max iterations (high limit - let the user decide when to give up)
+const DEFAULT_MAX_ITERATIONS = 100;
+
+// Task timeout - DISABLED (tasks run until completion or explicit kill)
+// Originally: 2 hours - caused premature termination of long-running tasks
+// Now: Infinity - tasks only stop on completion, explicit kill, or external error
+const DEFAULT_TASK_TIMEOUT_MS = Infinity;
+
+// Stale detection - ENABLED by default using multi-indicator analysis (safe from false positives)
+// Multi-indicator approach checks: process state, CPU usage, context switches, network I/O
+// Only flags as stuck when ALL indicators show inactivity (score >= 3.5)
+// Single-indicator detection (just output freshness) was too risky - this is safe.
+const DEFAULT_STALE_DURATION_MS = 30 * 60 * 1000; // 30 minutes before triggering analysis
+const DEFAULT_LIVENESS_CHECK_ENABLED = true; // Safe with multi-indicator detection
+
+/**
+ * Validate and normalize agent configuration
+ * @param {Object} config - Raw agent configuration
+ * @param {Object} options - Agent wrapper options
+ * @returns {Object} Normalized configuration
+ */
+function validateAgentConfig(config, options = {}) {
+  // CRITICAL: Enforce JSON schema output by default to prevent parse failures and crashes
+  // Agents MUST return structured output so hooks can safely use {{result.*}} templates
+  if (!config.outputFormat) {
+    config.outputFormat = 'json';
+  }
+
+  // If outputFormat is json but no schema defined, use a minimal default schema
+  // This prevents uncaught exceptions when parsing agent output
+  if (config.outputFormat === 'json' && !config.jsonSchema) {
+    config.jsonSchema = {
+      type: 'object',
+      properties: {
+        summary: {
+          type: 'string',
+          description: 'Brief summary of what was done',
+        },
+        result: {
+          type: 'string',
+          description: 'Detailed result or output',
+        },
+      },
+      required: ['summary', 'result'],
+    };
+  }
+
+  // Model configuration: support both static model and dynamic rules
+  let modelConfig;
+  if (config.modelRules) {
+    modelConfig = { type: 'rules', rules: config.modelRules };
+  } else {
+    modelConfig = { type: 'static', model: config.model || 'sonnet' };
+  }
+
+  // Prompt configuration: support static prompt OR iteration-based rules
+  // Formats:
+  //   prompt: "string"                              -> static
+  //   prompt: { system: "string" }                  -> static
+  //   prompt: { initial: "...", subsequent: "..." } -> iteration 1 vs 2+
+  //   prompt: { iterations: [...] }                 -> full control
+  let promptConfig = null;
+  if (config.prompt?.iterations) {
+    promptConfig = { type: 'rules', rules: config.prompt.iterations };
+  } else if (config.prompt?.initial || config.prompt?.subsequent) {
+    const rules = [];
+    if (config.prompt.initial) rules.push({ match: '1', system: config.prompt.initial });
+    if (config.prompt.subsequent) rules.push({ match: '2+', system: config.prompt.subsequent });
+    promptConfig = { type: 'rules', rules };
+  } else if (typeof config.prompt === 'string') {
+    promptConfig = { type: 'static', system: config.prompt };
+  } else if (config.prompt?.system) {
+    promptConfig = { type: 'static', system: config.prompt.system };
+  } else if (config.prompt) {
+    throw new Error(`Agent "${config.id}": invalid prompt format`);
+  }
+
+  // Build normalized config
+  const normalizedConfig = {
+    ...config,
+    modelConfig,
+    promptConfig,
+    maxIterations: config.maxIterations || DEFAULT_MAX_ITERATIONS,
+    timeout: config.timeout || DEFAULT_TASK_TIMEOUT_MS,
+    staleDuration: config.staleDuration || DEFAULT_STALE_DURATION_MS,
+    enableLivenessCheck: config.enableLivenessCheck ?? DEFAULT_LIVENESS_CHECK_ENABLED, // On by default, opt-out with false
+  };
+
+  // SAFETY: In test mode, verify mock is provided for agents that execute tasks
+  // Check if this agent executes tasks (vs orchestrator agents that only publish messages)
+  const executesTask = config.triggers?.some(
+    (trigger) => !trigger.action || trigger.action === 'execute_task'
+  );
+
+  if (options.testMode && !options.mockSpawnFn && executesTask) {
+    throw new Error(
+      `AgentWrapper: testMode=true but no mockSpawnFn provided for agent '${config.id}'. ` +
+        `This would cause real Claude API calls. ABORTING.`
+    );
+  }
+
+  return normalizedConfig;
+}
+
+module.exports = {
+  validateAgentConfig,
+  DEFAULT_MAX_ITERATIONS,
+  DEFAULT_TASK_TIMEOUT_MS,
+  DEFAULT_STALE_DURATION_MS,
+  DEFAULT_LIVENESS_CHECK_ENABLED,
+};