Skip to main content

​
Type Definitions

Shared domain types for the Longshot multi-agent system.

​
Task

Represents a task assigned by a planner to a worker agent. 
interface Task {
  id: string;
  parentId?: string;
  description: string;
  scope: string[];
  acceptance: string;
  branch: string;
  status: TaskStatus;
  assignedTo?: string;
  createdAt: number;
  startedAt?: number;
  completedAt?: number;
  priority: number;
  conflictSourceBranch?: string;
  retryCount?: number;
}

​
Fields

​
id
string
required
Unique task ID (UUID format)
​
parentId
string
Parent task ID if this is a subtask
​
description
string
required
Natural language description of what to do
​
scope
string[]
required
File paths the worker should focus on
​
acceptance
string
required
Natural language criteria for how to know when the task is complete
​
branch
string
required
Git branch name for this task
​
status
TaskStatus
required
Current task status. See TaskStatus
​
assignedTo
string
Sandbox ID of the assigned worker
​
createdAt
number
required
Unix timestamp in milliseconds when task was created
​
startedAt
number
Unix timestamp in milliseconds when task execution started
​
completedAt
number
Unix timestamp in milliseconds when task was completed
​
priority
number
required
Priority level from 1 (highest) to 10 (lowest)
​
conflictSourceBranch
string
Original branch that conflicted (for conflict-fix tasks)
​
retryCount
number
Number of times this task has been retried (0 = first attempt)

​
TaskStatus

Task lifecycle status. 
type TaskStatus = "pending" | "assigned" | "running" | "complete" | "failed" | "cancelled";
ValueDescription
pendingTask created but not yet assigned
assignedTask assigned to a worker
runningTask currently being executed
completeTask successfully completed
failedTask execution failed
cancelledTask was cancelled

​
AgentRole

Agent role types in the multi-agent system. 
type AgentRole = "root-planner" | "subplanner" | "worker" | "reconciler";
ValueDescription
root-plannerTop-level planning agent
subplannerNested planning agent for task decomposition
workerCode execution agent
reconcilerConflict resolution agent

​
Handoff

Report from a worker back to the planner after completing (or attempting) a task. 
interface Handoff {
  taskId: string;
  status: "complete" | "partial" | "blocked" | "failed";
  summary: string;
  diff: string;
  filesChanged: string[];
  concerns: string[];
  suggestions: string[];
  metrics: {
    linesAdded: number;
    linesRemoved: number;
    filesCreated: number;
    filesModified: number;
    tokensUsed: number;
    toolCallCount: number;
    durationMs: number;
  };
  buildExitCode?: number | null;
}

​
Fields

​
taskId
string
required
ID of the task being reported on
​
status
string
required
Completion status: complete, partial, blocked, or failed
​
summary
string
required
Description of what was accomplished
​
diff
string
required
Git diff output showing all changes
​
filesChanged
string[]
required
List of file paths that were modified
​
concerns
string[]
required
Issues or problems discovered during execution
​
suggestions
string[]
required
Recommendations for the planner
​
metrics
object
required
Execution metrics including:
  • linesAdded: Number of lines added
  • linesRemoved: Number of lines removed
  • filesCreated: Number of new files created
  • filesModified: Number of existing files modified
  • tokensUsed: Total LLM tokens consumed
  • toolCallCount: Number of tool calls made
  • durationMs: Execution duration in milliseconds
​
buildExitCode
number | null
Exit code from tsc --noEmit post-agent build check. null if check did not run

​
SandboxStatus

Worker sandbox status and health information. 
interface SandboxStatus {
  sandboxId: string;
  status: "starting" | "ready" | "working" | "completing" | "terminated" | "error";
  taskId?: string;
  progress?: string;
  healthCheck: {
    lastPing: number;
    consecutiveFailures: number;
  };
  url?: string;
}

​
Fields

​
sandboxId
string
required
Unique identifier for the sandbox
​
status
string
required
Current sandbox state: starting, ready, working, completing, terminated, or error
​
taskId
string
ID of task currently being executed
​
progress
string
Human-readable description of current activity
​
healthCheck
object
required
Health monitoring data:
  • lastPing: Unix timestamp in milliseconds of last health check
  • consecutiveFailures: Number of consecutive failed health checks
​
url
string
Tunnel URL for HTTP access to the sandbox

​
HarnessConfig

Configuration for the Longshot harness system. 
interface HarnessConfig {
  maxWorkers: number;
  workerTimeout: number;
  mergeStrategy: "fast-forward" | "rebase" | "merge-commit";
  llm: {
    endpoints: LLMEndpoint[];
    model: string;
    maxTokens: number;
    temperature: number;
    timeoutMs?: number;
  };
  git: {
    repoUrl: string;
    mainBranch: string;
    branchPrefix: string;
  };
  sandbox: {
    imageTag: string;
    cpuCores: number;
    memoryMb: number;
    idleTimeout: number;
  };
}

