Gemma 4 26B-A4B inference in ~2 GB of RAM on any M-series MacBook
Swift apple-silicongemmagemma4gemma4-26b-a4bgpgpullmllm-inferencelocal-aimacosmetalon-device-aion-device-llmswift
import Foundation
import Synchronization
import TurboFieldfare
import TurboFieldfareRepackCore
import Observation
@MainActor
@Observable
public final class AppModel {
public enum RunState: Equatable {
case idle
case running
}
/// How a turn ended.
///
/// `committed` covers a reply that finished and a stop that landed at a
/// token boundary: both are in the KV and on disk. `rewound` is a turn the
/// runtime took back — a hard stop, a stream failure, a lost lineage — so
/// it is in neither, and its message goes back to the composer. The cause
/// is already in `error` by the time this is read.
private enum TurnOutcome {
case committed
case rewound
}
public let appDataDirectory: URL
public let isModelLocationOverridden: Bool
public private(set) var isModelChoiceRequired: Bool
public private(set) var settingsDiagnostic: String?
public let canResetSettings: Bool
public private(set) var isChangingModelLocation = false
public var existingModelReview: ExistingModelReview?
public private(set) var isInspectingModelLocation = false
public private(set) var modelLocationDiagnostic: String? {
didSet {
if let message = modelLocationDiagnostic {
error = .invalidRequest(message)
} else if let oldValue, error == .invalidRequest(oldValue) {
error = nil
}
}
}
private var settingsWritesAllowed: Bool
private var savedModelPath: String?
private var migratedHistorySources: [String]
public var modelPathText: String
public var promptText: String = ""
public private(set) var imageAttachments: [StagedImage] = []
public private(set) var imageAttachmentError: String?
private var visionAvailabilityAttachmentError: String?
/// A count, not a flag. The picker and a drop can both be staging at once,
/// and whichever finished first cleared a shared Bool — reopening `canRun`
/// while the other was still copying, so Generate ran against a partial set
/// and the remaining images were appended after the run had snapshotted its
/// own, where `removeImage` and `clearImages` are no-ops.
private var addingImagesCount = 0
public var isAddingImages: Bool { addingImagesCount > 0 }
/// Set by the Model menu's Remove Image Support item; the window presents
/// the confirmation.
public var isConfirmingVisionPackRemoval = false
public internal(set) var outputPromptText: String = ""
/// The newest turn's pictures, as the transcript draws them. A live turn's
/// are staged; a reopened conversation's newest pair is drawn from its
/// document, whose pictures the conversation store owns.
public internal(set) var outputImageAttachments: [ChatImage] = []
/// The open chat. The transcript renders it, and its turn order is what the
/// decode service's gate checks every turn against.
public internal(set) var conversation = AppConversation()
/// What the window is showing, and in what state. One value: the six
/// fields it replaces could disagree, and twelve defects were two of them
/// disagreeing.
var machine = ConversationScreenMachine()
public var screen: ConversationScreen { machine.screen }
/// The epoch the inference side has actually been told to open. Nil after a
/// load or unload, both of which rebuild or release the KV; the next turn
/// opens the conversation again before it sends anything.
var serviceEpoch: UUID?
public var outputText: String = ""
public var runState: RunState = .idle
public var runtimeOptions = AppRuntimeOptions()
public var maxNewTokensOverride: Int?
/// Settable only through `setMaxContextTokens`, because changing it changes
/// which stored conversations can be continued — and what is on screen has
/// to be redrawn from the answer that now applies, not the one taken when
/// the row was clicked.
public private(set) var maxContextTokens: Int = AppContextLengthOption.eightK.tokens {
didSet {
if maxContextTokens != oldValue { contextClampNotice = nil }
}
}
public private(set) var contextClampNotice: String?
public var temperature: Double = 0.2
public var topKEnabled: Bool = true
public var topK: Int = 64
public var topPEnabled: Bool = true
public var topP: Double = 0.95
public private(set) var newlineShortcut: AppNewlineShortcut = .return
public private(set) var showPromptExamples: Bool = true
public private(set) var textSize: AppTextSize = .standard
/// Whether the list of chats is showing. Persisted, so the window comes
/// back the way it was left.
public private(set) var isSidebarVisible: Bool = true
/// Whether the Inspector is showing. Persisted alongside the sidebar, for
/// the same reason: the window comes back the way it was left.
public private(set) var isInspectorVisible: Bool = true
/// Whether launching the app should load the model straight away. Off by
/// default, because loading takes minutes and holds gigabytes.
public private(set) var loadModelOnLaunch: Bool = false
public var diagnostics: AppDiagnostics?
public var error: AppInferenceError?
public var installState: AppModelInstallState = .idle
public private(set) var installETAPresentation: DownloadETAPresentation = .hidden
public private(set) var installETAText: String?
/// The companion download is 1.5 GB and deserves the same answer to "how
/// long is this going to take" as the model download. Kept separate because
/// both can be in flight in principle and an estimator holds per-download
/// rate state.
public private(set) var visionInstallETAPresentation: DownloadETAPresentation = .hidden
public private(set) var visionInstallETAText: String?
public private(set) var installReadiness: AppModelInstallReadiness = .checking
public internal(set) var installationStatus: AppModelInstallationStatus
public private(set) var modelStorageMetrics: AppModelStorageMetrics?
public private(set) var modelStorageMetricsError: String?
public var visionInstallState: AppModelInstallState = .idle
/// How far activation's hash of the companion weights has got, 0 to 1.
/// Activation reads about 1.5 GB, which was a bare spinner with no way to
/// tell a slow verify from a stuck one.
public private(set) var visionActivationProgress: Double?
public private(set) var visionInstallReadiness: AppModelInstallReadiness = .checking
public private(set) var visionInstallationStatus: AppVisionPackInstallationStatus
public var loadState: AppModelLoadState = .notLoaded
public private(set) var loadedRuntimeKey: AppLoadedRuntimeKey?
public internal(set) var phase: AppGenerationPhase = .idle
public private(set) var liveTokenCount: Int = 0
public private(set) var liveElapsedDecodeSeconds: Double = 0
public internal(set) var livePrefillDone: Int = 0
public internal(set) var livePrefillTotal: Int = 0
public private(set) var liveMemoryBytes: UInt64?
/// Resident bytes of the inference process. The footprint above is what
/// the system counts against the process; this is what it actually holds,
/// including the mapped weights the footprint omits. A 26B model reports
/// about 160 MB of footprint right after loading, which is true and reads
/// as nonsense without this beside it.
public private(set) var liveResidentBytes: UInt64?
/// Tower weights the inference process is holding mapped, reported
/// separately because no per-process counter attributes them.
public private(set) var visionTowerMappedBytes: UInt64?
public private(set) var isCancellationPending: Bool = false
/// Increments when a generation starts. The transcript watches it to put
/// the newest turn on screen: with several images attached, the prompt and
/// its thumbnails are tall enough to push the answer out of view, so
/// scrolling only when the reader was already at the bottom left them
/// looking at their own attachments while the model worked.
public private(set) var runIdentity: Int = 0
let client: any AppInferenceClient
private let installer: any AppModelInstallerClient
private let visionInstaller: any AppVisionPackInstallerClient
/// The message currently on its way through the send pipeline, from the
/// click to the commit or the hand-back. `isTurnInFlight` reads it, so a
/// second Generate is refused for the whole journey and not only while the
/// runtime is generating.
private var sendTask: Task<Void, Never>?
private var loadTask: Task<Void, Never>?
private var installTask: Task<Void, Never>?
private var visionInstallTask: Task<Void, Never>?
private var unloadTask: Task<Void, Never>?
private var loadGeneration: UInt64 = 0
/// The highest load-phase sequence already applied. Each `onState` callback
/// hops to the main actor in its own task, and ordering between separately
/// created tasks is not guaranteed, so `.ready` could be applied before the
/// `.loading(.preparingRunner)` that preceded it and leave the UI showing a
/// phase the runtime had already left.
private var appliedLoadSequence: UInt64 = 0
private var unloadGeneration: UInt64 = 0
private var installGeneration: UInt64 = 0
private var visionInstallGeneration: UInt64 = 0
private var visionInstallCancellationRequested = false
private var pendingExplicitLoadRuntimeKey: AppLoadedRuntimeKey?
private var activeRunRuntimeKey: AppLoadedRuntimeKey?
private var hasHandledTerminalEvent = false
private var hasShutDownForTermination = false
/// What the generation stage left behind, read by the stage that decides
/// whether the message is committed or goes back to the composer.
private var turnOutcome: TurnOutcome = .committed
/// The send waiting for its turn to end, with the run it belongs to.
private var turnCompletion:
(generation: Int, continuation: CheckedContinuation<Void, Never>)?
private let memorySampler: AppMemorySampler
let settingsPersistenceEnabled: Bool
private let installETAClock: SuspendingClock
private let installETAOrigin: SuspendingClock.Instant
private var installETAEstimator = DownloadETAEstimator()
private var visionInstallETAEstimator = DownloadETAEstimator()
/// Internal rather than private: the history extension releases the staged
/// copies of a conversation the KV is giving up, and lives in another file.
let attachmentStore: AppImageAttachmentStore
/// What this Mac has, injected so the admission rule is testable without a
/// machine of that size. Read once: `physicalMemory` cannot change under a
/// running process, and re-reading it per query would make the menu, the
/// clamp and the load refusal three separate answers.
private let hostMemoryBytes: UInt64
public let isVisionRuntimeSupported: Bool
/// The stored conversations and which one is open.
public let history = ConversationHistoryState()
/// Nil when history is off for this instance — the tests that drive the
/// model without a disk do exactly that, and so does a run with settings
/// persistence disabled, which is the same "do not touch the user's files"
/// switch.
var conversationBinding: ConversationStoreBinding?
var conversationStore: ConversationStore? { conversationBinding?.store }
/// The directory the open chat is being written to. Created on the first
/// send rather than at New Chat, so an empty chat never lands on disk.
var storedConversationID: UUID?
/// Read from the installed model's manifest, because the app process never
/// loads the model. Nil until a model is installed.
var conversationIdentity: ConversationIdentity? {
get { conversationBinding?.identity }
set { conversationBinding?.identity = newValue }
}
var conversationBindingGeneration: UInt64 = 0
let conversationIdentityProvider: @Sendable (URL) throws -> ConversationIdentity
let conversationStoreProvider: @Sendable (URL) -> ConversationStore
var pendingServiceRecoveryConversationID: UUID?
/// Stored copies of the in-flight turn's images, written while the model is
/// generating so the wait is not paid twice.
var pendingTurnImageWrite: Task<TurnImageWriteOutcome, Never>?
var persistenceTail: Task<Void, Never>?
/// Reserves deletion across the persistence wait and the store actor hop.
var conversationDeletionTask: Task<Void, Never>?
var quarantinedPersistenceLineages: Set<PersistenceLineageKey> = []
/// Why the store last refused to do something. Names, counts and paths
/// only: a diagnostic carrying transcript text would put the user's
/// conversation wherever this is collected.
public internal(set) var historyDiagnostic: String?
public static var currentDeviceSupportsVisionRuntime: Bool {
VisionRuntime.isSupportedOnDefaultDevice
}
public init(modelDirectory: URL? = nil,
appDataDirectory: URL? = nil,
environment: [String: String] = ProcessInfo.processInfo.environment,
client: any AppInferenceClient = RealInferenceClient(),
installer: any AppModelInstallerClient = RepackModelInstallerClient(),
visionInstaller: any AppVisionPackInstallerClient = RepackVisionPackInstallerClient(),
memorySampler: AppMemorySampler = AppMemorySampler(),
attachmentStore: AppImageAttachmentStore = AppImageAttachmentStore(),
visionRuntimeSupported: Bool = true,
settingsPersistenceEnabled: Bool = false,
conversationIdentityProvider: @escaping @Sendable (URL) throws -> ConversationIdentity = {
try ConversationIdentity.forModelDirectory($0)
},
conversationStoreProvider: @escaping @Sendable (URL) -> ConversationStore = {
ConversationStore(rootURL: $0)
},
hostMemoryBytes: UInt64 = ContextAdmission.hostMemoryBytes) {
let dataRoot = AppDataLocation.resolve(explicitURL: appDataDirectory, environment: environment)
let defaultModel = environment["TURBO_FIELDFARE_APP_DATA_PATH"] != nil
? dataRoot.appendingPathComponent("gemma4.gturbo", isDirectory: true)
: AppModelLocation.defaultURL(environment: environment)
let legacy = (modelDirectory ?? defaultModel).standardizedFileURL
let bootstrap = AppDataBootstrap(root: dataRoot, legacyModel: legacy,
environment: environment, modelOverride: modelDirectory != nil, enabled: settingsPersistenceEnabled)
let settings = bootstrap.settings
let directory: URL
if let modelDirectory { directory = modelDirectory.standardizedFileURL }
else if let override = environment["TURBO_FIELDFARE_MODEL_PATH"], !override.isEmpty {
directory = URL(fileURLWithPath: override, isDirectory: true).standardizedFileURL
} else if let saved = settings.selectedModelPath {
directory = URL(fileURLWithPath: saved, isDirectory: true).standardizedFileURL
} else { directory = defaultModel.standardizedFileURL }
self.appDataDirectory = dataRoot
self.isModelLocationOverridden = modelDirectory != nil || !(environment["TURBO_FIELDFARE_MODEL_PATH"] ?? "").isEmpty
self.isModelChoiceRequired = bootstrap.modelChoiceRequired
self.settingsDiagnostic = bootstrap.failure
self.canResetSettings = settingsPersistenceEnabled && bootstrap.canResetSettings
self.settingsWritesAllowed = bootstrap.failure == nil
self.savedModelPath = settings.selectedModelPath
self.migratedHistorySources = settings.migratedHistorySources
let installETAClock = SuspendingClock()
self.modelPathText = directory.path
// The app always releases the image tower after each image. Keeping it
// resident saves a few hundred milliseconds on a run of images and
// holds about 1 GB of page cache to do it — a trade worth exposing to
// a CLI or server operator, not to someone using the app, where it was
// one more setting whose effect no figure on screen could show.
// `keepReady` remains available through AppRuntimeOptions for those.
self.runtimeOptions = AppRuntimeOptions(
expertCacheSlots: settings.expertCacheSlots,
prefillEnabled: settings.prefillEnabled,
rdadvisePolicy: settings.rdadvisePolicy,
visionResidencyPolicy: .onDemand)
let admitted = Self.admittedContext(settings.contextTokens,
hostMemoryBytes: hostMemoryBytes,
expertCacheSlots: settings.expertCacheSlots)
self.maxContextTokens = admitted.tokens
self.contextClampNotice = admitted.notice
self.temperature = settings.temperature
self.topKEnabled = settings.topKEnabled
self.topK = settings.topK
self.topPEnabled = settings.topPEnabled
self.topP = settings.topP
self.newlineShortcut = settings.newlineShortcut
self.showPromptExamples = settings.showPromptExamples
self.textSize = settings.textSize
self.isSidebarVisible = settings.sidebarVisible
self.isInspectorVisible = settings.inspectorVisible
self.loadModelOnLaunch = settings.loadModelOnLaunch
self.installationStatus = AppModelInstallationProbe.status(at: directory)
self.visionInstallationStatus = AppVisionPackInstallationProbe.status(at: directory)
self.client = client
self.installer = installer
self.visionInstaller = visionInstaller
self.memorySampler = memorySampler
self.attachmentStore = attachmentStore
self.hostMemoryBytes = hostMemoryBytes
self.isVisionRuntimeSupported = visionRuntimeSupported
self.settingsPersistenceEnabled = settingsPersistenceEnabled
self.conversationIdentityProvider = conversationIdentityProvider
self.conversationStoreProvider = conversationStoreProvider
self.installETAClock = installETAClock
self.installETAOrigin = installETAClock.now
// History follows the same switch as settings: a model driven by tests
// must not write to the user's Application Support directory.
if settingsPersistenceEnabled {
conversationBindingGeneration = 1
let identity: ConversationIdentity?
if installationStatus == .complete {
do {
identity = try conversationIdentityProvider(directory)
} catch {
identity = nil
historyDiagnostic = "the installed model identity could not be read: \(error)"
}
} else {
identity = nil
}
conversationBinding = ConversationStoreBinding(
modelDirectory: directory,
appDataDirectory: dataRoot,
identity: identity,
generation: conversationBindingGeneration,
storeProvider: conversationStoreProvider)
} else {
conversationBinding = nil
}
// Staged images of runs that were killed before they could clean up;
// nothing else ever removes them.
AppImageAttachmentStore.sweepAbandoned()
refreshInstallReadiness()
refreshVisionInstallReadiness()
activateConversationStore()
}
/// What the Context picker may offer on this Mac.
public var contextOptions: [AppContextLengthOption] {
AppContextLengthOption.available(on: hostMemoryBytes, expertCacheSlots: runtimeOptions.expertCacheSlots)
}
/// The caption under the Context picker when admission is hiding rows.
///
/// Static and free of SwiftUI so the sentence a user reads is covered by a
/// test rather than by looking at the window. Nil when every size is
/// offered — there is then nothing to explain.
public nonisolated static func contextOptionsNote(hostMemoryBytes: UInt64, expertCacheSlots: Int = 16) -> String? {
let hidden = AppContextLengthOption.allCases.filter {
$0.availability(hostMemoryBytes: hostMemoryBytes, expertCacheSlots: expertCacheSlots) != .available
}
guard !hidden.isEmpty else { return nil }
return hidden
.map { $0.needDescription(hostMemoryBytes: hostMemoryBytes, expertCacheSlots: expertCacheSlots) }
.joined(separator: " ")
}
public var contextOptionsNote: String? {
Self.contextOptionsNote(hostMemoryBytes: hostMemoryBytes, expertCacheSlots: runtimeOptions.expertCacheSlots)
}
/// A stored context this host cannot back, replaced with the largest it
/// can plus the sentence that says so.
///
/// Not a cosmetic correction: `beginLoad` refuses an unbacked context
/// before it allocates, so leaving the stored value in place would open
/// the app on a setting whose every load fails.
nonisolated static func admittedContext(
_ tokens: Int,
hostMemoryBytes: UInt64,
expertCacheSlots: Int = 16
) -> (tokens: Int, notice: String?) {
let config = ArchConfig.gemma4_26B_A4B
guard case .needsMemory = ContextAdmission.availability(
config: config, maxContext: tokens, hostMemoryBytes: hostMemoryBytes, expertCacheSlots: expertCacheSlots) else {
return (tokens, nil)
}
let fallback = AppContextLengthOption.largestAvailable(on: hostMemoryBytes, expertCacheSlots: expertCacheSlots)
let need = ContextAdmission.needDescription(config: config,
maxContext: tokens,
hostMemoryBytes: hostMemoryBytes, expertCacheSlots: expertCacheSlots)
return (fallback.tokens,
"\(need) Context is set to \(fallback.shortLabel) instead.")
}
public var isRunning: Bool { runState == .running }
public var isModelAvailable: Bool { loadState.isReady }
public var hasStaleLoadedRuntime: Bool {
guard loadState.isReady, let loadedRuntimeKey else { return false }
return loadedRuntimeKey != currentRuntimeKey
}
// The three lifecycle actions gate on the whole send, not on `isRunning`:
// a deferred replay is a full prefill during which no turn is generating
// yet, and an unload taken then dropped the KV under the replay, lost the
// message it was carrying, and queued behind the prefill on the service
// until the load timeout killed the connection.
public var canLoadModel: Bool {
if isChangingModelLocation || isModelChoiceRequired { return false }
return isModelInstalled && !isTurnInFlight && !isVisionFilesystemMutationInProgress
&& (loadState == .notLoaded || loadState.isFailed)
}
public var canCancelLoad: Bool {
if case .loading = loadState { return loadTask != nil }
return false
}
public var canReloadModel: Bool {
!isChangingModelLocation && isModelInstalled && !isTurnInFlight && !isVisionFilesystemMutationInProgress
&& loadState.isReady && hasStaleLoadedRuntime
}
public var canUnloadModel: Bool {
!isChangingModelLocation && isModelInstalled && !isTurnInFlight && !isVisionFilesystemMutationInProgress
&& loadState.isReady
}
public var isModelInstalled: Bool { installationStatus == .complete }
public var requiresModelInstallation: Bool { !isModelInstalled }
public var installDescriptor: AppModelInstallDescriptor { installer.descriptor }
public var installRequirement: AppModelInstallRequirement? {
installReadiness.requirement
}
public var isInstallingModel: Bool { installState.isInstalling }
public var canInstallModel: Bool {
if isChangingModelLocation || isModelChoiceRequired || !isModelLocationAvailable { return false }
guard case .ready = installReadiness else { return false }
return !isRunning && !loadState.isLoading && !isInstallingModel
&& !isVisionCompanionOperationInProgress
&& requiresModelInstallation
}
public var canCancelInstall: Bool { installState.canCancel }
public var isVisionPackInstalled: Bool { visionInstallationStatus == .complete }
public var isInstallingVisionPack: Bool { visionInstallState.isInstalling }
public var visionInstallDescriptor: AppModelInstallDescriptor {
visionInstaller.descriptor
}
/// Any companion operation currently owns the installer transaction.
public var isVisionCompanionOperationInProgress: Bool {
visionInstallState.isInstalling
}
public var isVisionFilesystemMutationInProgress: Bool {
switch visionInstallState {
case .activating, .discarding: return true
default: return false
}
}
/// Pack activation, repair and removal mutate the runtime's files and need
/// an unloaded model. Payload download does not use this gate.
public var canBeginVisionCompanionOperation: Bool {
!isChangingModelLocation && !isRunning && !loadState.isLoading && !loadState.isReady
&& !isInstallingModel && !isVisionCompanionOperationInProgress
}
private var canBeginVisionDownload: Bool {
!isRunning && !loadState.isLoading && !isInstallingModel
&& !isVisionCompanionOperationInProgress
}
public var canInstallVisionPack: Bool {
if isChangingModelLocation { return false }
guard isVisionRuntimeSupported else { return false }
// A layout with nowhere to put a companion cannot be repaired by
// downloading one, so do not offer to.
guard visionInstallationStatus != .unsupportedLayout else { return false }
guard isModelInstalled, !isVisionPackInstalled,
case .ready = visionInstallReadiness else { return false }
if case .readyToActivate = visionInstallState { return false }
return canBeginVisionDownload
}
public var canActivateVisionPack: Bool {
guard isVisionRuntimeSupported else { return false }
guard case .readyToActivate = visionInstallState else { return false }
return canBeginVisionCompanionOperation
}
public var canCancelVisionInstall: Bool { visionInstallState.canCancel }
public var visionInstallProgressFraction: Double? {
// Activation hashes about 1.5 GB, so it gets a bar of its own rather
// than an indeterminate spinner for minutes.
if case .activating = visionInstallState { return visionActivationProgress }
guard case .copyingPayload(let reused, let downloaded, let total) = visionInstallState,
total > 0 else { return nil }
let addition = reused.addingReportingOverflow(downloaded)
let done = addition.overflow ? UInt64.max : addition.partialValue
return min(max(Double(done) / Double(total), 0), 1)
}
public var visionInstallPhaseLabel: String {
switch visionInstallState {
case .idle: return isVisionPackInstalled ? "Installed" : "Not installed"
case .checking: return "Checking image support"
case .downloadingMetadata: return "Downloading metadata"
case .planning: return "Planning image support"
case .reservingOutput: return "Reserving storage"
case .copyingPayload: return "Downloading image support"
case .hashingOutput(let file): return "Verifying \(file)"
case .finalizing: return "Finalizing download"
case .activating:
guard let fraction = visionActivationProgress else {
return "Activating image support"
}
return "Verifying image support \(Int(fraction * 100))%"
case .cancelling: return "Cancelling"
case .discarding: return "Cleaning up"
case .cancelled: return "Download paused"
case .readyToActivate: return "Ready to activate"
case .recoverable: return "Saved download needs attention"
case .installed: return "Installed"
case .failed: return "Installation failed"
}
}
public var installDownloadedBytes: UInt64? {
guard case .copyingPayload(let reused, let downloaded, let total) = installState else {
return nil
}
return min(reused.addingReportingOverflow(downloaded).partialValue, total)
}
public var installTotalBytes: UInt64? {
guard case .copyingPayload(_, _, let total) = installState else {
return nil
}
return total
}
public var installReusedBytes: UInt64? {
guard case .copyingPayload(let reused, _, _) = installState else {
return nil
}
return reused
}
public var installDownloadedThisRunBytes: UInt64? {
guard case .copyingPayload(_, let downloaded, _) = installState else {
return nil
}
return downloaded
}
public var installProgressFraction: Double? {
guard case .copyingPayload(let reused, let downloaded, let total) = installState,
total > 0 else {
return nil
}
let addition = reused.addingReportingOverflow(downloaded)
let done = addition.overflow ? UInt64.max : addition.partialValue
return min(max(Double(done) / Double(total), 0), 1)
}
public var installPhaseLabel: String {
switch installState {
case .idle: return "Model required"
case .checking: return "Checking installation"
case .downloadingMetadata: return "Downloading metadata"
case .planning: return "Planning installation"
case .reservingOutput: return "Reserving storage"
case .copyingPayload: return "Downloading model"
case .hashingOutput(let file): return "Verifying \(file)"
case .finalizing: return "Finalizing installation"
case .activating:
guard let fraction = visionActivationProgress else {
return "Activating image support"
}
return "Verifying image support \(Int(fraction * 100))%"
case .cancelling: return "Cancelling"
case .discarding: return "Discarding download"
case .cancelled: return "Download paused"
case .readyToActivate: return "Ready to activate"
case .recoverable: return "Saved download needs attention"
case .installed: return "Model installed"
case .failed: return "Installation failed"
}
}
public var canRun: Bool {
if isChangingModelLocation { return false }
// Staging copies the files a request will carry. Starting a run while
// it is in flight sent a request without those images and then landed
// them on the next message instead.
// A deferred replay is not `isRunning` — no turn is generating yet —
// but the message has been sent and the lineage it will be stamped
// against does not exist yet. Without this a second Generate started a
// second replay, and whichever finished last defined the epoch, so the
// first one's request came back rejected as belonging to a conversation
// that was no longer open.
return !isTurnInFlight && conversationDeletionTask == nil
&& !isAddingImages && isModelAvailable && !loadState.isLoading
&& !isVisionFilesystemMutationInProgress
&& !hasStaleLoadedRuntime
// A conversation whose KV no longer matches it cannot take another
// turn; only New chat clears that.
&& conversation.canSend
// And the conversation on screen has to be one a message can go
// to. The live one always is; a stored row only when the notice
// says it can be continued. Asking only `conversation.canSend`
// let a row the notice had refused be sent anyway.
&& screen.allowsSend
&& (!promptText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
|| !imageAttachments.isEmpty)
&& (imageAttachments.isEmpty || isImageInputAvailable)
}
public var canCancel: Bool { isRunning && !isCancellationPending }
/// The message has been sent and nothing has come back yet.
///
/// Wider than `isRunning`, which covers only a generation: a reopened
/// conversation has to be replayed into the KV first, and that is a full
/// prefill of everything it holds. For the length of it the window showed a
/// composer that had been emptied and a transcript that had not changed, so
/// the app looked like it had dropped the message.
public var isTurnInFlight: Bool {
isRunning || screen.isReplaying || sendTask != nil
}
/// Activity whose prompt/output has been published to the transcript.
/// A queued send owns the composer before replacing the previous answer.
public var isTranscriptTurnInFlight: Bool {
isRunning || screen.isReplaying
}
public var hasOutputTranscript: Bool {
// Keep the transcript layout during a disk read; a missing document
// is still loading, not an empty chat. Never borrow the held chat's turns.
switch screen {
case .reading(_, let document, _, _), .replaying(_, let document, _, _):
return document == nil || !transcriptHistory.isEmpty
case .live, .unreadable:
return !conversation.outOfContextPairs.isEmpty
|| !conversation.isEmpty
|| !outputPromptText.isEmpty || !outputImageAttachments.isEmpty
|| !outputText.isEmpty
}
}
public var shouldShowPromptExamples: Bool {
showPromptExamples
&& promptText.isEmpty
&& !isRunning
&& !hasOutputTranscript
}
public var outputResponsePlainText: String {
// The mailbox wins only when it has something to say. `??` alone fell
// back to `outputText` when the mailbox was *absent*, never when it was
// merely empty — so a reopened conversation, whose newest reply is put
// straight into `outputText` with the mailbox freshly reset, drew an
// "Answer" heading with nothing under it. During a run the two agree,
// and a genuinely empty reply is empty either way.
let streamed = generationTranscriptMailbox?.completeText ?? ""
return streamed.isEmpty ? outputText : streamed
}
/// Completed turns the transcript draws *above* the live one.
///
/// The live fields keep holding the last finished turn between runs — that
/// is what leaves an answer on screen after it ends — so while nothing is
/// decoding the newest pair is drawn live and must not also appear here.
/// One property, used by both the transcript and Copy Conversation, so the
/// two cannot disagree about which turn is which.
/// The chat on screen is not the one the KV is holding.
public var isShowingStoredCopy: Bool { screen.isShowingStoredCopy }
/// The state of the conversation on screen. `.continuable` for a live chat
/// and for one being replayed; the other two say why the composer is
/// closed.
public var openedConversationState: ConversationContinuability {
switch screen {
case .live, .replaying:
return .continuable
case .reading(_, _, let state, _):
return state
case .unreadable:
// Nothing to put back and nothing to read: the same dead end as a
// record with no tokens, and the notice says the same thing.
return .cannotReplay(reason: .tokenCountUnknown)
}
}
/// Whether the live fields belong under what is on screen.
///
/// While a stored copy is merely being read they do not: they hold the chat
/// the KV is keeping, which is a different conversation. But a send starts
/// by replaying the chat being read, and for that stretch the live fields
/// hold the message that started it — so suppressing them there drew an
/// "Answer / Processing your prompt" with no question above it.
public var showsLiveTurn: Bool { isTranscriptTurnInFlight || !isShowingStoredCopy }
/// What the transcript is drawing, as an identity the incremental renderer
/// can key on.
///
/// The renderer appends and cannot take pairs back, so it has to be told
/// when the thing on screen is a different conversation. The live
/// conversation's epoch used to be enough because every open started a new
/// one; now that browsing leaves the lineage alone, going out to a stored
/// copy and back would be two changes the epoch cannot express, and the
/// chat that was read stayed on screen under the row that was returned to.
public var displayedTranscriptID: UUID {
switch screen {
case .live, .unreadable:
return conversation.epoch
case .reading(_, _, _, let renderID):
return renderID
case .replaying(_, _, _, let renderID):
return renderID
}
}
public var transcriptHistory: [(user: AppChatTurn, assistant: AppChatTurn)] {
// A stored conversation draws in full: its pairs are not
// `completedPairs`, so none of them is being held back for the live
// fields to draw — and the live conversation belongs to another chat.
switch screen {
case .reading, .replaying:
return screen.document?.pairs ?? []
case .live, .unreadable:
let pairs = conversation.completedPairs
let live = conversation.hasTurnInFlight ? pairs
: (pairs.isEmpty ? pairs : Array(pairs.dropLast()))
return conversation.outOfContextPairs + live
}
}
/// Where the transcript draws "earlier turns are no longer in context",
/// counted in pairs from the top. Nil when everything on screen is still in
/// the model's context.
///
/// A fact about the live conversation, so it is drawn only under one: a
/// stored copy read off disk is not in the model's context at all, and a
/// rule under every turn of it says nothing a reader can act on.
public var transcriptContextBreak: Int? {
switch screen {
case .reading, .replaying:
return nil
case .live, .unreadable:
return conversation.outOfContextPairs.isEmpty
? nil : conversation.outOfContextPairs.count
}
}
public var outputConversationPlainText: String {
var history: [String] = []
for pair in transcriptHistory {
var prompt = pair.user.text
if !pair.user.images.isEmpty {
let names = pair.user.images.map(\.displayName).joined(separator: ", ")
prompt = prompt.isEmpty ? "[images: \(names)]" : "[images: \(names)]\n\(prompt)"
}
history.append("You:\n\(prompt)")
history.append("Answer:\n\(pair.assistant.text)")
}
let live = liveConversationPlainText
if history.isEmpty { return live }
if live.isEmpty { return history.joined(separator: "\n\n") }
return history.joined(separator: "\n\n") + "\n\n" + live
}
private var liveConversationPlainText: String {
let response = outputResponsePlainText
switch (outputPromptText.isEmpty, response.isEmpty) {
case (true, true):
return ""
case (false, true):
return "You:\n\(outputPromptText)"
case (true, false):
return "Answer:\n\(response)"
case (false, false):
return "You:\n\(outputPromptText)\n\nAnswer:\n\(response)"
}
}
public var liveTokensPerSecond: Double {
liveElapsedDecodeSeconds > 0 ? Double(liveTokenCount) / liveElapsedDecodeSeconds : 0
}
public var presentation: AppPresentationState {
AppPresentationState.resolve(AppPresentationSnapshot(
requiresInstallation: requiresModelInstallation,
installState: installState,
installReadiness: installReadiness,
loadState: loadState,
hasStaleRuntime: hasStaleLoadedRuntime,
isRunning: isTurnInFlight,
isGenerationCancellationPending: isCancellationPending,
generationPhase: phase,
livePrefillDone: livePrefillDone,
livePrefillTotal: livePrefillTotal,
lastStopReason: diagnostics?.stopReason,
isVisionFilesystemMutationInProgress: isVisionFilesystemMutationInProgress))
}
public var currentProcessMemoryBytes: UInt64? {
guard loadState.isReady || isRunning else { return nil }
// `liveMemoryBytes` first because it is a tracked property: reading the
// reporter alone told the truth but was invisible to observation, so
// the figure only refreshed when something else — a generated token —
// happened to redraw the view. Through prefill, nothing did.
if let liveMemoryBytes { return liveMemoryBytes }
// When inference runs in another process, its memory is the only
// memory worth showing. Falling back to this app's own sampler put the
// UI's footprint in a row labelled as the model's.
if let reporter = client as? any AppInferenceMemoryReporting {
return reporter.currentInferenceMemoryBytes
}
return memorySampler.sample()
}
public var generationTranscriptMailbox: GenerationTranscriptMailbox? {
(client as? any AppInferenceTranscriptReporting)?.generationTranscriptMailbox
}
private var currentRuntimeKey: AppLoadedRuntimeKey {
AppLoadedRuntimeKey(modelDirectory: URL(fileURLWithPath: modelPathText),
maxContextTokens: maxContextTokens,
options: runtimeOptions,
forceLogitsHead: currentForceLogitsHead)
}
private var currentForceLogitsHead: Bool {
temperature != 0
}
public var isModelLocationAvailable: Bool {
AppModelLocation.isVolumeAvailable(for: URL(fileURLWithPath: modelPathText))
}
public var canChangeModelLocation: Bool {
!isModelLocationOverridden && settingsWritesAllowed && !isChangingModelLocation && !isInspectingModelLocation
&& !isTurnInFlight && !isInstallingModel && !isVisionCompanionOperationInProgress
&& loadTask == nil && unloadTask == nil && !loadState.isLoading && !isAddingImages
&& conversationDeletionTask == nil
}
public enum ModelLocationIntent: Sendable { case download, existing }
public func reviewExistingModelLocation(_ folder: URL) async {
guard canChangeModelLocation, existingModelReview == nil else { return }
isInspectingModelLocation = true
do {
let review = try await Task.detached { try ExistingModelSelection.inspect(folder) }.value
isInspectingModelLocation = false
guard canChangeModelLocation else {
modelLocationDiagnostic = "The model became busy. Try choosing the folder again when it finishes."
return
}
let valid = review.candidates.filter(\.canSelect)
guard !valid.isEmpty else {
let reasons = review.candidates.map { "\($0.textURL.lastPathComponent): \($0.textSummary)" }
modelLocationDiagnostic = "No usable text model found. " + reasons.joined(separator: "\n")
return
}
modelLocationDiagnostic = nil
if valid.count == 1 {
await selectModelLocation(valid[0].textURL, intent: .existing)
} else {
existingModelReview = review
}
} catch {
isInspectingModelLocation = false
modelLocationDiagnostic = "Could not inspect model folder: \(error)"
}
}
public func confirmExistingModelSelection(_ candidate: ExistingModelCandidate) async -> Bool {
guard canChangeModelLocation, let review = existingModelReview,
review.candidates.contains(candidate), candidate.canSelect else { return false }
do {
let current = try ExistingModelSelection.candidate(at: candidate.textURL)
guard current == candidate else {
existingModelReview = try ExistingModelSelection.inspect(review.folder)
modelLocationDiagnostic = "The model files changed while you were choosing. Review their status again."
return false
}
await selectModelLocation(candidate.textURL, intent: .existing)
guard modelLocationDiagnostic == nil,
AppModelLocation.canonicalURL(URL(fileURLWithPath: modelPathText)) == candidate.textURL else { return false }
existingModelReview = nil
return true
} catch {
modelLocationDiagnostic = "Could not select model: \(error)"
return false
}
}
public func selectModelLocation(_ url: URL, intent: ModelLocationIntent) async {
guard canChangeModelLocation else { return }
let candidate = intent == .download
? url.appendingPathComponent("gemma4.gturbo", isDirectory: true) : url
do {
try AppModelLocation.validate(candidate, intent: intent)
modelLocationDiagnostic = nil
await changeModelURL(candidate, persistSelection: true)
} catch {
modelLocationDiagnostic = "Could not select model location: \(error)"
}
}
/// Internal callers already validated their candidate; UI uses selectModelLocation.
public func setModelURL(_ url: URL) async {
guard !isTurnInFlight && !isInstallingModel && !isVisionCompanionOperationInProgress
&& loadTask == nil && unloadTask == nil && !loadState.isLoading
&& conversationDeletionTask == nil && !isChangingModelLocation else { return }
await changeModelURL(url, persistSelection: !isModelLocationOverridden)
}
private func changeModelURL(_ url: URL, persistSelection: Bool) async {
let directory = AppModelLocation.canonicalURL(url)
let sameDirectory = directory.path == AppModelLocation.canonicalURL(URL(fileURLWithPath: modelPathText)).path
let needsSelectionCommit = persistSelection && settingsPersistenceEnabled && savedModelPath == nil
guard !sameDirectory || needsSelectionCommit || isModelChoiceRequired else {
recheckModelAtCurrentLocation()
return
}
isChangingModelLocation = true
defer { isChangingModelLocation = false }
guard await awaitPendingPersistence(timeout: .seconds(30)) else {
modelLocationDiagnostic = "Pending chat writes did not settle. Retry when saving finishes."
return
}
if persistSelection, settingsPersistenceEnabled {
do {
var settings = currentSettings()
settings.selectedModelPath = directory.path
try MacAppSettingsFileStore.save(settings, at: AppDataLocation.settingsURL(in: appDataDirectory))
savedModelPath = directory.path
settingsDiagnostic = nil
} catch {
modelLocationDiagnostic = "Could not save model location; previous selection retained: \(error)"
return
}
}
// A rejected settings write must leave the active runtime and chat intact.
if let lifecycle = client as? AppModelLifecycleClient { await lifecycle.unload() }
loadedRuntimeKey = nil
loadState = .notLoaded
endConversationForReleasedKV()
modelPathText = directory.path
runIdentity &+= 1
isModelChoiceRequired = false
clearImages()
loadGeneration &+= 1
installGeneration &+= 1
visionInstallGeneration &+= 1
installState = .idle
visionInstallState = .idle
resetInstallETA()
diagnostics = nil
error = nil
phase = .idle
modelLocationDiagnostic = nil
installationStatus = AppModelInstallationProbe.status(at: directory)
visionInstallationStatus = AppVisionPackInstallationProbe.status(at: directory)
refreshInstallReadiness()
refreshVisionInstallReadiness()
replaceConversationBinding(for: directory, reason: "the model location changed")
}
public func importLegacyHistory(from modelDirectory: URL) async {
guard canChangeModelLocation, let store = conversationStore else { return }
isChangingModelLocation = true
defer { isChangingModelLocation = false }
guard await awaitPendingPersistence(timeout: .seconds(30)) else {
modelLocationDiagnostic = "Pending chat writes did not settle. Retry when saving finishes."
return
}
let source = ConversationStoreLocation.url(forModelDirectory: modelDirectory)
do {
try await store.importLegacyHistory(from: source)
if !migratedHistorySources.contains(source.path) { migratedHistorySources.append(source.path) }
persistSettings()
await refreshHistory()
} catch { modelLocationDiagnostic = "Could not import history: \(error)" }
}
public func resetSettingsAfterBackingUp() {
guard canResetSettings else { return }
do {
let url = AppDataLocation.settingsURL(in: appDataDirectory)
if FileManager.default.fileExists(atPath: url.path) {
try FileManager.default.copyItem(at: url, to: url.appendingPathExtension("backup-" + UUID().uuidString))
}
try MacAppSettingsFileStore.save(currentSettings(), at: url)
settingsWritesAllowed = true
settingsDiagnostic = nil
} catch { settingsDiagnostic = "Could not recover settings: \(error)" }
}
public func loadModel() {
guard canLoadModel else { return }
beginLoad()
}
public func perform(_ action: AppModelAction) {
switch action {
case .install: installModel()
case .cancelInstall: cancelInstall()
case .load, .retryLoad: loadModel()
case .cancelLoad: cancelLoad()
case .reload: reloadModel()
case .unload: unloadModel()
}
}
public func setNewlineShortcut(_ shortcut: AppNewlineShortcut) {
guard newlineShortcut != shortcut else { return }
newlineShortcut = shortcut
persistSettings()
}
public func setTextSize(_ size: AppTextSize) {
guard textSize != size else { return }
textSize = size
persistSettings()
}
public func setShowPromptExamples(_ show: Bool) {
guard showPromptExamples != show else { return }
showPromptExamples = show
persistSettings()
}
public func setExpertCacheSlots(_ slots: Int) {
guard runtimeOptions.expertCacheSlots != slots else { return }
runtimeOptions.expertCacheSlots = slots
let admitted = Self.admittedContext(maxContextTokens,
hostMemoryBytes: hostMemoryBytes,
expertCacheSlots: slots)
if admitted.tokens != maxContextTokens {
setMaxContextTokens(admitted.tokens)
contextClampNotice = admitted.notice
}
persistSettings()
}
/// Changes the context, and redraws a stored conversation against it.
///
/// Continuability is a function of the conversation's size and the context
/// in force, and the window took its answer once, when the row was clicked.
/// So raising the context from the notice left the chat continuable but
/// still drawn read-only, under a boundary rule saying earlier turns were
/// out of context when they no longer were. Re-opening rebuilds it from the
/// state that now applies, in both directions.
public func setMaxContextTokens(_ tokens: Int) {
guard maxContextTokens != tokens else { return }
maxContextTokens = tokens
persistSettings()
guard !isRunning, !screen.isReplaying,
let id = screen.conversationID,
let meta = history.entry(id) else { return }
perform(machine.apply(.contextChanged(
state: continuability(of: meta),
heldID: storedConversationID,
kvMatchesHeld: serviceEpoch == conversation.epoch,
renderID: UUID())))
}
public func setSidebarVisible(_ visible: Bool) {
guard isSidebarVisible != visible else { return }
isSidebarVisible = visible
persistSettings()
}
/// One action behind the strip button, the View menu item and its
/// shortcut, so the three cannot disagree about what "shown" means.
public func toggleSidebar() {
setSidebarVisible(!isSidebarVisible)
}
/// Retries the writer lock a second window could not take at launch.
///
/// `isReadOnly` was decided once, when the store was activated, so a window
/// that opened while another held the lock said "this one can read them but
/// not change them" for the rest of its life — including long after the
/// other one had quit. Becoming the frontmost window is exactly when that
/// is worth asking again: it is what the user does after closing the other
/// copy.
public func reacquireStoreIfPossible() {
guard history.isReadOnlyStore, let store = conversationStore else { return }
Task { [weak self] in
// Nil is the ordinary answer — another window is open — and anything
// else is a fault this one can act on. Discarded, a store that could
// not be locked for any other reason read as "another instance holds
// it" for the rest of the session.
if let reason = await store.retryLock() {
self?.recordHistoryDiagnostic(
"the conversation store could not be locked for writing: "
+ reason)
}
await self?.refreshHistory()
}
}
public func setInspectorVisible(_ visible: Bool) {
guard isInspectorVisible != visible else { return }
isInspectorVisible = visible
persistSettings()
}
public func toggleInspector() {
setInspectorVisible(!isInspectorVisible)
}
/// Whether New Chat can run right now.
///
/// The same guard `newChat()` already has, made askable so the button and
/// the menu item can be disabled rather than silently doing nothing, plus
/// the installer: there is no chat to start before a model exists.
public var canStartNewChat: Bool {
!isChangingModelLocation && !isTurnInFlight && !requiresModelInstallation
}
public func setLoadModelOnLaunch(_ enabled: Bool) {
guard loadModelOnLaunch != enabled else { return }
loadModelOnLaunch = enabled
persistSettings()
}
/// Starts the launch load if it is switched on and the model can be loaded.
/// Called once, when the window first appears; a model that is missing,
/// already loading, or busy with a companion operation is left alone.
public func loadModelAtLaunchIfEnabled() {
guard loadModelOnLaunch, canLoadModel else { return }
loadModel()
}
/// Whether an image can be attached at all.
///
/// The runtime flag only says this build *can* use images; the companion
/// pack is what makes it possible for this model. Gating on the flag alone
/// offered an Add-images button with no tower behind it, and the failure
/// only surfaced when the user pressed Generate.
public var isImageInputAvailable: Bool {
isVisionRuntimeSupported && isVisionPackInstalled
}
/// Image support is part of this build. Hardware support and companion-pack
/// availability are separate so the inspector can explain either absence.
public var visionRuntimeEnabled: Bool { true }
/// Room left for the prompt when working out how many images fit. The
/// runtime still rejects a combination that does not fit, so this only has
/// to be a defensible reserve rather than an exact prompt measurement.
nonisolated static let reservedPromptTokens = 1_024
/// How many images this conversation can hold, derived from the context
/// exactly as the server derives its budget. It used to be a fixed four,
/// which meant the same set of images was accepted over the API and refused
/// in the app.
public var maximumImageAttachments: Int {
// The context a run will actually use, which is the loaded session's
// until it is reloaded. Capping on the pending setting instead let the
// composer accept images the request then refused.
//
// The conversation counts against the same window, and the request
// reserves it (`AppGenerationRequest.validate`). Reserving only a fixed
// 1,024 here meant that past that point the composer kept offering
// images Send would refuse — accepted on attach, rejected on the button.
Self.imageAttachmentCapacity(
maxContextTokens: effectiveMaxContextTokens,
conversationTokens: conversation.kvTokens)
}
nonisolated static func imageAttachmentCapacity(
maxContextTokens: Int,
conversationTokens: Int?
) -> Int {
guard let conversationTokens else { return 0 }
// The reply's reserve too: `generate` refuses a prompt that leaves
// less than it free, after every image has been encoded on the GPU.
// Without it the composer offered image sets the turn then refused.
return VisionImageTokenBudget.capacity(
maxContext: maxContextTokens,
reservedTextTokens: max(reservedPromptTokens, conversationTokens)
+ ConversationGenerationReserve.tokens)
}
/// The context a generation would run with right now.
public var effectiveMaxContextTokens: Int {
(loadedRuntimeKey ?? currentRuntimeKey).maxContextTokens
}
/// `discardingSourceDirectory` is the temp directory a file-promise drop
/// wrote into. It is ours, it holds nothing but those copies, and staging
/// takes its own copy — so it must not outlive the staging that consumed
/// it, which is exactly how it leaked.
public func addImages(_ urls: [URL], discardingSourceDirectory: URL? = nil) {
// Every early return has to discard the promise directory itself. The
// staging task's `defer` below owns it only once that task exists, so a
// return above it strands the full-size copies with nothing left to
// delete them: the attachment sweep only covers the staging root.
func discardSource() {
if let discardingSourceDirectory {
try? FileManager.default.removeItem(at: discardingSourceDirectory)
}
}
guard !isChangingModelLocation else {
imageAttachmentError = "Wait for the model location change to finish before attaching images."
discardSource()
return
}
recheckVisionPackAtCurrentLocation()
guard isImageInputAvailable, !urls.isEmpty else {
if !isImageInputAvailable {
recordVisionAvailabilityError(
at: URL(fileURLWithPath: modelPathText, isDirectory: true))
}
discardSource()
return
}
// The whole send, not just the generation: a picture attached during
// a deferred replay met `restoreComposer`'s draft-wins rule when the
// replay failed, which deleted the sent message's own pictures.
guard !isTurnInFlight else {
// A promise drop admitted before the run started can be delivered
// after it. Returning silently made the images look as though they
// had simply vanished.
imageAttachmentError =
"Wait for the current run to finish before attaching images."
discardSource()
return
}
let capacity = maximumImageAttachments
let available = max(0, capacity - imageAttachments.count)
guard available > 0 else {
imageAttachmentError = Self.imageCapacityMessage(
capacity: capacity, context: effectiveMaxContextTokens)
discardSource()
return
}
addingImagesCount += 1
imageAttachmentError = nil
// Dropping the rest silently left the user believing every image they
// chose was attached.
let selected = Array(urls.prefix(available))
if selected.count < urls.count {
imageAttachmentError = Self.imageCapacityMessage(
capacity: capacity, context: effectiveMaxContextTokens)
}
Task.detached(priority: .userInitiated) { [weak self, attachmentStore] in
var staged: [StagedImage] = []
defer {
if let discardingSourceDirectory {
try? FileManager.default.removeItem(at: discardingSourceDirectory)
}
}
do {
for url in selected {
staged.append(try attachmentStore.stage(url))
}
await self?.finishAddingImages(staged)
} catch {
// The batch is all-or-nothing, so the copies made before the
// failure are referenced by nothing and would never be deleted.
for attachment in staged { attachmentStore.remove(attachment) }
await self?.finishAddingImages(error: error)
}
}
}
/// Attaches image bytes that have no file behind them: an image copied out
/// of another app arrives on the pasteboard as data, and a drag from an app
/// that has not written the file yet arrives as a promise.
public func addImageData(_ data: Data, displayName: String) {
guard !isChangingModelLocation else {
imageAttachmentError = "Wait for the model location change to finish before attaching images."
return
}
recheckVisionPackAtCurrentLocation()
guard isImageInputAvailable else {
recordVisionAvailabilityError(
at: URL(fileURLWithPath: modelPathText, isDirectory: true))
return
}
guard !isTurnInFlight else {
imageAttachmentError =
"Wait for the current run to finish before attaching images."
return
}
let capacity = maximumImageAttachments
guard imageAttachments.count < capacity else {
imageAttachmentError = Self.imageCapacityMessage(
capacity: capacity, context: effectiveMaxContextTokens)
return
}
addingImagesCount += 1
imageAttachmentError = nil
Task.detached(priority: .userInitiated) { [weak self, attachmentStore] in
do {
let staged = try attachmentStore.stage(
data: data, displayName: displayName)
await self?.finishAddingImages([staged])
} catch {
await self?.finishAddingImages(error: error)
}
}
}
static func imageCapacityMessage(capacity: Int, context: Int) -> String {
let plural = capacity == 1 ? "" : "s"
// Once about 9,000 tokens are free it is the per-turn cap that binds,
// not the context, and telling the reader to raise Context would send
// them to a setting that cannot change the answer.
guard capacity < VisionImageTokenBudget.maximumAttachmentsPerTurn else {
return "At most \(capacity) image\(plural) can be sent in one message."
}
return "At most \(capacity) image\(plural) fit in the "
+ "\(context / 1_024)K context this session is running with. Raise "
+ "Context in Memory and reload the model to send more."
}
public func reportImageAttachmentError(_ error: Error) {
imageAttachmentError = String(describing: error)
}
public func reportImageAttachmentError(_ message: String) {
imageAttachmentError = message
}
public func removeImage(id: UUID) {
guard !isTurnInFlight,
let index = imageAttachments.firstIndex(where: { $0.id == id }) else { return }
let attachment = imageAttachments.remove(at: index)
attachmentStore.remove(attachment)
imageAttachmentError = nil
}
/// Puts the composer in the state a completed pick leaves it in.
///
/// `addImages` needs a verifiable companion pack to reach its staging path,
/// which no unit test has, and the lifetime rules around these files are
/// exactly what needs covering.
func setComposerAttachmentsForTesting(_ attachments: [StagedImage]) {
imageAttachments = attachments
}
public func clearImages() {
guard !isTurnInFlight else { return }
for attachment in imageAttachments { attachmentStore.remove(attachment) }
imageAttachments.removeAll()
imageAttachmentError = nil
}
private func finishAddingImages(_ staged: [StagedImage]) {
// Two adds can be in flight at once — the picker and a drop — and each
// sized itself against the count it saw at admission, so the second to
// land can push past the cap. Re-check against the real count here and
// delete what does not fit, rather than leaving staged copies that
// nothing references.
defer { addingImagesCount = max(0, addingImagesCount - 1) }
// The counter keeps `canRun` closed until every batch lands, so a run
// should not be able to start underneath one. If it ever does, the run
// has already snapshotted its images: appending here would attach them
// to the *next* message with no way to take them off, which is worse
// than saying so. `addImages` refuses a mid-run drop the same way.
guard !isRunning else {
for attachment in staged { attachmentStore.remove(attachment) }
imageAttachmentError =
"Wait for the current run to finish before attaching images."
return
}
let capacity = maximumImageAttachments
let available = max(0, capacity - imageAttachments.count)
let accepted = staged.prefix(available)
for attachment in staged.dropFirst(accepted.count) {
attachmentStore.remove(attachment)
}
imageAttachments.append(contentsOf: accepted)
if accepted.count < staged.count {
imageAttachmentError = Self.imageCapacityMessage(
capacity: capacity, context: effectiveMaxContextTokens)
}
}
private func finishAddingImages(error: Error) {
addingImagesCount = max(0, addingImagesCount - 1)
imageAttachmentError = String(describing: error)
}
public func reloadModel() {
guard canReloadModel else { return }
beginLoad()
}
private func beginLoad() {
guard let lifecycle = client as? AppModelLifecycleClient else {
loadState = .failed(.modelLoadFailed("This client has no model load lifecycle."))
return
}
let directory = URL(fileURLWithPath: modelPathText)
let maxContext = maxContextTokens
// Refused here, before the load state moves and before anything is
// sent to the decode service. A 262,144-token KV is charged in full
// the moment a command buffer binds it, so a host that cannot hold it
// does not find out part-way through a load: it is killed.
if case .needsMemory = ContextAdmission.availability(
config: ArchConfig.gemma4_26B_A4B,
maxContext: maxContext,
hostMemoryBytes: hostMemoryBytes, expertCacheSlots: runtimeOptions.expertCacheSlots) {
loadState = .failed(.modelLoadFailed(
ContextAdmission.needDescription(config: ArchConfig.gemma4_26B_A4B,
maxContext: maxContext,
hostMemoryBytes: hostMemoryBytes, expertCacheSlots: runtimeOptions.expertCacheSlots)))
return
}
let forceLogitsHead = currentForceLogitsHead
let runtimeKey = AppLoadedRuntimeKey(modelDirectory: directory,
maxContextTokens: maxContext,
options: runtimeOptions,
forceLogitsHead: forceLogitsHead)
// The session is loaded with the same normalized options a run sends.
// Loading with the raw settings instead meant a control that is off but
// still carries a non-default value — RDADVISE off with its policy left
// on `bounded` — produced a loaded session no run could match, and the
// staleness check compares two normalized keys, so nothing ever offered
// the reload that would have cleared it.
let options = runtimeKey.options(prefillEnabled: runtimeOptions.prefillEnabled,
prefillChunkTokens: runtimeOptions.prefillChunkTokens)
let pendingUnload = unloadTask
loadGeneration &+= 1
let generation = loadGeneration
pendingExplicitLoadRuntimeKey = runtimeKey
error = nil
appliedLoadSequence = 0
loadState = .loading(.validatingDirectory)
let emitted = Mutex<UInt64>(0)
loadTask = Task.detached { [weak self, lifecycle, pendingUnload] in
do {
await pendingUnload?.value
try Task.checkCancellation()
try await lifecycle.ensureLoaded(modelDirectory: directory,
maxContextTokens: maxContext,
options: options,
forceLogitsHead: forceLogitsHead) { [weak self] state in
// Stamped where the phase is emitted, in order; checked
// where it is applied, which is not.
let sequence = emitted.withLock { value -> UInt64 in
value += 1
return value
}
Task { @MainActor in
self?.applyLoadState(state, generation: generation,
sequence: sequence)
}
}
} catch is CancellationError {
} catch let appError as AppInferenceError {
await self?.applyLoadState(.failed(appError), generation: generation)
} catch {
await self?.applyLoadState(
.failed(.modelLoadFailed("\(error)")),
generation: generation)
}
await self?.clearLoadTask(generation: generation)
}
}
public func cancelLoad() {
guard canCancelLoad, let lifecycle = client as? AppModelLifecycleClient else { return }
loadState = .cancelling
loadGeneration &+= 1
loadTask?.cancel()
loadTask = nil
pendingExplicitLoadRuntimeKey = nil
unloadGeneration &+= 1
let generation = unloadGeneration
unloadTask = Task { [weak self, lifecycle] in
await lifecycle.unload()
guard let self, generation == self.unloadGeneration else { return }
self.loadedRuntimeKey = nil
self.loadState = .notLoaded
endConversationForReleasedKV()
self.clearUnloadTask(generation: generation)
}
}
/// Ends the conversation because the KV behind it is gone.
///
/// `applyLoadState`'s `.notLoaded` branch does this too, but nothing reaches
/// it: every production transition to `.notLoaded` assigns `loadState`
/// directly. Calling this from those sites is what actually runs it.
private func endConversationForReleasedKV() {
serviceEpoch = nil
presentStoredConversationAfterReleasedKV()
}
public func unloadModel() {
guard canUnloadModel, let lifecycle = client as? AppModelLifecycleClient else { return }
loadState = .unloading
unloadGeneration &+= 1
let generation = unloadGeneration
unloadTask = Task { [weak self, lifecycle] in
await lifecycle.unload()
guard let self, generation == self.unloadGeneration else { return }
self.loadedRuntimeKey = nil
self.liveMemoryBytes = nil
self.loadState = .notLoaded
endConversationForReleasedKV()
self.clearUnloadTask(generation: generation)
}
}
public func installModel() {
guard !isRunning, !loadState.isLoading, !isInstallingModel,
requiresModelInstallation else {
return
}
refreshInstallReadiness()
guard canInstallModel else { return }
installTask?.cancel()
installer.cancel()
resetInstallETA()
let outputDirectory = URL(fileURLWithPath: modelPathText)
installGeneration &+= 1
let generation = installGeneration
installState = .checking
installTask = Task { [weak self, installer] in
do {
for try await event in installer.installDefaultModel(outputDirectory: outputDirectory) {
guard let self else { return }
self.applyInstallEvent(event, generation: generation)
}
self?.finishInstallStream(generation: generation)
} catch is CancellationError {
self?.finishInstallCancellation(generation: generation)
} catch {
self?.finishInstallFailure(error, generation: generation)
}
}
}
public func cancelInstall() {
guard canCancelInstall else { return }
installState = .cancelling
installer.cancel()
}
public var hasPartialModelDownload: Bool {
guard let paths = try? RemoteInstallPaths(outputDirectory: modelPathText) else {
return false
}
return FileManager.default.fileExists(atPath: paths.partialDirectory)
|| FileManager.default.fileExists(atPath: paths.checkpointFile)
}
public var canDiscardModelDownload: Bool {
hasPartialModelDownload && !isInstallingModel && !isRunning
}
public func discardModelDownload() {
guard canDiscardModelDownload else { return }
let outputDirectory = URL(fileURLWithPath: modelPathText)
installGeneration &+= 1
let generation = installGeneration
installState = .discarding
installTask = Task { [weak self, installer] in
do {
try await installer.discardPartialInstall(
outputDirectory: outputDirectory)
guard let self, generation == self.installGeneration else { return }
self.installTask = nil
self.installState = .idle
self.refreshInstallReadiness()
} catch {
self?.finishInstallFailure(error, generation: generation)
}
}
}
public var hasPartialVisionPackDownload: Bool {
guard let output = try? VisionPackLocation.companionURL(
forTextModel: URL(fileURLWithPath: modelPathText, isDirectory: true)),
let paths = try? RemoteInstallPaths(outputDirectory: output.path) else {
return false
}
return FileManager.default.fileExists(atPath: paths.partialDirectory)
|| FileManager.default.fileExists(atPath: paths.checkpointFile)
}
public var canDiscardVisionPackDownload: Bool {
hasPartialVisionPackDownload && canBeginVisionCompanionOperation
}
public var canRemoveVisionPack: Bool {
hasVisionPackDirectory && canBeginVisionCompanionOperation
}
public var hasVisionPackDirectory: Bool {
guard let output = try? VisionPackLocation.companionURL(
forTextModel: URL(fileURLWithPath: modelPathText, isDirectory: true)) else {
return false
}
var isDirectory: ObjCBool = false
return FileManager.default.fileExists(
atPath: output.path,
isDirectory: &isDirectory) && isDirectory.boolValue
}
public func installVisionPack() {
guard canInstallVisionPack else { return }
visionInstallCancellationRequested = false
visionInstallTask?.cancel()
visionInstaller.cancel()
let textModelDirectory = URL(
fileURLWithPath: modelPathText,
isDirectory: true).standardizedFileURL
visionInstallGeneration &+= 1
let generation = visionInstallGeneration
visionInstallState = .checking
visionInstallTask = Task { [weak self, visionInstaller] in
do {
for try await event in visionInstaller.install(
textModelDirectory: textModelDirectory) {
guard let self else { return }
self.applyVisionInstallEvent(event, generation: generation)
}
self?.finishVisionInstallStream(generation: generation)
} catch is CancellationError {
self?.finishVisionInstallCancellation(generation: generation)
} catch {
self?.finishVisionInstallFailure(error, generation: generation)
}
}
}
public func cancelVisionInstall() {
guard canCancelVisionInstall else { return }
visionInstallCancellationRequested = true
visionInstallState = .cancelling
visionInstaller.cancel()
// A cancel raised before the stream registers its own task would find no
// active install; cancelling the consumer terminates the stream, which
// routes through the same cooperative drain-to-checkpoint path.
visionInstallTask?.cancel()
}
public func activateVisionPack() {
guard canActivateVisionPack else { return }
let directory = URL(fileURLWithPath: modelPathText, isDirectory: true)
.standardizedFileURL
visionInstallCancellationRequested = false
visionInstallGeneration &+= 1
let generation = visionInstallGeneration
resetVisionInstallETA()
visionInstallState = .activating
visionActivationProgress = 0
visionInstallTask = Task { [weak self, visionInstaller] in
do {
let output = try await visionInstaller.activatePreparedInstall(
textModelDirectory: directory,
onVerifyProgress: { [weak self] fraction in
Task { @MainActor in
guard let self,
generation == self.visionInstallGeneration,
case .activating = self.visionInstallState else { return }
// Each hop is its own task, and tasks are not
// ordered against each other, so a late one must
// not walk the bar backwards.
guard fraction >= (self.visionActivationProgress ?? 0)
else { return }
self.visionActivationProgress = fraction
}
})
// Applied first: a progress hop still in flight is dropped
// once the state is no longer `.activating`, so clearing before
// this could be undone by a late update.
self?.applyVisionInstallEvent(
.installed(output), generation: generation)
self?.visionActivationProgress = nil
} catch is CancellationError {
// Cancellation can only land during verification, before
// anything is renamed, so the prepared pack is untouched and
// still activatable.
self?.finishVisionActivationCancelled(generation: generation)
self?.visionActivationProgress = nil
} catch {
self?.finishVisionInstallFailure(
error, generation: generation, phase: .activation)
self?.visionActivationProgress = nil
}
}
}
private func finishVisionActivationCancelled(generation: UInt64) {
guard generation == visionInstallGeneration else { return }
resetVisionInstallETA()
visionInstallTask = nil
visionInstallCancellationRequested = false
visionInstallState = .idle
refreshVisionInstallReadiness()
}
public func discardVisionPackDownload() {
guard canDiscardVisionPackDownload else { return }
let directory = URL(fileURLWithPath: modelPathText, isDirectory: true)
.standardizedFileURL
visionInstallCancellationRequested = false
visionInstallGeneration &+= 1
let generation = visionInstallGeneration
visionInstallState = .discarding
visionInstallTask = Task { [weak self, visionInstaller] in
do {
try await visionInstaller.discardPartialInstall(
textModelDirectory: directory)
guard let self, generation == self.visionInstallGeneration else { return }
self.visionInstallTask = nil
self.visionInstallState = .idle
self.refreshVisionInstallReadiness()
} catch {
self?.finishVisionInstallFailure(error, generation: generation)
}
}
}
/// Drives the confirmation the Model menu puts in front of `removeVisionPack`.
///
/// The Inspector hides its own Remove button once the pack is installed, so
/// the menu item is the only reachable way to delete 1.14 GB — and it called
/// straight through, with the dialog sitting on an unreachable branch.
public func requestVisionPackRemoval() {
guard canRemoveVisionPack else { return }
isConfirmingVisionPackRemoval = true
}
public func removeVisionPack() {
isConfirmingVisionPackRemoval = false
guard canRemoveVisionPack else { return }
let directory = URL(fileURLWithPath: modelPathText, isDirectory: true)
.standardizedFileURL
visionInstallCancellationRequested = false
visionInstallGeneration &+= 1
let generation = visionInstallGeneration
visionInstallState = .discarding
visionInstallTask = Task { [weak self, visionInstaller] in
do {
try await visionInstaller.removeInstalled(
textModelDirectory: directory)
guard let self, generation == self.visionInstallGeneration else { return }
self.visionInstallTask = nil
self.visionInstallState = .idle
self.visionInstallationStatus = .missing
self.refreshVisionInstallReadiness()
} catch {
self?.finishVisionInstallFailure(error, generation: generation)
}
}
}
public func refreshInstallReadiness() {
refreshInstallReadiness(
at: URL(fileURLWithPath: modelPathText, isDirectory: true).standardizedFileURL)
}
public func recheckModelAtCurrentLocation() {
let directory = URL(fileURLWithPath: modelPathText, isDirectory: true)
.standardizedFileURL
modelPathText = directory.path
refreshInstallReadiness(at: directory)
refreshVisionInstallReadiness(at: directory)
}
public func recheckVisionPackAtCurrentLocation() {
refreshVisionInstallReadiness(
at: URL(fileURLWithPath: modelPathText, isDirectory: true)
.standardizedFileURL)
}
private func refreshInstallReadiness(at outputDirectory: URL) {
installationStatus = AppModelInstallationProbe.status(
at: outputDirectory,
descriptor: installer.descriptor)
do {
modelStorageMetrics = FileManager.default.fileExists(atPath: outputDirectory.path)
? try AppModelStorageMetrics.measure(at: outputDirectory) : nil
modelStorageMetricsError = nil
} catch {
modelStorageMetrics = nil
modelStorageMetricsError = "installed storage could not be measured: \(error)"
}
guard !isModelInstalled else {
installReadiness = .installed
return
}
guard AppModelLocation.isVolumeAvailable(for: outputDirectory) else {
installReadiness = .failed("The selected volume is unavailable. Reconnect it and check again, or choose another location.")
return
}
installReadiness = .checking
do {
let requirement = try installer.checkInstallRequirement(
outputDirectory: outputDirectory)
installReadiness = requirement.canInstall
? .ready(requirement)
: .insufficientSpace(requirement)
} catch {
installReadiness = .failed("\(error)")
}
}
public func refreshVisionInstallReadiness() {
refreshVisionInstallReadiness(
at: URL(fileURLWithPath: modelPathText, isDirectory: true)
.standardizedFileURL)
}
private func refreshVisionInstallReadiness(at textModelDirectory: URL) {
visionInstallationStatus = AppVisionPackInstallationProbe.status(
at: textModelDirectory)
// Removing the companion leaves any attached image unsendable. Keep the
// draft intact and refuse the send until the reproducibility input is
// present again.
// Only once the dust has settled: the probe verifies the pack on disk,
// and a companion operation renames that directory underneath it, so
// refreshing mid-operation can briefly report no image support. Acting
// on that would delete images the user had staged.
if !isImageInputAvailable, !isVisionCompanionOperationInProgress,
!imageAttachments.isEmpty {
recordVisionAvailabilityError(at: textModelDirectory)
} else if isImageInputAvailable,
imageAttachmentError == visionAvailabilityAttachmentError {
imageAttachmentError = nil
visionAvailabilityAttachmentError = nil
}
guard isModelInstalled else {
visionInstallReadiness = .failed("Install the text model first")
return
}
guard !isVisionPackInstalled else {
visionInstallReadiness = .installed
return
}
if visionInstaller.preparedInstallIsValid(
textModelDirectory: textModelDirectory) {
let output = try? VisionPackLocation.companionURL(
forTextModel: textModelDirectory)
// A pack that failed to activate must not be re-offered for
// activation: `preparedInstallIsValid` does not hash the weights,
// so a corrupt pack still looks ready and the user would loop
// between Activate and the same failure.
let reportedBroken: Bool
switch visionInstallState {
case .recoverable, .failed: reportedBroken = true
default: reportedBroken = false
}
if let output, !isInstallingVisionPack, !reportedBroken {
visionInstallState = .readyToActivate(output)
}
}
visionInstallReadiness = .checking
do {
let requirement = try visionInstaller.checkInstallRequirement(
textModelDirectory: textModelDirectory)
visionInstallReadiness = requirement.canInstall
? .ready(requirement)
: .insufficientSpace(requirement)
} catch {
visionInstallReadiness = .failed("\(error)")
}
}
private func recordVisionAvailabilityError(at textModelDirectory: URL) {
let location: String
do {
location = try VisionPackLocation.companionURL(
forTextModel: textModelDirectory).path
} catch {
location = "an unresolved companion path (\(error))"
}
let cause: String
switch visionInstallationStatus {
case .missing:
cause = "the companion pack is missing"
case .partial(let detail):
cause = "the companion pack is incomplete: \(detail)"
case .unsupportedLayout:
cause = "this text-model layout cannot host a companion pack"
case .complete:
cause = isVisionRuntimeSupported
? "the companion pack is unavailable"
: "image inference is unsupported on this device"
}
let message = "Image support is unavailable at \(location): \(cause). "
+ "Restore the companion pack before sending."
visionAvailabilityAttachmentError = message
imageAttachmentError = message
}
private func applyVisionInstallEvent(
_ event: AppModelInstallEvent,
generation: UInt64
) {
guard generation == visionInstallGeneration else { return }
if visionInstallCancellationRequested {
switch event {
case .readyToActivate, .installed:
// Work that finished before the cancel landed is reported as it
// actually ended, not as a pause.
visionInstallCancellationRequested = false
default:
return
}
}
switch event {
case .checking:
resetVisionInstallETA()
visionInstallState = .checking
case .downloadingMetadata:
resetVisionInstallETA()
visionInstallState = .downloadingMetadata
case .planning:
resetVisionInstallETA()
visionInstallState = .planning
case .reservingOutput:
resetVisionInstallETA()
visionInstallState = .reservingOutput
case .copyingPayload(let reused, let downloaded, let total):
visionInstallState = .copyingPayload(
reusedBytes: reused,
downloadedThisRunBytes: downloaded,
totalBytes: total)
updateVisionInstallETA(
reusedBytes: reused,
downloadedThisRunBytes: downloaded,
totalBytes: total)
case .hashingOutput(let file):
resetVisionInstallETA()
visionInstallState = .hashingOutput(file)
case .finalizing:
resetVisionInstallETA()
visionInstallState = .finalizing
case .readyToActivate(let directory):
resetVisionInstallETA()
visionInstallState = .readyToActivate(directory)
visionInstallTask = nil
case .installed:
resetVisionInstallETA()
let textModelDirectory = URL(
fileURLWithPath: modelPathText,
isDirectory: true).standardizedFileURL
visionInstallationStatus = AppVisionPackInstallationProbe.status(
at: textModelDirectory)
guard isVisionPackInstalled else {
finishVisionInstallFailure(
RepackError.configurationInvalid(
detail: "completed vision install failed verification"),
generation: generation)
return
}
visionInstallState = .installed(modelDirectory: textModelDirectory)
visionInstallTask = nil
}
}
private func finishVisionInstallStream(generation: UInt64) {
guard generation == visionInstallGeneration,
visionInstallTask != nil else { return }
if visionInstallCancellationRequested || visionInstallState == .cancelling {
finishVisionInstallCancellation(generation: generation)
} else if !isVisionPackInstalled {
finishVisionInstallFailure(
RepackError.configurationInvalid(
detail: "vision installer ended before completion"),
generation: generation)
}
}
private func finishVisionInstallCancellation(generation: UInt64) {
guard generation == visionInstallGeneration else { return }
resetVisionInstallETA()
visionInstallCancellationRequested = false
visionInstallTask = nil
visionInstallState = .cancelled
refreshVisionInstallReadiness()
}
/// Which phase failed. Only a download failure may leave a prepared pack
/// that is worth activating; a verification failure must never send the
/// user back to Activate, or the same corrupt pack is offered forever.
enum VisionFailurePhase { case download, activation }
func finishVisionInstallFailure(
_ error: Error, generation: UInt64,
phase: VisionFailurePhase = .download
) {
guard generation == visionInstallGeneration else { return }
// An error raised because the user cancelled is a pause with saved
// progress, not an installation failure.
guard !visionInstallCancellationRequested else {
finishVisionInstallCancellation(generation: generation)
return
}
resetVisionInstallETA()
visionInstallTask = nil
let hasSavedDownload = hasPartialVisionPackDownload
let textModelDirectory = URL(
fileURLWithPath: modelPathText,
isDirectory: true).standardizedFileURL
// A download that finished and verifies is activatable whatever went
// wrong afterwards. Reporting it as "needs attention" hid the Activate
// button behind a Resume that only repeats work already done. The one
// failure that must not come back here is verification itself, or the
// same corrupt pack is offered forever — but a lock held by another
// process is contention, not corruption.
let isContention: Bool
if let repackError = error as? RepackError, case .installBusy = repackError {
isContention = true
} else {
isContention = false
}
if phase == .download || isContention, hasSavedDownload,
let output = try? VisionPackLocation.companionURL(
forTextModel: textModelDirectory),
visionInstaller.preparedInstallIsValid(
textModelDirectory: textModelDirectory) {
visionInstallState = .readyToActivate(output)
refreshVisionInstallReadiness(at: textModelDirectory)
return
}
visionInstallState = hasSavedDownload
? .recoverable("\(error)")
: .failed("\(error)")
if let repackError = error as? RepackError,
case .diskSpaceInsufficient(let path, let required, let available) = repackError {
visionInstallReadiness = .insufficientSpace(AppModelInstallRequirement(
probePath: path,
requiredBytes: required,
availableBytes: available))
} else {
refreshVisionInstallReadiness()
if hasSavedDownload {
visionInstallState = .recoverable("\(error)")
}
}
}
private func applyInstallEvent(_ event: AppModelInstallEvent, generation: UInt64) {
guard generation == installGeneration else { return }
switch event {
case .checking:
resetInstallETA()
installState = .checking
case .downloadingMetadata:
resetInstallETA()
installState = .downloadingMetadata
case .planning:
resetInstallETA()
installState = .planning
case .reservingOutput:
resetInstallETA()
installState = .reservingOutput
case .copyingPayload(let reused, let downloadedThisRun, let total):
installState = .copyingPayload(
reusedBytes: reused,
downloadedThisRunBytes: downloadedThisRun,
totalBytes: total)
updateInstallETA(
reusedBytes: reused,
downloadedThisRunBytes: downloadedThisRun,
totalBytes: total)
case .hashingOutput(let file):
resetInstallETA()
installState = .hashingOutput(file)
case .finalizing:
resetInstallETA()
installState = .finalizing
case .readyToActivate:
finishInstallFailure(
RepackError.configurationInvalid(
detail: "text installer returned a vision-only activation event"),
generation: generation)
case .installed(let directory):
resetInstallETA()
let directory = directory.standardizedFileURL
installationStatus = AppModelInstallationProbe.status(
at: directory,
descriptor: installer.descriptor)
guard installationStatus == .complete else {
finishInstallFailure(
RepackError.configurationInvalid(detail: "completed install did not pass metadata validation"),
generation: generation)
return
}
installState = .installed(modelDirectory: directory)
installTask = nil
modelPathText = directory.path
loadState = .notLoaded
endConversationForReleasedKV()
refreshVisionInstallReadiness(at: directory)
replaceConversationBinding(
for: directory,
reason: "the model installation completed")
}
}
private func finishInstallStream(generation: UInt64) {
guard generation == installGeneration, installTask != nil else { return }
if installState == .cancelling {
finishInstallCancellation(generation: generation)
} else if !isModelInstalled {
finishInstallFailure(
RepackError.configurationInvalid(detail: "installer ended before completion"),
generation: generation)
}
}
private func finishInstallCancellation(generation: UInt64) {
guard generation == installGeneration else { return }
installTask = nil
installState = .cancelled
resetInstallETA()
refreshInstallReadiness()
}
private func updateInstallETA(
reusedBytes: UInt64,
downloadedThisRunBytes: UInt64,
totalBytes: UInt64
) {
let observation = DownloadETAObservation(
reusedBytes: reusedBytes,
downloadedThisRunBytes: downloadedThisRunBytes,
totalBytes: totalBytes)
let timestamp = installETATimestamp
setInstallETAPresentation(
installETAEstimator.update(observation, timestamp: timestamp))
}
private var installETATimestamp: Double {
let components = installETAOrigin.duration(to: installETAClock.now).components
return Double(components.seconds)
+ Double(components.attoseconds) / 1_000_000_000_000_000_000
}
private func resetInstallETA() {
installETAEstimator.reset()
installETAPresentation = .hidden
installETAText = nil
}
private func updateVisionInstallETA(
reusedBytes: UInt64,
downloadedThisRunBytes: UInt64,
totalBytes: UInt64
) {
let observation = DownloadETAObservation(
reusedBytes: reusedBytes,
downloadedThisRunBytes: downloadedThisRunBytes,
totalBytes: totalBytes)
let presentation = visionInstallETAEstimator.update(
observation, timestamp: installETATimestamp)
visionInstallETAPresentation = presentation
visionInstallETAText = DownloadETAFormatter.string(for: presentation)
}
private func resetVisionInstallETA() {
visionInstallETAEstimator.reset()
visionInstallETAPresentation = .hidden
visionInstallETAText = nil
}
private func setInstallETAPresentation(
_ presentation: DownloadETAPresentation
) {
installETAPresentation = presentation
installETAText = DownloadETAFormatter.string(for: presentation)
}
private func currentSettings() -> MacAppSettings {
MacAppSettings(
selectedModelPath: savedModelPath,
migratedHistorySources: migratedHistorySources,
contextTokens: maxContextTokens,
expertCacheSlots: runtimeOptions.expertCacheSlots,
temperature: temperature,
topKEnabled: topKEnabled,
topK: topK,
topPEnabled: topPEnabled,
topP: topP,
prefillEnabled: runtimeOptions.prefillEnabled,
newlineShortcut: newlineShortcut,
showPromptExamples: showPromptExamples,
textSize: textSize,
sidebarVisible: isSidebarVisible,
inspectorVisible: isInspectorVisible,
visionResidencyPolicy: runtimeOptions.visionResidencyPolicy,
rdadvisePolicy: runtimeOptions.rdadvisePolicy,
loadModelOnLaunch: loadModelOnLaunch)
}
func persistSettings() {
guard settingsPersistenceEnabled, settingsWritesAllowed else { return }
do {
try MacAppSettingsFileStore.save(currentSettings(), at: AppDataLocation.settingsURL(in: appDataDirectory))
settingsDiagnostic = nil
} catch {
let message = "Saving Mac app settings failed: \(error)"
settingsDiagnostic = message
self.error = .unknown(message)
}
}
private func finishInstallFailure(_ error: Error, generation: UInt64) {
guard generation == installGeneration else { return }
installTask = nil
resetInstallETA()
let hasSavedDownload = hasPartialModelDownload
installState = hasSavedDownload ? .recoverable("\(error)") : .failed("\(error)")
if let repackError = error as? RepackError,
case .diskSpaceInsufficient(let path, let required, let available) = repackError {
let requirement = AppModelInstallRequirement(probePath: path,
requiredBytes: required,
availableBytes: available)
installReadiness = .insufficientSpace(requirement)
} else {
refreshInstallReadiness()
if hasSavedDownload {
installState = .recoverable("\(error)")
}
}
}
func applyLoadState(_ state: AppModelLoadState) {
applyLoadState(state, generation: loadGeneration)
}
/// `sequence` orders the phases a load emits. It is 0 for states this model
/// raises itself, which bypass the ordering check.
func applyLoadState(_ state: AppModelLoadState, generation: UInt64,
sequence: UInt64 = 0) {
guard generation == loadGeneration else { return }
if sequence > 0 {
guard sequence > appliedLoadSequence else { return }
appliedLoadSequence = sequence
}
if case .ready(let directory, _) = state,
directory.standardizedFileURL.path
!= URL(fileURLWithPath: modelPathText).standardizedFileURL.path {
return
}
loadState = state
// An outcome closes the load. Phases emitted before it but delivered
// after it must not reopen one that has already finished: `.failed` is
// raised here at sequence 0, so it never advanced the counter, and a
// late `.loading` hop could put the UI back into a load with no task
// left to cancel and no way to start another. `beginLoad` resets the
// counter, so the seal lasts exactly one load.
switch state {
case .notLoaded, .ready, .failed:
appliedLoadSequence = .max
case .loading, .cancelling, .unloading:
break
}
switch state {
case .notLoaded:
loadedRuntimeKey = nil
// Unloading released the runner and the KV, so whatever lineage was
// open no longer has tokens behind it.
serviceEpoch = nil
archiveConversationContext()
case .loading, .cancelling, .unloading:
break
case .ready(_, let seconds):
// A load builds a new runner and an empty KV. The service ends the
// lineage on its side for the same reason; leaving the app's epoch
// in place would have the next turn claim to resume onto a cache
// that had just been rebuilt.
let isAlreadyWaitingForReplay = serviceEpoch == nil
&& storedConversationID != nil
&& screen.conversationID == storedConversationID
serviceEpoch = nil
// And the conversation itself is gone with that KV. Keeping the
// turn list would leave the app numbering turns from where it left
// off while the service, having just ended the lineage, expects
// zero — so the gate would refuse the next turn and every turn
// after it, for the rest of the session.
if let id = pendingServiceRecoveryConversationID,
screen.conversationID == id,
storedConversationID == id {
prepareServiceRecoveryForReplay()
pendingServiceRecoveryConversationID = nil
} else if let id = pendingServiceRecoveryConversationID,
screen.conversationID == id {
// A replay lost the service with this row on screen and its
// message handed back; the failed replay already ended the
// held lineage. The row stays for the send that follows Retry
// Load. Archived instead, its selection went and the retried
// message opened a brand-new chat.
pendingServiceRecoveryConversationID = nil
} else if isAlreadyWaitingForReplay {
// An explicit unload already put the durable row on screen.
// Loading the new runner must not archive that row a second
// time or clear the selection before its deferred replay.
} else {
presentStoredConversationAfterReleasedKV()
}
loadedRuntimeKey = pendingExplicitLoadRuntimeKey
?? activeRunRuntimeKey
?? currentRuntimeKey
pendingExplicitLoadRuntimeKey = nil
// The freshly loaded model's footprint, so the figure is right
// before the first generation rather than after it.
sampleLiveMemory()
_ = seconds
case .failed(let loadError):
pendingExplicitLoadRuntimeKey = nil
error = loadError
}
}
/// Deletes every file this session staged. Called when the app is quitting,
/// which is the only moment they are all certainly unwanted.
///
/// The whole staging directory at once rather than picture by picture: a
/// release that walks the window's own references can only free what the
/// window still remembers, and quitting frees the rest as well.
public func releaseAllAttachments() {
imageAttachments.removeAll()
outputImageAttachments = []
attachmentStore.removeAll()
}
/// Memory comes from the process doing the work: the decode service when
/// there is one, this process otherwise.
private func sampleLiveMemory() {
if let reporter = client as? any AppInferenceMemoryReporting {
if let bytes = reporter.currentInferenceMemoryBytes {
liveMemoryBytes = bytes
}
if let resident = reporter.currentInferenceResidentBytes {
liveResidentBytes = resident
}
// Refreshed on every sample, so the tower figure tracks a run
// instead of appearing only in its final diagnostics.
if let tower = reporter.currentInferenceTowerBytes {
visionTowerMappedBytes = tower
}
} else {
liveMemoryBytes = memorySampler.sample()
// The occupied figure, not the footprint again: this row is the one
// that includes the mapped weights, and feeding it the footprint
// made both numbers report the same thing.
liveResidentBytes = memorySampler.occupiedSample()
}
}
/// Resident bytes for display, on the same terms as
/// `currentProcessMemoryBytes`.
public var currentProcessResidentBytes: UInt64? {
guard loadState.isReady || isRunning else { return nil }
if let liveResidentBytes { return liveResidentBytes }
if let reporter = client as? any AppInferenceMemoryReporting {
return reporter.currentInferenceResidentBytes
}
return memorySampler.occupiedSample()
}
/// Ends the conversation and starts an empty one.
///
/// No confirmation any more: the conversation being left is already on
/// disk, turn by turn, and one click in the sidebar brings it back. An
/// alert for something that is not lost is an alert for nothing.
public func newChat() {
// Refused during a replay as well as during a generation. The replay is
// putting a conversation into the KV for a turn that has already been
// sent; starting an empty chat under it left the window on the new chat
// and the model on the old one, and whichever landed last defined what
// the next turn was numbered against.
guard !isChangingModelLocation, !isTurnInFlight else { return }
quarantinedPersistenceLineages.removeAll()
pendingServiceRecoveryConversationID = nil
// The empty chat is not written until its first send, so it takes no
// row in the sidebar and the previous conversation stops being the one
// this window is appending to.
storedConversationID = nil
// Every turn holds its own hard links, and dropping the turn list
// without releasing them leaked one staged file per image per turn
// until quit. The release is the machine's
// `.releaseImagesOfHeldConversation` effect, so the transitions that
// give the KV up and the transitions that free its pictures are one
// list rather than two that drifted apart.
perform(machine.apply(.newChat))
// The composer's own attachments too. Released only from the transcript
// and the conversation, a picture attached but never sent stayed in the
// box and followed the user into the new chat — and its staged copy
// stayed on disk until the app quit.
clearImages()
conversation.startNew()
outputPromptText = ""
outputText = ""
generationTranscriptMailbox?.reset()
diagnostics = nil
error = nil
// Only the intent is recorded here; the next turn opens the new lineage
// on the inference side. Resetting eagerly as well raced that opening
// and sent two resets for one new chat, and it buys nothing: the KV
// allocation is fixed, so an unsent new chat holds no extra memory.
serviceEpoch = nil
}
/// Starts an empty conversation because the KV behind the old one is gone.
///
/// Distinct from `newChat()`: the user did not ask for this. The transcript
/// stays — lifecycle actions are not supposed to discard it — but its turns
/// move out of context, because the model can no longer see them. The
/// alternative, letting `conversation` keep counting, desynchronises the app
/// from the service's gate, which has just gone back to expecting turn zero;
/// the gate would then refuse every turn for the rest of the session.
private func archiveConversationContext() {
var carried = conversation.completedPairs
// The live fields hold the newest finished turn between runs, and it is
// already in `completedPairs`; nothing extra to carry.
if carried.isEmpty, !outputPromptText.isEmpty {
carried = [(user: AppChatTurn(role: .user, text: outputPromptText,
images: outputImageAttachments),
assistant: AppChatTurn(role: .assistant, text: outputText))]
}
// The read-only copy of a chat that was merely being looked at is not
// part of the live conversation's history, and it cannot be mistaken
// for one now: it lives in the screen and goes with the screen. When
// the two were one array, a reload or an unload while reading a chat
// that could not be continued drew that chat as the live conversation's
// own out-of-context turns, under a context break with nothing below
// it, and Re-read into a new chat built its prompt from a conversation
// the user had only been reading.
perform(machine.apply(.lineageEnded))
let outOfContext = conversation.outOfContextPairs + carried
conversation.startNew(carryingOutOfContext: outOfContext)
// The stored conversation keeps every turn it had, and its row will say
// whether it can still be continued. What must not happen is the next
// turn appending to that file while the KV holds only the new lineage:
// the transcript on disk would then claim a context the model does not
// have. So this window stops writing to it and the next send opens a
// new one.
storedConversationID = nil
// The archived pairs are what the transcript draws now. Leaving the
// live fields holding the newest of them would draw that turn twice,
// once as history and once as the turn still on screen.
if !carried.isEmpty {
outputPromptText = ""
outputText = ""
outputImageAttachments = []
generationTranscriptMailbox?.reset()
}
}
/// A persisted conversation remains the conversation on screen after its
/// KV is released. It is now a readable stored copy, and the next send
/// restores its exact token record before appending to the same directory.
/// A non-persisted session has no such record and keeps the legacy visible
/// context-break behavior instead.
private func presentStoredConversationAfterReleasedKV() {
// Browsing and KV ownership are independent. Releasing the held KV
// must not switch the viewed row or redirect its next message.
guard let id = screen.conversationID ?? storedConversationID,
conversationStore != nil,
history.entry(id) != nil else {
archiveConversationContext()
return
}
prepareServiceRecoveryForReplay()
openConversation(id: id)
}
/// Opens the conversation on the inference side if it has not been opened
/// yet. Called before every turn: a load or an unload ends the lineage
/// there without the app being asked, and the next turn has to re-open it
/// rather than resume onto a KV that was rebuilt empty.
private func openConversationIfNeeded() async throws {
guard serviceEpoch != conversation.epoch else { return }
guard let lifecycle = client as? AppModelLifecycleClient else { return }
try await lifecycle.resetConversation(epoch: conversation.epoch)
serviceEpoch = conversation.epoch
}
// MARK: - The send path
/// Hands a message over to the pipeline.
///
/// Synchronous on purpose, and it empties the composer before it returns:
/// `canRun` reads the composer, so a second Generate between the click and
/// the pipeline's first suspension is refused by the same guard that
/// refused the first one. Started inside the task instead, two clicks
/// started two replays of the same chat under different epochs, and the
/// turn the first had already stamped came back rejected as belonging to a
/// conversation that was no longer open.
public func send() {
recheckVisionPackAtCurrentLocation()
guard canRun else { return }
let turn = takeComposer()
sendTask = Task { [weak self] in
guard let self else { return }
await deliver(turn)
sendTask = nil
}
}
/// Takes the message out of the composer and gives it to the caller.
///
/// The images move rather than being copied: the composer stops drawing
/// them here and nothing deletes them, because the turn is now the only
/// thing that refers to those files. A stage that fails puts both halves
/// back through `restoreComposer`.
private func takeComposer() -> PreparedTurn {
let turn = PreparedTurn(prompt: promptText, images: imageAttachments)
promptText = ""
imageAttachments.removeAll()
imageAttachmentError = nil
return turn
}
/// The one path a message takes, in stages.
///
/// Every stage either advances or ends in `restoreComposer`, and nothing
/// here calls itself: the replay used to hand the message back to the
/// composer and re-enter `run()`, so a replay that resolved without putting
/// anything into the KV re-entered the same branch forever.
private func deliver(_ turn: PreparedTurn) async {
var turn = turn
// The transcript draws this message as the current turn from the moment
// a replay starts, so a stage that fails before the model saw it takes
// the message off the screen with it. A turn the runtime rewound
// afterwards keeps it: the window shows a stopped turn as the current
// one until the next send replaces it.
var isDrawnAsTheLiveTurn = false
// 1. Replay. A reopened conversation is on screen but not in the
// model's context, and the ticket below has to be reserved against
// the restored lineage or the service's gate refuses a turn numbered
// against the wrong epoch.
//
// Anything but the live conversation goes through here. Only
// `.reading` used to, so a send while the screen named an unreadable
// row skipped the replay and ran on the held chat: the turn was
// written into that chat's file while the sidebar, the notice and
// the saved selection all named the row that could not be read.
if case .live = screen {} else {
var replayID: UUID?
for case .replay(let id, _) in machine.apply(.sendRequested(turn)) {
replayID = id
}
guard let replayID else {
// The machine refused: the row on screen cannot be continued,
// which `canRun` already says. Handed back rather than run on
// the held conversation under the wrong row.
restoreComposer(turn, error: .invalidRequest(
"The conversation on screen cannot be continued."),
withdrawingFromTranscript: false)
return
}
// The message moves into the transcript now, under the same prefill
// placeholder an ordinary turn gets. A replay is a full prefill of
// everything the conversation holds, and for the length of it the
// window showed nothing at all — the composer was empty and the
// transcript had not changed — which is what made a second Generate
// the obvious thing to press.
runIdentity &+= 1
generationTranscriptMailbox?.reset()
outputPromptText = turn.prompt
outputImageAttachments = turn.images.map(ChatImage.staged)
outputText = ""
isDrawnAsTheLiveTurn = true
if await !replayIntoKV(id: replayID, turn: turn) {
// The machine's `.restoreComposer` effect has already handed
// the message back with the reason it could not be replayed.
return
}
}
// 2. Reserve the position the service will check, before the request is
// built, so the position the transcript shows is the position sent.
guard let ticket = conversation.beginTurn(text: turn.prompt) else {
// `canRun` already required `conversation.canSend`, and the emptied
// composer refuses a second send, so nothing should reach this.
// Refused with the message given back rather than dropped.
restoreComposer(turn, error: .invalidRequest(
"This conversation is already sending a turn."),
withdrawingFromTranscript: isDrawnAsTheLiveTurn)
return
}
// 3. Build the request from the message, not from the composer: the
// composer was emptied at stage 1 and may already hold the next one.
var request: AppGenerationRequest
do {
request = try makeRequest(turn, ticket: ticket)
} catch {
conversation.abandonTurn()
restoreComposer(
turn,
error: (error as? AppInferenceError) ?? .unknown("\(error)"),
withdrawingFromTranscript: isDrawnAsTheLiveTurn)
return
}
// 4. Retain the images. The run reads the transcript's own hard links
// rather than the composer's files, so the hand-off below cannot
// delete an image this request has not opened yet. A failed retain
// leaves no reference guaranteed to outlive the composer, so the run
// is refused instead of started against files about to be removed.
var retained: [StagedImage] = []
do {
for attachment in request.imageAttachments {
retained.append(try attachmentStore.retain(attachment))
}
} catch {
for attachment in retained { attachmentStore.remove(attachment) }
conversation.abandonTurn()
imageAttachmentError = String(describing: error)
restoreComposer(turn, error: .invalidRequest(
"Could not prepare the attached images for this run: \(error)"),
withdrawingFromTranscript: isDrawnAsTheLiveTurn)
return
}
request.imageAttachments = retained
// The hand-off. The message is carried by its retained links from here,
// and the copies it arrived with are referenced by nothing: handing
// those back after a rewind would give the user thumbnails with no
// files behind them.
for attachment in turn.images { attachmentStore.remove(attachment) }
turn = turn.carrying(retained)
// 5. Start the turn.
persistSettings()
generationTranscriptMailbox?.reset()
runIdentity &+= 1
let generation = runIdentity
outputPromptText = request.prompt
// Not released: every turn of a conversation keeps its own images for
// as long as the conversation shows them. They are hard links to files
// that already exist, so holding them costs no additional bytes.
conversation.attachImagesToPendingTurn(retained)
outputImageAttachments = retained.map(ChatImage.staged)
outputText = ""
diagnostics = nil
error = nil
hasHandledTerminalEvent = false
turnOutcome = .committed
activeRunRuntimeKey = AppLoadedRuntimeKey(
modelDirectory: request.modelDirectory,
maxContextTokens: request.maxContextTokens,
options: request.runtimeOptions,
forceLogitsHead: !request.isPureGreedy)
isCancellationPending = false
liveTokenCount = 0
liveElapsedDecodeSeconds = 0
livePrefillDone = 0
livePrefillTotal = 0
sampleLiveMemory()
phase = .prefill
runState = .running
// 6. Generate. The directory is created here, on the first send, rather
// than at New Chat: a chat the user opens and never uses must leave
// nothing behind. The images start being written now, overlapped with
// the reply the user is already waiting for.
if let storedID = await ensureStoredConversation(firstMessage: request.prompt) {
beginStoringTurnImages(request.imageAttachments, in: storedID)
}
// Off the main actor: an event stream whose producer runs inline would
// hold the window for the length of the run.
let stream = Task.detached { [weak self, client, request, generation] in
guard let self else { return }
do {
try await self.openConversationIfNeeded()
for try await event in client.generate(request) {
await self.apply(event, generation: generation)
}
} catch let appError as AppInferenceError {
await self.finishStreamFailure(appError, generation: generation)
} catch {
await self.finishStreamFailure(.unknown("\(error)"), generation: generation)
}
}
// The turn is over at its terminal event, not when the stream happens
// to close: a client that reports a failure and then goes quiet would
// otherwise hold the composer, New Chat and every later send for as
// long as it stayed quiet. The stream is watched as well, so a stream
// that ends without a terminal event still releases this.
await withCheckedContinuation { continuation in
turnCompletion = (generation: generation, continuation: continuation)
Task { [weak self] in
await stream.value
self?.endTurnWait(generation: generation)
}
}
// 7. Commit or hand back. `finishSuccessfully` has already written the
// turn; a rewind reaches here with the cause already in `error`.
guard case .rewound = turnOutcome else { return }
restoreComposer(turn, error: nil, withdrawingFromTranscript: false)
// Its images were written while the reply was generating, and the turn
// that would have cited them is gone. Ended before the sweep rather
// than beside it: the sweep deletes every file no record names, and a
// write still running would have raced it into the same directory.
await discardPendingTurnImages()
await sweepImagesOfRewoundTurn()
}
/// Puts a stored conversation back into the KV and says whether the turn
/// waiting on it may go.
private func replayIntoKV(id: UUID, turn: PreparedTurn) async -> Bool {
phase = .prefill
livePrefillDone = 0
// A denominator from the record, so the gauge counts up from the first
// moment rather than from whenever the first progress event lands.
livePrefillTotal = history.entry(id)?.kvTokens ?? 0
let outcome = await replayOutcome(id: id)
// Back out of the prefill phase the send put the window into, or the
// gauge keeps claiming a replay that has already finished.
phase = .idle
livePrefillDone = 0
livePrefillTotal = 0
let effects = machine.apply(outcome)
perform(effects)
return effects.contains { if case .startTurn = $0 { return true } else { return false } }
}
/// Puts a turn that never reached the model, or one the runtime rewound,
/// back in the composer.
///
/// The one function that hands a message back; every failing stage reaches
/// it exactly once. `error` is nil when the failure has already recorded
/// itself — a rewound generation sets `error` as it ends, and a second copy
/// of the same cause would replace what the window is already showing.
///
/// `withdrawingFromTranscript` takes the message off the screen as well.
/// True for every stage that failed before the model saw the turn, because
/// what is drawn there is this very message with nothing underneath it;
/// false for a turn the runtime rewound, which the window keeps drawing as
/// the current one until the next send replaces it.
func restoreComposer(_ turn: PreparedTurn,
error: AppInferenceError?,
withdrawingFromTranscript: Bool) {
if withdrawingFromTranscript {
outputPromptText = ""
outputText = ""
generationTranscriptMailbox?.reset()
}
// Dropped, never released: these are the same links the turn below is
// carrying, and deleting them here handed the composer back a set of
// pictures whose files had just been removed. Only when they are this
// message's, though. A refusal before the model saw the turn — a
// request that did not validate, a retain that failed — reaches here
// with the live fields still drawing the previous turn, and clearing
// them made that turn's pictures vanish from the transcript.
var own: Set<UUID> = []
for image in turn.images { own.insert(image.id) }
var drawsThisMessage = withdrawingFromTranscript
for image in outputImageAttachments {
if let staged = image.staged, own.contains(staged.id) {
drawsThisMessage = true
}
}
if drawsThisMessage {
outputImageAttachments = []
}
if promptText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
promptText = turn.prompt
}
if imageAttachments.isEmpty {
imageAttachments = turn.images
} else {
// The composer was used again while the turn was in flight, and its
// copies are the ones the next send will carry.
for attachment in turn.images { attachmentStore.remove(attachment) }
}
if let error { self.error = error }
}
public func cancel() {
guard canCancel else { return }
isCancellationPending = true
client.cancel()
}
/// The request the composer would build right now, for the callers that
/// only need to know whether what is in it is valid.
public func makeRequest(
ticket: AppConversation.Ticket? = nil
) throws -> AppGenerationRequest {
try makeRequest(
PreparedTurn(prompt: promptText, images: imageAttachments),
ticket: ticket)
}
/// The request one message makes.
///
/// Built from the turn rather than from the composer, which the send path
/// emptied before this is reached and which may already hold the next
/// message.
func makeRequest(
_ turn: PreparedTurn,
ticket: AppConversation.Ticket? = nil
) throws -> AppGenerationRequest {
// A run executes against the session that is actually loaded. Sending
// the current settings instead meant that changing Context, Slots or
// image residency and pressing Generate — without reloading first —
// was refused outright with "generation runtime options do not match
// the loaded session". The settings still apply on reload, which is
// what the Memory section promises; they simply no longer break the
// run in the meantime.
let effective = loadedRuntimeKey ?? currentRuntimeKey
let request = AppGenerationRequest(
modelDirectory: URL(fileURLWithPath: modelPathText),
prompt: turn.prompt,
imageAttachments: turn.images,
maxNewTokens: maxNewTokensOverride ?? effective.maxContextTokens,
maxContextTokens: effective.maxContextTokens,
temperature: Float(temperature),
topK: topKEnabled ? topK : nil,
topP: topKEnabled && topPEnabled ? Float(topP) : nil,
repetitionPenalty: 1.0,
runtimeOptions: effective.options(
prefillEnabled: runtimeOptions.prefillEnabled,
prefillChunkTokens: runtimeOptions.prefillChunkTokens),
// Carried whether or not a ticket exists: the image budget has to
// fit around the conversation even while the composer is only being
// validated.
// The decode service overrides this from its own gate, but the
// in-process client reads it directly — and without it that client
// ran every turn through the single-prompt path while the app drew a
// growing transcript, so the model saw only the newest message.
continuesConversation: ticket != nil,
// Unknown means the runtime committed a turn but did not report its
// position. Reserve the whole window: text can still continue on
// the service's own exact state, while every image fails closed.
conversationTokens: conversation.kvTokens ?? effective.maxContextTokens,
conversationEpoch: ticket?.epoch,
turnIndex: ticket?.index)
try request.validate(requireModelDirectory: true)
return request
}
func apply(_ event: AppInferenceEvent, generation: Int? = nil) {
guard generation == nil || generation == runIdentity else { return }
switch event {
case .memorySample:
sampleLiveMemory()
case .prefillProgress(let done, let total):
phase = .prefill
livePrefillDone = done
livePrefillTotal = total
sampleLiveMemory()
case .token(let token):
phase = .decode
liveTokenCount = token.index + 1
liveElapsedDecodeSeconds = token.elapsedDecodeSeconds
sampleLiveMemory()
if !token.textDelta.isEmpty {
outputText += token.textDelta
}
case .finished(let diagnostics):
visionTowerMappedBytes = diagnostics.visionTowerMappedBytes
finishSuccessfully(diagnostics)
case .cancelled(let diagnostics):
finishCancelled(diagnostics)
case .failed(let appError, let partial):
diagnostics = partial
materializeServiceTranscript()
finishWithError(appError)
}
}
private func finishSuccessfully(_ diagnostics: AppDiagnostics) {
guard !hasHandledTerminalEvent else { return }
hasHandledTerminalEvent = true
materializeServiceTranscript()
self.diagnostics = diagnostics
let userText = outputPromptText
let assistantText = outputText
conversation.completeTurn(text: outputText, diagnostics: diagnostics)
// Written here and nowhere else: this is the one path that commits a
// turn to the KV, so it is the one path where the transcript on disk
// and the model's context can be made to say the same thing. A turn
// that threw was rewound by the runtime and reaches `finishWithError`,
// which writes nothing.
enqueueCompletedTurnPersistence(
userText: userText, assistantText: assistantText,
diagnostics: diagnostics)
finishTerminalRun()
}
private func finishCancelled(_ diagnostics: AppDiagnostics) {
guard !hasHandledTerminalEvent else { return }
hasHandledTerminalEvent = true
materializeServiceTranscript()
self.diagnostics = diagnostics
error = .cancelled
// A `.cancelled` event means the run threw `CancellationError`, and the
// conversation rewound the turn: its tokens are not in the KV, and the
// service did not count it either. Counting it here put the app one
// ahead for the rest of the conversation, so the next turn carried an
// index the gate refused — and that refusal reached the user as
// "decode service runtime profile changed during generation".
//
// A stop that lands at a token boundary is a different event: the run
// returns normally with `.cancelled` as its *stop reason*, arrives as
// `.finished`, and is committed by `finishSuccessfully`.
// Not counted. The live fields are not part of `conversation.turns`, so
// what stays on screen is the stopped turn as the current one, exactly
// as the single-prompt path left it — the next run replaces it, and it
// never enters the history the transcript freezes.
//
// The turn itself is handed back rather than dropped: discarding it lost
// the user's message and stranded its retained image links, which the
// next run overwrote without releasing — one staged file per image,
// until quit. Recorded rather than handed back here: the send pipeline
// is holding the message, and it is the one place that gives it back.
if conversation.abandonTurn() != nil { turnOutcome = .rewound }
finishTerminalRun()
}
private func materializeServiceTranscript() {
guard let reporter = client as? any AppInferenceTranscriptReporting else { return }
outputText = reporter.generationTranscriptMailbox.completeText
}
private func finishWithError(_ appError: AppInferenceError) {
guard !hasHandledTerminalEvent else { return }
hasHandledTerminalEvent = true
error = appError
let abandoned: AppChatTurn?
if case .conversationLineageLost = appError {
// The transcript stays readable; nothing further can be sent until
// New chat.
abandoned = conversation.markLineageLost()
} else {
// The runtime rewound this turn, so it is in neither the KV nor the
// transcript. Give the user their message back instead of making
// them retype it.
abandoned = conversation.abandonTurn()
}
if abandoned != nil { turnOutcome = .rewound }
finishTerminalRun()
if case .connectionLost = appError {
recordLostServiceConnection(appError)
if let id = storedConversationID, let meta = history.entry(id) {
pendingServiceRecoveryConversationID = id
perform(machine.apply(.rowClicked(
id: id, heldID: id, kvMatchesHeld: false,
state: continuability(of: meta), renderID: UUID())))
}
}
}
/// The loaded model is gone with the decode service that held it.
///
/// One place for the state a lost connection leaves, reached by a
/// generation that ends on it and by a replay that does: the runtime key,
/// the memory readings and the epoch all belonged to a process that no
/// longer exists, and `.failed` is what puts Retry Load on screen.
func recordLostServiceConnection(_ appError: AppInferenceError) {
loadedRuntimeKey = nil
liveMemoryBytes = nil
liveResidentBytes = nil
loadState = .failed(appError)
serviceEpoch = nil
}
private func finishStreamFailure(_ appError: AppInferenceError, generation: Int) {
guard generation == runIdentity else { return }
materializeServiceTranscript()
finishWithError(appError)
}
private func finishTerminalRun() {
phase = .idle
runState = .idle
isCancellationPending = false
activeRunRuntimeKey = nil
endTurnWait(generation: runIdentity)
}
/// Releases the send's last stage.
///
/// Keyed on the run it belongs to: a stream from an abandoned run can close
/// long after the run that replaced it started, and resuming the newer
/// turn's wait would commit it before it had generated anything.
private func endTurnWait(generation: Int) {
guard let pending = turnCompletion, pending.generation == generation else {
return
}
turnCompletion = nil
pending.continuation.resume()
}
private func clearLoadTask(generation: UInt64) {
guard generation == loadGeneration else { return }
loadTask = nil
pendingExplicitLoadRuntimeKey = nil
}
private func clearUnloadTask(generation: UInt64) {
guard generation == unloadGeneration else { return }
unloadTask = nil
}
public func shutdownForTermination() {
guard !hasShutDownForTermination else { return }
hasShutDownForTermination = true
// Direct inspector bindings may have changed since the last saved action.
persistSettings()
client.cancel()
(client as? AppModelLifecycleClient)?.shutdownForTermination()
releaseAllAttachments()
}
}