Module contracts
Binding for everyone writing a package in this repository. The product brief is CLAUDE.md at the repository root
(read §5–§9, §13, §16, §17, §19 for the package you own). ~/Desktop/Cluster/apple/CLAUDE.md (KHAELOR) is an unrelated
project that happens to sit in a parent folder: ignore it, except that this repository uses the same file-header convention.
Ground rules
- Swift 6 language mode, strict concurrency, macOS 15+, no third-party dependency. System frameworks only.
- Every source file starts with the header (see any file in
Packages/ORIXCore): product nameORIX OS Automation,File:(path from repo root),Description:,Author: Simon-Pierre Boucher,Contact: contact@spboucher.ai. - One Swift package per module under
Packages/<Name>/(ownPackage.swift,Sources/,Tests/), depending on../ORIXCoreby path and on nothing else unless listed below.swift-tools-version: 6.0,swiftLanguageModes: [.v6]. Packages/ORIXCoreis frozen. Read all ofPackages/ORIXCore/Sources/ORIXCore/*.swiftfirst; conform to those protocols and reuse those types. If a contract is genuinely missing, do not edit Core: add what you need in your own package and list it under "Contract requests" in your final report.- Real behaviour only. No stub that returns canned success, no
TODObody. What cannot work on this Mac returns a typed, honest error (ToolError.unsupported,.tccBlocked, …). Never fake a result. - Tests use Swift Testing (
import Testing). Unit tests plus real integration tests (real files in aTempDirectory, real subprocesses, real SQLite, real WKWebView…). Name suites so mocked vs integration is obvious. Tests must not need user interaction and must not touch anything outside temp directories. A test that needs a macOS privacy permission must detect its absence and record the skip reason withwithKnownIssue/early return + a printedSKIPPED(<reason>)line — never pass vacuously in silence. - Never run
pkill -for kill processes you did not start. Never print, log or write secrets. Nevergit commit(the lead commits). Stay inside your package directory (plus the files explicitly assigned to you). - Build and test with
swift build/swift testinside your package directory until both are clean (zero warnings in your code is the goal). Your final report must give: public API summary (types + signatures the app will call), test counts (unit / integration / skipped with reasons), known limitations, contract requests. - This Mac's system language is French: use
LC_ALL=Cwhen parsing tool output; do not rely on localized strings.
Packages and owners
| Package | Depends on | Content |
|---|---|---|
ORIXCore (frozen) |
— | contracts, JSON, schema, redaction, path resolution, ORIXTestingSupport |
ORIXSecurity |
Core | PolicyEngine, KeychainStore, AuditLog |
ORIXPersistence |
Core | SQLite ORIXStore |
ORIXProviderAdapters |
Core | Anthropic, OpenAI, OpenRouter clients |
ORIXToolRegistry |
Core | registry, ToolExecutor, ProcessRunner, filesystem/shell/git/http/documents/python/script/system-info tools |
ORIXAppleAutomation |
Core | AppleScript/JXA, Accessibility, screen, app control, clipboard, notifications tools + permission status |
ORIXBrowserAutomation |
Core | WKWebView browser tools |
ORIXScheduler |
Core | cron/DST math, triggers, file watchers, durable queue engine |
ORIXWorkflowEngine |
Core | workflow IR, YAML/JSON codec, validator, executor, graph projection |
ORIXAgentRuntime |
Core | agent loop (lead) |
Tool rules (every tool package)
- A tool is a
struct/final classconforming toORIXTool.requirements(for:context:)is pure: it validates semantics, canonicalises every path withPathResolver.canonical(_:relativeTo: context.workingDirectory)and returns the exactCapabilitylist + tier + a one-sentence human summary built from the arguments.executethen acts only on those canonical paths / hosts / bundle ids. - Tools never check policy and never ask for approval:
ToolExecutordoes, beforeexecute. Tools never readRedactoreither; the executor redacts. - Tier guide: reading = 0; creating/modifying files in place, moving to Trash, clipboard write, notifications = 1;
network sends, running scripts/arbitrary processes, app control/automation, GUI input, git commit to a repo = 2
(git commit is 1), git push = 2 with
.externalSend(channel: "git-push"); permanent deletion, force push, anything privileged = 3.sudo,rm -rf /-class commands, writing protected paths: unsupported, refused inrequirements. - Tools honour
Taskcancellation andcontext.timeoutSeconds; subprocesses go throughProcessRunneronly. - Output is a JSON object matching
manifest.outputSchema; large text is truncated withString.truncated(maxBytes:)andToolResult.truncated = true. SetoutputIsUntrusted/untrustedfor content read from files, web, apps, processes. - Dry run (
input.dryRun) whensupportsDryRun: returnToolResult.simulateddescribing exactly what would change. - Each package exposes
public enum <Package>Tools { public static func all(...) -> [any ORIXTool] }.
Canonical tool identifiers (do not rename)
filesystem.list search read write mkdir copy move metadata checksum compare trash delete archive unarchive waitForChangeshell.run(argv array, no shell) ·script(bash text, tier 2)git.status diff log branches commit createPatch pushhttp.requestdocuments.csvRead csvWrite jsonQuery pdfText pdfInfo renderPDF imageInfo imageConvert xlsxRead textStatspython.run envInfo·script.swift javascriptsystem.info processes diskUsage powerState networkState(ToolRegistry) ·apps frontmost windows launchApp quitApp(AppleAutomation)clipboard.read write·notifications.postapplescript.run dictionary·jxa.runaccessibility.status tree find press setValue focus typeText waitForscreen.capture ocr comparebrowser.open read fill click waitFor screenshot download close
Argument naming: path, source, destination, paths, content, pattern, recursive, overwrite, url,
bundleID, selector, script, args, cwd, timeoutSeconds, maxBytes. camelCase everywhere.
ToolExecutor pipeline (ORIXToolRegistry)
invoke(call, context) never throws and always returns a ToolResult with durationMs:
- Look up the tool (unknown →
failed/not_found). - Validate
call.argumentsagainstmanifest.inputSchema(→invalidInput, nothing runs). tool.requirements(...); any capability path withPathResolver.isProtected→denied+ auditpolicyViolation.- Capabilities under
context.artifactsDirectoryare implicitly granted; build anAccessRequest(arguments preview redacted withmanifest.redactedInputKeys) for the rest and callpolicy.evaluate. .deny→denied..needsApproval→ emitapprovalRequested, call theApprovalBroker;.unanswered/.deny→notApproved(failure codenot_approved); approval →policy.recordApproval.- Idempotency: if
call.idempotencyKeywas already executed successfully in this run, return the stored result without executing again. Non-idempotent tools are never auto-retried by the executor. - Concurrency gate per
manifest.concurrency; execute withmin(manifest.defaultTimeoutSeconds, context.maxToolSeconds)(or the call's owntimeoutSecondsargument when smaller); timeout → cancel task,timedOut. - Convert thrown
ToolErrorto itsToolResult; validate success output againstoutputSchema(violation →failed/output_invalid); redact output and summary withRedactor; truncate tomaxOutputBytes. policy.consume, audit (toolExecuted/toolFailed/toolDenied), emittoolRequested/toolFinishedrun events (data:callID,toolID,arguments(redacted),status,tier,durationMs,summary).
Emergency stop: ToolExecutor.cancelAll() cancels every in-flight call and ProcessRunner.killAll() terminates every
child process group.
ProcessRunner (ORIXToolRegistry)
posix_spawn/Process with: explicit argv (no shell), explicit environment (minimal allowlist: PATH, HOME,
LANG, TMPDIR + caller-supplied), explicit cwd, new process group, timeout, SIGTERM then SIGKILL of the whole
group on timeout/cancel, bounded stdout/stderr capture with streaming callback, exit code. Optional Seatbelt
confinement through /usr/bin/sandbox-exec -p <profile> generated from a Confinement: deny by default file
writes outside writeRoots (+ the process temp dir), deny network unless allowsNetwork, always deny reads of the
protected locations in PathResolver.isProtected. Confinement is ON for shell.script, python.run,
script.swift, script.javascript and skills; shell.run/git.* use it too unless the executable needs otherwise.