SPB Git

Repository Public

AgentRunner.swift 20.0 KB 344 lines swift

1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Packages/LocalChatAgents/Sources/AgentRunner.swift3// Description: Multi-step agent loop over any TextGenerating backend: tool calls, human approval checkpoints, limits, cancellation, structured run log.4import Foundation5import LocalChatCore67public struct ApprovalRequest: Sendable, Identifiable, Hashable {8    public var id: String                 // tool call id9    public var runID: UUID10    public var toolName: String11    public var risk: ToolRisk12    public var arguments: JSONValue13    public var summary: String            // one line for the approval sheet14    public var canApproveForRun: Bool     // false for tools that must be approved every time (shell)15}1617public enum ApprovalDecision: Sendable, Hashable, Codable {18    case approve19    case approveForRun                    // do not ask again for this tool during this run20    case deny(reason: String?)21}2223public enum AgentLimit: String, Sendable, Codable { case steps, toolCalls, time }2425public struct AgentTotals: Sendable, Hashable, Codable {26    public var steps = 027    public var toolCalls = 028    public var promptTokens = 029    public var completionTokens = 030    public var duration: TimeInterval = 031    public init() {}32}3334public struct AgentRunLog: Codable, Sendable, Identifiable, Hashable {35    public enum Outcome: Codable, Sendable, Hashable { case running, completed, limitReached(AgentLimit), cancelled, failed(String) }36    public enum Decision: String, Codable, Sendable { case notRequired, approved, approvedForRun, denied, rejected }   // rejected = refused before approval (permission / schema)37    public struct ToolCallLog: Codable, Sendable, Hashable, Identifiable {38        public var id: String39        public var name: String40        public var arguments: JSONValue41        public var decision: Decision42        public var denialReason: String?43        public var output: String?44        public var isError: Bool45        public var startedAt: Date46        public var duration: TimeInterval47    }48    public struct Step: Codable, Sendable, Hashable {49        public var index: Int50        public var text: String51        public var reasoning: String52        public var toolCalls: [ToolCallLog]53        public var metrics: GenerationMetrics?54        public var startedAt: Date55    }56    public var id: UUID57    public var agentID: UUID58    public var agentName: String59    public var modelID: String60    public var task: String61    public var startedAt: Date62    public var endedAt: Date?63    public var steps: [Step]64    public var outcome: Outcome65    public var finalText: String66    public var totals: AgentTotals67}6869public enum AgentEvent: Sendable {70    case stepStarted(Int)71    case text(String)72    case reasoning(String)73    case toolRequested(ToolInvocation)74    case approvalNeeded(ApprovalRequest)75    case toolDenied(callID: String, reason: String)76    case toolStarted(callID: String, name: String)77    case toolFinished(callID: String, name: String, output: ToolOutput, duration: TimeInterval)78    case limitReached(AgentLimit)79    case finished(text: String, totals: AgentTotals, log: AgentRunLog)80    case failed(String, log: AgentRunLog)81}8283public struct AgentRunOptions: Sendable {84    public var perToolTimeout: TimeInterval85    public var toolOutputTokenBudget: Int        // tool results longer than this are truncated before they reach the model86    /// Opt-in fallback for models without native tool calling: a reply that is a single fenced JSON object87    /// `{"tool": "<name>", "arguments": {…}}` is treated as a tool call. The system prompt then explains this format.88    public var allowTextToolCalls: Bool89    public var sessionKey: String?90    public init(perToolTimeout: TimeInterval = 60, toolOutputTokenBudget: Int = 2000, allowTextToolCalls: Bool = false, sessionKey: String? = nil) {91        self.perToolTimeout = perToolTimeout; self.toolOutputTokenBudget = toolOutputTokenBudget92        self.allowTextToolCalls = allowTextToolCalls; self.sessionKey = sessionKey93    }94}9596public struct AgentRunner: Sendable {97    public typealias Approver = @Sendable (ApprovalRequest) async -> ApprovalDecision98    let generator: any TextGenerating99    let registry: ToolRegistry100    let knowledge: (any KnowledgeSearching)?101102    public init(generator: any TextGenerating, registry: ToolRegistry, knowledge: (any KnowledgeSearching)? = nil) {103        self.generator = generator; self.registry = registry; self.knowledge = knowledge104    }105106    /// Runs the agent on `messages` (the conversation so far, ending with the user's task). Cancel by ending the stream's consumer task.107    /// With no approver, any call that needs approval is denied.108    public func run(agent: AgentConfiguration, modelID: String, messages: [PromptMessage], permissions: ToolPermissions,109                    options: AgentRunOptions = .init(), approve: Approver? = nil) -> AsyncStream<AgentEvent> {110        AsyncStream { continuation in111            let task = Task { await self.loop(agent, modelID, messages, permissions, options, approve, continuation); continuation.finish() }112            continuation.onTermination = { _ in task.cancel() }113        }114    }115116    public static func systemPrompt(agent: AgentConfiguration, tools: [ToolDefinition], textToolCalls: Bool) -> String {117        var parts: [String] = []118        let instructions = agent.instructions.trimmingCharacters(in: .whitespacesAndNewlines)119        parts.append(instructions.isEmpty ? "You are \(agent.name), a helpful assistant that completes tasks step by step." : instructions)120        if !tools.isEmpty {121            parts.append("""122            You can use tools. Call a tool only when it helps; otherwise answer directly. Use one step at a time and read each result before deciding \123            the next step. If a tool fails or is denied, do not retry the same call: explain or try another way. When the task is done, give the final \124            answer in plain text without calling a tool. Never invent tool results.125            """)126            if textToolCalls {127                let list = tools.map { "- \($0.name): \($0.summary) Arguments schema: \($0.parameters.serialized())" }.joined(separator: "\n")128                parts.append("To call a tool, reply with only one fenced block:\n```json\n{\"tool\": \"<name>\", \"arguments\": { … }}\n```\nAvailable tools:\n\(list)")129            }130        }131        return parts.joined(separator: "\n\n")132    }133134    /// Parses the opt-in text form. Only a reply whose sole content is one JSON object with "tool" (and optional "arguments") counts.135    public static func parseTextToolCall(_ text: String) -> ToolInvocation? {136        var body = text.trimmingCharacters(in: .whitespacesAndNewlines)137        if body.hasPrefix("```") {138            guard body.hasSuffix("```"), body.components(separatedBy: "```").count == 3 else { return nil }139            body = String(body.dropFirst(3).dropLast(3))140            if let newline = body.firstIndex(of: "\n"), body[..<newline].allSatisfy({ $0.isLetter }) { body = String(body[body.index(after: newline)...]) }141            body = body.trimmingCharacters(in: .whitespacesAndNewlines)142        } else { return nil }143        guard let value = JSONValue.parse(body), let object = value.objectValue, let name = object["tool"]?.stringValue, !name.isEmpty,144              Set(object.keys).isSubset(of: ["tool", "arguments"]) else { return nil }145        return ToolInvocation(name: name, arguments: object["arguments"] ?? .object([:]))146    }147148    static func describe(_ call: ToolInvocation) -> String {149        switch call.name {150        case "run_shell": return "Run: " + (call.arguments["command"]?.stringValue ?? "")151        case "write_file": return "Write \(call.arguments["path"]?.stringValue ?? "a file") (\((call.arguments["content"]?.stringValue ?? "").utf8.count) bytes)"152        case "fetch_url": return "Fetch " + (call.arguments["url"]?.stringValue ?? "")153        default: return "\(call.name) \(call.arguments.serialized())".prefix(300).description154        }155    }156157    static func truncate(_ text: String, tokens: Int) -> String {158        let limit = max(200, tokens * 4)159        guard text.count > limit else { return text }160        let head = text.prefix(limit * 3 / 4), tail = text.suffix(limit / 4)161        return "\(head)\n[… \(text.count - limit) characters omitted …]\n\(tail)"162    }163164    private func loop(_ agent: AgentConfiguration, _ modelID: String, _ input: [PromptMessage], _ permissions: ToolPermissions,165                      _ options: AgentRunOptions, _ approve: Approver?, _ out: AsyncStream<AgentEvent>.Continuation) async {166        let started = Date()167        let deadline = started.addingTimeInterval(TimeInterval(max(1, agent.timeLimitSeconds)))168        let definitions = registry.definitions(for: permissions)169        let context = ToolContext(permissions: permissions, knowledge: knowledge, collectionIDs: agent.collectionIDs)170        var messages = input.filter { $0.role != .system }171        let extraSystem = input.filter { $0.role == .system }.map(\.content)172        let system = ([Self.systemPrompt(agent: agent, tools: definitions, textToolCalls: options.allowTextToolCalls)] + extraSystem).joined(separator: "\n\n")173        var log = AgentRunLog(id: UUID(), agentID: agent.id, agentName: agent.name, modelID: modelID,174                              task: messages.last(where: { $0.role == .user })?.content ?? "", startedAt: started, endedAt: nil, steps: [],175                              outcome: .running, finalText: "", totals: AgentTotals())176        var approvedForRun: Set<String> = []177        var finalText = ""; var limit: AgentLimit?178179        func close(_ outcome: AgentRunLog.Outcome) -> AgentRunLog {180            log.outcome = outcome; log.endedAt = Date(); log.finalText = finalText181            log.totals.duration = Date().timeIntervalSince(started); log.totals.steps = log.steps.count182            return log183        }184185        /// One model turn. Returns nil when the run must stop (cancelled / failed / time limit, already reported).186        func generate(step: Int, tools: [ToolDefinition]) async -> (text: String, calls: [ToolInvocation])? {187            out.yield(.stepStarted(step))188            var text = "", reasoning = "", calls: [ToolInvocation] = []; var metrics: GenerationMetrics?189            let request = GenerationRequest(messages: [.system(system)] + messages, settings: agent.settings, tools: tools, sessionKey: options.sessionKey)190            let stepStart = Date()191            do {192                for try await event in generator.generate(modelID: modelID, request: request) {193                    try Task.checkCancellation()194                    if Date() > deadline { limit = .time; break }195                    switch event {196                    case .text(let t): text += t; out.yield(.text(t))197                    case .reasoning(let t): reasoning += t; out.yield(.reasoning(t))198                    case .toolCall(let call): calls.append(call)199                    case .finished(let m): metrics = m200                    }201                }202            } catch {203                log.steps.append(.init(index: step, text: text, reasoning: reasoning, toolCalls: [], metrics: metrics, startedAt: stepStart))204                finalText = text205                if error is CancellationError || Task.isCancelled || (error as? InferenceError) == .cancelled { _ = close(.cancelled) }206                else {207                    let message = (error as? LocalizedError)?.errorDescription ?? String(describing: error)208                    out.yield(.failed(message, log: close(.failed(message))))209                }210                return nil211            }212            log.totals.promptTokens += metrics?.promptTokens ?? 0; log.totals.completionTokens += metrics?.completionTokens ?? 0213            if calls.isEmpty, options.allowTextToolCalls, !tools.isEmpty, let parsed = Self.parseTextToolCall(text) { calls = [parsed]; text = "" }214            log.steps.append(.init(index: step, text: text, reasoning: reasoning, toolCalls: [], metrics: metrics, startedAt: stepStart))215            if limit == .time {216                finalText = text; out.yield(.limitReached(.time))217                out.yield(.finished(text: finalText, totals: close(.limitReached(.time)).totals, log: log))218                return nil219            }220            return (text, calls)221        }222223        var step = 0224        while true {225            if Task.isCancelled { _ = close(.cancelled); return }226            if Date() > deadline { limit = .time; break }227            if step >= max(1, agent.maxSteps) { limit = .steps; break }228            step += 1229            guard let turn = await generate(step: step, tools: definitions) else { return }230            if turn.calls.isEmpty { finalText = turn.text; break }231            messages.append(PromptMessage(role: .assistant, content: turn.text, toolCalls: turn.calls))232233            for call in turn.calls {234                if Task.isCancelled { _ = close(.cancelled); return }235                out.yield(.toolRequested(call))236                var entry = AgentRunLog.ToolCallLog(id: call.id, name: call.name, arguments: call.arguments, decision: .notRequired, denialReason: nil,237                                                    output: nil, isError: false, startedAt: Date(), duration: 0)238                var output: ToolOutput239                if log.totals.toolCalls >= max(0, agent.maxToolCalls) {240                    limit = .toolCalls; entry.decision = .rejected241                    output = .error("The tool-call budget for this task is exhausted. Answer with what you have.")242                } else if Date() > deadline {243                    limit = .time; entry.decision = .rejected; output = .error("The time limit for this task is reached.")244                } else {245                    switch registry.prepare(call, permissions: permissions) {246                    case .failure(let error):247                        entry.decision = .rejected; output = .error(error.message)248                    case .success(let ready):249                        var allowed = true250                        let needsApproval = registry.requiresApproval(ready.tool, permissions: permissions)251                            && !(approvedForRun.contains(call.name) && !ready.tool.alwaysRequiresApproval)252                        output = .error("Denied.")253                        if needsApproval {254                            let request = ApprovalRequest(id: call.id, runID: log.id, toolName: call.name, risk: ready.tool.risk, arguments: ready.arguments,255                                                          summary: Self.describe(call), canApproveForRun: !ready.tool.alwaysRequiresApproval)256                            out.yield(.approvalNeeded(request))257                            let decision = await approve?(request) ?? .deny(reason: "No one is available to approve this action.")258                            if Task.isCancelled { _ = close(.cancelled); return }259                            switch decision {260                            case .approve: entry.decision = .approved261                            case .approveForRun:262                                entry.decision = ready.tool.alwaysRequiresApproval ? .approved : .approvedForRun263                                if !ready.tool.alwaysRequiresApproval { approvedForRun.insert(call.name) }264                            case .deny(let reason):265                                allowed = false; entry.decision = .denied; entry.denialReason = reason266                                let why = reason.flatMap { $0.isEmpty ? nil : $0 }267                                output = .error("The user denied this action" + (why.map { ": \($0)" } ?? ".") + " Do not retry it.")268                                out.yield(.toolDenied(callID: call.id, reason: why ?? "Denied by the user."))269                            }270                        }271                        if allowed {272                            log.totals.toolCalls += 1273                            out.yield(.toolStarted(callID: call.id, name: call.name))274                            let t0 = Date()275                            let prepared = ToolInvocation(id: call.id, name: call.name, arguments: ready.arguments)276                            output = await Self.withTimeout(min(options.perToolTimeout, max(1, deadline.timeIntervalSinceNow))) {277                                await registry.execute(prepared, context: context)278                            } ?? .error("The tool timed out after \(Int(options.perToolTimeout)) s.")279                            entry.duration = Date().timeIntervalSince(t0)280                            if Task.isCancelled { entry.output = output.text; entry.isError = true; log.steps[log.steps.count - 1].toolCalls.append(entry); _ = close(.cancelled); return }281                            output.text = Self.truncate(output.text, tokens: options.toolOutputTokenBudget)282                            out.yield(.toolFinished(callID: call.id, name: call.name, output: output, duration: entry.duration))283                        }284                    }285                }286                entry.output = output.text; entry.isError = output.isError287                log.steps[log.steps.count - 1].toolCalls.append(entry)288                messages.append(PromptMessage(role: .tool, content: output.text, toolCallID: call.id, toolName: call.name))289            }290            if limit != nil { break }291        }292293        if let reached = limit {294            out.yield(.limitReached(reached))295            if reached != .time, !Task.isCancelled {296                // one last turn without tools so the user still gets an answer from what was gathered297                messages.append(.user("You have reached the limit of actions for this task. Do not call tools. Give your best final answer now from what you already know, and say what is missing."))298                guard let turn = await generate(step: step + 1, tools: []) else { return }299                finalText = turn.text300            }301            out.yield(.finished(text: finalText, totals: close(.limitReached(reached)).totals, log: log))302            return303        }304        if Task.isCancelled { _ = close(.cancelled); return }305        out.yield(.finished(text: finalText, totals: close(.completed).totals, log: log))306    }307308    /// Runs `work`, returning nil when it takes longer than `seconds` (the work is cancelled).309    static func withTimeout<T: Sendable>(_ seconds: TimeInterval, _ work: @escaping @Sendable () async -> T) async -> T? {310        await withTaskGroup(of: T?.self) { group in311            group.addTask { await work() }312            group.addTask { try? await Task.sleep(nanoseconds: UInt64(max(0.01, seconds) * 1e9)); return nil }313            let first = await group.next() ?? nil314            group.cancelAll()315            return first316        }317    }318}319320/// File-backed store of run logs (one JSON file per run).321public struct AgentLogStore: Sendable {322    public let directory: URL323    public init(directory: URL) { self.directory = directory; try? FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true) }324325    private func url(_ id: UUID) -> URL { directory.appendingPathComponent(id.uuidString + ".json") }326327    public func save(_ log: AgentRunLog) throws {328        let encoder = CoreCoding.encoder; encoder.outputFormatting = [.sortedKeys, .prettyPrinted]329        try encoder.encode(log).write(to: url(log.id), options: .atomic)330    }331    public func load(_ id: UUID) throws -> AgentRunLog { try CoreCoding.decoder.decode(AgentRunLog.self, from: Data(contentsOf: url(id))) }332333    /// Newest first. Unreadable files are skipped.334    public func list(agentID: UUID? = nil, limit: Int = 200) -> [AgentRunLog] {335        let files = (try? FileManager.default.contentsOfDirectory(at: directory, includingPropertiesForKeys: nil)) ?? []336        return files.filter { $0.pathExtension == "json" }337            .compactMap { try? CoreCoding.decoder.decode(AgentRunLog.self, from: Data(contentsOf: $0)) }338            .filter { agentID == nil || $0.agentID == agentID }339            .sorted { $0.startedAt > $1.startedAt }.prefix(limit).map { $0 }340    }341    @discardableResult public func delete(_ id: UUID) -> Bool { (try? FileManager.default.removeItem(at: url(id))) != nil }342    public func deleteAll() { for log in list(limit: .max) { delete(log.id) } }343}344
Files main
Menu

Theme