SPB Git

Repository Public License

module-contracts.md 9.0 KB 120 lines markdown

1<!--2ORIX OS Automation3File: docs/architecture/module-contracts.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Module contracts89Binding for everyone writing a package in this repository. The product brief is `CLAUDE.md` at the repository root10(read §5–§9, §13, §16, §17, §19 for the package you own). `~/Desktop/Cluster/apple/CLAUDE.md` (KHAELOR) is an unrelated11project that happens to sit in a parent folder: **ignore it**, except that this repository uses the same file-header convention.1213## Ground rules1415- Swift 6 language mode, strict concurrency, macOS 15+, **no third-party dependency**. System frameworks only.16- Every source file starts with the header (see any file in `Packages/ORIXCore`): product name `ORIX OS Automation`,17  `File:` (path from repo root), `Description:`, `Author: Simon-Pierre Boucher`, `Contact: contact@spboucher.ai`.18- One Swift package per module under `Packages/<Name>/` (own `Package.swift`, `Sources/`, `Tests/`), depending on19  `../ORIXCore` by path and on nothing else unless listed below. `swift-tools-version: 6.0`, `swiftLanguageModes: [.v6]`.20- **`Packages/ORIXCore` is frozen.** Read all of `Packages/ORIXCore/Sources/ORIXCore/*.swift` first; conform to those21  protocols and reuse those types. If a contract is genuinely missing, do not edit Core: add what you need in your own22  package and list it under "Contract requests" in your final report.23- Real behaviour only. No stub that returns canned success, no `TODO` body. What cannot work on this Mac returns a typed,24  honest error (`ToolError.unsupported`, `.tccBlocked`, …). Never fake a result.25- Tests use Swift Testing (`import Testing`). Unit tests plus **real integration tests** (real files in a26  `TempDirectory`, real subprocesses, real SQLite, real WKWebView…). Name suites so mocked vs integration is obvious.27  Tests must not need user interaction and must not touch anything outside temp directories. A test that needs a macOS28  privacy permission must detect its absence and record the skip reason with `withKnownIssue`/early return + a printed29  `SKIPPED(<reason>)` line — never pass vacuously in silence.30- Never run `pkill -f` or kill processes you did not start. Never print, log or write secrets. Never `git commit`31  (the lead commits). Stay inside your package directory (plus the files explicitly assigned to you).32- Build and test with `swift build` / `swift test` **inside your package directory** until both are clean (zero33  warnings in your code is the goal). Your final report must give: public API summary (types + signatures the app34  will call), test counts (unit / integration / skipped with reasons), known limitations, contract requests.35- This Mac's system language is French: use `LC_ALL=C` when parsing tool output; do not rely on localized strings.3637## Packages and owners3839| Package | Depends on | Content |40|---|---|---|41| `ORIXCore` (frozen) | — | contracts, JSON, schema, redaction, path resolution, `ORIXTestingSupport` |42| `ORIXSecurity` | Core | `PolicyEngine`, `KeychainStore`, `AuditLog` |43| `ORIXPersistence` | Core | SQLite `ORIXStore` |44| `ORIXProviderAdapters` | Core | Anthropic, OpenAI, OpenRouter clients |45| `ORIXToolRegistry` | Core | registry, `ToolExecutor`, `ProcessRunner`, filesystem/shell/git/http/documents/python/script/system-info tools |46| `ORIXAppleAutomation` | Core | AppleScript/JXA, Accessibility, screen, app control, clipboard, notifications tools + permission status |47| `ORIXBrowserAutomation` | Core | WKWebView browser tools |48| `ORIXScheduler` | Core | cron/DST math, triggers, file watchers, durable queue engine |49| `ORIXWorkflowEngine` | Core | workflow IR, YAML/JSON codec, validator, executor, graph projection |50| `ORIXAgentRuntime` | Core | agent loop (lead) |5152## Tool rules (every tool package)5354- A tool is a `struct`/`final class` conforming to `ORIXTool`. `requirements(for:context:)` is pure: it validates55  semantics, canonicalises every path with `PathResolver.canonical(_:relativeTo: context.workingDirectory)` and returns56  the exact `Capability` list + tier + a one-sentence human summary built from the arguments. `execute` then acts **only57  on those canonical paths / hosts / bundle ids**.58- Tools never check policy and never ask for approval: `ToolExecutor` does, before `execute`. Tools never read59  `Redactor` either; the executor redacts.60- Tier guide: reading = 0; creating/modifying files in place, moving to Trash, clipboard write, notifications = 1;61  network sends, running scripts/arbitrary processes, app control/automation, GUI input, git commit to a repo = 262  (git commit is 1), git push = 2 with `.externalSend(channel: "git-push")`; permanent deletion, force push, anything63  privileged = 3. `sudo`, `rm -rf /`-class commands, writing protected paths: unsupported, refused in `requirements`.64- Tools honour `Task` cancellation and `context.timeoutSeconds`; subprocesses go through `ProcessRunner` only.65- Output is a JSON object matching `manifest.outputSchema`; large text is truncated with `String.truncated(maxBytes:)`66  and `ToolResult.truncated = true`. Set `outputIsUntrusted`/`untrusted` for content read from files, web, apps, processes.67- Dry run (`input.dryRun`) when `supportsDryRun`: return `ToolResult.simulated` describing exactly what would change.68- Each package exposes `public enum <Package>Tools { public static func all(...) -> [any ORIXTool] }`.6970### Canonical tool identifiers (do not rename)7172- `filesystem.` `list search read write mkdir copy move metadata checksum compare trash delete archive unarchive waitForChange`73- `shell.` `run` (argv array, no shell) · `script` (bash text, tier 2)74- `git.` `status diff log branches commit createPatch push`75- `http.` `request`76- `documents.` `csvRead csvWrite jsonQuery pdfText pdfInfo renderPDF imageInfo imageConvert xlsxRead textStats`77- `python.` `run envInfo` · `script.` `swift javascript`78- `system.` `info processes diskUsage powerState networkState` (ToolRegistry) · `apps frontmost windows launchApp quitApp` (AppleAutomation)79- `clipboard.` `read write` · `notifications.` `post`80- `applescript.` `run dictionary` · `jxa.` `run`81- `accessibility.` `status tree find press setValue focus typeText waitFor`82- `screen.` `capture ocr compare`83- `browser.` `open read fill click waitFor screenshot download close`8485Argument naming: `path`, `source`, `destination`, `paths`, `content`, `pattern`, `recursive`, `overwrite`, `url`,86`bundleID`, `selector`, `script`, `args`, `cwd`, `timeoutSeconds`, `maxBytes`. camelCase everywhere.8788## ToolExecutor pipeline (ORIXToolRegistry)8990`invoke(call, context)` never throws and always returns a `ToolResult` with `durationMs`:91921. Look up the tool (unknown → `failed/not_found`).932. Validate `call.arguments` against `manifest.inputSchema` (→ `invalidInput`, nothing runs).943. `tool.requirements(...)`; any capability path with `PathResolver.isProtected` → `denied` + audit `policyViolation`.954. Capabilities under `context.artifactsDirectory` are implicitly granted; build an `AccessRequest` (arguments preview96   redacted with `manifest.redactedInputKeys`) for the rest and call `policy.evaluate`.975. `.deny` → `denied`. `.needsApproval` → emit `approvalRequested`, call the `ApprovalBroker`; `.unanswered`/`.deny` →98   `notApproved` (failure code `not_approved`); approval → `policy.recordApproval`.996. Idempotency: if `call.idempotencyKey` was already executed successfully in this run, return the stored result100   without executing again. Non-idempotent tools are never auto-retried by the executor.1017. Concurrency gate per `manifest.concurrency`; execute with `min(manifest.defaultTimeoutSeconds, context.maxToolSeconds)`102   (or the call's own `timeoutSeconds` argument when smaller); timeout → cancel task, `timedOut`.1038. Convert thrown `ToolError` to its `ToolResult`; validate success output against `outputSchema` (violation →104   `failed/output_invalid`); redact output and summary with `Redactor`; truncate to `maxOutputBytes`.1059. `policy.consume`, audit (`toolExecuted`/`toolFailed`/`toolDenied`), emit `toolRequested`/`toolFinished` run events106   (`data`: `callID`, `toolID`, `arguments` (redacted), `status`, `tier`, `durationMs`, `summary`).107108Emergency stop: `ToolExecutor.cancelAll()` cancels every in-flight call and `ProcessRunner.killAll()` terminates every109child process group.110111## ProcessRunner (ORIXToolRegistry)112113`posix_spawn`/`Process` with: explicit argv (no shell), explicit environment (minimal allowlist: `PATH`, `HOME`,114`LANG`, `TMPDIR` + caller-supplied), explicit cwd, new process group, timeout, SIGTERM then SIGKILL of the whole115group on timeout/cancel, bounded stdout/stderr capture with streaming callback, exit code. Optional **Seatbelt116confinement** through `/usr/bin/sandbox-exec -p <profile>` generated from a `Confinement`: deny by default file117writes outside `writeRoots` (+ the process temp dir), deny network unless `allowsNetwork`, always deny reads of the118protected locations in `PathResolver.isProtected`. Confinement is ON for `shell.script`, `python.run`,119`script.swift`, `script.javascript` and skills; `shell.run`/`git.*` use it too unless the executable needs otherwise.120
Files main
Menu

Theme