Agentic AIWithout theToken Tax

// swift-tools-version: 6.2
import PackageDescription

let package = Package(
    name: "act",
    platforms: [.macOS(.v26)],
    targets: [
        .target(name: "ActionEngine"),
        .executableTarget(name: "act", dependencies: ["ActionEngine"]),
        .testTarget(name: "ActionEngineTests", dependencies: ["ActionEngine"]),
    ]
)

import Foundation

/// Everything the engine can ever do. There is no `case other`.
public enum Action: Codable, Equatable, Sendable {
    case addTask(title: String, due: Date?)
    case scheduleEvent(title: String, start: Date, minutes: Int)
    case saveNote(title: String, body: String)
    case extractTasks(note: String)
}

public struct Step: Codable, Equatable, Sendable {
    public var id: String
    public var action: Action
    public var after: [String]

    public init(id: String, action: Action, after: [String] = []) {
        self.id = id
        self.action = action
        self.after = after
    }
}

public struct Plan: Codable, Equatable, Sendable {
    public var steps: [Step]

    public init(steps: [Step]) { self.steps = steps }
}

import CryptoKit
import Foundation

/// One value, one byte sequence: sorted keys, fixed date format.
public func canonicalJSON<T: Encodable>(_ value: T) throws -> Data {
    let encoder = JSONEncoder()
    encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
    encoder.dateEncodingStrategy = .iso8601
    return try encoder.encode(value)
}

public func fingerprint<T: Encodable>(_ value: T) throws -> String {
    let digest = SHA256.hash(data: try canonicalJSON(value))
    return digest.prefix(6).map { String(format: "%02x", $0) }.joined()
}

public func decodeCanonical<T: Decodable>(_ type: T.Type, from data: Data) throws -> T {
    let decoder = JSONDecoder()
    decoder.dateDecodingStrategy = .iso8601
    return try decoder.decode(type, from: data)
}

import Foundation

/// Turns "friday at 3pm" into a date. Code owns the calendar, never the model.
public struct When: Sendable {
    public let now: Date
    public let calendar: Calendar

    public init(now: Date, timeZone: TimeZone = .gmt) {
        var calendar = Calendar(identifier: .gregorian)
        calendar.timeZone = timeZone
        self.now = now
        self.calendar = calendar
    }

    static let days = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"]

    /// The phrase must be a date, a time, or both, and nothing else.
    public func resolve(_ phrase: String) -> Date? {
        let pattern = /^(?:(?:on |next )?(?<day>today|tomorrow|sunday|monday|tuesday|wednesday|thursday|friday|saturday))?\s*(?:(?:at )?(?<hour>\d{1,2})(?::(?<minute>\d{2}))?\s*(?<ampm>am|pm)?)?$/
        let text = phrase.lowercased().trimmingCharacters(in: .whitespaces)
        guard !text.isEmpty, let match = text.wholeMatch(of: pattern) else { return nil }

        var hour = 9, minute = 0
        if let raw = match.hour {
            hour = Int(raw)!
            minute = match.minute.map { Int($0)! } ?? 0
            if let ampm = match.ampm {
                guard (1...12).contains(hour) else { return nil }
                hour = hour % 12 + (ampm == "pm" ? 12 : 0)
            } else if match.minute == nil {
                return nil // "at 3" could be either. Do not guess.
            }
        }
        guard (0...23).contains(hour), (0...59).contains(minute) else { return nil }

        let today = calendar.startOfDay(for: now)
        var offset = 0
        switch match.day.map(String.init) {
        case nil, "today": offset = 0
        case "tomorrow": offset = 1
        case let name?:
            let target = Self.days.firstIndex(of: name)! + 1
            let current = calendar.component(.weekday, from: today)
            offset = (target - current + 7) % 7
            if offset == 0 { offset = 7 }
        }
        let day = calendar.date(byAdding: .day, value: offset, to: today)!
        return calendar.date(bySettingHour: hour, minute: minute, second: 0, of: day)
    }
}

import Foundation

/// Tier 0. Known request shapes become plans with no model at all.
public struct Rules: Sendable {
    public let when: When

    public init(when: When) { self.when = when }

    public func plan(_ request: String) -> Plan? {
        let parts = request
            .split(separator: /\s+(?:and\s+)?then\s+/)
            .map { $0.trimmingCharacters(in: .whitespaces) }
        var steps: [Step] = []
        for (index, part) in parts.enumerated() {
            guard let action = action(part) else { return nil }
            let after = index == 0 ? [] : ["s\(index)"]
            steps.append(Step(id: "s\(index + 1)", action: action, after: after))
        }
        return steps.isEmpty ? nil : Plan(steps: steps)
    }

