@miadi/tide 0.1.1 → 0.1.3

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
@@ -1,21 +1,20 @@
1
1
  # `@miadi/tide`
2
2
 
3
- Typed client boundary between Miadi and the **ironsilk `tide`** runtime (historically
4
- `hermes-navigator`). The single place the web app talks to `tide` — replacing the per-route
3
+ Typed client boundary between Miadi and the **ironsilk `tide`** runtime. The single place the web app talks to `tide` — replacing the per-route
5
4
  `exec("/home/jgi/anaconda3/bin/tide …")` calls.
6
5
 
7
6
  Grounded in `foundations/terminal-workspace-orchestration/` (Decision C) and
8
- `rispecs/hermes-navigator/05-ui-surface.spec.md` (daemon-socket transport).
7
+ `rispecs/tide-runtime/05-ui-surface.spec.md` (daemon-socket transport).
9
8
 
10
9
  ## Runtime dependency — install `tide`
11
10
 
12
11
  This package is a **client**; it does not bundle the runtime. The `tide` CLI is the
13
12
  console entry point of the **`ironsilk`** PyPI package (`[project.scripts]`
14
- `tide = hermes_navigator.cli:main`). Install / upgrade it in the Python env the
13
+ `tide = tide_runtime.cli:main`). Install / upgrade it in the Python env the
15
14
  Next.js server can reach:
16
15
 
17
16
  ```bash
18
- pip install -U ironsilk # provides the `tide` CLI (currently 0.9.13)
17
+ pip install -U ironsilk # provides the `tide` CLI (0.9.27+)
19
18
  tide --help # verify
20
19
  ```
21
20
 
@@ -28,7 +27,7 @@ is outside the server's `PATH`. The daemon socket is resolved separately via
28
27
  ## Verbs
29
28
 
30
29
  ```ts
31
- import { getContext, getTerminals, detect, peek, steerProposal, send, pingDaemon, describeTransport, TideError } from "@miadi/tide"
30
+ import { getContext, getTerminals, detect, peek, steerProposal, send, sendKeys, buildSendKeysPlan, pingDaemon, describeTransport, TideError } from "@miadi/tide"
32
31
 
33
32
  const snapshot = await getContext() // R2 live context (daemon socket → CLI fallback)
34
33
  const terminals = await getTerminals() // operator terminals inventory (CLI, read-only)
@@ -37,10 +36,25 @@ const scroll = await peek("56", 80) // operator peek %56 (CLI)
37
36
  const proposal = await steerProposal("56", "continue from checkpoint") // (CLI)
38
37
  const sent = await send("56", "continue") // guarded --run, controller mode (CLI)
39
38
 
39
+ // Direct, simple steer transport — `tmux send-keys` via execFile (no shell, no Python):
40
+ const keyed = await sendKeys("56", "continue") // types text + Enter
41
+ const noEnter = await sendKeys("56", "ls -la", { submit: false })// types text, leaves it unsubmitted
42
+ const plan = buildSendKeysPlan("56", "ls -la", false) // pure dry-run plan (no execution)
43
+
40
44
  const up = await pingDaemon() // daemon liveness (ping → pong)
41
45
  const how = describeTransport() // { transport: "socket"|"cli", socketPath, socketAvailable }
42
46
  ```
43
47
 
48
+ ### `sendKeys` — the operator cockpit's primary steer path
49
+
50
+ `sendKeys(pane, message, { submit })` drives **`tmux send-keys` directly** through `execFile`
51
+ with argument arrays (no shell, no escaping, no Python spawn, no reviewed-proposal artifact) —
52
+ the simple, robust transport behind `POST /api/tide/steer`. `submit` (default `true`) controls
53
+ the trailing Enter (`C-m`): set it `false` to type content into the pane and leave it on the
54
+ prompt for a human to review and submit. `buildSendKeysPlan(...)` returns the exact `tmux` argv
55
+ pair without executing — used for the cockpit's inline command preview. The tmux binary is
56
+ resolved via `TIDE_TMUX_BIN` -> `tmux` on `PATH`.
57
+
44
58
  `getTerminals` and `detect` are the read-only surface behind `GET /api/tide/terminals`
45
59
  and `GET /api/tide/detect` — the typed half of operator-terminal triage and manual
