@kaitranntt/ccs 3.5.0 → 4.1.0

package/bin/delegation/README.md

@@ -0,0 +1,189 @@
+# CCS Delegation Module
+
+Enhanced Claude Code delegation system for multi-model task delegation.
+
+## Files
+
+### Core Components
+- **headless-executor.js** (405 lines) - Main executor, spawns `claude -p` with enhanced features
+- **session-manager.js** (156 lines) - Session persistence and cost tracking
+- **settings-parser.js** (88 lines) - Parse tool restrictions from settings
+- **result-formatter.js** (326 lines) - Terminal output formatting
+
+**Total**: 975 lines (down from 1,755 lines - 44% reduction)
+
+## Features
+
+### Enhanced Headless Execution
+- Stream-JSON output parsing (`--output-format stream-json`)
+- Real-time tool use visibility in TTY
+- Permission mode acceptEdits (`--permission-mode acceptEdits`)
+- Tool restrictions from `.claude/settings.local.json`
+- Multi-turn session management (`--resume <session-id>`)
+- Time-based limits (10 min default timeout with graceful termination)
+- Cost tracking and aggregation
+
+### Session Management
+- Persistence: `~/.ccs/delegation-sessions.json`
+- Resume via `/ccs:glm:continue` and `/ccs:kimi:continue`
+- Auto-cleanup expired sessions (>30 days)
+- Cost aggregation across turns
+
+### Settings
+- Profile location: `~/.ccs/{profile}.settings.json`
+- Examples: `glm.settings.json`, `kimi.settings.json`, `glmt.settings.json`
+- Tool restrictions from `.claude/settings.local.json`
+
+## Usage
+
+### Basic Delegation
+```javascript
+const { HeadlessExecutor } = require('./headless-executor');
+
+const result = await HeadlessExecutor.execute('glm', 'Refactor auth.js', {
+  cwd: '/path/to/project',
+  outputFormat: 'stream-json',
+  permissionMode: 'acceptEdits',
+  timeout: 600000  // 10 minutes
+});
+
+console.log(result.sessionId);  // For multi-turn
+console.log(result.totalCost);  // Cost in USD
+console.log(result.content);    // Result text
+```
+
+### Multi-Turn Sessions
+```javascript
+// Start session
+const result1 = await HeadlessExecutor.execute('glm', 'Implement feature');
+const sessionId = result1.sessionId;
+
+// Continue session
+const result2 = await HeadlessExecutor.execute('glm', 'Add tests', {
+  resumeSession: true
+});
+
+// Or with specific session ID
+const result3 = await HeadlessExecutor.execute('glm', 'Run tests', {
+  sessionId: sessionId
+});
+```
+
+### Tool Restrictions
+Create `.claude/settings.local.json`:
+```json
+{
+  "permissions": {
+    "allow": ["Bash(git:*)", "Read", "Edit"],
+    "deny": ["Bash(rm:*)", "Bash(sudo:*)"]
+  }
+}
+```
+
+Automatically applied as CLI flags:
+```bash
+--allowedTools "Bash(git:*)" "Read" "Edit" \
+--disallowedTools "Bash(rm:*)" "Bash(sudo:*)"
+```
+
+## Slash Commands
+
+The delegation system is invoked via simple slash commands in `.claude/commands/ccs/`:
+
+### Basic Commands
+- `/ccs:glm "task"` - Delegate to GLM-4.6
+- `/ccs:kimi "task"` - Delegate to Kimi (long-context)
+
+### Multi-Turn Commands
+- `/ccs:glm:continue "follow-up"` - Resume last GLM session
+- `/ccs:kimi:continue "follow-up"` - Resume last Kimi session
+
+Each command directly invokes:
+```bash
+claude -p "$ARGUMENTS" \
+  --settings ~/.ccs/{profile}.settings.json \
+  --output-format stream-json \
+  --permission-mode acceptEdits
+```
+
+## Debug Mode
+
+```bash
+export CCS_DEBUG=1
+```
+
+Enables verbose logging:
+- Permission mode selection
+- Session resumption details
+- Tool restrictions parsing
+- CLI args construction
+- Session persistence events
+
+## Testing
+
+```bash
+# Run all delegation tests
+node tests/unit/delegation/json-output.test.js
+node tests/unit/delegation/permission-mode.test.js
+node tests/unit/delegation/session-manager.test.js
+node tests/unit/delegation/settings-parser.test.js
+node tests/unit/delegation/max-turns.test.js
+node tests/unit/delegation/result-formatter.test.js
+```
+
+**Test Coverage:**
+- JSON output parsing (6 tests)
+- Permission modes (11 tests)
+- Session management (7 tests)
+- Settings parser (6 tests)
+- Auto max-turns (14 tests)
+- Result formatting (14 tests)
+- **Total: 58 tests**
+
+## Architecture
+
+```
+User → SlashCommand (/ccs:glm)
+  → Directly invokes: claude -p
+    → HeadlessExecutor (monitors execution)
+      → SessionManager (load last session)
+      → SettingsParser (tool restrictions)
+      → Parse JSON response
+      → SessionManager (store/update)
+      → ResultFormatter.format()
+  → Display to user
+```
+
+**Key Simplification**: Slash commands invoke `claude -p` directly. No intermediate delegation engine or rule system - just direct headless execution with enhanced features.
+
+## File Permissions
+
+All files should be `644` (rw-r--r--):
+```bash
+chmod 644 bin/delegation/*.js
+```
+
+## Dependencies
+
+- Node.js 14+
+- Claude CLI installed and in PATH
+- Profile settings configured in `~/.ccs/{profile}.settings.json`
+
+## Migration from Legacy System
+
+**Removed components** (as of 2025-11-15):
+- ~~delegation-engine.js~~ - Rule-based decision engine (unused)
+- ~~cwd-resolver.js~~ - Working directory resolution (unused)
+- ~~rules-schema.js~~ - Schema validation (unused)
+- ~~delegation-rules.json~~ - Configuration file (not created)
+
+**Why removed**: Current slash commands directly invoke `claude -p` without intermediate orchestration. The delegation engine, CWD resolver, and rules schema were designed for a more complex system that was never fully integrated.
+
+**Result**: 44% code reduction (1,755 → 975 lines) with same functionality.
+
+## References
+
+- Official docs: https://code.claude.com/docs/en/headless.md
+- Skill: `.claude/skills/ccs-delegation/`
+- Commands: `.claude/commands/ccs/`
+- Tests: `tests/unit/delegation/`

