Repository Public
1// SP Notes Core2// File: Sources/SPNotesAPI/AgentModels.swift3// Description: Models of the bounded agents (`/api/agents`): the fixed catalogue, executions, proposals with their4// before / after previews, and the results of approving, rejecting or undoing proposals.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation910/// The hard caps of one agent run.11public struct AgentLimits: Codable, Sendable, Equatable {12 public var maxToolCalls: Int?13 public var maxTurns: Int?14 public var maxTokens: Int?15 public var maxCostUsd: Double?16 public var timeoutMs: Int?17 public var maxProposals: Int?18}1920/// One task of the fixed catalogue. An agent only reads what its scope lists and only PROPOSES changes.21public struct AgentInfo: Codable, Sendable, Equatable, Identifiable {22 /// `sort_inbox`, `suggest_tags`, `plan_from_page`, `check_references`.23 public var id: String24 public var name: String25 public var icon: String?26 public var description: String?27 public var tools: [String]?28 public var scopes: [String]?29 /// Shown to the owner before a run: what it reads…30 public var reads: [String]?31 /// …what it may propose…32 public var proposes: [String]?33 /// …and what it never does.34 public var never: [String]?35 /// `required`, `optional` or `none`: whether a run takes a page.36 public var page: String?37 public var limits: AgentLimits?3839 public var needsPage: Bool { page == "required" }40 public var acceptsPage: Bool { page == "required" || page == "optional" }41}4243/// Where a run would be sent.44public struct AgentTarget: Codable, Sendable, Equatable {45 public var provider: String?46 public var model: String?47}4849/// The states of an execution (`status`).50public enum AgentExecutionStatus {51 public static let pending = "pending"52 public static let running = "running"53 public static let awaitingApproval = "awaiting_approval"54 public static let approved = "approved"55 public static let rejected = "rejected"56 public static let completed = "completed"57 public static let failed = "failed"58 /// A run that is still working: poll `agentExecution(id:)`.59 public static let live: Set<String> = [pending, running]60}6162/// An execution in the list of `GET /api/agents`.63///64/// Not observed on the scratch server (a run calls a paid model): fields follow the server code, all but `id`65/// optional.66public struct AgentExecutionSummary: Codable, Sendable, Equatable, Identifiable {67 public var id: String68 public var agent: String?69 public var model: String?70 /// See `AgentExecutionStatus`.71 public var status: String?72 /// One line: what the run did.73 public var outcome: String?74 public var error: String?75 public var costUsd: Double?76 public var tokensIn: Int?77 public var tokensOut: Int?78 public var createdAt: Date?79 public var startedAt: Date?80 public var finishedAt: Date?81 /// Number of proposals…82 public var proposals: Int?83 /// …of which still waiting for a decision.84 public var pendingProposals: Int?85 public var toolCalls: Int?86}8788/// `GET /api/agents` — the catalogue, whether a run is possible, and the last executions. Calls no provider.89public struct AgentCatalogue: Codable, Sendable, Equatable {90 public var agents: [AgentInfo]91 /// A provider key is set on the server.92 public var configured: Bool?93 /// `nil` when not configured or when no enabled model supports tool use.94 public var target: AgentTarget?95 public var budgetNote: String?96 public var executions: [AgentExecutionSummary]97}9899/// Answer of `POST /api/agents` (201).100public struct AgentRunStarted: Codable, Sendable, Equatable, Identifiable {101 /// The execution: poll `agentExecution(id:)`.102 public var id: String103 public var status: String?104}105106/// One side of the before → after preview of a proposal (built by the server from the real data).107public struct AgentPreview: Codable, Sendable, Equatable {108 public var label: String?109 public var lines: [String]?110 public var markdown: String?111}112113/// The states of a proposal.114public enum AgentProposalStatus {115 public static let proposed = "proposed"116 public static let applied = "applied"117 public static let rejected = "rejected"118 public static let failed = "failed"119 public static let undone = "undone"120}121122/// A change proposed by an agent. Nothing is written until it is approved; an applied proposal can be undone.123/// Not observed on the scratch server: every field but `idx` optional.124public struct AgentProposal: Codable, Sendable, Equatable, Identifiable {125 /// Its index in the execution: what approve / reject / undo take.126 public var idx: Int127 public var tool: String?128 /// `inbox_triage`, `tags`, `new_page`, `page_edit`, `task`.129 public var kind: String?130 public var rationale: String?131 public var title: String?132 /// Needs `confirmDestructive: true` to be approved (a trash proposal).133 public var destructive: Bool?134 /// See `AgentProposalStatus`.135 public var status: String?136 public var pageId: String?137 public var before: AgentPreview?138 public var after: AgentPreview?139 /// The change itself, by kind (raw JSON).140 public var payload: RawJSON?141 public var at: Date?142 public var decidedAt: Date?143 public var appliedAt: Date?144 public var undoneAt: Date?145 public var error: String?146 /// What applying created (page id, task id…), raw.147 public var result: RawJSON?148149 public var id: Int { idx }150}151152/// One line of the execution log (ids, counts and enum values only — never note text).153public struct AgentToolStep: Codable, Sendable, Equatable {154 public var tool: String?155 public var input: RawJSON?156 public var output: RawJSON?157 public var at: Date?158 public var ms: Double?159 public var error: String?160 public var proposalIdx: Int?161}162163/// A page an execution read.164public struct AgentDocument: Codable, Sendable, Equatable, Identifiable {165 public var id: String166 public var title: String?167 public var icon: String?168 public var deletedAt: Date?169}170171/// `GET /api/agents/<id>` — one execution: live status, proposals, log, cost.172/// Not observed on the scratch server: every field but `id` optional.173public struct AgentExecution: Codable, Sendable, Equatable, Identifiable {174 public var id: String175 public var agent: String?176 public var agentName: String?177 public var agentIcon: String?178 public var info: AgentInfo?179 /// The fixed task text of the catalogue.180 public var task: String?181 public var model: String?182 /// See `AgentExecutionStatus`.183 public var status: String?184 public var scopes: [String]?185 public var outcome: String?186 public var result: String?187 public var error: String?188 /// The page given at launch (only while the run is pending).189 public var contextPageId: String?190 public var proposedChanges: [AgentProposal]?191 public var toolsInvoked: [AgentToolStep]?192 /// Ids of the pages read…193 public var documentsAccessed: [String]?194 /// …and their titles.195 public var documents: [AgentDocument]?196 /// The decisions taken (raw).197 public var approvals: [RawJSON]?198 public var costUsd: Double?199 public var tokensIn: Int?200 public var tokensOut: Int?201 public var createdAt: Date?202 public var startedAt: Date?203 public var finishedAt: Date?204205 public var isLive: Bool { status.map(AgentExecutionStatus.live.contains) ?? false }206 public var pendingProposals: [AgentProposal] { (proposedChanges ?? []).filter { $0.status == AgentProposalStatus.proposed } }207}208209/// Answer of approving or rejecting proposals. Not observed: `applied` / `failed` kept raw.210public struct AgentDecisionResult: Codable, Sendable, Equatable {211 /// The new status of the execution.212 public var status: String?213 public var applied: RawJSON?214 public var failed: RawJSON?215 /// Proposals still waiting.216 public var pending: Int?217}218219/// Answer of undoing applied proposals. Not observed: `undone` / `failed` kept raw.220public struct AgentUndoResult: Codable, Sendable, Equatable {221 public var status: String?222 public var undone: RawJSON?223 public var failed: RawJSON?224}225