![\"\"](\"https://alejandromp.com/development/blog/sandboxing-an-ai-harness-on-macos/giphy.gif\")
A few weeks ago I read An Interpreter for Swift, from Cocoanetics, and I had that nice feeling of somebody else having already articulated the thing that was vaguely floating in your head.
Let me just say it outright: I get very sad every time somebody insists that TypeScript is the future of agentic coding. So I kept sending my wish to the universe that Swift should be also in the race for that. Now – finally – I was able to manifest the missing piece: an interpreter for the language I love. - Cocoanetics
That resounded inside me as I’ve always thought that Swift was the ideal language for this. And if I am already building a tiny Swift AI harness to learn how these systems work, then this felt like the perfect place to test the idea. So I immediately knew I had to try using this Swift interpreter in the harness. Even if the project is still tiny and mostly for learning, I thought it could still be useful.
In the previous post I had already replaced the little file toolbox with bash, mostly to see what happened if I stopped pretending those file tools were anything other than wrappers around shell commands.
So we were already in a good position to perform the next part of the experiment and answer, what if the generic tool was not bash, but Swift?
Instead of letting the model write shell, let it write whatever top-level Swift it needs to accomplish the task. That sounds much nicer to me already.
Want the finished project?
The whole point of this post is that you build it yourself, and all the important ideas are already here. But if you want to support my writing, or you just want to save time, I packaged the project for you to download.
The most obvious version of the idea is very simple. Keep the harness the same. Just replace bash with a swift tool. Let the model write top-level Swift, and call out to the compiler to execute it.
That would definitely work, but running real Swift brings the whole toolchain with it. Module caches. Compiler behavior. We all know that running Swift means going through a compilation step, and that is not the fastest thing in the world, especially if we need to start a new compiler process every time. And given LLMs might roundtrip many times to accomplish a task, any gains we get here are worth it. It is the usual reality of “this is a language toolchain”, not “this is a tiny embedded runtime”.
It also means we have the security issues we had with Bash, we can still use Seatbelt of course, but maybe we can take this chance to do better.
And finally, I just wanted to use the Swift Interpreter. Despite not being an official solution, it looks very promising and useful, and like something that should have been taken more seriously over the years. I still think Swift is the best language even for scripting, but performance is not there. So in my head there have always been two options: increase the performance of the toolchain and be as fast as Jai, or accept the limits and make a faster interpreter. So what we have here now, despite not coming from the core team, lets us prove the second idea.
That is where SwiftScript becomes interesting.
SwiftScript is a tree-walking Swift interpreter that you can embed as a library. No swiftc. No shelling out to swift -e. Just parse Swift and interpret it.
Now the swift tool is not another subprocess. It can just be part of the harness itself. So we just make a new ToolDefinition that looks very similar to the bash one.
static func swift() -> Self {\n ToolDefinition(\n name: "swift",\n description: "Run top-level Swift code directly inside the harness process, using SwiftScript as the execution engine and ShellKit for workspace confinement.",\n arguments: ["code"],\n run: { arguments, workspaceRoot in\n let code = arguments["code"] ?? ""\n let result = await SwiftScriptToolRunner.executeInProcess(\n code: code,\n at: workspaceRoot\n )\n\n return if result.exitCode == "ExitStatus(0)",\n let stdout = result.stdout.nonEmpty {\n stdout\n } else {\n executionResultJSON(\n stdout: result.stdout,\n stderr: result.stderr,\n exitCode: result.exitCode\n )\n }\n }\n )\n}\nThis was the next question I had to understand. I have experience writing interpreters and things are easy when you just need to exercise pure code. Interpreting a syntax tree that wants a mathematical computation is trivial, but things get trickier when you start talking about I/O and other features that need to interact with an “environment”.
So we have an interpreter that we can embed and it knows how to run Swift, but what is the environment around it? Where does print go? What is the current directory? How do file APIs know what to allow?
This is where ShellKit, another library from the same author, enters the picture.
SwiftScript’s interpreter defaults to using Shell.current for output and runtime context, and ShellKit lets an embedder install a custom Shell for the current async task with withCurrent { ... }.
So the actual execution path ends up looking like this:
let shell = Shell(\n stdout: stdoutSink,\n stderr: stderrSink,\n environment: .synthetic(workingDirectory: workspaceRoot.path),\n scriptName: "<swift-tool>",\n sandbox: try? makeSandbox(...)\n)\n\nlet interpreter = Interpreter()\n\nlet status = try await shell.withCurrent {\n try await interpreter.evalScript(code, fileName: "<swift-tool>")\n}\nThat withCurrent call is the key. It binds our synthetic shell as Shell.current for the duration of the script.
So when interpreted Swift does things that route through the ShellKit bridge, it sees:
That was one of those nice moments where the implementation becomes less magical after you read it. The interpreter is not doing anything mysterious. It is just running inside a runtime context we provide.
This change is already feeling better than just running bash. Not because Swift is “safer” in some abstract sense, but because the execution model is narrower and more controlled.
With bash, the natural shape of the tool is “here is a shell, good luck, have fun”. With the embedded SwiftScript, the natural shape is “here is an interpreter we host, and here is the runtime context we chose to expose”. That is a very different starting point.
And of course this could be accomplished too by using some bash shell virtualizer, but that’s not why we are here today ^^.
If the one-tool experiment is supposed to give the model a general-purpose language, Swift feels like a great candidate.
The good part is that the interpreter is not just floating there in the void. It runs inside the virtualized shell we control, and ShellKit gives that shell a sandbox too.
So when we build the shell for the swift tool, we can attach a policy like this:
return Sandbox(\n documentsDirectory: workspaceRoot,\n downloadsDirectory: workspaceRoot,\n libraryDirectory: workspaceRoot.appendingPathComponent(".swift-script-library", isDirectory: true),\n temporaryDirectory: temporaryDirectory,\n homeDirectory: workspaceRoot,\n authorize: { url in\n guard url.isFileURL else {\n guard let host = url.host, host.isEmpty == false else {\n throw Sandbox.Denial(url: url, reason: "non-file URL has no host to authorize")\n }\n return\n }\n\n let resolved = url.standardizedFileURL.resolvingSymlinksInPath()\n let path = resolved.path\n\n if path == gitDirectory.path || path.hasPrefix(gitDirectory.path + "/") {\n throw Sandbox.Denial(url: url, reason: "the Swift tool cannot access .git")\n }\n\n if isAllowed(path: path, under: workspaceRoot.path)\n || isAllowed(path: path, under: globalSkillsRoot.path)\n || isAllowed(path: path, under: temporaryDirectory.path) {\n return\n }\n\n throw Sandbox.Denial(url: url, reason: "file URL is outside the Swift tool sandbox")\n }\n)\nThat is already a much nicer situation than bash.
The interpreter gets a view of the world that we shape. It can read the workspace, the user-level skills directory, a temp directory, and it can also make network requests through the bridged APIs. It cannot touch .git. It cannot just wander off into the rest of the machine through the bridged file APIs.
So due to this, my first instinct was that SwiftScript plus ShellKit might already be enough. Once the execution model moves from bash to an embedded interpreter, the whole thing already feels much more controlled. There is no arbitrary shell pipeline by default. No compiler subprocess. No “just spawn more tools and see what happens” as the natural path.
But that still does not make the interpreter a hard security boundary.
The important distinction is that ShellKit.Sandbox is an in-process policy layer. It is very useful, but is different from an OS-enforced sandbox. It is also still part of the same process and the same runtime we are controlling so it also exposes our harness and the quality of our code to security attacks.
Another approach I took, but discarded to keep things simple, was to use the same embedded interpreter and shell sandbox, but spawning it in a separate process just like we did with bash. If we do that, then we can wrap that separate process in the same Seatbelt system and get yet an extra, OS-enforced layer, of protection.
sandbox-exec -p '<seatbelt profile>' swiftagentharness swift-script-helper 'print(40 + 2)'\nThis reminds me of when browsers started going multi-process for isolation. Even though for this learning harness keeping it simple seems enough thanks to ShellKit and the interpreter, it’s still interesting to see how an out-of-process system would play in practice.
At that point, the only interesting question left was the practical one. If I now run the harness with this swift tool, does it actually behave the way I want?
The answer was yes, at least for the kind of things that matter in this series.
The LLM can call the swift tool and just execute Swift:
<Step 1>\ntool-call: TOOL_CALL {"name":"swift","arguments":{"code":"print(40 + 2)"}}\ntool-success: swift -> 42\n<Step 2>\nAssistant: The Swift tool worked. It printed 42 from top-level Swift.\nIt can also use Foundation, inspect the workspace, and read files:
<Step 1>\ntool-call: TOOL_CALL {"name":"swift","arguments":{"code":"import Foundation ..."}}\ntool-success: swift -> cwd=/Users/me/code/swiftagentharness\ntop_level_count=11\ntop_level_sample=.agents,.build,.git,.gitignore,AGENTS.md,Package.resolved\npackage_lines=34\nagents_lines=6\n<Step 2>\nAssistant: The Swift tool worked and returned the requested result.\nSo from the LLM point of view, this already behaves much more like a real general-purpose language tool than a terminal wrapper.
And the sandbox does kick in when the script tries to escape:
<Step 1>\ntool-call: TOOL_CALL {"name":"swift","arguments":{"code":"import Foundation ... try \\"hello\\".write(toFile: \\"../escape.txt\\", atomically: true, encoding: .utf8)"}}\ntool-success: swift -> {"stdout":"","stderr":"file URL is outside the Swift tool sandbox\\n","exit_code":"interpreter-error"}\nWhich is exactly the kind of behavior I wanted. The model can read and write files, but only inside the world we decided to expose.
Of course, because this is still an interpreter library built by a single author and not some giant official runtime, there are parts of the surface that are not fully complete yet. That is fine. It still proves the point very well. The important thing is not that it supports every possible Swift API today. The important thing is that the one-tool experiment already feels real with Swift.
Replacing bash with embedded Swift is not just a gimmick. It genuinely changes the shape of the harness, and makes the one-tool experiment feel much more deliberate.
And I also like that the final answer is not perfectly clean.
The experiment did not end with “Swift replaces everything and all concerns disappear.” It ended somewhere more honest. Swift is a much nicer one-tool language than bash, embedding the interpreter is the interesting version of the idea, ShellKit gives that interpreter a controlled runtime context, and the question of hard sandboxing becomes smaller, but not completely gone.
Huge kudos to @cocoanetics, because this is already an impressive foundation for exploring ideas like this in practice. Like him, I wish the Swift project had an officially supported embeddable interpreter. It’s been many WWDCs now that I expected a “SwiftCoreKit” as an alternative to JavaScriptCore.
I’m very pleased with this exploration, not because I found the final perfect tool, but because the model around tool execution, shells and interpreters is clearer in my head now. I also had fun exploring Swift interpretation and out-of-process execution. For this series, that is the whole point.
", "date_published" : "2026-05-21T22:00:00Z", "id" : "https://alejandromp.com/development/blog/replacing-bash-with-swift-in-an-ai-harness", "summary" : "A few weeks ago I read An Interpreter for Swift, from Cocoanetics, and I had that nice feeling of somebody else having already articulated the thing that was vaguely floating in your head.", "tags" : [ "AI Development", "Swift", "Project" ], "title" : "Replacing Bash with Swift in an AI Harness", "url" : "https://alejandromp.com/development/blog/replacing-bash-with-swift-in-an-ai-harness" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "Skills are everywhere right now. People talk about them as if they were some magical incantation that will make AI more powerful while also keeping it under control.
But as with pretty much everything else in this space, once you look closely, it is much less mystical than it sounds. It is mostly markdown.
If you already understood how AGENTS.md works, then skills are not that different. They are just a more structured and reusable way of doing a very similar thing.
So the question I wanted to answer was simple. What does it actually take to teach skills to a tiny AI harness?
In its most basic form a skill is just a markdown file containing a reusable prompt for the LLM. Just like it happened with the AGENTS.md, the goal is to fill the context with useful information so the back and forth with the model improves.
In practice, a skill has a bit more. It also contains a bit of metadata and can contain extra files. For this, there is a standard for skills, which is honestly great because it means we are not talking only about one product’s private feature, but something compatible across harnesses.
The spec describes a skill as a folder with a markdown file called SKILL.md. That file contains the actual instructions in markdown, plus a bit of metadata like a name and a description as front matter.
That extra metadata is one of the most important aspects of skills since it lets harnesses follow a progressive disclosure principle. Skills can be discovered and loaded immediately, but just their name and description. Then, only when the skill is needed, the entire instruction content is loaded. This means the LLM context is not filled with unnecessary tokens. That progressive disclosure part is one of my favorite ideas here, unsurprisingly as it’s one of the core tenets of Swift language design.
It is funny too, because progressive disclosure is one of those principles that make so much sense for humans. Don’t dump everything at once. Show the right thing at the right moment. And it is interesting to see the same instinct apply to LLMs too.
The first actual implementation step is to find the skills themselves. As the standard and the harnesses I looked at support two locations, I wanted to implement the same. This would allow me to already test the harness with the real skills I’m using everywhere else.
There are two main locations where skills can live:
.agents/skills folder, for workflows that belong to the project~/.agents/skills folder, for global workflows available everywhereBut discovery is not only finding the right files and folders. It is also policy. And although the security of loading skills is not something we will get into here, it’s a can of worms that is worth considering. A repo-local skill that I wrote for the project is not the same thing as a skill I dumped into my home folder. So the harness has to decide not only where to scan, but also what kind of instructions it is willing to trust and surface automatically.
For our purposes, the actual code ended up being a small dedicated type for this. We can make a catalog type so the harness has specific knowledge and control of the skills.
struct SkillCatalog {\n let skills: [SkillDefinition]\n let workspaceSkillCount: Int\n let userSkillCount: Int\n\n static func load(workspaceRoot: URL, homeDirectory: URL = URL(fileURLWithPath: NSHomeDirectory())) -> Self {\n let workspaceSkills = loadSkills(\n in: workspaceRoot.appendingPathComponent(".agents/skills", isDirectory: true),\n source: .workspace\n )\n let userSkills = loadSkills(\n in: homeDirectory.appendingPathComponent(".agents/skills", isDirectory: true),\n source: .user\n )\n\n var discoveredByName = [String: SkillDefinition]()\n\n // Workspace skills load first, so they win name collisions.\n for skill in workspaceSkills + userSkills {\n let key = skill.name.lowercased()\n guard discoveredByName[key] == nil else { continue }\n discoveredByName[key] = skill\n }\n\n return SkillCatalog(\n skills: discoveredByName.values.sorted { ... },\n workspaceSkillCount: workspaceSkills.count,\n userSkillCount: userSkills.count\n )\n }\n}\nThe loader walks both directories recursively, looks for files named exactly SKILL.md, and builds an in-memory catalog.
That final step looks like this:
private static func loadSkill(at url: URL, source: SkillSource) -> SkillDefinition? {\n guard let content = try? String(contentsOf: url, encoding: .utf8) else {\n return nil\n }\n\n let parsed = parseSkillFile(content)\n let fallbackName = url.deletingLastPathComponent().lastPathComponent\n let name = parsed.metadata["name"]?.nonEmpty ?? fallbackName\n let description = parsed.metadata["description"]?.nonEmpty ?? "No description provided."\n\n return SkillDefinition(\n name: trimQuotes(from: name),\n description: trimQuotes(from: description),\n path: url,\n source: source\n )\n}\nAs you can see, the loop that loads the skills just skips entries whose name already exists. Since workspace skills are loaded first, that means they win collisions. If a repository wants to provide its own version of a skill, that should override my personal default for that session.
I also made the harness print what it discovered at startup, just like it already did for AGENTS.md. That way I can immediately verify that discovery is working before even asking the model to do anything:
Loaded workspace skills (2)\nLoaded user skills (29)\nDiscovered skills: harness-super-test, harness-swift-helper, agent-browser, ..., find-skills, ...\nLoaded AGENTS.md (11 lines)\nOnce the harness finds the skills, it has to parse them. The good part is that there is nothing special about it, if you’ve ever worked with a markdown-based static site generator, you will be familiar with YAML front matter. That’s what needs to be extracted, just the name and description. Maybe validate them a bit. But at this stage the harness does not keep the rest of the markdown in memory. It only keeps the catalog metadata and the path to the file.
Each discovered SKILL.md gets loaded as text. Then the harness looks for the front matter delimiters, parses the little metadata block, extracts name and description, and stores just enough information to build the catalog.
private static func parseSkillFile(_ content: String) -> (metadata: [String: String], instructions: String) {\n let lines = content.components(separatedBy: .newlines)\n\n guard lines.first == "---" else {\n return ([:], content.trimmingCharacters(in: .whitespacesAndNewlines))\n }\n\n var metadata = [String: String]()\n\n for line in lines.dropFirst() {\n if line == "---" { break }\n guard let separator = line.firstIndex(of: ":") else { continue }\n\n let key = line[..<separator].trimmingCharacters(in: .whitespaces)\n let value = line[line.index(after: separator)...].trimmingCharacters(in: .whitespaces)\n\n guard key.isEmpty == false, value.isEmpty == false else { continue }\n metadata[key] = value\n }\n\n return (metadata, content)\n}\nWe already have skills on disk. We already know what they are. We already know enough to tell the model they exist. But we have not paid the token cost of loading them all. Not yet.
We now have a catalog with the metadata of the available skills. The harness knows them, but the LLM still doesn’t. So just like with AGENTS.md, we now need to inject the catalog into the system prompt so it is available in the model context.
let catalog = skillCatalog.skills\n .map(\\.promptBlock)\n .joined(separator: "\\n")\n\nskillsPrompt = """\nAvailable skills:\nThese skills provide specialized instructions for specific tasks. When a task matches a skill's description, read the `SKILL.md` at the listed location before proceeding.\n<available_skills>\n\\(catalog)\n</available_skills>\n"""\nvar promptBlock: String {\n """\n <skill>\n name: \\(name)\n description: \\(description)\n location: \\(path.path)\n </skill>\n """\n}\nThat last field matters more than it may seem.
The location is what lets the model bridge the gap between “I know this skill exists” and “now I want to actually use it”. Without that field, the model would know the skill exists but would still need some other mechanism to get to the file.
And once that prompt change exists, we can finally test the interesting part.
Once the skills are in context, implicit activation is almost the purest version of the idea. The model sees that a skill exists, sees what it is for, and decides to load it when the task matches. We will look at explicit activation later, but this is the best place to start.
For this harness, that also means something very concrete. I am not going to add a special activate_skill tool right now. If the point of the project is learning, then I would rather keep the mechanism visible. The model sees a skill in the catalog, notices the path, and reads the file with the normal file-reading tool.
A dedicated activation tool is still a valid design, and maybe even the better one for a more serious agent. It gives tighter control, better permissions, and cleaner analytics. But for this harness it would hide the mechanism too early. I want to see the model load the markdown directly.
To make that work in practice, I had to do one small but important change. The harness already knew how to discover user-level skills in ~/.agents/skills, but the original implementation of the read_file tool and the sandbox would limit access to that directory because it sits outside the workspace.
So I updated two things:
read_file tool can now read both the workspace and ~/.agents/skillsbash can now read ~/.agents/skills toolet globalSkillsRoot = URL(fileURLWithPath: NSHomeDirectory())\n .appendingPathComponent(".agents/skills", isDirectory: true)\n .standardizedFileURL\n\nlet isInsideWorkspace = resolvedPath == rootPath || resolvedPath.hasPrefix(rootPath + "/")\nlet isInsideGlobalSkills = resolvedPath == globalSkillsPath || resolvedPath.hasPrefix(globalSkillsPath + "/")\n\nguard isInsideWorkspace || isInsideGlobalSkills else {\n throw HarnessError.workspaceViolation(path)\n}\n;; Global skills\n(allow file-read*\n (subpath "/Users/me/.agents/skills"))\nThat keeps the mechanism simple and visible. The model sees a skill in the catalog, notices the path, and reads the markdown like any other file.
Here is the local skill case:
<Turn 1>\nYou: Can you use the local harness-super-test skill?\n<Step 1>\nAssistant: I can use it, and I've loaded the local `harness-super-test` skill instructions. What would you like me to do with it?\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":".agents/skills/harness-super-test/SKILL.md"}}\ntool-success: read_file -> 10 lines\n<Step 2>\nAssistant: You now have super powers, you are a super harness.\n That phrasing came from the repo-local skill in `.agents/skills/harness-super-test`.\nAnd here is the global skill case:
<Turn 1>\nYou: Use the find-skills skill to search for the caveman skill, and read the skill file before proceeding.\n<Step 1>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"~/.agents/skills/find-skills/SKILL.md"}}\ntool-success: read_file -> 89 lines\n<Step 2>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"npx skills find caveman"}}\ntool-success: bash -> command succeeded\n<Step 3>\nAssistant: I used the `find-skills` skill and searched for `caveman`. I read the local `find-skills` skill first, then followed its workflow. The best match was...\nThat second example is important because it proves the whole chain in a very ordinary way. The catalog exposes a user-level skill, the model reads the file directly, and that file then guides the next action. There is no hidden magic layer in the middle. It is still just context plus tools.
A nice thing about the skills spec is that it allows for a skill to package extra resources. You might have noticed the skill shape: it is not a markdown file named as the skill, no. It’s a folder named as the skill, with a markdown file generically named SKILL.md inside. This is because there can be more.
The skill folder can contain other subfolders and files inside, which the main skill file can point to. More resources, reference docs, and even scripts. And again, all without polluting the context on load, just when it is needed. This is just progressive disclosure, one level deeper.
The previous local skill was intentionally tiny, just enough to make activation obvious. That was useful, but still a bit toy-like. So I added a second repo-local skill that feels a bit more like a real workflow:
It has a SKILL.md, a small reference note, and a tiny Swift helper script. That gave me a much better test, because now the skill was not just shaping the answer. It was guiding the model toward a concrete project-specific action using plain files and plain tools.
Here is the transcript:
<Turn 1>\nYou: Use the harness-swift-helper skill to summarize this package. Read the skill file first, follow its execution note, run the Swift helper, and then tell me the result.\n<Step 1>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":".agents/skills/harness-swift-helper/SKILL.md"}}\ntool-success: read_file -> 15 lines\n<Step 2>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":".agents/skills/harness-swift-helper/references/RUNNING.md"}}\ntool-success: read_file -> 16 lines\n<Step 3>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"swift .agents/skills/harness-swift-helper/scripts/package_summary.swift"}}\ntool-success: bash -> command succeeded\n<Step 4>\nAssistant: I read the `harness-swift-helper` skill, followed its execution note, ran the Swift helper, and here is the actual output:\n Package: swiftagentharness\n Platform...\nThat is exactly the kind of behavior I wanted to see. The helper script and the execution note were not sitting in the initial context from the start. The model loaded them only when the skill became relevant, and then used them to complete the task.
And this is yet another proof that skills are nothing magical, just reusable prompts that can easily package extra resources.
Doing explicit activation, where the user directly invokes a skill, can quickly turn into terminal UI and UX work instead of learning about AI and harnesses. I did not want to go down that rabbit hole here. But it still felt useful to dip our toes into it, if only to prove that explicit activation is also not magical.
So I built the smallest version worth having:
/skill-name [task]\nThat is it. No autocomplete. No picker. No search. No fancy terminal behavior.
When the harness sees an input line that starts with /, it checks whether the first token matches a discovered skill name. If it does, the harness reads that SKILL.md, injects it into the conversation, and then the loop continues as normal.
conversation.append(Message(role: "user", content: input))\nif let explicitSkillActivation = try resolveExplicitSkillActivation(from: input) {\n ui.printLine(\n "skill-load: /\\(explicitSkillActivation.skill.name) -> \\(explicitSkillActivation.skill.path.path)"\n )\n conversation.append(Message(\n role: "system",\n content: try explicitSkillSystemMessage(for: explicitSkillActivation)\n ))\n}\nAnd because I wanted this to be debuggable, the harness also prints a visible confirmation line in the terminal:
skill-load: /harness-swift-helper -> /Users/.../SKILL.md\nThat matters because we do not have to guess whether the harness explicitly loaded the skill, or whether the model later decided to read the file on its own. We can see it.
This is also the useful difference with implicit loading. There, we still depend on the model noticing that a skill is relevant. Here, the user decides first, and the harness makes sure those desires come true.
This is an important insight. It reinforces, again, that skills are nothing special, just text dumped into the context. Before, it was the LLM using the read tool to load that text. Now it is the harness doing it manually. After that, the loop just continues as usual. The fact that there are no other changes necessary clarifies a lot.
<Turn 1>\nYou: /find-skills caveman\nskill-load: /find-skills -> ~/.agents/skills/find-skills/SKILL.md\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"npx skills find caveman"}}\ntool-success: bash -> command succeeded\n<Step 2>\nAssistant: I found several `caveman`-related skills, including `juliusbrussee/caveman@caveman` and `mattpocock/skills@caveman`.\nWe can see how there was no read tool call. It was not necessary because the skill was already in the context, so the LLM could directly go and use bash as told by the skill. That means explicit invocation can save a round-trip, tokens, and cost.
This also affects the cost and behavior of different harnesses. For example, what happens if in the next turn we ask for something related?
<Turn 2>\nYou: and can you find the "web-search" one?\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"npx skills find web-search"}}\ntool-success: bash -> command succeeded\n<Step 2>\nAssistant: I found several web-search-related skills, including: ...\nYou can see how the model decided to use the skill again to answer our request. This time it did not have to load it again, because the information was already in the context. In this harness, that happens because the skill stays in the conversation. That is just a decision I made during the implementation. Some harnesses may keep the skill only on the demanded turn, clean it after a few turns, or reload it every time. These small decisions are part of what makes each harness feel distinct.
Better harnesses usually go much further here. They offer autocomplete, skill listing, filtering, search, and richer terminal interactions. I am intentionally stopping earlier. The point of this post is to demystify skills, not to deep dive into terminal UI. That can be its own journey later.
After walking through discovery, parsing, prompt disclosure, implicit loading, extra resources, and even a tiny explicit activation flow, I think the main lesson is simple.
Skills are not some new magical agent primitive. They are reusable prompts with a folder convention.
They can be great. They are also, at the end of the day, still mostly markdown. So think twice before jumping into the dogma hype train.
That is not diminishing them. If anything, I think that makes them more useful, because now the value is obvious. The harness is not growing a mysterious new organ. We are just giving the model a structured way to discover the right instructions, the right note, the right script, and only load them when they become relevant.
And because of that, all the usual context problems still apply. Pollution. Distraction. Conflicting instructions. Stale workflows. Too much noise. Skills do not escape any of that. They are just a cleaner way of doing context engineering.
The security side matters too. Pulling a random skill from the internet is letting somebody else inject instructions into an agent that may already have access to your files, your shell, your browser, whatever tools you gave it. We should all talk about that more.
So my recommendation is simple. Write your own skills. And if you find a good one online, take the core of the idea, read it carefully, tailor it, make it yours. The nice part is that once you stop treating skills like magic, that becomes trivial. They are mostly markdown, and the LLM can help you write them.
That is the real win for me. Not that skills are fancy. Not that they feel powerful. But that once you understand what they really are, you can shape them on purpose.
Want the finished project?
The whole point of this post is that you build it yourself, and all the important ideas are already here. But if you want to support my writing, or you just want to save time, I packaged the project for you to download.
In the previous post we gave superpowers to the harness in the form of a bash tool. Even doing it just for the learning experience, it was already very eye-opening. It made this little Swift harness feel much closer to the real thing.
And that is exactly why I don’t want to hand-wave the next part away.
We haven’t spent the time to make it production-ready, and we won’t because that’s not the purpose of this series. There are no carefully tuned prompts. No tailored rules for different models. No approval flows. No guardrails worth the name. It is just a tiny learning project.
But learning projects need to teach real lessons, and one of them is that giving an LLM shell access changes the nature of the problem immediately. It is no longer just “can the model inspect the project better?” It is also “what can this thing touch now, and what did I accidentally give it access to?”
So before happily moving on with the harness, I wanted to stop and look directly at that danger.
It’s easy to see what power we have given to the LLM:
<Turn 1>\nYou: Inspect this project and the surrounding projects so you can understand the environment better.\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"pwd && echo '--- ROOT ---' && ls -la && echo '--- PARENT ---' && ls -la .. && echo '--- GRANDPARENT ---' && ls -la ../../"}}\ntool-success: bash -> {"stdout":"\\/Users\\/me\\/code\\/swiftagentharness\\n--- ROOT --...\n<Step 2>\nAssistant: I inspected the current project and nearby directories.\nCurrent project:\n- `swiftagentharness`\n...\nSibling projects in `../`:\n...\nHigher-level directories in `../../`:\n...\nWe can see how even with the workspace guidance in the prompt, the model can easily use bash to escape the workspace.
It’s not hard to imagine what would happen if the model decided to use rm or inspect files that should be totally private, like credentials.
A common typical answer for this is to bring the cannons and use Docker to create a fully virtual and controlled environment so the AI can’t harm anything outside of it. And although that is the prevailing mentality across many developer communities, it’s not the only solution, nor the best or most elegant one.
So just for the sake of exploration and learning, let’s try something else. Let’s use native operating system tooling to sandbox execution. After all, if the entire revolution of mobile apps could happen with system sandboxes, surely we can benefit from the same work.
Before going further, I wanted to see whether this was one of those cases where I was overthinking it and everybody else had already moved on to some obvious better approach.
The short answer is no. The pattern I kept seeing was much more pragmatic.
OpenAI’s own local shell guide explicitly warns that running arbitrary shell commands can be dangerous and says you should sandbox execution or add strict allow and deny lists. That already tells us something important. Even if your product is all about agentic shell use, the default assumption is still that free execution is too much.
Claude Code’s sandboxing docs are probably the clearest public explanation of the approach. On macOS they use Seatbelt. On Linux they use bubblewrap. Filesystem access and network access are treated as two different problems, and all child processes inherit the same restrictions.
Anthropic also extracted that work into an open-source project, sandbox-runtime. Their README is very explicit about what it does: native OS sandboxing primitives plus proxy-based network filtering. That last bit is worth noticing. The serious versions of this don’t stop at filesystem restrictions.
Goose Desktop’s macOS sandbox docs show a very similar shape. Again, native sandboxing on macOS, plus extra machinery around network control.
And even when looking at OpenAI Codex in the wild, you can see the same reality leak through. OpenAI points to Codex CLI as a reference implementation from the shell guide, and their issue tracker has real macOS reports that mention the Seatbelt sandbox directly, like this network-related issue.
So the pattern seems pretty clear:
sandbox-exec.For me that is enough indication that is worth spending some time understanding Seatbelt and native sandboxing and seeing how it can improve our tiny harness.
Seatbelt is the low-level sandboxing facility in macOS. It is one of the pieces behind the strong sandboxing model Apple has used for years across macOS and iOS. So when we talk about app sandboxes and processes being limited by the operating system, this is the machinery that is under the hood.
That was already a good sign for this little experiment. If the whole mobile app world has been able to rely on OS sandboxing for such a long time, there is probably something useful here for us too, even if our use case is much smaller and much messier than a normal app. Apple’s own documentation around App Sandbox and the macOS App Sandbox configuration is mostly focused on proper app development, entitlements, containers, helper tools, and that whole world. That is not exactly our situation, but it tells us the underlying model is very real.
The slightly confusing part is that there is a difference between the modern Apple recommendation and the practical tool we can use from a little CLI harness.
The modern recommendation is App Sandbox. That is the official, entitlement-based way to sandbox a macOS app. But our harness is not a signed app with entitlements and containers. It is just a command-line tool that spawns /bin/bash.
That is where sandbox-exec comes in.
sandbox-exec is a command-line wrapper around that lower-level sandbox facility. You give it a policy, then tell it which command to run, and it launches that command under those restrictions. That is why it keeps showing up in agent harnesses and AI tools on macOS. It fits the shape of the problem much better than App Sandbox does.
The idea is very simple:
sandbox-exec -p '(version 1) ...rules here...' /bin/bash -lc 'pwd'\nThat -p argument is an inline sandbox profile. You can also load profiles from files, but for our tiny harness an inline profile is probably enough.
And this matters too: child processes inherit the sandbox. That means if we launch bash under Seatbelt restrictions, and then bash launches git, swift, ls, or anything else, those processes keep running inside the same boundary. That is exactly what we want. It would be quite useless to sandbox only the first command and then accidentally let the rest of the process tree escape 🤣.
There is one awkward detail though. Apple marks sandbox-exec as deprecated in the man page. So this is not me saying “this is the shiny modern blessed API.” It is more like “this is the old but still practical door into Seatbelt for command-line process sandboxing.” For our purposes, and also looking at what other harnesses are doing, that is still good enough to learn something real from it.
We already had a bash tool that used Subprocess.run. So we don’t have to redesign the whole harness around sandboxing. We just need a small change that can prove the idea.
Let’s start with preparing the sandbox as a custom method on Executable:
extension Executable {\n func runSandboxed<\n Input: InputProtocol,\n Output: OutputProtocol,\n Error: ErrorOutputProtocol\n >(\n arguments: [String] = [],\n environment: Environment = .inherit,\n workingDirectory: FilePath? = nil,\n input: Input = .none,\n output: Output,\n error: Error = .discarded,\n sandboxProfile: String\n ) async throws -> ExecutionRecord<Output, Error> {\n let resolvedExecutable = try self.resolveExecutablePath(in: environment)\n let wrappedArguments = ["-p", sandboxProfile, resolvedExecutable.string] + arguments\n\n return try await Subprocess.run(\n .path("/usr/bin/sandbox-exec"),\n arguments: Arguments(wrappedArguments),\n environment: environment,\n workingDirectory: workingDirectory,\n input: input,\n output: output,\n error: error\n )\n }\n}\nThis part is actually quite simple. We are still just spawning a process, but with the difference that instead of spawning /bin/bash directly, we spawn sandbox-exec, give it the Seatbelt profile, and then tell it to launch the real executable inside that sandbox.
Then the bash tool can just call this instead of the original Subprocess.run. I’ve added an argument to the harness to be able to use the sandbox only when desired, mostly to try the differences and for learning purposes.
let result = if sandboxEnabled {\n try await executable.runSandboxed(\n arguments: ["-c", command],\n workingDirectory: workingDirectory,\n output: capturedIO,\n error: capturedIO,\n sandboxProfile: SeatbeltProfile.workspaceBoundary(for: workspaceRoot)\n )\n} else {\n try await Subprocess.run(\n executable,\n arguments: ["-c", command],\n workingDirectory: workingDirectory,\n output: capturedIO,\n error: capturedIO\n )\n}\nThat shape was exactly what I wanted. The harness is still the same little harness. The bash tool is still the same bash tool. We are not replacing it with a different concept. We are just giving it a stricter execution path when sandboxing is enabled.
Just FYI, in my final implementation I also included a
sandboxsubcommand, that helped me run commands directly inside the sandbox without going through the LLM at all. That ended up being really handy for testing the profile itself without having to convince the LLM to do what I needed.
But of course, the interesting part is the profile.
I’m not gonna lie. I’m not an expert on sandboxing so what I’ve got working probably has flaws, but after some trial and error it seems to work for a few use cases. And that’s all I need for the learning process :)
For example, the first version was too strict and basically useless. Even pwd and ls were crashing. So this turned into a very practical exercise in seeing what macOS tools actually need to function under Seatbelt.
<Turn 1>\nYou: List the files in this project and summarize what it is. Use bash.\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"ls -la"}}\ntool-success: bash -> {"stdout":"","stderr":"","exit_code":"signaled(6)"}\nThe key unlock was importing Apple’s built-in system.sb base profile, and then layering our own file restrictions on top. After that, the profile started becoming actually useful instead.
(version 1)\n(deny default)\n(import "system.sb")\n\n;; Start from a deny-all profile, then re-allow only the minimum needed\n;; for "run bash inside the workspace" to work at all.\n(allow process-exec)\n(allow process-fork)\n(allow signal (target self))\n(allow sysctl-read)\n(allow mach-lookup)\n\n(allow file-read*\n (subpath "/Applications")\n (subpath "/bin")\n (subpath "/dev")\n (subpath "/System")\n (subpath "/usr")\n (subpath "/var/folders")\n (subpath "/private/var/folders")\n (subpath "/var/select")\n (subpath "/private/var/select")\n (subpath "<workspace>")\n (subpath "<sandbox-temp-directory>"))\n\n(allow file-read-metadata\n (literal "<workspace-parent>"))\n\n(allow file-write*\n (subpath "/var/folders")\n (subpath "/private/var/folders")\n (subpath "<workspace>")\n (subpath "<sandbox-temp-directory>"))\n\n(deny file-write*\n (subpath "<workspace>/.git"))\nIt’s all quite self explanatory but here is my own description of what’s happening:
bash, ls, git, swift, and friends need in practice, plus the workspace and dedicated sandbox temp directory.ls -la peeks at .. while listing the current directory.var/folders aliases that some commands use under the hood.Note that because we’re making a custom subfolder in the temporary directory, we have to update the bash tool instructions to include that path. Otherwise the LLM won’t have any clue where it can write temporary files.
Want the finished project?
The whole point of this post is that you build it yourself, and all the important ideas are already here. But if you want to support my writing, or you just want to save time, I packaged the project for you to download.
The nice part is that once this was in place we could actually test the boundary in a very concrete way.
<Turn 1>\nYou: run ls and pwd\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"pwd && ls"}}\ntool-success: bash -> {"stdout":"/Users/me/code/swiftagentharness\nAGENTS.md\nPackage.resolved\n...","stderr":"","exit_code":"exited(0)"}\n<Step 2>\nAssistant: /Users/me/code/swiftagentharness\nAGENTS.md\n...\n<Turn 2>\nYou: do it at the home folder\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"cd ~ && pwd && ls"}}\ntool-success: bash -> {"stdout":"/Users/me\n","stderr":"cd: error retrieving current directory: getcwd: cannot access parent directories: Operation not permitted\nls: .: Operation not permitted\n","exit_code":"exited(1)"}\n<Step 2>\nAssistant: Tried in `~`, but permissions prevented listing it.\nOutput: `/Users/me`\nErrors:\n- `getcwd: cannot access parent directories: Operation not permitted`\n- `ls: .: Operation not permitted`\n<Turn 3>\nYou: write it\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"printf 'workspace write test\\n' > scratch.txt && ls -l scratch.txt && cat scratch.txt"}}\ntool-success: bash -> {"stdout":"-rw-r--r--@ 1 me staff 21 ... scratch.txt\nworkspace write test\n","stderr":"","exit_code":"exited(0)"}\n<Step 2>\nAssistant: Wrote `scratch.txt` in the workspace successfully.\n<Turn 4>\nYou: prove that writing into .git failed\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"printf 'git dir write test\\n' > .git/scratch-test 2>&1; status=$?; if [ $status -eq 0 ]; then echo WRITE_OK; else echo WRITE_FAILED; fi; exit $status"}}\ntool-success: bash -> {"stdout":"WRITE_FAILED\n","stderr":"/bin/bash: .git/scratch-test: Operation not permitted\n","exit_code":"exited(1)"}\n<Step 2>\nAssistant: Writing into `.git` failed with `Operation not permitted`.\n<Turn 5>\nYou: prove that writing ../sandbox-escape.txt failed\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"printf 'escape test\\n' > ../sandbox-escape.txt 2>&1; status=$?; if [ $status -eq 0 ]; then echo WRITE_OK; else echo WRITE_FAILED; fi; exit $status"}}\ntool-success: bash -> {"stdout":"WRITE_FAILED\n","stderr":"/bin/bash: ../sandbox-escape.txt: Operation not permitted\n","exit_code":"exited(1)"}\n<Step 2>\nAssistant: Writing `../sandbox-escape.txt` failed with `Operation not permitted`.\n<Turn 0>\nYou: write a random file in a temporary file\n<Step 1>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"tmpfile=$(mktemp); head -c 32 /dev/urandom | base64 > \\"$tmpfile\\"; printf '%s' \\"$tmpfile\\""}}\ntool-success: bash -> {"stdout":"/var/folders/.../swiftagentharness-sandbox/<workspace-hash>/tmp.sjpO8WrRyF","stderr":"","exit_code":"exited(0)"}\n<Step 2>\nAssistant: Created a temporary file with random content at `/var/folders/.../swiftagentharness-sandbox/<workspace-hash>/tmp.sjpO8WrRyF`\nIt’s actually pretty cool to see that with so little we already have a more secure harness. Now there are some restrictions and safety around what we let the AI do. It still has bash superpowers, but now with a bit more responsibility.
Now, we need to be honest about what this is and what it is not. This does not make the harness “safe” in any absolute sense. It just makes it safer.
The profile still has to allow a bunch of system paths so normal commands can even run. That means this is not some perfect tiny prison where the process only knows about the repo. It is a constrained execution environment, sure, but it is not perfect isolation.
Also, this is not solving network access. Some of the more serious tools pair sandboxing with proxy-based network control. We are not doing that here. So this post is not a guide to production-grade AI isolation. It is a guide to learning how native sandboxing on macOS can help, and where it stops helping. Just be careful out there.
But sandboxing is not a substitute for judgment. A good harness still needs clear instructions, approvals where appropriate, sane defaults, and probably other layers around command execution. If you want the strongest isolation, containers and VMs still exist for a reason.
And let’s be honest, even with all of that, with enough tools and computing power, LLMs could probably cause trouble on any environment, so this is just about minimizing those risks at the obvious levels.
We’ve transformed some obscure features in popular harnesses and a trust me bro attitude, to an investigation into the implications of letting AI execute and what’s one of the possible mitigations. That’s very valuable.
Now I understand a bit better what macOS sandboxing actually looks like in practice. I understand the gap between App Sandbox and sandbox-exec. I understand why other harnesses still use Seatbelt. I understand that the policy itself is only half the story, and that the tool prompt also has to describe the environment correctly. And most importantly, I understand that “workspace root” and “security boundary” are not the same thing unless we do the work to make them the same.
So this is probably not good enough to ship blindly. Not good enough to call secure. But definitely good enough to learn something real.
And that is good enough for me.
", "date_published" : "2026-05-05T22:00:00Z", "id" : "https://alejandromp.com/development/blog/sandboxing-an-ai-harness-on-macos", "summary" : "In the previous post we gave superpowers to the harness in the form of abash tool. Even doing it just for the learning experience, it was already very eye-opening. It made this little Swift harness feel much closer to the real thing.",
"tags" : [
"AI Development",
"Swift",
"Project"
],
"title" : "Sandboxing an AI Harness on macOS",
"url" : "https://alejandromp.com/development/blog/sandboxing-an-ai-harness-on-macos"
},
{
"authors" : [
{
"name" : "Alejandro M. P."
}
],
"content_html" : "After teaching the harness to load AGENTS.md, my mind went back to thinking about the tools, and wondered, do we even need multiple tools?
Our tiny Swift harness had the usual little trio: read_file, list_files, and edit_file. Which is fine. It works. It is also exactly the kind of thing that makes agent tooling feel more magical and more special than it actually is.
Because if you squint a bit, those three tools are not really three capabilities. They are just tiny wrappers around what the shell has done for decades.
I’ve heard for a while that LLMs are now very good at just using bash, so I thought, maybe that’s the only tool they need? So… let’s remove them all and just use bash. Let’s see what happens.
Before changing anything, I wanted a baseline. Let’s remind ourselves how the current tool usage looks like.
Swift Agent Harness\nModel: gpt-5.4\nLoaded AGENTS.md (3 lines)\nCtrl+C to quit\n<Turn 1>\nYou: List and read all files in this project and tell me what's most interesting about them.\n<Step 1>\nAssistant: I can do that, but I need the actual file list first.\n...\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"AGENTS.md"}}\ntool-success: read_file -> 2 lines\n<Step 2>\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":"."}}\ntool-success: list_files -> 7 lines\n<Step 3>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Package.resolved"}}\ntool-success: read_file -> 15 lines\n<Step 4>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Package.swift"}}\ntool-success: read_file -> 22 lines\n...\n<Step 13>\nAssistant: I read all files that were visible from the project root...\nThe answer itself is not the interesting part, what I care about is the shape of the interaction. The model is not exploring the project in some rich, one off way. It’s as if it was playing a point-and-click adventure with the three verbs I gave it. It doesn’t know the environment in the same way we didn’t know everything that was clickable, so it goes and tries a call at a time and reassesses on every step, just like we rapidly click across the screen until we find an interactable object.
First read_file, because it already knows AGENTS.md exists. Then list_files, then read_file, then read_file again, then more listing, then more reading. Perfectly reasonable.
And so the question is, would reducing this down to a single tool that can do anything make this better or worse? Because with these three explicit tools, the model is forced to keep translating its intent into those wrappers over and over. That is not necessarily bad. There is something nice about how explicit it is. You can inspect every step. You can see exactly what the model asked for. You can keep the capabilities narrow.
But what if the model was able to cook a sequence of bash scripts in a single tool call and get everything it needs all at once? That was enough for me to want the next experiment. Remove the little toolbox. Leave just bash. See if the interaction becomes simpler, or just messier in a different way.
Let’s start by making the new bash tool without removing the existing ones yet.
I will use swift-subprocess, because is a nice showcase of modern Swift tooling, but also because it solves a real problem. If you let an LLM call bash, it is very easy for it to produce commands that dump a lot of output. Directory walks, file listings, find, sed, cat, maybe all of them chained together. That means stdout and stderr handling stops being a boring implementation detail very quickly. It is easy to get into awkward buffering problems or deadlocks if you try to wire process spawning by hand.
swift-subprocess is designed exactly for this kind of thing, and its API makes the “run a process and collect output properly” path feel trivial, not like a pile of edge cases we have to rediscover ourselves.
So the new tool looks like this:
static func bash() -> Self {\n ToolDefinition(\n name: "bash",\n description: "Run a bash command with the workspace root as the current directory.",\n arguments: ["command"],\n run: { arguments, workspaceRoot in\n let command = arguments["command"] ?? ""\n\n let result = try await Subprocess.run(\n .path("/bin/bash"),\n arguments: ["-c", command],\n workingDirectory: FilePath(workspaceRoot.path),\n output: .string(limit: 1_048_576),\n error: .string(limit: 1_048_576)\n )\n\n let stdout = result.standardOutput ?? ""\n let stderr = result.standardError ?? ""\n\n func jsonString(_ value: String) -> String {\n guard let data = try? JSONEncoder().encode(value),\n let string = String(data: data, encoding: .utf8) else {\n return "\\"\\""\n }\n return string\n }\n\n return """\n {"stdout":\\(jsonString(stdout)),"stderr":\\(jsonString(stderr)),"exit_code":\\(result.terminationStatus)}\n """\n }\n )\n}\nAnd then I just added it to the tools array. Nothing more.
let tools: [ToolDefinition] = [\n .bash(),\n .readFile(),\n .listFiles(),\n .editFile(),\n]\nThis was a very deliberate intermediate step. I did not want to jump straight into “bash only” yet. I wanted to see how the model behaved when bash existed, but the old explicit tools were still there too.
And the first answer was, not that differently at all.
When I asked for a quick architecture overview with the previous prompt, the model still preferred the old tools. Even with bash available, it kept thinking in terms of read_file and list_files. Which honestly makes sense. Those tools were still there, still very explicit, still easier to map to the task.
So I had to push it a bit more and ask explicitly for bash.
I asked this:
Use bash tool to give me a quick architecture overview of this project, including file sizes or line counts\nAnd that was enough for the LLM to use bash.
<Step 1>\nAssistant: Quick architecture overview based on the current workspace...\n...\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"printf 'Top-level structure:\\\\n'; find . -maxdepth 2 \\\\( -path '.\\\\/ .git' -o -path '.\\\\/ .build' \\\\) -prune -o -print | sed 's#^.\\\\/##' | sort; printf '\\\\n\\\\nFile sizes (bytes) and line counts:\\\\n'; find . -type f \\\\( -path '.\\\\/ .git\\\\/*' -o -path '.\\\\/ .build\\\\/*' \\\\) -prune -o -type f -print | sed 's#^.\\\\/##' | sort | while read f; do bytes=$(wc -c < \\"$f\\" | tr -d ' '); lines=$(wc -l < \\"$f\\" | tr -d ' '); printf '%8s bytes %6s lines %s\\\\n' \\"$bytes\\" \\"$lines\\" \\"$f\\"; done"}}\ntool-success: bash -> {"stdout":"Top-level structure:\\n.\\n.DS_Store\\n.gitignore\\nAGENTS.md\\nPackage...\n<Step 2>\nAssistant: Here's a quick architecture overview of the project, based on the file layout and line counts.\n...\nAnd as expected the LLM was able to make a tool call to get all the information it needed.
That was useful to see. Adding a more powerful tool does not automatically make the model prefer it. I’m sure we could tweak the system prompt to nudge it that way, but that’s an exercise on LLM research, and we’re here to talk about the harness. So let’s do the next logical step…
It was time to remove all the other specific tool calls and see what happened. Luckily this part was trivial, just remove them from the tools list and leave bash.
let tools: [ToolDefinition] = [\n .bash(),\n]\nAnd the result was immediately different.
I went back to the original style of prompt, no special instruction this time:
Give me a quick architecture overview of this project, including file sizes or line counts\nThis time the model had no alternative. If it wanted to inspect the repo, it had to do it through bash. Depending on the run, sometimes it used one bash call and sometimes a couple. But it did not have to follow the old pattern of many tiny file reads anymore. That is what I wanted to see.
<Turn 1>\nYou: Give me a quick architecture overview of this project, including file sizes or line counts\n<Step 1>\n...\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"printf 'Top-level:\\\\n'; find . -maxdepth 2 -type f | sed 's#^.\\\\/##' | sort; printf '\\\\n\\\\nTree (depth 3):\\\\n'; find . -maxdepth 3 | sed 's#^.\\\\/##' | sort"}}\ntool-success: bash -> {"stdout":"Top-level:\\n.build\\/.DS_Store\\n.build\\/.lock\\n.build\\/build.db\\n.b...\n<Step 2>\ntool-call: TOOL_CALL {"name":"bash","arguments":{"command":"printf 'Line counts (project files only):\\\\n'; for f in AGENTS.md Package.swift Package.resolved README.md run.sh share.sh Sources\\\\/swiftagentharness\\\\/*.swift; do [ -f \\"$f\\" ] && wc -l \\"$f\\"; done | sort -n; printf '\\\\n\\\\nPackage.swift:\\\\n'; sed -n '1,220p' Package.swift; printf '\\\\n\\\\nREADME.md:\\\\n'; sed -n '1,260p' README.md"}}\ntool-success: bash -> {"stdout":"Line counts (project files only):\\n 2 AGENTS.md\\n 9 sh...\n<Step 3>\nAssistant: Here's a quick architecture overview of the project.\n...\nBut we also need to note what we lose when we remove the specific tools. With read_file and list_files, part of the harness design was encoded in the tools themselves. The model could only ask for fairly narrow things and we had control over it. For example, we could make the list of files not return any hidden files, thus reducing the amount of likely useless data we fed back into the LLM’s context. With bash, that structure is gone. The model has much more freedom, which is exactly why it can gather more in fewer calls, but it also means the quality of the interaction depends much more on how well it shapes the command. As you can see in the exchange above, the LLM got a lot of hidden files that were not necessary and distracted from the goal.
That tradeoff is exactly what I was hoping to understand with this exercise. Bash really can replace the tiny toolbox. But it does not simply make the harness better. It moves complexity away from the tool harness and into the LLM’s command construction.
Seeing how the LLM can cook a single tool call using bash to gather all the information in one single step is eye-opening, it makes you realize the performance implications of tools. We’ve already seen how the context is the thing that matters to get the most out of AIs, but here we’ve seen how the tools that you give actually can have a tremendous impact too.
Even in this simple harness we can see how the impact on performance of the AI can be totally different depending on the tools we give it. For that we need to really internalize that every time the LLM needs more information, it must make a tool call, that means an extra step, and extra back and forth between the LLM and our harness. That also means triggering a new inference run. And remember, even if LLM architectures have caches and fancy tricks, every inference run virtually starts from the beginning of the conversation and it autocompletes the next part. So having a lot of back and forth on the same turn just to gather extra data is less than desirable.
![\"Side](\"https://alejandromp.com/development/blog/do-we-even-need-multiple-tools/tool-roundtrips.svg\")
Of course this is simplified, the bash version may still take two calls on some runs, and the multi-tool version may vary too. But the high level shape is the important part. One approach encourages lots of tiny round-trips. The other makes it possible to gather much more context in one go. Even if it’s up to the LLM to decide, the bash tool gives it the option to reduce the roundtrips.
This is where tradeoffs, analysis, engineering and research all meet to tweak a harness implementation and make it the most performant while making it useful and concrete enough for the LLM to know what to do. And this keeps evolving as LLMs evolve. This is one of the things that might make a harness feel better than another.
Want the finished project?
The whole point of this post is that you build it yourself, and all the important ideas are already here. But if you want to support my writing, or you just want to save time, I packaged the project for you to download.
Can we answer the question posed in the title of this post… as always, it depends. I think there is no real winner here, or at least not as clearly as I thought. I imagine one would have to run deeper and scientific benchmarks to see some sort of trend.
The multiple specific tools were useful mostly because they encoded structure. They constrained the model, made the interaction easier to inspect, and gave the harness more control over what kind of information could flow back into the context. And that is also exactly their limitation. Bash, on the other hand, got surprisingly close to replacing the whole little toolbox precisely because it removed that structure. Once the model had access to it, it could gather broad context much faster and with fewer round-trips. And that flexibility is also exactly the problem, because you lose control and specificity.
And that, for me, was the interesting shift in understanding. The question is not only what tools we can give the model. It is where we want the structure to live. In a carefully designed tool protocol, or in the commands the model writes for itself.
The advantage is that we’re just here to learn how these things work and see past the curtain, and on that I think we won. So for this step of the journey, I will leave it here. Each one can take the conclusion they want. I might just keep all tools available, and add a flag to run it in different modes.
", "date_published" : "2026-05-01T22:00:00Z", "id" : "https://alejandromp.com/development/blog/do-we-even-need-multiple-tools", "summary" : "After teaching the harness to loadAGENTS.md, my mind went back to thinking about the tools, and wondered, do we even need multiple tools?",
"tags" : [
"AI Development",
"Swift",
"Project"
],
"title" : "Do We Even Need Multiple Tools?",
"url" : "https://alejandromp.com/development/blog/do-we-even-need-multiple-tools"
},
{
"authors" : [
{
"name" : "Alejandro M. P."
}
],
"content_html" : "In the previous post, Have You Built an Agent Harness Yet?, we built a tiny harness in Swift. We gave it a loop, a prompt, and some tools, and with that it already had most of the features we are used to with modern AI. No magic. Just autocomplete, and a harness deciding what the model gets to see and do.
But there is another bit of magic we didn’t touch on and we should demystify. The appearance of memory. You know that moment when you open a brand new conversation and the agent already seems to know your project.
It doesn’t.
LLMs have no memory between fresh conversations. They just autocomplete from what they have in the current context. So if your AI tool of the week seems to remember your repo conventions, folder structure, or coding rules, what is happening is much simpler.
The industry has come to agree on the AGENTS.md standard, although some companies think they are special and use other file names. This is where you can put information about the project for the AI to learn.
But remember, there is no magic in AI. No memory. Just autocomplete. So how does this even work? If you’ve read the first post in this series, you already know the answer. The harness is doing the work.
The trick is that the harness automatically loads that file when the conversation starts and injects it into the context.
That’s it. That is the whole trick.
It is not a secret memory layer. It is not special agent magic. It is just more text in the context.
Let’s add it to the little harness from last post so you can see how simple the trick really is.
At the end of the previous article, our system prompt was still very simple:
self.systemPrompt = """\n You are a helpful assistant with access to tools.\n\n The workspace root is:\n \\(workspaceRoot.path)\n\n Tools:\n \\(toolsPrompt)\n\n When you want to use the tool, reply with exactly one line in this format and nothing else:\n TOOL_CALL {"name":"tool_name","arguments":{"path":"some/path"}}\n\n After receiving a TOOL_RESULT message, continue the task.\n If no tool is needed, answer normally.\n """\nThat is enough for the agent to use tools and know where the workspace root is. But it still doesn’t know anything specific about the project itself.
So if we start a fresh conversation, the agent won’t know anything about our project and will have to go discover it.
<Turn 1>\nYou: What do you know about this project?\n<Step 1>\nAssistant: I don’t know much yet beyond the project name and whatever is in the package manifest.\nFrom the workspace path, it appears to be a Swift project named **swiftagentharness**.\nI’ve requested the file listing and the `Package.swift` manifest so I can summarize:\n- what kind of Swift package it is\n- its targets/products\n- dependencies\n- likely purpose\nIf you want, I can continue by inspecting the repository structure and give you a concise overview of the project.\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"\\/Users\\/me\\/code\\/swiftagentharness\\/Package.swift"}}\ntool-success: read_file -> 22 lines\n<Step 2>\nAssistant: Based on `Package.swift`, here’s what I know:\n...\nThat is exactly what AGENTS.md is for.
The implementation is delightfully boring.
Before building the system prompt, we try to read an AGENTS.md file from the workspace root:
let agentsMD = try? String(\n contentsOf: workspaceRoot.appendingPathComponent("AGENTS.md"),\n encoding: .utf8\n)\n\nlet projectInstructions = if let agentsMD {\n """\n Project instructions in AGENTS.md:\n \\(agentsMD)\n """\n} else {\n ""\n}\nAnd once we have that text, we add it to the system prompt:
self.systemPrompt = """\n You are a helpful assistant with access to tools.\n\n The workspace root is:\n \\(workspaceRoot.path)\n\n \\(projectInstructions)\n\n Tools:\n \\(toolsPrompt)\n\n When you want to use the tool, reply with exactly one line in this format and nothing else:\n TOOL_CALL {"name":"tool_name","arguments":{"path":"some/path"}}\n\n After receiving a TOOL_RESULT message, continue the task.\n If no tool is needed, answer normally.\n """\nThat’s it.
Now the “project knowledge” is available to the LLM. Not in some mystical way, but just by being in its context. The harness literally copies the Markdown into the context it sends to the model.
That’s all this “project conventions” memory is.
Because one of the goals of this whole exercise is to break the illusion, I also made the harness print whether it loaded the file:
let agentsMD = try? String(contentsOf: workspaceRoot.appendingPathComponent("AGENTS.md"), encoding: .utf8)\nself.agentsMDLineCount = agentsMD.map { $0.components(separatedBy: .newlines).count }\n\n...\n\nprint("Swift Agent Harness")\nprint("Model: \\(client.model)")\nif let lineCount = agentsMDLineCount {\n print("Loaded AGENTS.md (\\(lineCount) lines)")\n}\nprint("Ctrl+C to quit")\nIf the harness says it loaded 2 lines, that means 2 lines of Markdown are about to shape the model’s behavior. Nothing more. Nothing less.
For my demo project, the file is tiny:
This is a test AGENTS.md.\nIf user says "Hello Swift Agent Harness", reply acknowledging you are that Swift agent harness and that you have read this AGENTS.md.\nAnd once the harness injects that into the system prompt, the effect is immediate:
Swift Agent Harness\nModel: gpt-5.4\nLoaded AGENTS.md (2 lines)\nCtrl+C to quit\n<Turn 1>\nYou: Hello Swift Agent Harness\n<Step 1>\nAssistant: Hello! I’m the Swift Agent Harness, and I’ve read the AGENTS.md.\nOf course it can answer that way. We literally gave it those instructions in the context.
![\"Diagram](\"https://alejandromp.com/development/blog/ai-doesn-t-remember-your-project-markdown-does/context-diagram.svg\")
This is the part I really want people to internalize.
AGENTS.md is not a magical new memory subsystem for AI. It is not some privileged channel into the model’s brain. It is not a special capability only the big fancy tools have.
It is just Markdown added into the context.
Useful Markdown, yes. Important Markdown, maybe. But still just text that your harness decided to prepend before the conversation starts. You could literally start each conversation by pasting that instruction yourself, and it wouldn’t be much different.
Look what happens if we do that before any of the changes in this post.
<Turn 1>\nYou: This is a test AGENTS.md. \nIf user says "Hello Swift Agent Harness", reply acknowledging you are that Swift agent harness and that you have read this AGENTS.md.\n<Step 1>\nAssistant: Understood. How can I help with the AGENTS.md test?\n<Turn 2>\nYou: Hello Swift Agent Harness\n<Step 1>\nAssistant: Hello! I’m the Swift Agent Harness, and I’ve read this AGENTS.md.\n<Turn 3>\nOf course, here we’re just trying to learn how things work and demystify them. Production-grade tools can go further. They may walk parent directories, support nested instruction files, merge global and local rules, decide when to refresh or skip them, even summarize huge files to fit the token budget.
All of that is just more real engineering work (and learning the particularities of the autocomplete machines).
But the core idea is still exactly this one. Somewhere in the code there is a boring piece of logic reading a file and sticking its contents into the prompt.
That is the “memory”.
That is the “project awareness”.
That is the “magic”.
Want the finished project?
The whole point of this post is that you build it yourself, and all the important ideas are already here. But if you want to support my writing, or you just want to save time, I packaged the project for you to download.
I like this example because it teaches a few things.
The model never knows your project by default. If it knows something, your harness probably put it there.
The conventions around agent tooling are much more ordinary than they sound. AGENTS.md is not a sacred artifact. It is just a contract between your harness and your repo. If this file exists, load it and send it too.
And honestly, that is reassuring. Once you see it clearly, the whole thing becomes easier to reason about. Easier to debug. Easier to improve. Easier to distrust when the marketing gets too theatrical.
It’s just models and context, with a bit of Markdown sprinkled on top.
", "date_published" : "2026-04-27T22:00:00Z", "id" : "https://alejandromp.com/development/blog/ai-doesn-t-remember-your-project-markdown-does", "summary" : "In the previous post, Have You Built an Agent Harness Yet?, we built a tiny harness in Swift. We gave it a loop, a prompt, and some tools, and with that it already had most of the features we are used to with modern AI. No magic. Just autocomplete, and a harness deciding what the model gets to see and do.", "tags" : [ "AI Development", "Swift", "Project" ], "title" : "AI doesn't remember your project, Markdown does", "url" : "https://alejandromp.com/development/blog/ai-doesn-t-remember-your-project-markdown-does" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "For years I have repeated a thing that I still believe. Every programmer should write a promise library once. I think agent harnesses are the 2026 version of that exercise.
If you use AI coding tools every day, and especially if you have opinions about agent workflows, subagents, MCPs, commands, skills, and whatever new ritual the week invented, build a tiny one yourself. Once. Not to ship it. Not because you are going to beat the existing ones, although honestly, with so much vibed slop around it would not be that hard. The point is that after you build one, the whole space stops feeling mystical. You stop thinking in terms of what big corp marketing wants and start thinking in terms of simple reality.
There is a model. There is a loop. There are tools. There is context. That is the heart of it.
Of course the real products do much more. But it’s still built around a core that is much simpler than people think.
A harness is just the little program that sits between the model and the outside world. That is it. Yes, a normal program with normal code. I guess nowadays we call it “classic”.
The model, the AI, does not touch your filesystem. The model does not open files. The model does not run commands. It only autocompletes text.
It is the harness that decides what messages get sent to the model, what context gets included, how the replies are interpreted, what tools the model has to see the world, and what result gets sent back after something happens locally.
That also means the conversation is yours.
This is one of the big things I think people should internalize. The continuity of the chat, the remembered context, the tool results, all of that is managed by the harness. The model endpoint is not secretly keeping your whole little world alive for you, it doesn’t have all your project in memory. The harness keeps appending messages and resending what matters. Sometimes even removing old ones!
Now, to be fair, modern APIs offer more stateful variants and convenience helpers on the server side. That changes the ergonomics, one would argue that for the worse, but not the core mental model. Somebody still owns the conversation contract, and when you build your own harness that somebody is you.
So the smallest possible mental model is this:
That is the whole trick. No magic. No AGI.
I can describe what a harness is, but to make sure we internalize it let’s build a simple one, from scratch.
To start, let’s keep the first step easy and simple. Let’s just make a CLI app that lets you send messages to the AI and shows you the LLM responses. Very simple, but useful to see how this works if you’ve never seen it before, and a necessary step before we get into the proper agentic features.
Let’s start with a simple CLI Swift package. Nothing fancy. No framework for agents. No giant abstraction tower. Just swift package init --type executable and the bits we actually need. As usual for command line tools in Swift, I used swift-argument-parser. That gives me a proper executable entrypoint with typed arguments.
At this stage the executable needs only a few things:
That is already enough to talk to an LLM.
For this post we will assume we have access to some LLM API, which in my project is represented by OpenAICompatibleClient. It’s not the interesting part of the project, but it is useful glue. It takes messages, performs the HTTP call to an OpenAI-compatible endpoint, and gives us back the assistant text. Don’t think it does anything special, it’s literally just an HTTP request-response.
The SwiftAgentHarness app is just a AsyncParsableCommand that reads the arguments, validates the endpoint, loads the API key from the environment, instantiates the client, creates an Agent, and calls run():
@main\nstruct SwiftAgentHarness: AsyncParsableCommand {\n @Option(help: "LLM chat completions endpoint.")\n var baseURL: String\n\n @Option(help: "Model name to use.")\n var model = "gpt-5.4"\n\n mutating func run() async throws {\n let environment = ProcessInfo.processInfo.environment\n guard let apiKey = environment["LLM_API_KEY"], apiKey.isEmpty == false else {\n throw HarnessError.missingAPIKey\n }\n guard let endpoint = URL(string: baseURL) else {\n throw HarnessError.invalidArguments("Invalid base URL: \\(baseURL)")\n }\n\n let client = OpenAICompatibleClient(apiKey: apiKey, baseURL: endpoint, model: model)\n let agent = Agent(client: client)\n try await agent.run()\n }\n}\nAt this point you can see our agent harness only needs the API client, nothing more. Let’s now make this Agent do something very basic.
struct Agent {\n let client: OpenAICompatibleClient\n\n func run() async throws {\n print("Swift Agent Harness")\n print("Model: \\(client.model)")\n print("Ctrl+C to quit")\n }\n}\nWith this in place we can now iterate on the Agent itself.
The first step is to set up what’s needed to have a conversation with the AI. A simple chat, nothing else.
The key thing to add now is the conversation structure itself. Not just reading one line and making one HTTP request, but actually keeping the state of the exchange in memory.
First, we need a system prompt. This is the hidden part of the context that the user never sees but that we, as the harness developers, can manipulate. This is quite an important piece for AI to behave as one desires, it’s part of the context, and as you know, context is all that matters (because remember, it is all there is, the only thing the AI sees).
struct Agent {\n private let systemPrompt = "You are a helpful assistant."\n \nThen we need to construct and keep around the conversation array. This is the state that we maintain to keep track of the whole conversation between the user and the AI (and later extra things our harness will do)
\n func run() async throws {\n print("Swift Agent Harness")\n print("Model: \\(client.model)")\n print("Ctrl+C to quit")\n\n var conversation = [Message(role: "system", content: systemPrompt)]\nThen we need the loop that reads user input from the terminal.
\n while true {\n print("\\u{001B}[94mYou\\u{001B}[0m: ", terminator: "")\n guard let input = readLine(), input.isEmpty == false else {\n continue\n }\nThat gives us the human side of the conversation. But that input is not useful yet until we actually append it to the state that we keep around.
\n conversation.append(Message(role: "user", content: input))\nNow comes the important bit. We send the entire conversation, not just the last line typed by the user.
\n let response = try await client.send(messages: conversation)\nAnd once we get the response back, we print it and append it too.
\n print("\\u{001B}[93mAssistant\\u{001B}[0m: \\(response)")\n conversation.append(Message(role: "assistant", content: response))\n }\n }\n}\nAnd yes, this is the first place where the illusion starts to break. The only reason the AI feels like it remembers what you said two messages ago is because the harness, the app, keeps sending the history back.
That is already a harness. Not a tool-using one, not a coding agent yet, but a simple one that is just a chat. But definitely a harness.
And we can give it a spin!
Swift Agent Harness\nModel: gpt-5.4\nCtrl+C to quit\nYou: Hello\nAssistant: Hello! How can I help you today?\nYou: What can you tell me about this project.\nAssistant: I’d be happy to help. Please share the project details—such as a description, code, repository link, files, screenshots, or goals—and I can explain:\n\n- what the project does\n- its architecture and components\n- the technologies used\n- how the code is organized\n- likely strengths, risks, and next steps\n\nIf you want, you can paste the README, folder structure, or source files here.\nThis is why I wanted to start here. Before the model can read files or edit code or do anything that looks magical, it first has to live inside a very boring loop. Read input. Append message. Call model. Print output. Append response. Repeat.
This was where AI started, where the ChatGPT revolution stayed for quite some time. You can see how we asked a question about the project, and it had no clue about it. There is no magic, the AI doesn’t know about our project, it has no access to it, so it just replies asking for more context. For a long time, even today, people still use AI this way, copy-pasting information into the context. But that’s not the revolution we expected.
So then, we gave it tools.
So far we only have a chat. Useful, yes. But not very exciting. The AI can only talk about whatever is already in the context. It still cannot see our project or interact with the world around it.
This is the first real step into agentic territory. We need to give the model a tool.
The important thing here is that there is still no hidden magic API involved. Current models are good enough that you can often teach them a new local convention just by adding it to the context. So for our little harness we do not need any special provider feature. We just extend the system prompt and tell the model that if it wants to use a tool it must reply in a very specific format.
To keep the first step small, let’s just add one. read_file.
private let systemPrompt = """\nYou are a helpful assistant with access to one tool.\n\nTool:\nName: read_file\nDescription: Read a UTF-8 text file from disk.\nArguments: path\n\nWhen you want to use the tool, reply with exactly one line in this format and nothing else:\nTOOL_CALL {"name":"read_file","arguments":{"path":"some/file.txt"}}\n\nAfter receiving a TOOL_RESULT message, continue the task.\nIf no tool is needed, answer normally.\n"""\nThis is worth pausing on. The tool is not just a function in Swift. The tool is also part of the prompt. The model needs to know that it exists, what it is for, and what shape of arguments it expects. The better you describe the tool, the better the model can use it.
Then, after the model replies, we check if the reply starts with TOOL_CALL.
let response = try await client.send(messages: conversation)\n\nlet trimmed = response.trimmingCharacters(in: .whitespacesAndNewlines)\nif trimmed.hasPrefix("TOOL_CALL ") {\n print("tool-call: \\(trimmed)")\n\n let outcome: ToolOutcomeResult\n do {\n // Get the tool call text from the LLM\n let payload = String(trimmed.dropFirst(10))\n guard let data = payload.data(using: .utf8) else {\n throw HarnessError.invalidToolInvocation\n }\n \n // Parse the tool call text to the JSON contract we specified in the prompt\n let invocation: ToolInvocation\n do {\n invocation = try JSONDecoder().decode(ToolInvocation.self, from: data)\n } catch {\n throw HarnessError.invalidToolPayload(payload)\n }\n \n // Check for the only tool we have\n guard invocation.name == "read_file" else {\n throw HarnessError.invalidToolInvocation\n }\n\n // Run the "tool"\n let path = invocation.arguments["path"] ?? ""\n let url = URL(fileURLWithPath: path)\n let result = try String(contentsOf: url, encoding: .utf8)\n print("tool-success: read_file -> \\(summarizeToolResult(result))")\n outcome = .success(result)\n } catch {\n let errorMessage = "Tool invocation failed: \\(error.localizedDescription). Reply again, either with a valid TOOL_CALL line or a normal answer."\n print("tool-error: \\(errorMessage)")\n outcome = .failure(errorMessage)\n }\n\n conversation.append(Message(role: "assistant", content: response))\n conversation.append(Message(role: "user", content: formatToolResult(outcome)))\n\n let followUp = try await client.send(messages: conversation)\n print("Assistant: \\(followUp)")\n conversation.append(Message(role: "assistant", content: followUp))\n continue\n}\nAnd just like that now our harness gives more powers to the AI:
You: Read the `README.md` file and summarize it\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"README.md"}}\ntool-success: read_file -> 17 lines\nAssistant: `swiftagentharness` is a Swift command-line project built with Swift Package Manager and Apple’s ArgumentParser.\n\nKey points:\n- Requires Swift tools 6.2\n- Requires macOS 26 or later\n- Build with: `swift build`\n- Run with: `swift run`\n- Optionally run via: `./run.sh`\nAgain, no magic. The model returns text. The harness interprets that text as a tool call. Then the harness decides to execute something locally. The tool-call and tool-success lines are just for the user, and for debugging in the terminal. What goes back to the AI is the TOOL_RESULT message, which includes the actual result together with a tiny SUCCESS or ERROR protocol we invented, just to make it more clear to the AI. With that new context in place, the model can then reply with the summary of the file as we asked.
ToolOutcomeResult definitionThe only extra thing I did allow myself is one small enum to represent the outcome.
enum ToolOutcomeResult {\n case success(String)\n case failure(String)\n}\nDoesn’t matter much, but I like having these things properly modeled.
Yes, that really is it. Now the AI has access to, a small part of, our world. The moment you do this, the conversation changes. Before, if you asked about a local file the AI had to ¯\\_(ツ)_/¯ and ask you to paste it. Now it can ask you to run the little contract you gave it.
And notice what happened here. We did not give the AI direct access to the file system. We did not open a mystical portal into the machine. We only gave it a way to request something in text, and we wrote the normal boring Swift code that fulfills that request.
And to make it even more clear, I have here a real run from this version of the harness that has so much to learn from:
Swift Agent Harness\nModel: gpt-5.4\nCtrl+C to quit\nYou: tell me about this project\nAssistant: Sure. If you want me to describe a specific project, I need to inspect its files first.\n\nPlease give me:\n- the project path, or\n- the main file to read\n\nYou: readme\nAssistant: Please provide the file path, e.g. `README.md` or `./README.md`, and I’ll read it and summarize the project.\n\nYou: README.md\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"README.md"}}\ntool-success: read_file -> 17 lines\nAssistant: This project is `swiftagentharness`, a Swift command-line app. ...\n\nYou: now read the run file\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"run.sh"}}\ntool-success: read_file -> 15 lines\nAssistant: `run.sh` is a convenience launcher for the CLI. ...\nWhen I ask vaguely about the project, the AI still does not know anything about it. That part has not changed. It only knows what is in the conversation. But now knows it has a way to learn. It cannot inspect the whole project by magic, but it knows it can read files if I give it a path.
But it knows it only has access to reading single files, so note that when I say readme, it pushes back and asks for something more specific. It doesn’t have enough context to make up a proper tool call. That is nice. It means the model is trying to operate within the contract we gave it instead of hallucinating a path.
Then I give it a proper file name README.md, it uses the read tool, and suddenly that file is now part of the conversation. Thanks to that, I can be a bit more ambiguous and say “the run file” and it understands I probably mean run.sh, because that is now in context too.
This is one of those moments where the illusion becomes very educational. The AI did not gain general awareness. It just accumulated a bit more text in the conversation, text that came from a tool call your harness fulfilled.
One funny thing here is that this first version did not stay stable for very long. As is typical with LLMs, things are not consistent and they reply with random responses, is part of their nature. In this case, it’s actually a good thing.
Soon enough I hit errors like this:
tool-error: Tool invocation failed: Tool invocation payload could not be decoded: {"name":"read_file","arguments":{"path":"README.md"}}\nI don’t have the contents of `README.md` yet. Please provide the file contents or ensure the tool result is available, and I’ll summarize it.. Reply again, either with a valid TOOL_CALL line or a normal answer.\nAt first this looks confusing, because the JSON in there seems totally valid. The problem was that the model, in this case GPT, was trying to be nice. Instead of replying with only the exact TOOL_CALL line I asked for, it sometimes produced an extra little explanatory sentence. Good for the user, not so much for our parsing code.
And honestly, that is a very model thing to do. Modern models are trained to be helpful, conversational, and a bit eager to explain themselves. They are not trying to break your harness. They are trying to be polite.
So this is a good moment to improve the code a bit. Not because the architecture changed, but because the real world showed us a new shape of output. This is a whole rabbit hole that makes making a production-ready harness a bit more complex. We would need to tailor the system prompt for every model, improve our parsing, and other engineering techniques that are not worth for this post.
But at least, let’s make it work for this use case so we can continue learning. Instead of assuming the whole response starts with TOOL_CALL, we now parse the assistant response line by line.
private func parseAssistantResponse(from response: String) throws -> ParsedAssistantResponse {\n let lines = response\n .split(whereSeparator: \\.isNewline)\n .map { String($0).trimmingCharacters(in: .whitespaces) }\n .filter { $0.isEmpty == false }\n\n var userFacingLines = [String]()\n var invocation: ToolInvocation?\n\n for line in lines {\n guard line.hasPrefix("TOOL_CALL ") else {\n userFacingLines.append(line)\n continue\n }\n\n let payload = String(line.dropFirst(10))\n guard let data = payload.data(using: .utf8) else {\n throw HarnessError.invalidToolInvocation\n }\n do {\n invocation = try JSONDecoder().decode(ToolInvocation.self, from: data)\n } catch {\n throw HarnessError.invalidToolPayload(payload)\n }\n }\n\n return ParsedAssistantResponse(\n userFacingText: userFacingLines.joined(separator: "\\n"),\n invocation: invocation\n )\n}\nThen the loop can show the assistant text to the user first, and still execute the tool if there is one.
let response = try await client.send(messages: conversation)\nlet parsedResponse = try parseAssistantResponse(from: response)\n\nif parsedResponse.userFacingText.isEmpty == false {\n print("Assistant: \\(parsedResponse.userFacingText)")\n}\n\nif let invocation = parsedResponse.invocation {\n // execute tool\n}\nThis is a bit of the secret sauce of every harness. Not secret magic. Not genius algorithms. Just more cases of text interpretation, because at the end of the day that is still what the harness is doing. AI dumps text, and somebody needs to deal with it to create the illusion.
At this point the next obvious limitation appears. read_file is useful, but it still depends too much on the human already knowing what file should be read.
The harness can inspect.
But it still cannot explore.
That is why the next tool to add is list_files.
And this is also the moment where the code starts earning a tiny bit of structure. Having one hardcoded tool inline was nice for the first learning step, but with a second tool it already makes sense to generalize a little.
So instead of special-casing everything directly in the loop, we will define a small tool type.
struct ToolDefinition {\n let name: String\n let description: String\n let arguments: [String]\n let run: ([String: String]) throws -> String\n}\nThen in the app entrypoint we can define the available tools explicitly.
let tools: [ToolDefinition] = [\n .readFile(),\n .listFiles(),\n]\nlet agent = Agent(client: client, tools: tools)\nAnd because the tools are now dynamic, the system prompt should be dynamic too. Instead of hardcoding the tool descriptions by hand, the Agent now builds the tool section of the prompt from the actual ToolDefinition values it receives.
init(client: OpenAICompatibleClient, tools: [ToolDefinition]) {\n self.client = client\n self.toolsByName = Dictionary(uniqueKeysWithValues: tools.map { ($0.name, $0) })\n\n let toolsPrompt = tools\n .sorted { $0.name < $1.name }\n .map(\\.promptBlock)\n .joined(separator: "\\n\\n")\n\n self.systemPrompt = """\n You are a helpful assistant with access to tools.\n\n Tools:\n \\(toolsPrompt)\n\n When you want to use the tool, reply with exactly one line in this format and nothing else:\n TOOL_CALL {"name":"tool_name","arguments":{"path":"some/path"}}\n\n After receiving a TOOL_RESULT message, continue the task.\n If no tool is needed, answer normally.\n """\nThat is an important little detail. It means the prompt does not drift away from reality. If I add a tool in Swift but forget to tell the model about it or if I tell the model about a tool that is not really available, the harness will be lying and the model will freak out. Building the prompt from the tool definitions keeps both sides synchronized.
With this in place we can extend the ToolDefinition and use it as a way to host the different tools we have.
extension ToolDefinition {\n static func readFile() -> Self { ... }\nThe list_files tool itself is still very simple.
static func listFiles() -> Self {\n let fileManager = FileManager.default\n\n return ToolDefinition(\n name: "list_files",\n description: "List files and directories in a path.",\n arguments: ["path"],\n run: { arguments in\n let path = arguments["path"] ?? "."\n let url = URL(fileURLWithPath: path)\n let values = try fileManager.contentsOfDirectory(\n at: url,\n includingPropertiesForKeys: [.isDirectoryKey],\n options: [.skipsHiddenFiles]\n )\n let lines = try values\n .sorted { $0.lastPathComponent < $1.lastPathComponent }\n .map { entry in\n let isDirectory = try entry.resourceValues(forKeys: [.isDirectoryKey]).isDirectory ?? false\n return isDirectory ? entry.lastPathComponent + "/" : entry.lastPathComponent\n }\n return lines.joined(separator: "\\n")\n }\n )\n}\nNotice what happened here. The architecture did not change. We still have the same loop, the same text protocol, the same TOOL_CALL, the same TOOL_RESULT.
What changed is just the model’s ability to gather context by itself.
This is a much bigger jump than it may look. read_file gave the AI a flashlight but list_files gives it a map.
You: List the names of the files in this project.\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":"."}}\ntool-success: list_files -> 5 lines\nAssistant: Package.resolved\nPackage.swift\nREADME.md\nSources/\nrun.sh\nYou: summarize the readme\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"README.md"}}\ntool-success: read_file -> 17 lines\nAssistant: The README says this is a Swift ...\nNice! Now the user doesn’t have to specify the exact file names and paths because the model can explore directories itself.
The example above was a bit forced to show the happy path. The reality is that we have a problem with our harness.
You: explore this project and tell me what is about\nAssistant: I need to inspect the project files first. Please provide the tool results for the directory listing so I can explore it and summarize what the project is about.\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":".\\/"}}\ntool-success: list_files -> 5 lines\nAssistant: TOOL_CALL {"name":"read_file","arguments":{"path":"README.md"}}\nYou:\nNotice how we asked a more open ended question to the agent, and it correctly recognized that to answer needed to explore the project, which it did by using the list_files tool correctly. Then the harness gave the result of that tool call just like we’ve done before, but hold on. The agent didn’t reply with text, it replied with more tool calls!
This brings us to the next piece of our learning: turns and steps.
In this context a turn is what includes one user request and the agent response to that request. A step is every individual interaction the agent needs to answer the user’s request.
When we started with the simple chat model, we had 1 step per 1 turn. User sends a message, the agent replies. When we added tool calling, we changed that a bit. User sends a message, the agent replies with a tool call, harness sends the result and agent replies with the final response. So there was an intermediate step in there, but that was it. And that’s not enough because agents often need multiple tool calls, multiple roundtrips to accomplish the goal the user asked for.
In this case it knew that it had to explore the project, but once it knew about the list of files, it then wanted to know about a specific file, but our harness is not yet ready for that, so it just stopped and waited for user input.
The problem is that right now our harness is just following a simple loop, we need to put the tool calling in an inner loop so the agent can have multiple steps in a single turn. We want the agent to be able to keep requesting tool calls until it is satisfied and gives as final answer.
In other words, a single turn can include multiple steps before the agent can give the final answer to the user.
\nSo the code grows one inner loop.
while true {\n turn += 1\n print("<Turn \\(turn)>")\n ...\n var step = 0\n\n while true { // <= new inner loop\n step += 1\n print("<Step \\(step)>")\n let response = try await client.send(messages: conversation)\n let parsedResponse = try parseAssistantResponse(from: response)\n\n if parsedResponse.userFacingText.isEmpty == false {\n ...\n }\n\n if let invocation = parsedResponse.invocation {\n ...\n conversation.append(Message(role: "assistant", content: response))\n conversation.append(Message(role: "user", content: formatToolResult(outcome)))\n continue\n }\n\n conversation.append(Message(role: "assistant", content: response))\n break\n }\n}\nThat is a really important moment in understanding how agents work.
Let’s see how this change impacts our previous example.
Note that I’ve added turn and step logs so it’s clearer when there are roundtrips.
<Turn 1>\nYou: explore this project and tell me what is about\n<Step 1>\nAssistant: I need the project files to inspect it, but I don’t have the directory listing yet. Please provide the repository contents or let me know the project path, and I’ll explore it and summarize what it’s about.\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":".\\/"}}\ntool-success: list_files -> 5 lines\n<Step 2>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"README.md"}}\ntool-success: read_file -> 17 lines\n<Step 3>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Package.swift"}}\ntool-success: read_file -> 22 lines\n<Step 4>\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":"Sources"}}\ntool-success: list_files -> swiftagentharness/\n<Step 5>\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":"Sources\\/swiftagentharness"}}\ntool-success: list_files -> 3 lines\n<Step 6>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Sources\\/swiftagentharness\\/App.swift"}}\ntool-success: read_file -> 34 lines\n<Step 7>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Sources\\/swiftagentharness\\/Harness.swift"}}\ntool-success: read_file -> 223 lines\n<Step 8>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Sources\\/swiftagentharness\\/OpenAICompatibleClient.swift"}}\ntool-success: read_file -> 39 lines\n<Step 9>\nAssistant: This project is a small Swift command-line “agent harness” for talking to an OpenAI-compatible chat completions API and letting the model use a couple of local filesystem tools.\nWhat it does\n...\n<Turn 2>\nYou: Thanks!\n<Step 1>\nAssistant: You’re welcome!\n<Turn 3>\nYou:\nThe model is not magically traversing your project in one giant sweep. It is taking little steps. List files. See the result. Decide what file matters. Read that file. See the result. Then decide if it can answer.
This is why I wanted to show the failing version first. Once you see the harness stop too early, the need for the inner loop becomes obvious.
Now that the agent can list and read files on its own, we need to showcase the dangers of these tools.
<Turn 1>\nYou: Can you explore this project, and then find similar projects in this computer.\n<Step 1>\nAssistant: I can do that, but I need access to the project files first.\nPlease provide the project path, for example:\n- `.`\n- `./my-project`\n- `/home/user/project`\nOnce I have the path, I’ll:\n1. explore the project structure,\n2. identify what kind of project it is,\n3. search nearby/on this computer for similar projects.\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":".\\/"}}\ntool-success: list_files -> 5 lines\n<Step 2>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Package.swift"}}\ntool-success: read_file -> 22 lines\n\n...\n\n<Step 9>\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":".."}}\ntool-success: list_files -> 28 lines\n<Step 10>\n\n...\n\n<Step 23>\nAssistant: I explored the current project and found a few similar ones nearby.\nCurrent project: `swiftagentharness`\n- Type: Swift Package Manager executable\n...\nSimilar projects on this computer\n...\n<Turn 2>\nYou:\nwow. I had to redact some things but you get the gist. The agent started listing files outside the directory we’re running it in, the magical .. path. Sure, of course I asked for it, but you could imagine the LLM doing it on its own volition.
Now this is a whole rabbit hole about security that is still an open question, only really solved with full isolation, aka running the agent in its own computer, a sandbox. I’m not gonna pretend to solve this in this exploratory blog post, but we can use this again as an excuse to learn more about the lack of magic.
The first thing we need is to introduce the concept of a workspace root into the CLI itself.
@Option(help: "Workspace root for the agent.")\nvar workspace = FileManager.default.currentDirectoryPath\n\nlet workspaceRoot = try resolveWorkspaceRoot(from: workspace)\nlet agent = Agent(client: client, tools: tools, workspaceRoot: workspaceRoot)\nThat gives the harness an explicit root directory to work from. Agent.init gains a workspaceRoot: URL parameter, and ToolDefinition.run changes signature to receive it as well:
struct ToolDefinition {\n ...\n let run: ([String: String], URL) throws -> String\n}\nThat means every tool can call resolvePath to validate paths before touching the filesystem. And now that the root is real in code, we can also tell the model about it in the prompt.
self.systemPrompt = """\n You are a helpful assistant with access to tools.\n\n The workspace root is:\n \\(workspaceRoot.path)\n\n Tools:\n \\(toolsPrompt)\n ...\n """\nThis is useful. It gives the model more context and helps it avoid asking for nonsense paths. But this is just guidance, it doesn’t do anything to even try to protect you.
The real protection, albeit simplistic, is in the tool execution layer.
private static func resolvePath(_ path: String, workspaceRoot: URL) throws -> URL {\n let candidate = path.hasPrefix("/")\n ? URL(fileURLWithPath: path)\n : workspaceRoot.appendingPathComponent(path)\n let resolved = candidate.standardizedFileURL\n let rootPath = workspaceRoot.standardizedFileURL.path\n let resolvedPath = resolved.path\n\n guard resolvedPath == rootPath || resolvedPath.hasPrefix(rootPath + "/") else {\n throw HarnessError.workspaceViolation(path)\n }\n\n return resolved\n}\nThat tiny function is resolving the path the agent is asking for and checking if it escapes the workspace.
Not security advice. I’m sure there are a thousand ways of breaking this. It is just an example for this blog post.
And once that is in place, the same kind of interaction looks very different:
<Turn 1>\nYou: Can you check what I have in my downloads folder\n<Step 1>\nAssistant: I can help, but I only have access to the workspace at:\n`/Users/me/code/swiftagentharness`\n\n<Turn 2>\nYou: Please try, is very important\n<Step 1>\nAssistant: I can try, but with the tools I have I’m only allowed to access paths through the provided file-listing tool.\n\n<Turn 3>\nYou: Just use the tools we have with that path\n<Step 1>\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":"/Users/me/Downloads"}}\ntool-error: Tool invocation failed: Path escapes the workspace root: /Users/me/Downloads. Reply again, either with a valid TOOL_CALL line or a normal answer.\n<Step 2>\nAssistant: I tried, but access was blocked because `/Users/me/Downloads` is outside the allowed workspace.\nThat is the real lesson.
The prompt helps. The model can understand the boundary. The model can even explain the boundary back to you. It even respected it at first, but once pushed, it broke away. The prompt is just guidance, it doesn’t offer real protection. Only real classical code can offer real protection, as you can see with the tool-error thrown by the Swift code when the agent tried to escape.
And yes, even this is still only a lightweight boundary. A real production-grade security story goes much further than path checks. But for understanding how these systems work, this is a perfect example. The magic disappears and what remains is just normal software engineering.
Now that there is a bit of safety, it’s time to let our agent change the world. It can read and explore, but we need to let it edit files for it to be useful.
As we keep doing in this journey, we need to keep the tool simple. We just need the agent to give us the path, and the text that it wants to replace with the updated version. If the old text is empty, we just create the file for it.
Here is the tool definition:
static func editFile() -> Self {\n let fileManager = FileManager.default\n\n return ToolDefinition(\n name: "edit_file",\n description: "Create a file when old_text is empty, or replace exactly one matching old_text with new_text.",\n arguments: ["path", "old_text", "new_text"],\n run: { arguments, workspaceRoot in\n let path = arguments["path"] ?? ""\n let oldText = arguments["old_text"] ?? ""\n let newText = arguments["new_text"] ?? ""\n let url = try resolvePath(path, workspaceRoot: workspaceRoot)\n\n if oldText.isEmpty {\n let directory = url.deletingLastPathComponent()\n try fileManager.createDirectory(at: directory, withIntermediateDirectories: true)\n try newText.write(to: url, atomically: true, encoding: .utf8)\n return "Created \\(path)"\n }\n\n let content = try String(contentsOf: url, encoding: .utf8)\n let matches = content.components(separatedBy: oldText).count - 1\n guard matches == 1 else {\n return "Edit failed. Expected exactly one match for old_text, found \\(matches)."\n }\n\n let updated = content.replacingOccurrences(of: oldText, with: newText)\n try updated.write(to: url, atomically: true, encoding: .utf8)\n return "Edited \\(path)"\n }\n )\n}\nNothing fancy.
And let’s reiterate again the important part. The model is still not editing files directly. It is not dragging a cursor around. The LLM is not an editor. It is not doing anything mystical. It is just proposing a very boring text transformation contract and the harness applies it.
And now, finally, the harness can do the thing that makes coding agents feel like coding agents. Not just read the world. Change it.
<Turn 1>\nYou: Can you create a new md file to summarize what this project is about.\n<Step 1>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"README.md"}}\ntool-success: read_file -> 17 lines\n<Step 2>\ntool-call: TOOL_CALL {"name":"list_files","arguments":{"path":"."}}\ntool-success: list_files -> 5 lines\n<Step 3>\ntool-call: TOOL_CALL {"name":"read_file","arguments":{"path":"Package.swift"}}\ntool-success: read_file -> 22 lines\n<Step 4>\n...\n<Step 9>\ntool-call: TOOL_CALL {"name":"edit_file","arguments":{"new_text":"# Project Summary\\n\\n...","old_text":"","path":"PROJECT_SUMMARY.md"}}\ntool-success: edit_file -> Created PROJECT_SUMMARY.md\n<Step 10>\nAssistant: Created `PROJECT_SUMMARY.md` in the project root with a summary of the project, its purpose, architecture, tools, and usage.\n<Turn 2>\nThis is the first moment where the harness stops being just an observer and starts becoming a real tool.
Want the finished project?
The whole point of this post is that you build it yourself, and all the important ideas are already here. But if you want to support my writing, or you just want to save time, I packaged the project for you to download.
There is one last exercise I really recommend if you build one of these.
Lie.
I mean it. Go to one of your tools and make it return something false on purpose.
Make read_file always return a joke. Make list_files invent files that do not exist. A fun one is to rewrite extensions and pretend every Swift file is actually a JavaScript file.
The model will believe you.
And yes, of course it will. That is the whole point.
By now it should be obvious, but I think doing this with your own hands makes it click in a completely different way. The model does not have direct access to your machine. It does not have a secret backdoor into reality. It only has the world your harness describes to it through tool results.
That means the world, for the model, is whatever the harness says it is.
Not because the model is stupid. Not because the model is broken. But because that is literally the way this autocomplete machine works.
If you reached this point I hope you now see past the illusion. Now you know how agentic tools and AI harnesses work, you built one yourself!
No matter what new features you see from marketing, everything boils down to the simple concepts that you learned. The model emits text. The harness interprets that text as a tool call. Your code executes something locally, or pretends to, and then sends more text back.
No mystical illusion. Just tools and code.
Models. Loops. Context. Tools. Turns. Engineering.
Nothing more.
In the next post in the series we will learn how the harness helps the AI pretend. Because AI doesn’t remember your project, Markdown does.
I was migrating to a newer version of The Composable Architecture, which meant there was a list of deprecations to clean up. One of the things on that list was adding InferSendableFromCaptures as an upcoming Swift feature flag across all our package targets.
SE-0418 is genuinely interesting. It makes method references participate more accurately in sendability checking when used as values. One of those proposals that feels obviously correct once you read it.
I added it while preparing for Swift 6, hoping to catch issues before the TCA 2.0 work. I was ready to fix code. I was not ready for another journey of concurrency discovery. The kind that challenges things I already knew, just to make sure I really knew them.
This is one of those posts I write because writing is thinking. Even at the risk of being wrong. That is actually better, because I will learn more. So don’t take this as a tutorial or the truth. Use critical thinking as you follow along.
A bunch of warnings appeared, all of the same shape, all of them in places where I was passing a SwiftUI view’s initialiser as a function reference to a navigation modifier.
.navigationLinkDestination(\n item: $store.scope(...),\n destination: ChildView.init(store:) // ⚠️\n)\nThe warning said something like “call to main actor-isolated initializer init(store:) in a synchronous nonisolated context”.
To understand what was happening I had to properly internalise what SE-0418 changes about function references. The warning appears because ChildView.init(store:) is not just “a function that makes a view”. ChildView conforms to View, and that makes the initialiser main actor-isolated. But the destination: parameter expects @escaping (StoreOf, with no @MainActor. When I pass the initialiser directly, I am asking the compiler to use a main actor-isolated initialiser as a plain synchronous callback. In Swift 5 mode it lets me do that, but warns me that the isolation does not fit the context I am putting it in.
That was the first model in my head, at least. It sounded convincing enough…
Once I saw it that way, the fix felt obvious: switch to a closure.
.navigationLinkDestination(\n item: $store.scope(...),\n destination: { ChildView(store: $0) } // ✅\n)\nNo warning.
We’re done, right? I applied it everywhere, but as I was doing it my inquisitive mind kept asking. But why?
Why did the closure work? They both call the same initialiser. They both end up constructing the same @MainActor view. Why is one fine and the other not?
SE-0418, the proposal behind InferSendableFromCaptures, adds type inference specifically to function and method references when used as values.
Before enabling the feature flag, ChildView.init(store:) used as a value slipped through as a non-sendable function value. After enabling it, the reference carries more of what the declaration means. The initialiser is main actor-isolated, so the function reference is treated as main actor-isolated too.
That is the right thing to do. The initialiser is @MainActor. The reference should say so. But the parameter I am passing it to is typed as @escaping (StoreOf, with no @MainActor annotation. So, in my first reading, the compiler was complaining because the function reference now brought main actor isolation with it, and the parameter did not ask for that.
Closure literals do not work that way. A closure literal has no pre-existing function reference that has to be squeezed into the parameter type. The compiler creates it fresh to satisfy the parameter type, @escaping (StoreOf, and then type-checks the body of the closure where it is written. The warning never fires because the compiler is no longer trying to use the isolated initialiser itself as the callback value.
That seemed to explain the difference between the two syntaxes. But it left me with a deeper question.
If the closure literal is created to match type @escaping (StoreOf, with no @MainActor annotation, then how can it safely call ChildView(store:) inside? That initialiser is @MainActor. I am inside a closure that is not annotated @MainActor. How is that not a problem?
In Swift 6 strict mode, calling a @MainActor function from a nonisolated context is an error. Not a warning. An error.
So I switched to .swiftLanguageMode(.v6), expecting to see it break.
It did not.
The closure compiled cleanly. No warning, no error. And that is when I realised I had been thinking about the wrong thing.
The closure does not have @MainActor in its type, but that does not mean it runs in a nonisolated context. Of course it doesn’t, and I knew that. But I let the compiler warning pull my attention to the wrong place. It is incredible how quickly a weak mental model can crumble when you trust the first explanation that seems to fit.
I defined it inside body. And body is @MainActor. A closure literal inherits the actor context of the scope it is written in, not just the type annotation of the parameter it satisfies. So the closure is effectively @MainActor at the point where it runs, even if that annotation is not visible in the parameter type.
Calling ChildView(store:) inside that closure is calling a @MainActor function from a @MainActor context. That is always safe. The compiler knows this. So there is no error in Swift 6. And there was no warning before. Everything was consistent enough to fool me.
At that point I thought I had it. The closure works because it inherits the main actor context. The function reference warns because it does not get to use that same context in the same way.
Nice little explanation.
Or is it?
Later I explained the whole thing to a coworker. And while explaining it, I felt that familiar discomfort. The words were coming out, but something felt off.
Because if the closure works because it inherits the main actor context from the view, then why would that not also apply to the method reference?
So I made the example smaller and more annoying.
struct ParentView: View {\n var body: some View {\n Text("parent")\n }\n\n func makeView() -> some View {\n doSomethingOnTheMainActor()\n\n let inferredReference = ChildView.init(store:)\n let typedReference: (StoreOf<Int>) -> ChildView = ChildView.init(store:)\n let mainActorReference: @MainActor (StoreOf<Int>) -> ChildView = ChildView.init(store:)\n let mainActorClosure: @MainActor (StoreOf<Int>) -> ChildView = { @MainActor in\n ChildView(store: $0)\n }\n\n _ = (inferredReference, typedReference, mainActorReference, mainActorClosure)\n\n return ChildView(store: StoreOf())\n }\n}\n\n@MainActor\nfunc doSomethingOnTheMainActor() {}\nThe important line is not even the function reference. It is this one:
doSomethingOnTheMainActor()\ndoSomethingOnTheMainActor() is @MainActor. I am calling it without await. And it compiles.
That means makeView() is already being treated as main actor-isolated, even though I did not write @MainActor on it. So my previous explanation was incomplete. The surrounding method is not some random nonisolated context. The compiler is already treating it as main actor-isolated.
Then the results got weirder.
In Swift 5 mode with InferSendableFromCaptures enabled, the inferred function reference warned. The explicitly typed plain function reference warned. Even the explicitly typed @MainActor function reference warned.
But the @MainActor closure did not.
And that is where it started to smell. mainActorReference and mainActorClosure have the exact same type:
@MainActor (StoreOf<Int>) -> ChildView\nBut one warned and the other did not.
That is the part that broke the simple explanation. If the problem were simply “you are in a nonisolated context”, then doSomethingOnTheMainActor() should have required await. It did not. And if the problem were simply “this is main actor-isolated but the parameter does not accept that”, then the closure should have failed too once I realised it was main actor-isolated. In my mind, if one failed, the other should fail. If one worked, the other should work.
Then I added @MainActor explicitly to makeView().
All warnings disappeared.
Then I removed that explicit annotation again, but switched the package to Swift 6 language mode.
All warnings disappeared too.
That was the real clue.
So I no longer think the interesting lesson is “closures inherit actor context and method references do not”. That is too clean. It is also not quite true.
What I think is happening is that this warning is a Swift 5 migration-mode artifact. Enabling InferSendableFromCaptures in Swift 5 mode makes method references participate in stricter concurrency checking, but that checking does not seem to line up perfectly with the actor isolation inference that Swift 6 applies. The surrounding SwiftUI method is already main actor-isolated. Swift 6 understands the whole thing and accepts it. Swift 5 with the upcoming feature flag sees enough to warn, but not enough to recognise what Swift 6 recognises.
The closure workaround still makes sense. It avoids the warning and expresses the code in a way the Swift 5 checker is happy with. But it is not proof that the original function reference was unsafe. It is more like a shape of code that avoids a transitional diagnostic.
And this is the subtle part that I think is easy to miss.
Upcoming feature flags, at least the ones related to the complex concurrency story, are not always the same experience as fully moving to the language mode where that feature belongs. They are there to surface future issues early, but they can expose interactions with the old mode that do not quite represent the final model.
The fix itself was small. One line changed per call site.
But understanding why it worked took a real detour through several parts of the concurrency model: how SE-0418 adds inference to function references, how closure literals behave differently, how actor context is inherited rather than just declared, and how Swift 5 migration checking can differ from Swift 6 even when an upcoming feature flag is involved.
The funny part is that I already knew most of those pieces. I knew closures inherit actor context. I knew SwiftUI views are main actor-isolated. I knew upcoming feature flags are part of a migration story. And yet I still managed to convince myself of an explanation that fit what I was seeing.
That is the dangerous part. When the first explanation is plausible, it is very easy to stop there. I could have changed all the call sites, written down “closures inherit actor context”, and walked away with a mental model that was close enough to feel right, but wrong enough to mislead me the next time.
Instead, the discomfort kept bothering me. The result did not feel fully justified. So I kept pushing. I made the example smaller, compared the function reference and closure with the exact same type, tried explicit @MainActor, tried Swift 6 mode, and only then did the model start to hold together.
The warning was not telling me my code was broken. At first I thought it was telling me I had a straightforward isolation mismatch. That was close. But not quite. The deeper lesson was that the compiler mode matters. In Swift 5 mode with this upcoming feature enabled, I was looking at a transitional warning. In Swift 6 mode, the same code made sense to the compiler. Adding @MainActor explicitly also made it make sense.
That is the kind of thing you understand properly only when you stop accepting the fix and start asking why it works. Not just until you find an explanation, but until you find one that survives the next question.
", "date_published" : "2026-04-14T22:00:00Z", "id" : "https://alejandromp.com/development/blog/a-small-swiftui-warning-and-a-long-journey-to-understand-it", "summary" : "I was migrating to a newer version of The Composable Architecture, which meant there was a list of deprecations to clean up. One of the things on that list was addingInferSendableFromCaptures as an upcoming Swift feature flag across all our package targets.",
"tags" : [
"Swift",
"Concurrency",
"SwiftUI"
],
"title" : "A Small SwiftUI Warning and a Long Journey to Understand It",
"url" : "https://alejandromp.com/development/blog/a-small-swiftui-warning-and-a-long-journey-to-understand-it"
},
{
"authors" : [
{
"name" : "Alejandro M. P."
}
],
"content_html" : "There was a period during the Swift Evolution Concurrency discussions that I remember very fondly.
And I was on the losing side. Or did I?
I came into the conversation questioning one of the big changes that would later become part of the “approachable concurrency” vision: the move away from the old behavior where non-isolated async functions would naturally hop off the current actor. At the time, I genuinely thought that model was one of the most brilliant parts of Swift Concurrency.
And I still think there was something beautiful in it.
Back then, one of my favorite things about Swift Concurrency was that it let developers stop worrying about threads. You didn’t have to constantly ask yourself if something needed to go “to the background”. You just wrote async code and, most of the time, things were fine. Especially in app development, where so many people come from years of GCD, Combine, Rx, and all sorts of “don’t block the main thread” patterns, that felt like a breath of fresh air.
That old promise, for some reason, mattered to me a lot.
You can even see that framing in some of my older writing. In Limit Swift Concurrency’s cooperative pool I wrote that “you should not worry about threads at all”. I still love that sentence. It captures something important about why Swift Concurrency felt refreshing in the first place.
The conversation around the original pitch and later SE-0461 is one I remember with a lot of affection. It was one of those moments that remind you the Swift Forums can be a very special place on the internet.
You could come in with a strong opinion, push back on a proposal, and instead of getting tribal nonsense, you got thoughtful replies from people who had clearly spent a lot of time thinking about the problem from multiple angles. People like Holly Borla, John McCall, Joe Groff, Mattie, and many others were not just defending a position. They were helping build a mental model.
That is a very different thing. And not something that happens often in the social interwebs these days.
Even though I was not sure about the change, it was genuinely enriching to see what the experts were seeing that I was not. That is one of the best things that can happen in a technical discussion. Not “winning”. Not getting your preferred syntax. Just having your picture of the problem expanded.
And I think that is worth saying explicitly, even now, years later, because we don’t always celebrate that enough. We talk a lot about the final proposal, the final syntax, the final accepted design. But the process of getting there matters too. Sometimes a language community proves its worth not when everybody agrees, but when disagreement is handled with care and clarity.
My discomfort was not really about syntax. It was about the original emotional promise of Swift Concurrency.
I liked that the model encouraged people to stop obsessing over threads. I liked being able to tell developers, especially app developers, to stop trying to manually dispatch everything around. I liked the fact that async code did not automatically mean “you might now be blocking the UI unless you remember to escape somewhere else first”.
That felt like progress.
At the time, I said this in the pitch thread:
“The idea of not blocking the main thread is pervasive in app developers.”
And also this:
“the current behaviour unloads a lot of burden once you embrace swift concurrency.”
And to be honest, I still feel a bit of grief around losing some of that simplicity. I am still annoyed that “be careful what you run on the main actor” is now a thing we have to teach more deliberately. I still think there was something elegant in a model where the default behavior helped developers avoid that whole category of thought.
That part still bothers me a little.
What convinced me was not that my concern was silly. It was that the other side of the tradeoff was bigger than I had fully appreciated.
The key argument, as I came to understand it, was that the old behavior made one particular thing feel easy while hiding a much more serious cost, it pushed ordinary async code into situations where data-race safety became harder to reason about, especially once Swift 6’s stricter checking started showing what was actually going on.
Holly Borla made the core of that case very clearly in the thread. The line that stayed with me was:
“the current default imposes data-race safety errors”
In other words, the old world was nice partly because it let many of us avoid seeing the edges.
And once those edges started becoming visible, the old default no longer looked like a clever simplification. It looked more like a convenience that was too often in tension with the safety model Swift was trying to build.
That did not make the transition emotionally pleasant for me. But it did make it intellectually convincing.
What is funny is that now the transition has happened and we are just used to the new world.
And it is fine.
This is maybe the most humbling part of language evolution. Sometimes a change feels huge when it is being discussed, deeply consequential while it is being pitched, mildly uncomfortable while it is rolling out, and then a year later it is just… the air you breathe.
That does not mean my concerns were invalid. It just means people adapt. Documentation improves, mental models settle, teams teach the new thing. The ecosystem metabolizes the change.
The world did not end and the language did not lose its soul. Swift Concurrency is still good, and in many ways it is better.
And of course, it even made me update my lovely context inheritance table, because if Swift Concurrency changes, apparently my diagrams must suffer too.
What I appreciate the most in hindsight is not only the technical direction, but how it was handled.
The whole “approachable concurrency” effort is a great example of something that was harder to grasp when looked at as isolated pieces. Bit by bit, any one proposal could feel subtle, fussy, or overly specific. But once the direction started to materialize as a coherent vision, you could see the shape of the work more clearly.
And that, to me, is where Holly and the rest of the team deserve enormous credit.
Because the hardest part of changes like this is often not the compiler work. It is the human side. It is helping a community reframe its intuitions. It is sequencing changes so they are survivable. It is explaining tradeoffs without talking down to people. It is accepting that some resistance is not ignorance but the result of people caring deeply about the original design goals.
That is hard work. Maybe the hardest kind.
Technical systems are difficult, of course. But sociotechnical transitions are something else entirely. You are not just changing a rule. You are changing habits, explanations, blog posts, conference talks, intuitions, code review comments, and the tiny phrases people use to teach one another.
From that point of view, I think the approachable concurrency effort has been a real success.
Even after having changed my mind, I still think caring about the main actor matters. Just not in the old GCD way of dispatching everything to the background.
Swift Concurrency is still better than that. It moves the responsibility from the caller to the code that is actually doing the expensive work. That is a meaningful distinction.
And maybe that is another reason why my fondness for the original design never fully went away.
The original promise that attracted me to Swift Concurrency is still a good promise, to help developers think less about low-level execution trivia and more about correctness and structure.
I still want that.
If anything, I think the lesson is that this promise was not defeated, but refined. The language could not keep that simplicity in exactly the form I first fell in love with. But the goal remains the right one.
And that is also something I touched on in another old post of mine, Why you should care about the future of Memory Ownership in Swift. A lot of these changes in Swift can look like they are adding complexity when viewed in isolation. But sometimes they are really the cost of making the language’s deeper guarantees more honest and more usable for normal code.
So maybe the real story here is not “I was wrong” or “the experts won”.
It is that I got to witness a language community do one of the hardest things in software reasonably well: change its mind in public, with care, over time.
I still remember that period with a lot of warmth. Not because every detail was pleasant, but because it reminded me what a good technical community can look like.
You come in attached to a mental model.
You push back.
People answer seriously.
You learn what tradeoff you were underestimating.
The change lands.
Life goes on.
And if things go well, you come out of it not defeated, but enlarged.
Not so bad for the losing side.
", "date_published" : "2026-04-07T22:00:00Z", "id" : "https://alejandromp.com/development/blog/swift-concurrency-approachability-transition", "summary" : "There was a period during the Swift Evolution Concurrency discussions that I remember very fondly.", "tags" : [ "Swift", "Concurrency" ], "title" : "The Swift Concurrency Transition I Learned to Love", "url" : "https://alejandromp.com/development/blog/swift-concurrency-approachability-transition" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "Today Mastodon has officially released their solution for a Share to Mastodon button. I was already using a third party service on this site, but I decided to give it a try because using officially supported tools seems easier to maintain in the future, especially for something I don’t work on every day.
The reason something like this must exist is due to the beauty and the problem with Mastodon. It is not a single website. There are thousands of servers. A share button can’t just link to mastodon.social and call it a day, because the user’s account might be in another server. So a redirect tool that lets you pick your instance must exist. That used to be a third-party problem to solve. Not anymore.
Mastodon now hosts share.joinmastodon.org. Open source, no tracking, runs entirely in the browser, remembers your accounts.
On the code side, this was a one-liner. The old URL:
https://mastodonshare.com/?text=<title>&url=<url>&via=alexito4\nThe new one:
https://share.joinmastodon.org/?text=<title> <url>\nThe official service takes a single text parameter with the content you want to pre-fill. Title and URL combined. That’s it.
Using a third-party share button means you’re depending on someone else’s uptime, their privacy policy, and their continued interest in maintaining the thing. The via parameter I was passing didn’t even make sense for Mastodon the way it does on Twitter. It was just cargo-culted from the Twitter share URL pattern. And honestly, every time I used it myself, even on Twitter, I end up removing the “via…” anyway.
The official tool is the right call. It does less, and that’s a good thing.
If you have a “Share on Mastodon” button on your site using an old third-party service, now is a good time to swap it out. And don’t hesitate to try it with this post, the button is just down below.
", "date_published" : "2026-03-02T23:00:00Z", "id" : "https://alejandromp.com/development/blog/using-the-official-mastodon-share-button", "summary" : "Today Mastodon has officially released their solution for a Share to Mastodon button. I was already using a third party service on this site, but I decided to give it a try because using officially supported tools seems easier to maintain in the future, especially for something I don’t work on every day.", "tags" : [ "Meta", "Web Development", "Open Source" ], "title" : "Using the Official Mastodon Share Button", "url" : "https://alejandromp.com/development/blog/using-the-official-mastodon-share-button" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "I have this weird feeling of deja vu.
![\"Matrix](\"https://alejandromp.com/development/blog/development-dogma-is-back-a-i-agents/matrix-cat.jpg\")
If you know me, you know I think dogma is one of the biggest curses in software engineering. Dogma is what happens when a practice gets treated as universal truth before context, evidence, and tradeoffs are considered.
Dogma is what made OOP feel like the answer to everything. Dogma is what fueled the whole clean-code-industrial-complex. I lived through that as a junior developer. I was taught from university to my early jobs: follow these rules because they are “best practices.” Then you apply critical thinking and realize many of them do not hold in real projects.
Not every time. Not for everything.
Hey, let’s be clear. All these things that get popular actually have good points in them. As much as I’ve pushed back against OOP and dumb rules, some things do make sense. But developers love fashion as much as anyone waiting all year for Paris Fashion Week. It’s just that our fashion makes even less sense. Thankfully I had great mentors that fueled my critical thinking, and I followed people online who were very vocal about it. But the industry didn’t stop at those old programming concepts. Oh no, no! 🤪 They also pushed microservices on everybody until everybody realized they made no sense unless you were one of the few companies that actually needed them.
But I’m not here to rehash the past. I’m here to tell you we are doing it again.
Now we are seeing a new version in the age of AI. In an era of exploration, we already see people trying to push their half-baked dogma just to sell you their books (well, online courses nowadays).
Overcomplicated and useless agentic workflows. Made-up standards that are not proven. Just another thing that this revolution doesn’t need.
And again, some ideas in every wave are genuinely useful. The problem is not the tools, or the core concepts. The problem is turning preferences and unproven opinions into doctrine.
I keep seeing teams copy-pasting agent workflows before proving they improve delivery, reliability, or product outcomes. Without even learning the basics first.
MCP is a perfect mini-case of this pendulum:
Hype, backlash, partial recovery. New acronym, same cycle.
And look, it’s true that MCP solves a real problem in certain scenarios. But 99% of the time it’s not needed. And those who applied critical thinking, who knew the fundamentals of how this tech works, understood the hype wasn’t worth it. Be one of those. Don’t be the sheep that follows the shepherd blindly.
And if you don’t want to think for yourself and you need a guiding hand, look, even Anthropic, the fan favorite for all the vibe engineers, recommends starting simple and only adding complexity when needed.
Every practice needs to prove its value. If it can’t, get rid of it.
If a workflow adds setup cost, cognitive load, or debugging pain, it must pay that back with real outcomes in your context. Not in theory. Not in someone else’s codebase.
Take small functions, one of the most repeated dogmas in our industry. Functions must be small, do one thing. No proof. No study showing smaller functions actually correlate with fewer bugs or better maintainability. Just repetition until it became law.
What actually happens? A dev breaks logic into five tiny named functions. Another dev comes along, sees a function name that looks like what they need, and reuses it. Months later, someone needs to tweak the behavior. Of course they do, because the reusability was born in imagination, not reality. They change that shared function. Now things break in three places nobody expected. If it had stayed in one place, the blast radius would have been zero.
Now think about what the AI equivalent of “functions must be small” is. What rules are being spread as gospel right now, with no proof? Things are moving fast enough that by the time we realize a dogma was wrong, half the industry has already built on top of it. This is actually the best moment we’ve had in years to slow down and think before repeating. AIs are smart, but we also have brains.
Good engineers do not ask, “Is everyone doing this?”
They ask, “Does this work for my context?”
Use AI. Use agents. Experiment aggressively.
But look around. Every tool, every platform, every framework now has its own version of the same thing. Agents, subagents, prompts, skills, modes, MCPs, commands… you name it, someone is selling their spin on it. The complexity is artificial. The race to have the most elaborate setup is just the new cargo cult.
And the irony is that models are actually good enough now that none of it matters that much. If the harness is decent and you know what the AI can and can’t do, just being a good engineer is enough. Asking the right questions. Knowing when to push back. Understanding what you are looking at.
So the last piece of advice is the oldest one. Focus on the fundamentals, and don’t overfill your tools with crap you don’t need.
When you stop questioning and start copying, you are not doing engineering anymore. You are doing cosplay.
Tools are tools, not doctrine.
", "date_published" : "2026-02-22T23:00:00Z", "id" : "https://alejandromp.com/development/blog/development-dogma-is-back-a-i-agents", "summary" : "I have this weird feeling of deja vu.", "tags" : [ "AI Development", "Methodology", "Art of Programming and Paradigms" ], "title" : "Your Agent Stack Is the New Clean Code", "url" : "https://alejandromp.com/development/blog/development-dogma-is-back-a-i-agents" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "Today I made an exciting discovery: the existence of AnchoredRelativeFormatStyle. An API that, as of the time of writing this, barely appears in search results other than Apple’s sparse documentation. And to my surprise, it’s exactly what I’ve been looking for over the past few years.
Some time ago, I wrote about An exploration of FormatStyle as a Dependency. Thanks to my team’s work, we pushed that exploration further and developed an interesting solution (which I should write about!).
During that work, we defined a few date formatters for our application. One of the most interesting ones was a formatter for relative dates.
In the old times, with Foundation Formatter APIs, to get a formatted string for the relative time between two dates, things like “2 days ago” or “Tomorrow”, one could use:
localizedString(for date: Date, relativeTo referenceDate: Date) -> String \nIn the new Foundation FormatStyle APIs, the way to do that is using the nice fluent API on a date:
.formatted(.relative(presentation: .named))\nThe new API looks elegant for quick code and tutorials. However, it becomes problematic when:
All these issues arise from the same root problem: the implicit dependency on the current Date(). In the Formatter API you could pass the two dates but in the new Style API you just call formatted on a single Date, without a way to pass a second one.
In our system using swift-dependencies, we had workarounds with limitations. While investigating improvements, I stumbled upon AnchoredRelativeFormatStyle - which solves our exact problem by allowing two dates!
As someone who watches nearly every WWDC video and stays current with the Swift ecosystem, I was surprised I’d never heard of this API. A Google search returned just a couple of results with no substantial information. Was I imagining things?
Thankfully, we live in a world in which Foundation is open-source and easily accessible, so I could just go to GitHub and actually check not only the source code for AnchoredRelativeFormatStyle but also its history. Thanks to that, I could find the Foundation proposal that described the background of this new API: The DiscreteFormatStyle Protocol.
The proposal document is very interesting, but it took me a couple of reads to fully grasp it. I recommend you take a read, but its purpose is to improve the existing FormatStyle infrastructure to enhance its performance when used directly in user interfaces, read: SwiftUI.
If you’re the one implementing SwiftUI Text and accept a string made from a formatter like the ones mentioned above, you can see how the existing API limits your optimizations. Your system needs to keep the UI up to date with an Input, “the relative target date” that doesn’t change, but internally the output (the string) depends on a moving target, “now”, which you don’t have visibility on because remember, the API is tomorrow.formatted(.relative). This means you don’t have any alternative other than recomputing that formatted string at a high framerate, even if the output of the format will only change once a second or even once a minute.
This is why the proposal introduced DiscreteFormatStyle, a new protocol that allows FormatStyles to expose when an output is expected to be different given the style configuration. This allows UI implementors to optimize the refresh rate by asking the style when it needs a refresh to be scheduled.
Some existing formatters were able to conform to the protocol without problems, but RelativeFormatStyle couldn’t because its current design has Date() as a hidden dependency, which means the format implementation is not a pure function and thus breaks the assumptions of the infrastructure around the styles. From the infrastructure’s point of view, “tomorrow” is constant so it could optimize things, but the fact that every call to format with the same input can give a different output breaks the assumptions. This is a bit tricky to understand until you internalize how format infrastructure works, with the styles themselves being just value types that are suposed to just be a wrapper around a pure function.
To solve the above, DiscreteFormatStyle’s design is a bit backwards from what we would expect. A naïve design for this API would be to have a parameter for the “now” in the style itself, something like:
tomorrow.formatted(.relative(to: now))\nThat would solve the problem I have with the existing relative style by removing the implicit dependency on Date(). But it wouldn’t solve the problem about performance as, even if now visible to us, the dependency on now that would change all the time wouldn’t be visible to the formatting infrastructure (aka format wouldn’t be a pure function).
So DiscreteFormatStyle works the other way around. The “anchor”, the data that doesn’t move, is part of the style, and the moving date is instead the instance where format is called on. Something like:
now.formatted(.relative(to: tomorrow))\nBut, as stated in the proposal, since this would break expectations from developers, the Foundation team decided to not offer the static method API at all. If you want to use this, you need to construct the FormatStyle yourself, which by the way, as we explored in my previous post, you can do for any FormatStyle, you just need to know the type.
Date.AnchoredRelativeFormatStyle(anchor: tomorrow).format(now)\nWe explicitly decided against adding such function for Date.AnchoredRelativeFormatStyle as that style always formats its anchor date, and only uses the actual format input as the reference date. Thus any spelling that starts with Date.now.formatted is ultimately misleading or very verbose. - A static factory function for
Date.AnchoredRelativeFormatStyle.
I understand that reasoning, but it also makes this API basically hidden and unknown, which is quite unfortunate. I guess if the main use case is as part of the SwiftUI Text it makes more sense, but for me this API has way more uses than that.
Since we already have our own bit of sugar on top of FormatStyles that mixes it with swift-dependencies, it’s quite easy for me to improve this API. One could argue if I should do it, but I think for my use cases it’s totally fine.
If you want to also be naughty, it’s quite easy:
public struct NaughtyRelativeFormatStyle: FormatStyle {\n public typealias FormatInput = Date\n public typealias FormatOutput = String\n \n var referenceDate: Date\n \n public func format(_ value: Date) -> String {\n referenceDate.formatted(Date.AnchoredRelativeFormatStyle.init(anchor: value))\n }\n}\n\nextension FormatStyle where Self == NaughtyRelativeFormatStyle {\n public static func relative(\n to referenceDate: Date\n ) -> Self {\n NaughtyRelativeFormatStyle.init(\n referenceDate: referenceDate\n )\n }\n}\n\ntomorrow.formatted(.relative(to: now))\nOf course the code above doesn’t implement all configuration options available on Foundation, but adding them is quite easy. I’ll leave that up to you so you make conscious decisions if you want to be naughty ;)
This was a very surprising day, I was not expecting to find such a hidden API that actually solved my problems. I still needed to do some work because we still want to use swift-dependencies, but at least I could use a modern API on new OSs and stop relying on the old Formatters. It also made me look again deeply into FormatStyles, which is a very nice API on the usage side but has some fascinating intricacies in its implementation.
", "date_published" : "2024-10-23T22:00:00Z", "id" : "https://alejandromp.com/development/blog/anchored-relative-format-style-the-hidden-replacement-for-date-relative-format-style", "summary" : "Today I made an exciting discovery: the existence ofAnchoredRelativeFormatStyle. An API that, as of the time of writing this, barely appears in search results other than Apple’s sparse documentation. And to my surprise, it’s exactly what I’ve been looking for over the past few years.",
"tags" : [
"Swift"
],
"title" : "AnchoredRelativeFormatStyle: The Hidden Replacement for Date RelativeFormatStyle",
"url" : "https://alejandromp.com/development/blog/anchored-relative-format-style-the-hidden-replacement-for-date-relative-format-style"
},
{
"authors" : [
{
"name" : "Alejandro M. P."
}
],
"content_html" : "Recently, while watching a Tsoding stream, I saw something that piqued my curiosity. Alexey demonstrated how one of his applications could render a video just by calling into the ffmpeg binary directly, instead of using it as a source code dependency or even a static or dynamic library linked to his program.
This caught my attention because, although I sometimes use binaries as dependencies by calling them (a good example is how I call the tailwindcss binary from Genesis to generate this website), it had never occurred to me to use them for something as sophisticated as rendering a video. Calling them to do something they can do on their own, like reading some files and generating output? Sure. But calling a binary and somehow passing the data to generate a video seemed like another level entirely. However, the more I thought about it, the more the idea made sense. After all, it’s all just binary data flowing through pipes. So, I decided to spend some time having fun with the idea.
The first part wasn’t very difficult; I just had to refresh my knowledge about the incantation of parameters necessary to ask ffmpeg to generate a video from a few frames, something I hadn’t done in years. With a list of parameters at hand, I started writing some Swift code to spawn a Process to run ffmpeg.
class FFMPEG {\n let process = Process()\n let pipe = Pipe()\n \n func startRenderingVideo(width: Int, height: Int, framerate: Int) throws {\n let resolution = "\\(width)x\\(height)"\n\n process.currentDirectoryURL = // directory to generate the file\n process.executableURL = // path to ffmpeg in your system\n process.arguments = [\n "-loglevel", "verbose",\n "-y",\n \n "-f", "rawvideo",\n "-pix_fmt", "rgba",\n "-s", resolution,\n "-r", String(describing: framerate),\n "-i", "-", \n \n "-c:v", "libx264",\n "-vb", "2500k",\n "-pix_fmt", "yuv420p",\n "output.mp4"\n ] \n \n // set a pipe to feed the frames via standard input\n process.standardInput = pipe \n \n try process.run()\n }\nWith this code, I was able to spawn ffmpeg and make it wait on standard input for a bunch of frames. Of course, the parameters can be tweaked as needed, but these worked quite well for what I wanted to try.
The next part was the interesting one: how to pass the raw bytes that defined each frame. For this, we need to look at the parameters I used. We asked for each pixel to be an rgba color and specified the resolution of each frame. So the next step was to create a buffer of bytes with the correct shape.
Thankfully, on macOS, we have great solutions as part of our tools. In this case, an old one: CoreGraphics. I could have done this part manually to make it work on other platforms, but since I was just having some fun and wanted to generate images with SwiftUI, I went with the easy solution. It would be interesting to use something else that worked on other platforms and make the bytes manually, but that’s an exercise for another day.
Here’s the bit of code needed to take the bytes from a CGImage and feed them into the Pipe:
func sendFrame(_ cgImage: CGImage) {\n let width = cgImage.width\n let height = cgImage.height\n let bitsPerComponent = 8\n let bytesPerPixel = 4 // RGBA = 4 bytes per pixel\n let bytesPerRow = bytesPerPixel * width\n let totalBytes = height * bytesPerRow\n\n var pixelData = Data(count: totalBytes)\n pixelData.withUnsafeMutableBytes { (ptr) in\n let context = CGContext(\n data: ptr.baseAddress,\n width: width,\n height: height,\n bitsPerComponent: bitsPerComponent,\n bytesPerRow: bytesPerRow,\n space: CGColorSpaceCreateDeviceRGB(),\n bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue\n )!\n\n context.draw(cgImage, in: CGRect(x: 0, y: 0, width: CGFloat(width), height: CGFloat(height)))\n }\n\n pipe.fileHandleForWriting.write(pixelData)\n}\nA few things to note in the above code:
CGContext needs to match what we’ve told ffmpeg to expect: four bytes per pixel, 1 byte per color component, etc.Data where I ask Core Graphics to draw the image. I would be curious if there was a different way of doing this because I imagine the draw actually needs to iterate through the image, but maybe there is a way to dump its bytes directly. Although that would assume the format is the same, so I guess it wouldn’t be very portable.Pipe, which is set as the standard input of the ffmpeg process, taking a file handle and writing the data into it. Through the magic of the operating system, this will transfer the bytes from one process to the other, letting ffmpeg render the frame of the video.The last bit we’re missing is very easy: just a way to tell ffmpeg that there are no more frames incoming. Otherwise, it will just keep waiting for more data. To do this, we just close the file handle of the pipe. Then it’s just a matter of waiting for ffmpeg to finish the rendering.
func endRendering() {\n pipe.fileHandleForWriting.closeFile()\n process.waitUntilExit()\n}\nAnd with this, we have a very simple class that will render a video from our given frames. Under the hood, it will use ffmpeg, but our usage code doesn’t have to worry about the intricacies of it anymore.
class FFMPEG {\n func startRenderingVideo(width: Int, height: Int, framerate: Int) throws\n func sendFrame(_ cgImage: CGImage)\n func endRendering()\n}\nTo try this out, I wanted to make a small animation with SwiftUI. From time to time, I have the need to create some animation to support an explanation, but I never do it because reaching for motion graphics software is a big step for something so simple. So I thought this would be the perfect time to make a proof of concept with SwiftUI.
The idea is quite simple: prove that we can get the frames of an animation that changes the contents of some text and another that moves a shape through the screen.
The SwiftUI part is, of course, very simple. It’s just a stack with some text and shapes:
VStack {\n Text(text)\n .foregroundStyle(Color.white)\n Circle()\n .fill(.red)\n .frame(width: circleSize, height: circleSize)\n .offset(x: (circlePosition+circleSize/2) - (width/2))\n Rectangle()\n .stroke(.green)\n}\n![\"SwiftUI](\"https://alejandromp.com/development/blog/using-binaries-as-libraries/ffmpegswiftuiframe.jpg\")
Getting an image, specifically a CGImage, from this view was also very trivial thanks to SwiftUI’s ImageRenderer.
let view = ToRender(text: text, circlePosition: circlePosition, width: width, height: height)\nlet renderer = ImageRenderer(content: view)\nlet cgImage = renderer.cgImage!\nffmpeg.sendFrame(cgImage)\nThe tricky part was figuring out how to get each frame. I would love to use SwiftUI animations and somehow just get a snapshot for each frame, but I’m not sure there is a trivial way of doing it that allows me to leverage SwiftUI animations. So instead of going down that rabbit hole, I opted to drive the animations myself.
This means, as you can see in the View above, that I can’t just use animation directly in the views. Instead, I need to manipulate their properties, like the circle offset, and then compute that myself on each frame. Luckily, SwiftUI exposes a few core types for animations that are separate from the view layer, so I can use that instead of letting SwiftUI drive the animation.
For example, we can use KeyframeTimeline to combine LinearKeyframe and even SpringKeyframe to then request the timeline value at a specific time or progress.
For the text, it’s quite simple for what I need. Knowing at which frame we are, we can just interpolate to know how many characters of the full text we want to display and just prefix the string up to that index.
let fullText = "Hello World!"\n// Animate text\nlet tEnd = Double(fullText.count-1)\nlet tkf = KeyframeTimeline(initialValue: 0) {\n LinearKeyframe(tEnd, duration: 1.5)\n SpringKeyframe(tEnd/2, duration: 0.5)\n CubicKeyframe(tEnd, duration: 1)\n}\nlet text = String(\n fullText.prefix(upTo: fullText.index(fullText.startIndex, offsetBy: Int(tkf.value(progress: progress))))\n)\nFor the circle that we want to move through the screen, we can use the same technique of using a keyframe timeline and asking it to get us the value at a certain time.
// Move Circle\nlet startPosition = 0.0\nlet endPosition = Double(width) - 100\nlet keyframes = KeyframeTimeline(initialValue: startPosition) {\n LinearKeyframe(endPosition/2, duration: 1, timingCurve: .linear)\n LinearKeyframe(endPosition/3, duration: 1, timingCurve: .easeInOut)\n SpringKeyframe(endPosition, duration: 1)\n}\nlet circlePosition = keyframes.value(progress: progress)\nAnd with this, I can just make a loop that generates all the frames needed and feeds them into ffmpeg.
let totalSeconds = 3\nlet totalFrames = framerate * totalSeconds\nfor i in 0..<totalFrames {\n let progress = CGFloat(i) / CGFloat(totalFrames - 1)\n // ... generate frame and send to ffmpeg\n}\nThe point was to have fun and explore the capabilities of calling binaries as if they were libraries, avoiding the integration cost that comes with source code or libraries in other languages. There’s always a trade-off, and of course, source code or library integration exists for good reasons. I haven’t come out of this thinking binary integrations are always the best solution, but now I have more knowledge and practice with them, so it’s yet another tool in my belt. And that was a goal well accomplished.
On the other hand, I have a proof of concept for creating videos from SwiftUI, which opens the door to using this technique in the future when I want to explain some things without having to do it with a full-featured video editor. Doing it in SwiftUI and code is actually faster for certain things.
And finally, I hope I’ve piqued your interest as mine was piqued! Have fun with programming!
", "date_published" : "2024-10-06T22:00:00Z", "id" : "https://alejandromp.com/development/blog/using-binaries-as-libraries", "summary" : "Recently, while watching a Tsoding stream, I saw something that piqued my curiosity. Alexey demonstrated how one of his applications could render a video just by calling into theffmpeg binary directly, instead of using it as a source code dependency or even a static or dynamic library linked to his program.",
"tags" : [
"Swift",
"Art of Programming and Paradigms"
],
"title" : "Using Binaries as Libraries",
"url" : "https://alejandromp.com/development/blog/using-binaries-as-libraries"
},
{
"authors" : [
{
"name" : "Alejandro M. P."
}
],
"content_html" : "Sometimes in command line tools we want to perform some cleanup final task before the process is killed. To detect this scenario we can hook to unix signals like an interrupt and perform the needed work before existing from the process.
This post was originally written in 2016-05-29 as a follow up to The state of Swift scripting and discussed my old library Trap in GitHub. Since then the ecosystem has grown a lot so it has been updated in 2024 with a more modern approach.
In the server ecosystem this is very well handled with the swift-service-lifecycle package, that brings support for graceful shutdown to concurrency tasks. What might surprise you is that the same package exposes a module for handling unix signals, without the service part. I find this ideal for command line utilities that don’t require the full service lifecycle of a server application but still want to handle unix signals.
To include this module you just need to depend on the library, but instead of including the service module into your target, you just include UnixSignals.
dependencies: [\n .package(url: "https://github.com/swift-server/swift-service-lifecycle.git", exact: "2.6.1")\n ],\n targets: [\n .executableTarget(\n name: "...",\n dependencies: [\n .product(name: "UnixSignals", package: "swift-service-lifecycle")\n ]\n ),\n ]\nWith this implace you can now import the UnixSignals module and instantiate a UnixSignalsSequence with the specific signals you want to listen to.
import UnixSignals\n\nfor await signal in await UnixSignalsSequence(trapping: .sigint) {\n print(signal)\n}\nIf you run this on your terminal and try to interrupt it with Ctrl + C you will see ^CSIGINT printed in the console but the process won’t stop. Now that you are handling the interruption is up to you to actually exit from the process. Isn’t it nice how respecful unix is?
If you want to kill the process use
Ctrl + Z. This will send a different signal and since we’re not handling that one it will behave as default and kill the proess. Alternatively just use Activity Monitor and force quit it.
With this power in our hands we can see an example of how it would work. In the following code we spawn two child tasks, one keeps a running counter that increments after a few miliseconds; the other awaits for an interrupt signal to be triggered.
await withTaskGroup(of: Void.self) { group in\n group.addTask {\n var i = 0\n while true {\n print(i)\n i += 1\n try? await Task.sleep(for: .milliseconds(500))\n }\n }\n group.addTask {\n for await signal in await UnixSignalsSequence(trapping: .sigint) {\n print(signal)\n print("Shutting down...")\n try? await Task.sleep(for: .seconds(2))\n exit(EXIT_FAILURE)\n }\n }\n}\nRunning this and using Ctrl + C we can see how the running counter keeps printing for a few extra seconds before the process is closed.
0\n1\n2\n^CSIGINT\nShutting down...\n3\n4\n5\n6\n7\nThis illustrates how we can have extra time to perform a gracefull shutdown of whatever process we are running.
If you need something more complex make sure to check out all the capabilities from swift-service-lifecycle.
", "date_published" : "2024-10-02T22:00:00Z", "id" : "https://alejandromp.com/development/blog/swift-catch-os-signals-trap", "summary" : "Sometimes in command line tools we want to perform some cleanup final task before the process is killed. To detect this scenario we can hook to unix signals like an interrupt and perform the needed work before existing from the process.", "tags" : [ "Swift", "Scripting" ], "title" : "It’s a trap! React to Unix signals in Swift.", "url" : "https://alejandromp.com/development/blog/swift-catch-os-signals-trap" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "Recently, I finished an almost final draft of my novel and decided it was time to refresh my online presence and website. Instead of starting my next novel, I dove into creating the next version of my site, what I call alejandromp4. And, of course, you know what that means… using a new static site generator! Yes, I have a problem with focusing my hobbies; I’m working on it.
Let me first tell you what was the status quo of the version 3 of my site. It was built using Publish, a static site generator written in Swift. That worked really well as Swift is my favorite language, but more than that, it’s the ecosystem where I spend most of my time. This helps me avoid surprises when I come back to the website after a while, something I disliked about previous incarnations based on Ruby or Node, ecosystems that seem to break every time I had to publish an article.
But Publish wasn’t all roses. I have some peculiar requirements for my site around taxonomies and multiple sections that needed to work well together. Although Publish offers some customization options, it wasn’t enough. I quickly had to change some things in Publish, which meant discarding the nice defaults that come with it. I also had to fork it and open some internal functions to avoid repeating what was already built. Over time, I grew comfortable with that codebase and my customizations, but it’s not something I want to deal with long-term.
So, I thought it was a good occasion to look for a replacement.
Recently, another contender has appeared: Ignite. There are many others, but this one has the backing of a prominent figure in the ecosystem, which has propelled it to popularity. I spent some time with it, and it’s not that dissimilar from Publish—in the end, all static site generators are more or less the same. There are things I really like about Ignite, the documentation and the easy of use is really something to admire. But ultimately I decided it wasn’t for me. In an effort to be easy to use out of the box, it’s too tight for my taste. For example, to build pages, you need to accept using Bootstrap and a DSL, which is nice for a quick start but I needed the flexibility to not only use another CSS system (because I don’t like Bootstrap) but also use existing HTML templates that were already good to go.
I looked around for a bit and found other interesting alternatives with intriguing declarative systems to build the site in various shapes and forms. This is a trend in modern static site generators—a sort of declarative way of specifying pages and content for the generator. It’s an approach that aims to simplify the configuration process, though it comes with its own set of tradeoffs.
Ultimately, I came to the conclusion that it was time for me to tackle the problem myself. But I you should probably look at the mentioned projects if you are in need of a static site generator, they are very good and probably more inline what you expect.
With a few years of experience and having seen how other generators work, I thought it wouldn’t be too hard to make one myself. In fact, the core idea is an old one, as is the name, but I never pursued it because I didn’t want to have something to maintain.
Now, I was not happy with my current situation, a forked engine with the original project barely maintained. And if I had to switch to another project that, even if promising today, could be abandoned any time, I wouldn’t be in a better position. So the tradeoff of making my own is very different.
But if I have to build my own site generator, and make sure doesn’t take too much time from writing the actual content for the blog, I need to make a few decisions that will help me now and in the future. So I defined a core rule: simplicity.
This meant no fancy declarative rule system, no fancy HTML DSL, no building things from scratch, etc. But the best thing came with the realization that doing things that way woudl actually bring me all the benefits that I found lacking in other solutions. It was a win win sitaution!
So, armed with valor, some open-source code that I could reuse, and a few ideas in my mind, I sat down and started writing requirements to not lose the north star, drawing some diagrams, and finally coding.
The first overarching goal was to keep things simple—no, really, as simple as possible. I knew that remaking my entire site wouldn’t be trivial; there’s a lot of custom logic and hacks I’ve done to Publish that, although simpler in my own engine, still had to be ported. I also have some peripheral tools for my site (a CLI to work with it and a tool to create posters), but I was confident those could be moved directly.
I acomplish this by making the API very clear and specific, without fancy declarative engines or DSLs. What you get are just a few small protocols and a bunch of functions that you can call.
The other goal was to keep things flexible. Not to make this a fancy library, neither for my future self. It wasn’t flexibility for the sake of flexibility or purity. It was flexibility because I already know that my current requriements have some complexity that requires it.
Learned from experience, I don’t want to have defaults that become irrelevant as soon as you want to customize things. And if you want to customize things you should be able to reuse as much as the engine as possible without having to fork and make things public. This means that I don’t want to have a single call that does everything, but instead the tools that I can compose as needed.
Genesis provides APIs to load content and generate pages using simple function calls. It’s procedural on purpose. Just call the functions however you want without being tied to a specific structure or rule system.
For example there is a clearBuildFolder() function that does what the name indicates. But you don’t have to call it if you don’t want, nobody is forcing you. Of course when publishing your site you probably want to do a clean generation, but while iterating and previewing it? It’s just a waste of time. Or not. You decide. That’s the point.
What I wanted for sure the new generator to give me was the flexibility to handle pure HTML templates directly so I could take a beautiful template made from a good designer and just use it. But also I knew that eventually I would want to write some HTML in Swift with one of the fancy DSLs that everybody uses. But which one was another story. Beacuse of that I didn’t want to imbue the engine with any DSL, I wanted to engine to just work witht the minimum thing that needed.
So what’s the only thing that is needed as an input to generate a file that can be served? A String.
So instead of using a fancy DSL for typed Swift HTML, Genesis simply works with strings. This simplicity opens up a world of possibilities: from using existing HTML templates to experimenting with various Swift HTML DSLs, all without changing the core engine.
The advantage is that acomplishing this is also very simple, you just need a function that returns a String.
func render(context: Context) async throws -> String {\n """\n <html>\n <body>\n <p>A page in your site is just a String. Easy.</p>\n </body>\n </html>\n """\n}\nI know many will be screaming on seeing this, but honestly I’ve written most of this site you are reading in Swift String interpolation and is totally fine. Reusing “components” is just making a separate function that returns a String. It doesn’t get simpler than that.
And the best thing is that I can easily add fancy DSLs on top. It took me five minutes to add suport for a new DSL library, elementary, and a few more to try another one. Adding support for loading tempalted files is also trivial.
Something else I didn’t want was to tie the engine to specific web frameworks. For example, I’m not a fan of Bootstrap so that wouldn’t come prebacked. The old version of the site used Bulma but the previous version of my author site used TailwindCSS. So the engine doesn’t care what you use, again, it simply expects a String. It’s actually very nice how different requirements coalesce into the same goal.
Genesis doesn’t automatically load any dynamic content for you. I don’t want it to check specified folders for predefined files. Instead Genesis expects you to define ContentLoaders to load dynamic Content. This allows you to determine what the content is and how it’s loaded, from markdown files, a database, or a remote CMS. The engine doesn’t care about it.
A simple async function is all you need to implement. Even what “content” is is not defined, you bring your own.
struct BlogLoader: ContentLoader {\n\tfunc load(context: Context) async throws -> sending [any Content] {\n let contentDirectory = await context.contentDirectory\n let contents = try FileManager.default.contentsOfDirectory...\n return try contents\n .map { BlogPost(...) }\n}\nBesides loading content, the other core concept of the engine is generating pages. A Page is a type that implements the render function explained above. That’s it. This makes it very trivial to generate single pages for your site, things like the Home or the Author page.
But there are pages that need to be rendered multiple times, for each instance ot the loaded content. like each post page. For this the engine has another simple protocol, the PageProvider. And again, it’s a very simple requirement: just return a list of pages.
func source(context: Genesis.Context) async throws -> [any Page]
These few basic requirements are what defines the core of the engine, which also makes it very easy to understand what’s the process of generation and how you interact with it.
And the reality is that that’s all a static site generator is at its core. When you put it this way it’s not that scary anymore. If you even think about it, and I have, half of these protocols are not even necessary from how simple they are. But I found that having them helped me have a better mental model of the core of the engine.
The beauty of this simple architecture is that it let’s me expand it as needed. I already mentioned above that adding a DSL for HTML is very simple, but there is more that can be done.
To reiterate, the core of the engine doesn’t do anything for you. You might expect RSS, sitemaps, etc to be generated, like it happens in most other engines. But in Genesis that’s up to you, you give it the Pages that you want to generate.
But of course, RSS and Sitemaps are pages that are quite standarized. So for that I took some code from other engines and with a few tweaks it was working fine for my site. Now this are bundled in the library but is up to you to use them or not.
This is probably the first thing anybody wants from a static site generator, so you might be surprised that, again, Genesis doesn’t have support for Markdown fiels embeded into its core. That’s another consious decision. I don’t want to make the mistake of embeding a specific library that will make things harder for the sites build with the engine, I’ve already suffered that in the past.
But agian, Genesis doesn’t need this embeded, it can be added from the outside because its core is very small. In my case I’ve decided to use Apple’s swift-markdown because I think is a safe bet nowadays, it makes it trivial to parse Markdown fiels intro an AST that then can be transofrmed into a String.
Crucially, the fact that I have full control over the Markdown library used and of the type that defines a “post” means that it has been trivial to do something that I’ve found impossible in any other site: keep the markdown tree trough all stages of generation so it can be tweaked in specific pages. This small thing has given me so many headaches over the years that I can’t believe how trivial it is in Genesis. Just because you have the contorl and you decide.
By going back to the basics, I’ve been able to build a static site generator and port my site to it in a few days. I love how Genesis offers a flexible and powerful static site generator that doesn’t constrain you to specific workflows or technologies. It’s designed to grow with your needs, allowing for simple setups for basic sites and complex configurations for more demanding projects.
I haven’t optimized for a marketable experience, so while it may not have the polish or out-of-the-box features of some popular generators, Genesis provides the building blocks for creating exactly the site you want, without fighting against pre-defined structures or limitations. It’s a testament to the power of simplicity and the value of understanding your tools from the ground up.
Of course this is just the begining, I will continue to develop and use Genesis for my own site, I’m excited to see how it evolves. I already have a few ideas to add more batteries while keeping the core simple.
And finally, this is not a sales pitch. As I said at the start, you probably want to check the existing generators with bigger communnities, but if you like things simple and are not afraid of getting your hands dirty you can try Genesis. Or maybe if you want to build your own this post can serve as a guide and word of advice: keep it simple!
", "date_published" : "2024-09-24T22:00:00Z", "id" : "https://alejandromp.com/development/blog/back-to-the-basics-with-genesis", "summary" : "Recently, I finished an almost final draft of my novel and decided it was time to refresh my online presence and website. Instead of starting my next novel, I dove into creating the next version of my site, what I callalejandromp4. And, of course, you know what that means… using a new static site generator! Yes, I have a problem with focusing my hobbies; I’m working on it.",
"tags" : [
"Swift",
"Project",
"Release",
"Meta"
],
"title" : "Back to the basics with Genesis",
"url" : "https://alejandromp.com/development/blog/back-to-the-basics-with-genesis"
},
{
"authors" : [
{
"name" : "Alejandro M. P."
}
],
"content_html" : "In my team, one of the things we always make sure of is keeping our dependencies up to date. We rarely add a dependency without a really good reason, and when we do, we assign an owner who is responsible for keeping it up to date.
These owners always keep an eye on new updates and make it a task to go through them as soon as they can. But sometimes, life happens, and one is not able to keep up with it. More often than not, though, the reason why updates are not kept on top of is simply because people forget that it’s part of their responsibilities. And I don’t blame them. Right now, we just keep the list of owners in our documentation site, which is a very passive way of doing things.
Instead, we’ve now worked on upgrading our nightly notification system! This existing system not only runs a set of unit tests and sends a message with test results and code coverage to our Slack channel, but it also shows a list of outdated dependencies thanks to swift-outdated and some custom code on top that is part of our development tools.
So before, the message just included a table of dependencies to be updated:
| Package | swift-composable-architecture | 1.12.0 | 1.13.0 | ❗️
But now, we’ve added an @mention to the Slack user responsible for each outdated dependency.
In my experience, the reason updates often get neglected is simply because it can be easy to forget or overlook tasks that aren’t constantly in front of you. That’s why I think having a system for notes is so crucial - it helps keep important responsibilities top-of-mind. By providing a daily reminder of the pending updates they are responsible for, our new notification system has helped streamline things for the whole team.
Doing this is very simple since we already have the infrastructure in place. It was just a matter of having a mapping between dependencies and Slack users in our CLI. Something very low-tech that does the work 👌
But there was an extra requirement of mine: if there is a dependency we don’t have an owner for, we send an error on the nightly message so we can assign one immediately. This is something not trivial with swift-outdated because that reads from the .resolved file, which has no information about what dependencies are transitive and which ones are directly yours. Since in our opinion, we don’t want to be bothered with transitive dependencies, we don’t assign owners to those.
To solve this, we read the Package.swift file in advance so we know what the direct dependencies are. This is quite simple, as SPM makes it very easy to get a JSON representation of a package: swift package dump-package.
So work done.
But you know me, I can’t avoid getting excited with interesting ideas. So when discussing how to approach this with my team, I wondered… what if we could attach the owner to the dependency itself in the Package.swift file? Well, hold my glass of water.
Something I love about SPM is that the package definition file is actually a Swift file, which means you can run Swift code in it. Thanks to that, we can add an API to the PackageDescription that does what we want.
.package(url: "...", exact: "...", owner: "...")\nTo do this, we can extend the SPM types with our own method. Of course, we need to return what SPM expects.
extension PackageDescription.Package.Dependency {\n static func package(\n url: String,\n exact version: Version,\n owner: String\n ) -> PackageDescription.Package.Dependency {\n .package(url: url, exact: version)\n }\n}\nSo what’s the point of having the new parameter if it’s not used? Well, that we have it in the same source, and we can extract it from it!
But if you’re thinking SPM dump will include this data, well, of course, it won’t, as SPM doesn’t know anything about it. That doesn’t mean we can’t get it; it just means it’s our work. For things like this, I always rely on swift-parsing, and it makes it quite easy to extract the dependency from the file.
This is the output of running a quick proof of concept command line:
▶ ./spm-owners Package.swift\n┏━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓\n┃ ┃ Package ┃ Version ┃ Owner ┃\n┃ ┃ <String> ┃ <String> ┃ <String> ┃\n┡━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩\n│ 0 │ swift-parsing │ 0.13.0 │ Martin │\n│ 1 │ swift-argument-parser │ 1.5.0 │ Martin │\n│ 2 │ swift-composable-architecture │ 1.13.0 │ Alex │\n└───┴───────────────────────────────┴──────────┴──────────┘\nI love this! Having the ownership data as part of the Package.swift makes it so things are always in sync and up to date.
Of course, I’m not using this in our team’s system because it’s not production-ready; it’s just a proof of concept. The big disadvantage is that although Package.swift can run Swift code, you can’t just import a separate package, which means one would have to copy-paste the code above manually. Not a deal-breaker, but not nice enough for me to want to maintain 😂 If one could import in the package file, it would be another story.
So there you go, an interesting proof of concept that has kept me entertained for a couple of hours. I wish SPM would officially support a way to accomplish this, somehow to be able to add metadata and that it would be kept for other tools. And maybe there is, and I’m not aware?
You can check out the proof of concept on the spm-owners repo, if you are curious.
", "date_published" : "2024-08-20T22:00:00Z", "id" : "https://alejandromp.com/development/blog/swift-package-manager-dependency-owners", "summary" : "In my team, one of the things we always make sure of is keeping our dependencies up to date. We rarely add a dependency without a really good reason, and when we do, we assign an owner who is responsible for keeping it up to date.", "tags" : [ "Swift", "Swift Package Manager" ], "title" : "Swift Package Manager Dependency Owners", "url" : "https://alejandromp.com/development/blog/swift-package-manager-dependency-owners" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "Every year SwiftUI improves and gets new modifiers that widen the capabilities of the framework. Sadly, as responsible developers, we can’t use any of that because our users take some time to update and, as opposed to the Android ecosystem where Jetpack Compose is just a library embedded in every app, we need to wait for our users to be at the required minimum OS version to enjoy those fancy new tools.
Or do we?
There are some APIs that are easy to backport if we disregard the old versions of the operative system. This may sound awful but is a valid option that is worth considering. If you know you have a very little percentage of users stuck in the old version but you can’t get rid of it because of some policy, you know the impact is very minimal. And if time has already passed and dropping that version is on the horizon, you have more reason to plan for the future and not get stuck in the past. No matter what, we should make sure that users in the old version don’t get a bad experience. It may be not perfect and modern, but they still should be able to use the app properly. It’s a case-by-case decision that you have to take, but if you do, here is how to pull it off.
We will focus on SwiftUI modifiers. Other features can also be backported, but they will need slightly different techniques. The one for modifiers is actually quite simple, but it always depends on the functionality itself.
I’ve used this technique for a while, and it works very well. For example the scrollDismissesKeyboard(_:) modifier is a good candidate. It’s a new functionality that users in old versions won’t miss because they wouldn’t have access to it before (well, unless your app was UIKit, again, case by case).
The first step is to copy the modifier function signature in your own View extension:
extension View {\n /// docs...\n @available(iOS 16.0, macOS 13.0, tvOS 16.0, watchOS 9.0, *)\n public func scrollDismissesKeyboard(_ mode: ScrollDismissesKeyboardMode) -> some View\n}\nI also recommend copying over the documentation so the users of this function will get all the info they need. Just as if it was the legitimate function from the framework.
Conceptually the implementation of the function is very simple: we check in which OS version we are and we call the SwiftUI function when available and fallback to something else when not. This applies to all modifiers you want to port, but there are two things to consider.
What do you do as a fallback? That’s the first question to consider and it will depend on the feature, its complexity, how much worth it is for you and a multitude of other aspects, technical and non-technical. This is the “case by case” part of this work.
In this example, the fallback is simply to do nothing. And that works for many cases, really. To implement this, we just need to return self in the old version so our modifier does nothing with the view.
if #available(iOS 16.0, *) {\n self\n .scrollDismissesKeyboard(mode)\n} else {\n self\n}\nThat’s what we want, easy, right? Well, remember that for this to work, we need to opt in this function into the ViewBuilder DSL. Check out ViewBuilder vs. AnyView for more details about this.
If your modifier didn’t take any parameters, that would be all you needed, but that’s rarely the case.
Most modifiers take some parameters to adjust its functionality. Those types are often new and thus not present in old versions, so we need to port those too.
The process for that is similar, just copy the existing types into your own file.
public struct ScrollDismissesKeyboardMode {\n public static var automatic: ScrollDismissesKeyboardMode { get }\n public static var immediately: ScrollDismissesKeyboardMode { get }\n public static var interactively: ScrollDismissesKeyboardMode { get }\n public static var never: ScrollDismissesKeyboardMode { get }\n}\nNow that’s a fine way to start, but I find it significantly easier to work with an enum. That way, you don’t have to worry about internal implementations or storing any data. Furthermore, I also recommend prefixing the name of the type so is distinct from the SwiftUI one. This is not strictly necessary, but I’ve found that makes the compiler way happier as it helps distinguish the functions easily. It’s also a hint to the user of the function that there are some shenanigans going on.
So let’s convert that type to an enum instead:
public enum MyScrollDismissesKeyboardMode {\n case automatic\n case immediately\n case interactively\n case never\n}\nThis makes it so the usage side can use the same dot syntax and names as with the original function while using our custom types. But we still need to give SwiftUI its own types, so I always add a property to do the conversion.
// MyScrollDismissesKeyboardMode\n @available(iOS 16.0, *)\n var swiftUI: ScrollDismissesKeyboardMode {\n switch self {\n case .automatic: return .automatic\n case .immediately: return .immediately\n case .interactively: return .interactively\n case .never: return .never\n }\n }\nThis property is only available in the new OS since when we call it we will be in the correct version.
Now we can switch the function to use the new type.
@ViewBuilder func scrollDismissesKeyboard(\n _ mode: MyScrollDismissesKeyboardMode\n ) -> some View {\n if #available(iOS 16.0, *) {\n self\n .scrollDismissesKeyboard(mode.swiftUI)\n } else {\n self\n }\n }\nAnd that’s the function fully back ported. We take our custom parameter, and if we are in the new version, convert it to the SwiftUI one and call the real modifier. Otherwise, we just return the view unmodified.
With this, the usage side would look exactly as with the real code.
SomeView()\n .scrollDismissesKeyboard(.immediately)\nFor that to work you just need to make sure your function is in your module, or if it’s in a separate package (which I always recommend) you need to import it in your file.
This works because your code always takes precedence over system frameworks. This means the compiler will pick your custom function and types before SwiftUI’s.
Another very useful tip is to use an availability annotation to ensure the compiler will remind you to remove this code when your minimum target matches the one that introduced the modifier. For this, we can add an @available with the obsoleted parameter.
@available(iOS, obsoleted: 16.0, message: "SwiftUI.View.scrollDismissesKeyboard is available on iOS 16.")\nThis is very helpful and makes the compiler work for you.
Just like deciding what to do as a fallback based on tradeoffs, choosing which parameters and features to support is important too.
For example, if we want to port presentationDetents(_:) we will find out is a bit more complex. The custom detent needs some generic work that might not be trivial, so when you see that sort of complexity you can decide to just ignore it. Remember that this code is for you. It’s likely that you are not trying to make a full featured framework for the entire world, so if you don’t need some functionality right now, just skip it. By the time you need it, you will use the native solution already.
So in this case, you may decide to simplify the detents you offer:
public enum MyPresentationDetent: Hashable {\n case medium\n case large\n case fraction(_ fraction: CGFloat)\n case height(_ height: CGFloat)\n // no custom detent supported\n}\nThis technique is not only useful to back port functionality to older OSs but also to improve functionality and make it work the way you want. You can use the same technique, ignoring the version checks, and that will give you a way to offer more reusable parameters and options and to have a reusable place to include extra logic, all of that while keeping the same syntax as the system.
This is beneficial because it allows your code to be easily adjusted when Apple adds new options natively, saving you from having to completely refactor multiple views.
This technique is just another tool on your belt. It’s up to you to decide when is appropriate to use it, but I recommend you to think about it. There are plenty of times when we could use modern APIs with little problem while keeping compatibility with older systems.
Just have it in mind, analyze the tradeoffs and decide.
", "date_published" : "2023-10-19T22:00:00Z", "id" : "https://alejandromp.com/development/blog/backport-swiftui-modifiers", "summary" : "Every year SwiftUI improves and gets new modifiers that widen the capabilities of the framework. Sadly, as responsible developers, we can’t use any of that because our users take some time to update and, as opposed to the Android ecosystem where Jetpack Compose is just a library embedded in every app, we need to wait for our users to be at the required minimum OS version to enjoy those fancy new tools.", "tags" : [ "Swift", "SwiftUI" ], "title" : "Backport SwiftUI modifiers", "url" : "https://alejandromp.com/development/blog/backport-swiftui-modifiers" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "It’s been a while since the last time I thought about traits and mixins in Swift, but the WWDC23 presentations about macros brought a lot of memories from those times when I really lamented not having that functionality in the language. Thankfully, Swift 5.9 gives us a form or meta-programming that allows us to get some basic support for mixins.
It’s still not fully generic since macros don’t give you all the type information you need for that yet, but they are functional and usable via ad hoc macros.
But also I don’t think we have a big need for them anymore, the development landscape has changed a lot since those days.
Check out this video:
\nPrevious conversations about traits and mixins:
WWDC23 is over and as previous year I’m sharing my unedited notes from all the sessions I’ve watched.
This year has been quite entertaining as the main focus has been on the new platform, something that hasn’t taken too much brain power of mine. visionOS is very cool, but it still feels like a very narrow and futuristic device. For what I care, the software and the engineering, there are two parts: apps as we know them, and new spatial design. For the first one there is not much difficult things to learn since is all based on all the farmeworks we know and love. For the spatial design it requires bringing 3Dc ontent into apps, which is a different discipline that although I’ve dabbled with, it’s not in my priorities right now. The combination of that means all the visionOS talks have been a breeze to go trough, like watching a scifi show.
The rest of sessions have been on the usual topics and frameworks. In general I’ve found all of them quite straightforward, without anything new or revolutionary that would make by brain go boom. Most of this is thanks to Swift being open source, which removes the surprise factor of the things I’m interested in by a lot. I basically knew everything coming on that front already. So that leaves SwiftUI as the delightful surprise machine.
I’m not complaining, is good to have a year a bit more relaxed. Before WWDC started I already decided to take this year a bit calmed, for my own mental health. I could jump in the wagon of content generation but I prefer to enjoy it, treat it as entertainment and learn with it. It’s way more fun!
After long nights and early mornings, I’ve watched more than 90 sessions. That’s pretty much every single session that is not gaming, ML, web or business related 😂. It’s not that much time when you watch it an higher speed ⏭️ I surprised even myself, but with all the sessions being quite low in new content time flew by, it was very enjoyable!
From all of those the ones I’ve kept bookmarket are:
Even if this year the content was not super impactful for me, every single session and presenter is amazing. The quality is over the clouds. They all are interesting to watch and listen, and present the topics in a very entertaining and interesting manner. And I love how Apple, a huge coorporation, let’s every presenter add a bit of their own personality to the videos. It makes them so much approachable. My congratulations to all the ones involved in making this sessions so enjoyable!
This won’t include every detail in all sessions. The notes reflect things that have caught my attention and that I want to remember their existence for later. Details are best obtained by going to the documentation when needed knowledge is up to date.
With WidgetKit, you can surface your content in many places across the system. With App Intents, your app’s functionality is integrated into the system even more seamlessly. With TipKit, you can surface beautiful tips directly in your app. And with AirDrop, you can make it even more convenient for your users to share content with those nearby.
![\"\"](\"https://alejandromp.com/development/blog/wwdc23-notes/WWDC23xcodesummary.jpg\")
![\"\"](\"https://alejandromp.com/development/blog/wwdc23-notes/WWDC23visionOSstack.jpg\")
![\"WWDC23](\"https://alejandromp.com/development/blog/wwdc23-notes/WWDC23swiftuisummary.jpg\")
Views that show further detail of selected content.Is a right sidebar that adapts to a sheet on smaller sizes.
New presentationBackground to change the background of the sheets overlays, the overlay that covers the entire screen.presentationBackgroundInteraction let’s you enable the interaction of the content behind even when a sheet is up.presentationCornerRadius(_:)presentationContentInteraction(_:)presentationCompactAdaptation(_:)Some of these modifiers also work when Inspectors are presented as sheets.
Phases:
Keyframes:
UnitCurve and Spring contain the algorithms/curves that drive the change of values. You can use them directly to get a value at a specific point in time.
CustomAnimation protocol to write custom animation curves. Can impleemnt velocty and merge behaviour to mix with other animations that was triggered while another was running.
Transaction is now public. Is another implicit-data flow construct, a dictionary that is passed trough the view hierarchy on every update and discarded at the end. it’s used for animatable views to know if they should animate on this update. It’s what withAnimation does, and the animation modifier touches. Now you can add your own data to know if during a body update it was triggered programmatically or by the user for example.A new animation modifier with a closure let’s you apply the animation just to specific effects instead of inserting it in the view hierarchy. the other children views are not affected by this animation, unlike the normal animation modifier that injects the animation to all children.
macro, so we just need State ![\"\"](\"https://alejandromp.com/development/blog/wwdc23-notes/WWDC23swiftuipropertywrappers.jpg\")
te and Environment wrappers now.
scrollTransition to modify the rows when the enter the visible area.
scrollTargetBehaviour(.paging) for full screen paging decelerationscrollTargetBehaviour(.viewAligned) to decelerate targeting a view, to mark which views are targets use scrollTargetLayout for lazy stacks (important because not all views are created yet, but the stack knows and will tell the scroll) or scrollTarget for the individual views themselves.Can use custom behaviours with ScrollTargetBehaviour conformance.
safeAreaPadding modifier, so the scrollview still extends to the full screen but its views are padded (both your content and its scroll indicators).contentMargin modifier to specify padding only to the content or to the scroll indicators.
containerRelativeFrame to let the view grow based on the container size. And can use parameters to let multiple views share the space, making grid like layouts.
scrollPosition(id: gives a binding to scroll to that view.
It gets the content and a geometry proxy.
You can use a coordinate space outside of the view, and compute the distance of a point in the space to the view using the proxy, then use that distance to change the content with effects.
Picker with the palette style
Make sure IDs are fast to compute.Just pass to views what they need, otherwise they depend on more.ForEach should just have 1 view so it can match the ID with it. It eagerly gets all IDs, but lazy the views. If there are more views it needs to easily get them too which is bad.
You can specify the interaction for when a view is focused. (edit or activate)Default focus to specify which element should be focused by default.New onKeyPress modifier.Focus values to tell menu commands which view is in focus.Focus sections to let directional focus (like in tvOS) fall into a non-adjacent view that otherwise wouldn’t be elegible for focus.
![\"\"](\"https://alejandromp.com/development/blog/wwdc23-notes/WWDC23watchwidgetslayouts.jpg\")
![\"\"](\"https://alejandromp.com/development/blog/wwdc23-notes/WWDC23swiftdatasummary.jpg\")
CKSyncEngine.Between high level core data integration and low level operations.
Looks very interesting, specially with the rules system that will prompt the tips at the appropiate moment and a consistent UI.
![\"\"](\"https://alejandromp.com/development/blog/wwdc23-notes/WWDC23macroroles.jpg\")
![\"\"](\"https://alejandromp.com/development/blog/wwdc23-notes/WWDC23swiftbuild-incodeexpansion.jpg\")
![\"\"](\"https://alejandromp.com/development/blog/wwdc23-notes/WWDC23macroroleprotocols.jpg\")
![\"\"](\"https://alejandromp.com/development/blog/wwdc23-notes/WWDC23macronamespecifiers.jpg\")
Custom traits let you bridge with swiftui environmentStatus bar changes color automaticallyPage control with progress and timer.Menu paletteNew text selection style. Comes from free with system text views. Now can also be used in custom text views together with the loupe.New UITextItemTagAttributeName to tag ranges in a text so we can get interactions, ideal for “See More” in text! And it has new APIs to change the default menu behaviour when interacting with them.List and bullets supported in attributed string.
Improvements on app intentsApp shortcuts are now discoverable in Spotlight, design for it.![\"\"](\"https://alejandromp.com/development/blog/wwdc23-notes/WWDC23appintentsintegrations.jpg\")
New Monitor API based on actors.
One of the many things I love about working with The Composable Architecture is how it encourages the developer to focus on domain modeling. I think that properly designing the models or entities of a domain is one of the biggest contributors into good code, and the lack of it makes everything way harder than it should be. Thankfully Swift is a great language that allows us to express almost everything we need to in a very strict and concise way, another reason the language of your choice matters most than people pretends.
So the topic I will discuss here is not really specific to the TCA, but more about domain modeling and types. Let’s start by exposing the issue:
Let’s imagine we want to model the result of some side effect, like an API call, that can succeed and fail. We can easily do this with Swift’s Result type, but in this case we do not care about the success data at all, only about the failure. In other words, we want to know which specific error occurred, but if it succeeded we don’t want to know anything about the success data.
Of course if you have done any meaningful coding with TCA this will feel very familiar, and indeed is where I find this more often, with its other variations of I only care about success data and not the error, I don’t care about any of the two, etc… But let’s ignore that for now and see what the issue is and why is so important to model this correctly.
What? Math? Seriously? Yes! It’s actually the easiest way of realizing what you are doing when modeling a solution. Don’t fear, it’s very simple.
If you want to learn more about Algebraic Data Types I really recommend subsribing to Pointfree (get one month free with this link)
Let’s first think how many potential scenarios the most basic design gives us:
Result<Int, Error>\nWith this type, we have n possibilities for the integer in case of success, and m possibilities for the error in case of failure. (let’s assume Int is what the side effect responds with). These are n + m cases we would have to deal with, too many! Remember, we don’t care about the success data.
So if we don’t care about the success and only about the error, maybe we can ditch the Result type completely and just use the Error.
Error\nThat will give us m possibilities, but we are lacking a way to know if it succeeded. We want to know that it succeeded, but not about its specific data. But Swift already provides with a tool for it, Optional.
Optional<Error> // Error?\nNow we have m from the Error and 1 from the optional nil case, so m + 1. Exactly the amount of cases we wanted!
Simple right?
But let’s say we want to still use the Result type for consistency with the rest of the code. How can we use that type, which requires a Success and still keep the same m + 1? We need a type that only gives us 1 option, and again, we have one. Swift calls it Void or () (the empty tuple), called Unit in other languages. With that knowledge, let’s use Result again.
Result<Void, Error>\nThanks to Void we can use the Result type and still have 1 + m cases to deal with.
This may seem like a minor thing, after all, you could just use the original data (Int) and just ignore it on your code. But that’s a slippery slope that makes your code harder to reason about. When your future self comes back and reads the code, the types will explain the story of what is happening without having to read the code. The compiler will make you remember the decisions you took when you already forgot them. Such is the power of properly modeling domains with a proper type system.
This is all nice but we need to use this response in another type, in the case of the TCA we need to embed this in an Action enum, but it could be any other type you use to carry data around.
This is how it would look if we cared about the success data:
struct ApiResponse {\n let response: Result<Int, Error>\n}\nAll well so far. But let’s make this type more realistic and make it conform to Equatable, which is something we need most of the time.
struct ApiResponse: Equatable { // Type 'ApiResponse' does not conform to protocol 'Equatable'\nBoom! 💥 The compiler can’t synthesise the conformance because our Result type is not equatable. Int is obviously fine, the problem is the Error.
The reason for this is a rabbit whole we don’t have time to get into now, but there are multiple solutions for it. Thankfully PointFree has already provided one for the users of the TCA in the form of TaskResult (docs) so we can ignore this exact problem and move on to the one I want to discuss.
struct ApiResponse: Equatable {\n let response: TaskResult<Int>\n}\nNow the compiler is happy again. Keep in mind that even if we don’t see the Error type anymore, the failure case is still there case failure(Error) so we still have the data we care about.
But we are still using the awful Int, let’s switch back to use our lovely Void.
struct ApiResponse: Equatable { // Type 'ApiResponse' does not conform to protocol 'Equatable'\n let response: TaskResult<Void>\n}\n💥 Here we are again! Now it’s Void that is not Equatable and if you know a bit about Swift you know why.
Void is a non-nominal type, which in simple terms it means there is not a name you can use to refer to it in some language features. One such feature is protocol conformance, which allows types to adopt a set of behaviors defined by a protocol, in this case equatability. Because Void is not a named type, Swift does not inherently know whether it conforms to any given protocol. Although we might want to make Void conform to Equatable ourselves by defining an extension, we can’t do it because we cannot reference it by name! Therefore, we can’t retroactively make Void conform to any protocol. 😞
extension Void: Equatable {} // Non-nominal type 'Void' cannot be extended\nSo if we can’t use Void, maybe we can use the alternative of using an Optional?
Well, that brings us back the problem with Error that we solved with TaskResult so is not a solution.
struct ApiResponse: Equatable { // Type 'ApiResponse' does not conform to protocol 'Equatable'\n let response: Error?\n}\nMy favorite solution to this problem is just to make Void a nominal type. Of course you can’t make the existing one but you can just make your own. Remember how we described Void as the empty tuple ()? A tuple is an anonymous product type, but we can use a named product type instead.
struct EquatableVoid: Equatable {}\nOur EquatableVoid it has the same shape a Void, it only has 1 possible value which we can get by calling the initializer EquatableVoid(). Is not as nice as just () but such is the price we need to pay.
With this new type, we can change our response and finally have what we want:
struct ApiResponse: Equatable {\n let response: TaskResult<EquatableVoid>\n}\nThis gives us 1 + m cases, no more, no less. We have expressed exactly our domain.
We can use our types like so:
let ok = ApiResponse(response: TaskResult<EquatableVoid>.success(EquatableVoid()))\nlet ko = ApiResponse(response: TaskResult<EquatableVoid>.failure(Badabum.granBadabum))\nAnd work with them in a switch statement exactly like we wanted:
switch response {\ncase .success(let void):\n // not much you can do here, you only have 1 possible value that is always the same\ncase .failure(let error):\n // but here you have all errors so you can work with them as you please\n}\nThere are, of course, other solutions that have other tradeoffs, so as usual I give you the tools so you can take the decision on your own.
You could use the optional alternative by using a specific error type that was equatable: SpecificEquatableErrorForYourDomain?. That would work but then you need to reconcile your specific error type with Swift’s untyped errors. With time I’ve learned to embrace Swift’s error system and stop fighting it, so I don’t recommend this. Is a fix for this exact part of the code, but you will have to write patches in other parts to deal with any errors and default cases.
Another solution would be to use NSError, which is convertible to Error and is equatable. I tend to run away from it. I’m fine receiving it from Objective-C APIs but I want my Swift code to be Swift code. NSError loses the type safety at the usage side. You can’t cast it to a specific type but need to rely on strings and integers. It’s not a tradeoff I’m willing to make.
And I imagine there are other ways of solving this with different tradeoffs, but I’m not aware of one that gives me what I want in a better way :)
This technique is not something new that I only use for this case, in fact this is the third occurrence in my codebase of this solution.
In our project, we use the TCA to its fullest and I made a generic loading system that we are very happy with. The closure that lets you customize how to get the data receives a parameter that can be injected from other domains. Think of an ID that you need to fetch a user, for example. But not all screens need parameters, so you would want to define the generic type as Void, but again it needs to be equatable. In this case, I employ another trick that let developers avoid even constructing this type at all.
public typealias NoParameter = _NoParameter?\npublic struct _NoParameter: Equatable {}\nBy using NoParameter as the generic type, developers (in fact our library has this default cause supported) can just pass nil when constructing the domain and they don’t have to deal with the parameter in their implementation.
I should talk about our generic loading system because I think is pretty neat. Ping me if it’s something you would be interested in :)
Another place where this pattern occurred is in the API library I implemented, which uses Swift’s generic type system to make it very simple to define endpoints. In an endpoint, there is a generic parameter that defines the response model you want to decode, but of course, sometimes you don’t really want to decode anything. The same goes for the generic parameter that specifies which parameter to send to the API. For that, again, you would love to use Void but it’s not Decodable or Encodable so it won’t work.
public struct Ignore: Equatable, Codable {}\nMaybe I should think about making a SuperVoid that covers all the cases :)
Domain modeling matters, and having a language with a type system that supports us when designing, is crucial. Swift gets very far, but it still has some limitations with non-nominal types that thankfully can be solved by defining our own types to cover for these cases.
", "date_published" : "2023-03-08T23:00:00Z", "id" : "https://alejandromp.com/development/blog/non-nominal-types-workaround-for-domain-modeling", "summary" : "One of the many things I love about working with The Composable Architecture is how it encourages the developer to focus on domain modeling. I think that properly designing the models or entities of a domain is one of the biggest contributors into good code, and the lack of it makes everything way harder than it should be. Thankfully Swift is a great language that allows us to express almost everything we need to in a very strict and concise way, another reason the language of your choice matters most than people pretends.", "tags" : [ "Swift", "PointFree Composable Architecture", "Software Design and Architecture" ], "title" : "Non-nominal types workaround for domain modeling", "url" : "https://alejandromp.com/development/blog/non-nominal-types-workaround-for-domain-modeling" }, { "authors" : [ { "name" : "Alejandro M. P." } ], "content_html" : "Buckle up. This is an adventurer journal while exploring what’s the best way of exposing the new style of formatting APIs in Foundation. We will walk through the paths of the type system, including existential types, generics and type erasure; and discover the magical possibilities of the dependency system.
This idea came to mind after finding a clashing in styles of development. When I work on my side projects and I have to do things quickly, mostly for fun, I love the new formatting APIs, thePast.formatted(.relative(presentation: .numeric, unitsStyle: .abbreviated)). But then when working in a proper product, in a team, with a long-term vision, you need to use proper engineering techniques, which often involves doing dependency injection.
I use PointFree’s dependency library (as part of the TCA) which I’ve discussed previously (On the new Point-Free swift-dependencies library) but this applies to any other DI technique pretty much. Usually when you want to DI something that lets you format, the best way is to provide a function that takes the input value and gives you an output value, typically a String.
public struct DateFormatter {\n public let format: (_ date: Date) -> String\n}\nThen the live implementation of this dependency can use a DateFormatter or the new .formatted style. The advantage of having this API as a dependency is that it allows you to very easily switch the implementation for testing and previews.
static var testValue: DateFormatter = XCTUnimplemented("\\(Self.self).format")\nstatic var previewValue: DateFormatter = { _ in "Tue, Nov 29" }\nstatic var liveValue = { $0.formatted(...) }\nBeing able to just have a hard-coded value for previews or testing without having to deal with the formatters themselves is a tremendous benefit that can’t be underestimated.
But as nice as this is, I resented the usage side not being as nice and natural as using the Foundation fluent API.
formatDate(selectedDay.date)\nIt’s not bad, but I prefer the fluent API in this case. I just enjoy it a lot more when working on my side projects, so I started thinking how I could keep the joyfulness of the code but still adding the seriousness of DI.
To start, I had to learn more about how the newly fluent API worked. I explored it in the past but Apple’s documentation is not super clear in this area, but then I was pointed to Gosh Darn Format Style! which does a great job of explaining how the API works.
The key is understanding that behind these fancy fluent APIs there is one protocol: FormatStyle. All the dot syntax calls create types conforming to that protocol and fluently mutate them. In other words, you can hold an instance of the style that you want.
// wo this seems so complex!\n(2.5).formatted(.number.decimalSeparator(strategy: .always).precision(.integerLength(1)))\n\n// but is just really a mutation of structs\nlet numberStyle = FloatingPointFormatStyle<Double>.number\nlet withDecimalSeparator = numberStyle.decimalSeparator(strategy: .always)\nlet withPrecision = withDecimalSeparator.precision(.integerLength(1))\n(2.5).formatted(withPrecision)\nThis seems obvious, but I think this API has so many combinations and you get so overwhelmed with the auto-completion, that is sometimes hard to realise the simplicity of it. I think the eye-opening moment is when you actually understand that the API surface is not in the extension of the input type but in the fluent extensions of the concrete FormatStyle. The Date, Double, … types are not the ones with the complex API, they just have one method, the .formatted call. It’s in their specific formatter styles that the complexity resides.
What this also means is that you can easily create your predefined instances of styles in order to reuse them in your application. I think this is key because otherwise the risk of slightly doing different formats in different views is too big.
extension FormatStyle where Self == FloatingPointFormatStyle<Double> {\n public static var numberFancy: FloatingPointFormatStyle<Double> {\n Self.number.decimalSeparator(strategy: .always).precision(.integerLength(1))\n }\n}\n\n// Use numberFancy instead of the long chain from before\n(2.5).formatted(.numberFancy)\nWith this ability in our hands, let’s go back to defining how it would ideally work with dependency injection.
If we consider I would love to keep the fluent API and have DI the obvious usage looks like this:
@Dependency(\\.numberFancy) var style\nnumber.formatted(style)\nThe simple way of accomplishing this with the dependency system just involves declaring the dependency using the FloatingPointFormatStyle type.
extension DependencyValues {\n var numberFancy: FloatingPointFormatStyle<Double> {\n get { self[NumberFancyFormatterStyleKey.self] }\n set { self[NumberFancyFormatterStyleKey.self] = newValue }\n }\n}\n\nprivate enum NumberFancyFormatterStyleKey: DependencyKey {\n static let liveValue: FloatingPointFormatStyle<Double> = .number.decimalSeparator(strategy: .always).precision(.integerLength(1))\n}\nIf you have used the Dependency system, this should be pretty familiar. We just declare the DependencyKey and provide the property DependencyValues to get the KeyPath. The important part is how we can now declare the FloatingPointFormatStyle we want and that is injected into our code, while it lets us still use the nice fluent syntax.
And we are done, right? Nope!
Remember the advantage of using a function: we can easily provide test and preview values without having to deal with the formatters themselves. With the new setup we lost this ability, there is no way, to my knowledge, to mutate a style implementation like FloatingPointFormatStyle and force it to return a custom string.
The alternative I pursued was to create a custom format style, after all, FormatStyle is just a protocol. It may seem that each input type, like numbers or dates, is tied to a specific FormatStyle type, but that’s not true. It may be confusing because the types are nested and so it feels they are hardcoded, but in reality, the formatted function is generic.
// From Foundation extension BinaryFloatingPoint\nfunc formatted<S>(_ format: S) -> S.FormatOutput where Self == S.FormatInput, S : FormatStyle\nThis constrained function lets you pass any FormatStyle with a FormatInput associated type that it’s a BinaryFloatingPoint. This means that it accepts a FloatingPointFormatStyle but also a custom type with the correct associated types.
Let’s make a format style that always returns the same string:
struct HardcodedNumberFormatStyle: FormatStyle {\n typealias FormatInput = Double\n typealias FormatOutput = String\n \n func format(_ value: FormatInput) -> FormatOutput {\n return "hardcoded"\n }\n}\nAnd we can use this to format the Double from before:
number.formatted(HardcodedNumberFormatStyle())\nTo make it look nicer, we should provide an extension to allow dot syntax as shown above.
This is all good, but how do we stuff this in our dependency system?
private enum NumberFancyFormatterStyleKey: DependencyKey {\n\tstatic let liveValue: FloatingPointFormatStyle<Double> = ...\n static let testValue = HardcodedNumberFormatStyle()\nOf course, this doesn’t compile, the types of liveValue and testValue don’t match. But again, we don’t care about the specific types, just about the input and output types of the format style. So maybe if we use generics…
If we change the type to some FormatStyle the dependency is fine, but also useless. You can’t use the style because it’s not constrained, so the formatted function won’t accept it. The solution would be to specify the associated types like some FormatStyle but sadly, the FormatStyle protocol doesn’t offer primary associated types. So we can’t use generics at this level.
A solution that occurred to me is to create a wrapper type that dispatches to the correct formatter accordingly. But the question is how to decide the dispatch.
struct WrappedNumberFormatStyle: FormatStyle {\n func format(_ value: Double) -> String {\n return FloatingPointFormatStyle or HardcodedNumberFormatStyle\n }\n}\nA typical way I would do this is by passing the correct style at init time. After all, the dependency system makes the decision for us.
private enum NumberFancyFormatterStyleKey: DependencyKey {\n static let liveValue: WrappedNumberFormatStyle = .init(FloatingPointFormatStyle<Double>.number ...)\n static let testValue: WrappedNumberFormatStyle = .init(HardcodedNumberFormatStyle())\n}\nBut of course, this raises the question of how we store the style generically. Maybe we can try to make the type generic…
struct WrappedNumberFormatStyle<Wrapped: FormatStyle>: FormatStyle where Wrapped.FormatInput == Double, Wrapped.FormatOutput == String {\nBut even if the type itself compiles, we have solved nothing. Generics end up polluting the api surface and it means we are back at the same problem. Using a different Wrapped type results in a different WrappedNumberFormatStyle.
Another possibility is to keep the wrapped property type erased and enforce the correct types in the init, that’s a technique that works well when you want to erase some types.
struct WrappedNumberFormatStyle: FormatStyle {\n private let wrapped: any FormatStyle\n \n init<T: FormatStyle>(wrapped: T) where T.FormatInput == Self.FormatInput, T.FormatOutput == Self.FormatOutput {\n self.wrapped = wrapped\n }\nBut this doesn’t compile because the existential type itself doesn’t conform to Codable, Equatable and Hashable, all protocol requirements inherited from FormatStyle. This means we would need to type erase all the requirements of those protocols… and at that point I’m starting to lose interest.
But just for fun, let’s assume that we don’t care about those requirements right now and move on, hole driven development for the win. The next challenge is to make the format call compile.
func format(_ value: Double) -> String {\n return wrapped.format(value)\n}\nThe immediate problem is that since wrapped is an existential, the return type of the format call is not constrained, it returns Any. And since Any is not String it won’t compile. The fix here is easy: since we know the only way to create the wrapped property is going through the init that applies the constraints, we can assume the output type is a String, so a force cast should be safe.
func format(_ value: Double) -> String {\n return wrapped.format(value) as! String\n}\nBut now we encounter another problem: Member 'format' cannot be used on value of type 'any FormatStyle'; consider using a generic constraint instead. This error is a bit weirdly explained, but what is happening is that since wrapped is an existential, even though it has the format method defined, the input type of the format call can’t be known at compile time and thus the requirement of value: Double being equal to the input type of wrapped is not satisfied.
Here is where I got stuck. I’m able, thanks to the recent additions to opening existential, to create a generic function that opens the wrapped type. But I haven’t figured out a way to relate that with the input type. I was hoping the following worked…
private func _format<F: FormatStyle>(\n formatStyle: F,\n value: F.FormatInput\n) -> F.FormatOutput {\n formatStyle\n .format(value)\n}\n\nfunc format(_ value: Double) -> String {\n return _format(formatStyle: wrapped, value: value)\n}\n\n… but it can’t: Type 'any FormatStyle' cannot conform to 'FormatStyle'. Again, the error is a bit misleading because the issue is really with the second parameter. If the _format function just had 1 parameter formatStyle: F the compiler is able to open the existential at runtime and is all fine. But we can’t link the type of the second parameter F.FormatInput to another value and keep the relation with the first one.
I was confused by this for some time. I even read the proposal that introduced this functionality twice. But in the end, it makes sense. I’m passing a Double as the second parameter, but that has no relation with wrapped whatsoever. I wonder if there is some trick here that I’m not aware of.
The only way I know of making this compile is to add more force casts. And even though they should be safe since the init constraints the types of the wrapped instance, it feels too much trouble.
So I tried to come up with an alternative. The idea of passing the type from the outside is nice, especially because I would have loved to have a generic format style wrapper that could reduce boilerplate; but if that didn’t work, I wanted to try a less generic approach.
Let’s still keep the dispatch decision on the dependency system, but specify the types of the formatters we need. Keeping the types concrete would solve the problem we have. For this I decided to switch to an enum with associated types since it felt like the quickest solution.
enum WrappedNumberFormatStyle: FormatStyle {\n case foundation(FloatingPointFormatStyle<Double>)\n case hardcoded(String)\n case unimplemented\n \n func format(_ value: Double) -> String {\n switch self {\n case .foundation(let floatingPointFormatStyle):\n return floatingPointFormatStyle.format(value)\n case .hardcoded(let string):\n return string\n case .unimplemented:\n return XCTestDynamicOverlay.unimplemented()\n }\n }\n}\nThere are no generics in this enum. All types are concrete, so we don’t have any problems with the type system. We exchange a sort of dynamic dispatch with a static and manual dispatch instead. I also took the opportunity to remove the HardcodedNumberFormatStyle type since a String in the hardcoded does the same job, and also add the unimplemented functionality for tests.
With this, the dependency integration is quite simple:
private enum NumberFancyFormatterStyleKey: DependencyKey {\n static let liveValue: WrappedNumberFormatStyle = .foundation(FloatingPointFormatStyle<Double>.number.decimalSeparator(strategy: .always).precision(.integerLength(1)))\n static let testValue: WrappedNumberFormatStyle = .unimplemented\n static let previewValue: WrappedNumberFormatStyle = .hardcoded("hardcoded")\n}\nThis works!
Now, I admit that seeing case foundation(FloatingPointFormatStyle still makes me want to make it generic but we’ve been through that rabbit hole so there is no need to repeat it 😂
One of the big benefits of having the dependency system in place is that we can solve one of the annoying parts of formatters: dealing with the locale. It’s true that with the code above we can control the format style dependency itself, but if we wanted to still use the real one for testing, we would still have to deal with the locale. A very nice thing we can do is use the @Dependency ourselves in the implementation.
func format(_ value: Double) -> String {\n @Dependency(\\.locale) var locale\n\n switch self {\n case .foundation(let floatingPointFormatStyle):\n return floatingPointFormatStyle\n .locale(locale)\n .format(value)\nWith this minor change, we now have a formatter that automatically gets the locale, like the default format styles, but with the difference that we can control that dependency.
Seeing how we can access the dependencies internally, there is another trick that you can employ. Be ready for some magic 🧙♀️ .
The way that PointFree dependency system decides which value to provide is using a context value, that is itself part of the dependency system 🤯. This is very powerful because it means you can change the context yourself, or read it and leverage the internal logic of the library.
Thanks to this, we can actually have a type that magically changes.
struct MagicNumberFancyFormatStyle: FormatStyle {\n func format(_ value: Double) -> String {\n @Dependency(\\.context) var context\n @Dependency(\\.locale) var locale\n \n switch context {\n case .live:\n return FloatingPointFormatStyle<Double>.number.decimalSeparator(strategy: .always).precision(.integerLength(1))\n .locale(locale)\n .format(value)\n case .preview:\n return "hardcoded"\n case .test:\n return XCTestDynamicOverlay.unimplemented()\n }\n }\n}\nIn fact, you can use this trick and expose the format style as an extension, without going through DependencyValues at all! It means that (2.5).formatted(.numberFancy) would look exactly normal, like any other Apple API, but under the hood you made your code fully testable and controllable. This is a huge win in my opinion, and I’m really tempted to use this trick directly without having to deal with the @Dependency in the usage side.
Of course this might be too much magic. Analyze the tradeoffs and decide by yourself if it’s worth.
Here is where I stopped my exploration. It was fun, and I learned a bunch of things again. We still need to decide if these wrapped types are worth the effort or if we will just keep the function style as the dependency. But for my side project usages I’m very tempted to use the magic solution :)
As always, thanks for coming with me in this journey, I hope you learned like I did. And if you know of other tricks or solutions that could get me the requirements I want, don’t hesitate to tell me 😜
", "date_published" : "2023-01-19T23:00:00Z", "id" : "https://alejandromp.com/development/blog/an-exploration-of-formatstyle-as-a-dependency", "summary" : "Buckle up. This is an adventurer journal while exploring what’s the best way of exposing the new style of formatting APIs in Foundation. We will walk through the paths of the type system, including existential types, generics and type erasure; and discover the magical possibilities of the dependency system.", "tags" : [ "Swift" ], "title" : "An exploration of FormatStyle as a Dependency", "url" : "https://alejandromp.com/development/blog/an-exploration-of-formatstyle-as-a-dependency" } ], "language" : "en", "title" : "Development Blog - Alejandro M. P.", "version" : "https://jsonfeed.org/version/1.1" }