> ## Documentation Index
> Fetch the complete documentation index at: https://docs.standardagentbuilder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ThreadState

> Unified runtime API for tools, hooks, and endpoints

## 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.

```typescript theme={null}
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

```typescript theme={null}
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.

## Related

* [Thread](/core-concepts/thread)
* [Subagents](/core-concepts/subagents)