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
  • sandboxed JavaScript/TypeScript execution through Dynamic Workers
  • subagent hierarchy and lifecycle surfaces
  • thread invocation arguments and per-execution scratch context

​
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

​
Arguments and Context

  • arguments: read-only invocation or creation arguments for the thread
  • context: mutable scratch data shared only during the current execution
For resumable subagents, subagent_create.arguments is persisted with the child thread and restored as state.arguments for both child sides on every run. Top-level argument keys are also available to prompt variable interpolation, including included prompts. Use state.context for derived values that should be shared among tools, hooks, and runtime code during one execution. Do not use it for durable thread state or subagent creation arguments; use state.arguments, state.getValue() / state.setValue(), or files depending on the data.

​
Resource Loading

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

​
Environment

  • env(propertyName)
  • envType(propertyName)
  • setEnv(propertyName, value, options?)
env() resolves values from thread, account, instance, agent, and prompt env sources. envType() returns secret by default; text values may be shown in tool output and errors, while secret values should be redacted. setEnv() writes a thread-scoped env value and propagates it to active descendant threads. Pass { type: 'text' } or { type: 'secret' } to choose the display/redaction type; omitting type preserves the existing type or defaults new keys to secret.

​
Utilities

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

​
Code Execution

runCode() executes JavaScript or TypeScript in a Cloudflare Dynamic Worker sandbox loaded by stable content ID when possible. The sandbox does not receive thread state, filesystem, network access, timers, or host globals automatically. Bridge exact capabilities through options.imports and options.globals, use options.modules for local relative ES modules, and use options.execute to choose which export to run with which arguments. By default, AgentBuilder executes the default export with no args. 
const run = state.runCode(
  `
    const text = await readText('/notes.txt');
    report({ length: text.length });
    export function summarize(limit: number) {
      return text.slice(0, limit);
    }
  `,
  {
    execute: { fn: 'summarize', args: [120] },
    globals: {
      readText: async (path: string) => {
        const data = await state.readFile(path);
        return data ? new TextDecoder().decode(data) : '';
      },
    },
    report: (value) => console.log(value),
  },
);

const result = await run;
The returned handle is promise-like and supports run.terminate(reason). AgentBuilder uses the AGENT_BUILDER_CODE_LOADER Worker Loader binding; missing configuration returns a link_error result naming that binding. Memory is enforced by Cloudflare’s Dynamic Worker isolate limit. AgentBuilder accepts memoryLimitBytes for spec compatibility but cannot lower Cloudflare’s platform ceiling or report memoryUsedBytes; recognizable platform memory failures are returned with status: 'memory'.

​
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
  • message APIs expose sendMessage() and queueMessage() queued entries as pending messages with metadata.queued: true

​
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.
  • arguments is the place for thread invocation and subagent creation arguments.
  • context is ephemeral execution scratch state, not durable storage.
  • _notPackableRuntimeContext is runtime-specific and not portable.