@itz4blitz/agentful 0.5.1 → 1.0.1

package/README.md

@@ -4,29 +4,24 @@ A carrot on a stick for Claude Code
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://badge.fury.io/js/%40itz4blitz%2Fagentful.svg)](https://www.npmjs.com/package/@itz4blitz/agentful)
-[![Tests](https://img.shields.io/badge/tests-370%20passing-brightgreen)](https://github.com/itz4blitz/agentful)
-[![Coverage](https://img.shields.io/badge/coverage-98.26%25-brightgreen)](https://github.com/itz4blitz/agentful)
+[![CI Status](https://github.com/itz4blitz/agentful/actions/workflows/pipeline.yml/badge.svg)](https://github.com/itz4blitz/agentful/actions)
 
 ## Overview
 
-agentful is a production-ready Claude Code configuration that provides structured development through specialized AI agents. It coordinates multiple agents to implement features, write tests, and validate code quality according to a defined product specification, with human checkpoints for key decisions.
-
-**Production Quality**: Enterprise-grade testing (370 tests), 98.26% code coverage, comprehensive error handling, and lifecycle hooks for validation and metrics.
+agentful is a Claude Code configuration that provides structured development through specialized AI agents. It coordinates multiple agents to implement features, write tests, and validate code quality according to a defined product specification.
 
 ## Web Configurator
 
 Configure your agentful installation with an interactive web interface:
 
-**[agentful.app/configure](https://agentful.app/configure)**
+**[agentful.app](https://agentful.app)**
 
 - Visual component selection
-- 5 optimized presets
+- 2 optimized presets
 - Custom configurations
 - Shareable setup URLs
 - No CLI required
 
-See the [Web Configurator Guide](https://agentful.app/getting-started/configurator) for details.
-
 ## Installation
 
 ### Default Installation (Recommended)
@@ -40,7 +35,6 @@ npx @itz4blitz/agentful init
 This installs:
 - **8 agents**: orchestrator, architect, backend, frontend, tester, reviewer, fixer, product-analyzer
 - **6 skills**: product-tracking, validation, testing, conversation, product-planning, deployment
-- **Hooks**: health-check (configurable)
 - **Quality gates**: types, tests, coverage, lint, security, dead-code
 
 **Tech stack is auto-detected** on first run (TypeScript, Python, React, etc.) - no need to specify.
@@ -71,17 +65,16 @@ npx @itz4blitz/agentful presets
 
 ### Shareable Configurations
 
-Use a configuration from [agentful.app/configure](https://agentful.app/configure):
+Use a configuration from the web configurator:
 
 ```bash
-npx @itz4blitz/agentful init --config=https://agentful.app/c/abc12345
+npx @itz4blitz/agentful init --config=<shareable-url>
 ```
 
 **Available Flags:**
 - `--preset=<name>` - Use a preset configuration
 - `--agents=<list>` - Comma-separated list of agents (orchestrator, backend, frontend, tester, reviewer, fixer, architect, product-analyzer)
 - `--skills=<list>` - Comma-separated list of skills (validation, testing, product-tracking, conversation, product-planning, deployment)
-- `--hooks=<list>` - Comma-separated list of hooks (health-check, typescript-validation, notifications, format-on-save)
 - `--gates=<list>` - Comma-separated list of quality gates (types, tests, coverage, lint, security, dead-code)
 
 Flags override preset values when both are specified.
@@ -196,7 +189,7 @@ For projects with existing code:
 
 ### Agent System
 
-agentful uses seven specialized agents:
+agentful uses eight specialized agents:
 
 | Agent | Responsibility |
 |-------|---------------|
@@ -207,15 +200,16 @@ agentful uses seven specialized agents:
 | tester | Writes unit, integration, and end-to-end tests |
 | reviewer | Validates code quality, security, and standards |
 | fixer | Resolves validation failures and test errors |
+| product-analyzer | Analyzes product specs for gaps, ambiguities, and readiness scoring |
 
 ### Quality Gates
 
-Code changes are validated against 6 core automated quality gates:
+Code changes are validated against 6 automated quality gates:
 
 - Type checking (TypeScript, Flow, etc.)
 - Linting (ESLint, Biome, etc.)
-- Test execution (all tests must pass)
-- Code coverage (minimum 80%)
+- Test execution
+- Code coverage
 - Security scanning
 - Dead code detection
 
@@ -230,13 +224,11 @@ Runtime state is stored in `.agentful/` (gitignored, managed by npm package):
   - New projects: Starts with declared stack (`confidence: 0.4`)
   - Existing projects: Detected from code (`confidence: 0.8-1.0`)
   - Re-analyzed after first implementation in new projects
-- `last-validation.json` - Latest test/lint results
 - `conversation-history.json` - Session tracking
-- `product-analysis.json` - Readiness analysis (generated by `/agentful-product`)
 
 User configuration is stored in `.claude/` (version controlled):
 
-- `agents/` - Agent definitions (core + custom + ephemeral)
+- `agents/` - Agent definitions
 - `commands/` - Slash commands
 - `product/` - Product specifications
   - `index.md` - Main product spec (user editable)
@@ -246,20 +238,23 @@ User configuration is stored in `.claude/` (version controlled):
   - `product-tracking/` - Progress calculation and state tracking
   - `product-planning/` - Product specification guidance
   - `validation/` - Quality gate checks and tool detection
+  - `testing/` - Test strategy and coverage
+  - `deployment/` - Deployment preparation and validation
 - `settings.json` - Project configuration
 
-**See [ARCHITECTURE.md](./ARCHITECTURE.md) for detailed explanation of file organization.**
-
 ## Commands
 
 | Command | Description |
 |---------|-------------|
+| `/agentful` | Main agentful command - shows help and available commands |
 | `/agentful-product` | Smart product planning: create, analyze, and refine requirements |
 | `/agentful-start` | Start or resume structured development |
 | `/agentful-status` | Display progress and current state |
 | `/agentful-validate` | Run all quality checks |
 | `/agentful-decide` | Answer pending decisions |
 | `/agentful-update` | Smart update mechanism - fetches latest templates and gracefully migrates changes |
+| `/agentful-analyze` | Analyze architecture and generate specialized agents for your tech stack |
+| `/agentful-generate` | Generate specialized agents from architecture analysis |
 
 ## CI/CD Integration
 
@@ -273,7 +268,7 @@ agentful ci --generate-workflow
 agentful ci
 ```
 
-See `examples/` for sample workflow configurations ([GitHub Actions](examples/github-actions.yml), [GitLab CI](examples/gitlab-ci.yml), [Jenkins](examples/jenkins.groovy)).
+See `examples/` for sample workflow configurations ([GitHub Actions](examples/github-actions-pipeline.yml), [GitLab CI](examples/gitlab-ci-cd.yml)).
 
 ## Remote Execution
 
@@ -290,7 +285,7 @@ agentful serve --auth=hmac --secret=$SECRET --https --cert=cert.pem --key=key.pe
 agentful serve --auth=none
 ```
 
-Three authentication modes: **Tailscale** (WireGuard encryption), **HMAC** (signature-based with replay protection), **SSH tunnel** (localhost-only). See `examples/server-deployment.sh` for complete deployment examples including Oracle Cloud Free Tier, Let's Encrypt SSL, and systemd service configuration.
+Three authentication modes: **Tailscale** (WireGuard encryption), **HMAC** (signature-based with replay protection), **SSH tunnel** (localhost-only).
 
 ## Technology Support
 
@@ -311,13 +306,7 @@ agentful detects and adapts to your technology stack automatically:
 
 ## Documentation
 
-Full documentation: [agentful.app](https://agentful.app)
-
-Key guides:
-- [CI/CD Integration](https://agentful.app/ci-integration) - Deploy agents to production
-- [Quick Start](https://agentful.app/getting-started/quick-start) - Get started in 5 minutes
-- [Agent Architecture](https://agentful.app/concepts/architecture) - How agents work
-- [Commands Reference](https://agentful.app/commands) - All available commands
+Documentation: [agentful.app](https://agentful.app)
 
 ## Project Structure
 
@@ -337,7 +326,6 @@ your-project/
 │   ├── completion.json
 │   ├── decisions.json
 │   ├── architecture.json
-│   ├── last-validation.json
 │   └── conversation-history.json
 └── src/                            # Source code
 ```
@@ -350,5 +338,4 @@ MIT
 
 - GitHub: [github.com/itz4blitz/agentful](https://github.com/itz4blitz/agentful)
 - Issues: [github.com/itz4blitz/agentful/issues](https://github.com/itz4blitz/agentful/issues)
-- Documentation: [agentful.app](https://agentful.app)
-- NPM: [npmjs.com/@itz4blitz/agentful](https://www.npmjs.com/package/@itz4blitz/agentful)
+- NPM: [npmjs.com/package/@itz4blitz/agentful](https://www.npmjs.com/package/@itz4blitz/agentful)

package/bin/cli.js

@@ -996,12 +996,272 @@ async function remote(args) {
   }
 }
 
+/**
+ * Get PID file path
+ * @returns {string} Path to PID file
+ */
+function getPidFilePath() {
+  return path.join(process.cwd(), '.agentful', 'server.pid');
+}
+
+/**
+ * Start server in daemon mode
+ * @param {string[]} args - Original args
+ * @param {Object} config - Server configuration
+ */
+async function startDaemon(args, config) {
+  const { spawn } = await import('child_process');
+
+  // Check if daemon is already running
+  const pidFile = getPidFilePath();
+  if (fs.existsSync(pidFile)) {
+    const pid = parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10);
+
+    // Check if process is still running
+    try {
+      process.kill(pid, 0); // Signal 0 checks if process exists
+      log(colors.yellow, 'Server is already running');
+      log(colors.dim, `PID: ${pid}`);
+      console.log('');
+      log(colors.dim, 'To stop: agentful serve --stop');
+      log(colors.dim, 'To check status: agentful serve --status');
+      process.exit(1);
+    } catch (error) {
+      // Process doesn't exist, clean up stale PID file
+      fs.unlinkSync(pidFile);
+    }
+  }
+
+  // Ensure .agentful directory exists
+  const agentfulDir = path.join(process.cwd(), '.agentful');
+  if (!fs.existsSync(agentfulDir)) {
+    fs.mkdirSync(agentfulDir, { recursive: true });
+  }
+
+  // Prepare args for child process (remove --daemon flag)
+  const childArgs = args.filter(arg => !arg.startsWith('--daemon') && arg !== '-d');
+
+  // Spawn detached child process
+  const child = spawn(
+    process.argv[0], // node executable
+    [process.argv[1], 'serve', ...childArgs], // script path and args
+    {
+      detached: true,
+      stdio: 'ignore',
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        AGENTFUL_DAEMON: '1' // Flag to indicate we're running as daemon
+      }
+    }
+  );
+
+  // Write PID file
+  fs.writeFileSync(pidFile, child.pid.toString(), 'utf-8');
+
+  // Unref to allow parent to exit
+  child.unref();
+
+  // Show success message
+  log(colors.green, `Server started in background (PID: ${child.pid})`);
+  console.log('');
+  log(colors.dim, `PID file: ${pidFile}`);
+  log(colors.dim, `Port: ${config.port}`);
+  log(colors.dim, `Auth: ${config.auth}`);
+  console.log('');
+  log(colors.dim, 'Commands:');
+  log(colors.dim, '  agentful serve --stop     Stop the daemon');
+  log(colors.dim, '  agentful serve --status   Check daemon status');
+  console.log('');
+}
+
+/**
+ * Stop daemon server
+ */
+async function stopDaemon() {
+  const pidFile = getPidFilePath();
+
+  if (!fs.existsSync(pidFile)) {
+    log(colors.yellow, 'No daemon server running');
+    log(colors.dim, 'PID file not found');
+    process.exit(1);
+  }
+
+  const pid = parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10);
+
+  // Try to kill the process
+  try {
+    process.kill(pid, 'SIGTERM');
+
+    // Wait a moment for graceful shutdown
+    await new Promise(resolve => setTimeout(resolve, 1000));
+
+    // Check if process is still running
+    try {
+      process.kill(pid, 0);
+      // Still running, force kill
+      log(colors.yellow, 'Graceful shutdown failed, forcing...');
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // Process stopped successfully
+    }
+
+    // Remove PID file
+    fs.unlinkSync(pidFile);
+
+    log(colors.green, `Server stopped (PID: ${pid})`);
+  } catch (error) {
+    if (error.code === 'ESRCH') {
+      // Process doesn't exist
+      log(colors.yellow, 'Server process not found (stale PID file)');
+      fs.unlinkSync(pidFile);
+    } else if (error.code === 'EPERM') {
+      log(colors.red, `Permission denied to kill process ${pid}`);
+      log(colors.dim, 'Try: sudo agentful serve --stop');
+      process.exit(1);
+    } else {
+      log(colors.red, `Failed to stop server: ${error.message}`);
+      process.exit(1);
+    }
+  }
+}
+
+/**
+ * Check daemon server status
+ */
+async function checkDaemonStatus() {
+  const pidFile = getPidFilePath();
+
+  if (!fs.existsSync(pidFile)) {
+    log(colors.yellow, 'No daemon server running');
+    log(colors.dim, 'PID file not found');
+    console.log('');
+    log(colors.dim, 'Start daemon: agentful serve --daemon');
+    process.exit(1);
+  }
+
+  const pid = parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10);
+
+  // Check if process is running
+  try {
+    process.kill(pid, 0); // Signal 0 just checks if process exists
+
+    log(colors.green, 'Server is running');
+    console.log('');
+    log(colors.dim, `PID: ${pid}`);
+    log(colors.dim, `PID file: ${pidFile}`);
+
+    // Try to get more info from /proc (Linux/macOS)
+    try {
+      const { execSync } = await import('child_process');
+      const psOutput = execSync(`ps -p ${pid} -o comm,etime,rss`, { encoding: 'utf-8' });
+      const lines = psOutput.trim().split('\n');
+      if (lines.length > 1) {
+        const [cmd, etime, rss] = lines[1].trim().split(/\s+/);
+        console.log('');
+        log(colors.dim, `Uptime: ${etime}`);
+        log(colors.dim, `Memory: ${Math.round(parseInt(rss) / 1024)} MB`);
+      }
+    } catch {
+      // ps command failed, skip detailed info
+    }
+
+    console.log('');
+    log(colors.dim, 'Commands:');
+    log(colors.dim, '  agentful serve --stop     Stop the daemon');
+  } catch (error) {
+    if (error.code === 'ESRCH') {
+      log(colors.yellow, 'Server not running (stale PID file)');
+      log(colors.dim, `PID file exists but process ${pid} not found`);
+      console.log('');
+      log(colors.dim, 'Clean up: rm .agentful/server.pid');
+      process.exit(1);
+    } else {
+      log(colors.red, `Failed to check status: ${error.message}`);
+      process.exit(1);
+    }
+  }
+}
+
 /**
  * Serve command - Start remote execution server
  */
 async function serve(args) {
   const flags = parseFlags(args);
 
+  // Handle --stop subcommand
+  if (flags.stop) {
+    return await stopDaemon();
+  }
+
+  // Handle --status subcommand
+  if (flags.status) {
+    return await checkDaemonStatus();
+  }
+
+  // Handle --help flag first
+  if (flags.help || flags.h) {
+    showBanner();
+    log(colors.bright, 'Agentful Remote Execution Server');
+    console.log('');
+    log(colors.dim, 'Start a secure HTTP server for remote agent execution.');
+    console.log('');
+    log(colors.bright, 'USAGE:');
+    console.log(`  ${colors.green}agentful serve${colors.reset} ${colors.dim}[options]${colors.reset}`);
+    console.log('');
+    log(colors.bright, 'AUTHENTICATION MODES:');
+    console.log(`  ${colors.cyan}--auth=tailscale${colors.reset}   ${colors.dim}(default) Tailscale network only${colors.reset}`);
+    console.log(`  ${colors.cyan}--auth=hmac${colors.reset}        ${colors.dim}HMAC signature authentication (requires --secret)${colors.reset}`);
+    console.log(`  ${colors.cyan}--auth=none${colors.reset}        ${colors.dim}No authentication (binds to all interfaces, use with SSH tunnel)${colors.reset}`);
+    console.log('');
+    log(colors.bright, 'OPTIONS:');
+    console.log(`  ${colors.yellow}--port=<number>${colors.reset}      ${colors.dim}Server port (default: 3000)${colors.reset}`);
+    console.log(`  ${colors.yellow}--secret=<key>${colors.reset}       ${colors.dim}HMAC secret key (required for --auth=hmac)${colors.reset}`);
+    console.log(`  ${colors.yellow}--https${colors.reset}             ${colors.dim}Enable HTTPS (requires --cert and --key)${colors.reset}`);
+    console.log(`  ${colors.yellow}--cert=<path>${colors.reset}        ${colors.dim}SSL certificate file path${colors.reset}`);
+    console.log(`  ${colors.yellow}--key=<path>${colors.reset}         ${colors.dim}SSL private key file path${colors.reset}`);
+    console.log(`  ${colors.yellow}--daemon, -d${colors.reset}        ${colors.dim}Run server in background (daemon mode)${colors.reset}`);
+    console.log(`  ${colors.yellow}--stop${colors.reset}              ${colors.dim}Stop background server${colors.reset}`);
+    console.log(`  ${colors.yellow}--status${colors.reset}            ${colors.dim}Check background server status${colors.reset}`);
+    console.log(`  ${colors.yellow}--help, -h${colors.reset}          ${colors.dim}Show this help message${colors.reset}`);
+    console.log('');
+    log(colors.bright, 'EXAMPLES:');
+    console.log('');
+    log(colors.dim, '  # Start server with Tailscale auth (default)');
+    console.log(`  ${colors.green}agentful serve${colors.reset}`);
+    console.log('');
+    log(colors.dim, '  # Start server with HMAC authentication');
+    console.log(`  ${colors.green}agentful serve --auth=hmac --secret=your-secret-key${colors.reset}`);
+    console.log('');
+    log(colors.dim, '  # Start HTTPS server with HMAC auth');
+    console.log(`  ${colors.green}agentful serve --auth=hmac --secret=key --https --cert=cert.pem --key=key.pem${colors.reset}`);
+    console.log('');
+    log(colors.dim, '  # Start server without auth (public access, use SSH tunnel)');
+    console.log(`  ${colors.green}agentful serve --auth=none --port=3737${colors.reset}`);
+    console.log('');
+    log(colors.dim, '  # Start server in background (daemon mode)');
+    console.log(`  ${colors.green}agentful serve --daemon${colors.reset}`);
+    console.log('');
+    log(colors.dim, '  # Check daemon status');
+    console.log(`  ${colors.green}agentful serve --status${colors.reset}`);
+    console.log('');
+    log(colors.dim, '  # Stop daemon');
+    console.log(`  ${colors.green}agentful serve --stop${colors.reset}`);
+    console.log('');
+    log(colors.dim, '  # Generate HMAC secret');
+    console.log(`  ${colors.green}openssl rand -hex 32${colors.reset}`);
+    console.log('');
+    log(colors.dim, '  # Generate self-signed certificate');
+    console.log(`  ${colors.green}openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes${colors.reset}`);
+    console.log('');
+    log(colors.bright, 'SECURITY NOTES:');
+    console.log(`  ${colors.yellow}Tailscale mode:${colors.reset} Binds to 0.0.0.0, relies on Tailscale network isolation`);
+    console.log(`  ${colors.yellow}HMAC mode:${colors.reset}      Binds to 0.0.0.0, uses cryptographic signatures (recommended for public networks)`);
+    console.log(`  ${colors.yellow}None mode:${colors.reset}       Binds to 0.0.0.0, no authentication (use SSH tunnel: ssh -L 3000:localhost:3000 user@host)`);
+    console.log('');
+    return;
+  }
+
   // Parse configuration
   const config = {
     auth: flags.auth || 'tailscale',
@@ -1013,6 +1273,9 @@ async function serve(args) {
     projectRoot: process.cwd(),
   };
 
+  // Check if --daemon flag is set
+  const isDaemon = flags.daemon || flags.d;
+
   // Validate auth mode
   const validAuthModes = ['tailscale', 'hmac', 'none'];
   if (!validAuthModes.includes(config.auth)) {
@@ -1027,8 +1290,15 @@ async function serve(args) {
     process.exit(1);
   }
 
-  // Show configuration
-  showBanner();
+  // If daemon mode, fork the process
+  if (isDaemon) {
+    return await startDaemon(args, config);
+  }
+
+  // Show configuration (skip banner if running as daemon child)
+  if (!process.env.AGENTFUL_DAEMON) {
+    showBanner();
+  }
   log(colors.bright, 'Starting Agentful Server');
   console.log('');
   log(colors.dim, `Authentication: ${config.auth}`);
@@ -1036,8 +1306,8 @@ async function serve(args) {
   log(colors.dim, `HTTPS: ${config.https ? 'enabled' : 'disabled'}`);
 
   if (config.auth === 'none') {
-    log(colors.yellow, 'Warning: Server will only accept localhost connections');
-    log(colors.dim, 'Use SSH tunnel for remote access: ssh -L 3000:localhost:3000 user@host');
+    log(colors.yellow, 'Warning: Server running with no authentication (binds to all interfaces)');
+    log(colors.dim, 'Recommended: Use SSH tunnel for remote access: ssh -L 3000:localhost:3000 user@host');
   }
 
   if (config.auth === 'hmac' && !config.secret) {

package/lib/init.js

@@ -91,32 +91,40 @@ export async function initProject(targetDir, config = null) {
     await fs.mkdir(agentfulDir, { recursive: true });
     createdFiles.push('.agentful/');
 
-    // Create state.json
+    // Create state.json (runtime state for orchestrator)
     const stateFile = path.join(agentfulDir, 'state.json');
     const initialState = {
-      initialized: new Date().toISOString(),
-      version: '1.0.0',
-      agents: [],
-      skills: []
+      version: '1.0',
+      current_task: null,
+      current_phase: 'idle',
+      iterations: 0,
+      last_updated: new Date().toISOString(),
+      blocked_on: []
     };
     await fs.writeFile(stateFile, JSON.stringify(initialState, null, 2));
     createdFiles.push('.agentful/state.json');
 
-    // Create completion.json
+    // Create completion.json (feature progress tracking)
     const completionFile = path.join(agentfulDir, 'completion.json');
     const initialCompletion = {
-      agents: {},
-      skills: {},
-      lastUpdated: new Date().toISOString()
+      features: {},
+      gates: {
+        tests_passing: false,
+        no_type_errors: false,
+        no_dead_code: false,
+        coverage_80: false,
+        security_clean: false
+      },
+      overall_progress: 0
     };
     await fs.writeFile(completionFile, JSON.stringify(initialCompletion, null, 2));
     createdFiles.push('.agentful/completion.json');
 
-    // Create decisions.json
+    // Create decisions.json (pending and resolved decisions)
     const decisionsFile = path.join(agentfulDir, 'decisions.json');
     const initialDecisions = {
-      decisions: [],
-      lastUpdated: new Date().toISOString()
+      pending: [],
+      resolved: []
     };
     await fs.writeFile(decisionsFile, JSON.stringify(initialDecisions, null, 2));
     createdFiles.push('.agentful/decisions.json');

package/lib/server/executor.js

@@ -133,13 +133,15 @@ ${agent.instructions}
  * @param {string} [options.projectRoot] - Project root directory
  * @param {number} [options.timeout] - Execution timeout in ms
  * @param {Object} [options.env] - Additional environment variables
- * @returns {Promise<Object>} Execution result
+ * @param {boolean} [options.async=false] - If true, return immediately with executionId
+ * @returns {Promise<Object>} Execution result (or just executionId if async=true)
  */
 export async function executeAgent(agentName, task, options = {}) {
   const {
     projectRoot = process.cwd(),
     timeout = 10 * 60 * 1000, // 10 minutes default
     env = {},
+    async = false, // New option for non-blocking execution
   } = options;
 
   // Validate agent name to prevent path traversal
@@ -176,6 +178,55 @@ export async function executeAgent(agentName, task, options = {}) {
 
   executions.set(executionId, execution);
 
+  // If async mode, start execution in background and return immediately
+  if (async) {
+    // Start execution in background (don't await)
+    runAgentExecution(executionId, agentName, task, {
+      projectRoot,
+      timeout,
+      filteredEnv,
+    }).catch((error) => {
+      // Update execution with error if background execution fails
+      const exec = executions.get(executionId);
+      if (exec) {
+        exec.state = ExecutionState.FAILED;
+        exec.endTime = Date.now();
+        exec.error = error.message;
+        exec.exitCode = -1;
+      }
+    });
+
+    return {
+      executionId,
+      state: ExecutionState.PENDING,
+      message: 'Execution started in background',
+    };
+  }
+
+  // Synchronous mode - wait for completion and return full result
+  return runAgentExecution(executionId, agentName, task, {
+    projectRoot,
+    timeout,
+    filteredEnv,
+  });
+}
+
+/**
+ * Internal function to run agent execution
+ * @param {string} executionId - Execution ID
+ * @param {string} agentName - Agent name
+ * @param {string} task - Task description
+ * @param {Object} options - Execution options
+ * @returns {Promise<Object>} Execution result
+ */
+async function runAgentExecution(executionId, agentName, task, options) {
+  const { projectRoot, timeout, filteredEnv } = options;
+  const execution = executions.get(executionId);
+
+  if (!execution) {
+    throw new Error(`Execution ${executionId} not found`);
+  }
+
   try {
     // Load agent definition
     const agent = await loadAgentDefinition(agentName, projectRoot);

package/lib/server/index.js

@@ -243,24 +243,28 @@ export function createServer(config = {}) {
           );
         }
 
-        // Execute agent (non-blocking)
-        const result = executeAgent(body.agent, body.task, {
+        // Log agent execution request
+        console.log(`[${new Date().toISOString()}] Executing agent: ${body.agent}`);
+        console.log(`[${new Date().toISOString()}] Task: ${body.task}`);
+
+        // Start agent execution in background (async mode)
+        const executionTimeout = body.timeout || 10 * 60 * 1000; // Default 10 min for execution
+
+        const result = await executeAgent(body.agent, body.task, {
           projectRoot,
-          timeout: body.timeout,
+          timeout: executionTimeout,
           env: body.env,
+          async: true, // Return immediately with executionId
         });
 
-        // Don't await - return immediately with execution ID
-        result.then(() => {}).catch(() => {}); // Prevent unhandled rejection
-
-        const executionId = (await result).executionId;
+        console.log(`[${new Date().toISOString()}] Execution started: ${result.executionId}`);
 
         res.writeHead(202, { 'Content-Type': 'application/json' });
         res.end(
           JSON.stringify({
-            executionId,
+            executionId: result.executionId,
             message: 'Agent execution started',
-            statusUrl: `/status/${executionId}`,
+            statusUrl: `/status/${result.executionId}`,
           })
         );
       } catch (error) {
@@ -315,6 +319,13 @@ export function createServer(config = {}) {
 
   // Request handler
   const requestHandler = (req, res) => {
+    const startTime = Date.now();
+    const clientIP = req.socket.remoteAddress;
+
+    // Log incoming request
+    const timestamp = new Date().toISOString();
+    console.log(`[${timestamp}] ${req.method} ${req.url} from ${clientIP}`);
+
     // Add CORS headers (restricted by default)
     if (corsOrigin) {
       res.setHeader('Access-Control-Allow-Origin', corsOrigin);
@@ -328,14 +339,27 @@ export function createServer(config = {}) {
     // Handle preflight
     if (req.method === 'OPTIONS') {
       res.writeHead(204);
+      const duration = Date.now() - startTime;
+      console.log(`[${new Date().toISOString()}] Response sent: 204 (${duration}ms)`);
       return res.end();
     }
 
     // Apply rate limiting
     if (!checkRateLimit(req, res)) {
+      const duration = Date.now() - startTime;
+      console.log(`[${new Date().toISOString()}] Response sent: 429 Rate Limited (${duration}ms)`);
       return; // Rate limit exceeded, response already sent
     }
 
+    // Intercept res.end to log responses
+    const originalEnd = res.end;
+    res.end = function(...args) {
+      const duration = Date.now() - startTime;
+      const statusCode = res.statusCode;
+      console.log(`[${new Date().toISOString()}] Response sent: ${statusCode} (${duration}ms)`);
+      originalEnd.apply(res, args);
+    };
+
     // Capture raw body (needed for HMAC verification)
     captureRawBody(req, res, () => {
       // Apply authentication (except for /health)
@@ -384,8 +408,9 @@ export function createServer(config = {}) {
     server = http.createServer(requestHandler);
   }
 
-  // Determine bind address based on auth mode
-  const host = auth === 'none' ? '127.0.0.1' : '0.0.0.0';
+  // Always bind to all interfaces (0.0.0.0)
+  // Security is enforced through authentication middleware, not binding address
+  const host = '0.0.0.0';
 
   return {
     start: () => {
@@ -400,7 +425,7 @@ export function createServer(config = {}) {
           console.log(`Authentication mode: ${auth}`);
 
           if (auth === 'none') {
-            console.log('Server is bound to localhost only - use SSH tunnel for remote access');
+            console.log('Warning: No authentication enabled - use SSH tunnel for secure remote access');
           }
 
           // Start periodic cleanup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itz4blitz/agentful",
-  "version": "0.5.1",
+  "version": "1.0.1",
   "description": "Human-in-the-loop development kit for Claude Code with smart product analysis and natural conversation",
   "type": "module",
   "bin": {

package/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.5.0"
+  "version": "1.0.0"
 }