Merge pull request #68 from gaelic-ghost/docs/roadmap-spi-status

release: prepare v1.1.0

Author: gaelic-ghost

README.md

@@ -17,7 +17,7 @@ SwiftASB helps Swift apps work with the local Codex app-server without making ap
 
 ### Status
 
-SwiftASB has a supported v1 public API for the core local Codex app-server lifecycle. `v1.0.3` is the current released baseline.
+SwiftASB has a supported v1 public API for the core local Codex app-server lifecycle. `v1.1.0` is the current released baseline.
 
 ### What This Project Is
 
@@ -33,7 +33,7 @@ Add SwiftASB from the GitHub package URL:
 
 https://github.com/gaelic-ghost/SwiftASB
 
-Use release `v1.0.3` or newer unless your project intentionally pins an older version.
+Use release `v1.1.0` or newer unless your project intentionally pins an older version.
 
 You also need a local Codex CLI installation with app-server support. SwiftASB looks for `codex` in the usual command-line locations, and apps can provide an exact executable path when they need stricter control.
 
@@ -45,7 +45,11 @@ For copy-pasteable startup code, open the DocC getting-started guide:
 
 Use SwiftASB when an app needs to show what Codex is doing right now, keep recent command and file activity visible, answer interactive requests, or build SwiftUI state around a running Codex turn.
 
-For app-wide sidebars and launchers, `CodexAppServer.makeLibrary()` provides observable stored-thread lists, cwd grouping, refresh actions, library-local selection state, and app-wide model, MCP, and hook diagnostics snapshots.
+For app-wide sidebars and launchers, `CodexAppServer.makeLibrary()` provides observable stored-thread lists, cwd or repository grouping, refresh actions, library-local selection state, and app-wide model, MCP, and hook diagnostics snapshots.
+
+Use `CodexAppServer.fs` when a sandboxed client needs filesystem metadata, directory listings, file bytes, file discovery, fuzzy file lookup, or file-change watches through the Codex app-server instead of reading local disk directly. `CodexWorkspace` carries app-server-owned workspace permission selections, active permission-profile provenance, and runtime filesystem/network permission facts for started threads and turns. Use `CodexAppServer.config` for effective config reads, and `CodexAppServer.extensions` for app, skill, plugin, and collaboration-mode inventory.
+
+Use `CodexAppServer.ThreadListQD`, `CodexFS.FileDiscoveryQD`, `CodexThread.HistoryWindowQD`, `CodexThread.RecentFilesQD`, and `CodexThread.RecentCommandsQD` when a client needs to preserve repeatable list, file-discovery, history-window, or recent-activity intent without depending on Core Data, SwiftData, direct filesystem reads, or raw app-server paging details.
 
 The generated Codex wire models are internal to this package. App code should use SwiftASB's public Swift types instead.
 

ROADMAP.md

