agent-lookout 0.2.4 → 0.2.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +56 -0
- package/PRIVACY.md +121 -39
- package/README.md +29 -22
- package/SECURITY.md +35 -12
- package/dist/assets/HistoryPanel-Cwmn7YtJ.js +1 -0
- package/dist/assets/SessionPanel-BJ5t_CPi.js +1 -0
- package/dist/assets/index-B_1Its0R.css +1 -0
- package/dist/assets/index-QSfCI-L_.js +3 -0
- package/dist/cli/agent-lookout.js +4 -4
- package/dist/cli/{chunk-63XPRBHW.js → chunk-I6Q35DHC.js} +76 -8
- package/dist/cli/{chunk-KNOLJ3IC.js → chunk-JSBQMY3Q.js} +1 -1
- package/dist/cli/{chunk-XVXSGVEW.js → chunk-LZ62RW3N.js} +16 -4
- package/dist/cli/{mcpServer-HGH6PY4W.js → mcpServer-HJSH3WIS.js} +16 -10
- package/dist/cli/{startCommand-KNXMVM2U.js → startCommand-PR5JPWCT.js} +6781 -3109
- package/dist/index.html +2 -2
- package/docs/API.md +214 -64
- package/docs/GUIDE.md +398 -35
- package/package.json +1 -1
- package/dist/assets/HistoryPanel-CIjshvhu.js +0 -1
- package/dist/assets/SessionPanel-eBOdTLD9.js +0 -1
- package/dist/assets/index-B-myfVQS.js +0 -2
- package/dist/assets/index-Cceyz9yZ.css +0 -1
package/dist/index.html
CHANGED
|
@@ -28,11 +28,11 @@
|
|
|
28
28
|
document.documentElement.setAttribute("data-theme", theme);
|
|
29
29
|
})();
|
|
30
30
|
</script>
|
|
31
|
-
<script type="module" crossorigin src="/assets/index-
|
|
31
|
+
<script type="module" crossorigin src="/assets/index-QSfCI-L_.js"></script>
|
|
32
32
|
<link rel="modulepreload" crossorigin href="/assets/react-C2DiJaR6.js">
|
|
33
33
|
<link rel="modulepreload" crossorigin href="/assets/motion-BAhdRuCw.js">
|
|
34
34
|
<link rel="modulepreload" crossorigin href="/assets/radix-BH0JH8UU.js">
|
|
35
|
-
<link rel="stylesheet" crossorigin href="/assets/index-
|
|
35
|
+
<link rel="stylesheet" crossorigin href="/assets/index-B_1Its0R.css">
|
|
36
36
|
</head>
|
|
37
37
|
<body>
|
|
38
38
|
<div id="root"></div>
|
package/docs/API.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# API
|
|
2
2
|
|
|
3
|
-
Agent Lookout's server answers a small HTTP API under `/api/`. The dashboard reads it, and so do `agent-lookout status` and `agent-lookout mcp`. It is meant for this computer only: it listens on a loopback address, and it answers only requests made to a loopback name. Every route returns JSON, and every route but
|
|
3
|
+
Agent Lookout's server answers a small HTTP API under `/api/`. The dashboard reads it, and so do `agent-lookout status` and `agent-lookout mcp`. It is meant for this computer only: it listens on a loopback address, and it answers only requests made to a loopback name. Every route returns JSON, and every route but seven only reads.
|
|
4
4
|
|
|
5
5
|
The answers hold your session names and folder paths. Check one before you share it.
|
|
6
6
|
|
|
@@ -31,30 +31,34 @@ curl -s http://127.0.0.1:4777/api/sessions
|
|
|
31
31
|
|
|
32
32
|
Every answer has `Content-Type: application/json; charset=utf-8`, `Cache-Control: no-store`, `X-Content-Type-Options: nosniff` and `Cross-Origin-Resource-Policy: same-origin`. Every answer that is not a 200 has the body `{ "error": "<one sentence>" }`.
|
|
33
33
|
|
|
34
|
-
| Status | When
|
|
35
|
-
| ------ |
|
|
36
|
-
| 400 | The address, `since` or `windowMs` could not be read
|
|
37
|
-
| 403 | The `Host`, the `Origin` or `Sec-Fetch-Site` above
|
|
38
|
-
| 404 | There is no route at that path
|
|
39
|
-
| 405 | Any method but `GET`, with `Allow: GET`. The
|
|
40
|
-
| 500 | Something went wrong that the server did not expect
|
|
34
|
+
| Status | When |
|
|
35
|
+
| ------ | ------------------------------------------------------------------------------------------------------- |
|
|
36
|
+
| 400 | The address, `since` or `windowMs` could not be read |
|
|
37
|
+
| 403 | The `Host`, the `Origin` or `Sec-Fetch-Site` above |
|
|
38
|
+
| 404 | There is no route at that path |
|
|
39
|
+
| 405 | Any method but `GET`, with `Allow: GET`. The seven routes that act take only `POST`, with `Allow: POST` |
|
|
40
|
+
| 500 | Something went wrong that the server did not expect |
|
|
41
41
|
|
|
42
42
|
## Routes
|
|
43
43
|
|
|
44
|
-
| Route
|
|
45
|
-
|
|
|
46
|
-
| `GET /api/health`
|
|
47
|
-
| `GET /api/sessions`
|
|
48
|
-
| `GET /api/events?since=<epoch ms>`
|
|
49
|
-
| `GET /api/history?windowMs=<ms>`
|
|
50
|
-
| `GET /api/email`
|
|
51
|
-
| `GET /api/webhook`
|
|
52
|
-
| `GET /api/pull-requests`
|
|
53
|
-
| `GET /api/waits`
|
|
54
|
-
| `
|
|
55
|
-
| `POST /api/
|
|
56
|
-
| `POST /api/
|
|
57
|
-
| `POST /api/sessions/
|
|
44
|
+
| Route | Answers |
|
|
45
|
+
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
46
|
+
| `GET /api/health` | `{ ok: true, version }` |
|
|
47
|
+
| `GET /api/sessions` | The latest snapshot: `{ generatedAt, sources, sessions, answering, timeRules, quiet }` |
|
|
48
|
+
| `GET /api/events?since=<epoch ms>` | `{ events }`, newest first, at most 200 |
|
|
49
|
+
| `GET /api/history?windowMs=<ms>` | `{ points, startedAt, since, kept, restarts }`, one point for each poll, oldest first |
|
|
50
|
+
| `GET /api/email` | `{ on, to, events, afterMs, asking, problem, last, limitedUntil }` |
|
|
51
|
+
| `GET /api/webhook` | `{ on, host, events, afterMs, asking, problem, last, limitedUntil }` |
|
|
52
|
+
| `GET /api/pull-requests` | `{ on, problem, gh, last }`: whether each branch's pull request is shown |
|
|
53
|
+
| `GET /api/waits` | `{ at, today, sevenDays, since, where }`: how long sessions waited on you |
|
|
54
|
+
| `GET /api/settings` | `{ timeRules, file, problem, permissionRules, permissionRulesProblem, ruleAnswers, ruleAnswersSince }`: the time rules, the permission rules, the file they are kept in, and what the rules answered |
|
|
55
|
+
| `POST /api/jump` | `{ ok: true, kind, place }`, with `app` for a terminal tab. One of seven routes that act |
|
|
56
|
+
| `POST /api/history/clear` | `{ ok: true, clearedAt }`. A route that acts |
|
|
57
|
+
| `POST /api/sessions/stop` | `{ ok: true }` once the session's process has ended. A route that acts |
|
|
58
|
+
| `POST /api/sessions/clean-up` | `{ results }`, what became of each session left running. A route that acts |
|
|
59
|
+
| `POST /api/permission/answer` | `{ ok: true, decision }` once a permission prompt was answered. A route that acts |
|
|
60
|
+
| `POST /api/settings/time-rules` | `{ ok: true, timeRules }` once the time rules are saved. A route that acts |
|
|
61
|
+
| `POST /api/settings/permission-rules` | `{ ok: true, permissionRules }` once one change to the permission rules is saved. A route that acts |
|
|
58
62
|
|
|
59
63
|
Times are milliseconds since 1970, and lengths of time are milliseconds.
|
|
60
64
|
|
|
@@ -98,50 +102,71 @@ The snapshot the collector made at its last poll, two seconds apart at most:
|
|
|
98
102
|
"links": {},
|
|
99
103
|
"stale": false
|
|
100
104
|
}
|
|
101
|
-
]
|
|
105
|
+
],
|
|
106
|
+
"timeRules": {
|
|
107
|
+
"longWait": { "on": true, "minutes": 10 },
|
|
108
|
+
"idle": { "on": false, "hours": 48 },
|
|
109
|
+
"quietHours": {
|
|
110
|
+
"on": true,
|
|
111
|
+
"from": "22:00",
|
|
112
|
+
"to": "08:00",
|
|
113
|
+
"days": ["mon", "tue", "wed", "thu", "fri"],
|
|
114
|
+
"leaveOutAnswered": false
|
|
115
|
+
}
|
|
116
|
+
},
|
|
117
|
+
"quiet": false
|
|
102
118
|
}
|
|
103
119
|
```
|
|
104
120
|
|
|
121
|
+
`timeRules` are the [time rules](GUIDE.md#time-rules) in force when the snapshot was made, as `GET /api/settings` gives them. Every session's `stale` follows the idle rule, worked out again at each poll whatever its source said, and the dashboard's notifications follow the reminder by them, at the snapshot's `generatedAt`. `quiet` says whether the snapshot was made in quiet hours, by the clock and time zone of the computer Agent Lookout runs on, and the dashboard holds its notifications by it rather than by its own clock. A session on another machine is stale by this computer's idle rule, and its waits are reminded of and held back here by this computer's rules: the `timeRules` and `quiet` in that machine's own snapshot are not read.
|
|
122
|
+
|
|
105
123
|
Sessions come in this order: those that need you first, longest wait first, then working, idle, finished, failed and unknown, each with the most recent change first.
|
|
106
124
|
|
|
107
|
-
| Session field | Holds
|
|
108
|
-
| ----------------- |
|
|
109
|
-
| `id` | Stable across polls: the source, a colon, and the agent's own id for the session
|
|
110
|
-
| `source` | `claude-code`, `codex` or `status-files`
|
|
111
|
-
| `agent` | The agent's own name, for a session from a status file
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `git
|
|
118
|
-
| `git.
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
|
|
132
|
-
|
|
|
133
|
-
|
|
|
134
|
-
|
|
135
|
-
|
|
|
136
|
-
|
|
|
137
|
-
| `
|
|
138
|
-
| `
|
|
139
|
-
| `
|
|
140
|
-
| `
|
|
141
|
-
| `
|
|
125
|
+
| Session field | Holds |
|
|
126
|
+
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
127
|
+
| `id` | Stable across polls: the source, a colon, and the agent's own id for the session. A session on another machine has that machine's own id for it after its source: `remote:devbox:claude-code:…` |
|
|
128
|
+
| `source` | `claude-code`, `codex` or `status-files`, or for a session on another machine `remote:` and the machine's name, such as `remote:devbox` |
|
|
129
|
+
| `agent` | The agent's own name, for a session from a status file, and for a session on another machine, such as `Claude Code`. Left out for the others, whose agent is the source's `label` |
|
|
130
|
+
| `machine` | The other machine it runs on, as `AGENT_LOOKOUT_REMOTES` names it: letters, digits and dashes, such as `devbox`. Left out for a session on this computer. Such a session has no `pid`, `links.open`, `jump`, `stop`, `ask` or `git.pullRequest`, since those act on this computer or are read from its folders |
|
|
131
|
+
| `surface` | `terminal`, `vscode`, `desktop`, `cloud`, `browser` or `unknown` |
|
|
132
|
+
| `name` | What the dashboard calls it |
|
|
133
|
+
| `cwd` | The folder it works in, or `null` |
|
|
134
|
+
| `project` | The last part of `cwd`, or `null` |
|
|
135
|
+
| `git` | `{ branch }`, or `{ commit }` with seven characters when no branch is checked out, each with `repository`. Left out when the folder is in no repository that could be read |
|
|
136
|
+
| `git.repository` | `{ id, name }`: the repository the folder belongs to, the same for its main folder and every worktree of it. `name` is the main folder's name. `id` is 16 hexadecimal characters, a hash of the path of the repository's own git folder, which its worktrees share, for telling repositories apart. Left out for a repository with no name, at the root, or a worktree whose `commondir` cannot be read |
|
|
137
|
+
| `git.pullRequest` | With `AGENT_LOOKOUT_PULL_REQUESTS=on` only, for a branch whose pull request on github.com your own `gh` found: `{ number, title, state, checks, url }`. Described below. Left out with the setting off, for a commit, for the default branch, for a branch named with digits alone, such as `51`, for a repository with no remote on github.com, for a branch with no pull request, and for a session on another machine |
|
|
138
|
+
| `status` | `needs-you`, `working`, `idle`, `finished`, `failed` or `unknown` |
|
|
139
|
+
| `waitingReason` | For `needs-you` only: `permission`, `question` or `other` |
|
|
140
|
+
| `waitingDetail` | The agent's own words for the wait, when it gives any |
|
|
141
|
+
| `waitingText` | For `needs-you` Claude Code sessions only, and sessions on another machine whose Agent Lookout sent it: what the session is asking, in a line or two, read from the last message of its transcript, such as `Run: npm test`, `Edit: src/app.ts` or the question it put. Plain text of at most 200 characters. Left out when the transcript does not say, or with `AGENT_LOOKOUT_WAITING_TEXT=off`. No event in `/api/events`, and no history point, holds it. An email or webhook post holds it only with `AGENT_LOOKOUT_EMAIL_ASKING=on` or `AGENT_LOOKOUT_WEBHOOK_ASKING=on` |
|
|
142
|
+
| `startedAt` | When it started, or `null` |
|
|
143
|
+
| `statusSince` | When its status last changed, or `null`. It does not move while a wait goes on |
|
|
144
|
+
| `lastWriteAt` | When its agent last wrote the file it is read from, for Codex and status files |
|
|
145
|
+
| `pid`, `alive` | Its process and whether that still runs, when known |
|
|
146
|
+
| `links.open` | A `vscode://` address that opens it, for a session in VS Code |
|
|
147
|
+
| `jump` | `{ kind: "tmux", place }` or `{ kind: "terminal", app, place }` when `POST /api/jump` can take you to it |
|
|
148
|
+
| `stop` | `{ how: "signal" }` or `{ how: "background" }` when `POST /api/sessions/stop` can stop it: a Claude Code session in a terminal or VS Code, or a background job. It holds nothing else |
|
|
149
|
+
| `ask` | For `needs-you` Claude Code sessions with the Agent Lookout plugin only, while Agent Lookout holds the session's permission request: `{ requestId, tool, command, description, inputs, allow, denyOnly, subagent, until }`. `command` is the whole command for `Bash`, every line, and `inputs` is `[{ name, value }]`, each input as text, for any other tool or the rest of a command's. `allow` says whether `POST /api/permission/answer` takes `allow`, which it does only when the whole of what is allowed is here: never for `Edit`, `Write`, `MultiEdit` or `NotebookEdit`, and not for `ExitPlanMode` or `AskUserQuestion`, past 4,000 characters or 40 lines, with a character that cannot be shown as it is, with more than two blank lines in a row, or for a command holding right-to-left letters, with `denyOnly` saying why: `edit`, `too-long`, `hidden-characters`, `not-yes-or-no`, `right-to-left` or `blank-lines`. `until` is when the request is let go. Kept in memory only while it is held: no event, history point, email, webhook post or answer of `agent-lookout mcp` holds it |
|
|
150
|
+
| `answered` | `true` for a `needs-you` Claude Code session whose permission request Agent Lookout has answered, from Allow, Deny or a [permission rule](GUIDE.md#permission-rules), or is answering by a rule, while its registry file still says it waits in that wait, as it can for a second or two after the answer, and for 10 seconds after the answer at most. A session on another machine has it when Agent Lookout there sent it, for an answer given there. The wait is over: the dashboard's notifications and Agent Lookout's own, email and the webhook send nothing more for it, no reminder comes, `/api/waits` does not count it as waiting, `/api/history` counts it as working, not as needing you, and the dashboard, the Mac app's Dock badge and menu bar, `agent-lookout status` and the MCP tools count it as working too. Left out otherwise |
|
|
151
|
+
| `stale` | `true` once it has been idle for 24 hours, or for as long as the idle rule in `timeRules` says while it is on. For a session on another machine too, by this computer's rule, whatever that machine said |
|
|
152
|
+
|
|
153
|
+
| Source field | Holds |
|
|
154
|
+
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
155
|
+
| `id`, `label` | `claude-code` and `Claude Code`, `codex` and `Codex`, or `status-files` and `Status files`, or for another machine `remote:devbox` and `devbox` |
|
|
156
|
+
| `state` | `ok`, `searching`, `unavailable`, `not-set-up` or `error` |
|
|
157
|
+
| `detail` | One plain sentence: how it is being read, or what went wrong |
|
|
158
|
+
| `advice` | One plain sentence saying what you can do about a problem, when the collector knows |
|
|
159
|
+
| `watching` | `[{ label, value }]`: what it reads and runs, and how often |
|
|
160
|
+
| `basis` | Which way the sessions were read, for a source that has more than one |
|
|
161
|
+
| `capabilities` | What its agent can report, and whether its sessions can be stopped and answered: for each of nine things, `{ level: "yes" }`, or `{ level: "no" }` or `"partly"` with a `reason` |
|
|
162
|
+
| `checkedAt` | When it was last read |
|
|
163
|
+
| `machine` | For another machine: its name, which its sessions carry as their `machine` |
|
|
164
|
+
| `agents` | For another machine: `[{ label, capabilities }]`, what each agent found there can report, as last read from it, with `jump`, `stop` and `answer` always `no` |
|
|
142
165
|
|
|
143
166
|
The [guide](GUIDE.md#what-each-agent-can-report) has the table `capabilities` holds.
|
|
144
167
|
|
|
168
|
+
Another machine that `AGENT_LOOKOUT_REMOTES` names is a source of its own, after this computer's three. Its `state` is `ok` while its sessions are read, `searching` while ssh signs in the first time, for 10 seconds at most, and `unavailable`, with the reason in `detail` and what to do in `advice`, for anything else: still connecting after those 10 seconds, ssh not found, the machine turned ssh away, the connection dropped, no Agent Lookout answering there, or an answer that cannot be read. A machine that is switched off is no fault of this computer, so it is not `error`. Its `watching` gives the ssh target, the command, the routes asked for, how often, the version there and the state of each source there, the first 20. When `AGENT_LOOKOUT_REMOTES` is set but cannot be read, one source stands for the machines instead: `remote:`, with no name after it, labelled `Other machines`, `not-set-up`, with what is wrong in `detail` and how to correct it in `advice`, and no sessions. Its sessions are listed with this computer's, in the same order, and counted in the same way. [Another machine over SSH](GUIDE.md#another-machine-over-ssh) has the rest.
|
|
169
|
+
|
|
145
170
|
With `AGENT_LOOKOUT_PULL_REQUESTS=on`, a session on a branch that has a pull request carries it in `git`:
|
|
146
171
|
|
|
147
172
|
```json
|
|
@@ -170,10 +195,11 @@ With `AGENT_LOOKOUT_PULL_REQUESTS=on`, a session on a branch that has a pull req
|
|
|
170
195
|
| `url` | Its page, `https://github.com/<owner>/<repository>/pull/<number>`, which the collector builds from the remote and the number rather than take from GitHub |
|
|
171
196
|
|
|
172
197
|
It is what `gh` last said, asked at most once every 2 minutes for each repository and branch, so it can be up to about 2 minutes old. [Pull requests](GUIDE.md#pull-requests) in the guide says when it is asked for.
|
|
198
|
+
`answering` says whether permission prompts can be answered from the dashboard: `{ state, plugin, holdMs, problem }`. `state` is `on` while Agent Lookout listens for the plugin's requests, `off` with `AGENT_LOOKOUT_ANSWER=off`, and `unavailable` when it could not listen or does not, as on Windows, which has no Unix socket for the plugin's hook, with `problem` saying why in one sentence. `plugin` is `seen` once a request has arrived since the last permission prompt it missed, `missed` when a Claude Code session waited for permission and no request arrived, as for a session without the plugin, and `unknown` before either. `holdMs` is how long a request is held.
|
|
173
199
|
|
|
174
200
|
### `GET /api/events?since=<epoch ms>`
|
|
175
201
|
|
|
176
|
-
`{ "events": [...] }`: what changed, newest first, at most 200, and with `since` only those after it. Each event is `{ id, at, sessionId, sessionName, kind, from, to, severity }`, where `kind` is `appeared`, `status-changed`, `ended` or `
|
|
202
|
+
`{ "events": [...] }`: what changed, newest first, at most 200, and with `since` only those after it. Each event is `{ id, at, sessionId, sessionName, kind, from, to, severity }`, where `kind` is `appeared`, `status-changed`, `ended`, `stopped` or `answered`, `from` and `to` are statuses, and `severity` is `advisory`, `warning` for a change to `needs-you` or `critical` for a change to `failed`. A `stopped` event says that Agent Lookout stopped the session, when you pressed Stop or ended the sessions left running: it has `from`, the status the session had, no `to`, and `by: "agent-lookout"`. Its leaving the list is an `ended` event of its own. An `answered` event says that Agent Lookout answered a permission prompt of the session's, when you pressed Allow or Deny, or by a permission rule: it has `from`, `by: "agent-lookout"` and `decision`, `allow` or `deny`, and nothing of what was asked. One a rule gave also has `tool`, the tool's name as Claude Code gave it, and `rule`, `{ tool, command }`, the rule as you wrote it, with `command` only for a Bash rule that names one; its decision is the event's. Neither holds the command the session asked to run. A reader should pass over a `kind` it does not know: later versions may add others. The collector keeps the last 1,000 in memory, and with history kept on disk it reads them back when it starts again.
|
|
177
203
|
|
|
178
204
|
### `GET /api/history?windowMs=<ms>`
|
|
179
205
|
|
|
@@ -302,9 +328,105 @@ Whether Agent Lookout shows each session's [pull request](GUIDE.md#pull-requests
|
|
|
302
328
|
|
|
303
329
|
It never holds a token: `gh` signs in with its own login, which Agent Lookout never reads.
|
|
304
330
|
|
|
331
|
+
### `GET /api/settings`
|
|
332
|
+
|
|
333
|
+
The settings Agent Lookout keeps itself, in a file on this computer, so they hold with no dashboard open: the [time rules](GUIDE.md#time-rules) and the [permission rules](GUIDE.md#permission-rules), with what the permission rules answered since Agent Lookout started. It only reads.
|
|
334
|
+
|
|
335
|
+
```json
|
|
336
|
+
{
|
|
337
|
+
"timeRules": {
|
|
338
|
+
"longWait": { "on": true, "minutes": 10 },
|
|
339
|
+
"idle": { "on": true, "hours": 48 },
|
|
340
|
+
"quietHours": {
|
|
341
|
+
"on": true,
|
|
342
|
+
"from": "22:00",
|
|
343
|
+
"to": "08:00",
|
|
344
|
+
"days": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"],
|
|
345
|
+
"leaveOutAnswered": false
|
|
346
|
+
}
|
|
347
|
+
},
|
|
348
|
+
"file": "~/.agent-lookout/settings.json",
|
|
349
|
+
"problem": null,
|
|
350
|
+
"permissionRules": [
|
|
351
|
+
{ "id": "3f9c2a71b0de", "decision": "deny", "tool": "Bash", "command": "git push --force:*" },
|
|
352
|
+
{ "id": "8a41d07e6c2b", "decision": "allow", "tool": "Bash", "command": "npm test:*" },
|
|
353
|
+
{ "id": "c5e0b9124fa3", "decision": "allow", "tool": "WebFetch" }
|
|
354
|
+
],
|
|
355
|
+
"permissionRulesProblem": null,
|
|
356
|
+
"ruleAnswers": [
|
|
357
|
+
{
|
|
358
|
+
"at": 1791331869617,
|
|
359
|
+
"sessionId": "claude-code:00000000-0000-4000-8000-000000000001",
|
|
360
|
+
"sessionName": "checkout-flow",
|
|
361
|
+
"tool": "Bash",
|
|
362
|
+
"decision": "allow",
|
|
363
|
+
"rule": { "decision": "allow", "tool": "Bash", "command": "npm test:*" }
|
|
364
|
+
}
|
|
365
|
+
],
|
|
366
|
+
"ruleAnswersSince": 1791328269617
|
|
367
|
+
}
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
| Field | Holds |
|
|
371
|
+
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
372
|
+
| `timeRules.longWait` | The long wait reminder: `on`, and `minutes`, a whole number from 1 to 1,440, how long a wait lasts before it is reminded of. 10 unless set |
|
|
373
|
+
| `timeRules.idle` | The idle rule: `on`, and `hours`, a whole number from 1 to 720, how long a session is idle before it is stale. 48 unless set. While it is off a session is stale after 24 hours |
|
|
374
|
+
| `timeRules.quietHours` | Quiet hours: `on`, `from` and `to` on the 24-hour clock as `HH:MM`, two different times, which run past midnight when `to` is the earlier, and `days`, the days they begin on, any of `mon` to `sun`. 22:00 to 08:00 every day unless set |
|
|
375
|
+
| `quietHours.leaveOutAnswered` | Whether the summary sent when quiet hours end leaves out the waits that were answered while they held |
|
|
376
|
+
| `file` | The file they are kept in, `~/.agent-lookout/settings.json` or the one `AGENT_LOOKOUT_SETTINGS_FILE` names, with your home folder written `~` |
|
|
377
|
+
| `problem` | While the file could not be read when Agent Lookout started, or the last change could not be saved: one sentence that says why and names the file. `null` otherwise |
|
|
378
|
+
| `permissionRules` | The permission rules in force, in their order, each `{ id, decision, tool, command }`: `decision` `allow`, `ask` or `deny`, `tool` a tool's name as Claude Code writes it or `*` for every tool, and `command` only for a Bash rule that names one, exactly, `npm test`, or as a prefix, `npm test:*`. 100 at most. Empty is none |
|
|
379
|
+
| `permissionRulesProblem` | While the permission rules in the file could not be read whole, which leaves none in force, or the last change to them could not be saved: one sentence that says so. `null` otherwise |
|
|
380
|
+
| `ruleAnswers` | The requests the permission rules answered since Agent Lookout started, newest first, 100 at most, each `{ at, sessionId, sessionName, tool, decision, rule }`, with `rule` as it read then. Never the command the session asked to run |
|
|
381
|
+
| `ruleAnswersSince` | When Agent Lookout started, which is where `ruleAnswers` begins |
|
|
382
|
+
|
|
383
|
+
Every time rule is off until you turn it on, and there is no permission rule until you add one. A time rule the file holds in a form that cannot be read is off, and `problem` names it. Permission rules are read whole or not at all: a list that cannot be read whole is none in force, so an allow rule never answers what an ask rule beside it, unread, would have held back.
|
|
384
|
+
|
|
385
|
+
### `POST /api/settings/time-rules`
|
|
386
|
+
|
|
387
|
+
A route that acts. It puts the time rules in force and saves them in the settings file, as the Time rules card in Settings does. It makes the same checks as `POST /api/jump`, with its own action, in `src/collector/settings/timeRulesRoute.ts`, and answers only a request that:
|
|
388
|
+
|
|
389
|
+
- is a `POST`. Any other method gets 405, with `Allow: POST`.
|
|
390
|
+
- has an `Origin` that names this computer, or gets 403.
|
|
391
|
+
- is marked `same-origin` in `Sec-Fetch-Site`, when that header is sent, or gets 403.
|
|
392
|
+
- carries `X-Agent-Lookout-Action: time-rules`, or gets 403.
|
|
393
|
+
- has `Content-Type: application/json`, or gets 415.
|
|
394
|
+
- has a body of 2,048 bytes or less, or gets 413, that is exactly the three rules, `longWait`, `idle` and `quietHours`, each whole, with exactly the fields `GET /api/settings` gives and every value in range, or gets 400.
|
|
395
|
+
|
|
396
|
+
The rules are in force once they are saved, and not before: the file is written whole, with mode 600, in a folder made with mode 700, and never through a link. Nothing in the request names a file.
|
|
397
|
+
|
|
398
|
+
| Status | Body |
|
|
399
|
+
| ------ | ------------------------------------------------------------------------------------------------------- |
|
|
400
|
+
| 200 | `{ "ok": true, "timeRules": { ... } }`: the rules now in force |
|
|
401
|
+
| 400 | `reason: "invalid"`, with an `error` sentence that says what the body must be |
|
|
402
|
+
| 500 | `reason: "not-saved"`: the file could not be read or written, as when it is a link, and nothing changed |
|
|
403
|
+
|
|
404
|
+
### `POST /api/settings/permission-rules`
|
|
405
|
+
|
|
406
|
+
A route that acts. It makes one change to the permission rules and saves the list in the settings file, as the Permission rules card in Settings does. It makes the same checks as `POST /api/jump`, with `X-Agent-Lookout-Action: permission-rules`, in `src/collector/settings/permissionRulesRoute.ts`, and takes a body of 1,024 bytes or less that is exactly one of:
|
|
407
|
+
|
|
408
|
+
```text
|
|
409
|
+
{ "add": { "decision": "allow", "tool": "Bash", "command": "npm test:*" } }
|
|
410
|
+
{ "edit": { "id": "8a41d07e6c2b", "decision": "ask", "tool": "Bash", "command": "npm test:*" } }
|
|
411
|
+
{ "move": { "id": "8a41d07e6c2b", "to": "up" } }
|
|
412
|
+
{ "remove": { "id": "8a41d07e6c2b" } }
|
|
413
|
+
```
|
|
414
|
+
|
|
415
|
+
A new rule goes to the end of the list, with an ID the server makes. A move at either end of the list changes nothing. The change is made to the list the settings file holds, read again just before, so one saved by another copy of Agent Lookout is kept. The server checks the rule itself, whatever the page checked, by `ruleProblem` in `src/core/permission-rules/permissionRules.ts`: a tool's name of letters, digits, `_` and `-` starting with a letter, or `*`; a command for Bash alone, in plain ASCII with one space between words, with no `;`, `&`, `|`, `<`, `>`, parentheses, quotes, backslashes, `$`, braces, and no `*` but a final `:*`; a command that begins with the program's name, not a variable set before it; and an allow rule that names one tool, never an MCP server alone such as `mcp__docs`, for Bash a command, and never `Edit`, `Write`, `MultiEdit`, `NotebookEdit`, `ExitPlanMode` or `AskUserQuestion`, whose command is one plain command that does not begin with a program that runs another, such as `sudo`, `env`, `xargs` or a shell (`COMMAND_RUNNERS` in `src/core/permission-rules/commandWords.ts`), or with one that sends requests or runs the code it is given, such as `curl`, `wget`, `nc`, `ssh`, `node`, `python` or `awk` (`NETWORK_CLIENTS_AND_INTERPRETERS` in the same file). The rules are in force once they are saved, and not before. Nothing in the request names a file.
|
|
416
|
+
|
|
417
|
+
| Status | Body |
|
|
418
|
+
| ------ | --------------------------------------------------------------------------------------------------------- |
|
|
419
|
+
| 200 | `{ "ok": true, "permissionRules": [ ... ] }`: the rules now in force |
|
|
420
|
+
| 400 | `reason: "invalid"`, with an `error` sentence that says what the body or the rule must be |
|
|
421
|
+
| 404 | `reason: "no-rule"`: no rule has that ID, as when another tab or another copy of Agent Lookout removed it |
|
|
422
|
+
| 409 | `reason: "full"`, the list holds 100 rules, or `reason: "duplicate"`, it holds that rule already |
|
|
423
|
+
| 500 | `reason: "not-saved"`: the file could not be read or written, and nothing changed |
|
|
424
|
+
|
|
425
|
+
A held permission request is put to the rules as its session's registry file confirms its wait, and a deny or an allow rule answers it through the same path as `POST /api/permission/answer`, below, with every check it makes. [Permission rules](GUIDE.md#permission-rules) says what each rule matches.
|
|
426
|
+
|
|
305
427
|
### `POST /api/jump`
|
|
306
428
|
|
|
307
|
-
One of the
|
|
429
|
+
One of the seven routes that act. It selects the tmux pane a session runs in, or brings its tab of Terminal or iTerm2 to the front, as the Jump button does. Its checks, on top of the ones every request passes, are `jumpRefusalFor` in `src/collector/jumpRoute.ts`, which makes those `actionRefusalFor` in `src/collector/handler.ts` makes for every route that acts. It answers only a request that:
|
|
308
430
|
|
|
309
431
|
- is a `POST`. Any other method gets 405, with `Allow: POST`.
|
|
310
432
|
- has an `Origin` that names this computer. A request with no `Origin` gets 403 here, though a read may go without one.
|
|
@@ -359,7 +481,7 @@ A route that acts. It ends one Claude Code session's process, as Stop session do
|
|
|
359
481
|
- has `Content-Type: application/json`, or gets 415.
|
|
360
482
|
- has a body of 1,024 bytes or less, or gets 413, that is exactly `{ "sessionId": "..." }`, or gets 400.
|
|
361
483
|
|
|
362
|
-
The server looks the session up in its own latest snapshot, and stops only one with a `stop` field, by what it found for it itself: its process, or its background job. Before it acts it reads the session's registry file again, which must still name that session, that process, the same kind, `interactive` or `bg`, and the same start time, and asks `ps` for the process's start time again, which must be the same, to the second. It never stops process 1, its own process, the one it was started from or any process above that. Then it sends SIGTERM, and waits up to 10 seconds for the process to end
|
|
484
|
+
The server looks the session up in its own latest snapshot, and stops only one with a `stop` field, by what it found for it itself: its process, or its background job. Before it acts it reads the session's registry file again, which must still name that session, that process, the same kind, `interactive` or `bg`, and the same start time, and asks `ps` for the process's start time again, which must be the same, to the second. It never stops process 1, its own process, the one it was started from or any process above that. Then it sends SIGTERM, or runs `claude stop` with the job's ID, and waits up to 10 seconds for the process to end. Nothing in the request reaches a signal or a command. A stop adds a `stopped` event, and the server reads the sessions again before it answers. It makes one stop a second, and one at a time, with the clean-up's.
|
|
363
485
|
|
|
364
486
|
| Status | Body |
|
|
365
487
|
| ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -372,7 +494,7 @@ The server looks the session up in its own latest snapshot, and stops only one w
|
|
|
372
494
|
| 429 | `reason: "too-soon"`, with `Retry-After: 1` |
|
|
373
495
|
| 500 | `reason: "failed"`: the signal could not be sent, or `claude stop` failed |
|
|
374
496
|
|
|
375
|
-
Each of these has an `error` sentence beside its `reason`. With `AGENT_LOOKOUT_STOP=off
|
|
497
|
+
Each of these has an `error` sentence beside its `reason`. With `AGENT_LOOKOUT_STOP=off`, or on Windows, there is no such route, and a POST to it gets 405. Windows has no `ps` to confirm a process's start time and no POSIX signal to send, so no session there has a `stop` field.
|
|
376
498
|
|
|
377
499
|
### `POST /api/sessions/clean-up`
|
|
378
500
|
|
|
@@ -389,7 +511,7 @@ A route that acts. It ends the sessions left running that you chose, as End does
|
|
|
389
511
|
}
|
|
390
512
|
```
|
|
391
513
|
|
|
392
|
-
with 1 to 20 sessions, none named twice, each with the `statusSince` the page showed for it. Anything else gets 400. For each session in turn the server makes every check of `POST /api/sessions/stop`, and then reads in the session's registry file, and in its own latest list of sessions, that it is still idle, since that same `statusSince`, and that this was 24 hours or more ago. A session that has done anything since is left running. Then it stops each one that passed, as the stop route does, and waits up to 10 seconds for them all.
|
|
514
|
+
with 1 to 20 sessions, none named twice, each with the `statusSince` the page showed for it. Anything else gets 400. For each session in turn the server makes every check of `POST /api/sessions/stop`, and then reads in the session's registry file, and in its own latest list of sessions, that it is still idle, since that same `statusSince`, and that this was 24 hours or more ago, or as long ago as the idle rule says while it is on. A session that has done anything since is left running. Then it stops each one that passed, as the stop route does, and waits up to 10 seconds for them all.
|
|
393
515
|
|
|
394
516
|
```json
|
|
395
517
|
{
|
|
@@ -400,7 +522,33 @@ with 1 to 20 sessions, none named twice, each with the `statusSince` the page sh
|
|
|
400
522
|
}
|
|
401
523
|
```
|
|
402
524
|
|
|
403
|
-
The answer is 200 with an `outcome` for each session asked for, in order: `ended`, `became-active`, `not-stale`, `gone`, `unsupported`, `cannot-confirm`, `not-allowed`, `still-running` or `failed`, which mean what the stop route's reasons do. One `stopped` event is added for each session ended. A clean-up while a stop or another clean-up is under way, or less than a second after one began, gets 429 with `reason: "too-soon"`.
|
|
525
|
+
The answer is 200 with an `outcome` for each session asked for, in order: `ended`, `became-active`, `not-stale`, `gone`, `unsupported`, `cannot-confirm`, `not-allowed`, `still-running` or `failed`, which mean what the stop route's reasons do. One `stopped` event is added for each session ended. A clean-up while a stop or another clean-up is under way, or less than a second after one began, gets 429 with `reason: "too-soon"`. With `AGENT_LOOKOUT_STOP=off`, or on Windows, there is no such route either, and a POST to it gets 405.
|
|
526
|
+
|
|
527
|
+
### `POST /api/permission/answer`
|
|
528
|
+
|
|
529
|
+
A route that acts. It answers one permission prompt of a Claude Code session, as Allow and Deny do in Needs you and in the session's details. It makes the same checks as `POST /api/jump`, with `X-Agent-Lookout-Action: answer`, in `src/collector/answers/answerRoute.ts`, and takes a body of 1,024 bytes or less that is exactly:
|
|
530
|
+
|
|
531
|
+
```json
|
|
532
|
+
{
|
|
533
|
+
"sessionId": "claude-code:00000000-0000-4000-8000-000000000001",
|
|
534
|
+
"requestId": "0123456789abcdef0123456789abcdef",
|
|
535
|
+
"decision": "allow"
|
|
536
|
+
}
|
|
537
|
+
```
|
|
538
|
+
|
|
539
|
+
with `decision` `allow` or `deny`, and `requestId` the one the session's `ask` gave. Anything else gets 400. The server answers only a request it holds for that session under that ID, `allow` only when `ask.allow` is `true`, and only after it has read the session's registry file again and found it still says the session is waiting. It then hands the plugin's hook one of two fixed answers, allow, or deny with a sentence that says the person denied it from Agent Lookout, and never a rewritten input or a permission rule. An answer adds an `answered` event, and the server reads the sessions again before it replies, so a `GET /api/sessions` sent once the reply has come finds the session gone on, or `answered`.
|
|
540
|
+
|
|
541
|
+
| Status | Body |
|
|
542
|
+
| ------ | -------------------------------------------------------------------------------------------------------- |
|
|
543
|
+
| 200 | `{ "ok": true, "decision": "allow" }`: the answer was handed to the session |
|
|
544
|
+
| 404 | `reason: "no-ask"`: no such request is held, or the session is not listed |
|
|
545
|
+
| 409 | `reason: "not-allowable"`: `allow` for a request that offers only Deny |
|
|
546
|
+
| 409 | `reason: "gone"`: the session was answered there, is no longer waiting, or the request was held too long |
|
|
547
|
+
| 429 | `reason: "too-soon"`: that request is being answered |
|
|
548
|
+
|
|
549
|
+
Each of these has an `error` sentence beside its `reason`. With `AGENT_LOOKOUT_ANSWER=off`, on Windows, or with an `AGENT_LOOKOUT_ANSWER_WAIT` it cannot read, `AGENT_LOOKOUT_CLAUDE_HOME` set without `AGENT_LOOKOUT_ANSWER_SOCKET`, or a socket path too long for a socket, there is no such route, and a POST to it gets 405. When the socket could not be opened as Agent Lookout started, as in a folder other users can open that it did not make, with something other than a socket at its path, or while another copy of Agent Lookout listens on it, nothing is held, and a POST that passes the checks above gets the same 405.
|
|
550
|
+
|
|
551
|
+
The plugin's hook reaches Agent Lookout another way, not through this API: a Unix socket, `~/.agent-lookout/answer.sock` unless `AGENT_LOOKOUT_ANSWER_SOCKET` names another, of mode 600 in a folder of mode 700. It takes `POST /hooks/permission-request` with `X-Agent-Lookout-Hook: permission-request` and the hook's input as a JSON body of 1 MiB or less, holds it, and answers it with the decision JSON when you press Allow or Deny or a permission rule decides it, or with an empty 200 when the request is let go. [Answer a permission prompt](GUIDE.md#answer-a-permission-prompt) says when that is.
|
|
404
552
|
|
|
405
553
|
## In the Mac app only
|
|
406
554
|
|
|
@@ -429,6 +577,8 @@ The API has no token or password. The `Host` and `Origin` rules keep websites, a
|
|
|
429
577
|
|
|
430
578
|
A token would not keep out programs running as you, which could read it as easily as the API. It could keep out other accounts on a shared computer, stopping your sessions included, the known limit above, and is left for a later version. The MCP server changes none of this: it opens no port of its own, speaks to the app that started it over stdin and stdout, and reads the same loopback API the dashboard and `agent-lookout status` read without one. A token is also for an API that can be reached some other way, such as from another computer, and Agent Lookout has none.
|
|
431
579
|
|
|
580
|
+
Another computer reads it only through SSH: with `AGENT_LOOKOUT_REMOTES` set there, Agent Lookout on that computer runs `ssh` to this one and forwards a port of its own loopback to this one's `127.0.0.1:4777`. Its requests then arrive on this computer's loopback, from the ssh server, which only someone who can sign in to this computer can open. It asks for `GET /api/health` and `GET /api/sessions`, with no `Origin` and no notifications header, and nothing else. [Another machine over SSH](GUIDE.md#another-machine-over-ssh) describes it.
|
|
581
|
+
|
|
432
582
|
## The MCP server
|
|
433
583
|
|
|
434
584
|
`agent-lookout mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server for an agent that keeps track of your other agents. The agent's app starts it and speaks to it over stdin and stdout. For each tool call it reads `GET /api/sessions` once, exactly as `agent-lookout status` does: from a loopback address only, with no `Origin` and no notifications header. It has three tools, and none of them acts:
|