SPB Git

Repository Public

AgentModels.swift 8.1 KB 225 lines swift

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
Files main
Menu

Theme