Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.namastex.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Processes represent the actual execution of attempts. Monitor running AI agents, check resource usage, and control execution. Base URL: http://localhost:8887/api/processes

​
List Processes

Get all active processes. 
GET /api/processes

​
Query Parameters

ParameterTypeDescription
statusenumFilter by status (running, completed, failed)
llmstringFilter by AI agent
 
curl http://localhost:8887/api/processes?status=running

{
  "success": true,
  "data": [
    {
      "id": "proc_abc123",
      "attemptId": "attempt_xyz789",
      "taskId": "task_def456",
      "llm": "claude",
      "status": "running",
      "startedAt": "2024-01-15T10:30:00Z",
      "duration": 45000,
      "resources": {
        "cpuUsage": 45.2,
        "memoryUsage": 512000000,
        "diskIO": 1024000
      },
      "progress": {
        "current": "Generating authentication logic",
        "percentage": 65
      }
    }
  ]
}

​
Get Process

Get detailed process information. 
GET /api/processes/:id

​
Example Response

{
  "success": true,
  "data": {
    "id": "proc_abc123",
    "attemptId": "attempt_xyz789",
    "taskId": "task_def456",
    "llm": "claude",
    "model": "claude-3-5-sonnet-20241022",
    "status": "running",
    "startedAt": "2024-01-15T10:30:00Z",
    "duration": 45000,
    "resources": {
      "cpuUsage": 45.2,
      "memoryUsage": 512000000,
      "diskIO": 1024000,
      "networkIO": 204800
    },
    "progress": {
      "stage": "code_generation",
      "current": "Generating authentication logic",
      "percentage": 65,
      "estimatedRemaining": 25000
    },
    "tokens": {
      "inputTokens": 8420,
      "outputTokens": 1250,
      "estimatedCost": 0.12
    }
  }
}

​
Cancel Process

Stop a running process. 
POST /api/processes/:id/cancel

curl -X POST http://localhost:8887/api/processes/proc_abc123/cancel

{
  "success": true,
  "data": {
    "id": "proc_abc123",
    "status": "cancelled",
    "cancelledAt": "2024-01-15T10:32:00Z"
  }
}

​
Get Process Logs

Stream real-time logs from a process. 
GET /api/processes/:id/logs

​
Query Parameters

ParameterTypeDescription
followbooleanStream logs in real-time
tailintegerNumber of recent lines to show
 
curl "http://localhost:8887/api/processes/proc_abc123/logs?follow=true"

{
  "success": true,
  "data": {
    "processId": "proc_abc123",
    "metrics": [
      {
        "timestamp": "2024-01-15T10:30:00Z",
        "cpu": 45.2,
        "memory": 512000000,
        "diskIO": 1024000,
        "networkIO": 204800
      },
      {
        "timestamp": "2024-01-15T10:30:01Z",
        "cpu": 48.5,
        "memory": 524000000,
        "diskIO": 1126400,
        "networkIO": 225280
      }
    ],
    "averages": {
      "cpu": 46.8,
      "memory": 518000000
    }
  }
}

​
Stop Process

Stop a running execution process. 
POST /api/execution-processes/:id/stop

​
Example Response

{
  "success": true,
  "data": {
    "id": "proc_abc123",
    "status": "stopped",
    "stoppedAt": "2024-01-15T10:35:00Z",
    "duration": 300000
  }
}

​
WebSocket: Stream Process Logs

Stream real-time process logs via WebSocket.

​
Raw Logs Stream

ws://localhost:8887/ws/execution-processes/:id/logs/raw
Streams raw, unprocessed log output from the execution process. Example: 
const ws = new WebSocket('ws://localhost:8887/ws/execution-processes/proc_abc123/logs/raw');

ws.onmessage = (event) => {
  console.log('Raw log:', event.data);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

​
Normalized Logs Stream

ws://localhost:8887/ws/execution-processes/:id/logs/normalized
Streams processed, structured log messages. Example: 
const ws = new WebSocket('ws://localhost:8887/ws/execution-processes/proc_abc123/logs/normalized');

ws.onmessage = (event) => {
  const log = JSON.parse(event.data);
  // { level: 'info', message: '...', timestamp: '...', source: 'executor' }
  console.log(`[${log.level}] ${log.message}`);
};
Message Format: 
{
  "level": "info",
  "message": "Generating authentication logic",
  "timestamp": "2024-01-15T10:30:45Z",
  "source": "executor",
  "metadata": {
    "file": "src/auth.ts",
    "action": "code_generation"
  }
}

​
WebSocket: Stream All Processes

Monitor all execution processes in real-time. 
ws://localhost:8887/ws/execution-processes
Receives updates when any process status changes. Example: 
const ws = new WebSocket('ws://localhost:8887/ws/execution-processes');

ws.onmessage = (event) => {
  const update = JSON.parse(event.data);
  // { type: 'process_started', processId: '...', ... }
  // { type: 'process_completed', processId: '...', ... }
  // { type: 'process_failed', processId: '...', error: '...' }
  console.log('Process update:', update);
};
Event Types:
  • process_started - New process began execution
  • process_progress - Progress update
  • process_completed - Process finished successfully
  • process_failed - Process encountered error
  • process_stopped - Process was stopped by user

​
SDK Examples

import { ForgeClient } from '@automagik/forge-sdk';

const forge = new ForgeClient();

// List running processes
const processes = await forge.processes.list({
  status: 'running'
});

// Get process details
const process = await forge.processes.get('proc_abc123');

// Stop a process
await forge.processes.stop('proc_abc123');

// Monitor progress
const interval = setInterval(async () => {
  const proc = await forge.processes.get('proc_abc123');
  console.log(`Progress: ${proc.progress.percentage}%`);

  if (proc.status !== 'running') {
    clearInterval(interval);
  }
}, 1000);

// Stream raw logs via WebSocket
const rawWs = new WebSocket('ws://localhost:8887/ws/execution-processes/proc_abc123/logs/raw');
rawWs.onmessage = (event) => console.log('Raw:', event.data);

// Stream normalized logs via WebSocket
const normalizedWs = new WebSocket('ws://localhost:8887/ws/execution-processes/proc_abc123/logs/normalized');
normalizedWs.onmessage = (event) => {
  const log = JSON.parse(event.data);
  console.log(`[${log.level}] ${log.message}`);
};

// Monitor all processes
const allProcessesWs = new WebSocket('ws://localhost:8887/ws/execution-processes');
allProcessesWs.onmessage = (event) => {
  const update = JSON.parse(event.data);
  console.log(`Process ${update.type}:`, update.processId);
};

​
Next Steps

Attempts API

Manage task attempts

Tasks API

Create and manage tasks