    func action(_ text: String) -> Action? {
        if let m = text.wholeMatch(of: /(?i)(?:remind me to|add a task to|add task:?|todo:?)\s+(?<rest>.+)/) {
            let (title, phrase) = splitWhen(String(m.rest))
            if let phrase {
                guard let due = when.resolve(phrase) else { return nil }
                return .addTask(title: title, due: due)
            }
            return .addTask(title: title, due: nil)
        }
        if let m = text.wholeMatch(of: /(?i)(?:schedule|book)\s+(?!me\b)(?<rest>.+?)(?:\s+for\s+(?<n>\d+)\s*(?<unit>minutes?|mins?|hours?))?/) {
            let (title, phrase) = splitWhen(String(m.rest))
            guard let phrase, let start = when.resolve(phrase) else { return nil }
            var minutes = 30
            if let n = m.n.flatMap({ Int($0) }) {
                minutes = m.unit?.lowercased().hasPrefix("hour") == true ? n * 60 : n
            }
            return .scheduleEvent(title: title, start: start, minutes: minutes)
        }
        if let m = text.wholeMatch(of: /(?i)(?:save a note|save note|note)(?:\s+(?:called|titled))?\s+(?<title>[^:]+):\s*(?<body>.+)/) {
            return .saveNote(title: String(m.title), body: String(m.body))
        }
        if let m = text.wholeMatch(of: /(?i)extract tasks from\s+(?<a>.+)|turn\s+(?<b>.+)\s+into tasks/) {
            return .extractTasks(note: String(m.a ?? m.b ?? ""))
        }
        return nil
    }

    /// Splits "send the invoice friday at 3pm" into a title and a date phrase.
    func splitWhen(_ text: String) -> (String, String?) {
        let tail = /(?i)\s+(?<phrase>(?:on |next )?(?:today|tomorrow|sunday|monday|tuesday|wednesday|thursday|friday|saturday)(?:\s+(?:at )?\d{1,2}(?::\d{2})?\s*(?:am|pm)?)?|at \d{1,2}(?::\d{2})?\s*(?:am|pm)?)$/
        guard let m = text.firstMatch(of: tail) else { return (text, nil) }
        return (String(text[..<m.range.lowerBound]), String(m.phrase))
    }
}

import Foundation

/// What a model may say. Dates stay as words here; code resolves them later.
public struct Proposal: Codable, Equatable, Sendable {
    public struct Item: Codable, Equatable, Sendable {
        public var action: String
        public var title: String
        public var when: String
        public var minutes: Int
        public var body: String
    }
    public var steps: [Item]

    public static let schema = """
    {"type":"object","required":["steps"],"additionalProperties":false,"properties":{
      "steps":{"type":"array","minItems":1,"maxItems":4,"items":{
        "type":"object","additionalProperties":false,
        "required":["action","title","when","minutes","body"],
        "properties":{
          "action":{"enum":["add_task","schedule_event","save_note","extract_tasks","none"]},
          "title":{"type":"string","maxLength":120},
          "when":{"type":"string","maxLength":40},
          "minutes":{"type":"integer","minimum":0,"maximum":480},
          "body":{"type":"string","maxLength":800}}}}}}
    """

    public static let instructions = """
    You turn one request into JSON steps. Pick "action" from this list only:
    add_task: something to do or remember. title is the task. when is the due date in the user's words, or "".
    schedule_event: a meeting or appointment. title is the event. when is the start in the user's words. minutes is the length, or 0.
    save_note: keep some text. title is the note name, the words before the colon. body is all the words after the colon. when stays "".
    extract_tasks: pull tasks out of a saved note. title is the note name.
    none: anything else, including anything you cannot do with these four. Leave the other fields empty.
    Copy dates exactly as the user wrote them. Never work out a date.

    Examples:
    "I must return the library books by monday" add_task title "return the library books" when "monday"
    "get coffee with Ana in my diary for thursday at 9am" schedule_event title "coffee with Ana" when "thursday at 9am"
    "store this as Recipes: two eggs, one lemon" save_note title "Recipes" body "two eggs, one lemon"
    "find the to-dos in my Budget note" extract_tasks title "Budget"
    "order me a pizza" none
    """
}

public enum ProposalError: Error, Equatable, CustomStringConvertible {
    case declined
    case unreadableDate(String)
    case missingDate(String)

    public var description: String {
        switch self {
        case .declined: "The request is outside the four things this engine can do."
        case .unreadableDate(let text): "\"\(text)\" is not a date this engine can read."
        case .missingDate(let title): "\"\(title)\" needs a start time."
        }
    }
}

extension Proposal {
    /// The bridge from words to a typed plan. Everything past here is plain code.
    public func plan(when clock: When) throws(ProposalError) -> Plan {
        var result: [Step] = []
        for (index, item) in steps.enumerated() {
            let after = index == 0 ? [] : ["s\(index)"]
            let step = Step(id: "s\(index + 1)", action: try action(item, clock), after: after)
            result.append(step)
        }
        return Plan(steps: result)
    }

