PiDurableKit is a Swift-native framework designed to build durable AI agents for Apple platforms (iOS, macOS, visionOS). It acts as a bridge between the Swift ecosystem and the pi-durable JavaScript environment, enabling robust, state-preserving agent workflows that can recover from application crashes or OS-induced process termination.

Core Methodology and Architecture

The framework operates by bridging the pi-durable library, pi-ai, and chord into JavaScriptCore. All execution occurs on a dedicated, serial dispatch queue per runtime, ensuring thread safety while managing the bridge between Swift and JavaScript.

1. Durable Task and State Management
The framework ensures that conversations, model turns, and tool calls are persisted to storage (SQLite or JSONL) before being presented to the user. Persistence is achieved through atomic transactions:

• harness.commit { tx in ... }: Executes read and write operations atomically. If any portion of the transaction throws an error, the entire operation rolls back.
• Durable Tasks: Defined as $TaskType<Input, Checkpoint, Output>$, these tasks use checkpoints to track execution state. After a crash, the system inspects the last committed checkpoint and resumes execution, maintaining the integrity of long-running workflows.

2. Tool Execution and Sandboxing
Tool definitions allow agents to perform side effects or execute subagents.

• Replayability: Tools can be marked as replay: .safe, allowing them to rerun across crashes if the process is interrupted.
• Subagents: A tool call can trigger a child conversation. By linking the child to the parent's taskId, the framework ensures that aborting the parent also terminates the child process, effectively managing hierarchical agent nesting.
• Sandboxing: For file system operations, the framework defines a directory environment. Agents are restricted to a scoped path, preventing unauthorized file access.

3. Integration and Extensibility

• JavaScript Hooks: Developers can inject custom logic into the agent loop using Extension, Hook, and Wrap. These allow for modifying prompt sections, pre-processing user input, or post-processing assistant responses without altering the core agent logic.
• OAuth and Credentials: The framework manages API keys and OAuth tokens using the system Keychain. It implements a local loopback server (via Network.framework) to handle OAuth redirects, enabling agents to use subscriptions like ChatGPT or Claude Pro directly within the app.
• Typed Transcripts: Developers can define EntryType and Document schemas, allowing structured data to be stored and retrieved directly within the agent’s history and state.

Technical Implementation

The bridge between JavaScript and Swift is managed through a JSON-based protocol (JS/src/bridge.ts). While JavaScript handles the orchestration logic, Swift manages the low-level platform interfaces:

• Networking: URLSession is mapped to the fetch API.
• Storage: SQLiteDatabase provides the persistence layer, where the schema and transactions are managed by pi-durable.
• Concurrency: Swift concurrency is the primary interface for the user, while the underlying agent "waits" are managed by Chord contexts, allowing for seamless integration with SwiftUI AsyncSequence streams for real-time UI updates.

The framework supports dynamic updates to agent behavior through configure calls, which can reset instructions, change models, or modify extensions at runtime. By maintaining an audit trail of every commit, PiDurableKit enables complex, multi-turn AI interactions that remain stable regardless of device power state or app lifecycle events.