​
Fields

​
maxWorkers
number
required
Maximum number of concurrent worker sandboxes
​
workerTimeout
number
required
Worker execution timeout in milliseconds
​
mergeStrategy
string
required
Git merge strategy: fast-forward, rebase, or merge-commit
​
llm
object
required
LLM configuration:
  • endpoints: Array of LLM endpoints (see LLMEndpoint)
  • model: Model name to use
  • maxTokens: Maximum tokens per request
  • temperature: Sampling temperature (0-1)
  • timeoutMs: Optional request timeout in milliseconds
​
git
object
required
Git repository configuration:
  • repoUrl: Repository URL
  • mainBranch: Main branch name (e.g., “main” or “master”)
  • branchPrefix: Prefix for task branches
​
sandbox
object
required
Sandbox environment configuration:
  • imageTag: Docker image tag to use
  • cpuCores: Number of CPU cores to allocate
  • memoryMb: Memory limit in megabytes
  • idleTimeout: Idle timeout in milliseconds

​
LLMEndpoint

LLM endpoint configuration with load balancing weight. 
interface LLMEndpoint {
  name: string;
  endpoint: string;
  apiKey?: string;
  weight: number;
}

​
Fields

​
name
string
required
Human-readable endpoint name
​
endpoint
string
required
API endpoint URL
​
apiKey
string
Optional API key for authentication
​
weight
number
required
Load balancing weight (higher = more requests)

​
LogEntry

Structured log entry for NDJSON logging. 
interface LogEntry {
  timestamp: number;
  level: "debug" | "info" | "warn" | "error";
  agentId: string;
  agentRole: AgentRole;
  taskId?: string;
  message: string;
  data?: Record<string, unknown>;
}

​
Fields

​
timestamp
number
required
Unix timestamp in milliseconds
​
level
string
required
Log level: debug, info, warn, or error
​
agentId
string
required
Unique identifier for the logging agent
​
agentRole
AgentRole
required
Role of the logging agent
​
taskId
string
Optional task ID if log is task-specific
​
message
string
required
Log message
​
data
Record<string, unknown>
Optional structured data payload

​
MetricsSnapshot

System-wide metrics snapshot. 
interface MetricsSnapshot {
  timestamp: number;
  activeWorkers: number;
  pendingTasks: number;
  runningTasks: number;
  completedTasks: number;
  failedTasks: number;
  suspiciousTaskCount: number;
  commitsPerHour: number;
  mergeSuccessRate: number;
  totalTokensUsed: number;
  totalCostUsd: number;
  activeToolCalls: number;
  estimatedInFlightTokens: number;
  
  // Finalization phase metrics (populated only after finalization runs)
  finalizationAttempts?: number;
  finalizationBuildPassed?: boolean;
  finalizationTestsPassed?: boolean;
  finalizationAllMerged?: boolean;
  finalizationUnmergedCount?: number;
  finalizationDurationMs?: number;
}

​
Fields

​
timestamp
number
required
Unix timestamp in milliseconds when snapshot was taken
​
activeWorkers
number
required
Number of currently active worker sandboxes
​
pendingTasks
number
required
Number of tasks waiting to be assigned
​
runningTasks
number
required
Number of tasks currently being executed
​
completedTasks
number
required
Number of successfully completed tasks
​
failedTasks
number
required
Number of failed tasks
​
suspiciousTaskCount
number
required
Number of tasks flagged as suspicious
​
commitsPerHour
number
required
Commit velocity metric
​
mergeSuccessRate
number
required
Percentage of successful merges (0-1)
​
totalTokensUsed
number
required
Total LLM tokens consumed across all tasks
​
totalCostUsd
number
required
Estimated total cost in USD
​
activeToolCalls
number
required
Number of tool calls currently in progress
​
estimatedInFlightTokens
number
required
Estimated tokens in active requests
​
finalizationAttempts
number
Number of finalization attempts (populated after finalization)
​
finalizationBuildPassed
boolean
Whether the finalization build check passed
​
finalizationTestsPassed
boolean
Whether the finalization tests passed
​
finalizationAllMerged
boolean
Whether all tasks were successfully merged
​
finalizationUnmergedCount
number
Number of tasks that failed to merge
​
finalizationDurationMs
number
Duration of finalization phase in milliseconds

Build docs developers (and LLMs) love

Get started for freeTalk to us