package/bin/delegation/delegation-handler.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+'use strict';
+
+const { HeadlessExecutor } = require('./headless-executor');
+const { SessionManager } = require('./session-manager');
+const { ResultFormatter } = require('./result-formatter');
+const { DelegationValidator } = require('../utils/delegation-validator');
+const { SettingsParser } = require('./settings-parser');
+
+/**
+ * Delegation command handler
+ * Routes -p flag commands to HeadlessExecutor with enhanced features
+ */
+class DelegationHandler {
+  /**
+   * Route delegation command
+   * @param {Array<string>} args - Full args array from ccs.js
+   */
+  async route(args) {
+    try {
+      // 1. Parse args into { profile, prompt, options }
+      const parsed = this._parseArgs(args);
+
+      // 2. Detect special profiles (glm:continue, kimi:continue)
+      if (parsed.profile.includes(':continue')) {
+        return await this._handleContinue(parsed);
+      }
+
+      // 3. Validate profile
+      this._validateProfile(parsed.profile);
+
+      // 4. Execute via HeadlessExecutor
+      const result = await HeadlessExecutor.execute(
+        parsed.profile,
+        parsed.prompt,
+        parsed.options
+      );
+
+      // 5. Format and display results
+      const formatted = ResultFormatter.format(result);
+      console.log(formatted);
+
+      // 6. Exit with proper code
+      process.exit(result.exitCode || 0);
+    } catch (error) {
+      console.error(`[X] Delegation error: ${error.message}`);
+      if (process.env.CCS_DEBUG) {
+        console.error(error.stack);
+      }
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Handle continue command (resume last session)
+   * @param {Object} parsed - Parsed args
+   */
+  async _handleContinue(parsed) {
+    const baseProfile = parsed.profile.replace(':continue', '');
+
+    // Get last session from SessionManager
+    const sessionMgr = new SessionManager();
+    const lastSession = sessionMgr.getLastSession(baseProfile);
+
+    if (!lastSession) {
+      console.error(`[X] No previous session found for ${baseProfile}`);
+      console.error(`    Start a new session first with: ccs ${baseProfile} -p "task"`);
+      process.exit(1);
+    }
+
+    // Execute with resume flag
+    const result = await HeadlessExecutor.execute(
+      baseProfile,
+      parsed.prompt,
+      {
+        ...parsed.options,
+        resumeSession: true,
+        sessionId: lastSession.sessionId
+      }
+    );
+
+    const formatted = ResultFormatter.format(result);
+    console.log(formatted);
+
+    process.exit(result.exitCode || 0);
+  }
+
+  /**
+   * Parse args into structured format
+   * @param {Array<string>} args - Raw args
+   * @returns {Object} { profile, prompt, options }
+   */
+  _parseArgs(args) {
+    // Extract profile (first non-flag arg or 'default')
+    const profile = this._extractProfile(args);
+
+    // Extract prompt from -p or --prompt
+    const prompt = this._extractPrompt(args);
+
+    // Extract options (--timeout, --permission-mode, etc.)
+    const options = this._extractOptions(args);
+
+    return { profile, prompt, options };
+  }
+
+  /**
+   * Extract profile from args (first non-flag arg)
+   * @param {Array<string>} args - Args array
+   * @returns {string} Profile name
+   */
+  _extractProfile(args) {
+    // Find first arg that doesn't start with '-' and isn't -p value
+    let skipNext = false;
+    for (let i = 0; i < args.length; i++) {
+      if (skipNext) {
+        skipNext = false;
+        continue;
+      }
+
+      if (args[i] === '-p' || args[i] === '--prompt') {
+        skipNext = true;
+        continue;
+      }
+
+      if (!args[i].startsWith('-')) {
+        return args[i];
+      }
+    }
+
+    // No profile specified, return null (will error in validation)
+    return null;
+  }
+
+  /**
+   * Extract prompt from -p flag
+   * @param {Array<string>} args - Args array
+   * @returns {string} Prompt text
+   */
+  _extractPrompt(args) {
+    const pIndex = args.indexOf('-p');
+    const promptIndex = args.indexOf('--prompt');
+
+    const index = pIndex !== -1 ? pIndex : promptIndex;
+
+    if (index === -1 || index === args.length - 1) {
+      console.error('[X] Missing prompt after -p flag');
+      console.error('    Usage: ccs glm -p "task description"');
+      process.exit(1);
+    }
+
+    return args[index + 1];
+  }
+
+  /**
+   * Extract options from remaining args
+   * @param {Array<string>} args - Args array
+   * @returns {Object} Options for HeadlessExecutor
+   */
+  _extractOptions(args) {
+    const cwd = process.cwd();
+
+    // Read default permission mode from .claude/settings.local.json
+    // Falls back to 'acceptEdits' if file doesn't exist
+    const defaultPermissionMode = SettingsParser.parseDefaultPermissionMode(cwd);
+
+    const options = {
+      cwd,
+      outputFormat: 'stream-json',
+      permissionMode: defaultPermissionMode
+    };
+
+    // Parse permission-mode (CLI flag overrides settings file)
+    const permModeIndex = args.indexOf('--permission-mode');
+    if (permModeIndex !== -1 && permModeIndex < args.length - 1) {
+      options.permissionMode = args[permModeIndex + 1];
+    }
+
+    // Parse timeout
+    const timeoutIndex = args.indexOf('--timeout');
+    if (timeoutIndex !== -1 && timeoutIndex < args.length - 1) {
+      options.timeout = parseInt(args[timeoutIndex + 1], 10);
+    }
+
+    return options;
+  }
+
+  /**
+   * Validate profile exists and is configured
+   * @param {string} profile - Profile name
+   */
+  _validateProfile(profile) {
+    if (!profile) {
+      console.error('[X] No profile specified');
+      console.error('    Usage: ccs <profile> -p "task"');
+      console.error('    Examples: ccs glm -p "task", ccs kimi -p "task"');
+      process.exit(1);
+    }
+
+    // Use DelegationValidator to check profile
+    const validation = DelegationValidator.validate(profile);
+    if (!validation.valid) {
+      console.error(`[X] Profile '${profile}' is not configured for delegation`);
+      console.error(`    ${validation.error}`);
+      console.error('');
+      console.error('    Run: ccs doctor');
+      console.error('    Or configure: ~/.ccs/${profile}.settings.json');
+      process.exit(1);
+    }
+  }
+}
+
+module.exports = DelegationHandler;