finnvoor/PiDurableKit

PiDurableKit

Durable AI agents for iPhone, iPad, Mac, and Vision Pro, powered by @earendil-works/pi-durable running in JavaScriptCore.

Conversations, model turns, tool calls, and your own state are committed to storage before anything is shown. If iOS kills your app mid-turn, reopening the storage picks the work up where it stopped.

import PiDurableKit

let models = Models(credentials: .keychain)
try await models.setAPIKey(anthropicKey, for: .anthropic)
let harness = try await Harness.open(.sqlite(at: .documentsDirectory.appending(path: "agent.sqlite")), models: models)
let root = try await harness.root(agent: AgentChange(model: .anthropic("claude-sonnet-4-5")))

let submission = try await root.submit("What is the capital of France?")
let settled = try await submission.wait()
if case .done(_, let answer?) = settled.status {
    let entry = try await root.commit { tx in try await tx.entry(answer) }
    print(entry?.assistantMessage?.text ?? "")
}

• Swift tools, system prompt sections, hooks, and wraps, written as plain closures
• Subagents, durable tasks with child tasks, and atomic transactions
• Every pi-ai provider (Anthropic, OpenAI, Google, OpenRouter, Groq, xAI, Mistral, …) plus any OpenAI- or Anthropic-compatible server
• SQLite or JSONL persistence with crash recovery, or in-memory storage
• pi-durable's read/write/edit tools in a sandboxed directory
• Streaming: AsyncSequences of conversation views (for SwiftUI) and coding-agent style events
• Steering, follow-ups, abort, reset, compaction, forks, typed documents and entries, usage and cost
• OAuth sign-in to Claude Pro/Max, ChatGPT, GitHub Copilot, and OpenRouter, with tokens in the Keychain and automatic refresh
• A scripted faux provider for tests and SwiftUI previews

Requires iOS 17, macOS 14, tvOS 17, or visionOS 1.

Installation

.package(url: "https://github.com/<you>/PiDurableKit.git", from: "1.0.0")

and add PiDurableKit to your target's dependencies.

Concepts

The Swift API mirrors pi-durable's, with Swift concurrency in place of Chord contexts (cancel the Swift task to cancel a wait; cancelling a wait never cancels the work).

Tools

struct WeatherArguments: Decodable, Sendable { var city: String }

let weather = Tool(
    "get_weather",
    description: "Look up the current weather in a city",
    parameters: .object(["city": .string("City name")])
) { (args: WeatherArguments, call) in
    call.output("Looking up \(args.city)…\n")   // streamed to the UI while the tool runs
    return "Sunny and 22°C in \(args.city)"      // a String, a ToolResult, or a JSONValue
}

let assistant = Extension("assistant") {
    PromptSection("preamble", tag: false, text: "You are a concise assistant on an iPhone.")
    PromptSection("today") { _ in Date.now.formatted(date: .complete, time: .omitted) }
    weather
    Hook.beforeTool { call, _ in
        await askUserForApproval(call) ? .allow : .block("The user declined")
    }
}

let harness = try await Harness.open(.sqlite(at: url), models: models, extensions: [assistant])

Each call is its own durable task. Throwing gives the model an error result. A call interrupted by a crash reruns after a restart only when the tool is declared replay: .safe; otherwise the model gets an interrupted error. Return ToolResult.text(…).terminating() to end the run without another model request.

Install, replace, or remove extensions at runtime with harness.install(_:) and harness.uninstall(_:). Choose per conversation with configure:

try await conversation.configure(AgentChange(
    model: .openAI("gpt-4.1"),
    thinkingLevel: .high,
    extensions: .remove(assistant),
    instructions: "Only answer in French."
))
try await conversation.configure(AgentChange(reset: [.extensions, .instructions]))

JavaScript extensions

pi-durable extensions written in JavaScript install unchanged, the way a Node app installs its own:

