# Agent isolation

An agent of GizDesk reads and changes files and runs commands on the person's computer. This
document is the one description of what keeps it to what the person gave it, and of what does
not. How the runtime confines a process is in [System: Confinement](system.md#confinement).

## Contents

1. [Layers](#layers)
2. [Places](#places)
3. [A conversation's scope](#a-conversation-s-scope)
4. [Access levels](#access-levels)
5. [Commands](#commands)
6. [Approvals](#approvals)
7. [Other computers](#other-computers)
8. [What it does not keep](#what-it-does-not-keep)
9. [Code and tests](#code-and-tests)

## Layers

| Layer | Who keeps it | What it keeps |
| --- | --- | --- |
| Places | The Desk (`desk/places.giz`) | The folders of the computer that agents may reach at all. |
| Scope | The Desk, per conversation | Which places one conversation reaches, and its access level. |
| File tools | The Drive API (`desk/drive.giz`) | Reads and changes of files, with versions and a trash, inside the scope. |
| Commands | The system (`runtime/isolate.c`) | What a shell command reads, writes and reaches on the network. |
| Approvals | The agent's policy (`desk/model.giz`) | Which tool calls wait for the person. |

Each layer is the only owner of its rule. A command is not checked by the Desk's code: the
system refuses what the scope does not allow, so a command that the agent writes cannot get
around it.

## Places

A place is a Drive of the Desk:

- **Giz Drive**, the Desk's own Drive, in `~/Giz Drive` (`GIZDESK_FILES`). It is always first.
- **A folder of this computer** that the person gave on the Drive page (*Folders of this
  computer*): any absolute path, read and changed (`folder`) or read only (`readonly`). A folder
  that is a place already, holds one or is in one is refused.

A place is a Drive record, so its view, search, versions (`.giz/` inside the folder), trash,
share links and S3 access are those of every Drive. Removing a place keeps its folder and files.
In a place read only, every reader is a `viewer`: the Drive API refuses each change, and a share
link into it reads only, whatever role it was made with.

## A conversation's scope

Each conversation (table `chats`) has `folders`, the Drive ids of its places separated by
spaces ("" is every place), and `access`. The person sets both with the folder button beside the
message box; a new conversation takes the last choice, and a branch takes its parent's.

- A relative path is in the first place of the scope. Commands start there.
- An absolute path must be inside one of the places; any other path is refused.
- A place that no longer exists is left out. A scope left with none has every place.
- The agent is told its folders and access level, and the `folders` tool lists them.
- `search` and `read` find and read the files of the scope only.

## Access levels

| Level | File tools | Commands on this computer | Approval |
| --- | --- | --- | --- |
| `read` | Read the places. | Read every file, change none, reach no network. | None. |
| `work` (default) | Read, and change the places that are not read only. | Change only those places and the temporary folders. | None. |
| `full` | As `work`. | Run as the person, with no limit. | Each command. |

The temporary folders are `/tmp`, `/var/tmp`, `/dev/shm`, the terminal and null devices and
`~/.cache` (`~/Library/Caches` on macOS), so compilers and package tools work; on Windows,
`%LOCALAPPDATA%\Temp\Low`, which `TEMP` and `TMP` name for the command.

## Commands

`run_command` runs a command in the shell of the system: `powershell.exe -NoProfile -Command`
on Windows, `/bin/sh -lc` elsewhere. It runs in the first place of the scope, for at most 600 s,
and answers at most 1 MiB of output.

At `read` and `work` the Desk starts the shell with `SpawnOptions.confined` of
[Confinement](system.md#confinement). The runtime confines the child before the shell starts, so
the shell and all that it starts are confined:

| System | Files | Network at `read` |
| --- | --- | --- |
| Linux | Landlock: writes only in the allowed folders; reads every file. A kernel before 5.13 has no Landlock and confines no files. | seccomp refuses IPv4 and IPv6 sockets. |
| macOS | The sandbox profile: writes only in the allowed folders; reads every file. | The profile refuses IP connections. |
| Windows | Low integrity: writes only in the allowed folders, which are labeled Low only while the command runs; reads every file. | Not refused: the network stays. |

If the process cannot be confined, the command does not run (exit 71). On Windows a command stopped at its limit is ended
with its job, and the Desk's runtime takes the Low labels away.

## Approvals

The agent's permission policy (*Permissions*, `Assistant.approve`) decides which tool calls wait
for the person; a write tool waits under *Create with approval* and *All tools*. On top of it,
`run_command` always waits at `full`, and `run_on_host` always waits. There is no second
approval setting.

## Other computers

Connections → *Computers* adds SSH hosts (`desk/hosts.giz`). `list_hosts` lists them and
`run_on_host` runs a command there as that host's account, in its folder. No scope applies
there, so every such command waits for the person's approval.

## What it does not keep

- **Reads.** At `read` and `work` a command can read every file the person can, such as
  `~/.ssh`. Only the places limit what the file tools read.
- **The network at `work`.** A command may reach the network; on Windows also at `read`.
- **Compute.** CPU, memory and the number of processes are not limited; the bounds are 600 s and
  1 MiB of output.
- **Old kernels.** On Linux before 5.13 files are not confined.
- **What a model is sent.** Files the agent reads go to its model's provider.

For untrusted code at a service's scale, use a separate sandbox with compute limits
([Isolation](system.md#isolation) and [Resource limits](system.md#resource-limits) are the
runtime's own).

## Code and tests

| Part | Code | Tests |
| --- | --- | --- |
| Places, scope, confined commands | `desk/places.giz`, `desk/places.ghtml` | `tests/desk/places.test.giz` |
| File tools in a scope | `desk/drive.giz` | `tests/desk/places.test.giz`, `tests/desk/drive.test.giz` |
| Hosts and their tools | `desk/hosts.giz` | `tests/desk/accounts.test.giz` |
| Confinement | `runtime/isolate.c` | `tests/desk/places.test.giz` (Linux), `tests/browser/renderer.test.giz` |
