@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.
Files changed (3) hide show
  1. package/README.md +14 -18
  2. package/package.json +1 -1
  3. 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
- Grounded in `foundations/terminal-workspace-orchestration/` (Decision C) and
7
- `rispecs/tide-runtime/05-ui-surface.spec.md` (daemon-socket transport).
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
- Source for the runtime lives at `/usr/local/src/ironsilk/runtime/` (editable:
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 (EP137
78
- > herdr-smoke lane, 2026-07-16) — inventory parsing, send-text/send-keys, pane run, read,
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 (EP152, live-verified)
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, EP152 2026-07-18): 85 advertised socket
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 (EP152 wave-2)
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 (jgwill/Miadi#382). The write-back half (assign a pane to a domain)
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, EP137 smoke + runner-mocked tests) |
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 — herdr reachability from `/api/tide/*` is tracked in
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` (jgwill/gaia#80) and a headless
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
- Second pass (2026-09-12, Mia's marks, Episode 339): a vessel remembers the pane it was fetched
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 `tests/annotate-routes.test.mjs` and `test/annotate-deliver.test.ts`.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@miadi/tide",
3
- "version": "0.5.1",
3
+ "version": "0.5.2",
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"
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