SPB Git

Repository Public License

overview.md 7.2 KB 93 lines markdown

1<!--2ORIX OS Automation3File: docs/architecture/overview.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Architecture89## Layers1011```12┌──────────────────────────── ORIX OS Automation.app (SwiftUI + AppKit) ────────────────────────────┐13│ Dashboard · Agent Chat · Workflow Studio · Code Studio · Runs · Agents · Skills · Scheduler ·      │14│ Permissions · Settings · Onboarding · Menu-bar item · Command palette · Approval sheets            │15└───────────────▲──────────────────────────────▲───────────────────────────────▲─────────────────────┘16                │ observes                      │ answers approvals             │ edits17        ┌───────┴────────┐              ┌───────┴────────┐              ┌───────┴─────────┐18        │ ORIXPersistence│◀─ events ────│   AppServices  │── documents ▶│ ORIXWorkflow    │19        │ SQLite (WAL)   │              │ (composition)  │              │ Engine (IR)     │20        └───────▲────────┘              └───┬───────┬────┘              └───────┬─────────┘21                │                           │       │                           │ tool + agent steps22                │                 ┌─────────▼──┐  ┌─▼──────────────┐            │23                │                 │ ORIXAgent  │  │ ORIXScheduler  │            │24                │                 │ Runtime    │  │ (queue, cron)  │            │25                │                 └─────┬──────┘  └───────┬────────┘            │26                │     model turns       │ tool calls      │ launches runs       │27        ┌───────┴────────┐        ┌─────▼────────────────────────────────────────▼─────┐28        │ ORIXProvider   │        │            ToolExecutor (ORIXToolRegistry)          │29        │ Adapters       │        │ schema → requirements → policy → approval → run →   │30        │ (URLSession)   │        │ redact → audit                                      │31        └────────────────┘        └──┬──────────────┬─────────────────┬────────────────┘32                                     │ PolicyEngine │ Tools           │ ProcessRunner33                                     │ (ORIXSecurity)│ files, shell,  │ process groups,34                                     │ grants, tiers │ git, http, docs│ timeouts, Seatbelt35                                     │ AuditLog      │ Apple, browser │36                                     └──────────────┴─────────────────┴────────────────37```3839## Separation that the code enforces4041| Concern | Lives in | Cannot do |42|---|---|---|43| Reasoning | `ORIXAgentRuntime` + provider adapters | Touch the machine. Its only door is `ToolInvoking`. |44| Permission | `ORIXSecurity.PolicyEngine` | Execute anything. It only answers allow / ask / deny. |45| Execution | `ORIXToolRegistry.ToolExecutor` + tools | Decide policy or approve itself. |46| Audit | `ORIXSecurity.AuditLog`, run events in the store | Be rewritten silently: the log is hash-chained. |47| UI | the app | Run a tool directly: it submits runs and answers approval requests. |4849`ORIXCore` holds the contracts between them (protocols and value types only), so each layer can be tested alone and50none can reach around another.5152## One model, three views5354A workflow is one `WorkflowDocument` (the IR). The code view edits its YAML/JSON text; the visual view applies edit55operations to the document; the agent view asks a model to produce or change the same document. Every view parses56or emits through `WorkflowCodec`, and `WorkflowValidator` judges the result. What a view cannot represent (comments57in YAML when the canvas rewrites the text) is reported before the rewrite.5859## Processes6061- **The app** owns the UI, answers approvals, and runs foreground work.62- **The background agent** is the same signed executable started by launchd with `--background-agent`63  (registered with `SMAppService`, opt-in). It runs the scheduler and headless workflows. It is the same binary on64  purpose: identical code signature means identical Keychain access without widening any access list, and no second65  executable to keep entitlement-minimal. It has no window and cannot answer approvals: anything not pre-granted66  parks as `WAITING_APPROVAL` and is surfaced by a notification and in the app.67- Both share one SQLite database (WAL). A lease row ensures a single active scheduler. Changes are announced with a68  Darwin notification so the other process refreshes.69- **Subprocesses** (scripts, git, python…) are children of whichever process runs the tool, each in its own process70  group, confined with a generated Seatbelt profile where applicable, killed as a group on timeout, cancel or71  emergency stop.7273## Data on disk7475`~/Library/Application Support/ORIX Automation/`: `orix.sqlite` (runs, events, workflows and versions, grants,76schedules, queue, agents, memory), `audit.jsonl` (hash-chained), `artifacts/<runID>/`, `skills/<id>/<version>/`,77`python-env/`. Provider keys and user secrets: login Keychain only (service `ai.spboucher.orix.automation`).7879## Decisions80811. **No third-party code.** YAML subset codec, SQLite wrapper, SSE parser, PDF rendering and the editor are written82   against system frameworks. Nothing to license, pin or audit beyond Apple's SDK.832. **SQLite, not SwiftData.** Two processes write the same store; explicit migrations, WAL, leases and84   corrupt-file quarantine need direct control.853. **Same-binary background agent** (see above) rather than a helper tool or an XPC service. There is no XPC surface86   to authenticate because there is no XPC: the processes cooperate through the database.874. **Seatbelt (`sandbox-exec`) for scripts.** Deprecated as a public tool but present and functional on macOS 27;88   it is the only supported way for a non-sandboxed parent to confine an arbitrary child. If Apple removes it,89   script tools must refuse to run unconfined unless the user explicitly accepts (tracked in the risk register).905. **OpenAI through Chat Completions.** One wire format shared with OpenRouter. The Responses API is future work.916. **Verification decides status.** A run is `SUCCEEDED` only from tool results and runtime-checked postconditions;92   the model's closing statement is stored as a claim.93
Files main
Menu

Theme