@miadi/tide 0.1.0 → 0.1.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 +29 -7
- package/package.json +4 -1
- package/src/client.ts +126 -0
- package/src/types.ts +56 -0
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@ Typed client boundary between Miadi and the **ironsilk `tide`** runtime (histori
|
|
|
5
5
|
`exec("/home/jgi/anaconda3/bin/tide …")` calls.
|
|
6
6
|
|
|
7
7
|
Grounded in `foundations/terminal-workspace-orchestration/` (Decision C) and
|
|
8
|
-
`rispecs/
|
|
8
|
+
`rispecs/tide-runtime/05-ui-surface.spec.md` (daemon-socket transport).
|
|
9
9
|
|
|
10
10
|
## Runtime dependency — install `tide`
|
|
11
11
|
|
|
@@ -28,17 +28,39 @@ is outside the server's `PATH`. The daemon socket is resolved separately via
|
|
|
28
28
|
## Verbs
|
|
29
29
|
|
|
30
30
|
```ts
|
|
31
|
-
import { getContext, peek, steerProposal, send, pingDaemon, describeTransport, TideError } from "@miadi/tide"
|
|
31
|
+
import { getContext, getTerminals, detect, peek, steerProposal, send, sendKeys, buildSendKeysPlan, pingDaemon, describeTransport, TideError } from "@miadi/tide"
|
|
32
32
|
|
|
33
|
-
const snapshot
|
|
34
|
-
const
|
|
35
|
-
const
|
|
36
|
-
const
|
|
33
|
+
const snapshot = await getContext() // R2 live context (daemon socket → CLI fallback)
|
|
34
|
+
const terminals = await getTerminals() // operator terminals inventory (CLI, read-only)
|
|
35
|
+
const match = await detect({ pane: "56" })// R1 domain detection for a pane/cwd → match | null (CLI)
|
|
36
|
+
const scroll = await peek("56", 80) // operator peek %56 (CLI)
|
|
37
|
+
const proposal = await steerProposal("56", "continue from checkpoint") // (CLI)
|
|
38
|
+
const sent = await send("56", "continue") // guarded --run, controller mode (CLI)
|
|
39
|
+
|
|
40
|
+
// Direct, simple steer transport — `tmux send-keys` via execFile (no shell, no Python):
|
|
41
|
+
const keyed = await sendKeys("56", "continue") // types text + Enter
|
|
42
|
+
const noEnter = await sendKeys("56", "ls -la", { submit: false })// types text, leaves it unsubmitted
|
|
43
|
+
const plan = buildSendKeysPlan("56", "ls -la", false) // pure dry-run plan (no execution)
|
|
37
44
|
|
|
38
45
|
const up = await pingDaemon() // daemon liveness (ping → pong)
|
|
39
46
|
const how = describeTransport() // { transport: "socket"|"cli", socketPath, socketAvailable }
|
|
40
47
|
```
|
|
41
48
|
|
|
49
|
+
### `sendKeys` — the operator cockpit's primary steer path
|
|
50
|
+
|
|
51
|
+
`sendKeys(pane, message, { submit })` drives **`tmux send-keys` directly** through `execFile`
|
|
52
|
+
with argument arrays (no shell, no escaping, no Python spawn, no reviewed-proposal artifact) —
|
|
53
|
+
the simple, robust transport behind `POST /api/tide/steer`. `submit` (default `true`) controls
|
|
54
|
+
the trailing Enter (`C-m`): set it `false` to type content into the pane and leave it on the
|
|
55
|
+
prompt for a human to review and submit. `buildSendKeysPlan(...)` returns the exact `tmux` argv
|
|
56
|
+
pair without executing — used for the cockpit's inline command preview. The tmux binary is
|
|
57
|
+
resolved via `TIDE_TMUX_BIN` -> `tmux` on `PATH`.
|
|
58
|
+
|
|
59
|
+
`getTerminals` and `detect` are the read-only surface behind `GET /api/tide/terminals`
|
|
60
|
+
and `GET /api/tide/detect` — the typed half of operator-terminal triage and manual
|
|
61
|
+
domain assignment (jgwill/Miadi#382). The write-back half (assign a pane to a domain)
|
|
62
|
+
is deferred to the runtime + a guarded route.
|
|
63
|
+
|
|
42
64
|
## Transport status
|
|
43
65
|
|
|
44
66
|
| Layer | Status |
|
|
@@ -58,7 +80,7 @@ const how = describeTransport() // { transport: "socket"|"cli", soc
|
|
|
58
80
|
- **`cli`**: force the CLI.
|
|
59
81
|
|
|
60
82
|
`peek` / `steerProposal` / `send` are **CLI-only**: the daemon exposes `get_context` / `ping` /
|
|
61
|
-
`detect`, not the operator mutation verbs. They join the socket path when the runtime adds those
|
|
83
|
+
`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
|
|
62
84
|
actions — verb signatures are the stable surface; only the transport underneath changes.
|
|
63
85
|
|
|
64
86
|
### Wire protocol (mirrors `hermes_navigator/daemon.py`)
|
package/package.json
CHANGED
|
@@ -1,7 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@miadi/tide",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "Typed client boundary for the ironsilk `tide` runtime. Daemon Unix-socket transport with CLI fallback.",
|
|
5
|
+
"publishConfig": {
|
|
6
|
+
"access": "public"
|
|
7
|
+
},
|
|
5
8
|
"type": "module",
|
|
6
9
|
"main": "./src/index.ts",
|
|
7
10
|
"types": "./src/index.ts",
|
package/src/client.ts
CHANGED
|
@@ -15,9 +15,12 @@ import { promisify } from "node:util"
|
|
|
15
15
|
|
|
16
16
|
import type {
|
|
17
17
|
ContextSnapshot,
|
|
18
|
+
TideTerminalsResult,
|
|
19
|
+
TideDetectResult,
|
|
18
20
|
TidePeekResult,
|
|
19
21
|
TideSendResult,
|
|
20
22
|
TideSteerResult,
|
|
23
|
+
TideSendKeysResult,
|
|
21
24
|
} from "./types"
|
|
22
25
|
import {
|
|
23
26
|
daemonRequest,
|
|
@@ -111,6 +114,18 @@ export interface GetContextOptions extends TideRunOptions {
|
|
|
111
114
|
transport?: TransportMode
|
|
112
115
|
}
|
|
113
116
|
|
|
117
|
+
export interface GetTerminalsOptions extends TideRunOptions {
|
|
118
|
+
/** Optional domain filter passed through to `tide operator terminals --domain`. */
|
|
119
|
+
domain?: string
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
export interface DetectOptions extends TideRunOptions {
|
|
123
|
+
/** tmux pane id to detect against (with or without the leading `%`). */
|
|
124
|
+
pane?: string
|
|
125
|
+
/** Working directory to detect against (defaults to the runtime's own cwd). */
|
|
126
|
+
detectCwd?: string
|
|
127
|
+
}
|
|
128
|
+
|
|
114
129
|
/** Which transport `getContext()` would use right now — a diagnostic for the operator cockpit. */
|
|
115
130
|
export function describeTransport(): {
|
|
116
131
|
transport: "socket" | "cli"
|
|
@@ -156,6 +171,29 @@ export async function getContext(opts: GetContextOptions = {}): Promise<ContextS
|
|
|
156
171
|
})
|
|
157
172
|
}
|
|
158
173
|
|
|
174
|
+
/** Operator cockpit — read-only inventory of tmux terminal targets. */
|
|
175
|
+
export function getTerminals(opts: GetTerminalsOptions = {}): Promise<TideTerminalsResult> {
|
|
176
|
+
const args = ["operator", "terminals"]
|
|
177
|
+
const domain = opts.domain?.trim()
|
|
178
|
+
if (domain) args.push("--domain", domain)
|
|
179
|
+
args.push("--format", "json")
|
|
180
|
+
return runTideJson<TideTerminalsResult>(args, { timeoutMs: 8_000, ...opts })
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* R1 — domain detection for a pane or cwd without mutating state. Returns the
|
|
185
|
+
* best match (`null` when nothing clears the confidence threshold). The read-only
|
|
186
|
+
* half of manual terminal → domain assignment (F5).
|
|
187
|
+
*/
|
|
188
|
+
export function detect(opts: DetectOptions = {}): Promise<TideDetectResult> {
|
|
189
|
+
const args = ["detect", "--format", "json"]
|
|
190
|
+
const pane = opts.pane?.trim()
|
|
191
|
+
if (pane) args.push("--pane", pane.startsWith("%") ? pane : `%${pane}`)
|
|
192
|
+
const cwd = opts.detectCwd?.trim()
|
|
193
|
+
if (cwd) args.push("--cwd", cwd)
|
|
194
|
+
return runTideJson<TideDetectResult>(args, { timeoutMs: 8_000, ...opts })
|
|
195
|
+
}
|
|
196
|
+
|
|
159
197
|
/** Operator cockpit — read scrollback for a pane without attaching. `pane` is the numeric index (no `%`). */
|
|
160
198
|
export function peek(pane: string, lines = 30, opts?: TideRunOptions): Promise<TidePeekResult> {
|
|
161
199
|
return runTideJson<TidePeekResult>(
|
|
@@ -189,3 +227,91 @@ export function send(pane: string, message: string, opts?: TideRunOptions): Prom
|
|
|
189
227
|
{ timeoutMs: 10_000, ...opts },
|
|
190
228
|
)
|
|
191
229
|
}
|
|
230
|
+
|
|
231
|
+
// ── Direct send-keys (simple, robust steer transport) ───────────────────────
|
|
232
|
+
//
|
|
233
|
+
// The operator cockpit's primary steer path. Instead of the heavier reviewed
|
|
234
|
+
// `steer-proposal` → `send --run` pipeline (which always submits Enter and spawns
|
|
235
|
+
// Python), this drives `tmux send-keys` directly via `execFile` with ARGUMENT
|
|
236
|
+
// ARRAYS (no shell, no escaping). One verb, one round-trip, and the caller decides
|
|
237
|
+
// whether to submit Enter — the affordance the cockpit's "send Enter" checkbox needs.
|
|
238
|
+
|
|
239
|
+
/** Resolve the tmux binary: `TIDE_TMUX_BIN` env → `tmux` (on PATH). */
|
|
240
|
+
function resolveTmuxBin(): string {
|
|
241
|
+
return process.env.TIDE_TMUX_BIN?.trim() || "tmux"
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
/** Normalize a pane reference to a `%`-prefixed tmux pane id (e.g. "56" → "%56"). */
|
|
245
|
+
export function normalizePaneTarget(pane: string): string {
|
|
246
|
+
const trimmed = pane.trim()
|
|
247
|
+
return trimmed.startsWith("%") ? trimmed : `%${trimmed}`
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
export interface SendKeysOptions extends TideRunOptions {
|
|
251
|
+
/**
|
|
252
|
+
* Append a trailing Enter (`C-m`) after typing the literal text. Default true.
|
|
253
|
+
* When false the text is left on the pane's prompt unsubmitted, so a human can
|
|
254
|
+
* review and press Enter — the "send Enter after content" cockpit toggle.
|
|
255
|
+
*/
|
|
256
|
+
submit?: boolean
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
/**
|
|
260
|
+
* Build the exact `tmux send-keys` argv pair for a steer WITHOUT executing it.
|
|
261
|
+
* Pure — safe for client-side previews and dry-run plans. `submit_command` is
|
|
262
|
+
* null when `submit` is false (nothing is submitted).
|
|
263
|
+
*/
|
|
264
|
+
export function buildSendKeysPlan(
|
|
265
|
+
pane: string,
|
|
266
|
+
message: string,
|
|
267
|
+
submit = true,
|
|
268
|
+
): TideSendKeysResult {
|
|
269
|
+
const target = normalizePaneTarget(pane)
|
|
270
|
+
return {
|
|
271
|
+
target,
|
|
272
|
+
message,
|
|
273
|
+
submitted: submit,
|
|
274
|
+
// `-l` types the bytes literally (no tmux key-name interpretation).
|
|
275
|
+
literal_command: ["send-keys", "-l", "-t", target, message],
|
|
276
|
+
submit_command: submit ? ["send-keys", "-t", target, "C-m"] : null,
|
|
277
|
+
}
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
/**
|
|
281
|
+
* Operator cockpit — steer a pane by typing `message` into it via `tmux send-keys`.
|
|
282
|
+
* Robust and simple: no shell, no Python spawn, no reviewed-proposal artifact.
|
|
283
|
+
* Set `submit: false` to type the content without pressing Enter.
|
|
284
|
+
*
|
|
285
|
+
* Two tmux invocations when submitting: the literal text is typed first, then a
|
|
286
|
+
* separate `C-m` submits it. If the literal step succeeds but the submit step
|
|
287
|
+
* fails, the text is already on the pane's prompt (unsubmitted) — the thrown
|
|
288
|
+
* `TideError` names which step failed so the caller can surface that partial state.
|
|
289
|
+
*/
|
|
290
|
+
export async function sendKeys(
|
|
291
|
+
pane: string,
|
|
292
|
+
message: string,
|
|
293
|
+
opts: SendKeysOptions = {},
|
|
294
|
+
): Promise<TideSendKeysResult> {
|
|
295
|
+
const submit = opts.submit ?? true
|
|
296
|
+
const plan = buildSendKeysPlan(pane, message, submit)
|
|
297
|
+
const bin = resolveTmuxBin()
|
|
298
|
+
const runOpts = { timeout: opts.timeoutMs ?? 10_000, cwd: opts.cwd }
|
|
299
|
+
try {
|
|
300
|
+
await pExecFile(bin, plan.literal_command, runOpts)
|
|
301
|
+
} catch (err) {
|
|
302
|
+
const msg = err instanceof Error ? err.message : String(err)
|
|
303
|
+
throw new TideError(`tmux send-keys to ${plan.target} failed (typing literal text): ${msg}`, err)
|
|
304
|
+
}
|
|
305
|
+
if (plan.submit_command) {
|
|
306
|
+
try {
|
|
307
|
+
await pExecFile(bin, plan.submit_command, runOpts)
|
|
308
|
+
} catch (err) {
|
|
309
|
+
const msg = err instanceof Error ? err.message : String(err)
|
|
310
|
+
throw new TideError(
|
|
311
|
+
`tmux send-keys to ${plan.target} failed (submitting Enter; literal text was typed but left unsubmitted): ${msg}`,
|
|
312
|
+
err,
|
|
313
|
+
)
|
|
314
|
+
}
|
|
315
|
+
}
|
|
316
|
+
return { ...plan, sent_at: new Date().toISOString() }
|
|
317
|
+
}
|
package/src/types.ts
CHANGED
|
@@ -42,6 +42,38 @@ export interface ContextSnapshot {
|
|
|
42
42
|
editor_buffers?: string[]
|
|
43
43
|
}
|
|
44
44
|
|
|
45
|
+
/** `tide operator terminals --format json`. Read-only terminal inventory. */
|
|
46
|
+
export interface TideTerminalTarget {
|
|
47
|
+
terminal_id: string
|
|
48
|
+
session_id: string
|
|
49
|
+
session_name: string
|
|
50
|
+
window_id: string
|
|
51
|
+
window_name: string
|
|
52
|
+
pane_id: string
|
|
53
|
+
cwd: string
|
|
54
|
+
pane_active: boolean
|
|
55
|
+
session_attached: number
|
|
56
|
+
pid: number
|
|
57
|
+
command: string
|
|
58
|
+
domain_id: string | null
|
|
59
|
+
domain_confidence: number
|
|
60
|
+
attach_command: string
|
|
61
|
+
switch_command: string
|
|
62
|
+
select_pane_command: string
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
export type TideTerminalsResult = TideTerminalTarget[]
|
|
66
|
+
|
|
67
|
+
/** `tide detect --format json`. Null means no domain match. */
|
|
68
|
+
export interface TideDetectMatch {
|
|
69
|
+
domain_id: string
|
|
70
|
+
confidence: number
|
|
71
|
+
signal_type: string
|
|
72
|
+
source_detail: string
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
export type TideDetectResult = TideDetectMatch | null
|
|
76
|
+
|
|
45
77
|
/** `tide operator peek <pane> --format json`. Shape per runtime; loose pending schema. */
|
|
46
78
|
export interface TidePeekResult {
|
|
47
79
|
pane?: string
|
|
@@ -58,3 +90,27 @@ export interface TideSteerResult {
|
|
|
58
90
|
export interface TideSendResult {
|
|
59
91
|
[key: string]: unknown
|
|
60
92
|
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Result of a direct `tmux send-keys` performed by `sendKeys()`/`buildSendKeysPlan()`.
|
|
96
|
+
* This is the simple, robust transport the operator cockpit uses to steer a pane
|
|
97
|
+
* without the heavier reviewed-proposal pipeline.
|
|
98
|
+
*
|
|
99
|
+
* `submitted` reflects the "send Enter after content" toggle: when false, the
|
|
100
|
+
* literal text is typed into the pane but NOT submitted (no trailing `C-m`),
|
|
101
|
+
* leaving it on the prompt for the human to review and press Enter themselves.
|
|
102
|
+
*/
|
|
103
|
+
export interface TideSendKeysResult {
|
|
104
|
+
/** Resolved tmux pane target, always `%`-prefixed (e.g. "%56"). */
|
|
105
|
+
target: string
|
|
106
|
+
/** The literal text typed into the pane. */
|
|
107
|
+
message: string
|
|
108
|
+
/** Whether a trailing Enter (`C-m`) was sent after the literal text. */
|
|
109
|
+
submitted: boolean
|
|
110
|
+
/** Exact `tmux send-keys -l` argv used to type the literal text (no shell). */
|
|
111
|
+
literal_command: string[]
|
|
112
|
+
/** Exact `tmux send-keys … C-m` argv used to submit, or null when `submitted` is false. */
|
|
113
|
+
submit_command: string[] | null
|
|
114
|
+
/** ISO timestamp the keys were sent (omitted on a dry-run plan). */
|
|
115
|
+
sent_at?: string
|
|
116
|
+
}
|