    private func action(_ item: Item, _ clock: When) throws(ProposalError) -> Action {
        switch item.action {
        case "add_task":
            return .addTask(title: item.title, due: try date(item.when, clock))
        case "schedule_event":
            guard let start = try date(item.when, clock) else { throw .missingDate(item.title) }
            return .scheduleEvent(title: item.title, start: start, minutes: item.minutes == 0 ? 30 : item.minutes)
        case "save_note":
            return .saveNote(title: item.title, body: item.body)
        case "extract_tasks":
            return .extractTasks(note: item.title)
        default:
            throw .declined
        }
    }

    private func date(_ words: String, _ clock: When) throws(ProposalError) -> Date? {
        if words.isEmpty { return nil }
        guard let date = clock.resolve(words) else { throw .unreadableDate(words) }
        return date
    }
}

import Foundation

public struct ModelReply: Sendable {
    public var raw: String
    public var tokens: Int
}

public protocol Proposer: Sendable {
    var name: String { get }
    func propose(_ request: String) async throws -> ModelReply
}

/// Runs any GGUF model on this machine. The grammar comes from the JSON schema,
/// so tokens that would break it are never sampled.
public struct LlamaProposer: Proposer {
    public let modelPath: String
    public var name: String { URL(filePath: modelPath).deletingPathExtension().lastPathComponent }

    public init(modelPath: String) { self.modelPath = modelPath }

    public func propose(_ request: String) async throws -> ModelReply {
        let log = FileManager.default.temporaryDirectory.appending(path: UUID().uuidString)
        FileManager.default.createFile(atPath: log.path, contents: nil)
        defer { try? FileManager.default.removeItem(at: log) }

        let process = Process()
        let output = Pipe()
        process.executableURL = URL(filePath: "/usr/bin/env")
        process.arguments = [
            "llama-completion", "-m", modelPath,
            "-sys", Proposal.instructions, "-p", request,
            "--json-schema", Proposal.schema,
            "--temp", "0", "--seed", "42", "-n", "256", "-c", "2048",
            "-st", "--no-display-prompt", "--simple-io", "--perf",
        ]
        process.standardOutput = output
        process.standardError = try FileHandle(forWritingTo: log)
        process.standardInput = FileHandle.nullDevice
        try process.run()
        let data = output.fileHandleForReading.readDataToEndOfFile()
        process.waitUntilExit()

        let text = String(decoding: data, as: UTF8.self)
        guard let start = text.firstIndex(of: "{"), let end = text.lastIndex(of: "}") else {
            throw CocoaError(.coderReadCorrupt)
        }
        let perf = (try? String(contentsOf: log, encoding: .utf8)) ?? ""
        return ModelReply(raw: String(text[start...end]), tokens: Self.tokens(in: perf))
    }

    /// llama.cpp ends its timings with "total time = ... / 412 tokens".
    static func tokens(in log: String) -> Int {
        log.matches(of: /total time.*\/\s+(\d+) tokens/).last.flatMap { Int($0.1) } ?? 0
    }
}

#if canImport(FoundationModels)
import Foundation
import FoundationModels

/// The same contract on Apple's built-in model. Nothing to download.
@available(macOS 26, iOS 26, *)
public struct AppleProposer: Proposer {
    @Generable
    struct Draft {
        @Generable
        struct Item {
            @Guide(.anyOf(["add_task", "schedule_event", "save_note", "extract_tasks", "none"]))
            var action: String
            var title: String
            @Guide(description: "The date in the user's words, or empty")
            var when: String
            @Guide(.range(0...480))
            var minutes: Int
            var body: String
        }
        @Guide(.count(1...4))
        var steps: [Item]
    }

    public let name = "apple-on-device"

    public init() {}

    public static var isAvailable: Bool {
        if case .available = SystemLanguageModel.default.availability { return true }
        return false
    }

    public func propose(_ request: String) async throws -> ModelReply {
        let session = LanguageModelSession(instructions: Proposal.instructions)
        let options = GenerationOptions(samplingMode: .greedy)
        let draft = try await session.respond(to: request, generating: Draft.self, options: options).content
        let proposal = Proposal(steps: draft.steps.map {
            .init(action: $0.action, title: $0.title, when: $0.when, minutes: $0.minutes, body: $0.body)
        })
        let raw = String(decoding: try canonicalJSON(proposal), as: UTF8.self)
        return ModelReply(raw: raw, tokens: 0)
    }
}
#endif

import Foundation

public enum PlanError: Error, Equatable, CustomStringConvertible {
    case empty
    case tooManySteps(Int)
    case duplicateStep(String)
    case unknownDependency(step: String, needs: String)
    case cycle
    case badField(step: String, reason: String)

