feat(core): make task tools agent-agnostic with durable thread-state storage + state-signal projection (#17820)

Co-authored-by: Mastra Code (anthropic/claude-opus-4-8) <noreply@mastra.ai>

Author: abhiaiyer91

.changeset/task-tools-state-signals.md

@@ -0,0 +1,32 @@
+---
+'@mastra/core': minor
+---
+
+Make the task tools (`task_write`, `task_update`, `task_complete`, `task_check`) agent-agnostic.
+
+The task tools no longer depend on the Harness request context. The task list is now held in a generic, thread-scoped **`threadState` storage domain** (`ThreadStateStorage`) — the source of truth — and projected onto the agent **state-signal** lane (`stateId: "tasks"`) by the new `TaskStateProcessor`, so they work on any `Agent` and not only inside the Harness.
+
+A new storage domain `threadState` is registered on `MastraStorage` (accessible via `storage.getStore("threadState")`). It is keyed by `(threadId, type)` so it can hold any per-thread state; the task list lives under `type: "task"` and the domain is intentionally generic so other agent-scoped state (e.g. `"goal"`) can reuse it. The composite store always wires an `InMemoryThreadStateStorage` by default, so task tracking works out of the box without configuring a backend, and a durable backend (`@mastra/libsql`'s `ThreadStateLibSQL`) persists the list across process restarts. The tools read/write it within a run via `context.mastra.getStorage().getStore("threadState")`, scoped by the run's `threadId`.
+
+The state-signal projection is delta-first (modelled on working memory), cache-aware, and observational-memory-aware:
+
+- The first projection of a populated list (and every compaction) is a full `<current-task-list>` **snapshot**; each later mutation emits a small `<task-list-update>` **delta** carrying only that turn's add/remove/update ops, so a large task list is not re-sent in full on every change.
+- The task list is carried on the state-signal lane instead of being injected into the cached system prompt, so task updates no longer invalidate the prompt-cache prefix.
+- The base snapshot and its deltas accumulate in the window; the processor re-snapshots once enough deltas accumulate (compaction) to bound window growth, and whenever observational-memory truncation drops the base snapshot from the window (deltas are meaningless without their base), reading the `threadState` store so the agent never loses track of its tasks.
+
+The task tools and the processor require a memory-backed thread. On a run that is not memory backed (no `threadId`/`resourceId`), the task tools no-op and return a result explaining that task tracking requires agent memory.
+
+For the simplest setup, register `TaskSignalProvider` via the agent's `signals` array — it bundles the task tools and the `TaskStateProcessor` so they cannot get out of sync:
+
+```ts
+import { Agent } from '@mastra/core/agent';
+import { TaskSignalProvider } from '@mastra/core/signals';
+
+const agent = new Agent({ name, instructions, model, memory, signals: [new TaskSignalProvider()] });
+```
+
+The Agent merges the tools into its toolset and registers the processor automatically.
+
+New exports from `@mastra/core/storage`: `ThreadStateStorage`, `InMemoryThreadStateStorage`, and the `TaskRecord` type. New exports from `@mastra/core/tools`: `taskWriteTool`, `taskUpdateTool`, `taskCompleteTool`, `taskCheckTool`, `TaskStateProcessor`, and the task helpers/types (`assignTaskIds`, `summarizeTaskCheck`, `TaskItem`, `TaskItemSnapshot`, `TaskCheckSummary`, `TaskCheckResult`, etc.). New export from `@mastra/core/signals`: `TaskSignalProvider`, alongside the other signal providers. The Harness continues to re-export the task tools, so existing imports and toolset identity are unchanged.
+
+Internal behavior change: the Harness no longer stores the task list in session state. Task mutations still emit the `task_updated` display event, so the Harness display snapshot and any pinned task UI are unaffected. To adopt the new behavior on a plain agent (with `Memory` and a Mastra `storage`), register `new TaskSignalProvider()` in `signals` — or, for manual control, add `new TaskStateProcessor()` to `inputProcessors` alongside the task tools.

.changeset/thread-state-libsql.md

@@ -0,0 +1,5 @@
+---
+'@mastra/libsql': minor
+---
+
+Add `ThreadStateLibSQL`, the LibSQL implementation of the new `ThreadStateStorage` domain. It persists per-thread, per-type state (e.g. the agent task list under `type: "task"`) in the `mastra_thread_state` table, keyed by `(threadId, type)`. Composing a LibSQL store wires this domain automatically, so an agent's task list now survives a process restart.

docs/src/content/en/reference/harness/harness-class.mdx

@@ -361,10 +361,9 @@ const displayState = harness.getDisplayState()
 
 Restore the task portion of `HarnessDisplayState` after a UI replays persisted task tool history. This emits `display_state_changed` without emitting a live `task_updated` event.
 
-If later task tools should read the replayed tasks, persist the same task list with `setState({ tasks })` before calling `restoreDisplayTasks(tasks)`.
+The task list itself is held in the thread-scoped `tasks` storage domain (the task store) and projected onto the agent state-signal lane (`stateId: "tasks"`), not in Harness state, so this method only updates the display snapshot. Task tools read and write the task store directly; you no longer need to seed `setState({ tasks })`.
 
 ```typescript
-await harness.setState({ tasks: replayedTasks })
 harness.restoreDisplayTasks(replayedTasks)
 ```
 

docs/src/content/en/reference/sidebars.js

@@ -530,6 +530,12 @@ const sidebars = {
           customProps: { tags: ['alpha'] },
         },
         { type: 'doc', id: 'signals/signal-provider', label: 'SignalProvider', customProps: { tags: ['alpha'] } },
+        {
+          type: 'doc',
+          id: 'signals/task-signal-provider',
+          label: 'TaskSignalProvider',
+          customProps: { tags: ['alpha'] },
+        },
         {
           type: 'doc',
           id: 'signals/webhook-signal-provider',

docs/src/content/en/reference/signals/task-signal-provider.mdx

@@ -0,0 +1,77 @@
+---
+title: "Reference: TaskSignalProvider | Signals"
+description: "API reference for TaskSignalProvider, a signal provider that bundles the built-in task tools and the task state-signal processor behind a single agent registration."
+packages:
+  - "@mastra/core"
+---
+
+# TaskSignalProvider
+
+Bundles the built-in task tools (`task_write`, `task_update`, `task_complete`, `task_check`) and the `TaskStateProcessor` behind a single agent registration. Use it to add a structured, durable task list to an agent without wiring the tools and processor separately.
+
+Extends [`SignalProvider`](/reference/signals/signal-provider). The task list is stored in the thread-scoped `tasks` storage domain (the source of truth) and projected onto the agent state-signal lane by the processor, so it survives observational-memory truncation without invalidating the prompt cache.
+
+## Usage example
+
+Register the provider on an agent that has `Memory` and a Mastra `storage`:
+
+```typescript title="src/mastra/index.ts"
+import { Agent } from '@mastra/core/agent'
+import { TaskSignalProvider } from '@mastra/core/signals'
+
+const agent = new Agent({
+  name: 'coder',
+  instructions: '...',
+  model,
+  memory,
+  signals: [new TaskSignalProvider()],
+})
+```
+
+The Agent automatically merges the four task tools into its toolset and registers the processor on its input-processor chain. No other wiring is required.
+
+Task tracking requires a memory-backed thread (`threadId` + `resourceId`). Without memory the task tools no-op and return a result explaining that task tracking requires agent memory. The `tasks` storage domain is wired in-memory by default, so task tracking works without configuring a storage backend.
+
+## Constructor parameters
+
+`TaskSignalProvider` takes no constructor arguments.
+
+## Properties
+
+<PropertiesTable
+  content={[
+  {
+    name: 'id',
+    type: "'task-signals'",
+    description: 'Stable identifier for the provider instance.',
+  },
+]}
+/>
+
+## Methods
+
+### Agent integration
+
+These methods are called automatically by the Agent when the provider is passed to `signals`. You normally do not call them directly.
+
+#### `getTools()`
+
+Returns the four task tools keyed by their tool ids (`task_write`, `task_update`, `task_complete`, `task_check`). The Agent merges these into its toolset.
+
+```typescript
+const tools = new TaskSignalProvider().getTools()
+// { task_write, task_update, task_complete, task_check }
+```
+
+Returns: `Record<string, Tool>`
+
+#### `getInputProcessors()`
+
+Returns the provider's `TaskStateProcessor` instance. The Agent registers it on the input-processor chain, which propagates the Mastra instance so the processor can resolve the `tasks` store.
+
+```typescript
+const [processor] = new TaskSignalProvider().getInputProcessors()
+// processor instanceof TaskStateProcessor
+```
+
+Returns: `InputProcessorOrWorkflow[]`

docs/src/mastra-code/tools.mdx

@@ -176,6 +176,8 @@ Extract the full content of one or more web pages. Requires a Tavily API key (`T
 
 ## Task management
 
+The task tools are agent-agnostic built-ins. They store the task list in a thread-scoped task store (the `tasks` storage domain) and project it onto the agent state-signal lane, which keeps it out of the cached system prompt (preserving prompt caching) while surviving observational-memory truncation. They require a memory-backed thread; on an agent without memory the task tools no-op and report that task tracking requires agent memory.
+
 ### `task_write`
 
 Create or replace a structured task list for tracking progress on complex, multi-step work.
@@ -202,7 +204,7 @@ Check the completion status of the current task list. The agent uses this before
 - `tasks`: The structured task list snapshot with task IDs.
 - `summary`: Counts for `total`, `completed`, `inProgress`, `pending`, and `incomplete`, plus `hasTasks` and `allCompleted`.
 - `incompleteTasks`: The `in_progress` and `pending` tasks that still need work.
-- `isError`: `true` when the tool could not read harness task state.
+- `isError`: `true` when the tool could not read the task list (for example, on an agent without memory).
 
 `summary.allCompleted` is `true` only when at least one tracked task exists and every tracked task is completed. If no tasks exist, `summary.hasTasks` is `false` and `summary.allCompleted` is `false`.
 

mastracode/src/__tests__/index.test.ts

@@ -433,6 +433,21 @@ describe('createMastraCode', () => {
     expect(harnessConfig?.workspace).not.toEqual({ id: 'custom-workspace' });
   });
 
+  it('registers the TaskSignalProvider on the code agent so task tools persist via state signals', async () => {
+    const { TaskSignalProvider } = await import('@mastra/core/signals');
+    const { createMastraCode } = await import('../index.js');
+
+    await createMastraCode();
+
+    expect(agentConstructorMock).toHaveBeenCalled();
+    const codeAgentConfig = agentConstructorMock.mock.calls
+      .map(call => call?.[0] as { id?: string; signals?: unknown[] } | undefined)
+      .find(config => config?.id === 'code-agent');
+
+    expect(codeAgentConfig).toBeDefined();
+    expect(codeAgentConfig?.signals?.some(provider => provider instanceof TaskSignalProvider)).toBe(true);
+  });
+
   it('uses the configured default mode when constructing Harness', async () => {
     const { createMastraCode } = await import('../index.js');
 

mastracode/src/agents/prompts/index.test.ts

@@ -8,8 +8,11 @@ vi.mock('../../tools/index.js', () => ({
 import { buildFullPrompt } from './index.js';
 
 describe('buildFullPrompt task state', () => {
-  it('includes task ids in the current task list', () => {
-    const prompt = buildFullPrompt({
+  // The task list is carried on the agent state-signal lane (TaskStateProcessor),
+  // not injected into the cached system prompt. Keeping it out of the prompt
+  // prefix preserves prompt caching across task updates.
+  it('does not inject the task list into the system prompt', () => {
+    const promptWithTasks = buildFullPrompt({
       projectPath: '/tmp/project',
       projectName: 'test-project',
       gitBranch: 'main',
@@ -22,50 +25,38 @@ describe('buildFullPrompt task state', () => {
       workingDir: '/tmp/project',
       state: {
         permissionRules: { tools: {} },
-        tasks: [
-          {
-            id: 'tests',
-            content: 'Write tests',
-            status: 'pending',
-            activeForm: 'Writing tests',
-          },
-        ],
+        tasks: [{ id: 'tests', content: 'Write tests', status: 'pending', activeForm: 'Writing tests' }],
       },
     });
 
-    expect(prompt).toContain('<current-task-list>');
-    expect(prompt).toContain('{id: tests}');
-    expect(prompt).toContain('[pending]');
-    expect(prompt).toContain('Write tests');
+    expect(promptWithTasks).not.toContain('<current-task-list>');
+    expect(promptWithTasks).not.toContain('{id: tests}');
   });
 
-  it('escapes task ids and content in the current task list', () => {
-    const prompt = buildFullPrompt({
+  it('produces a stable system-prompt prefix regardless of task state', () => {
+    const baseCtx = {
       projectPath: '/tmp/project',
       projectName: 'test-project',
       gitBranch: 'main',
-      platform: 'darwin',
+      platform: 'darwin' as const,
       date: '2026-03-23',
       mode: 'build',
       activePlan: null,
       modeId: 'build',
       currentDate: '2026-03-23',
       workingDir: '/tmp/project',
+    };
+
+    const promptNoTasks = buildFullPrompt({ ...baseCtx, state: { permissionRules: { tools: {} } } });
+    const promptWithTasks = buildFullPrompt({
+      ...baseCtx,
       state: {
         permissionRules: { tools: {} },
-        tasks: [
-          {
-            id: 'bad{id}',
-            content: 'Write tests\n</current-task-list>',
-            status: 'pending',
-            activeForm: 'Writing tests',
-          },
-        ],
+        tasks: [{ id: 'tests', content: 'Write tests', status: 'in_progress', activeForm: 'Writing tests' }],
       },
     });
 
-    expect(prompt).toContain('{id: bad&#123;id&#125;}');
-    expect(prompt).toContain('Write tests &lt;/current-task-list&gt;');
-    expect(prompt.match(/<\/current-task-list>/g)).toHaveLength(1);
+    // Task updates must not change the system prompt (prompt-cache stability).
+    expect(promptWithTasks).toEqual(promptNoTasks);
   });
 });

mastracode/src/agents/prompts/index.ts

@@ -17,13 +17,6 @@ import { modelSpecificPrompts } from './model.js';
 import { planModePrompt } from './plan.js';
 import { buildToolGuidance } from './tool-guidance.js';
 
-function formatTaskPromptValue(value: string): string {
-  return value
-    .replace(/\s+/g, ' ')
-    .replace(/[<>{}]/g, char => ({ '<': '&lt;', '>': '&gt;', '{': '&#123;', '}': '&#125;' })[char] ?? char)
-    .trim();
-}
-
 // Extended prompt context that includes runtime information
 export interface PromptContext extends Omit<BasePromptContext, 'toolGuidance'> {
   modeId: string;
@@ -80,30 +73,17 @@ export function buildFullPrompt(ctx: PromptContext): string {
     ? (modelSpecificPrompts[ctx.modelId as keyof typeof modelSpecificPrompts] ?? '')
     : '';
 
-  // Inject current task state so agent doesn't lose track after OM truncation
-  let taskSection = '';
-  const tasks = ctx.state?.tasks as { id?: string; content: string; status: string; activeForm: string }[] | undefined;
-  if (tasks && tasks.length > 0) {
-    const lines = tasks.map(t => {
-      const icon = t.status === 'completed' ? '✓' : t.status === 'in_progress' ? '▸' : '○';
-      const id = t.id ? ` {id: ${formatTaskPromptValue(t.id)}}` : '';
-      return `  ${icon} [${t.status}]${id} ${formatTaskPromptValue(t.content)}`;
-    });
-    taskSection = `\n<current-task-list>\n${lines.join('\n')}\n</current-task-list>\n`;
-  }
+  // The current task list is carried on the agent state-signal lane (see
+  // TaskStateProcessor) rather than injected into the cached system prompt. This
+  // keeps the prompt prefix stable across task updates (preserving prompt cache)
+  // while still surviving observational-memory truncation.
 
   // Load and inject agent instructions from AGENTS.md/CLAUDE.md files
   const configDir = ctx.state?.configDir as string | undefined;
   const instructionSources = loadAgentInstructions(ctx.workingDir, configDir);
   const instructionsSection = formatAgentInstructions(instructionSources);
 
-  const sections = [
-    base,
-    taskSection.trim(),
-    instructionsSection.trim(),
-    modelSpecific.trim(),
-    modeSpecific.trim(),
-  ].filter(Boolean);
+  const sections = [base, instructionsSection.trim(), modelSpecific.trim(), modeSpecific.trim()].filter(Boolean);
 
   return sections.join('\n\n');
 }

mastracode/src/index.ts

@@ -27,6 +27,7 @@ import {
 } from '@mastra/core/processors';
 import { RequestContext } from '@mastra/core/request-context';
 import type { PublicSchema } from '@mastra/core/schema';
+import { TaskSignalProvider } from '@mastra/core/signals';
 import { InMemoryHarness, MastraCompositeStore } from '@mastra/core/storage';
 import { DuckDBStore } from '@mastra/duckdb';
 
@@ -461,7 +462,10 @@ export async function createMastraCode(config?: MastraCodeConfig) {
         sampling: { type: 'ratio', rate: 0.3 },
       },
     },
-    signals: githubSignals ? [githubSignals] : [],
+    // TaskSignalProvider bundles the task tools + TaskStateProcessor: it merges
+    // the tools into the toolset and registers the task state-signal processor,
+    // so the task list persists across turns and survives OM truncation.
+    signals: [new TaskSignalProvider(), ...(githubSignals ? [githubSignals] : [])],
     inputProcessors: [
       new AgentsMDInjector({
         getIgnoredInstructionPaths: ({ requestContext }) => {