@miadi/tide 0.5.1 → 0.5.3

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.
Files changed (3) hide show
  1. package/README.md +111 -188
  2. package/package.json +2 -2
  3. package/src/annotate.ts +29 -23
package/README.md CHANGED
@@ -1,231 +1,154 @@
1
1
  # `@miadi/tide`
2
2
 
3
- Typed client boundary between Miadi and the **ironsilk `tide`** runtime. The single place the web app talks to `tide` — replacing the per-route
4
- `exec("/home/jgi/anaconda3/bin/tide …")` calls.
3
+ Read and steer the agents working in your terminals, from TypeScript.
5
4
 
6
- Grounded in `foundations/terminal-workspace-orchestration/` (Decision C) and
7
- `rispecs/tide-runtime/05-ui-surface.spec.md` (daemon-socket transport).
5
+ In the Miadi stack, `@miadi/tide` is how a program sees and directs agents at work. It lists
6
+ the terminals on a machine, reads what the agent in a pane is doing, and sends that agent a
7
+ message when the caller is allowed to. It works with tmux and with
8
+ [herdr](https://github.com/ogulcancelik/herdr). Every send passes a steer gate first, so a
9
+ program cannot type into a pane unless a controller has been named for it. Miadi's operator
10
+ cockpit is built on this package.
8
11
 
9
- ## Runtime dependency — install `tide`
12
+ Works with:
10
13
 
11
- This package is a **client**; it does not bundle the runtime. The `tide` CLI is the
12
- console entry point of the **`ironsilk`** PyPI package (`[project.scripts]`
13
- `tide = tide_runtime.cli:main`). Install / upgrade it in the Python env the
14
- Next.js server can reach:
14
+ - `@miadi/tide-contract`: the schema this client and the tide runtime share.
15
+ - `@miadi/annotate-core`: marks an agent's reply before a review is sent back to its pane.
16
+ - the `tide` CLI from the `ironsilk` Python package: the runtime this client talks to.
17
+
18
+ ## Install
15
19
 
16
20
  ```bash
21
+ npm install @miadi/tide
17
22
  pip install -U ironsilk # provides the `tide` CLI (0.9.27+)
18
23
  tide --help # verify
19
24
  ```
20
25
 
21
- Source for the runtime lives at `/usr/local/src/ironsilk/runtime/` (editable:
22
- `pip install -e .`). `@miadi/tide` resolves the binary via `TIDE_BIN` →
23
- `which tide` → legacy `/home/jgi/anaconda3/bin/tide`; set `TIDE_BIN` when `tide`
24
- is outside the server's `PATH`. The daemon socket is resolved separately via
25
- `TIDE_SOCKET` (see below).
26
+ The package ships TypeScript source (`src/index.ts`), so compile it with your bundler. In
27
+ Next.js, add `@miadi/tide` to `transpilePackages`.
26
28
 
27
29
  ## Verbs
28
30
 
29
31
  ```ts
30
32
  import { getContext, getTerminals, detect, peek, steerProposal, send, sendKeys, buildSendKeysPlan, pingDaemon, describeTransport, TideError } from "@miadi/tide"
31
33
 
32
- const snapshot = await getContext() // R2 live context (daemon socket → CLI fallback)
33
- const terminals = await getTerminals() // operator terminals inventory (CLI, read-only)
34
- const match = await detect({ pane: "56" })// R1 domain detection for a pane/cwd → match | null (CLI)
35
- const scroll = await peek("56", 80) // operator peek %56 (CLI)
36
- const proposal = await steerProposal("56", "continue from checkpoint") // (CLI)
37
- const sent = await send("56", "continue") // guarded --run, controller mode (CLI)
34
+ const snapshot = await getContext() // live context of every terminal (daemon socket → CLI fallback)
35
+ const terminals = await getTerminals() // operator terminals inventory (read-only)
36
+ const match = await detect({ pane: "56" })// domain detection for a pane or cwd → match | null
37
+ const scroll = await peek("56", 80) // last 80 lines of pane %56
38
+ const proposal = await steerProposal("56", "continue from checkpoint") // reviewed proposal, nothing sent
39
+ const sent = await send("56", "continue") // guarded send through the tide runtime
38
40
 
39
- // Direct, simple steer transport — `tmux send-keys` via execFile (no shell, no Python):
41
+ // Direct steer through `tmux send-keys` (no shell, no Python):
40
42
  const keyed = await sendKeys("56", "continue") // types text + Enter
41
- const noEnter = await sendKeys("56", "ls -la", { submit: false })// types text, leaves it unsubmitted
42
- const plan = buildSendKeysPlan("56", "ls -la", false) // pure dry-run plan (no execution)
43
+ const noEnter = await sendKeys("56", "ls -la", { submit: false })// types text, leaves it for a person to submit
44
+ const plan = buildSendKeysPlan("56", "ls -la", false) // the tmux argv that would run, nothing executed
43
45
 
44
46
  const up = await pingDaemon() // daemon liveness (ping → pong)
45
47
  const how = describeTransport() // { transport: "socket"|"cli", socketPath, socketAvailable }
46
48
  ```
47
49
 
48
- ### `sendKeys` — the operator cockpit's primary steer path
49
-
50
- `sendKeys(pane, message, { submit })` drives **`tmux send-keys` directly** through `execFile`
51
- with argument arrays (no shell, no escaping, no Python spawn, no reviewed-proposal artifact) —
52
- the simple, robust transport behind `POST /api/tide/steer`. `submit` (default `true`) controls
53
- the trailing Enter (`C-m`): set it `false` to type content into the pane and leave it on the
54
- prompt for a human to review and submit. `buildSendKeysPlan(...)` returns the exact `tmux` argv
55
- pair without executing — used for the cockpit's inline command preview. The tmux binary is
56
- resolved via `TIDE_TMUX_BIN` -> `tmux` on `PATH`.
57
-
58
- ### herdr transport — `multiplexer: "herdr"` (live-verified)
59
-
60
- `sendKeys(pane, message, { multiplexer: "herdr" })` dispatches to the herdr CLI transport
61
- (`src/herdr.ts`): `herdr pane send-text` types the text, `herdr pane send-keys … Enter` submits
62
- (`submit: false` skips it, same toggle as tmux). The result is the herdr variant of the
63
- `TideSendKeysResult` union from `@miadi/tide-contract` (`multiplexer: "herdr"`, herdr CLI argv).
64
- herdr pane ids (`"w1:p2"` as of herdr 0.7; legacy `"1-2"` accepted) are **session-scoped** —
65
- they reset on herdr restart, and a stale id fails loudly with `pane_not_found`. Pass `paneLabel`
66
- (set via `herdr pane rename`) and the client re-resolves label → current id via
67
- `herdr pane list` before **every** action; duplicate labels throw rather than guess. Additional
68
- verbs: `runInHerdrPane`, `readHerdrPane` (recent-unwrapped text), `renameHerdrPane` (sets the
69
- durable label), `waitForHerdrOutput` (typed `TideHerdrWaitOutputResult`),
70
- `waitForHerdrAgentStatus` (typed `TideHerdrAgentStatusEvent` — live hits print an event
71
- envelope), `listHerdrPanes/Workspaces/Tabs`, and `getHerdrInventory({ includeTabs? })` — the
72
- one-call snapshot (`TideHerdrInventory`: workspaces + panes, tabs on request) behind
73
- `GET /api/tide/herdr`, so cockpit routes stay thin. `peek(pane, lines, { multiplexer: "herdr" })`
74
- reads herdr scrollback through the stable peek verb. Pane-id segments are alphanumeric
75
- (`w2:pE` past `p9`). Binary resolution: `TIDE_HERDR_BIN` → `herdr` on `PATH`.
76
-
77
- > **Readiness: `live-verified`.** Smoked against a real herdr 0.7.4 instance (EP137
78
- > herdr-smoke lane, 2026-07-16) — inventory parsing, send-text/send-keys, pane run, read,
79
- > wait output (hit + timeout exit codes), agent-status, and label→id resolution — in
80
- > addition to the injected-runner tests in `test/herdr.test.ts`.
81
-
82
- #### Observer inventory + capability advertisement (EP152, live-verified)
83
-
84
- ```ts
85
- import { getHerdrSnapshot, describeHerdrCapabilities } from "@miadi/tide"
86
-
87
- const snap = await getHerdrSnapshot()
88
- // `herdr api snapshot` — the whole observer inventory in ONE socket round-trip
89
- // (socket method session.snapshot): workspaces, tabs, panes, detected agents,
90
- // the focus triple, and the server's version/protocol. Read-only, consistent
91
- // (no tearing across a workspace/tab/pane list stitch).
92
-
93
- const caps = await describeHerdrCapabilities()
94
- // `herdr api schema --json` — capability advertisement DERIVED from the live
95
- // schema document: { available, protocol, schema_version, methods[] } plus
96
- // deterministic boolean views (inventory, snapshot, labels, agents,
97
- // wait_output, wait_events, lifecycle_advertised). `lifecycle_authorized` is
98
- // constant false: the server ADVERTISING workspace.close does not authorize
99
- // this client to drive it — that flips only when the closure-receipts ladder
100
- // lands as code. Never throws: a failed probe returns { available: false,
101
- // reason } — safe for /api/tide/health.
102
- ```
103
-
104
- Live receipts (herdr 0.7.4, protocol 16, EP152 2026-07-18): 85 advertised socket
105
- methods, all seven derived flags true, snapshot of 7 workspaces / 22 tabs / 44
106
- panes / 21 agents. That smoke also showed pane ids go **alphanumeric** past `p9`
107
- (`w2:pE`, `w7:pA`) — herdr's own schema types `pane_id` as a plain string — so the
108
- client id pattern accepts the family agreed with `@miadi/tide-contract` 0.2.3:
109
- `w[0-9A-Za-z]+:p[0-9A-Za-z]+` (the dashed legacy form stays digits-only).
110
-
111
- #### Steer gate — ACTIVE_CONTROLLER + TTY + live target (EP152 wave-2)
112
-
113
- Every steer **execution** (`sendKeys` tmux + herdr, `sendKeysViaHerdr`,
114
- `runInHerdrPane`) passes the 3-part gate ported from the Python runtime's
115
- `tide operator send --run` boundary (`src/steer-gate.ts`):
116
-
117
- 1. **live-resolved target** — the pane must appear in the CURRENT multiplexer
118
- inventory (`tmux list-panes -a` / `herdr pane list`; label resolution counts
119
- as live proof);
120
- 2. **ACTIVE_CONTROLLER posture** — `mode: controller` in
121
- `${MIADI_HOME|~/.miadi/navigator}/config.yml`, with the controller TTL lease
122
- applied on every read (an expired lease reads as observer, fail-closed);
123
- 3. **interactive local TTY** — or `TIDE_ALLOW_NON_INTERACTIVE_RUN=1` set by an
124
- approval-queue-fronted service after its own review.
125
-
126
- A refused steer throws `TideError` naming **every** failed check and never
127
- touches the multiplexer. Plan builders (`buildSendKeysPlan`,
128
- `buildHerdrSendKeysPlan`) stay ungated — dry-run is the covenant's default
129
- posture. `evaluateSteerGate`/`requireSteerGate`/`readNavigatorPosture` are
130
- exported for `/api/tide/health`-style surfaces. The `gate` option injects
131
- probes (tests, first-party wiring); it cannot disable the gate, and overrides
132
- are only accepted when branded by `trustSteerGateProbes()` — which is NOT on
133
- the package surface (direct module import only; the brand is a module-private
134
- non-enumerable Symbol, so JSON/request-derived gate options are structurally
135
- refused).
136
-
137
- Label hardening (same wave): resolution is NFC-normalized, label-only (the
138
- `title` fallback is gone), **duplicate labels are a hard refusal**, and
139
- `{ workspace: "w7" }` scopes resolution. Wrong-multiplexer dispatch fails
140
- loudly in both directions (a herdr-shaped id on the tmux path and vice versa).
141
-
142
- `getTerminals` and `detect` are the read-only surface behind `GET /api/tide/terminals`
143
- and `GET /api/tide/detect` — the typed half of operator-terminal triage and manual
144
- domain assignment (jgwill/Miadi#382). The write-back half (assign a pane to a domain)
145
- is deferred to the runtime + a guarded route.
146
-
147
- ## Transport status
148
-
149
- | Layer | Status |
150
- |---|---|
151
- | One-shot CLI (`tide … --format json`, `execFile` arg-arrays, no shell) | **implemented** |
152
- | Daemon + Unix-domain-socket transport (`miadi.tide.daemon.v2`) | **implemented** (`src/socket.ts`) |
153
- | herdr CLI transport (`src/herdr.ts`, `multiplexer: "herdr"`) | **live-verified** (herdr 0.7.4, EP137 smoke + runner-mocked tests) |
154
- | Schema-first contract (`tide-api.schema.json` → generated types) | planned |
50
+ `sendKeys` is the primary steer path. It runs `tmux send-keys` through `execFile` with
51
+ argument arrays, so nothing is interpreted by a shell. `submit` (default `true`) controls the
52
+ trailing Enter. `buildSendKeysPlan` returns the exact command without running it, for a
53
+ preview.
155
54
 
156
- ### How transport selection works
55
+ `pingDaemon()` and `describeTransport()` tell a caller which transport is live and whether the
56
+ daemon answers, before it reads context or proposes a steer.
157
57
 
158
- `getContext()` is transport-aware:
58
+ ## The steer gate
159
59
 
160
- - **`auto`** (default): use the daemon socket if it is up; on absence *or* daemon error, fall
161
- back to the CLI. No Python spawn on the hot path when the daemon is running (~µs socket
162
- round-trip vs ~200–500 ms CLI spawn).
163
- - **`socket`**: daemon only — throws `TideDaemonError` if unavailable.
164
- - **`cli`**: force the CLI.
60
+ Every steer that executes (`sendKeys` on tmux or herdr, `sendKeysViaHerdr`, `runInHerdrPane`)
61
+ passes three checks, the same ones the Python runtime applies to `tide operator send --run`:
165
62
 
166
- `peek` / `steerProposal` / `send` are **CLI-only**: the daemon exposes `get_context` / `ping` /
167
- `detect`, not the operator mutation verbs. `sendKeys` is independent of both — it talks to `tmux` directly. They join the socket path when the runtime adds those
168
- actions — verb signatures are the stable surface; only the transport underneath changes.
63
+ 1. **Live target.** The pane is in the current multiplexer inventory (`tmux list-panes -a` or
64
+ `herdr pane list`).
65
+ 2. **Controller posture.** `${MIADI_HOME:-~/.miadi/navigator}/config.yml` says
66
+ `mode: controller`, and its lease has not expired. An expired lease reads as observer.
67
+ 3. **Interactive terminal.** stdin is a TTY, or `TIDE_ALLOW_NON_INTERACTIVE_RUN=1` is set by a
68
+ service that has reviewed the request itself.
169
69
 
170
- ### Wire protocol (mirrors `tide_runtime/daemon.py`)
70
+ A refused steer throws `TideError` naming every failed check and never touches the
71
+ multiplexer. Plan builders (`buildSendKeysPlan`, `buildHerdrSendKeysPlan`) are not gated.
171
72
 
172
- Newline-delimited JSON over a Unix socket. Request
173
- `{contract_version:"miadi.tide.daemon.v2", request_id, action, payload}` →
174
- `{contract_version, request_id, ok:true, data}` (or `ok:false, error:{code,message,retryable}}`).
73
+ `evaluateSteerGate`, `requireSteerGate` and `readNavigatorPosture` expose the gate for health
74
+ checks. A server route that has already authenticated a person can pass
75
+ `humanConsentSteerGate("<route and gate name>")` as the `gate` option: posture and terminal then
76
+ count as satisfied, and the live-target check still applies. No other gate option is accepted
77
+ from outside the package, so options built from JSON or a request cannot bypass the gate.
175
78
 
176
- ### Socket path resolution
79
+ ## herdr
177
80
 
178
- `TIDE_SOCKET` (explicit) → `${MIADI_HOME || ~/.miadi/navigator}/daemon.sock`
179
- (mirrors the runtime's `get_config_dir()`). Binary resolution for the CLI fallback:
180
- `TIDE_BIN` → `which tide` → legacy `/home/jgi/anaconda3/bin/tide`.
81
+ `sendKeys(pane, message, { multiplexer: "herdr" })` types with `herdr pane send-text` and
82
+ submits with `herdr pane send-keys … Enter`. `peek(pane, lines, { multiplexer: "herdr" })`
83
+ reads herdr scrollback.
181
84
 
182
- ## Operator-cockpit surface
85
+ herdr pane ids (`w1:p2`, alphanumeric past `p9` as in `w2:pE`; legacy `1-2` accepted) reset
86
+ when herdr restarts, and a stale id fails with `pane_not_found`. Name a pane with
87
+ `renameHerdrPane` and pass `paneLabel`: the client resolves the label to the current id
88
+ before every action. Labels are compared after NFC normalization, a duplicate label is refused
89
+ rather than guessed, and `{ workspace: "w7" }` limits the search to one workspace. Sending a
90
+ herdr id down the tmux path, or the reverse, fails.
183
91
 
184
- `describeTransport()` + `pingDaemon()` back the shipped `GET /api/tide/health` route, so a
185
- Hermes/Ava/Miadi session can see *which transport is live and whether the daemon is answering*
186
- before it reads context or proposes a steer. The cockpit routes (`steer`, `peek`, `detect`,
187
- `terminals`) are still tmux-only — herdr reachability from `/api/tide/*` is tracked in
188
- jgwill/Miadi#494.
92
+ Other herdr verbs:
189
93
 
190
- ### Annotate surface — `/api/tide/annotate/{resolve,mark,deliver}` (2026-09-12)
94
+ | verb | returns |
95
+ |---|---|
96
+ | `runInHerdrPane`, `readHerdrPane`, `renameHerdrPane` | run a command, read recent text, set a label |
97
+ | `waitForHerdrOutput`, `waitForHerdrAgentStatus` | wait for output or an agent status change |
98
+ | `listHerdrPanes`, `listHerdrWorkspaces`, `listHerdrTabs` | inventory lists |
99
+ | `getHerdrInventory({ includeTabs? })` | workspaces and panes in one call |
100
+ | `getHerdrSnapshot()` | the whole inventory in one socket round trip: workspaces, tabs, panes, agents, focus, server version |
101
+ | `describeHerdrCapabilities()` | what the running herdr advertises, derived from its schema. Never throws: a failed probe returns `{ available: false, reason }` |
191
102
 
192
- The web leg of the plannotator review loop that `tan <pane>` runs in a terminal. Verbs:
193
- `fetchReply(pane, {pick, host})`, `listBlocks(doc)`, `mark(doc, {block | quote, text, kind})`,
194
- `exportReview(doc)`, `deliver(pane, doc, {submit})`. An adapter over
195
- `/opt/gaia/linux_migration/11-plannotator-tmux-review.sh` (jgwill/gaia#80) and a headless
196
- `plannotator-tui` — no resolution or delivery logic of its own, so the two clients cannot drift.
197
- Marks land in plannotator's store keyed by the vessel document, so a review begun in the browser
198
- can be finished in the terminal TUI and the other way round. A block mark is always a comment;
199
- `looks_good` / `delete` need a quote (plannotator-tui 0.6.0). tmux only.
103
+ `describeHerdrCapabilities()` reports `lifecycle_authorized: false` even when herdr advertises
104
+ `workspace.close`: this client does not close workspaces. Tested against herdr 0.7.4.
200
105
 
201
- Second pass (2026-09-12, Mia's marks, Episode 339): a vessel remembers the pane it was fetched
202
- from (`source.json`) and `deliver` refuses any other pane, or a document with no source identity;
203
- every mark made here carries `author` (a stable principal id) and `author_name` — required in
204
- `mark()`, derived from a tailnet identity by the route when there is one — while marks made
205
- earlier or in the TUI stay unattributed. Gates: `resolve` and `mark` are writer-tier
206
- (`requireMiadiAuth({ write: true })`, as `/api/tide/peek`); `deliver` additionally needs the writer
207
- token or a tailnet identity, as `/api/tide/steer`, and answers a pane-guard refusal as `held`, not
208
- an error. Proven in `tests/annotate-routes.test.mjs` and `test/annotate-deliver.test.ts`.
106
+ ## Transports
209
107
 
210
- Resolution: `PLANNOTATOR_TMUX_REVIEW_SCRIPT` → the gaia path above; `PLANNOTATOR_TUI_BIN` →
211
- `which plannotator-tui` → `~/.cargo/bin/plannotator-tui` (the Next server's PATH lacks cargo's
212
- bin); `PLANNOTATOR_TMUX_REVIEW_DIR` is the script's own vessel root, web runs sit under `web/`.
213
- Grounding: `foundations/annotation-as-coordination/`. Routes: `app/api/tide/annotate/*`;
214
- UI: `components/tide/reply-annotator.tsx` in the `/tide` pane inspector.
108
+ | transport | used by |
109
+ |---|---|
110
+ | daemon Unix socket (`miadi.tide.daemon.v2`) | `getContext` when the daemon is up |
111
+ | `tide` CLI (`tide … --format json`, `execFile`, no shell) | `getContext` fallback, `getTerminals`, `detect`, `peek`, `steerProposal`, `send` |
112
+ | tmux directly | `sendKeys` |
113
+ | herdr CLI | the herdr verbs and `multiplexer: "herdr"` |
215
114
 
216
- ## Tests
115
+ `getContext({ transport })` accepts `auto` (default: socket, falling back to the CLI on
116
+ absence or error), `socket` (throws `TideDaemonError` when unavailable) or `cli`. The socket
117
+ answers in microseconds where a CLI spawn costs 200–500 ms. Verb signatures stay the same when
118
+ a verb moves to another transport.
217
119
 
218
- ```bash
219
- cd packages/tide && npm test
220
- ```
120
+ The daemon speaks newline-delimited JSON. Request
121
+ `{contract_version:"miadi.tide.daemon.v2", request_id, action, payload}`, reply
122
+ `{contract_version, request_id, ok:true, data}` or `{…, ok:false, error:{code,message,retryable}}`.
221
123
 
222
- Compiles `src` + `test` to `/tmp/miadi-tide-test` (CJS) and runs `node --test`. The suite proves
223
- socket selection and CLI fallback with a **fake Unix-socket daemon** and a **fake `tide` binary** —
224
- no live daemon, no live `tide` required.
124
+ ## Annotating a reply
225
125
 
226
- ## App wiring (current)
126
+ The web half of the plannotator review loop that `tan <pane>` runs in a terminal:
227
127
 
228
- Resolved as **source** via a `tsconfig.json` path alias
229
- (`"@miadi/tide": ["./packages/tide/src/index.ts"]`) — same pattern as `@miadi/a2a-contracts`,
230
- no `pnpm install`, no lockfile change. Switch to a `workspace:*` dependency + `dist/` build when a
231
- real build step is introduced.
128
+ | verb | does |
129
+ |---|---|
130
+ | `fetchReply(pane, { pick, host })` | copy the agent's last reply from a pane into a review document |
131
+ | `listBlocks(doc)` | the document's blocks |
132
+ | `mark(doc, { block \| quote, text, kind, author, author_name })` | add a signed mark |
133
+ | `exportReview(doc)` | the review as text |
134
+ | `deliver(pane, doc, { submit })` | send the review back to the pane it came from |
135
+
136
+ The package holds no review logic of its own. It drives the review script and a headless
137
+ `plannotator-tui`, so a review begun in the browser can be finished in the terminal and the
138
+ other way round. A document remembers the pane it was fetched from, and `deliver` refuses any
139
+ other pane. A block mark is always a comment. `looks_good` and `delete` need a quote.
140
+
141
+ ## Configuration
142
+
143
+ | variable | default | used for |
144
+ |---|---|---|
145
+ | `TIDE_BIN` | `which tide`, then `/home/jgi/anaconda3/bin/tide` | the `tide` CLI |
146
+ | `TIDE_SOCKET` | `${MIADI_HOME:-~/.miadi/navigator}/daemon.sock` | the daemon socket |
147
+ | `MIADI_HOME` | `~/.miadi/navigator` | socket and `config.yml` (controller posture) |
148
+ | `TIDE_TMUX_BIN` | `tmux` on `PATH` | `sendKeys` |
149
+ | `TIDE_HERDR_BIN` | `herdr` on `PATH` | the herdr verbs |
150
+ | `TIDE_ALLOW_NON_INTERACTIVE_RUN` | unset | `1` lets a reviewed service pass the terminal check |
151
+ | `PLANNOTATOR_TMUX_REVIEW_SCRIPT` | `/opt/gaia/linux_migration/11-plannotator-tmux-review.sh` | the review script |
152
+ | `PLANNOTATOR_TUI_BIN` | `which plannotator-tui`, then `~/.cargo/bin/plannotator-tui` | the headless annotator |
153
+ | `PLANNOTATOR_TMUX_REVIEW_DIR` | `${XDG_STATE_HOME:-~/.local/state}/plannotator-tmux-review` | review documents (web runs under `web/`) |
154
+ | `PLANNOTATOR_STORE_DIR` | `~/.plannotator/clients/plannotator-tui/annotations` | plannotator's mark records |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@miadi/tide",
3
- "version": "0.5.1",
3
+ "version": "0.5.3",
4
4
  "description": "Typed client boundary for the ironsilk `tide` runtime. Daemon Unix-socket transport with CLI fallback.",
5
5
  "publishConfig": {
6
6
  "access": "public"
@@ -15,7 +15,7 @@
15
15
  "src"
16
16
  ],
17
17
  "dependencies": {
18
- "@miadi/annotate-core": "^0.1.0",
18
+ "@miadi/annotate-core": "^0.1.1",
19
19
  "@miadi/tide-contract": "0.3.0"
20
20
  },
21
21
  "keywords": [
package/src/annotate.ts CHANGED
@@ -572,10 +572,14 @@ function assertTarget(target: string): void {
572
572
  // -------------------------------------------------------------------- verbs --
573
573
 
574
574
  /**
575
- * The newest earlier web vessel that holds this very reply from this very pane
576
- * and has marks on it. Fetching reopens it instead of keeping a fresh copy, so
575
+ * The newest earlier vessel that holds this very reply from this very pane and
576
+ * has marks on it. Fetching reopens it instead of keeping a fresh copy, so
577
577
  * marks another person made on the reply are there when it is fetched again
578
578
  * (Episode 339: William opens an agent in the cockpit and finds Mia's marks).
579
+ * Two layouts are searched: web runs at `<root>/web/<run>/<vessel>/` and
580
+ * terminal `tan` runs at `<root>/<stamp>-<target>/`, which the review script
581
+ * gives a `source.json` since jgwill/gaia#87. Their stamps are not comparable
582
+ * (UTC vs local time), so matches are ordered by `fetched_at`.
579
583
  * Null when the reply changed since, or nobody marked it.
580
584
  */
581
585
  export async function findMarkedVessel(
@@ -583,32 +587,34 @@ export async function findMarkedVessel(
583
587
  text: string,
584
588
  opts: { root?: string; storeRoot?: string; exclude?: string } = {},
585
589
  ): Promise<{ vessel: string; doc: string; source: SourceIdentity } | null> {
586
- const webDir = join(opts.root ?? resolveVesselRoot(), WEB_VESSEL_SUBDIR)
590
+ const root = opts.root ?? resolveVesselRoot()
591
+ const webDir = join(root, WEB_VESSEL_SUBDIR)
587
592
  const dirs = async (dir: string) =>
588
- (await readdir(dir, { withFileTypes: true })).filter(d => d.isDirectory()).map(d => d.name)
589
- let runs: string[]
590
- try {
591
- // Run directories are stamped, so name order is time order.
592
- runs = (await dirs(webDir)).sort().reverse().slice(0, 200)
593
- } catch {
594
- return null
595
- }
596
- for (const run of runs) {
593
+ (await readdir(dir, { withFileTypes: true }).catch(() => [])).filter(d => d.isDirectory()).map(d => d.name)
594
+ // Run directories are stamped, so within one layout name order is time order.
595
+ const newest = (names: string[]) => names.sort().reverse().slice(0, 200)
596
+ const vessels: string[] = []
597
+ for (const run of newest(await dirs(webDir))) {
597
598
  const runDir = join(webDir, run)
598
599
  if (runDir === opts.exclude) continue
599
- for (const child of await dirs(runDir).catch(() => [] as string[])) {
600
- const vessel = join(runDir, child)
601
- const doc = join(vessel, "reply.md")
602
- try {
603
- const source = JSON.parse(await readFile(join(vessel, SOURCE_FILE), "utf8")) as SourceIdentity
604
- if (source.pane_id !== paneId) continue
605
- if ((await readFile(doc, "utf8")) !== text) continue
606
- if ((await listMarks(doc, opts.storeRoot)).length > 0) return { vessel, doc, source }
607
- } catch {
608
- // not a complete web vessel — skip
609
- }
600
+ for (const child of await dirs(runDir)) vessels.push(join(runDir, child))
601
+ }
602
+ for (const run of newest((await dirs(root)).filter(name => name !== WEB_VESSEL_SUBDIR))) vessels.push(join(root, run))
603
+ const matches: { vessel: string; doc: string; source: SourceIdentity }[] = []
604
+ for (const vessel of vessels) {
605
+ const doc = join(vessel, "reply.md")
606
+ try {
607
+ const source = JSON.parse(await readFile(join(vessel, SOURCE_FILE), "utf8")) as SourceIdentity
608
+ if (source.pane_id !== paneId) continue
609
+ if ((await readFile(doc, "utf8")) !== text) continue
610
+ matches.push({ vessel, doc, source })
611
+ } catch {
612
+ // not a complete vessel (a terminal run from before source.json) — skip
610
613
  }
611
614
  }
615
+ // Stable: vessels without fetched_at keep their name order.
616
+ matches.sort((a, b) => String(b.source.fetched_at ?? "").localeCompare(String(a.source.fetched_at ?? "")))
617
+ for (const m of matches) if ((await listMarks(m.doc, opts.storeRoot)).length > 0) return m
612
618
  return null
613
619
  }
614
620