Repository Public MIT
1// =============================================================================2// SP BOUCHER | SOFTWARE & RESEARCH3// ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project : ORIX Astra9// File : Tests/AstraAgentsTests/Support.swift10// Module : AstraAgentsTests11// Repository : https://git.spboucher.ai/orix-astra12// Created : 2026-11-2113// Last Modified : 2026-11-2114//15// =============================================================================16// AUTHOR & PROFESSIONAL AFFILIATION17// =============================================================================18//19// Author : Simon-Pierre Boucher20// Position : Professor of Finance21// Institution : Université du Québec en Outaouais (UQO)22// Department : Département des sciences administratives23// Organization : SP Boucher24//25// Website : https://spboucher.ai26// Git : https://git.spboucher.ai27//28// =============================================================================29// OFFICIAL CONTACT DIRECTORY30// =============================================================================31//32// General : info@spboucher.ai33// Professional : contact@spboucher.ai34// Direct : simon@spboucher.ai35// Research : research@spboucher.ai36// Development : dev@spboucher.ai37// Support : support@spboucher.ai38// Security/Admin : admin@spboucher.ai39// Notifications : notifications@spboucher.ai40//41// Preferred Contact: support@spboucher.ai42//43// =============================================================================44// COPYRIGHT & INTELLECTUAL PROPERTY45// =============================================================================46//47// Copyright (c) 202648// Simon-Pierre Boucher49//50// All rights reserved where applicable.51//52// This file is governed by the applicable project license,53// copyright notices, institutional agreements and relevant law.54//55// Unless expressly authorized by the applicable license or56// rights holder, copying, redistribution, sublicensing,57// publication and commercial exploitation are not permitted.58//59// Existing third-party rights and notices remain unaffected.60//61// =============================================================================62// CONFIDENTIALITY & SECURITY63// =============================================================================64//65// Classification : Public66// Distribution : Public repository; use is governed by the project license67// Security Contact : admin@spboucher.ai68//69// Access to this source does not independently grant permission70// to redistribute or disclose confidential materials.71//72// Do not embed credentials, private keys, access tokens,73// certificates or confidential personal information.74//75// =============================================================================76// LICENSE & MAINTENANCE77// =============================================================================78//79// License : Proprietary, all rights reserved (see license file)80// License File : LICENSE81// Maintainer : Simon-Pierre Boucher82// Technical Contact: dev@spboucher.ai83//84// =============================================================================85// END OF SP BOUCHER SOURCE HEADER86// =============================================================================8788import Foundation89import Testing90import AstraCore91@testable import AstraAgents9293// MARK: - Scripted provider (test double: lives in the test target only)9495final class ScriptedProvider: ChatProvider, @unchecked Sendable {96 enum Turn: Sendable {97 case events([StreamEvent])98 /// Yields the events, then never finishes until the request is cancelled.99 case hang(after: [StreamEvent])100 case fail(AstraError)101 }102103 let kind: ProviderKind104 private let lock = NSLock()105 private var turns: [Turn]106 private var recorded: [GenerationRequest] = []107 /// Used when the script runs out.108 private let fallback: (@Sendable (Int) -> Turn)?109110 init(kind: ProviderKind = .openAI, _ turns: [Turn], fallback: (@Sendable (Int) -> Turn)? = nil) {111 self.kind = kind; self.turns = turns; self.fallback = fallback112 }113114 var requests: [GenerationRequest] { lock.withLock { recorded } }115116 func listModels() async throws -> [ModelInfo] { [] }117 func verify() async throws -> ConnectionStatus { ConnectionStatus(ok: true, detail: "scripted") }118119 func stream(_ request: GenerationRequest) -> AsyncThrowingStream<StreamEvent, Error> {120 let turn: Turn = lock.withLock {121 recorded.append(request)122 if !turns.isEmpty { return turns.removeFirst() }123 return fallback?(recorded.count) ?? .fail(.protocolViolation("the script has no more turns"))124 }125 return AsyncThrowingStream { continuation in126 let task = Task {127 switch turn {128 case .events(let events):129 for event in events { continuation.yield(event) }130 continuation.finish()131 case .hang(let events):132 for event in events { continuation.yield(event) }133 try? await Task.sleep(nanoseconds: 60_000_000_000)134 continuation.finish(throwing: CancellationError())135 case .fail(let error):136 continuation.finish(throwing: error)137 }138 }139 continuation.onTermination = { _ in task.cancel() }140 }141 }142143 // Script builders144145 static func text(_ text: String, usage: TokenUsage? = TokenUsage(inputTokens: 100, outputTokens: 20)) -> Turn {146 var events: [StreamEvent] = [.messageStarted(MessageStart(responseID: "r", reportedModel: "scripted"))]147 // Two deltas, so tests see real streaming.148 let middle = text.index(text.startIndex, offsetBy: text.count / 2)149 if !text.isEmpty { events += [.textDelta(String(text[..<middle])), .textDelta(String(text[middle...]))] }150 if let usage { events.append(.usage(usage)) }151 events.append(.messageCompleted(.endOfTurn))152 return .events(events)153 }154155 static func calls(_ calls: [ToolCall], text: String = "", usage: TokenUsage? = TokenUsage(inputTokens: 100, outputTokens: 20)) -> Turn {156 var events: [StreamEvent] = [.messageStarted(MessageStart())]157 if !text.isEmpty { events.append(.textDelta(text)) }158 for call in calls {159 events += [.toolCallStarted(id: call.id, name: call.name), .toolCallDelta(id: call.id, argumentsFragment: call.arguments.serialized()),160 .toolCallCompleted(call)]161 }162 if let usage { events.append(.usage(usage)) }163 events.append(.messageCompleted(.toolCalls))164 return .events(events)165 }166167 static func call(_ name: String, _ arguments: JSONValue = [:], id: String = UUID().uuidString) -> Turn {168 calls([ToolCall(id: id, name: name, arguments: arguments)])169 }170}171172// MARK: - Fakes173174/// A configurable tool that records how it was called.175final class SpyTool: AgentTool, @unchecked Sendable {176 let definition: ToolDefinition177 let risk: ToolRisk178 private let lock = NSLock()179 private var recorded: [JSONValue] = []180 private let output: @Sendable (JSONValue) throws -> String181 private let scopeKey: String?182183 init(_ name: String, risk: ToolRisk = .safe, scopeKey: String? = nil, parameters: JSONValue? = nil,184 output: @escaping @Sendable (JSONValue) throws -> String = { _ in "ok" }) {185 definition = ToolDefinition(name: name, summary: "Test tool \(name).", parameters: parameters ?? ["type": "object"])186 self.risk = risk; self.output = output; self.scopeKey = scopeKey187 }188189 var calls: [JSONValue] { lock.withLock { recorded } }190 func approvalScope(_ arguments: JSONValue) -> String? { scopeKey.flatMap { arguments[$0]?.stringValue } }191 func run(_ arguments: JSONValue, context: ToolContext) async throws -> ToolOutput {192 lock.withLock { recorded.append(arguments) }193 return ToolOutput(try output(arguments))194 }195}196197/// Starts and then never returns on its own; `honoursCancellation` false models a tool stuck in a call that ignores cancellation.198struct HangingTool: AgentTool {199 let definition = ToolDefinition(name: "hang", summary: "Never returns.", parameters: ["type": "object"])200 let risk: ToolRisk = .safe201 var honoursCancellation = true202 func run(_ arguments: JSONValue, context: ToolContext) async throws -> ToolOutput {203 if honoursCancellation { try await Task.sleep(nanoseconds: 60_000_000_000) }204 else { await withCheckedContinuation { (_: CheckedContinuation<Void, Never>) in } }205 return ToolOutput("never")206 }207}208209final class ApprovalRecorder: ApprovalHandler, @unchecked Sendable {210 private let lock = NSLock()211 private var recorded: [ApprovalRequest] = []212 private let decide: @Sendable (ApprovalRequest, Int) async -> ApprovalDecision213214 init(_ decide: @escaping @Sendable (ApprovalRequest, Int) async -> ApprovalDecision) { self.decide = decide }215 convenience init(always decision: ApprovalDecision) { self.init { _, _ in decision } }216217 var requests: [ApprovalRequest] { lock.withLock { recorded } }218 func requestApproval(_ request: ApprovalRequest) async -> ApprovalDecision {219 let index = lock.withLock { () -> Int in recorded.append(request); return recorded.count }220 return await decide(request, index)221 }222}223224struct FakeDocuments: DocumentSearching {225 var hits: [DocumentHit]226 func search(_ query: String, limit: Int) async throws -> [DocumentHit] { hits }227}228229final class FakeFiles: FileAccessing, @unchecked Sendable {230 private let lock = NSLock()231 var items: [GrantedItem]232 var contents: [String: String]233 var writeResult: FileWriteResult?234 private var readIDs: [String] = []235 private var writeLog: [(String, String)] = []236237 init(items: [GrantedItem] = [], contents: [String: String] = [:], writeResult: FileWriteResult? = nil) {238 self.items = items; self.contents = contents; self.writeResult = writeResult239 }240 var reads: [String] { lock.withLock { readIDs } }241 var writes: [(String, String)] { lock.withLock { writeLog } }242243 func grantedItems() async throws -> [GrantedItem] { items }244 func readText(itemID: String, maxBytes: Int) async throws -> FileText {245 lock.withLock { readIDs.append(itemID) }246 guard let text = contents[itemID] else { throw ToolError("not granted") }247 let cut = text.utf8.count > maxBytes248 return FileText(text: cut ? String(decoding: text.utf8.prefix(maxBytes), as: UTF8.self) : text, truncated: cut)249 }250 func proposeWrite(fileName: String, text: String) async throws -> FileWriteResult {251 lock.withLock { writeLog.append((fileName, text)) }252 return writeResult ?? .saved(name: fileName)253 }254}255256final class FakeWeb: WebFetching, @unchecked Sendable {257 private let lock = NSLock()258 private var fetched: [URL] = []259 private let respond: @Sendable (WebFetchRequest) throws -> WebFetchResponse260261 init(_ respond: @escaping @Sendable (WebFetchRequest) throws -> WebFetchResponse) { self.respond = respond }262 convenience init(html: String) {263 self.init { WebFetchResponse(status: 200, contentType: "text/html; charset=utf-8", body: Data(html.utf8), finalURL: $0.url) }264 }265 var urls: [URL] { lock.withLock { fetched } }266 func fetch(_ request: WebFetchRequest) async throws -> WebFetchResponse {267 lock.withLock { fetched.append(request.url) }268 return try respond(request)269 }270}271272// MARK: - Helpers273274let testModel = ModelRef(provider: .openAI, modelID: "scripted-1")275276func makeRunner(_ provider: ScriptedProvider, tools: [any AgentTool] = [], approvals: any ApprovalHandler = ClosureApprovalHandler.denyAll) -> AgentRunner {277 AgentRunner(orchestrator: InferenceOrchestrator(maxRetries: 0) { _ in provider }, registry: ToolRegistry(tools), approvals: approvals)278}279280func makeProfile(tools: [String] = [], budgets: AgentBudgets = AgentBudgets(), hosts: [String] = [], planning: Bool = true,281 model: ModelRef = testModel) -> AgentProfile {282 AgentProfile(id: "profile-1", name: "Tester", instructions: "Be exact.", model: model, allowedTools: tools, budgets: budgets,283 preApprovedWebHosts: hosts, planningEnabled: planning)284}285286func collect(_ stream: AsyncStream<AgentEvent>) async -> [AgentEvent] {287 var out: [AgentEvent] = []288 for await event in stream { out.append(event) }289 return out290}291292func runTool(_ tool: any AgentTool, _ arguments: JSONValue) async throws -> String {293 try SchemaValidator.validate(arguments: arguments, for: tool.definition)294 try tool.preflight(arguments)295 return try await tool.run(arguments, context: ToolContext()).text296}297298func toolError(_ tool: any AgentTool, _ arguments: JSONValue) async -> String? {299 do { _ = try await runTool(tool, arguments); return nil }300 catch { return (error as? ToolError)?.message ?? String(describing: error) }301}302303extension Array where Element == AgentEvent {304 var status: AgentRunStatus? {305 for case .runFinished(let status, _) in self { return status }306 return nil307 }308 var finalText: String? {309 for case .runFinished(_, let text) in self { return text }310 return nil311 }312 var steps: [Int] { compactMap { if case .stepStarted(let n) = $0 { n } else { nil } } }313 var started: [String] { compactMap { if case .toolStarted(_, let name) = $0 { name } else { nil } } }314 var requested: [ToolCall] { compactMap { if case .toolRequested(let call) = $0 { call } else { nil } } }315 var approvalRequests: [ApprovalRequest] { compactMap { if case .approvalRequested(let r) = $0 { r } else { nil } } }316 var decisions: [ApprovalDecision] { compactMap { if case .approvalResolved(_, let d) = $0 { d } else { nil } } }317 var checkpoints: [AgentCheckpoint] { compactMap { if case .checkpointSaved(let c) = $0 { c } else { nil } } }318 var plans: [AgentPlan] { compactMap { if case .planUpdated(let p) = $0 { p } else { nil } } }319 var warnings: [BudgetWarning] { compactMap { if case .budgetWarning(let w) = $0 { w } else { nil } } }320 var costs: [CostEstimate] { compactMap { if case .usage(_, let c) = $0 { c } else { nil } } }321 var totals: [TokenUsage] { compactMap { if case .usage(let u, _) = $0 { u } else { nil } } }322 var text: String { compactMap { if case .modelTextDelta(let t) = $0 { t } else { nil } }.joined() }323 struct Finished { var callID: String; var name: String; var output: String; var isError: Bool; var flagged: [InjectionFinding] }324 var finished: [Finished] {325 compactMap {326 if case .toolFinished(let id, let name, let output, let isError, let flagged) = $0 {327 Finished(callID: id, name: name, output: output, isError: isError, flagged: flagged)328 } else { nil }329 }330 }331}332333/// The tool-result messages the provider received in its `n`-th request (0-based).334func toolMessages(_ provider: ScriptedProvider, request n: Int) -> [PromptMessage] {335 provider.requests[n].messages.filter { $0.role == .tool }336}337