Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -621,6 +621,7 @@ Exit codes: 0 ok, 3 nothing live, 64 usage, 65 a vocabulary term fails validatio
| `GET /calls/{id\|live\|last}` | Header, parts, roster, health, final state. `live` gives 404 `no_live_call {last}` when nothing is recording |
| `PATCH /calls/{id\|live\|last}` `{title?, workspace?}` | Renames the call at any time with a `call.renamed` event, and an export akou wrote takes the new name; 422 on an empty title, and the old name stays. `workspace` moves a finished call's folder into that workspace and writes `call.moved`; 409 `live_call` while it records |
| `DELETE /calls/{id}` · `POST /calls/{id}/restore` | Moves a finished call to `.trash/<workspace>/` under the recordings folder, out of every list, deleted for good at the first start after 30 days; 409 `live_call` while it records. Restore brings it back to its workspace unchanged |
| `GET /trash` · `DELETE /trash` | The calls in the trash, newest first; Empty trash deletes every one for good at once, through the same purge as the start, and touches nothing outside `.trash/` |
| `PATCH /calls/{id}/segments/{sid}` `{spk}` | Who spoke one line: `seg rev+1` with the new `spk` and `by`; the text, its raw form and every earlier revision stay. 422 for a microphone line. The words of a line are fixed with `POST /calls/{id}/fix` |
| `POST /calls/{id}/{stop,pause,resume,mute,unmute,restart}` | Controls. `restart` takes `{force}` |
| `GET /calls/{id}/events?after=SEQ&wait=25` | Raw log, long-poll |
Expand Down
1 change: 1 addition & 0 deletions docs/TRAPS.md
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,7 @@ Every number here comes from our vocabulary measurements: a synthetic TTS set an
- **What macOS WebKit does differently with buttons and an early pause** [WK-3] (M1). Given macOS WebKit never focuses a button on a click, and moves Tab only between text fields unless the user turned on Keyboard navigation (Option+Tab reaches buttons either way), a test must not take a click to leave focus on the button it clicked; it puts the focus there itself. Given that in its first few hundred ms of playback macOS WebKit reports a position ahead of what it has played, and a pause there drops the position back to it (as far as 0), a test of pause and resume lets the line play past its first second first. Neither is an akou bug. Test: the W5.2 Space test and the W5.6 PageUp test; the `ui (webkit, macOS)` job runs the player bar tests in macOS WebKit.
- **A redraw that drops the selection** [W4.9, CI flake] (M1). Given a line on screen is drawn again with the same text, setting its `.text` element's `textContent` anyway replaces the text node, and a selection inside it goes with it. The stream sends the app's `read` for the corrected lines on its own 250 ms tick, so after a fix (or any vocabulary change) both lines it corrected are redrawn about 150 ms later, whatever the user is doing. A double-click whose second press lands before that redraw and whose release lands after it selects nothing: WebKit fires no `dblclick` and Chromium fires one with an empty selection, so the fix never opens. That failed `tests/ui/fix-word.test.ts` three times in about 290 `ui (webkit)` runs from 2026-10-24 to 2026-10-31, each time as `waitForSelector('#popover .fix-learned')` timing out on a double-click made within a second of a fix; the Mac never showed it (0 in 120 runs). `fillRow` sets the text only when it changed. Test: `[W4.9] a line the stream redraws mid double-click keeps the word, and the fix still opens` holds the second press while a word is added to the vocabulary file, waits for the `read` it sends, and checks that the same text node is still there and the fix opens with the word selected; the positive control replaces the text node during the press, as the old redraw did, and nothing opens.
- **An Undo the next message takes away** [W13.3] (M1). Given the window had one `#toast` element and every message rewrote it, a second Move to Trash, a copy or an error within 10 s of a Move to Trash removed that call's Undo button long before its 10 s were up; the window has no Trash page yet, so the call could then come back only through the API or the file manager. A fix's Undo (W4.8) went the same way. akou must move an Undo that a newer message would replace into `#toast-held`, where it stays for what is left of its own 10 s and still works, and must not bring back an Undo whose time is up. Test: `[W13.3] a second toast inside the Undo's 10 s moves the first Undo aside` in `tests/ui/call-menu.test.ts` trashes two calls and restores the first from the held Undo, then the second from its own; the single rewritten `#toast` is the positive control and finds no held Undo.
- **A trash that frees no space** [TRASH-1] (M1). Given a call moved to the Trash only goes to `.trash/` under the recordings folder, which Finder hides, and the purge ran only at the start of akou for calls trashed 30 days before, deleting calls to free a full disk freed nothing, and an app that ran for weeks kept even older ones. akou must offer Empty trash on every door: `DELETE /trash` (with `GET /trash` to count what is there), `akou calls empty-trash` (it asks on a terminal and needs `--yes` elsewhere) and Empty Trash… in a call row's menu, which asks first, naming how many calls go and that it cannot be undone. Only the calls the question counted go: the window and the CLI send `upTo`, the newest `trashedAt` of the `GET /trash` they asked about, so a call trashed while the question is open stays, with its Undo. It runs the same purge the start runs, with no age limit, and touches only folders under `.trash/`. Test: `tests/empty-trash.e2e.test.ts` `[TRASH-1]` trashes calls (one today, one 10 days before) and empties them over the API and the CLI; the call never trashed stays listed with its folder byte for byte, a live call stays recording, and the trashed folders are on disk before the empty as the positive control; a call trashed after the `GET /trash` stays through `DELETE /trash?upTo=` and through the CLI's question, and goes with a bare `DELETE /trash` as the positive control. `tests/ui/call-menu.test.ts` `[TRASH-1]` asks, keeps the calls on Dismiss, and on Empty Trash deletes only them, not a call trashed while the question was open.

