Skip to main content

​
What Is ThreadState?

ThreadState is the runtime interface passed to tools, hooks, and thread endpoints. It provides:
  • thread identity
  • message operations
  • model/prompt/agent loaders
  • tool and effect scheduling helpers
  • filesystem access
  • subagent hierarchy and lifecycle surfaces

​
Core Surfaces

​
Identity

  • threadId
  • agentId
  • userId
  • createdAt

​
Messaging

  • getMessages()
  • getMessage()
  • injectMessage()
  • updateMessage()
  • queueMessage()

​
Subagent Hierarchy

  • getChildThread(referenceId)
  • getParentThread()
  • children (resumable child registry)

​
Lifecycle

  • terminate()
  • terminated

​
Resource Loading

  • loadModel()
  • loadPrompt()
  • loadAgent()

​
Utilities

  • queueTool() / invokeTool()
  • scheduleEffect() / getScheduledEffects() / removeScheduledEffect()
  • file APIs (readFile, writeFile, readdirFile, findFiles, etc.)

​
ThreadState in Tools

import { defineTool } from '@standardagents/builder';
import { z } from 'zod';

export default defineTool({
  description: 'Inspect subagent status',
  args: z.object({ referenceId: z.string() }),
  execute: async (state, args) => {
    const child = await state.getChildThread(args.referenceId);

    if (!child) {
      return { status: 'error', error: 'Child thread not found.' };
    }

    return {
      status: 'success',
      result: `Child terminated: ${child.terminated ? 'yes' : 'no'}`,
    };
  },
});

​
Queue Semantics

queueMessage() is durable and ordered:
  • active thread: injected before next model step
  • idle thread: queue triggers execution
  • queue survives eviction

​
Cross-Thread Attachment Safety

When parent/child communication includes attachments, runtimes copy files across thread filesystems and rewrite attachment paths to destination-local values.

​
Notes

  • execution may be null when thread is at rest.
  • _notPackableRuntimeContext is runtime-specific and not portable.