Threads

const thread = await ade.threads.open("support", {
  provider: "claude",
  model: "claude-sonnet-4-5",
});

const again = await ade.threads.open("support");

​

When the runtime lost the session

​

List, rename, archive, delete

const rows = await ade.threads.list();
await ade.threads.archive("support");
await ade.threads.unarchive("support");
await ade.threads.delete("support");

const row = await ade.threads.get("support");   // ThreadSummary | null

ade.on("threadLifecycle", ({ key, change }) => chatList.apply(key, change));

​

Title and model

thread.title;   // string | null
thread.model;   // { modelId, provider, model, displayName } | null

• A title that you set with update({ title }) marks the chat as named. The runtime’s automatic title never replaces it, at any time. That includes Claude’s summary title and Codex’s thread name.
• Without a host title, the runtime may name the chat after its first message.
• update({ title: null }) clears the host title (runtime 1.2.82). The chat then shows the provider’s placeholder title, for example "Claude Chat", so thread.title reads that string, not null. The automatic title may name the chat again after its next message. Before 1.2.82, null set the placeholder and still counted as a host title.

​

update()

await thread.update({ title: "Outage review" });
await thread.update({ reasoningEffort: "high", fastMode: false });

​

Send, steer, interrupt

await thread.send("What changed?");
await thread.steer("Focus on the outage"); // mid-turn follow-up
await thread.steer("", { attachments: [{ path: "/Users/me/MyApp/work/log.txt" }] });
await thread.interrupt();

​

Retry and edit

await thread.retry();                                   // run the last user message again
await thread.editLast("Use the March numbers instead");  // replace it, then run it
await thread.editLast("", { attachments: [{ path: "/Users/me/MyApp/work/new.csv" }] });

1. session_meta_updated with historyInvalidated: true and a new historyGeneration. Drop your copy of the events at or after retractedFromSequence (from the result), or read history() again. useAdeThread in chat-ui 0.4 re-reads by itself.
2. The new turn: user_message, status started, and the rest of the turn.

• Claude and Codex only. Another provider, or a runtime older than 1.2.82, throws unsupported.
• Not during a turn. A running turn, or one that waits on an approval, throws turn_in_flight, and nothing changes. Wait for the turn to end, or call interrupt() first.
• Files are not restored. The rollback covers the conversation, not the disk: changes the old turn made stay. The result does not say whether the old turn wrote files, because the runtime cannot tell which of your tools write. If you allow writes, find them yourself — the removed events are the ones at or after retractedFromSequence in your own history copy, so inspect their tool calls and warn the user if any of them was a write.
• A thread with no user message yet throws rpc_error.

​

Events

const off = thread.on("event", (envelope) => {
  // envelope.event.type — assistant text, tool_call, tool_result, …
});
thread.on("status", (envelope) => { /* running | idle */ });
thread.on("usage", (envelope) => { /* token usage */ });

​

History

let page = await thread.historyPage({ limit: 200 });   // newest page
while (page.hasMore) {
  page = await thread.historyPage({ beforeSequence: page.nextBeforeSequence!, limit: 200 });
}

​

Instructions

const thread = await ade.threads.open("assistant", {
  provider: "claude",
  model: "claude-sonnet-4-5",
  instructions: { mode: "replace", text: "You are Ada, MyApp's assistant." },
});

• { mode: "append", text } keeps ADE’s own personal-chat prompt and adds yours after it. Use this when you want ADE’s safety framing.
• { mode: "replace", text } uses your text alone. Use this when the chat is branded as your assistant and must not mention ADE.
• A bare string is shorthand for { mode: "append", text }.

if (thread.instructionsCapability?.level !== "applied") {
  console.warn(thread.instructionsCapability?.detail);
}

​

Working directory

const thread = await ade.threads.open("assistant", {
  provider: "claude",
  model: "claude-sonnet-4-5",
  cwd: "/Users/me/Library/Application Support/MyApp/work",
});

• A relative path. It would resolve against the runtime’s working directory, which you cannot see and did not choose.
• A path starting with ~. It is not expanded.
• A filesystem root, including a Windows drive root and a bare UNC share root.
• The user’s home directory itself.
• Anything inside the SDK’s own home, which holds the runtime’s state.

