Skip to main content

​
Overview

The worker runner is the core execution environment for Longshot tasks running in Modal sandboxes. It orchestrates the execution of the pi-coding-agent with full filesystem and search capabilities, manages git operations, and produces structured handoff results.

​
Main Function

​
runWorker()

Executes a coding task in an isolated sandbox environment. 
export async function runWorker(): Promise<void>
Process Flow:
  1. Reads task payload from /workspace/task.json
  2. Enables distributed tracing if trace context is provided
  3. Writes worker instructions to /workspace/AGENTS.md
  4. Registers custom LLM provider and model
  5. Creates agent session with full Pi capabilities (7 tools)
  6. Runs agent prompt with task description
  7. Performs safety-net commit for uncommitted changes
  8. Runs post-agent build check (tsc --noEmit) if TypeScript project
  9. Extracts git diff statistics and metrics
  10. Writes handoff result to /workspace/result.json
Example Task Payload: 
{
  "task": {
    "id": "agent-001",
    "description": "Implement user authentication",
    "scope": ["src/auth/", "src/middleware/"],
    "acceptance": "Users can login and logout",
    "branch": "worker/agent-001"
  },
  "systemPrompt": "You are an expert TypeScript developer...",
  "llmConfig": {
    "endpoint": "https://api.example.com/v1",
    "model": "glm-4-flash",
    "maxTokens": 8192,
    "temperature": 0.7,
    "apiKey": "sk-..."
  },
  "trace": {
    "traceId": "abc123",
    "parentSpanId": "span456"
  }
}

​
Helper Functions

​
buildTaskPrompt()

Constructs the prompt that gets sent to the coding agent. 
export function buildTaskPrompt(task: Task): string
Parameters:
  • task - Task object with id, description, scope, acceptance criteria, and branch
Returns: Formatted prompt string including task metadata and instructions Example Output: 
## Task: agent-001
**Description:** Implement user authentication
**Scope (files to focus on):** src/auth/, src/middleware/
**Acceptance criteria:** Users can login and logout
**Branch:** worker/agent-001

Complete this task. Commit your changes when done. Stay focused on the scoped files.

​
Tool Configuration

​
Full Pi Tools

The worker provides all 7 built-in Pi coding agent tools: 
const fullPiTools = [...codingTools, grepTool, findTool, lsTool]
Available Tools:
  • read - Read files
  • bash - Execute shell commands
  • edit - Edit file contents
  • write - Write new files
  • grep - Ripgrep-powered content search
  • find - Glob-based file search
  • ls - Directory listing

​
Artifact Filtering

The worker automatically excludes build artifacts from git diffs and metrics: 
const ARTIFACT_PATTERNS = [
  /^node_modules\//,
  /^\.next\//,
  /^dist\//,
  /^build\//,
  /^out\//,
  /^\.turbo\//,
  /^\.tsbuildinfo$/,
  /^package-lock\.json$/,
  /^pnpm-lock\.yaml$/,
  /^yarn\.lock$/,
  /^\.pnpm-store\//,
]

​
Handoff Structure

The worker produces a structured handoff result: 
interface Handoff {
  taskId: string
  status: 'complete' | 'failed'
  summary: string
  diff: string
  filesChanged: string[]
  concerns: string[]
  suggestions: string[]
  buildExitCode?: number | null
  metrics: {
    linesAdded: number
    linesRemoved: number
    filesCreated: number
    filesModified: number
    tokensUsed: number
    toolCallCount: number
    durationMs: number
  }
}

​
Error Handling

​
Empty LLM Response Detection

The worker detects and handles empty LLM responses: 
const isEmptyResponse = tokensUsed === 0 && toolCallCount === 0
When detected:
  • Task status is marked as failed
  • Concerns include “Empty LLM response — possible API failure”
  • Safety-net commit is skipped
  • Suggestions provided for troubleshooting

​
Build Validation

For TypeScript projects, the worker runs tsc --noEmit after agent execution: 
try {
  execSync('npx tsc --noEmit', { cwd: WORK_DIR, timeout: 60_000 })
  buildExitCode = 0
} catch (buildErr) {
  buildExitCode = 1
  // Added to concerns array
}

​
Environment

Working Directory: /workspace/repo File Locations:
  • Task input: /workspace/task.json
  • Result output: /workspace/result.json
  • Worker instructions: /workspace/AGENTS.md

​
Tracing Integration

The worker supports distributed tracing via trace context propagation: 
if (payload.trace) {
  const tracer = Tracer.fromPropagated(payload.trace)
  workerSpan = tracer.startSpan('sandbox.worker', {
    taskId: task.id,
    agentId: `sandbox-${task.id}`
  })
}
Span Events:
  • sandbox.agentSessionCreate - Before creating agent session
  • sandbox.agentPromptStart - Before running prompt
  • sandbox.agentPromptEnd - After prompt completion
Span Attributes:
  • toolCallCount - Number of tool invocations
  • tokensUsed - Total tokens consumed
  • filesChanged - Files modified count
  • linesAdded / linesRemoved - Code change metrics
  • durationMs - Total execution time

Build docs developers (and LLMs) love

Get started for freeTalk to us