    public var description: String {
        switch self {
        case .empty: "The plan has no steps."
        case .tooManySteps(let n): "The plan has \(n) steps. The limit is \(Validator.maxSteps)."
        case .duplicateStep(let id): "Two steps share the id \(id)."
        case .unknownDependency(let step, let needs): "Step \(step) waits for \(needs), which does not exist."
        case .cycle: "The steps wait for each other in a loop."
        case .badField(let step, let reason): "Step \(step): \(reason)"
        }
    }
}

public struct Validator: Sendable {
    public static let maxSteps = 8
    public let now: Date

    public init(now: Date) { self.now = now }

    /// Returns the steps in the order they must run, or the reason they cannot.
    public func check(_ plan: Plan) throws(PlanError) -> [Step] {
        guard !plan.steps.isEmpty else { throw .empty }
        guard plan.steps.count <= Self.maxSteps else { throw .tooManySteps(plan.steps.count) }

        var ids = Set<String>()
        for step in plan.steps {
            guard ids.insert(step.id).inserted else { throw .duplicateStep(step.id) }
        }
        for step in plan.steps {
            try checkFields(step)
            for needed in step.after where !ids.contains(needed) {
                throw .unknownDependency(step: step.id, needs: needed)
            }
        }
        return try ordered(plan.steps)
    }

    func checkFields(_ step: Step) throws(PlanError) {
        func bad(_ reason: String) -> PlanError { .badField(step: step.id, reason: reason) }
        let horizon = now.addingTimeInterval(2 * 365 * 86_400)

        switch step.action {
        case .addTask(let title, let due):
            try checkTitle(title, step)
            if let due, due < now || due > horizon { throw bad("the due date is not in the next two years.") }
        case .scheduleEvent(let title, let start, let minutes):
            try checkTitle(title, step)
            if start < now || start > horizon { throw bad("the start is not in the next two years.") }
            if !(5...480).contains(minutes) { throw bad("an event lasts 5 to 480 minutes.") }
        case .saveNote(let title, let body):
            try checkTitle(title, step)
            if body.isEmpty || body.count > 4_000 { throw bad("a note body has 1 to 4,000 characters.") }
        case .extractTasks(let note):
            try checkTitle(note, step)
        }
    }

    func checkTitle(_ title: String, _ step: Step) throws(PlanError) {
        if title.trimmingCharacters(in: .whitespaces).isEmpty || title.count > 120 {
            throw .badField(step: step.id, reason: "a title has 1 to 120 characters.")
        }
        if title.contains(where: \.isNewline) {
            throw .badField(step: step.id, reason: "a title is a single line.")
        }
    }

    /// Kahn's algorithm. Ties keep plan order, so the result never varies.
    func ordered(_ steps: [Step]) throws(PlanError) -> [Step] {
        var done = Set<String>()
        var result: [Step] = []
        while result.count < steps.count {
            guard let next = steps.first(where: {
                !done.contains($0.id) && $0.after.allSatisfy(done.contains)
            }) else { throw .cycle }
            done.insert(next.id)
            result.append(next)
        }
        return result
    }
}

import Foundation

public struct Routed: Codable, Equatable, Sendable {
    public var request: String
    public var now: Date
    public var route: String
    public var plan: Plan
    public var hash: String
    public var raw: String?
    public var localTokens: Int
    public var cloudTokens: Int
    public var milliseconds: Double
}

public enum EngineError: Error, CustomStringConvertible {
    case noRoute
    case rejected(String)

    public var description: String {
        switch self {
        case .noRoute: "No rule matched, and no local model is set."
        case .rejected(let reason): reason
        }
    }
}

public struct Engine: Sendable {
    public let now: Date
    public let timeZone: TimeZone
    public let proposer: (any Proposer)?

    public init(now: Date, timeZone: TimeZone = .gmt, proposer: (any Proposer)? = nil) {
        self.now = now
        self.timeZone = timeZone
        self.proposer = proposer
    }

    /// Rules first. The model only hears what the rules could not read.
    public func plan(_ request: String) async throws -> Routed {
        let clock = When(now: now, timeZone: timeZone)
        let started = ContinuousClock.now

        if let plan = Rules(when: clock).plan(request) {
            return try seal(request, "rules", plan, nil, 0, started)
        }
        guard let proposer else { throw EngineError.noRoute }

        let reply = try await proposer.propose(request)
        let plan = try Self.decode(reply.raw, clock)
        return try seal(request, proposer.name, plan, reply.raw, reply.tokens, started)
    }

    /// Rebuilds a plan from a record without running any model.
    public static func replay(_ record: Routed, timeZone: TimeZone = .gmt) throws -> Plan {
        let clock = When(now: record.now, timeZone: timeZone)
        if let raw = record.raw { return try decode(raw, clock) }
        guard let plan = Rules(when: clock).plan(record.request) else { throw EngineError.noRoute }
        return plan
    }