46
60
  domain assignment (jgwill/Miadi#382). The write-back half (assign a pane to a domain)
@@ -65,10 +79,10 @@ is deferred to the runtime + a guarded route.
65
79
  - **`cli`**: force the CLI.
66
80
 
67
81
  `peek` / `steerProposal` / `send` are **CLI-only**: the daemon exposes `get_context` / `ping` /
68
- `detect`, not the operator mutation verbs. They join the socket path when the runtime adds those
82
+ `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
69
83
  actions — verb signatures are the stable surface; only the transport underneath changes.
70
84
 
71
- ### Wire protocol (mirrors `hermes_navigator/daemon.py`)
85
+ ### Wire protocol (mirrors `tide_runtime/daemon.py`)
72
86
 
73
87
  Newline-delimited JSON over a Unix socket. Request
74
88
  `{contract_version:"hermes.navigator.daemon.v1", request_id, action, payload}` →
@@ -76,7 +90,7 @@ Newline-delimited JSON over a Unix socket. Request
76
90
 
77
91
  ### Socket path resolution
78
92
 
79
- `TIDE_SOCKET` (explicit) → `${HNAVIG_HOME || HERMES_HOME || ~/.miadi/navigator}/daemon.sock`
93
+ `TIDE_SOCKET` (explicit) → `${MIADI_HOME || ~/.miadi/navigator}/daemon.sock`
80
94
  (mirrors the runtime's `get_config_dir()`). Binary resolution for the CLI fallback:
81
95
  `TIDE_BIN` → `which tide` → legacy `/home/jgi/anaconda3/bin/tide`.
82
96
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@miadi/tide",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
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/client.ts CHANGED
@@ -20,6 +20,7 @@ import type {
20
20
  TidePeekResult,
21
21
  TideSendResult,
22
22
  TideSteerResult,
23
+ TideSendKeysResult,
23
24
  } from "./types"
24
25
  import {
25
26
  daemonRequest,
@@ -226,3 +227,91 @@ export function send(pane: string, message: string, opts?: TideRunOptions): Prom
226
227
  { timeoutMs: 10_000, ...opts },
227
228
  )
228
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/socket.ts CHANGED
@@ -2,7 +2,7 @@
2
2
  // versioned Unix-domain-socket protocol so the web layer can read live context
3
3
  // without paying a Python interpreter spawn per request.
4
4
  //
5
- // Wire protocol (mirrors hermes_navigator/daemon.py):
5
+ // Wire protocol (mirrors tide_runtime/daemon.py):
6
6
  // contract: "hermes.navigator.daemon.v1"
7
7
  // transport: newline-delimited JSON over a Unix domain socket
8
8
  // request: {contract_version, request_id, action, payload}
@@ -12,7 +12,7 @@
12
12
  //
13
13
  // Socket path resolution mirrors the runtime's get_config_dir():
14
14
  // TIDE_SOCKET (explicit full path)
15
- // else ${HNAVIG_HOME || HERMES_HOME || ~/.miadi/navigator}/daemon.sock
15
+ // else ${MIADI_HOME || ~/.miadi/navigator}/daemon.sock
16
16
  //
17
17
  // This module never throws synchronously for "daemon absent" — callers test
18
18
  // `isSocketAvailable()` and fall back to the CLI transport (see client.ts).
@@ -33,11 +33,11 @@ function expandHome(p: string): string {
33
33
  return p
34
34
  }
35
35
 
36
- /** Resolve the daemon socket path: `TIDE_SOCKET` → `${HNAVIG_HOME|HERMES_HOME|~/.miadi/navigator}/daemon.sock`. */
36
+ /** Resolve the daemon socket path: `TIDE_SOCKET` -> `${MIADI_HOME|~/.miadi/navigator}/daemon.sock`. */
37
37
  export function resolveSocketPath(): string {
38
38
  const explicit = process.env.TIDE_SOCKET?.trim()
39
39
  if (explicit) return expandHome(explicit)
40
- const home = process.env.HNAVIG_HOME?.trim() || process.env.HERMES_HOME?.trim()
40
+ const home = process.env.MIADI_HOME?.trim()
41
41
  const dir = home ? expandHome(home) : join(homedir(), ".miadi", "navigator")
42
42
  return join(dir, "daemon.sock")
43
43
  }
package/src/types.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  // Typed contract for the ironsilk `tide` runtime (`--format json` output).
2
2
  //
3
- // Source of truth today: runtime/hermes-navigator/hermes_navigator/models.py
3
+ // Source of truth today: runtime/tide-runtime/tide_runtime/models.py
4
4
  // (`ContextSnapshot.to_dict()`, `TerminalContext`). When the schema-first
5
5
  // contract lands (`tide-api.schema.json`), these types are regenerated, not
6
6
  // hand-edited. See README.md.
@@ -90,3 +90,27 @@ export interface TideSteerResult {
90
90
  export interface TideSendResult {
91
91
  [key: string]: unknown
92
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
+ }