let source = #"""
const { defineExtension, defineTool } = require("@earendil-works/pi-durable");
const { Type } = require("@earendil-works/pi-ai");
module.exports = defineExtension({
  name: "dice",
  tools: [defineTool({
    name: "roll", description: "Roll a die", parameters: Type.Object({ sides: Type.Number() }),
    execute: async (args) => ({ content: [{ type: "text", text: String(1 + Math.floor(Math.random() * args.sides)) }] }),
  })],
});
"""#
try await harness.install(Extension("dice", javaScript: source))

The module is CommonJS and can require @earendil-works/pi-durable (and /tools, /env), @earendil-works/pi-ai, and @earendil-works/chord/context. As in pi-durable, extension code is not sandboxed, so install only code you trust; it cannot reach PiDurableKit's own bridge to storage. Like any extension, install it again after a restart before resuming (Harness.open(…, resume: false), install, resume()) so its pending tool calls continue.

PiDurable.documentation is pi-durable's own README.md and TypeScript declarations for the bundled version, as its npm package ships them (the bundle keeps only minified code). Give it to an agent that writes extensions, the way pi points its agent at pi's docs.

Examples/PiChat uses both to let the agent write extensions into its workspace and load them into the running session: it copies the documentation to /docs/pi-durable, points a prompt section at it, and installs modules with a load_extension tool. That flow is app policy, not part of the package.

Subagents and transactions

A tool call can commit transactions and drive other conversations. This is pi-durable's foreground subagent: the child conversation is owned by the call, so aborting the call aborts the child, and a crash-rerun finds the same child.

let subagent = Tool("subagent", description: "Delegate a task", parameters: .object(["task": .string]), replay: .safe) {
    (args: SubagentArguments, call) -> String in
    let child = try await call.commit { tx in
        if let existing = try await tx.conversations(ownedBy: call.taskId, limit: 1).items.first { return existing.id }
        let created = try await tx.createConversation(ownedBy: call.taskId)
        try await tx.configure(created.id, AgentChange(model: .anthropic("claude-haiku-4-5"), extensions: .remove(assistant)))
        return created.id
    }
    let handle = try await call.conversation(child)!
    let settled = try await handle.submit(args.task, requestId: "subagent:\(call.taskId)").wait()
    guard case .done(_, let answer?) = settled.status else { return "\(settled.status)" }
    return try await call.commit { tx in try await tx.entry(answer)?.assistantMessage?.text ?? "" }
}

ToolCallContext also offers memo (values that survive a rerun), agent(), document(_:), createTask, waitForTask, and details/diagnostic. Results can addingTools(…), and tools can repair arguments (preparingArguments) or bound their output (limitingOutput).

harness.commit { tx in … } and conversation.commit { tx in … } run any set of reads and writes atomically: create conversations and forks, append entries, create tasks, configure agents, and read or write documents. Throwing rolls everything back.

Durable tasks

struct Step: TaskCheckpoint { var phase: String }                     // a checkpoint names its next phase
struct Checkout: TaskCheckpoint { var phase = "pay"; var payments: [TaskID] = [] }

let payment = TaskType<String, Step, String>(
    "app.payment", version: 1, initial: { _ in Step(phase: "charge") },
    abort: { run in try await run.commit { _, _ in .aborted(nil) } }
) {
    Phase("charge") { run in
        let key = try await run.memo("idempotencyKey", default: UUID().uuidString)   // stable across reruns
        let receipt = try await charge(run.input, key: key)
        try await run.commit { _, _ in .completed(receipt) }
    }
}

let checkout = TaskType<[String], Checkout, [String]>(
    "app.checkout", version: 1, initial: { _ in Checkout() },
    abort: { run in try await run.commit { _, _ in .aborted(nil) } }
) {
    Phase("pay") { run in
        try await run.commit { tx, current in
            var payments: [TaskID] = []
            for card in run.input { payments.append(try await tx.createTask(payment, input: card, ownedBy: current.id)) }
            return .waiting(Checkout(phase: "done", payments: payments), on: payments, policy: .failFast)
        }
    }
    Phase("done") { run in
        let receipts = try await run.outcomes(of: run.checkpoint.payments, as: String.self).compactMap(\.result)
        try await run.commit { _, _ in .completed(receipts) }
    }
}

let shop = Extension("shop") { payment; checkout }
let id = try await conversation.commit { tx in try await tx.createTask(checkout, input: ["visa", "amex"]) }
let outcome = try await harness.waitForTask(id, as: [String].self)   // .completed, .failed, .aborted, …

Every phase transition is a checkpoint; after a crash the task continues from the last one. Pass version: and migrate: to upgrade live tasks, and abort: to undo a task's effects wh

... (truncated at the site's per-page length limit; see the source link below for the full text.)