Raw Protocol

TaskDaemon raw protocol guide

Raw Protocol

Write handlers in any language without an SDK using the raw stdin/stdout protocol.

Protocol Overview

TaskDaemon communicates with handlers via:

• Input: JSON task objects sent to stdin (one per line)
• Output: JSON result objects written to stdout (one per line)

The handler process stays alive and processes multiple tasks.

Input Format

Each line on stdin is a JSON object:

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "task_type": "process",
  "task_data": {"key": "value"},
  "attempt": 1
}

Field	Type	Description
task_id	string	Unique task identifier (UUID)
task_type	string	Handler type from config
task_data	JSON value	Arbitrary input data from client
attempt	number	Current attempt number (1-indexed)

The handler request uses attempt = stored attempts + 1, starting at attempt: 1. API attempts starts at zero and increments on retry scheduling or a Failed marking; successful completion does not increment it. An initial success therefore has request attempt: 1 and API attempts: 0, while an initial terminal failure stores attempts: 1. Recovery can repeat the same request attempt, so this number is not a unique execution counter.

The daemon retries only valid status: "error" responses with retryable: true, subject to the task’s stored retry budget and backoff. Execution timeout or broken protocol/I/O is a terminal failure, and the unusable handler stream is stopped before reuse.

Output Format

Write one JSON object per line to stdout.

Success Response

{"status": "success", "result": {"key": "value"}}

Error Response

{"status": "error", "error": "Error message", "retryable": false}

Field	Type	Description
status	string	"success" or "error"
result	any	Result data (success only)
error	string	Error message (error only)
retryable	boolean	Whether to retry (error only, default: false)

Example Implementations

Python (No SDK)

import json
import sys

for line in sys.stdin:
    task = json.loads(line)

    try:
        # Process task
        name = task["task_data"].get("name", "World")
        result = {"message": f"Hello, {name}!"}
        response = {"status": "success", "result": result}
    except Exception as e:
        response = {"status": "error", "error": str(e), "retryable": False}

    print(json.dumps(response), flush=True)

Node.js (No SDK)

const readline = require('readline');

const rl = readline.createInterface({ input: process.stdin });

rl.on('line', (line) => {
  const task = JSON.parse(line);

  try {
    const name = task.task_data.name || 'World';
    const result = { message: `Hello, ${name}!` };
    console.log(JSON.stringify({ status: 'success', result }));
  } catch (e) {
    console.log(JSON.stringify({ status: 'error', error: String(e), retryable: false }));
  }
});

Ruby

require 'json'

STDOUT.sync = true

STDIN.each_line do |line|
  task = JSON.parse(line)

  begin
    name = task['task_data']['name'] || 'World'
    result = { message: "Hello, #{name}!" }
    puts JSON.generate({ status: 'success', result: result })
  rescue => e
    puts JSON.generate({ status: 'error', error: e.message, retryable: false })
  end
end

PHP

<?php
while ($line = fgets(STDIN)) {
    $task = json_decode($line, true);

    try {
        $name = $task['task_data']['name'] ?? 'World';
        $result = ['message' => "Hello, {$name}!"];
        $response = ['status' => 'success', 'result' => $result];
    } catch (Exception $e) {
        $response = ['status' => 'error', 'error' => $e->getMessage(), 'retryable' => false];
    }

    echo json_encode($response) . "\n";
    flush();
}

Bash

#!/bin/bash
while IFS= read -r line; do
    name=$(echo "$line" | jq -r '.task_data.name // "World"')
    jq -nc --arg name "$name" '{status:"success", result:{message:("Hello, " + $name + "!")}}'
done

Perl

use JSON;
use strict;

$| = 1;  # Autoflush

while (my $line = <STDIN>) {
    my $task = decode_json($line);
    my $name = $task->{task_data}{name} // 'World';

    print encode_json({
        status => 'success',
        result => { message => "Hello, $name!" }
    }) . "\n";
}

Important Requirements

1. Flush Output

Always flush stdout after writing to ensure TaskDaemon receives the response immediately:

print(json.dumps(response), flush=True)  # Python

// Node.js console.log auto-flushes
console.log(JSON.stringify(response));

STDOUT.sync = true  # Ruby

2. One Response Per Task

Write exactly one JSON response line per input line. Send diagnostic logs to stderr, especially JSON-formatted logs that could be mistaken for responses.

3. Keep Running

The handler process stays alive and processes multiple tasks. Don’t exit after one task:

# Wrong - exits after one task
task = json.loads(input())
print(json.dumps(result))

# Correct - keeps running
for line in sys.stdin:
    task = json.loads(line)
    print(json.dumps(result), flush=True)

4. Handle Errors Gracefully

Return error status instead of crashing:

try:
    result = process(task)
    response = {"status": "success", "result": result}
except Exception as e:
    response = {"status": "error", "error": str(e), "retryable": False}

5. Use Unbuffered I/O

Configure your runtime for unbuffered or line-buffered I/O:

# Python
ENV PYTHONUNBUFFERED=1
CMD ["python", "-u", "handler.py"]

# Node.js (auto-flushes)
CMD ["node", "handler.js"]

# Ruby
CMD ["ruby", "-e", "$stdout.sync=true; load 'handler.rb'"]

Dockerfile Template

FROM your-base-image

COPY handler.ext /app/
WORKDIR /app

# Ensure unbuffered output (language-specific)
ENV PYTHONUNBUFFERED=1

CMD ["your-runtime", "handler.ext"]

Testing Handlers Locally

Test your handler without TaskDaemon:

echo '{"task_id":"test","task_type":"greet","task_data":{"name":"World"},"attempt":1}' | ./handler

Expected output:

{"status":"success","result":{"message":"Hello, World!"}}