    static func decode(_ raw: String, _ clock: When) throws -> Plan {
        let proposal = try JSONDecoder().decode(Proposal.self, from: Data(raw.utf8))
        do {
            return try proposal.plan(when: clock)
        } catch {
            throw EngineError.rejected(error.description)
        }
    }

    private func seal(
        _ request: String, _ route: String, _ plan: Plan, _ raw: String?, _ tokens: Int,
        _ started: ContinuousClock.Instant
    ) throws -> Routed {
        do {
            _ = try Validator(now: now).check(plan)
        } catch {
            throw EngineError.rejected(error.description)
        }
        let elapsed = started.duration(to: .now).components
        let ms = Double(elapsed.seconds) * 1_000 + Double(elapsed.attoseconds) / 1e15
        return Routed(
            request: request, now: now, route: route, plan: plan, hash: try fingerprint(plan),
            raw: raw, localTokens: tokens, cloudTokens: 0, milliseconds: ms
        )
    }
}

import Foundation

/// Every file the engine touches lives under one root.
public struct Workspace: Sendable {
    public let root: URL

    public init(root: URL) throws {
        self.root = root
        for folder in ["notes", "events", "plans"] {
            try FileManager.default.createDirectory(
                at: root.appending(path: folder), withIntermediateDirectories: true)
        }
    }

    public var tasks: URL { root.appending(path: "tasks.md") }
    public var journal: URL { root.appending(path: "journal.jsonl") }
    public var audit: URL { root.appending(path: "audit.jsonl") }
    public func note(_ title: String) -> URL { root.appending(path: "notes/\(Self.slug(title)).md") }
    public func plan(_ hash: String) -> URL { root.appending(path: "plans/\(hash).json") }

    /// Letters, digits, and hyphens only, so a title can never become a path.
    public static func slug(_ text: String) -> String {
        let words = text.lowercased().split { !($0.isASCII && ($0.isLetter || $0.isNumber)) }
        return words.isEmpty ? "untitled" : words.joined(separator: "-")
    }

    public func append(_ line: Data, to file: URL) throws {
        if !FileManager.default.fileExists(atPath: file.path) {
            FileManager.default.createFile(atPath: file.path, contents: nil)
        }
        let handle = try FileHandle(forWritingTo: file)
        defer { try? handle.close() }
        try handle.seekToEnd()
        try handle.write(contentsOf: line + Data("\n".utf8))
    }

    public func lines(of file: URL) -> [String] {
        guard let text = try? String(contentsOf: file, encoding: .utf8) else { return [] }
        return text.split(separator: "\n").map(String.init)
    }
}

import Foundation

public enum HandlerError: Error, CustomStringConvertible {
    case noteExists(String)
    case noteMissing(String)

    public var description: String {
        switch self {
        case .noteExists(let name): "A different note called \(name) already exists."
        case .noteMissing(let name): "There is no note called \(name)."
        }
    }
}

/// Each handler is safe to run twice with the same key.
struct Handlers {
    let workspace: Workspace

    func perform(_ action: Action, key: String) throws -> String {
        switch action {
        case .addTask(let title, let due):
            return try addTask(title, due: due, key: key)
        case .scheduleEvent(let title, let start, let minutes):
            return try writeEvent(title, start: start, minutes: minutes, key: key)
        case .saveNote(let title, let body):
            return try saveNote(title, body: body)
        case .extractTasks(let note):
            return try extractTasks(from: note, key: key)
        }
    }

    func addTask(_ title: String, due: Date?, key: String) throws -> String {
        let marker = "<!-- act:\(key) -->"
        if workspace.lines(of: workspace.tasks).contains(where: { $0.hasSuffix(marker) }) {
            return "tasks.md (already there)"
        }
        let date = due.map { " (due \($0.formatted(.iso8601)))" } ?? ""
        try workspace.append(Data("- [ ] \(title)\(date) \(marker)".utf8), to: workspace.tasks)
        return "tasks.md"
    }

    func writeEvent(_ title: String, start: Date, minutes: Int, key: String) throws -> String {
        let stamp = Date.ISO8601FormatStyle(dateSeparator: .omitted, timeSeparator: .omitted, timeZone: .gmt)
        let end = start.addingTimeInterval(Double(minutes) * 60)
        let summary = title
            .replacing("\\", with: "\\\\").replacing(";", with: "\\;").replacing(",", with: "\\,")
        let lines = [
            "BEGIN:VCALENDAR", "VERSION:2.0", "PRODID:-//act//EN", "BEGIN:VEVENT",
            "UID:\(key)@act", "DTSTAMP:\(stamp.format(start))",
            "DTSTART:\(stamp.format(start))", "DTEND:\(stamp.format(end))",
            "SUMMARY:\(summary)", "END:VEVENT", "END:VCALENDAR", "",
        ]
        let name = "events/\(Workspace.slug(title))-\(key).ics"
        try Data(lines.joined(separator: "\r\n").utf8).write(to: workspace.root.appending(path: name), options: .atomic)
        return name
    }

