Durable Task State

Overview

Durable Task State tracks checkpoints, file artifacts, and arbitrary key-value data across an agent's execution. It is designed for long-running tasks where you need crash recovery and audit trails.

• Slot: 110 (Slot.WORKING_MEMORY + 10)
• Scope: execution
• Default budget: { min: 100, max: 800 }
• Store timeout: 30000 ms

Usage

import { durableTaskState } from '@noetic/core';

const layer = durableTaskState({
  baseDir: './task-output',
  gitCommit: true,
});

Configuration

interface DurableTaskStateConfig {
  baseDir?: string;
  gitCommit?: boolean;
  schema?: ZodType;
  serializer?: DurableTaskStateSerializer;
}

State Type

interface DurableTaskState {
  checkpoints: Array<{
    timestamp: number;
    depth: number;
  }>;
  files: string[];
  data: Record<string, unknown>;
}

How It Works

init

Loads saved DurableTaskState from scoped storage. Falls back to empty checkpoints, files, and data.

recall

Serializes the full state as JSON inside a <task_state> XML block and injects it as a developer message. This gives the LLM awareness of all checkpoints and artifacts.

store

Appends a new checkpoint with the current timestamp and execution depth on every store cycle.

onSpawn

Deep-clones the parent state to the child. Unlike other layers, Durable Task State always provides child state to spawned agents.

onReturn

Merges child artifacts back into the parent:

• Checkpoints are concatenated
• File lists are deduplicated via Set
• Data objects are shallow-merged (child keys overwrite parent keys)

onComplete

Records the execution outcome ('success', 'failure', or 'aborted') in data.__outcome and appends a final checkpoint.

StorageAdapter

Durable Task State relies on the StorageAdapter provided in your AgentConfig. The adapter must implement:

interface StorageAdapter {
  get<T>(key: string): Promise<T | null>;
  set<T>(key: string, value: T): Promise<void>;
  delete(key: string): Promise<void>;
  list(prefix: string): Promise<string[]>;
}

You can use the built-in InMemoryRuntime for development or implement a persistent adapter backed by a database or file system.

Example: Task Recovery

import { durableTaskState } from '@noetic/core';

const layer = durableTaskState();

// After a crash, the agent resumes with full checkpoint history
// The runtime calls init(), which loads the saved state
// The LLM sees all previous checkpoints and can continue from where it left off

Next Steps

• Working Memory -- lightweight scratchpad alternative
• Custom Layers -- build your own persistence layer