Repository Public License
1<!--2ORIX OS Automation3File: docs/api/tools.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Tool reference89Generated by `orixctl tools --markdown` from the registered tool manifests (77 tools). Do not edit by hand.1011## accessibility1213### `accessibility.find`1415Finds interface elements of a running application by role, title, identifier or value and returns their stable paths for the action tools.1617- side effect: read18- default tier: 019- timeout: 60 s20- idempotent21- output is untrusted data22- macOS permission: accessibility2324| Argument | Type | Required | Description |25|---|---|---|---|26| `bundleID` | string | yes | Application bundle identifier, for example com.apple.finder. |27| `identifier` | string | | Exact accessibility identifier. |28| `includeMenuBar` | boolean | | Search the menu bar too (default false). |29| `maxDepth` | integer | | Search depth (default 30). |30| `maxResults` | integer | | Maximum matches returned (default 20). |31| `role` | string | | Accessibility role or subrole, for example AXButton, AXTextField, AXMenuItem. |32| `title` | string | | Case-insensitive substring of the element's title or description. |33| `value` | string | | Case-insensitive substring of the element's value (never matches secure fields). |3435Output fields: `matches`, `searched`, `truncated`3637### `accessibility.focus`3839Brings a running application to the front and gives keyboard focus to one of its elements, then verifies both. Call before accessibility.typeText.4041- side effect: write42- default tier: 243- timeout: 15 s44- idempotent45- output is untrusted data46- macOS permission: accessibility4748| Argument | Type | Required | Description |49|---|---|---|---|50| `activate` | boolean | | Bring the application to the front first (default true). |51| `bundleID` | string | yes | Application bundle identifier, for example com.apple.finder. |52| `element` | string | yes | Element path returned by accessibility.tree or accessibility.find, for example AXApplication/AXWindow[0]/AXButton[2]. |53| `expectedTitle` | string | | Optional title or description the element must still have; the action is refused if it changed. |5455Output fields: `element`, `focused`, `frontmost`5657### `accessibility.press`5859Presses a button, menu item or other pressable element of a running application through the Accessibility API (no pointer movement). The element is re-resolved from its path right before the action.6061- side effect: write62- default tier: 263- timeout: 15 s64- dry run: yes65- output is untrusted data66- macOS permission: accessibility6768| Argument | Type | Required | Description |69|---|---|---|---|70| `bundleID` | string | yes | Application bundle identifier, for example com.apple.finder. |71| `element` | string | yes | Element path returned by accessibility.tree or accessibility.find, for example AXApplication/AXWindow[0]/AXButton[2]. |72| `expectedTitle` | string | | Optional title or description the element must still have; the action is refused if it changed. |7374Output fields: `element`, `pressed`7576### `accessibility.setValue`7778Sets the value of a text field, checkbox, slider or similar element of a running application, then reads it back. Secure text fields are refused.7980- side effect: write81- default tier: 282- timeout: 15 s83- dry run: yes84- output is untrusted data85- macOS permission: accessibility8687| Argument | Type | Required | Description |88|---|---|---|---|89| `bundleID` | string | yes | Application bundle identifier, for example com.apple.finder. |90| `element` | string | yes | Element path returned by accessibility.tree or accessibility.find, for example AXApplication/AXWindow[0]/AXButton[2]. |91| `expectedTitle` | string | | Optional title or description the element must still have; the action is refused if it changed. |92| `value` | string or number or boolean | yes | New value. |9394Output fields: `element`, `set`, `verified`9596### `accessibility.status`9798Reports whether this app is trusted for Accessibility control and how the user can enable it. Never prompts.99100- side effect: read101- default tier: 0102- timeout: 5 s103- idempotent104105Output fields: `howToEnable`, `settingsURL`, `trusted`106107### `accessibility.tree`108109Lists the interface elements of a running application (role, title, value, enabled, frame, stable path). Values of secure text fields are replaced by «secure».110111- side effect: read112- default tier: 0113- timeout: 60 s114- idempotent115- output is untrusted data116- macOS permission: accessibility117118| Argument | Type | Required | Description |119|---|---|---|---|120| `bundleID` | string | yes | Application bundle identifier, for example com.apple.finder. |121| `element` | string | | Optional path of the element to start from (default: the application). |122| `includeMenuBar` | boolean | | Include the menu bar (default false). |123| `maxDepth` | integer | | How deep to go below the start element (default 6). |124| `maxNodes` | integer | | Maximum elements returned (default 300). |125126Output fields: `application`, `nodes`, `truncated`127128### `accessibility.typeText`129130Types text as keyboard events into one element of the frontmost application. Refused unless that application is in front and that element has keyboard focus (checked again before every chunk), and always refused for secure text fields.131132- side effect: write133- default tier: 2134- timeout: 60 s135- dry run: yes136- output is untrusted data137- macOS permission: accessibility138139| Argument | Type | Required | Description |140|---|---|---|---|141| `bundleID` | string | yes | Application bundle identifier, for example com.apple.finder. |142| `element` | string | yes | Element path returned by accessibility.tree or accessibility.find, for example AXApplication/AXWindow[0]/AXButton[2]. |143| `expectedTitle` | string | | Optional title or description the element must still have; the action is refused if it changed. |144| `text` | string | yes | Text to type. Newlines press Return, tabs press Tab. |145146Output fields: `element`, `typedCharacters`147148### `accessibility.waitFor`149150Polls a running application's interface until an element exists, disappears, becomes enabled or focused, or shows a given value. Use it to confirm the effect of an action instead of sleeping.151152- side effect: read153- default tier: 0154- timeout: 120 s155- idempotent156- output is untrusted data157- macOS permission: accessibility158159| Argument | Type | Required | Description |160|---|---|---|---|161| `bundleID` | string | yes | Application bundle identifier, for example com.apple.finder. |162| `condition` | string | | What to wait for (default exists). |163| `element` | string | | Element path to watch, as an alternative to the role/title/identifier/value filters. |164| `expected` | string | | Expected value for valueEquals / valueContains. |165| `identifier` | string | | Exact accessibility identifier. |166| `pollIntervalMs` | integer | | Polling interval (default 200). |167| `role` | string | | Accessibility role or subrole, for example AXButton, AXTextField, AXMenuItem. |168| `timeoutSeconds` | number | | How long to wait (default 10). |169| `title` | string | | Case-insensitive substring of the element's title or description. |170| `value` | string | | Case-insensitive substring of the element's value (never matches secure fields). |171172Output fields: `condition`, `elapsedMs`, `satisfied`173174## applescript175176### `applescript.dictionary`177178Summarises an application's AppleScript/JXA scripting dictionary (suites, commands with parameters, classes with properties). Reports unsupported when the application is not scriptable.179180- side effect: read181- default tier: 0182- timeout: 30 s183- idempotent184- output is untrusted data185186| Argument | Type | Required | Description |187|---|---|---|---|188| `bundleID` | string | | Application bundle identifier, for example com.apple.finder. |189| `maxItems` | integer | | Maximum commands and classes returned per suite (default 60). |190| `path` | string | | Path of the application bundle, as an alternative to bundleID. |191192Output fields: `application`, `classCount`, `commandCount`, `path`, `suites`193194### `applescript.run`195196Runs AppleScript source out of process and returns its result. Every application the script addresses must be listed in targets (bundle identifiers); a script with no target only computes. Shell, Objective-C bridge and file access from the script need the bash runtime grant.197198- side effect: external199- default tier: 2200- timeout: 120 s201- dry run: yes202- output is untrusted data203- macOS permission: appleEvents204205| Argument | Type | Required | Description |206|---|---|---|---|207| `script` | string | yes | The AppleScript source text. |208| `targets` | array | | Bundle identifiers of every application the script talks to. Empty for pure computation. |209| `timeoutSeconds` | number | | Maximum run time in seconds (default 30). |210211Output fields: `language`, `parsed`, `result`, `stderr`, `targets`, `value`212213### `jxa.run`214215Runs JavaScript for Automation source out of process and returns its result. Every application the script addresses must be listed in targets (bundle identifiers); a script with no target only computes. Shell, Objective-C bridge and file access from the script need the bash runtime grant.216217- side effect: external218- default tier: 2219- timeout: 120 s220- dry run: yes221- output is untrusted data222- macOS permission: appleEvents223224| Argument | Type | Required | Description |225|---|---|---|---|226| `script` | string | yes | The JavaScript for Automation source text. |227| `targets` | array | | Bundle identifiers of every application the script talks to. Empty for pure computation. |228| `timeoutSeconds` | number | | Maximum run time in seconds (default 30). |229230Output fields: `language`, `parsed`, `result`, `stderr`, `targets`, `value`231232## browser233234### `browser.click`235236Click an element of the open page by CSS selector, after checking that it exists, is visible and is enabled. Waits for any navigation that follows and reports it. A navigation to a host the run was not granted is blocked.237238- side effect: external239- default tier: 2240- timeout: 60 s241- output is untrusted data242243| Argument | Type | Required | Description |244|---|---|---|---|245| `selector` | string | yes | CSS selector of the element, as returned by browser.read. |246| `timeoutSeconds` | number | | Give up waiting for a navigation after this many seconds. |247248Output fields: `clicked`, `dialogs`, `navigated`, `selector`, `status`, `title`, `url`249250### `browser.close`251252Close the ORIX browser session of this run and discard its cookies and page state.253254- side effect: write255- default tier: 0256- timeout: 10 s257- idempotent258259Output fields: `closed`260261### `browser.download`262263Download a file with the ORIX browser's session (its cookies apply) into the run's artifacts folder or a given path, with a size cap. Returns the path, size and SHA-256. Pages never start downloads on their own.264265- side effect: external266- default tier: 2267- timeout: 600 s268- output is untrusted data269270| Argument | Type | Required | Description |271|---|---|---|---|272| `maxBytes` | integer | | Refuse anything larger. Default 52428800 (50 MB). |273| `overwrite` | boolean | | Replace an existing file. Default false. |274| `path` | string | | Where to save it. Default: downloads/<file name> in the run's artifacts folder. |275| `timeoutSeconds` | number | | Give up after this many seconds. |276| `url` | string | yes | Absolute https URL of the file. |277278Output fields: `bytes`, `mimeType`, `path`, `sha256`, `status`, `suggestedFilename`, `url`279280### `browser.fill`281282Set the value of a form control on the open page (text field, textarea, select by option value or label, checkbox or radio) and dispatch input/change events. Password and payment-card fields only accept secretRef, the name of a stored secret, so the value never passes through a model.283284- side effect: external285- default tier: 2286- timeout: 20 s287288| Argument | Type | Required | Description |289|---|---|---|---|290| `checked` | boolean | | For a checkbox or radio button: the state to set. |291| `secretRef` | string | | Reference name of a stored secret to enter instead of a value. |292| `selector` | string | yes | CSS selector of the field, as returned by browser.read. |293| `value` | string | | Text to enter, or the option to select. |294295Output fields: `filled`, `secure`, `selector`, `tag`, `type`, `valueLength`296297### `browser.open`298299Open a URL in the ORIX browser (a private WebKit view with no access to Safari's cookies) and wait for the page to load. Returns the final URL, HTTP status and title. Only https, or http on this Mac's loopback.300301- side effect: external302- default tier: 1303- timeout: 60 s304- output is untrusted data305306| Argument | Type | Required | Description |307|---|---|---|---|308| `timeoutSeconds` | number | | Give up after this many seconds. |309| `url` | string | yes | Absolute https URL. |310311Output fields: `dialogs`, `redirected`, `status`, `title`, `url`312313### `browser.read`314315Read the page currently open in the ORIX browser as structured data: title, URL, visible text, headings, links, forms with their fields, buttons and tables. Every interactive element comes with a CSS selector that browser.fill, browser.click and browser.waitFor accept. Password and payment-card values are never returned.316317- side effect: read318- default tier: 0319- timeout: 20 s320- idempotent321- output is untrusted data322323| Argument | Type | Required | Description |324|---|---|---|---|325| `maxBytes` | integer | | Upper bound for the visible text, in bytes. |326| `maxItems` | integer | | Upper bound for each list (links, fields, buttons…). |327328Output fields: `buttons`, `dialogs`, `fields`, `forms`, `headings`, `links`, `tables`, `text`, `title`, `truncated`, `url`329330### `browser.screenshot`331332Save a PNG picture of the visible part of the open page. Without a path the file goes to the run's artifacts folder.333334- side effect: write335- default tier: 1336- timeout: 30 s337- output is untrusted data338339| Argument | Type | Required | Description |340|---|---|---|---|341| `overwrite` | boolean | | Replace an existing file. Default false. |342| `path` | string | | Where to save the PNG. Default: the run's artifacts folder. |343344Output fields: `bytes`, `height`, `path`, `sha256`, `url`, `width`345346### `browser.waitFor`347348Wait until the open page reaches a state: an element matching a selector is present, visible or absent, the page text contains a string, and/or the URL matches a regular expression. Returns as soon as all given conditions hold; fails with a timeout otherwise.349350- side effect: read351- default tier: 0352- timeout: 120 s353- idempotent354- output is untrusted data355356| Argument | Type | Required | Description |357|---|---|---|---|358| `selector` | string | | CSS selector to watch. |359| `state` | string | | What the selector must be. |360| `text` | string | | Text the page must contain. |361| `timeoutSeconds` | number | | How long to wait. Default 10. |362| `urlMatches` | string | | Regular expression the page URL must match. |363364Output fields: `dialogs`, `elapsedMs`, `matched`, `title`, `url`365366## documents367368### `documents.csvRead`369370Parses a CSV file (RFC 4180 quoting, delimiter and header detected unless stated) and returns the columns and a bounded window of rows.371372- side effect: read373- default tier: 0374- timeout: 120 s375- idempotent376- output is untrusted data377378| Argument | Type | Required | Description |379|---|---|---|---|380| `asObjects` | boolean | | Return each row as an object keyed by column name. |381| `delimiter` | string | | One of , ; \| or tab. Detected when absent. |382| `header` | string | | Whether the first row is a header (default auto). |383| `limit` | integer | | Rows returned (default 500). |384| `offset` | integer | | Data rows to skip. |385| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |386387Output fields: `columns`, `delimiter`, `hasHeader`, `rowCount`, `rows`, `totalRows`, `truncated`388389### `documents.csvWrite`390391Writes rows (arrays, or objects with columns) to a CSV file with RFC 4180 quoting. Refuses to replace an existing file unless overwrite is true (a backup is kept).392393- side effect: write394- default tier: 1395- timeout: 30 s396- dry run: yes397398| Argument | Type | Required | Description |399|---|---|---|---|400| `columns` | array | | Header row; required order for object rows. |401| `delimiter` | string | | |402| `overwrite` | boolean | | |403| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |404| `rows` | array | yes | Arrays of cells, or objects keyed by column. |405406Output fields: `bytes`, `path`, `rows`407408### `documents.imageConvert`409410Converts one image (source → destination file) or a batch (paths → destination folder) to png, jpeg, heic, tiff, gif or bmp, optionally scaled down to a maximum dimension. Sources are never modified and existing files are not replaced unless overwrite is true.411412- side effect: write413- default tier: 1414- timeout: 600 s415- dry run: yes416417| Argument | Type | Required | Description |418|---|---|---|---|419| `destination` | string | yes | Output file (single) or output folder (batch). |420| `format` | string | | Required for a batch; inferred from the destination extension otherwise. |421| `maxDimension` | integer | | Longest side in pixels; images are only ever scaled down. |422| `overwrite` | boolean | | |423| `paths` | array | | Images to convert as a batch. |424| `quality` | number | | Lossy formats only (default 0.85). |425| `source` | string | | Single image to convert. |426427Output fields: `converted`, `count`428429### `documents.imageInfo`430431Returns the format, pixel size, resolution, colour model, alpha, orientation and frame count of an image file.432433- side effect: read434- default tier: 0435- timeout: 30 s436- idempotent437- output is untrusted data438439| Argument | Type | Required | Description |440|---|---|---|---|441| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |442443Output fields: `bytes`, `format`, `height`, `width`444445### `documents.jsonQuery`446447Reads a JSON file and returns the value at a path such as items[0].name, items[*].id or items[?price>10].name (operators == != > >= < <= ~=). An empty query returns the document outline.448449- side effect: read450- default tier: 0451- timeout: 30 s452- idempotent453- output is untrusted data454455| Argument | Type | Required | Description |456|---|---|---|---|457| `limit` | integer | | Maximum values returned for wildcard/filter queries (default 200). |458| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |459| `query` | string | | Path expression; empty for an outline of the top level. |460461Output fields: `count`, `found`, `result`462463### `documents.pdfInfo`464465Returns the page count, page size, encryption state and document properties (title, author, dates) of a PDF.466467- side effect: read468- default tier: 0469- timeout: 30 s470- idempotent471- output is untrusted data472473| Argument | Type | Required | Description |474|---|---|---|---|475| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |476477Output fields: `bytes`, `encrypted`, `locked`, `pageCount`478479### `documents.pdfText`480481Extracts the text layer of a PDF, page by page, for a page range. Scanned PDFs without a text layer return empty pages (hasText false).482483- side effect: read484- default tier: 0485- timeout: 180 s486- idempotent487- output is untrusted data488489| Argument | Type | Required | Description |490|---|---|---|---|491| `firstPage` | integer | | 1-based (default 1). |492| `lastPage` | integer | | Inclusive (default: last). |493| `maxBytes` | integer | | Total text bound (default 200000). |494| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |495496Output fields: `hasText`, `pageCount`, `pages`, `truncated`497498### `documents.renderPDF`499500Renders Markdown-like text into a paginated PDF: # headings, paragraphs with **bold** *italic* `code`, bullet and numbered lists, | tables |, ``` code blocks, --- rules,  images and page numbers.501502- side effect: write503- default tier: 1504- timeout: 180 s505- dry run: yes506507| Argument | Type | Required | Description |508|---|---|---|---|509| `author` | string | | |510| `content` | string | yes | Markdown-like source. |511| `destination` | string | yes | Path of the .pdf to create. |512| `fontSize` | integer | | Body size in points (default 11). |513| `overwrite` | boolean | | |514| `pageSize` | string | | letter (default) or a4. |515| `title` | string | | Document title (also printed as the first heading). |516517Output fields: `bytes`, `pages`, `path`518519### `documents.textStats`520521Counts lines, words, characters and bytes of a text file (or of given text) and lists its most frequent terms.522523- side effect: read524- default tier: 0525- timeout: 30 s526- idempotent527- output is untrusted data528529| Argument | Type | Required | Description |530|---|---|---|---|531| `content` | string | | Text to analyse instead of a file. |532| `minTermLength` | integer | | |533| `path` | string | | Absolute path, ~/ path, or path relative to the working directory. |534| `topTerms` | integer | | How many frequent terms (default 10). |535536Output fields: `bytes`, `characters`, `lines`, `topTerms`, `words`537538### `documents.xlsxRead`539540Reads the cell values of one sheet of an .xlsx workbook (shared strings, numbers, booleans, inline strings, cached formula results). Dates come back as serial numbers; legacy .xls and encrypted workbooks are unsupported.541542- side effect: read543- default tier: 0544- timeout: 120 s545- idempotent546- output is untrusted data547548| Argument | Type | Required | Description |549|---|---|---|---|550| `limit` | integer | | Rows returned (default 500). |551| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |552| `sheet` | string | | Sheet name, or its 1-based position (default: first sheet). |553554Output fields: `rowCount`, `rows`, `sheet`, `sheets`, `truncated`, `unsupported`555556## filesystem557558### `filesystem.archive`559560Compresses a file or a directory into a .zip archive. Refuses to replace an existing archive unless overwrite is true.561562- side effect: write563- default tier: 1564- timeout: 600 s565- dry run: yes566567| Argument | Type | Required | Description |568|---|---|---|---|569| `destination` | string | yes | Path of the .zip to create. |570| `keepParent` | boolean | | For a directory: store it as the top-level folder of the archive (default true). |571| `overwrite` | boolean | | |572| `source` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |573574Output fields: `bytes`, `destination`, `sha256`575576### `filesystem.checksum`577578Computes the SHA-256 digest of a file.579580- side effect: read581- default tier: 0582- timeout: 300 s583- idempotent584585| Argument | Type | Required | Description |586|---|---|---|---|587| `algorithm` | string | | |588| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |589590Output fields: `algorithm`, `bytes`, `digest`, `path`591592### `filesystem.compare`593594Compares two files (identical or not) or two directory trees (entries added, removed and changed in destination relative to source).595596- side effect: read597- default tier: 0598- timeout: 300 s599- idempotent600601| Argument | Type | Required | Description |602|---|---|---|---|603| `destination` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |604| `includeHidden` | boolean | | |605| `limit` | integer | | Maximum paths per list (default 500). |606| `source` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |607608Output fields: `identical`, `kind`609610### `filesystem.copy`611612Copies a file or a directory tree to a destination path. Refuses to replace an existing destination unless overwrite is true (files only; a backup is kept).613614- side effect: write615- default tier: 1616- timeout: 300 s617- dry run: yes618619| Argument | Type | Required | Description |620|---|---|---|---|621| `destination` | string | yes | Full path of the copy. |622| `overwrite` | boolean | | |623| `source` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |624625Output fields: `backupPath`, `destination`, `source`626627### `filesystem.delete`628629Permanently deletes a file or directory. Irreversible: prefer filesystem.trash. A non-empty directory needs recursive: true.630631- side effect: destructive632- default tier: 3633- timeout: 300 s634- dry run: yes635636| Argument | Type | Required | Description |637|---|---|---|---|638| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |639| `recursive` | boolean | | Required to delete a non-empty directory. |640641Output fields: `deleted`, `items`, `path`642643### `filesystem.list`644645Lists the entries of a directory (name, type, size, modification date), optionally recursively to a bounded depth.646647- side effect: read648- default tier: 0649- timeout: 30 s650- idempotent651- output is untrusted data652653| Argument | Type | Required | Description |654|---|---|---|---|655| `includeHidden` | boolean | | Include dot files (default false). |656| `limit` | integer | | Maximum entries returned (default 500). |657| `maxDepth` | integer | | Depth limit when recursive (default 3). |658| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |659| `recursive` | boolean | | Descend into subdirectories. |660661Output fields: `count`, `entries`, `path`, `truncated`662663### `filesystem.metadata`664665Returns type, size, dates, POSIX permissions, owner and content type of a file or directory.666667- side effect: read668- default tier: 0669- timeout: 30 s670- idempotent671672| Argument | Type | Required | Description |673|---|---|---|---|674| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |675676Output fields: `path`, `size`, `type`677678### `filesystem.mkdir`679680Creates a directory (and missing parents). Succeeds when the directory already exists.681682- side effect: write683- default tier: 1684- timeout: 30 s685- dry run: yes686- idempotent687688| Argument | Type | Required | Description |689|---|---|---|---|690| `createParents` | boolean | | Default true. |691| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |692693Output fields: `created`, `path`694695### `filesystem.move`696697Moves or renames a file or directory. Never replaces an existing destination: the call fails instead.698699- side effect: write700- default tier: 1701- timeout: 300 s702- dry run: yes703704| Argument | Type | Required | Description |705|---|---|---|---|706| `destination` | string | yes | Full new path. |707| `source` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |708709Output fields: `destination`, `source`710711### `filesystem.read`712713Reads a file as UTF-8 text (bounded by maxBytes from an offset), or as base64 when encoding is base64.714715- side effect: read716- default tier: 0717- timeout: 30 s718- idempotent719- output is untrusted data720721| Argument | Type | Required | Description |722|---|---|---|---|723| `encoding` | string | | utf8 (default) or base64 for binary content. |724| `maxBytes` | integer | | Default 100000. |725| `offset` | integer | | Byte offset to start from. |726| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |727728Output fields: `bytesRead`, `content`, `encoding`, `offset`, `path`, `totalBytes`, `truncated`729730### `filesystem.search`731732Finds files under a directory by name glob and/or by content (substring or regular expression). Results and scanned bytes are bounded.733734- side effect: read735- default tier: 0736- timeout: 120 s737- idempotent738- output is untrusted data739740| Argument | Type | Required | Description |741|---|---|---|---|742| `caseSensitive` | boolean | | Content matching is case-sensitive (default false). |743| `content` | string | | Text to find inside files. |744| `includeHidden` | boolean | | |745| `maxDepth` | integer | | |746| `maxFileBytes` | integer | | Files larger than this are not scanned for content (default 2 MB). |747| `maxResults` | integer | | Default 100. |748| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |749| `pattern` | string | | Name glob such as *.pdf (matched on the file name). |750| `regex` | boolean | | Treat content as a regular expression. |751752Output fields: `count`, `filesScanned`, `matches`, `truncated`753754### `filesystem.trash`755756Moves a file or directory to the Trash (recoverable) and returns where it now is.757758- side effect: write759- default tier: 1760- timeout: 30 s761- dry run: yes762763| Argument | Type | Required | Description |764|---|---|---|---|765| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |766767Output fields: `path`, `trashPath`768769### `filesystem.unarchive`770771Extracts a .zip archive into a directory. Archives whose entries would land outside the destination (zip-slip) are refused, and existing files are never replaced.772773- side effect: write774- default tier: 1775- timeout: 600 s776- dry run: yes777- output is untrusted data778779| Argument | Type | Required | Description |780|---|---|---|---|781| `destination` | string | yes | Directory to extract into (created if missing). |782| `source` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |783784Output fields: `count`, `destination`, `entries`785786### `filesystem.waitForChange`787788Waits until a file or anything inside a directory changes, or until the timeout. Returns the changed paths; a timeout is a normal result with changed: false.789790- side effect: read791- default tier: 0792- timeout: 3060 s793- idempotent794795| Argument | Type | Required | Description |796|---|---|---|---|797| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |798| `timeoutSeconds` | number | | |799800Output fields: `changed`, `events`, `timedOut`801802### `filesystem.write`803804Creates a file, appends to it, or overwrites it when overwrite is true. An overwritten or appended file is first copied to the run's artifacts so the change can be undone.805806- side effect: write807- default tier: 1808- timeout: 30 s809- dry run: yes810811| Argument | Type | Required | Description |812|---|---|---|---|813| `content` | string | yes | Text, or base64 when encoding is base64. |814| `createParents` | boolean | | Create missing parent directories (default true). |815| `encoding` | string | | |816| `mode` | string | | create (default; fails if the file exists unless overwrite) or append. |817| `overwrite` | boolean | | Required to replace an existing file. |818| `path` | string | yes | Absolute path, ~/ path, or path relative to the working directory. |819820Output fields: `backupPath`, `bytesWritten`, `created`, `path`, `sha256`821822## git823824### `git.branches`825826Lists local branches (and remote-tracking branches on request) with their tip, upstream and which one is checked out.827828- side effect: read829- default tier: 0830- timeout: 60 s831- idempotent832- output is untrusted data833834| Argument | Type | Required | Description |835|---|---|---|---|836| `includeRemotes` | boolean | | |837| `path` | string | | Repository directory (default: the run's working directory). |838839Output fields: `branches`, `current`840841### `git.commit`842843Stages the given paths and commits exactly those paths with a message. Hooks run; history is never amended or rewritten.844845- side effect: write846- default tier: 1847- timeout: 300 s848- dry run: yes849- output is untrusted data850851| Argument | Type | Required | Description |852|---|---|---|---|853| `message` | string | yes | |854| `path` | string | | Repository directory (default: the run's working directory). |855| `paths` | array | yes | Files or folders to commit. |856857Output fields: `branch`, `commit`, `summary`858859### `git.createPatch`860861Writes the unstaged, staged or range diff of a repository as a .patch file in the run's artifacts (untracked files are not included). The repository is not modified.862863- side effect: read864- default tier: 0865- timeout: 120 s866- idempotent867868| Argument | Type | Required | Description |869|---|---|---|---|870| `name` | string | | File name without extension. |871| `path` | string | | Repository directory (default: the run's working directory). |872| `paths` | array | | |873| `range` | string | | Revision or range such as main..feature. |874| `staged` | boolean | | |875876Output fields: `bytes`, `empty`, `patchPath`877878### `git.diff`879880Shows the unstaged diff, the staged diff, or the diff of a revision range (a..b), optionally limited to paths. Output is bounded.881882- side effect: read883- default tier: 0884- timeout: 120 s885- idempotent886- output is untrusted data887888| Argument | Type | Required | Description |889|---|---|---|---|890| `contextLines` | integer | | |891| `maxBytes` | integer | | Default 100000. |892| `path` | string | | Repository directory (default: the run's working directory). |893| `paths` | array | | Limit to these paths. |894| `range` | string | | Revision or range such as main..feature. |895| `staged` | boolean | | Diff of the index against HEAD. |896| `stat` | boolean | | Only the per-file summary. |897898Output fields: `diff`, `empty`, `truncated`899900### `git.log`901902Lists recent commits (hash, author, date, subject) of a branch or revision range, optionally limited to paths.903904- side effect: read905- default tier: 0906- timeout: 60 s907- idempotent908- output is untrusted data909910| Argument | Type | Required | Description |911|---|---|---|---|912| `limit` | integer | | Default 20. |913| `path` | string | | Repository directory (default: the run's working directory). |914| `paths` | array | | |915| `ref` | string | | Branch, tag, commit or range. |916917Output fields: `commits`, `count`918919### `git.push`920921Pushes one branch to a configured remote. This publishes commits outside the Mac; force replaces remote history and is high-risk.922923- side effect: external924- default tier: 2925- timeout: 600 s926- dry run: yes927- output is untrusted data928929| Argument | Type | Required | Description |930|---|---|---|---|931| `branch` | string | | Branch to push (default: the current branch). |932| `force` | boolean | | Replace the remote branch. |933| `path` | string | | Repository directory (default: the run's working directory). |934| `remote` | string | | Remote name (default origin). |935| `setUpstream` | boolean | | |936| `timeoutSeconds` | number | | Seconds before the call is stopped. |937938Output fields: `branch`, `forced`, `output`, `remote`939940### `git.status`941942Reports the branch, upstream, ahead/behind counts and the staged, unstaged, untracked and conflicted files of a repository.943944- side effect: read945- default tier: 0946- timeout: 60 s947- idempotent948- output is untrusted data949950| Argument | Type | Required | Description |951|---|---|---|---|952| `path` | string | | Repository directory (default: the run's working directory). |953954Output fields: `clean`, `staged`, `unstaged`, `untracked`955956## http957958### `http.request`959960Sends one HTTP request (HTTPS only, plain HTTP allowed for loopback) to a declared host and returns status, headers and a bounded body. Redirects to another host are reported, not followed. Secrets go in secretHeaders by reference and are never echoed.961962- side effect: external963- default tier: 2964- timeout: 300 s965- output is untrusted data966967| Argument | Type | Required | Description |968|---|---|---|---|969| `body` | string | | Request body text. |970| `followRedirects` | boolean | | Follow redirects that stay on the same host (default true). |971| `headers` | object | | |972| `maxBytes` | integer | | Response body bound (default 200000). |973| `method` | string | | Default GET. |974| `secretHeaders` | object | | Header name → secret reference name. The header value is the secret (prefix it with secretPrefix if needed). |975| `secretPrefix` | string | | Text put before each secret value, for example "Bearer ". |976| `timeoutSeconds` | number | | Seconds before the call is stopped. |977| `url` | string | yes | Absolute URL. |978979Output fields: `body`, `bodyEncoding`, `headers`, `redirect`, `status`, `truncated`, `url`980981## notifications982983### `notifications.post`984985Shows a local notification from ORIX OS Automation. With an approvalID it carries Approve / Deny / Open buttons; the answer goes to the app, not to the agent.986987- side effect: write988- default tier: 1989- timeout: 15 s990- dry run: yes991- macOS permission: notifications992993| Argument | Type | Required | Description |994|---|---|---|---|995| `approvalID` | string | | Approval request the notification asks about. |996| `body` | string | yes | Notification text. |997| `runID` | string | | Run the notification belongs to. |998| `sound` | boolean | | Play the default sound (default true). |999| `subtitle` | string | | |1000| `title` | string | yes | Notification title. |10011002Output fields: `id`, `posted`10031004## python10051006### `python.envInfo`10071008Describes ORIX's managed Python environment: whether it exists yet, interpreter path and version, and the installed packages.10091010- side effect: read1011- default tier: 01012- timeout: 60 s1013- idempotent10141015Output fields: `exists`, `interpreter`, `packages`, `root`, `version`10161017### `python.run`10181019Runs Python code (or a script file) in ORIX's own virtual environment, inside a sandbox limited to the run's granted folders. Files it creates are returned as artifacts. Packages can be installed first, exact pins only (name==1.2.3).10201021- side effect: external1022- default tier: 21023- timeout: 1800 s1024- output is untrusted data10251026| Argument | Type | Required | Description |1027|---|---|---|---|1028| `args` | array | | sys.argv[1:]. |1029| `code` | string | | Python source to run. |1030| `cwd` | string | | Working directory (default: a fresh folder in the run's artifacts). |1031| `maxBytes` | integer | | |1032| `path` | string | | Script file to run instead of code. |1033| `requirements` | array | | Packages to install first, each pinned as name==version. |1034| `stdin` | string | | |1035| `timeoutSeconds` | number | | Seconds before the call is stopped. |10361037Output fields: `durationMs`, `exitCode`, `stderr`, `stdout`, `truncated`10381039## screen10401041### `screen.capture`10421043Takes a PNG screenshot of one display, of an application's frontmost window, or of a rectangular region. Windows of password managers are left out, and nothing is captured while secure keyboard input is active.10441045- side effect: write1046- default tier: 11047- timeout: 30 s1048- macOS permission: screenRecording10491050| Argument | Type | Required | Description |1051|---|---|---|---|1052| `bundleID` | string | | Application whose frontmost window is captured, for scope window. |1053| `displayIndex` | integer | | Display to capture for scope display (0 is the main display). |1054| `overwrite` | boolean | | Replace an existing file at path (default false). |1055| `path` | string | | Where to write the PNG (default: the run's artifacts directory). |1056| `region` | object | | Rectangle in global screen points (origin top-left of the main display), for scope region. |1057| `scope` | string | yes | What to capture. |10581059Output fields: `path`, `pixelHeight`, `pixelWidth`, `scale`, `scope`10601061### `screen.compare`10621063Compares two image files of the same pixel size and returns the ratio of changed pixels and the bounding box of the difference; can write an annotated PNG showing what changed.10641065- side effect: write1066- default tier: 11067- timeout: 120 s1068- idempotent10691070| Argument | Type | Required | Description |1071|---|---|---|---|1072| `after` | string | yes | Second image file. |1073| `before` | string | yes | First image file. |1074| `diffPath` | string | | Optional PNG to write: the second image with changed pixels tinted red and the difference outlined. |1075| `overwrite` | boolean | | Replace an existing file at diffPath (default false). |1076| `tolerance` | integer | | Per-channel difference (0–255) below which a pixel counts as unchanged (default 8). |10771078Output fields: `changedPixels`, `changedRatio`, `height`, `identical`, `totalPixels`, `width`10791080### `screen.ocr`10811082Recognises text in an image file (PNG, JPEG, TIFF, HEIC …) on this Mac with Vision and returns text blocks with confidence and bounding boxes (top-left origin, normalised and in pixels).10831084- side effect: read1085- default tier: 01086- timeout: 120 s1087- idempotent1088- output is untrusted data10891090| Argument | Type | Required | Description |1091|---|---|---|---|1092| `fast` | boolean | | Use the fast recogniser instead of the accurate one (default false). |1093| `languages` | array | | Preferred recognition languages, for example ["en-US", "fr-FR"] (default: automatic). |1094| `maxBlocks` | integer | | Maximum text blocks returned (default 400). |1095| `path` | string | yes | Image file. |10961097Output fields: `blocks`, `imageHeight`, `imageWidth`, `text`10981099## script11001101### `script.javascript`11021103Runs JavaScript in the system JavaScriptCore shell (jsc) as a separate sandboxed process: print(), readFile(), arguments are available; there is no DOM, no Node API and no network.11041105- side effect: external1106- default tier: 21107- timeout: 1800 s1108- output is untrusted data11091110| Argument | Type | Required | Description |1111|---|---|---|---|1112| `args` | array | | |1113| `cwd` | string | | Working directory (default: a fresh folder in the run's artifacts). |1114| `maxBytes` | integer | | |1115| `script` | string | yes | JavaScript source. |1116| `timeoutSeconds` | number | | Seconds before the call is stopped. |11171118Output fields: `durationMs`, `exitCode`, `stderr`, `stdout`, `truncated`11191120### `script.swift`11211122Runs a Swift script with the system toolchain inside a sandbox limited to the run's granted folders (no network unless a host is granted). Needs the Xcode command line tools.11231124- side effect: external1125- default tier: 21126- timeout: 1800 s1127- output is untrusted data11281129| Argument | Type | Required | Description |1130|---|---|---|---|1131| `args` | array | | |1132| `cwd` | string | | Working directory (default: a fresh folder in the run's artifacts). |1133| `maxBytes` | integer | | |1134| `script` | string | yes | Swift source. |1135| `timeoutSeconds` | number | | Seconds before the call is stopped. |11361137Output fields: `durationMs`, `exitCode`, `stderr`, `stdout`, `truncated`11381139## shell11401141### `shell.run`11421143Runs one executable with an explicit argument array (no shell, no interpolation), confined to the folders granted to the run. Refuses sudo/su/doas and interpreters given inline code; a non-zero exit code is returned, not raised.11441145- side effect: external1146- default tier: 21147- timeout: 1800 s1148- output is untrusted data11491150| Argument | Type | Required | Description |1151|---|---|---|---|1152| `args` | array | | Arguments, passed verbatim as separate argv elements. |1153| `cwd` | string | | Working directory (default: the run's working directory). |1154| `env` | object | | Extra environment variables. |1155| `executable` | string | yes | Program name (resolved through a fixed system PATH) or absolute path. |1156| `maxBytes` | integer | | Output bound per stream (default 100000). |1157| `stdin` | string | | Text written to the program's standard input. |1158| `timeoutSeconds` | number | | Seconds before the call is stopped. |11591160Output fields: `durationMs`, `exitCode`, `stderr`, `stdout`, `truncated`11611162### `shell.script`11631164Runs bash script text inside a Seatbelt sandbox: it can only write to the folders granted to the run and its artifacts, and has no network unless a host is granted. Privilege escalation is refused.11651166- side effect: external1167- default tier: 21168- timeout: 1800 s1169- output is untrusted data11701171| Argument | Type | Required | Description |1172|---|---|---|---|1173| `args` | array | | Positional parameters ($1, $2 …). |1174| `cwd` | string | | Working directory (default: the run's working directory). |1175| `env` | object | | |1176| `maxBytes` | integer | | |1177| `script` | string | yes | Bash source. |1178| `timeoutSeconds` | number | | Seconds before the call is stopped. |11791180Output fields: `durationMs`, `exitCode`, `stderr`, `stdout`, `truncated`11811182## skill11831184### `skills.install`11851186Install a draft produced by skills.propose as a versioned local tool. The user reviews its source, permissions, analysis and test results and must approve. After installation the tool skill.<name> is available.11871188- side effect: external1189- default tier: 21190- timeout: 30 s11911192| Argument | Type | Required | Description |1193|---|---|---|---|1194| `draftID` | string | yes | |11951196### `skills.list`11971198List installed skills and pending drafts with their versions and permissions.11991200- side effect: read1201- default tier: 01202- timeout: 30 s1203- idempotent12041205### `skills.propose`12061207Propose a new reusable tool when no existing tool fits. Give a manifest (name, summary, runtime python or bash, input/output schemas, the exact file and network permissions it needs), the source, and tests with fixture files. The source reads its input as JSON on stdin and prints one JSON object on stdout. The package is analysed and its tests are run in a sandbox with no network. Nothing is installed: use skills.install afterwards, which asks the user.12081209- side effect: external1210- default tier: 21211- timeout: 300 s12121213| Argument | Type | Required | Description |1214|---|---|---|---|1215| `fileRead` | array | | |1216| `fileWrite` | array | | |1217| `inputSchema` | object | yes | JSON Schema of the input object |1218| `name` | string | yes | camelCase name; the tool becomes skill.<name> |1219| `network` | array | | |1220| `outputSchema` | object | | JSON Schema of the output object |1221| `runtime` | string | yes | |1222| `source` | string | yes | Complete source of the entry file |1223| `summary` | string | yes | What the tool does, for a model choosing tools |1224| `tests` | array | yes | |1225| `title` | string | yes | Human-readable name |1226| `version` | string | | major.minor.patch |12271228## system12291230### `clipboard.read`12311232Reads the text and the file paths currently on the clipboard. Other kinds of content are only named, and entries marked as concealed by a password manager are withheld.12331234- side effect: read1235- default tier: 01236- timeout: 10 s1237- idempotent1238- output is untrusted data12391240| Argument | Type | Required | Description |1241|---|---|---|---|1242| `maxBytes` | integer | | Maximum text size returned (default 100000). |12431244Output fields: `changeCount`, `concealed`, `fileURLs`, `text`, `types`12451246### `clipboard.write`12471248Replaces the clipboard with text, or with a list of files (as if copied in Finder).12491250- side effect: write1251- default tier: 11252- timeout: 10 s1253- dry run: yes1254- idempotent12551256| Argument | Type | Required | Description |1257|---|---|---|---|1258| `content` | string | | Text to place on the clipboard. |1259| `paths` | array | | Files to place on the clipboard instead of text. |12601261Output fields: `changeCount`, `kind`, `written`12621263### `system.apps`12641265Lists running applications with name, bundle identifier, process id and whether each is active or hidden.12661267- side effect: read1268- default tier: 01269- timeout: 10 s1270- idempotent12711272| Argument | Type | Required | Description |1273|---|---|---|---|1274| `includeBackground` | boolean | | Also list background agents and menu-bar-only apps (default false). |12751276Output fields: `applications`12771278### `system.diskUsage`12791280Lists mounted volumes with total and available capacity.12811282- side effect: read1283- default tier: 01284- timeout: 30 s1285- idempotent12861287| Argument | Type | Required | Description |1288|---|---|---|---|1289| `includeHidden` | boolean | | Include system volumes hidden from the Finder. |12901291Output fields: `volumes`12921293### `system.frontmost`12941295Reports the frontmost application and, when Accessibility or Screen Recording access allows it, the title of its focused window. Says which source was used and why a title is missing.12961297- side effect: read1298- default tier: 01299- timeout: 10 s1300- idempotent1301- output is untrusted data13021303Output fields: `application`, `titleSource`, `windowTitle`13041305### `system.info`13061307Reports the macOS version, Mac model, processor, core counts, memory and uptime of this Mac.13081309- side effect: read1310- default tier: 01311- timeout: 30 s1312- idempotent13131314Output fields: `cores`, `cpu`, `memoryBytes`, `model`, `osVersion`, `uptimeSeconds`13151316### `system.launchApp`13171318Launches an application by bundle identifier or path (or brings it forward if it is running) and waits until it reports that it finished launching.13191320- side effect: write1321- default tier: 21322- timeout: 90 s1323- dry run: yes1324- idempotent13251326| Argument | Type | Required | Description |1327|---|---|---|---|1328| `activate` | boolean | | Bring the application to the front (default true). |1329| `bundleID` | string | | Application bundle identifier, for example com.apple.finder. |1330| `path` | string | | Path of the application bundle, as an alternative to bundleID. |1331| `timeoutSeconds` | number | | How long to wait for the launch to finish (default 30). |13321333Output fields: `alreadyRunning`, `bundleID`, `finishedLaunching`, `pid`13341335### `system.networkState`13361337Reports whether the Mac currently has a usable network path and through which interface types (Wi-Fi, wired, cellular), without contacting any host.13381339- side effect: read1340- default tier: 01341- timeout: 30 s1342- idempotent13431344Output fields: `interfaces`, `online`, `status`13451346### `system.powerState`13471348Reports whether the Mac runs on AC power or battery, and the charge and charging state of each battery (a desktop Mac has none).13491350- side effect: read1351- default tier: 01352- timeout: 30 s1353- idempotent13541355Output fields: `batteries`, `hasBattery`, `onACPower`, `source`13561357### `system.processes`13581359Lists the processes using the most CPU or memory (pid, parent, CPU %, memory %, resident size, user, name).13601361- side effect: read1362- default tier: 01363- timeout: 30 s1364- idempotent1365- output is untrusted data13661367| Argument | Type | Required | Description |1368|---|---|---|---|1369| `limit` | integer | | Default 15. |1370| `sortBy` | string | | cpu (default) or memory. |13711372Output fields: `processes`, `total`13731374### `system.quitApp`13751376Asks an application to quit the normal way (it may ask the user to save) and reports whether it did. Never force-quits.13771378- side effect: write1379- default tier: 21380- timeout: 60 s1381- dry run: yes1382- idempotent13831384| Argument | Type | Required | Description |1385|---|---|---|---|1386| `bundleID` | string | yes | Application bundle identifier, for example com.apple.finder. |1387| `timeoutSeconds` | number | | How long to wait for the application to quit (default 10). |13881389Output fields: `bundleID`, `refused`, `terminated`, `wasRunning`13901391### `system.windows`13921393Lists on-screen windows front to back: owner application, bounds, layer and display. Window titles are included only when Screen Recording access is enabled; the output says whether they are.13941395- side effect: read1396- default tier: 01397- timeout: 10 s1398- idempotent1399- output is untrusted data14001401| Argument | Type | Required | Description |1402|---|---|---|---|1403| `bundleID` | string | | Only windows of this application. |1404| `includeAllLayers` | boolean | | Include menu bar, Dock and overlay layers (default false: normal windows only). |1405| `maxWindows` | integer | | Maximum windows returned (default 200). |14061407Output fields: `displays`, `titlesAvailable`, `windows`14081409