​

Configuration layers

settingSources: "project"   // "none" (default) | "project" | "user" | "all"

​

Switch models

await thread.interrupt();
const next = await thread.setModel("claude-opus-4");
// next.modelId / next.provider / next.model / next.displayName — what the runtime resolved
// next.capabilities — the four capability reports on the new provider

​

Export and dispose

const jsonl = await ade.exportThread("support"); // one JSON envelope per line
await ade.dispose();

​

Attachments

await thread.send("Look at this screenshot", {
  attachments: [
    { path: "/Users/me/MyApp/work/screen.png" },                  // sent as an image
    { path: "notes/spec.md", name: "spec.md" },                  // relative to the chat's cwd
    { path: "/Users/me/MyApp/work/mix.wav", hydrate: false },    // path only, bytes never read
  ],
});

type AgentChatFileRef = {
  path: string;              // absolute, or relative to the chat's working directory
  name?: string;
  mimeType?: string;
  bytes?: number;
  type?: "file" | "image";   // inferred when absent
  hydrate?: boolean;         // default true
};

​

type

​

hydrate: false

​

Where a path may point

• A relative path resolves in the chat’s working directory: the thread’s cwd, or the runtime’s scratch workspace when you did not set one.
• An absolute path must be inside one of these roots:
  • the chat’s working directory;
  • <home>/personal-chats/state, the runtime’s state directory;
  • a directory in the thread’s attachmentRoots (SDK 0.4, runtime 1.2.82).
• Any other path throws, and the send fails. The error names the path.

​

How the runtime compares paths

• It resolves each root with realpath, so a symlinked root (a Music folder that is a link) works. A root that no longer exists is skipped.
• It resolves the attachment path one part at a time. Each part that exists is replaced by its real path, and .. goes to the parent of that real path. A part that does not exist yet is kept as written, and the read fails later if the file is still missing.
• The resolved path must be inside the resolved root. A symlink inside a root that points outside it is refused.
• On macOS, letter case does not matter for parts that exist.

​

attachmentRoots: attach files where they are

const thread = await ade.threads.open("main", {
  provider: "claude",
  model: "claude-sonnet-4-5",
  cwd: workDir,
  attachmentRoots: [app.getPath("downloads"), musicLibraryDir],
});

// Later, a new folder: replace the roots. This works on a thread the client
// already holds open, and on a resume. A refused root fails the open and
// changes nothing.
await ade.threads.open("main", { refresh: { attachmentRoots: [app.getPath("downloads"), newLibraryDir] } });

• Each root follows the cwd rules: absolute, no ~, not a filesystem root, not the home directory itself, not inside the SDK home. At most 32. A bad entry throws invalid_option and names it.
• The roots are read roots for attachments only. They do not change where the agent runs, and they are not a sandbox.
• One refused entry fails the whole open. Because the runtime is sent the whole list, and a host usually sends the same roots on every open, one bad entry would lock every chat. Test a candidate with checkAttachmentRoot, or prepare the list with filterAttachmentRoots (SDK 0.5), which drops the bad entry and reports why instead of throwing:
  const { roots, dropped } = filterAttachmentRoots([downloads, musicDir, "/"], home);
  for (const entry of dropped) log.warn(`attachment root ignored: ${entry.root} — ${entry.reason}`);
  await ade.threads.open("main", { ...createOptions, attachmentRoots: roots });
  
• A list identical to the one already on the thread is not sent again, the same way an identical refresh.mcpServers map is skipped. A host that repeats its four roots on every open costs no update call and does not restart the provider.
• Like cwd, attachmentRoots on a resume is ignored (with a log line). Use refresh.attachmentRoots to replace them; [] clears them.
• With hydrate: false, a file in a root is attached without being read, so a File Provider placeholder is not downloaded.

​

Do you need to stage files yourself?

• Codex: the runtime copies each attachment that it may read to its own temporary directory at send time. With hydrate: false it copies nothing and puts the path in the prompt.
• Claude: the runtime reads the bytes into the message.

​

Size limits

​

Next