@miadi/tide 0.2.1 → 0.2.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 CHANGED
@@ -64,9 +64,12 @@ resolved via `TIDE_TMUX_BIN` -> `tmux` on `PATH`.
64
64
  herdr pane ids (`"w1:p2"` as of herdr 0.7; legacy `"1-2"` accepted) are **session-scoped** —
65
65
  they reset on herdr restart, and a stale id fails loudly with `pane_not_found`. Pass `paneLabel`
66
66
  (set via `herdr pane rename`) and the client re-resolves label → current id via
67
- `herdr pane list` before **every** action. Additional verbs:
68
- `runInHerdrPane`, `readHerdrPane` (recent-unwrapped text), `waitForHerdrOutput`,
69
- `waitForHerdrAgentStatus`, `listHerdrPanes/Workspaces/Tabs`. Binary resolution:
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`. `peek(pane, lines, { multiplexer: "herdr" })`
72
+ reads herdr scrollback through the stable peek verb. Binary resolution:
70
73
  `TIDE_HERDR_BIN` → `herdr` on `PATH`.
71
74
 
72
75
  > **Readiness: `live-verified`.** Smoked against a real herdr 0.7.4 instance (EP137
@@ -114,11 +117,13 @@ Newline-delimited JSON over a Unix socket. Request
114
117
  (mirrors the runtime's `get_config_dir()`). Binary resolution for the CLI fallback:
115
118
  `TIDE_BIN` → `which tide` → legacy `/home/jgi/anaconda3/bin/tide`.
116
119
 
117
- ## Operator-cockpit surface (next)
120
+ ## Operator-cockpit surface
118
121
 
119
- `describeTransport()` + `pingDaemon()` are the building blocks for a `GET /api/tide/health`
120
- endpoint so a Hermes/Ava/Miadi session can see *which transport is live and whether the daemon is
121
- answering* before it reads context or proposes a steer. See the foundations plan.
122
+ `describeTransport()` + `pingDaemon()` back the shipped `GET /api/tide/health` route, so a
123
+ Hermes/Ava/Miadi session can see *which transport is live and whether the daemon is answering*
124
+ before it reads context or proposes a steer. The cockpit routes (`steer`, `peek`, `detect`,
125
+ `terminals`) are still tmux-only — herdr reachability from `/api/tide/*` is tracked in
126
+ jgwill/Miadi#494.
122
127
 
123
128
  ## Tests
124
129
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@miadi/tide",
3
- "version": "0.2.1",
3
+ "version": "0.2.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"
@@ -15,7 +15,7 @@
15
15
  "src"
16
16
  ],
17
17
  "dependencies": {
18
- "@miadi/tide-contract": "0.2.1"
18
+ "@miadi/tide-contract": "0.2.2"
19
19
  },
20
20
  "scripts": {
21
21
  "test": "d=$(mktemp -d \"${TMPDIR:-/tmp}/miadi-tide-test.XXXXXX\") && trap 'rm -rf \"$d\"' EXIT && ../../node_modules/.bin/tsc -p tsconfig.test.json --outDir \"$d\" && node --test \"$d\"/packages/tide/test/*.test.js"
package/src/client.ts CHANGED
@@ -41,7 +41,7 @@ import {
41
41
  TideDaemonError,
42
42
  } from "./socket"
43
43
  import { TideError } from "./errors"
44
- import { sendKeysViaHerdr } from "./herdr"
44
+ import { HERDR_PANE_ID_PATTERN, buildHerdrSendKeysPlan, readHerdrPane, sendKeysViaHerdr } from "./herdr"
45
45
  import type { HerdrCommandRunner } from "./herdr"
46
46
 
47
47
  const pExecFile = promisify(execFile)
@@ -204,8 +204,26 @@ export function detect(opts: DetectOptions = {}): Promise<TideDetectResult> {
204
204
  return runTideJson<TideDetectResult>(args, { timeoutMs: 8_000, ...opts })
205
205
  }
206
206
 
207
- /** Operator cockpit — read scrollback for a pane without attaching. `pane` is the numeric index (no `%`). */
208
- export function peek(pane: string, lines = 30, opts?: TideRunOptions): Promise<TidePeekResult> {
207
+ export interface PeekOptions extends TideRunOptions {
208
+ /** Absent or "tmux" keeps the historical tide-runtime peek; "herdr" reads via `herdr pane read`. */
209
+ multiplexer?: Multiplexer
210
+ /** herdr only: durable pane label, re-resolved to the current pane id at action time. */
211
+ paneLabel?: string
212
+ /** herdr only: injected command runner (tests). */
213
+ runner?: HerdrCommandRunner
214
+ }
215
+
216
+ /**
217
+ * Operator cockpit — read scrollback for a pane without attaching. tmux path:
218
+ * `pane` is the numeric index (no `%`). herdr path (`multiplexer: "herdr"`):
219
+ * `pane` is a herdr pane id (or pass `paneLabel`), and the recent-unwrapped
220
+ * text comes back split into `lines`.
221
+ */
222
+ export async function peek(pane: string, lines = 30, opts: PeekOptions = {}): Promise<TidePeekResult> {
223
+ if (opts.multiplexer === "herdr") {
224
+ const text = await readHerdrPane(pane, lines, opts)
225
+ return { multiplexer: "herdr", pane, lines: text.split("\n"), text }
226
+ }
209
227
  return runTideJson<TidePeekResult>(
210
228
  ["operator", "peek", `%${pane}`, "--lines", String(lines), "--format", "json"],
211
229
  { timeoutMs: 8_000, ...opts },
@@ -320,6 +338,13 @@ export async function sendKeys(
320
338
  if (opts.multiplexer === "herdr") {
321
339
  return sendKeysViaHerdr(pane, message, opts)
322
340
  }
341
+ // herdr-only options on the tmux path would silently steer the raw tmux
342
+ // pane — the wrong-pane hazard labels exist to prevent. Fail loudly instead.
343
+ if (opts.paneLabel !== undefined || opts.runner !== undefined) {
344
+ throw new TideError(
345
+ `sendKeys: "paneLabel"/"runner" are herdr-only options — pass multiplexer: "herdr"`,
346
+ )
347
+ }
323
348
  const submit = opts.submit ?? true
324
349
  const plan = buildSendKeysPlan(pane, message, submit)
325
350
  const bin = resolveTmuxBin()
@@ -465,13 +490,21 @@ export async function listPendingApprovals(
465
490
  }
466
491
  }
467
492
 
468
- /** Build a steer plan with lane context (wraps buildSendKeysPlan, adds lane_id). */
493
+ /**
494
+ * Build a steer plan with lane context (adds lane_id). Dispatches on the
495
+ * pane-target format: contract-legal herdr targets like "w1:p2" (see
496
+ * `EpisodeLane.pane_target`) get a herdr plan — the tmux normalizer would
497
+ * otherwise mangle them into garbage like "%w1:p2". The two id grammars are
498
+ * disjoint (tmux: `%?digits`), so format detection is unambiguous.
499
+ */
469
500
  export function buildEpisodeSteerPlan(
470
501
  laneId: string,
471
502
  pane: string,
472
503
  message: string,
473
504
  submit = true,
474
- ): ReturnType<typeof buildSendKeysPlan> & { lane_id: string } {
475
- const plan = buildSendKeysPlan(pane, message, submit)
505
+ ): TideSendKeysResult & { lane_id: string } {
506
+ const plan = HERDR_PANE_ID_PATTERN.test(pane.trim())
507
+ ? buildHerdrSendKeysPlan(pane, message, submit)
508
+ : buildSendKeysPlan(pane, message, submit)
476
509
  return { ...plan, lane_id: laneId }
477
510
  }
package/src/herdr.ts CHANGED
@@ -30,7 +30,13 @@
30
30
  import { execFile } from "node:child_process"
31
31
  import { promisify } from "node:util"
32
32
 
33
- import type { TideAgentStatus, TideHerdrSendKeysResult } from "@miadi/tide-contract"
33
+ import type {
34
+ TideAgentStatus,
35
+ TideHerdrAgentStatusEvent,
36
+ TideHerdrPaneInfo,
37
+ TideHerdrSendKeysResult,
38
+ TideHerdrWaitOutputResult,
39
+ } from "@miadi/tide-contract"
34
40
  import { TideError } from "./errors"
35
41
  import type { TideRunOptions } from "./client"
36
42
 
@@ -83,7 +89,10 @@ function describeRunnerError(err: unknown): string {
83
89
  const stderr = typeof e?.stderr === "string" ? e.stderr.trim() : ""
84
90
  if (stderr) return stderr
85
91
  const raw = err instanceof Error ? err.message : String(err)
86
- const stripped = raw.replace(/^Command failed:[^\n]*\n?/, "").trim()
92
+ // A "Command failed:" message embeds the full argv — possibly across several
93
+ // lines when the steered text contains newlines — so discard it entirely
94
+ // rather than stripping just the first line.
95
+ const stripped = raw.startsWith("Command failed:") ? "" : raw.trim()
87
96
  if (stripped) return stripped
88
97
  const meta = [
89
98
  e?.code != null ? `exit code ${String(e.code)}` : null,
@@ -128,22 +137,12 @@ export function normalizeHerdrPaneTarget(pane: string): string {
128
137
  }
129
138
 
130
139
  /**
131
- * One row from `herdr pane list`. Loosely typed; the named fields below are
132
- * the ones observed live on herdr 0.7.4. `label` only appears after
133
- * `herdr pane rename`; `title` is tolerated for other herdr builds.
140
+ * One row from `herdr pane list` — the covenant shape (tide-contract 0.2.2's
141
+ * `TideHerdrPaneInfo`) plus a `title` field tolerated for other herdr builds
142
+ * (live 0.7.4 rows never carry it; resolution matches it only as a fallback).
134
143
  */
135
- export interface HerdrPaneInfo {
136
- pane_id?: string
137
- label?: string
144
+ export interface HerdrPaneInfo extends TideHerdrPaneInfo {
138
145
  title?: string
139
- focused?: boolean
140
- agent_status?: TideAgentStatus | string
141
- workspace_id?: string
142
- tab_id?: string
143
- cwd?: string
144
- terminal_title?: string
145
- terminal_title_stripped?: string
146
- [key: string]: unknown
147
146
  }
148
147
 
149
148
  export interface HerdrWorkspaceInfo {
@@ -202,7 +201,17 @@ export async function listHerdrTabs(workspace: string, opts: HerdrRunOptions = {
202
201
  export async function resolveHerdrPaneId(paneLabel: string, opts: HerdrRunOptions = {}): Promise<string> {
203
202
  const label = paneLabel.trim()
204
203
  const panes = await listHerdrPanes(opts)
205
- const match = panes.find((p) => p.label === label || p.title === label)
204
+ // Two passes: an explicit `pane rename` label always beats a title
205
+ // coincidence, regardless of pane order.
206
+ let matches = panes.filter((p) => p.label === label)
207
+ if (matches.length === 0) matches = panes.filter((p) => p.title === label)
208
+ if (matches.length > 1) {
209
+ const ids = matches.map((p) => p.pane_id ?? "?").join(", ")
210
+ throw new TideError(
211
+ `ambiguous herdr pane label "${label}" — matches panes ${ids}; rename panes to unique labels`,
212
+ )
213
+ }
214
+ const match = matches[0]
206
215
  if (!match?.pane_id) {
207
216
  throw new TideError(`no herdr pane labeled "${label}" in \`herdr pane list\``)
208
217
  }
@@ -231,17 +240,17 @@ export interface HerdrSendKeysOptions extends HerdrTargetOptions {
231
240
  }
232
241
 
233
242
  /**
234
- * Build the exact herdr CLI argv pair for a steer WITHOUT executing it. Pure —
235
- * the herdr counterpart of buildSendKeysPlan(). `pane` must already be a
236
- * resolved herdr pane id; label→id resolution happens in sendKeysViaHerdr().
243
+ * Assemble the steer plan for an ALREADY-TRUSTED target — no validation. Ids
244
+ * herdr itself just returned (label resolution) must pass through unchecked:
245
+ * re-validating them against HERDR_PANE_ID_PATTERN is the regression class
246
+ * that broke 0.2.0 when live 0.7 ids arrived.
237
247
  */
238
- export function buildHerdrSendKeysPlan(
239
- pane: string,
248
+ function makeHerdrSendKeysPlan(
249
+ target: string,
240
250
  message: string,
241
- submit = true,
251
+ submit: boolean,
242
252
  paneLabel?: string,
243
253
  ): TideHerdrSendKeysResult {
244
- const target = normalizeHerdrPaneTarget(pane)
245
254
  const plan: TideHerdrSendKeysResult = {
246
255
  multiplexer: "herdr",
247
256
  target,
@@ -254,6 +263,20 @@ export function buildHerdrSendKeysPlan(
254
263
  return plan
255
264
  }
256
265
 
266
+ /**
267
+ * Build the exact herdr CLI argv pair for a steer WITHOUT executing it. Pure —
268
+ * the herdr counterpart of buildSendKeysPlan(). `pane` is caller-supplied and
269
+ * therefore validated; label→id resolution happens in sendKeysViaHerdr().
270
+ */
271
+ export function buildHerdrSendKeysPlan(
272
+ pane: string,
273
+ message: string,
274
+ submit = true,
275
+ paneLabel?: string,
276
+ ): TideHerdrSendKeysResult {
277
+ return makeHerdrSendKeysPlan(normalizeHerdrPaneTarget(pane), message, submit, paneLabel)
278
+ }
279
+
257
280
  /**
258
281
  * Steer a herdr pane: type `message` via `herdr pane send-text`, then submit a
259
282
  * real Enter via `herdr pane send-keys … Enter` unless `submit: false`. Same
@@ -266,8 +289,9 @@ export async function sendKeysViaHerdr(
266
289
  message: string,
267
290
  opts: HerdrSendKeysOptions = {},
268
291
  ): Promise<TideHerdrSendKeysResult> {
292
+ // resolveTarget validates caller-supplied ids and trusts label-resolved ones.
269
293
  const target = await resolveTarget(pane, opts)
270
- const plan = buildHerdrSendKeysPlan(target, message, opts.submit ?? true, opts.paneLabel)
294
+ const plan = makeHerdrSendKeysPlan(target, message, opts.submit ?? true, opts.paneLabel)
271
295
  const runner = makeRunner(opts)
272
296
  const bin = resolveHerdrBin()
273
297
  try {
@@ -293,6 +317,20 @@ export async function sendKeysViaHerdr(
293
317
 
294
318
  // ── Other transport verbs ───────────────────────────────────────────────────
295
319
 
320
+ /**
321
+ * `herdr pane rename <id> <label>` — set the durable label that label→id
322
+ * resolution matches. The one command the whole re-resolution design rests on:
323
+ * without a rename, live 0.7.4 pane rows carry no `label` field at all.
324
+ */
325
+ export async function renameHerdrPane(
326
+ pane: string,
327
+ label: string,
328
+ opts: HerdrTargetOptions = {},
329
+ ): Promise<void> {
330
+ const target = await resolveTarget(pane, opts)
331
+ await runHerdr(["pane", "rename", target, label], opts)
332
+ }
333
+
296
334
  /** `herdr pane run <id> <command>` — send the text and a real Enter in one request. */
297
335
  export async function runInHerdrPane(
298
336
  pane: string,
@@ -333,15 +371,20 @@ export async function waitForHerdrOutput(
333
371
  pane: string,
334
372
  match: string,
335
373
  opts: HerdrWaitOptions = {},
336
- ): Promise<unknown> {
374
+ ): Promise<TideHerdrWaitOutputResult> {
337
375
  const target = await resolveTarget(pane, opts)
338
376
  const waitMs = opts.waitTimeoutMs ?? 30_000
339
377
  const args = ["wait", "output", target, "--match", match]
340
378
  if (opts.regex) args.push("--regex")
341
379
  args.push("--timeout", String(waitMs))
342
- // Child-process timeout must outlive the herdr-side wait.
343
- const { stdout } = await runHerdr(args, { ...opts, timeoutMs: opts.timeoutMs ?? waitMs + 5_000 })
344
- return parseHerdrJson<unknown>(stdout, "wait output")
380
+ // Child-process timeout must outlive the herdr-side wait — even when the
381
+ // caller passed a smaller generic timeoutMs, which would otherwise SIGTERM
382
+ // herdr mid-wait.
383
+ const { stdout } = await runHerdr(args, {
384
+ ...opts,
385
+ timeoutMs: Math.max(opts.timeoutMs ?? 0, waitMs + 5_000),
386
+ })
387
+ return parseHerdrJson<TideHerdrWaitOutputResult>(stdout, "wait output")
345
388
  }
346
389
 
347
390
  /**
@@ -355,12 +398,12 @@ export async function waitForHerdrAgentStatus(
355
398
  pane: string,
356
399
  status: TideAgentStatus,
357
400
  opts: HerdrWaitOptions = {},
358
- ): Promise<unknown> {
401
+ ): Promise<TideHerdrAgentStatusEvent> {
359
402
  const target = await resolveTarget(pane, opts)
360
403
  const waitMs = opts.waitTimeoutMs ?? 60_000
361
404
  const { stdout } = await runHerdr(
362
405
  ["wait", "agent-status", target, "--status", status, "--timeout", String(waitMs)],
363
- { ...opts, timeoutMs: opts.timeoutMs ?? waitMs + 5_000 },
406
+ { ...opts, timeoutMs: Math.max(opts.timeoutMs ?? 0, waitMs + 5_000) },
364
407
  )
365
- return parseHerdrJson<unknown>(stdout, "wait agent-status")
408
+ return parseHerdrJson<TideHerdrAgentStatusEvent>(stdout, "wait agent-status")
366
409
  }