    func saveNote(_ title: String, body: String) throws -> String {
        let file = workspace.note(title)
        let content = "# \(title)\n\n\(body)\n"
        if let existing = try? String(contentsOf: file, encoding: .utf8) {
            guard existing == content else { throw HandlerError.noteExists(title) }
            return "notes/\(file.lastPathComponent) (already there)"
        }
        try Data(content.utf8).write(to: file, options: .atomic)
        return "notes/\(file.lastPathComponent)"
    }

    func extractTasks(from note: String, key: String) throws -> String {
        guard let text = try? String(contentsOf: workspace.note(note), encoding: .utf8) else {
            throw HandlerError.noteMissing(note)
        }
        let found = text.split(whereSeparator: \.isNewline).compactMap { line in
            line.wholeMatch(of: /\s*(?:TODO:|- \[ \])\s*(.+)/).map { String($0.1) }
        }
        for (index, title) in found.enumerated() {
            _ = try addTask(title, due: nil, key: "\(key)-\(index)")
        }
        return "tasks.md (\(found.count) from \(note))"
    }
}

import Foundation

public struct Entry: Codable, Equatable, Sendable {
    public var key: String
    public var step: String
    public var status: String
    public var detail: String
}

public struct Executor: Sendable {
    public let workspace: Workspace
    public let now: Date
    /// Tests use this to crash after a side effect, before it is recorded.
    public var crashAfter: String?

    public init(workspace: Workspace, now: Date, crashAfter: String? = nil) {
        self.workspace = workspace
        self.now = now
        self.crashAfter = crashAfter
    }

    public struct Crash: Error {}

    /// Runs a plan in dependency order. Finished steps are never run again.
    @discardableResult
    public func run(_ plan: Plan) throws -> [Entry] {
        let order = try Validator(now: now).check(plan)
        let handlers = Handlers(workspace: workspace)
        let finished = Set(journal().filter { $0.status == "done" }.map(\.key))
        var results: [Entry] = []

        for step in order {
            let key = try fingerprint(step)
            if finished.contains(key) {
                results.append(Entry(key: key, step: step.id, status: "skipped", detail: "already done"))
                continue
            }
            try record(Entry(key: key, step: step.id, status: "started", detail: ""))
            do {
                let detail = try handlers.perform(step.action, key: key)
                if crashAfter == step.id { throw Crash() }
                let entry = Entry(key: key, step: step.id, status: "done", detail: detail)
                try record(entry)
                results.append(entry)
            } catch is Crash {
                throw Crash()
            } catch {
                let reason = String(describing: error)
                try record(Entry(key: key, step: step.id, status: "failed", detail: reason))
                throw EngineError.rejected(reason)
            }
        }
        return results
    }

    func record(_ entry: Entry) throws {
        try workspace.append(try canonicalJSON(entry), to: workspace.journal)
    }

    public func journal() -> [Entry] {
        workspace.lines(of: workspace.journal).compactMap {
            try? decodeCanonical(Entry.self, from: Data($0.utf8))
        }
    }
}

import ActionEngine
import Foundation

let usage = """
usage: act plan "<request>"   Build a plan and print its hash
       act run <hash>         Run a plan you have read
       act replay <hash>      Rebuild a plan from the audit log, without a model
       act eval <cases.jsonl> Score the engine against a test set
"""

var arguments = Array(CommandLine.arguments.dropFirst())
let environment = ProcessInfo.processInfo.environment

@MainActor func option(_ name: String) -> String? {
    guard let index = arguments.firstIndex(of: name), index + 1 < arguments.count else { return nil }
    defer { arguments.removeSubrange(index...(index + 1)) }
    return arguments[index + 1]
}

func fail(_ message: Any) -> Never {
    print("stopped: \(message)")
    exit(1)
}

let now = option("--now").flatMap { try? Date($0, strategy: .iso8601) } ?? Date()
let timeZone = environment["ACT_TZ"].flatMap(TimeZone.init(identifier:)) ?? .current
let workspace = try Workspace(root: URL(filePath: environment["ACT_HOME"] ?? ".act"))

func proposer() -> (any Proposer)? {
    if let path = environment["ACT_MODEL"] { return LlamaProposer(modelPath: path) }
    #if canImport(FoundationModels)
    if AppleProposer.isAvailable { return AppleProposer() }
    #endif
    return nil
}

func describe(_ action: Action) -> String {
    let data = (try? canonicalJSON(action)) ?? Data()
    return String(decoding: data, as: UTF8.self)
}

