π«π· Version franΓ§aise
Drive tools
See also: Tool inventory Β· E-mail tools Β· Configuration reference Β· ADR-013 Β· Back to index
The drive family gives agents a cloud drive: Google Drive ("My Drive") through the Drive API v3, and OneDrive β personal, or for work and school β through Microsoft Graph. Both are spoken in plain HTTP, with no vendor SDK. An agent lists, searches, reads, downloads into the virtual file system, uploads from it, creates folders, moves, renames, deletes and shares β within what the operator allows:
- The operator declares the accounts under
Orkeon:Tools:Drive. An agent names an account (or uses the default one), never a client id, a secret or a token. Rightsis mandatory for each account:Read, Write, Organize, Share, Delete, Purge.Rootconfines an account to a folder of its drive. Every item a call touches must lie under it; an item outside is reported as not found.- Sharing is closed by default: an empty
Share:AllowedRecipientsallows nobody, and public links stay off untilShare:AllowPublicLinksistrue. - Every account signs in once with OAuth2 (
orkeon drive loginin a terminal), and the tools refresh the access token by themselves.
Test coverage. The family is covered by offline tests against scripted Google and Microsoft APIs; it has not been verified here against every live account configuration. Report what differs.
The eleven tools
| Tool | Right needed | What it does |
|---|---|---|
drive_accounts |
none | Lists the accounts: name, rights, root folder, whether each is ready |
drive_list |
Read | One page of a folder (the root by default), folders first |
drive_search |
Read | Items matching words, a name, a MIME type, a kind, a date or a folder, inside the root |
drive_info |
Read | One item's metadata, its browser address included |
drive_read |
Read | The text of a text file or a Google document, screened, in slices |
drive_download |
Read + a writable mount | Saves a file into a virtual directory; Google documents are exported |
drive_upload |
Write | Uploads a file of the VFS, or replaces a file's content (replace_id) |
drive_create_folder |
Write | Creates a folder |
drive_move |
Organize | Moves and/or renames an item |
drive_delete |
Delete (+ Purge with permanent) |
Moves an item to the trash, or deletes it for good |
drive_share |
Share | Gives allowed addresses access, or creates a public link when allowed |
Ids are the provider's own and opaque: pass them back exactly as drive_list or drive_search
returned them. root names the account's root folder wherever a folder id is taken
(folder_id, parent_id, destination_id).
OneDrive (Microsoft Graph)
Register an application in Microsoft Entra
- Open the Microsoft Entra admin center βΊ App registrations βΊ New registration.
- Name it (
Orkeon drive, for instance) and choose the supported account types: Personal Microsoft accounts only for a personal OneDrive, Accounts in any organizational directory and personal Microsoft accounts to serve both. No redirect URI is needed. - In Authentication, set Allow public client flows to Yes: the sign-in uses the device-code flow.
- In API permissions βΊ Microsoft Graph βΊ Delegated permissions, add
Files.ReadWrite(orFiles.Readfor an account that only reads) andoffline_access. Withoutoffline_accessMicrosoft issues no refresh token, and the login refuses to store a sign-in that would expire within the hour. - Copy the Application (client) ID.
An application registered for the e-mail family can serve the drive family too: add the Files.*
permissions to it.
Declare the account and sign in
Under Orkeon:Tools:Drive:Accounts:
"pro": {
"Provider": "OneDrive",
"Rights": "Read, Write, Organize",
"Root": "Orkeon/agents",
"Auth": { "ClientId": "00000000-0000-0000-0000-000000000000" }
}
Auth:Tenant defaults to consumers, the tenant of personal accounts; for OneDrive for work or
school set "Tenant": "organizations" or your tenant id.
In a terminal:
orkeon drive login pro
The command prints Microsoft's verification address and a code. Open the address in any browser β
on any device β, enter the code, sign in and accept. The command stores the tokens and prints
Signed in. Check the account with orkeon drive check pro: it finds the root folder and lists
its first items.
Google Drive
Google's device flow does not offer the Drive scopes, so the login prints the address of Google's
consent page for you to open, and receives the answer on a loopback address (127.0.0.1), with
PKCE β the same flow as a Gmail account with OAuth2.
In the Google Cloud console, create a project and enable the Google Drive API.
Configure the OAuth consent screen: user type External, add the scope
https://www.googleapis.com/auth/drive(ordrive.readonlyfor an account that only reads), and add your own address as a test user.Create an OAuth client ID of type Desktop app. Copy its client ID, and put its client secret in an environment variable (
GOOGLE_DRIVE_CLIENT_SECRETbelow).Declare the account, under
Orkeon:Tools:Drive:Accounts:"perso": { "Provider": "GoogleDrive", "Rights": "Read, Write", "Root": "Orkeon", "Auth": { "ClientId": "123456789012-abcdefghijklmnop.apps.googleusercontent.com", "ClientSecretEnvVar": "GOOGLE_DRIVE_CLIENT_SECRET" } }Sign in: in a terminal, run
orkeon drive login perso. It prints a Google address to open and listens on a free port of127.0.0.1. Sign in and accept; Google shows a warning screen for an application it has not verified, which you may continue past for your own application. When the browser runs on another machine β WSL, a container, an SSH session β the last page cannot load: copy the address it ends on (http://127.0.0.1:β¦/?state=β¦&code=β¦) from the address bar, paste it in the terminal and press Enter.
Keep the sign-in alive. A Google application left in the Testing publishing status gets refresh tokens that expire after 7 days. Publish it (In production) to keep them.
Settings reference
Key (under Orkeon:Tools:Drive) |
Meaning |
|---|---|
DefaultAccount |
The account a call that names none uses; optional with a single account |
CredentialsDirectory |
Where the tokens are kept (its drive subdirectory); default credentials next to the per-user settings |
Screening:WithholdRejected |
Withhold the text of a file the prompt-injection screen rejects (default false: flag only) |
Accounts:<name>:Provider |
GoogleDrive or OneDrive β mandatory |
Accounts:<name>:Rights |
Of Read, Write, Organize, Share, Delete, Purge β mandatory |
Accounts:<name>:Root |
The folder the account is confined to, as a path from the root of the drive (Orkeon/agents); unset: the whole drive |
Accounts:<name>:Auth:ClientId |
The Google Cloud or Microsoft Entra application β mandatory |
Accounts:<name>:Auth:ClientSecretEnvVar |
The name of the variable holding the Google client secret β mandatory for Google Drive. Write the name alone: Orkeon expands no variable, and an account whose Auth:ClientSecretEnvVar holds a ${NAME} or %NAME% reference is set aside, with that problem |
Accounts:<name>:Auth:Tenant |
Microsoft only: consumers (default), organizations, common or a tenant id |
Accounts:<name>:Share:AllowedRecipients |
Who an agent may share with: an address, *@domain or *; empty: nobody |
Accounts:<name>:Share:AllowPublicLinks |
Whether an agent may create a link anyone holding it can open (default false) |
Accounts:<name>:MaxUploadMegabytes |
The largest upload (default 100) |
Accounts:<name>:TimeoutSeconds |
HTTP timeout of the account's calls |
The section is validated lazily, as the e-mail one: a broken account is reported when a call or
orkeon drive uses it, and never breaks a crew that opens no drive. The client secret is read
like the e-mail secrets: the process environment, then β on Windows β the user's own variables.
Rights, root folder and scopes
| Right | Tools it opens |
|---|---|
Read |
drive_list, drive_search, drive_info, drive_read, drive_download |
Write |
drive_upload, drive_create_folder |
Organize |
drive_move |
Share |
drive_share |
Delete |
drive_delete (to the trash) |
Purge |
drive_delete with permanent: true |
- An account that only reads asks for a read-only scope (
drive.readonly,Files.Read): a leaked token of a reading crew cannot write either. GrantingWritelater changes the scopes, and the account asks for a new sign-in. Rootis found once per run: by path on OneDrive, by name under each parent on Google Drive (which has no paths). An item is inside the root when its parent path says so (OneDrive) or when climbing its parents reaches the root (Google Drive, 32 levels at most). A search on Google Drive cannot be bounded to a subtree: its results outside the root are dropped, so a page can hold fewer items thanlimit.- A name already taken in a folder is refused on upload, folder creation and move: Google Drive would accept two items of the same name, and an agent addressing files by name would then pick the wrong one.
- The trash first.
drive_deletemoves to the trash (the recycle bin on OneDrive), from where a person restores it.permanent: trueneedsPurge; an account on theconsumerstenant (personal Microsoft accounts; the default) has no permanent deletion on OneDrive and the tool refuses it. - A crew whose drive tools need a right no ready account grants is refused at start, before any model call, with a line per tool β as for the mail tools.
What reaches the agent, and what never leaves
- The token stays with the API. It is sent to
www.googleapis.comorgraph.microsoft.comonly, over HTTPS. A OneDrive download goes through the pre-authenticated@microsoft.graph.downloadUrlwithout it, an upload session receives the bytes without it, and a paging cursor that does not point at the API is refused. - Content is data.
drive_readopens with a notice that the text is untrusted, and the verdict of the prompt-injection screen (clean,suspicious,rejected). WithScreening:WithholdRejectedthe text of a rejected file is withheld. Names and metadata of the other tools go through the run's usual result sanitizer. - Downloads never overwrite.
drive_downloadwrites a new file (name (2).extwhen the name is taken) into a mount the crew may create in. - Results fit the agent loop. A page is asked again with fewer items until it fits a tool
result, so
next_cursorresumes exactly after the last item shown;drive_readreturns slices withnext_offset. - A search keeps to the root. Neither provider searches a subtree alone (Google searches the
whole drive, OneDrive on the
consumerstenant may), sodrive_searchdrops what lies outside the account's root and reads further provider pages, up to five, to fill the page asked for. A page can still come back short, even empty, with anext_cursorthat goes on from there. - Drive traffic stays out of the LLM exchange log. The drive client is excluded from what
--llm-logcaptures: its requests, file contents and upload session addresses are never written there.
Using the tools
From a YAML crew:
agents:
archivist:
role: "Archivist"
goal: "File the weekly report in the team drive"
tools: [drive_list, drive_upload, drive_move]
From an .ork.ts script, the tools are typed (Typings/tools.d.ts), with the tool's own
snake_case keys:
const page = await tools.driveList({ folder_id: "root" });
const report = await tools.driveUpload({ path: "/output/report.pdf", folder_id: page.items[0].id });
Commands
orkeon drive accounts [--json] # the accounts, their rights, root folder and readiness (no network)
orkeon drive login <account> # the one interactive step: device code (OneDrive) or browser (Google)
orkeon drive check <account> # connects, finds the root folder, lists its first items
orkeon drive logout <account> # forgets the stored tokens
Every verb takes --settings <file>; without it the settings are resolved like orkeon run
resolves them, so the tokens land where every run looks for them. login and check take
--events jsonl too: one event line per step, for a program that drives them
(CLI reference).
accounts --json writes one object per account: name, provider, rights, root, default,
ready, problem, plus configuration_problems (the configuration's problems, one sentence each,
the section's first; empty when the account resolves), credential_problem (why a resolved account
cannot sign in yet, else null) and token_endpoint (the OAuth token endpoint after presets: for
OneDrive it names the tenant; null for an account set aside). problem keeps its text: the joined
configuration problems or the credential diagnosis.
Where the tokens live
The runner keeps them under its internal /credentials root, which no agent-facing tool resolves,
in a drive subdirectory created owner-only on Unix β beside the e-mail family's email one, in
the same credentials directory. As for e-mail, the tokens are shielded from the VFS tools, not
from a shell_command running as the same operating-system user. orkeon-repl keeps no token
store: a drive tool called from the REPL says so.
Out of scope for now
Google shared drives and SharePoint document libraries (an account sees its own "My Drive" or OneDrive), revisions, comments, removing a share, copying, and a forge trial drive β the forge removes the drive tools from a forged crew. A drive mounted in the virtual file system is not offered either: the tools are the interface.