@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 +12 -7
- package/package.json +2 -2
- package/src/client.ts +39 -6
- package/src/herdr.ts +75 -32
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
|
|
68
|
-
`runInHerdrPane`, `readHerdrPane` (recent-unwrapped text), `
|
|
69
|
-
|
|
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
|
|
120
|
+
## Operator-cockpit surface
|
|
118
121
|
|
|
119
|
-
`describeTransport()` + `pingDaemon()`
|
|
120
|
-
|
|
121
|
-
|
|
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.
|
|
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.
|
|
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
|
-
|
|
208
|
-
|
|
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
|
-
/**
|
|
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
|
-
):
|
|
475
|
-
const plan =
|
|
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 {
|
|
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
|
-
|
|
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
|
|
132
|
-
*
|
|
133
|
-
*
|
|
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
|
-
|
|
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
|
-
*
|
|
235
|
-
*
|
|
236
|
-
*
|
|
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
|
-
|
|
239
|
-
|
|
248
|
+
function makeHerdrSendKeysPlan(
|
|
249
|
+
target: string,
|
|
240
250
|
message: string,
|
|
241
|
-
submit
|
|
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 =
|
|
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<
|
|
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
|
-
|
|
344
|
-
|
|
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<
|
|
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<
|
|
408
|
+
return parseHerdrJson<TideHerdrAgentStatusEvent>(stdout, "wait agent-status")
|
|
366
409
|
}
|