@MainActor func load(_ hash: String) throws -> Routed? {
    try workspace.lines(of: workspace.audit).reversed()
        .lazy.compactMap { try? decodeCanonical(Routed.self, from: Data($0.utf8)) }
        .first { $0.hash == hash }
}

guard let command = arguments.first, arguments.count == 2 else {
    print(usage)
    exit(2)
}
let input = arguments[1]

do {
    switch command {
    case "plan":
        let engine = Engine(now: now, timeZone: timeZone, proposer: proposer())
        let routed = try await engine.plan(input)
        try canonicalJSON(routed.plan).write(to: workspace.plan(routed.hash))
        try workspace.append(try canonicalJSON(routed), to: workspace.audit)
        print("route   \(routed.route)")
        print("tokens  \(routed.localTokens) local, \(routed.cloudTokens) cloud")
        print("time    \(String(format: "%.2f", routed.milliseconds)) ms")
        for step in routed.plan.steps { print("\(step.id)      \(describe(step.action))") }
        print("hash    \(routed.hash)")

    case "run":
        let data = try Data(contentsOf: workspace.plan(input))
        let plan = try decodeCanonical(Plan.self, from: data)
        guard try fingerprint(plan) == input else { fail("this plan changed after you read it.") }
        for entry in try Executor(workspace: workspace, now: now).run(plan) {
            print("\(entry.step)  \(entry.status)  \(entry.detail)")
        }

    case "replay":
        guard let record = try load(input) else { fail("no record of \(input).") }
        let plan = try Engine.replay(record, timeZone: timeZone)
        print(try fingerprint(plan) == input ? "identical  \(input)" : "different  \(input)")

    case "eval":
        let report = try await Evaluation.run(
            file: URL(filePath: input), engine: Engine(now: now, timeZone: timeZone, proposer: proposer()))
        print(report)

    default:
        print(usage)
        exit(2)
    }
} catch {
    fail(error)
}

import Foundation

public struct Case: Codable, Sendable {
    public var request: String
    public var expect: [String]
    public var date: Date?
}

public enum Evaluation {
    public static func kind(_ action: Action) -> String {
        switch action {
        case .addTask: "addTask"
        case .scheduleEvent: "scheduleEvent"
        case .saveNote: "saveNote"
        case .extractTasks: "extractTasks"
        }
    }

    static func date(_ action: Action) -> Date? {
        switch action {
        case .addTask(_, let due): due
        case .scheduleEvent(_, let start, _): start
        default: nil
        }
    }

    public static func run(file: URL, engine: Engine) async throws -> String {
        let text = try String(contentsOf: file, encoding: .utf8)
        let cases = try text.split(separator: "\n").map {
            try decodeCanonical(Case.self, from: Data($0.utf8))
        }
        var routes: [String: (total: Int, right: Int, ms: Double, tokens: Int)] = [:]
        var wrong: [String] = []

        for item in cases {
            var route = "refused"
            var got = ["refused"]
            var right = false
            var ms = 0.0, tokens = 0
            do {
                let routed = try await engine.plan(item.request)
                route = routed.route
                ms = routed.milliseconds
                tokens = routed.localTokens
                got = routed.plan.steps.map { kind($0.action) }
                right = got == item.expect
                    && (item.date == nil || routed.plan.steps.first.flatMap { date($0.action) } == item.date)
            } catch {
                right = item.expect == ["refused"]
            }
            var row = routes[route] ?? (0, 0, 0, 0)
            row.total += 1
            row.right += right ? 1 : 0
            row.ms += ms
            row.tokens += tokens
            routes[route] = row
            if !right { wrong.append("  \(item.request)\n    wanted \(item.expect), got \(got)") }
        }

        var lines = ["route                     cases  right  avg ms   local tokens"]
        for (route, row) in routes.sorted(by: { $0.key < $1.key }) {
            let columns = [
                route.padding(toLength: 24, withPad: " ", startingAt: 0),
                String(format: "%5d  %5d  %7.2f  %6d", row.total, row.right, row.ms / Double(row.total), row.tokens),
            ]
            lines.append(columns.joined(separator: " "))
        }
        let right = routes.values.map(\.right).reduce(0, +)
        lines.append("\(right) of \(cases.count) right, 0 cloud tokens")
        if !wrong.isEmpty { lines.append("wrong:\n" + wrong.joined(separator: "\n")) }
        return lines.joined(separator: "\n")
    }
}

import Foundation
import Testing

@testable import ActionEngine

let now = try! Date("2026-11-05T09:00:00Z", strategy: .iso8601)
let friday3pm = try! Date("2026-11-06T15:00:00Z", strategy: .iso8601)

func scratch() throws -> Workspace {
    try Workspace(root: FileManager.default.temporaryDirectory.appending(path: UUID().uuidString))
}

@Suite struct Dates {
    let when = When(now: now)

