Ship afm-server 1.1.0 beta 3

Author: mikedoise

README.md

@@ -15,7 +15,7 @@ Built by [Techopolis](https://techopolisonline.com).
 - **Guardrail Recovery**: Automatic session eviction on safety violations prevents refusal spirals — a single bad message does not poison the entire conversation
 - **Soft Refusal Detection**: Detects when the model returns a refusal as normal text (not an exception) and resets the session to keep follow-up messages working
 - **Concurrency Control**: Configurable semaphore limits concurrent inference calls (default 3) with FIFO queuing for additional requests
-- **Tool Calling**: File system tools (read, write, edit, delete, move, list directory, create directory, check path)
+- **Tool Calling**: OpenAI-compatible delegated tool calls for agent harnesses, plus server-local file and terminal tools for built-in/local requests
 - **Auto-Updates**: Sparkle 2 checks for updates daily and shows a dock badge when one is available
 - **Privacy First**: All processing happens on-device — no data leaves your Mac
 
@@ -358,7 +358,7 @@ For comparison, you can also configure cloud-hosted models in Xcode 26 Intellige
 
 Visit [OpenRouter.ai](https://openrouter.ai) to get an API key that provides access to models from Anthropic, OpenAI, Google, and others through a single endpoint.
 
-However, afm-server offers the advantage of completely local, private AI assistance without requiring API keys or incurring usage costs.
+However, afm-server offers the advantage of completely local, private AI assistance without cloud API keys or usage costs. The local server still uses a user-configurable API key to protect its loopback endpoints.
 
 ### Cursor IDE
 
@@ -392,26 +392,38 @@ Any application that supports custom OpenAI API endpoints can use afm-server:
 
 - Set the API base URL to `http://127.0.0.1:11435/v1`
 - Use `apple.local` as the model name
-- API key is not required (but can be set to any value if the client requires it)
+- Set the client API key to the value shown in afm-server Settings or the dashboard API Key card
+- afm-server accepts that key as `Authorization: Bearer <API key>`
 
 ## Tool Calling
 
-The server supports tool calling for file operations within a sandboxed workspace:
+afm-server supports two tool paths:
 
-### Available Tools
+### Client-Delegated Tools
 
-- `read_file`: Read file contents
-- `write_file`: Create or write content to a file
-- `edit_file`: Modify a file by replacing text
-- `delete_file`: Remove a file
-- `move_file`: Move or rename a file
-- `list_directory`: List directory contents
-- `create_directory`: Create new directories
-- `check_path`: Check if a path exists and get its type
+When an OpenAI-compatible client sends a `tools` array to `POST /v1/chat/completions`, afm-server behaves like a model backend. It can return an assistant message with `tool_calls` and `finish_reason: "tool_calls"`. The connecting client, such as Pi, Hermes, OpenClaw, or another coding harness, is responsible for executing those tools on the client machine and sending the results back as `role: "tool"` messages.
+
+This is the correct path for agentic coding work because the harness owns the workspace, terminal, approvals, and tool registry.
+
+Streaming requests also emit OpenAI-style `delta.tool_calls` chunks so clients that keep `stream: true` can still see tool calls.
+
+### Server-Local Tools
+
+When no client tools are provided, afm-server can use Apple Foundation Models native Swift tools for local file and terminal requests. These tools run inside the afm-server process on the Mac hosting the server:
+
+- `bash`: Execute a short shell command on the server Mac
+- `read_file`: Read file contents on the server Mac
+- `write_file`: Create or write content to a file on the server Mac
+- `edit_file`: Modify a file by replacing text on the server Mac
+- `delete_file`: Remove a file on the server Mac
+- `move_file`: Move or rename a file on the server Mac
+- `list_directory`: List directory contents on the server Mac
+- `create_directory`: Create new directories on the server Mac
+- `check_path`: Check if a path exists and get its type on the server Mac
 
 ### Workspace Configuration
 
-Set the `PI_WORKSPACE_ROOT` environment variable to specify the root directory for file operations. If not set, it defaults to your Documents folder.
+Set the `PI_WORKSPACE_ROOT` environment variable to specify the root directory for server-local file operations. If not set, it defaults to your Documents folder.
 
 ```bash
 export PI_WORKSPACE_ROOT=/path/to/your/workspace

afm-server-1.1.0-beta.3.dmg

@@ -270,7 +270,7 @@
 				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
 				CODE_SIGN_ENTITLEMENTS = "afm-server/afm-server.entitlements";
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 2;
+				CURRENT_PROJECT_VERSION = 3;
 				DEVELOPMENT_TEAM = M9SNPTXA44;
 				ENABLE_APP_SANDBOX = YES;
 				ENABLE_HARDENED_RUNTIME = YES;
@@ -295,7 +295,7 @@
 				LD_RUNPATH_SEARCH_PATHS = "@executable_path/Frameworks";
 				"LD_RUNPATH_SEARCH_PATHS[sdk=macosx*]" = "@executable_path/../Frameworks";
 				MACOSX_DEPLOYMENT_TARGET = 26.0;
-				MARKETING_VERSION = 1.1.0-beta.2;
+				MARKETING_VERSION = 1.1.0-beta.3;
 				PRODUCT_BUNDLE_IDENTIFIER = "online.techopolis.afm-server";
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				REGISTER_APP_GROUPS = YES;
@@ -318,7 +318,7 @@
 				ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
 				CODE_SIGN_ENTITLEMENTS = "afm-server/afm-server.entitlements";
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 2;
+				CURRENT_PROJECT_VERSION = 3;
 				DEVELOPMENT_TEAM = M9SNPTXA44;
 				ENABLE_APP_SANDBOX = YES;
 				ENABLE_HARDENED_RUNTIME = YES;
@@ -343,7 +343,7 @@
 				LD_RUNPATH_SEARCH_PATHS = "@executable_path/Frameworks";
 				"LD_RUNPATH_SEARCH_PATHS[sdk=macosx*]" = "@executable_path/../Frameworks";
 				MACOSX_DEPLOYMENT_TARGET = 26.0;
-				MARKETING_VERSION = 1.1.0-beta.2;
+				MARKETING_VERSION = 1.1.0-beta.3;
 				PRODUCT_BUNDLE_IDENTIFIER = "online.techopolis.afm-server";
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				REGISTER_APP_GROUPS = YES;

afm-server-1.1.0-beta.3.zip

@@ -78,7 +78,7 @@ struct AFMServerApp: App {
     #endif
 
     init() {
-        // Server auto-starts on launch via the MenuBarExtra .task modifier
+        // Server auto-starts on launch via ServerController.
     }
 
     var body: some Scene {

afm-server.xcodeproj/project.pbxproj

@@ -76,7 +76,7 @@ final class AppLogStore: ObservableObject {
     }
 }
 
-enum AppLog {
+nonisolated enum AppLog {
     private static let logger = Logger(subsystem: "online.techopolis.afm-server", category: "AppLog")
 
     static func debug(_ message: String, source: String = "app") {

afm-server/AFMServerApp.swift

@@ -7,6 +7,9 @@
 
 import Foundation
 import OSLog
+#if canImport(Darwin)
+import Darwin
+#endif
 
 #if canImport(FoundationModels)
 import FoundationModels
@@ -19,7 +22,7 @@ import FoundationModels
 nonisolated final class FileToolsManager: @unchecked Sendable {
     static let shared = FileToolsManager()
 
-    private let logger = Logger(subsystem: "com.example.PerspectiveIntelligence", category: "FileTools")
+    private let logger = Logger(subsystem: "online.techopolis.afm-server", category: "FileTools")
     private let fm = FileManager.default
 
     /// The allowed root directories for file operations.
@@ -76,6 +79,25 @@ nonisolated final class FileToolsManager: @unchecked Sendable {
     /// Resolves a path to an absolute URL, handling ~ expansion and relative paths
     func resolvePath(_ path: String) -> URL {
         var resolvedPath = path
+        let trimmedPath = resolvedPath.trimmingCharacters(in: .whitespacesAndNewlines)
+        let lowerPath = trimmedPath.lowercased()
+        let developerExactMatches = ["developer", "~/developer", "~/desktop/developer"]
+        let developerPrefixes = ["developer/", "~/developer/", "~/desktop/developer/"]
+
+        for prefix in developerExactMatches where lowerPath == prefix {
+            let developerURL = fm.homeDirectoryForCurrentUser.appendingPathComponent("Developer")
+            return developerURL.standardized
+        }
+
+        for prefix in developerPrefixes where lowerPath.hasPrefix(prefix) {
+            let suffixStart = trimmedPath.index(trimmedPath.startIndex, offsetBy: min(prefix.count, trimmedPath.count))
+            let suffix = String(trimmedPath[suffixStart...]).trimmingCharacters(in: CharacterSet(charactersIn: "/"))
+            var developerURL = fm.homeDirectoryForCurrentUser.appendingPathComponent("Developer")
+            if !suffix.isEmpty {
+                developerURL.appendPathComponent(suffix)
+            }
+            return developerURL.standardized
+        }
 
         // Expand ~ to home directory
         if resolvedPath.hasPrefix("~/") {
@@ -447,6 +469,106 @@ nonisolated struct PathCheckResult: Codable, Sendable {
     let size: Int?
 }
 
+nonisolated struct TerminalCommandResult: Codable, Sendable {
+    let command: String
+    let workingDirectory: String
+    let exitCode: Int32?
+    let timedOut: Bool
+    let durationSeconds: Double
+    let output: String
+    let truncated: Bool
+    let fullOutputPath: String?
+}
+
+nonisolated enum TerminalCommandRunner {
+    private static let maxOutputBytes = 64 * 1024
+
+    static func run(command: String, workingDirectory: URL, timeoutSeconds: Int) async throws -> TerminalCommandResult {
+        try await Task.detached(priority: .utility) {
+            let timeout = min(max(timeoutSeconds, 1), 120)
+            let fm = FileManager.default
+            let outputURL = fm.temporaryDirectory
+                .appendingPathComponent("afm-terminal-\(UUID().uuidString).log")
+
+            fm.createFile(atPath: outputURL.path, contents: nil)
+            let outputHandle = try FileHandle(forWritingTo: outputURL)
+            defer {
+                try? outputHandle.close()
+            }
+
+            let process = Process()
+            process.executableURL = URL(fileURLWithPath: "/bin/zsh")
+            process.arguments = ["-lc", command]
+            process.currentDirectoryURL = workingDirectory
+            process.standardOutput = outputHandle
+            process.standardError = outputHandle
+
+            let startedAt = Date()
+            try process.run()
+
+            let deadline = Date().addingTimeInterval(TimeInterval(timeout))
+            var timedOut = false
+
+            while process.isRunning {
+                if Date() >= deadline {
+                    timedOut = true
+                    process.terminate()
+                    break
+                }
+                try await Task.sleep(nanoseconds: 50_000_000)
+            }
+
+            if timedOut {
+                let killDeadline = Date().addingTimeInterval(2)
+                while process.isRunning && Date() < killDeadline {
+                    try await Task.sleep(nanoseconds: 50_000_000)
+                }
+                #if canImport(Darwin)
+                if process.isRunning {
+                    kill(process.processIdentifier, SIGKILL)
+                }
+                #endif
+            }
+
+            process.waitUntilExit()
+            try? outputHandle.close()
+
+            let duration = Date().timeIntervalSince(startedAt)
+            let attrs = try? fm.attributesOfItem(atPath: outputURL.path)
+            let fileSize = attrs?[.size] as? UInt64 ?? 0
+            let truncated = fileSize > UInt64(maxOutputBytes)
+            let outputData: Data
+
+            let readHandle = try FileHandle(forReadingFrom: outputURL)
+            defer {
+                try? readHandle.close()
+            }
+
+            if truncated {
+                try readHandle.seek(toOffset: fileSize - UInt64(maxOutputBytes))
+                outputData = readHandle.readDataToEndOfFile()
+            } else {
+                outputData = readHandle.readDataToEndOfFile()
+                try? fm.removeItem(at: outputURL)
+            }
+
+            let output = String(data: outputData, encoding: .utf8)
+                ?? String(decoding: outputData, as: UTF8.self)
+
+            return TerminalCommandResult(
+                command: command,
+                workingDirectory: workingDirectory.path,
+                exitCode: timedOut ? nil : process.terminationStatus,
+                timedOut: timedOut,
+                durationSeconds: duration,
+                output: output.isEmpty ? "(no output)" : output,
+                truncated: truncated,
+                fullOutputPath: truncated ? outputURL.path : nil
+            )
+        }.value
+    }
+}
+
 // MARK: - Foundation Models Tool Definitions
 
 #if canImport(FoundationModels)
@@ -492,7 +614,7 @@ nonisolated struct WriteFileTool: Tool {
 
     func call(arguments: Arguments) async throws -> String {
         // Log that the tool was called
-        let logger = Logger(subsystem: "com.example.PerspectiveIntelligence", category: "WriteFileTool")
+        let logger = Logger(subsystem: "online.techopolis.afm-server", category: "WriteFileTool")
         logger.log("[WriteFileTool] CALLED with path=\(arguments.path, privacy: .public)")
 
         let result = try FileToolsManager.shared.writeFile(
@@ -594,11 +716,11 @@ nonisolated struct MoveFileTool: Tool {
 @available(iOS 26.0, macOS 26.0, visionOS 26.0, *)
 nonisolated struct ListDirectoryTool: Tool {
     let name = "list_directory"
-    let description = "List contents of a directory"
+    let description = "List contents of a local directory. Use ~/Developer for the user's Developer folder."
 
     @Generable
     struct Arguments {
-        @Guide(description: "The absolute path to the directory")
+        @Guide(description: "Directory path, such as ~/Developer or ~/Downloads")
         let path: String
 
         @Guide(description: "If true, list recursively (default false)")
@@ -658,4 +780,40 @@ nonisolated struct CheckPathTool: Tool {
         return String(data: data, encoding: .utf8) ?? ""
     }
 }
+
+@available(iOS 26.0, macOS 26.0, visionOS 26.0, *)
+nonisolated struct BashTerminalTool: Tool {
+    let name = "bash"
+    let description = "Execute a short local terminal command and return stdout plus stderr. Use this for real local facts, repo checks, git status, ls, rg, find, build, and test commands."
+
+    @Generable
+    struct Arguments {
+        @Guide(description: "The shell command to execute, such as pwd, ls -la ~/Developer, git status --short, or rg -n pattern")
+        let command: String
+
+        @Guide(description: "Working directory for the command. Use ~/Developer or a project path when relevant. Defaults to the user's home directory.")
+        let workingDirectory: String?
+
+        @Guide(description: "Timeout in seconds. Defaults to 10 and is capped at 120.")
+        let timeoutSeconds: Int?
+    }
+
+    func call(arguments: Arguments) async throws -> String {
+        let cwd = try FileToolsManager.shared.validatePath(arguments.workingDirectory ?? "~")
+        var isDirectory: ObjCBool = false
+        guard FileManager.default.fileExists(atPath: cwd.path, isDirectory: &isDirectory), isDirectory.boolValue else {
+            throw FileToolsManager.FileToolError.isNotDirectory(cwd.path)
+        }
+
+        let result = try await TerminalCommandRunner.run(
+            command: arguments.command,
+            workingDirectory: cwd,
+            timeoutSeconds: arguments.timeoutSeconds ?? 10
+        )
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = .prettyPrinted
+        let data = try encoder.encode(result)
+        return String(data: data, encoding: .utf8) ?? ""
+    }
+}
 #endif