@@ -98,6 +98,7 @@ actor ThreadHistoryStore {
         let forkedFromThreadID: String?
         let forkedFromTurnID: String?
         let gitBranch: String?
+        let gitOriginURL: String?
         let isArchived: Bool
         let isClosed: Bool
         let modelProvider: String
@@ -153,6 +154,7 @@ actor ThreadHistoryStore {
         let ephemeral: Bool
         let forkedFromThreadID: String?
         let gitBranch: String?
+        let gitOriginURL: String?
         let isArchived: Bool
         let isClosed: Bool
         let lastCompletedTurnAt: Int?
@@ -609,6 +611,7 @@ actor ThreadHistoryStore {
                 forkedFromThreadID: thread.forkedFromThreadID,
                 forkedFromTurnID: thread.forkedFromTurnID,
                 gitBranch: thread.gitBranch,
+                gitOriginURL: thread.gitOriginURL,
                 isArchived: thread.isArchived,
                 isClosed: thread.isClosed,
                 modelProvider: thread.modelProvider,
@@ -896,6 +899,7 @@ actor ThreadHistoryStore {
         thread.ephemeral = info.ephemeral
         thread.forkedFromThreadID = info.forkedFromThreadID
         thread.gitBranch = info.gitInfo?.branch
+        thread.gitOriginURL = info.gitInfo?.originURL
         thread.modelProvider = info.modelProvider
         thread.name = info.name
         thread.preview = info.preview
@@ -1062,6 +1066,7 @@ actor ThreadHistoryStore {
             ephemeral: thread.ephemeral,
             forkedFromThreadID: thread.forkedFromThreadID,
             gitBranch: thread.gitBranch,
+            gitOriginURL: thread.gitOriginURL,
             isArchived: thread.isArchived,
             isClosed: thread.isClosed,
             lastCompletedTurnAt: Self.lastCompletedTurnAt(for: thread),
@@ -1450,6 +1455,7 @@ actor ThreadHistoryStore {
             attribute("forkedFromThreadID", .stringAttributeType, isOptional: true),
             attribute("forkedFromTurnID", .stringAttributeType, isOptional: true),
             attribute("gitBranch", .stringAttributeType, isOptional: true),
+            attribute("gitOriginURL", .stringAttributeType, isOptional: true),
             attribute("modelProvider", .stringAttributeType, isOptional: false),
             attribute("name", .stringAttributeType, isOptional: true),
             attribute("preview", .stringAttributeType, isOptional: false),
@@ -1679,6 +1685,7 @@ final class HistoryThread: NSManagedObject {
     @NSManaged var forkedFromThreadID: String?
     @NSManaged var forkedFromTurnID: String?
     @NSManaged var gitBranch: String?
+    @NSManaged var gitOriginURL: String?
     @NSManaged var id: String
     @NSManaged var isArchived: Bool
     @NSManaged var isClosed: Bool

Sources/SwiftASB/Generated/CodexWire/Latest/CodexLifecycleV2Batch+JSONValue.swift

@@ -15,6 +15,9 @@ enum CodexAppServerProtocolEvent: Equatable, Sendable {
 	case threadClosed(CodexWireThreadClosedNotification)
 	case threadNameUpdated(CodexWireThreadNameUpdatedNotification)
 	case threadTokenUsageUpdated(CodexWireThreadTokenUsageUpdatedNotification)
+	case threadGoalUpdated(CodexWireThreadGoalUpdatedNotification)
+	case threadGoalCleared(CodexWireThreadGoalClearedNotification)
+	case fsChanged(CodexWireFSChangedNotification)
 	case hookStarted(CodexWireHookStartedNotification)
 	case hookCompleted(CodexWireHookCompletedNotification)
 	case warning(CodexWireWarningNotification)
@@ -54,6 +57,8 @@ struct CodexProtocolModelProviderCapabilitiesReadResponse: Decodable, Equatable,
     let webSearch: Bool
 }
 
+struct CodexProtocolCollaborationModeListParams: Encodable, Equatable, Sendable {}
+
 struct CodexProtocolThreadMetadataUpdateParams: Encodable, Equatable, Sendable {
     let gitInfo: GitInfo?
     let threadID: String
@@ -139,6 +144,7 @@ struct CodexProtocolThreadResumeParams: Encodable, Equatable, Sendable {
     let excludeTurns: Bool?
     let model: String?
     let modelProvider: String?
+    let permissions: CodexWirePermissionProfileSelectionParams?
     let personality: CodexWirePersonality?
     let sandbox: CodexWireSandboxMode?
     let serviceName: String?
@@ -155,6 +161,7 @@ struct CodexProtocolThreadResumeParams: Encodable, Equatable, Sendable {
         case excludeTurns
         case model
         case modelProvider
+        case permissions
         case personality
         case sandbox
         case serviceName
@@ -174,6 +181,7 @@ struct CodexProtocolThreadForkParams: Encodable, Equatable, Sendable {
     let excludeTurns: Bool?
     let model: String?
     let modelProvider: String?
+    let permissions: CodexWirePermissionProfileSelectionParams?
     let personality: CodexWirePersonality?
     let sandbox: CodexWireSandboxMode?
     let serviceName: String?
@@ -191,6 +199,7 @@ struct CodexProtocolThreadForkParams: Encodable, Equatable, Sendable {
         case excludeTurns
         case model
         case modelProvider
+        case permissions
         case personality
         case sandbox
         case serviceName