    @Test func resolvesWords() {
        #expect(when.resolve("friday at 3pm") == friday3pm)
        #expect(when.resolve("tomorrow 15:00") == friday3pm)
    }

    @Test func refusesToGuess() {
        #expect(when.resolve("at 3") == nil)
        #expect(when.resolve("when I get in") == nil)
        #expect(when.resolve("13pm") == nil)
    }
}

@Suite struct Tier0 {
    let rules = Rules(when: When(now: now))

    @Test func readsKnownShapes() {
        let plan = rules.plan("remind me to send the invoice friday at 3pm")
        #expect(plan?.steps == [Step(id: "s1", action: .addTask(title: "send the invoice", due: friday3pm))])
    }

    @Test func chainsSteps() {
        let plan = rules.plan("save a note called Standup: TODO: ship it then extract tasks from Standup")
        #expect(plan?.steps.count == 2)
        #expect(plan?.steps[1].after == ["s1"])
    }

    @Test func leavesTheRestAlone() {
        #expect(rules.plan("nudge me about the invoice when I get in") == nil)
        #expect(rules.plan("book me a flight to Lisbon on friday") == nil)
        #expect(rules.plan("turn off the lights") == nil)
    }
}

@Suite struct Gate {
    let validator = Validator(now: now)

    @Test func catchesLoops() {
        let plan = Plan(steps: [
            Step(id: "a", action: .saveNote(title: "A", body: "x"), after: ["b"]),
            Step(id: "b", action: .saveNote(title: "B", body: "x"), after: ["a"]),
        ])
        #expect(throws: PlanError.cycle) { try validator.check(plan) }
    }

    @Test func catchesThePast() {
        let plan = Plan(steps: [Step(id: "a", action: .addTask(title: "Late", due: .distantPast))])
        #expect(throws: PlanError.self) { try validator.check(plan) }
    }

    @Test func modelCannotInventAnAction() throws {
        let raw = #"{"steps":[{"action":"delete_files","title":"~","when":"","minutes":0,"body":""}]}"#
        #expect(throws: EngineError.self) { try Engine.decode(raw, When(now: now)) }
    }
}

@Suite struct Effects {
    let plan = Plan(steps: [
        Step(id: "s1", action: .addTask(title: "Send the invoice", due: friday3pm)),
        Step(id: "s2", action: .scheduleEvent(title: "Review", start: friday3pm, minutes: 45), after: ["s1"]),
    ])

    @Test func runningTwiceChangesNothing() throws {
        let workspace = try scratch()
        let executor = Executor(workspace: workspace, now: now)
        try executor.run(plan)
        let second = try executor.run(plan)
        #expect(second.allSatisfy { $0.status == "skipped" })
        #expect(workspace.lines(of: workspace.tasks).count == 1)
    }

    @Test func aCrashNeverDuplicates() throws {
        let workspace = try scratch()
        let crashing = Executor(workspace: workspace, now: now, crashAfter: "s1")
        #expect(throws: Executor.Crash.self) { try crashing.run(plan) }

        try Executor(workspace: workspace, now: now).run(plan)
        #expect(workspace.lines(of: workspace.tasks).count == 1)
    }

    @Test func aTitleCannotEscapeTheWorkspace() {
        #expect(Workspace.slug("../../.ssh/authorized_keys") == "ssh-authorized-keys")
    }
}

@Test func readsTokenCountFromLlamaTimings() {
    let log = """
    prompt eval time =  16.83 ms /    13 tokens
           eval time =  27.04 ms /     7 runs
          total time =  46.43 ms /    20 tokens
    """
    #expect(LlamaProposer.tokens(in: log) == 20)
}

@Suite struct Replay {
    struct Canned: Proposer {
        let name = "canned"
        func propose(_ request: String) async throws -> ModelReply {
            let raw = #"{"steps":[{"action":"add_task","title":"Pay rent","when":"friday at 3pm","minutes":0,"body":""}]}"#
            return ModelReply(raw: raw, tokens: 40)
        }
    }

    @Test func aRecordRebuildsTheSamePlan() async throws {
        let routed = try await Engine(now: now, proposer: Canned()).plan("sort out rent by friday afternoon")
        #expect(routed.route == "canned")
        #expect(routed.cloudTokens == 0)
        #expect(try fingerprint(try Engine.replay(routed)) == routed.hash)
    }
}

{"request":"remind me to send the invoice friday at 3pm","expect":["addTask"],"date":"2026-11-06T15:00:00Z"}
{"request":"nudge me to pay the rent on monday","expect":["addTask"],"date":"2026-11-09T09:00:00Z"}
{"request":"put a 45 minute design review on my calendar for tomorrow at 10am","expect":["scheduleEvent"],"date":"2026-11-06T10:00:00Z"}
{"request":"book me a flight to Lisbon","expect":["refused"]}