## Kept from closed traps, as invariants

Expand Down
102 changes: 101 additions & 1 deletion docs/api/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,9 @@
{
"name": "segments"
},
{
"name": "trash"
},
{
"name": "devices"
},
Expand Down Expand Up @@ -1432,7 +1435,7 @@
"tags": [
"calls"
],
"description": "Move a finished call to the trash: its folder goes to `.trash/` under the recordings folder, no list shows it, and it is deleted for good after 30 days. A call that is recording answers 409 `live_call`. Exports already written are the user's and stay. `POST /calls/{id}/restore` brings it back.",
"description": "Move a finished call to the trash: its folder goes to `.trash/` under the recordings folder, no list shows it, and it is deleted for good at the first start of akou after 30 days, or at once by `DELETE /trash`. A call that is recording answers 409 `live_call`. Exports already written are the user's and stay. `POST /calls/{id}/restore` brings it back.",
"parameters": [
{
"name": "id",
Expand Down Expand Up @@ -1655,6 +1658,103 @@
"x-akou-access": "admin"
}
},
"/v1/trash": {
"get": {
"operationId": "trash.list",
"tags": [
"trash"
],
"description": "The calls in the trash, newest first: each one's `id`, the `workspace` it came from and `trashedAt` (ms). `POST /calls/{id}/restore` brings one back; `DELETE /trash` deletes them all for good.",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"401": {
"$ref": "#/components/responses/401.unauthorized"
},
"403": {
"$ref": "#/components/responses/403.bad_host.browser_request.forbidden"
},
"413": {
"$ref": "#/components/responses/413.body_too_large"
},
"500": {
"$ref": "#/components/responses/500.internal"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"x-akou-modes": [
"app"
],
"x-akou-access": "admin"
},
"delete": {
"operationId": "trash.empty",
"tags": [
"trash"
],
"description": "Empty the trash: every call in it is deleted for good now, folder and audio, instead of 30 days after it was trashed. This cannot be undone. Calls that are not in the trash are never touched, and exports already written stay. With `upTo`, only the calls trashed at that time or before go, so a client that asked about the calls of a `GET /trash` deletes only those. Answers how many calls were deleted.",
"parameters": [
{
"name": "upTo",
"in": "query",
"required": false,
"description": "Delete only the calls trashed at this time (ms) or before: the newest `trashedAt` of the `GET /trash` the user was asked about. Default: all of them.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/400.bad_param"
},
"401": {
"$ref": "#/components/responses/401.unauthorized"
},
"403": {
"$ref": "#/components/responses/403.bad_host.browser_request.forbidden"
},
"413": {
"$ref": "#/components/responses/413.body_too_large"
},
"415": {
"$ref": "#/components/responses/415.json_required"
},
"500": {
"$ref": "#/components/responses/500.internal"
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"x-akou-modes": [
"app"
],
"x-akou-access": "admin"
}
},
"/v1/calls/{id}/stop": {
"post": {
"operationId": "calls.stop",
Expand Down
9 changes: 7 additions & 2 deletions docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,20 +161,24 @@ example: akou open last
## calls

```text
akou calls: List calls by date, title and duration (no content search), or rename one
akou calls: List calls by date, title and duration (no content search), rename one, or empty the trash

usage: akou calls [-w WORKSPACE] [--limit N] [--failed] [--json] | akou calls rename CALL TITLE… [--json]
usage: akou calls [-w WORKSPACE] [--limit N] [--failed] [--json] | akou calls rename CALL TITLE… [--json] | akou calls empty-trash [--yes] [--json]

-w, --workspace WS only calls in this workspace
--limit N at most N calls, newest first
--failed only calls whose start failed (nothing was recorded), instead of the others
-c, --call CALL live, last or a call id (default: none; name one)
--yes with empty-trash: delete without asking (needed when stdin is not a terminal)
--json print the answer as JSON, errors included
-h, --help show this help
--restart if akou takes the connection and never answers, restart it first, even for a command that only reads

calls empty-trash deletes every call in the trash for good, now, instead of 30 days after it was trashed; it cannot be undone. On a terminal it asks first; elsewhere it needs --yes.

example: akou calls -w work --limit 5
example: akou calls rename last Weekly sync
example: akou calls empty-trash --yes
```

## workspaces
Expand Down Expand Up @@ -940,6 +944,7 @@ example: akou serve
| List calls | `calls` | `GET /calls` | `akou_list_calls` | `src/ui/app.ts` |
| Rename a call | `calls` | `PATCH /calls/:id` | `akou_rename_call` | `src/ui/app.ts` |
| Trash and restore a call | none: missing: CLI-26 adds calls delete and calls restore | `DELETE /calls/:id`, `POST /calls/:id/restore` | none: missing: PG-M4 names move, delete and restore (CLI.md doors table) | `src/ui/app.ts` |
| Empty the trash: delete trashed calls for good, now | `calls` | `GET /trash`, `DELETE /trash` | none: deleting calls for good is the user's, behind a confirmation; PG-M4 names no tool for it | `src/ui/app.ts` |
| Change who spoke one line | none: missing: CLI-29 adds edit SEG --speaker | `PATCH /calls/:id/segments/:sid` | none: no tool yet, and no design item names one | none: missing: W4.10 adds the speaker picker on a line |
| List and add workspaces | `workspaces`, `workspace` | `GET /workspaces`, `POST /workspaces` | none: not one call's: akou_start names the workspace and makes its folder, and akou_list_calls shows each call's | `src/ui/workspaces.ts` |
| Share a live link | `share` | `GET /share`, `POST /share`, `DELETE /share` | `akou_share_on`, `akou_share_off`, `akou_share_status` | `src/ui/app.ts` |
Expand Down
2 changes: 1 addition & 1 deletion docs/ux/CLI.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ The tree stays flat: one verb per action, with subcommands only where a noun has
| During the call | `name SPK NAME` · `name --merge A B` · `name --unmerge SPK` · `note "TEXT"` · `note --edit ID "TEXT"` · `note --del ID` · `remember "TEXT"` · `remember --del ID` · `mark [LABEL]` **new** (CLI-34) | has, except `mark` |
| Vocabulary | `vocab list\|add\|fix\|remove\|approve\|reject\|suggest\|check\|import\|pass` | has |
| After the call | `enhance [--template T]` · `finalize [CALL] [--force] [--engine E]` · `export [CALL] [--to DIR]` · `hooks run CALL [--stage S]` · `hooks test` **new** (PG-H2) · `show CALL [--layer best\|live\|final] [--format md\|json\|txt]` | has, except `--engine` (TRN-16) and `hooks test` |
| Calls | `calls [-w WS] [--limit N] [--failed]` · `calls rename CALL TITLE…` · `calls move\|delete\|restore CALL …` **new** (CLI-26) · `workspaces` · `workspace add NAME` · `import hark-viewer DIR… [-w WS]` | has, except `move`, `delete` and `restore` |
| Calls | `calls [-w WS] [--limit N] [--failed]` · `calls rename CALL TITLE…` · `calls empty-trash [--yes]` · `calls move\|delete\|restore CALL …` **new** (CLI-26) · `workspaces` · `workspace add NAME` · `import hark-viewer DIR… [-w WS]` | has, except `move`, `delete` and `restore` |
| Share | `share on\|off\|status [-c CALL] [--bind tailnet\|lan\|IP] [--notes] [--expires 3h]` | has |
| Setup | `config show\|get\|set\|unset\|path` · `models list\|pull [PRESET\|MODEL]\|delete MODEL\|import\|select` (`pull` and `import` need no running app, SV-P3; `delete` asks the running akou, which refuses the default model and one in use) · `devices` · `apps` · `templates list\|show` (PG-F3) · `token path\|rotate` · `doctor [--grant] [--capture-test]` · `demo [--clean]` **new** (SET-10) · `completion SHELL` **new** (CLI-08) | partial: `devices` and `apps` exit 69 "not built"; no `get`, `path`, `models select` (SET-06), `doctor --capture-test` (DK-O1), `demo`, `completion` |
| Dictation | `dictate FILE [--engine E] [--language L]` **new** (DICTATION.md DC-G3: a clip through the dictation path) · `dictate start\|stop\|toggle\|cancel` · `dictations list\|show\|retry\|delete` **new** (DC-G3) | has every command in this row ([dictate.ts](../../src/main/cli/commands/dictate.ts)) |
Expand Down
2 changes: 1 addition & 1 deletion docs/ux/WINDOW.md
Original file line number Diff line number Diff line change
Expand Up @@ -402,7 +402,7 @@ The sidebar is the window's left column, the full height of the window: the word
|---|---|---|---|---|---|
| W13.1 | The sidebar's calls: grouped by workspace, each group folding with the mouse or the keyboard and showing its count; newest first inside a group, the live call on top with a red dot, the group with the newest call first; each row the title and a line with the day (Today, Yesterday, the weekday within a week, then the date), the local start time and how long it ran ("live", "failed"); a search that narrows the list by title or workspace as you type, never by what was said, and Escape or clearing it brings every group back; switch without reload | done | DESIGN 7; design-explorations | `tests/ui/parity.test.ts` "Sidebar list of calls by workspace and day…", with a positive control on the search; `tests/ui-model.test.ts` "the calls list" | has |
| W13.2 | Rename a call and move it to another workspace | P1 | Audit: no rename anywhere | Rename goes through PG-A4 and writes a `call.renamed` event (W3.16); moving a call to another workspace moves its folder; the export file is found again by `akou_id` and renamed on the next export | partial: rename (W3.16) and move from a call row's menu (right-click, `Shift+F10` or the Menu key: Rename…, Move to workspace…), `tests/ui/call-menu.test.ts` "[W13.2]"; the export's new file name missing |
| W13.3 | Delete a call to the Trash, restore from it, empty it now | P1 | Granola, Minutes; audit: no delete in any surface | Delete follows PG-A4 (refused for a live call, folder moved to `trash/`, purged after 30 days); the call leaves the list; Restore brings it back intact; "Empty trash now" asks for confirmation. Exports already written are the user's and are not touched | partial: Move to Trash from a call row's menu ([dark](design-explorations/built/calls-row-menu-dark.png)), the row gone at once and Undo for 10 s (`POST /calls/{id}/restore`); a recording call's item stays, greyed with the reason; the sidebar selects no text and never shows the webview's own menu, `tests/ui/call-menu.test.ts` "[W13.3]". A Trash page to restore from later and "Empty trash now" are missing: the API has no list of the trash and no empty |
| W13.3 | Delete a call to the Trash, restore from it, empty it now | P1 | Granola, Minutes; audit: no delete in any surface | Delete follows PG-A4 (refused for a live call, folder moved to `trash/`, purged after 30 days); the call leaves the list; Restore brings it back intact; "Empty trash now" asks for confirmation. Exports already written are the user's and are not touched | partial: Move to Trash from a call row's menu ([dark](design-explorations/built/calls-row-menu-dark.png)), the row gone at once and Undo for 10 s (`POST /calls/{id}/restore`); a recording call's item stays, greyed with the reason; the sidebar selects no text and never shows the webview's own menu, `tests/ui/call-menu.test.ts` "[W13.3]". Empty Trash… in the same menu asks first, naming how many calls go and that it cannot be undone, then deletes them for good (`GET /trash`, `DELETE /trash`), `tests/ui/call-menu.test.ts` "[TRASH-1]". A Trash page to restore from later is missing |
| W13.4 | Suggested title for a call started without one, applied only on the user's yes | P2 | heed | After the final pass, an untitled call shows "Title: Budget review? Use it" | missing |
| W13.6 | Open on a workspace: `akou open -w WS`, `POST /window {workspace}` and the page's `?workspace=` put that workspace first in the picker, even before any call is filed under it | P2 | hark-viewer `?workspace=` (carried) | Opening with `?workspace=ops` on an empty home shows "ops" selected in the picker; Record starts a call in it | missing |
| W13.7 | The main panes (the calls list, the transcript, the notes) share one scrollbar: thin, hidden at rest, shown on hover or while scrolled by hand, then it fades; its gutter is always kept, so the calls never narrow when the list starts to scroll and line up with the rows under it ([before](design-explorations/built/calls-list-before-dark.png), [at rest](design-explorations/built/calls-list-after-rest-dark.png), [on hover](design-explorations/built/calls-list-after-hover-dark.png)) | done | Owner: the default bar always showed and took the rows' width | `tests/ui/window.test.ts` "[W13.7]": the calls keep the width of the rows under them, no pane shows a bar at rest, a scroll the code makes shows nothing, hover and a wheel scroll show it and it goes after | has |
Expand Down
Loading
Loading