@miadi/tide 0.5.1 → 0.5.2
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/README.md +14 -18
- package/package.json +1 -1
- package/src/annotate.ts +29 -23
package/README.md
CHANGED
|
@@ -3,8 +3,8 @@
|
|
|
3
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
4
|
`exec("/home/jgi/anaconda3/bin/tide …")` calls.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
6
|
+
Grounding, specs, issues and episodes behind this package are listed in `AGENTS.md` in the
|
|
7
|
+
source repository.
|
|
8
8
|
|
|
9
9
|
## Runtime dependency — install `tide`
|
|
10
10
|
|
|
@@ -18,8 +18,7 @@ pip install -U ironsilk # provides the `tide` CLI (0.9.27+)
|
|
|
18
18
|
tide --help # verify
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
`pip install -e .`). `@miadi/tide` resolves the binary via `TIDE_BIN` →
|
|
21
|
+
`@miadi/tide` resolves the binary via `TIDE_BIN` →
|
|
23
22
|
`which tide` → legacy `/home/jgi/anaconda3/bin/tide`; set `TIDE_BIN` when `tide`
|
|
24
23
|
is outside the server's `PATH`. The daemon socket is resolved separately via
|
|
25
24
|
`TIDE_SOCKET` (see below).
|
|
@@ -74,12 +73,12 @@ one-call snapshot (`TideHerdrInventory`: workspaces + panes, tabs on request) be
|
|
|
74
73
|
reads herdr scrollback through the stable peek verb. Pane-id segments are alphanumeric
|
|
75
74
|
(`w2:pE` past `p9`). Binary resolution: `TIDE_HERDR_BIN` → `herdr` on `PATH`.
|
|
76
75
|
|
|
77
|
-
> **Readiness: `live-verified`.** Smoked against a real herdr 0.7.4 instance
|
|
78
|
-
>
|
|
76
|
+
> **Readiness: `live-verified`.** Smoked against a real herdr 0.7.4 instance
|
|
77
|
+
> (2026-07-16) — inventory parsing, send-text/send-keys, pane run, read,
|
|
79
78
|
> wait output (hit + timeout exit codes), agent-status, and label→id resolution — in
|
|
80
79
|
> addition to the injected-runner tests in `test/herdr.test.ts`.
|
|
81
80
|
|
|
82
|
-
#### Observer inventory + capability advertisement (
|
|
81
|
+
#### Observer inventory + capability advertisement (live-verified)
|
|
83
82
|
|
|
84
83
|
```ts
|
|
85
84
|
import { getHerdrSnapshot, describeHerdrCapabilities } from "@miadi/tide"
|
|
@@ -101,14 +100,14 @@ const caps = await describeHerdrCapabilities()
|
|
|
101
100
|
// reason } — safe for /api/tide/health.
|
|
102
101
|
```
|
|
103
102
|
|
|
104
|
-
Live receipts (herdr 0.7.4, protocol 16,
|
|
103
|
+
Live receipts (herdr 0.7.4, protocol 16, 2026-07-18): 85 advertised socket
|
|
105
104
|
methods, all seven derived flags true, snapshot of 7 workspaces / 22 tabs / 44
|
|
106
105
|
panes / 21 agents. That smoke also showed pane ids go **alphanumeric** past `p9`
|
|
107
106
|
(`w2:pE`, `w7:pA`) — herdr's own schema types `pane_id` as a plain string — so the
|
|
108
107
|
client id pattern accepts the family agreed with `@miadi/tide-contract` 0.2.3:
|
|
109
108
|
`w[0-9A-Za-z]+:p[0-9A-Za-z]+` (the dashed legacy form stays digits-only).
|
|
110
109
|
|
|
111
|
-
#### Steer gate — ACTIVE_CONTROLLER + TTY + live target
|
|
110
|
+
#### Steer gate — ACTIVE_CONTROLLER + TTY + live target
|
|
112
111
|
|
|
113
112
|
Every steer **execution** (`sendKeys` tmux + herdr, `sendKeysViaHerdr`,
|
|
114
113
|
`runInHerdrPane`) passes the 3-part gate ported from the Python runtime's
|
|
@@ -141,7 +140,7 @@ loudly in both directions (a herdr-shaped id on the tmux path and vice versa).
|
|
|
141
140
|
|
|
142
141
|
`getTerminals` and `detect` are the read-only surface behind `GET /api/tide/terminals`
|
|
143
142
|
and `GET /api/tide/detect` — the typed half of operator-terminal triage and manual
|
|
144
|
-
domain assignment
|
|
143
|
+
domain assignment. The write-back half (assign a pane to a domain)
|
|
145
144
|
is deferred to the runtime + a guarded route.
|
|
146
145
|
|
|
147
146
|
## Transport status
|
|
@@ -150,7 +149,7 @@ is deferred to the runtime + a guarded route.
|
|
|
150
149
|
|---|---|
|
|
151
150
|
| One-shot CLI (`tide … --format json`, `execFile` arg-arrays, no shell) | **implemented** |
|
|
152
151
|
| 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,
|
|
152
|
+
| herdr CLI transport (`src/herdr.ts`, `multiplexer: "herdr"`) | **live-verified** (herdr 0.7.4, live smoke + runner-mocked tests) |
|
|
154
153
|
| Schema-first contract (`tide-api.schema.json` → generated types) | planned |
|
|
155
154
|
|
|
156
155
|
### How transport selection works
|
|
@@ -184,34 +183,31 @@ Newline-delimited JSON over a Unix socket. Request
|
|
|
184
183
|
`describeTransport()` + `pingDaemon()` back the shipped `GET /api/tide/health` route, so a
|
|
185
184
|
Hermes/Ava/Miadi session can see *which transport is live and whether the daemon is answering*
|
|
186
185
|
before it reads context or proposes a steer. The cockpit routes (`steer`, `peek`, `detect`,
|
|
187
|
-
`terminals`) are still tmux-only
|
|
188
|
-
jgwill/Miadi#494.
|
|
186
|
+
`terminals`) are still tmux-only; herdr reachability from `/api/tide/*` is not wired yet.
|
|
189
187
|
|
|
190
188
|
### Annotate surface — `/api/tide/annotate/{resolve,mark,deliver}` (2026-09-12)
|
|
191
189
|
|
|
192
190
|
The web leg of the plannotator review loop that `tan <pane>` runs in a terminal. Verbs:
|
|
193
191
|
`fetchReply(pane, {pick, host})`, `listBlocks(doc)`, `mark(doc, {block | quote, text, kind})`,
|
|
194
192
|
`exportReview(doc)`, `deliver(pane, doc, {submit})`. An adapter over
|
|
195
|
-
`/opt/gaia/linux_migration/11-plannotator-tmux-review.sh`
|
|
193
|
+
`/opt/gaia/linux_migration/11-plannotator-tmux-review.sh` and a headless
|
|
196
194
|
`plannotator-tui` — no resolution or delivery logic of its own, so the two clients cannot drift.
|
|
197
195
|
Marks land in plannotator's store keyed by the vessel document, so a review begun in the browser
|
|
198
196
|
can be finished in the terminal TUI and the other way round. A block mark is always a comment;
|
|
199
197
|
`looks_good` / `delete` need a quote (plannotator-tui 0.6.0). tmux only.
|
|
200
198
|
|
|
201
|
-
|
|
199
|
+
A vessel remembers the pane it was fetched
|
|
202
200
|
from (`source.json`) and `deliver` refuses any other pane, or a document with no source identity;
|
|
203
201
|
every mark made here carries `author` (a stable principal id) and `author_name` — required in
|
|
204
202
|
`mark()`, derived from a tailnet identity by the route when there is one — while marks made
|
|
205
203
|
earlier or in the TUI stay unattributed. Gates: `resolve` and `mark` are writer-tier
|
|
206
204
|
(`requireMiadiAuth({ write: true })`, as `/api/tide/peek`); `deliver` additionally needs the writer
|
|
207
205
|
token or a tailnet identity, as `/api/tide/steer`, and answers a pane-guard refusal as `held`, not
|
|
208
|
-
an error. Proven in `
|
|
206
|
+
an error. Proven in `test/annotate-deliver.test.ts`.
|
|
209
207
|
|
|
210
208
|
Resolution: `PLANNOTATOR_TMUX_REVIEW_SCRIPT` → the gaia path above; `PLANNOTATOR_TUI_BIN` →
|
|
211
209
|
`which plannotator-tui` → `~/.cargo/bin/plannotator-tui` (the Next server's PATH lacks cargo's
|
|
212
210
|
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.
|
|
215
211
|
|
|
216
212
|
## Tests
|
|
217
213
|
|
package/package.json
CHANGED
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
|
|
576
|
-
*
|
|
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
|
|
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
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
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).
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
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
|
|