@miadi/tide 0.2.3 → 0.3.0
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 +60 -0
- package/package.json +2 -2
- package/src/client.ts +42 -0
- package/src/herdr.ts +271 -22
- package/src/index.ts +17 -0
- package/src/steer-gate.ts +245 -0
package/README.md
CHANGED
|
@@ -79,6 +79,66 @@ reads herdr scrollback through the stable peek verb. Pane-id segments are alphan
|
|
|
79
79
|
> wait output (hit + timeout exit codes), agent-status, and label→id resolution — in
|
|
80
80
|
> addition to the injected-runner tests in `test/herdr.test.ts`.
|
|
81
81
|
|
|
82
|
+
#### Observer inventory + capability advertisement (EP152, live-verified)
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
import { getHerdrSnapshot, describeHerdrCapabilities } from "@miadi/tide"
|
|
86
|
+
|
|
87
|
+
const snap = await getHerdrSnapshot()
|
|
88
|
+
// `herdr api snapshot` — the whole observer inventory in ONE socket round-trip
|
|
89
|
+
// (socket method session.snapshot): workspaces, tabs, panes, detected agents,
|
|
90
|
+
// the focus triple, and the server's version/protocol. Read-only, consistent
|
|
91
|
+
// (no tearing across a workspace/tab/pane list stitch).
|
|
92
|
+
|
|
93
|
+
const caps = await describeHerdrCapabilities()
|
|
94
|
+
// `herdr api schema --json` — capability advertisement DERIVED from the live
|
|
95
|
+
// schema document: { available, protocol, schema_version, methods[] } plus
|
|
96
|
+
// deterministic boolean views (inventory, snapshot, labels, agents,
|
|
97
|
+
// wait_output, wait_events, lifecycle_advertised). `lifecycle_authorized` is
|
|
98
|
+
// constant false: the server ADVERTISING workspace.close does not authorize
|
|
99
|
+
// this client to drive it — that flips only when the closure-receipts ladder
|
|
100
|
+
// lands as code. Never throws: a failed probe returns { available: false,
|
|
101
|
+
// reason } — safe for /api/tide/health.
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Live receipts (herdr 0.7.4, protocol 16, EP152 2026-07-18): 85 advertised socket
|
|
105
|
+
methods, all seven derived flags true, snapshot of 7 workspaces / 22 tabs / 44
|
|
106
|
+
panes / 21 agents. That smoke also showed pane ids go **alphanumeric** past `p9`
|
|
107
|
+
(`w2:pE`, `w7:pA`) — herdr's own schema types `pane_id` as a plain string — so the
|
|
108
|
+
client id pattern accepts the family agreed with `@miadi/tide-contract` 0.2.3:
|
|
109
|
+
`w[0-9A-Za-z]+:p[0-9A-Za-z]+` (the dashed legacy form stays digits-only).
|
|
110
|
+
|
|
111
|
+
#### Steer gate — ACTIVE_CONTROLLER + TTY + live target (EP152 wave-2)
|
|
112
|
+
|
|
113
|
+
Every steer **execution** (`sendKeys` tmux + herdr, `sendKeysViaHerdr`,
|
|
114
|
+
`runInHerdrPane`) passes the 3-part gate ported from the Python runtime's
|
|
115
|
+
`tide operator send --run` boundary (`src/steer-gate.ts`):
|
|
116
|
+
|
|
117
|
+
1. **live-resolved target** — the pane must appear in the CURRENT multiplexer
|
|
118
|
+
inventory (`tmux list-panes -a` / `herdr pane list`; label resolution counts
|
|
119
|
+
as live proof);
|
|
120
|
+
2. **ACTIVE_CONTROLLER posture** — `mode: controller` in
|
|
121
|
+
`${MIADI_HOME|~/.miadi/navigator}/config.yml`, with the controller TTL lease
|
|
122
|
+
applied on every read (an expired lease reads as observer, fail-closed);
|
|
123
|
+
3. **interactive local TTY** — or `TIDE_ALLOW_NON_INTERACTIVE_RUN=1` set by an
|
|
124
|
+
approval-queue-fronted service after its own review.
|
|
125
|
+
|
|
126
|
+
A refused steer throws `TideError` naming **every** failed check and never
|
|
127
|
+
touches the multiplexer. Plan builders (`buildSendKeysPlan`,
|
|
128
|
+
`buildHerdrSendKeysPlan`) stay ungated — dry-run is the covenant's default
|
|
129
|
+
posture. `evaluateSteerGate`/`requireSteerGate`/`readNavigatorPosture` are
|
|
130
|
+
exported for `/api/tide/health`-style surfaces. The `gate` option injects
|
|
131
|
+
probes (tests, first-party wiring); it cannot disable the gate, and overrides
|
|
132
|
+
are only accepted when branded by `trustSteerGateProbes()` — which is NOT on
|
|
133
|
+
the package surface (direct module import only; the brand is a module-private
|
|
134
|
+
non-enumerable Symbol, so JSON/request-derived gate options are structurally
|
|
135
|
+
refused).
|
|
136
|
+
|
|
137
|
+
Label hardening (same wave): resolution is NFC-normalized, label-only (the
|
|
138
|
+
`title` fallback is gone), **duplicate labels are a hard refusal**, and
|
|
139
|
+
`{ workspace: "w7" }` scopes resolution. Wrong-multiplexer dispatch fails
|
|
140
|
+
loudly in both directions (a herdr-shaped id on the tmux path and vice versa).
|
|
141
|
+
|
|
82
142
|
`getTerminals` and `detect` are the read-only surface behind `GET /api/tide/terminals`
|
|
83
143
|
and `GET /api/tide/detect` — the typed half of operator-terminal triage and manual
|
|
84
144
|
domain assignment (jgwill/Miadi#382). The write-back half (assign a pane to a domain)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@miadi/tide",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
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.4"
|
|
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
|
@@ -49,6 +49,8 @@ import {
|
|
|
49
49
|
sendKeysViaHerdr,
|
|
50
50
|
} from "./herdr"
|
|
51
51
|
import type { HerdrCommandRunner } from "./herdr"
|
|
52
|
+
import { requireSteerGate, acceptGateOverrides } from "./steer-gate"
|
|
53
|
+
import type { SteerGateOverrides } from "./steer-gate"
|
|
52
54
|
|
|
53
55
|
const pExecFile = promisify(execFile)
|
|
54
56
|
|
|
@@ -304,6 +306,27 @@ export interface SendKeysOptions extends TideRunOptions {
|
|
|
304
306
|
paneLabel?: string
|
|
305
307
|
/** herdr only: injected command runner (tests). */
|
|
306
308
|
runner?: HerdrCommandRunner
|
|
309
|
+
/**
|
|
310
|
+
* Steer-gate probe overrides (test seam / cockpit injection). The gate
|
|
311
|
+
* itself cannot be disabled — these only answer its three questions
|
|
312
|
+
* (live target, ACTIVE_CONTROLLER posture, interactive TTY). See
|
|
313
|
+
* steer-gate.ts (EP152 wave-2 W1).
|
|
314
|
+
*/
|
|
315
|
+
gate?: SteerGateOverrides
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
/**
|
|
319
|
+
* Steer-gate liveness probe for the tmux path: the `%N` target must appear in
|
|
320
|
+
* the CURRENT `tmux list-panes -a` inventory (the direct-transport analog of
|
|
321
|
+
* the Python gate's `resolution_status == "resolved"`). Read-only.
|
|
322
|
+
*/
|
|
323
|
+
async function tmuxTargetResolved(
|
|
324
|
+
target: string,
|
|
325
|
+
bin: string,
|
|
326
|
+
runOpts: { timeout: number; cwd?: string },
|
|
327
|
+
): Promise<boolean> {
|
|
328
|
+
const { stdout } = await pExecFile(bin, ["list-panes", "-a", "-F", "#{pane_id}"], runOpts)
|
|
329
|
+
return stdout.split("\n").some((line) => line.trim() === target)
|
|
307
330
|
}
|
|
308
331
|
|
|
309
332
|
/**
|
|
@@ -336,6 +359,11 @@ export function buildSendKeysPlan(
|
|
|
336
359
|
* separate `C-m` submits it. If the literal step succeeds but the submit step
|
|
337
360
|
* fails, the text is already on the pane's prompt (unsubmitted) — the thrown
|
|
338
361
|
* `TideError` names which step failed so the caller can surface that partial state.
|
|
362
|
+
*
|
|
363
|
+
* Execution is steer-gated (EP152 wave-2 W1, both multiplexers): live-resolved
|
|
364
|
+
* target + ACTIVE_CONTROLLER posture + interactive TTY (or approval-fronted
|
|
365
|
+
* `TIDE_ALLOW_NON_INTERACTIVE_RUN=1`) — the same 3-part boundary as
|
|
366
|
+
* `tide operator send --run`. `buildSendKeysPlan` stays ungated (dry-run).
|
|
339
367
|
*/
|
|
340
368
|
export async function sendKeys(
|
|
341
369
|
pane: string,
|
|
@@ -354,10 +382,24 @@ export async function sendKeys(
|
|
|
354
382
|
`sendKeys: "paneLabel"/"runner" are herdr-only options — pass multiplexer: "herdr"`,
|
|
355
383
|
)
|
|
356
384
|
}
|
|
385
|
+
// Wrong-multiplexer dispatch assertion (EP152 wave-2 W2): a herdr-shaped id
|
|
386
|
+
// on the tmux path would be blindly %-prefixed into a bogus tmux target
|
|
387
|
+
// ("%w1:p2") — or worse, parse as tmux session:window syntax. Fail loudly.
|
|
388
|
+
if (HERDR_PANE_ID_PATTERN.test(pane.trim())) {
|
|
389
|
+
throw new TideError(
|
|
390
|
+
`"${pane.trim()}" is a herdr pane id but the tmux path was selected — pass multiplexer:"herdr" to steer herdr panes`,
|
|
391
|
+
)
|
|
392
|
+
}
|
|
357
393
|
const submit = opts.submit ?? true
|
|
358
394
|
const plan = buildSendKeysPlan(pane, message, submit)
|
|
359
395
|
const bin = resolveTmuxBin()
|
|
360
396
|
const runOpts = { timeout: opts.timeoutMs ?? 10_000, cwd: opts.cwd }
|
|
397
|
+
const gate = acceptGateOverrides(opts.gate)
|
|
398
|
+
await requireSteerGate({
|
|
399
|
+
...gate,
|
|
400
|
+
target: plan.target,
|
|
401
|
+
resolveTarget: gate.resolveTarget ?? (() => tmuxTargetResolved(plan.target, bin, runOpts)),
|
|
402
|
+
})
|
|
361
403
|
try {
|
|
362
404
|
await pExecFile(bin, plan.literal_command, runOpts)
|
|
363
405
|
} catch (err) {
|
package/src/herdr.ts
CHANGED
|
@@ -13,6 +13,8 @@
|
|
|
13
13
|
// wait output <id> --match … [--regex] --timeout ms (JSON)
|
|
14
14
|
// wait agent-status <id> --status … --timeout ms (JSON)
|
|
15
15
|
// workspace list | tab list --workspace <id> | pane list (JSON)
|
|
16
|
+
// api snapshot one-call observer inventory (JSON)
|
|
17
|
+
// api schema --json capability advertisement source (JSON)
|
|
16
18
|
//
|
|
17
19
|
// herdr pane ids are "w<N>:p<M>" (e.g. "w1:p2") as of herdr 0.7; the legacy
|
|
18
20
|
// dashed "1-2" form is still accepted for older releases. Live smoke against
|
|
@@ -41,6 +43,8 @@ import type {
|
|
|
41
43
|
TideHerdrWorkspaceInfo,
|
|
42
44
|
} from "@miadi/tide-contract"
|
|
43
45
|
import { TideError } from "./errors"
|
|
46
|
+
import { requireSteerGate, acceptGateOverrides } from "./steer-gate"
|
|
47
|
+
import type { SteerGateOverrides } from "./steer-gate"
|
|
44
48
|
import type { TideRunOptions } from "./client"
|
|
45
49
|
|
|
46
50
|
const pExecFile = promisify(execFile)
|
|
@@ -126,17 +130,24 @@ function parseHerdrJson<T>(stdout: string, what: string): T {
|
|
|
126
130
|
// ── Pane targets and label→id resolution ────────────────────────────────────
|
|
127
131
|
|
|
128
132
|
// "w1:p2" is the live herdr 0.7 format; the dashed "1-2" form is legacy.
|
|
129
|
-
//
|
|
130
|
-
//
|
|
131
|
-
//
|
|
133
|
+
// BOTH segments are ALPHANUMERIC, not digits-only: live herdr 0.7.4 (EP152,
|
|
134
|
+
// 2026-07-18) lists ids like "w2:pE" and "w2:pQ" once a workspace has grown
|
|
135
|
+
// past p9, and herdr's own API schema (`herdr api schema --json`, protocol 16)
|
|
136
|
+
// types pane_id as a plain string with no pattern. This is the ONE pattern
|
|
137
|
+
// family agreed with the tide-contract lineage (npm 0.2.3, EP152 wave-2
|
|
138
|
+
// reconciliation): w[0-9A-Za-z]+:p[0-9A-Za-z]+. The legacy dashed form stays
|
|
139
|
+
// digits-only as observed on older releases.
|
|
132
140
|
export const HERDR_PANE_ID_PATTERN = /^(w[0-9A-Za-z]+:p[0-9A-Za-z]+|[0-9]+-[0-9]+)$/
|
|
133
141
|
|
|
134
142
|
/** Validate a herdr pane id (e.g. "w1:p2"). Unlike tmux there is no `%` prefix to add. */
|
|
135
143
|
export function normalizeHerdrPaneTarget(pane: string): string {
|
|
136
144
|
const trimmed = pane.trim()
|
|
137
145
|
if (!HERDR_PANE_ID_PATTERN.test(trimmed)) {
|
|
146
|
+
const tmuxHint = /^%?[0-9]+$/.test(trimmed)
|
|
147
|
+
? `; "${trimmed}" looks like a tmux pane id — pass multiplexer:"tmux" (or omit multiplexer) for tmux panes`
|
|
148
|
+
: ""
|
|
138
149
|
throw new TideError(
|
|
139
|
-
`invalid herdr pane id "${pane}" (expected "w<workspace>:p<pane>", e.g. "w1:p2"); herdr ids are session-scoped — pass paneLabel to resolve by label instead`,
|
|
150
|
+
`invalid herdr pane id "${pane}" (expected "w<workspace>:p<pane>", e.g. "w1:p2"); herdr ids are session-scoped — pass paneLabel to resolve by label instead${tmuxHint}`,
|
|
140
151
|
)
|
|
141
152
|
}
|
|
142
153
|
return trimmed
|
|
@@ -145,7 +156,8 @@ export function normalizeHerdrPaneTarget(pane: string): string {
|
|
|
145
156
|
/**
|
|
146
157
|
* One row from `herdr pane list` — the covenant shape (tide-contract 0.2.2's
|
|
147
158
|
* `TideHerdrPaneInfo`) plus a `title` field tolerated for other herdr builds
|
|
148
|
-
* (live 0.7.4 rows never carry it; resolution
|
|
159
|
+
* (live 0.7.4 rows never carry it; label→id resolution is label-ONLY — the
|
|
160
|
+
* title fallback was removed by the EP152 wave-2 W2 hardening).
|
|
149
161
|
*/
|
|
150
162
|
export interface HerdrPaneInfo extends TideHerdrPaneInfo {
|
|
151
163
|
title?: string
|
|
@@ -222,34 +234,227 @@ export async function getHerdrInventory(opts: HerdrInventoryOptions = {}): Promi
|
|
|
222
234
|
return inventory
|
|
223
235
|
}
|
|
224
236
|
|
|
237
|
+
// ── Daemon-facing observer inventory + capability advertisement (EP152) ─────
|
|
238
|
+
|
|
239
|
+
/**
|
|
240
|
+
* The `result.snapshot` payload of `herdr api snapshot` — the whole observer
|
|
241
|
+
* inventory in ONE round-trip over the herdr unix socket (socket method
|
|
242
|
+
* `session.snapshot`): every workspace, tab, pane, and detected agent, plus
|
|
243
|
+
* the focus triple and the server's version/protocol. Loosely typed like
|
|
244
|
+
* HerdrPaneInfo: the named fields are the ones observed live on herdr 0.7.4
|
|
245
|
+
* (EP152, 2026-07-18); unknown fields pass through.
|
|
246
|
+
*/
|
|
247
|
+
export interface HerdrSnapshot {
|
|
248
|
+
version?: string
|
|
249
|
+
protocol?: number
|
|
250
|
+
focused_workspace_id?: string | null
|
|
251
|
+
focused_tab_id?: string | null
|
|
252
|
+
focused_pane_id?: string | null
|
|
253
|
+
workspaces?: HerdrWorkspaceInfo[]
|
|
254
|
+
tabs?: HerdrTabInfo[]
|
|
255
|
+
panes?: HerdrPaneInfo[]
|
|
256
|
+
/** Panes with a detected agent — same row shape as `panes`, minus `scroll`. */
|
|
257
|
+
agents?: HerdrPaneInfo[]
|
|
258
|
+
layouts?: unknown[]
|
|
259
|
+
[key: string]: unknown
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* `herdr api snapshot` — the smallest daemon-facing observer inventory:
|
|
264
|
+
* read-only, one CLI call, one socket round-trip underneath. Prefer this over
|
|
265
|
+
* stitching `workspace list` + `tab list` + `pane list` when a whole-instance
|
|
266
|
+
* view is needed (the three-call stitch can tear across concurrent changes;
|
|
267
|
+
* the snapshot is one consistent read).
|
|
268
|
+
*/
|
|
269
|
+
export async function getHerdrSnapshot(opts: HerdrRunOptions = {}): Promise<HerdrSnapshot> {
|
|
270
|
+
const { stdout } = await runHerdr(["api", "snapshot"], opts)
|
|
271
|
+
const payload = parseHerdrJson<unknown>(stdout, "api snapshot")
|
|
272
|
+
const env = payload as { result?: { snapshot?: unknown }; snapshot?: unknown } | null
|
|
273
|
+
const snap = env?.result?.snapshot ?? env?.snapshot
|
|
274
|
+
if (!snap || typeof snap !== "object" || Array.isArray(snap)) {
|
|
275
|
+
throw new TideError("herdr api snapshot returned an unexpected JSON shape")
|
|
276
|
+
}
|
|
277
|
+
return snap as HerdrSnapshot
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
/**
|
|
281
|
+
* Capability advertisement for the herdr backend, DERIVED live from
|
|
282
|
+
* `herdr api schema --json` (a bare JSON-schema document: protocol,
|
|
283
|
+
* schema_version, and `schemas.request.oneOf[*].properties.method.const` —
|
|
284
|
+
* 85 socket methods on herdr 0.7.4 / protocol 16). Nothing here is
|
|
285
|
+
* hard-coded per herdr version: a herdr that gains or loses a method
|
|
286
|
+
* advertises differently. The boolean views are deterministic reads over
|
|
287
|
+
* `methods` in the MISSION vocabulary (inventory / snapshot / labels /
|
|
288
|
+
* agents / wait / lifecycle).
|
|
289
|
+
*/
|
|
290
|
+
export interface HerdrCapabilities {
|
|
291
|
+
multiplexer: "herdr"
|
|
292
|
+
/** False when the schema probe failed (binary missing, server down, bad JSON). */
|
|
293
|
+
available: boolean
|
|
294
|
+
/** Binary the probe used (TIDE_HERDR_BIN → "herdr" on PATH). */
|
|
295
|
+
binary: string
|
|
296
|
+
/** Socket protocol number from the schema document (16 on herdr 0.7.4). */
|
|
297
|
+
protocol: number | null
|
|
298
|
+
schema_version: number | null
|
|
299
|
+
/** Sorted socket method ids, e.g. "pane.list", "session.snapshot". */
|
|
300
|
+
methods: string[]
|
|
301
|
+
/** Why the probe failed, when `available` is false. */
|
|
302
|
+
reason?: string
|
|
303
|
+
/** workspace.list + tab.list + pane.list */
|
|
304
|
+
inventory: boolean
|
|
305
|
+
/** session.snapshot (the one-call observer inventory above) */
|
|
306
|
+
snapshot: boolean
|
|
307
|
+
/** pane.rename — durable labels for session-scoped pane ids */
|
|
308
|
+
labels: boolean
|
|
309
|
+
/** agent.list — detected-agent inventory with agent_status */
|
|
310
|
+
agents: boolean
|
|
311
|
+
/** pane.wait_for_output */
|
|
312
|
+
wait_output: boolean
|
|
313
|
+
/** events.wait — event subscription (agent-status waits ride on it) */
|
|
314
|
+
wait_events: boolean
|
|
315
|
+
/**
|
|
316
|
+
* workspace.create + tab.create + pane.split + pane.close are ADVERTISED by
|
|
317
|
+
* the server schema. Advertised is not authorized (W10b): the server
|
|
318
|
+
* answering a method exists says nothing about whether this client may
|
|
319
|
+
* drive it.
|
|
320
|
+
*/
|
|
321
|
+
lifecycle_advertised: boolean
|
|
322
|
+
/**
|
|
323
|
+
* Whether THIS CLIENT is authorized to drive lifecycle mutation
|
|
324
|
+
* (create/split/close). Constant `false`: the EP152 safety ladder
|
|
325
|
+
* (G0 observe → … → G4 close) and William's per-unit gate exist as mission
|
|
326
|
+
* law, not yet as code — no lifecycle verb ships in @miadi/tide until the
|
|
327
|
+
* closure-receipts contract does. Flips only with that implementation.
|
|
328
|
+
*/
|
|
329
|
+
lifecycle_authorized: false
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
function extractSchemaMethods(doc: unknown): {
|
|
333
|
+
protocol: number | null
|
|
334
|
+
schema_version: number | null
|
|
335
|
+
methods: string[]
|
|
336
|
+
} {
|
|
337
|
+
const d = doc as {
|
|
338
|
+
protocol?: unknown
|
|
339
|
+
schema_version?: unknown
|
|
340
|
+
schemas?: { request?: { oneOf?: unknown } }
|
|
341
|
+
} | null
|
|
342
|
+
const variants = d?.schemas?.request?.oneOf
|
|
343
|
+
if (!Array.isArray(variants)) {
|
|
344
|
+
throw new TideError("herdr api schema returned an unexpected JSON shape (no schemas.request.oneOf)")
|
|
345
|
+
}
|
|
346
|
+
const methods = new Set<string>()
|
|
347
|
+
for (const v of variants) {
|
|
348
|
+
const m = (v as { properties?: { method?: { const?: unknown } } } | null)?.properties?.method?.const
|
|
349
|
+
if (typeof m === "string") methods.add(m)
|
|
350
|
+
}
|
|
351
|
+
return {
|
|
352
|
+
protocol: typeof d?.protocol === "number" ? d.protocol : null,
|
|
353
|
+
schema_version: typeof d?.schema_version === "number" ? d.schema_version : null,
|
|
354
|
+
methods: [...methods].sort(),
|
|
355
|
+
}
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
/**
|
|
359
|
+
* Probe the live herdr for its advertised capabilities. NEVER throws — a
|
|
360
|
+
* failed probe returns `available: false` with a `reason`, so cockpit health
|
|
361
|
+
* endpoints can call this unconditionally next to describeTransport().
|
|
362
|
+
*/
|
|
363
|
+
export async function describeHerdrCapabilities(opts: HerdrRunOptions = {}): Promise<HerdrCapabilities> {
|
|
364
|
+
const binary = resolveHerdrBin()
|
|
365
|
+
const unavailable = (reason: string): HerdrCapabilities => ({
|
|
366
|
+
multiplexer: "herdr",
|
|
367
|
+
available: false,
|
|
368
|
+
binary,
|
|
369
|
+
protocol: null,
|
|
370
|
+
schema_version: null,
|
|
371
|
+
methods: [],
|
|
372
|
+
reason,
|
|
373
|
+
inventory: false,
|
|
374
|
+
snapshot: false,
|
|
375
|
+
labels: false,
|
|
376
|
+
agents: false,
|
|
377
|
+
wait_output: false,
|
|
378
|
+
wait_events: false,
|
|
379
|
+
lifecycle_advertised: false,
|
|
380
|
+
lifecycle_authorized: false,
|
|
381
|
+
})
|
|
382
|
+
try {
|
|
383
|
+
const { stdout } = await runHerdr(["api", "schema", "--json"], opts)
|
|
384
|
+
const { protocol, schema_version, methods } = extractSchemaMethods(
|
|
385
|
+
parseHerdrJson<unknown>(stdout, "api schema"),
|
|
386
|
+
)
|
|
387
|
+
const has = (m: string) => methods.includes(m)
|
|
388
|
+
return {
|
|
389
|
+
multiplexer: "herdr",
|
|
390
|
+
available: true,
|
|
391
|
+
binary,
|
|
392
|
+
protocol,
|
|
393
|
+
schema_version,
|
|
394
|
+
methods,
|
|
395
|
+
inventory: has("workspace.list") && has("tab.list") && has("pane.list"),
|
|
396
|
+
snapshot: has("session.snapshot"),
|
|
397
|
+
labels: has("pane.rename"),
|
|
398
|
+
agents: has("agent.list"),
|
|
399
|
+
wait_output: has("pane.wait_for_output"),
|
|
400
|
+
wait_events: has("events.wait"),
|
|
401
|
+
lifecycle_advertised:
|
|
402
|
+
has("workspace.create") && has("tab.create") && has("pane.split") && has("pane.close"),
|
|
403
|
+
lifecycle_authorized: false,
|
|
404
|
+
}
|
|
405
|
+
} catch (err) {
|
|
406
|
+
return unavailable(err instanceof Error ? err.message : String(err))
|
|
407
|
+
}
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
export interface HerdrResolveOptions extends HerdrRunOptions {
|
|
411
|
+
/**
|
|
412
|
+
* Scope label resolution to one workspace (`workspace_id`, e.g. "w7").
|
|
413
|
+
* Labels are only unique per operator discipline, not by herdr — scoping
|
|
414
|
+
* shrinks the collision surface (EP152 wave-2 W2 hardening).
|
|
415
|
+
*/
|
|
416
|
+
workspace?: string
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
/** Labels compare NFC-normalized: "é" typed composed and decomposed must be the same pane. */
|
|
420
|
+
const nfc = (s: string) => s.normalize("NFC")
|
|
421
|
+
|
|
225
422
|
/**
|
|
226
423
|
* Resolve a durable pane label to the CURRENT herdr pane id via `pane list`.
|
|
227
424
|
* Runs before every action when a label is given — herdr ids are
|
|
228
425
|
* session-scoped (a herdr restart resets them), so a cached id can go stale.
|
|
229
426
|
* Live 0.7.4: a stale id fails loudly with pane_not_found (ids are never
|
|
230
|
-
* reused within a session); `pane rename` sets the `label` field matched here
|
|
427
|
+
* reused within a session); `pane rename` sets the `label` field matched here
|
|
428
|
+
* (matching is label-only — live 0.7.4 rows carry no `title` field, and the
|
|
429
|
+
* old title fallback could silently hit an unrelated pane on other builds).
|
|
430
|
+
*
|
|
431
|
+
* Hardening (EP152 wave-2 W2, adversarial findings): matching is
|
|
432
|
+
* NFC-normalized, and a DUPLICATE label is a hard refusal — first-match on an
|
|
433
|
+
* order-unstable inventory could steer the wrong agent. Rename the panes or
|
|
434
|
+
* scope with `{ workspace }`.
|
|
231
435
|
*/
|
|
232
|
-
export async function resolveHerdrPaneId(paneLabel: string, opts:
|
|
233
|
-
const label = paneLabel.trim()
|
|
436
|
+
export async function resolveHerdrPaneId(paneLabel: string, opts: HerdrResolveOptions = {}): Promise<string> {
|
|
437
|
+
const label = nfc(paneLabel.trim())
|
|
234
438
|
const panes = await listHerdrPanes(opts)
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
if (matches.length === 0
|
|
439
|
+
const scoped = opts.workspace ? panes.filter((p) => p.workspace_id === opts.workspace) : panes
|
|
440
|
+
const matches = scoped.filter((p) => typeof p.label === "string" && nfc(p.label) === label)
|
|
441
|
+
const where = opts.workspace ? ` in workspace ${opts.workspace}` : ""
|
|
442
|
+
if (matches.length === 0 || !matches[0]?.pane_id) {
|
|
443
|
+
throw new TideError(`no herdr pane labeled "${paneLabel.trim()}"${where} in \`herdr pane list\``)
|
|
444
|
+
}
|
|
239
445
|
if (matches.length > 1) {
|
|
240
|
-
const
|
|
446
|
+
const seen = matches
|
|
447
|
+
.map((p) => `${p.pane_id ?? "?"} (workspace ${p.workspace_id ?? "?"})`)
|
|
448
|
+
.join(", ")
|
|
241
449
|
throw new TideError(
|
|
242
|
-
`
|
|
450
|
+
`duplicate herdr pane label "${paneLabel.trim()}"${where}: ${seen} — refusing first-match steering; ` +
|
|
451
|
+
"rename the panes (`herdr pane rename`) or scope the resolution with { workspace }",
|
|
243
452
|
)
|
|
244
453
|
}
|
|
245
|
-
|
|
246
|
-
if (!match?.pane_id) {
|
|
247
|
-
throw new TideError(`no herdr pane labeled "${label}" in \`herdr pane list\``)
|
|
248
|
-
}
|
|
249
|
-
return match.pane_id
|
|
454
|
+
return matches[0].pane_id
|
|
250
455
|
}
|
|
251
456
|
|
|
252
|
-
export interface HerdrTargetOptions extends
|
|
457
|
+
export interface HerdrTargetOptions extends HerdrResolveOptions {
|
|
253
458
|
/**
|
|
254
459
|
* Durable pane label; when set it wins over the pane id argument and is
|
|
255
460
|
* re-resolved to the current id at action time.
|
|
@@ -268,6 +473,12 @@ function resolveTarget(pane: string, opts: HerdrTargetOptions): Promise<string>
|
|
|
268
473
|
export interface HerdrSendKeysOptions extends HerdrTargetOptions {
|
|
269
474
|
/** Send a real Enter key after the literal text. Default true (mirrors the tmux path). */
|
|
270
475
|
submit?: boolean
|
|
476
|
+
/**
|
|
477
|
+
* Steer-gate probe overrides (test seam / cockpit injection). The gate
|
|
478
|
+
* itself cannot be disabled — these only answer its questions. See
|
|
479
|
+
* steer-gate.ts (EP152 wave-2 W1).
|
|
480
|
+
*/
|
|
481
|
+
gate?: SteerGateOverrides
|
|
271
482
|
}
|
|
272
483
|
|
|
273
484
|
/**
|
|
@@ -308,12 +519,29 @@ export function buildHerdrSendKeysPlan(
|
|
|
308
519
|
return makeHerdrSendKeysPlan(normalizeHerdrPaneTarget(pane), message, submit, paneLabel)
|
|
309
520
|
}
|
|
310
521
|
|
|
522
|
+
/**
|
|
523
|
+
* Liveness probe for the steer gate: label resolution IS live proof (herdr
|
|
524
|
+
* just returned the id); a raw id must appear in the current `pane list`.
|
|
525
|
+
*/
|
|
526
|
+
function herdrTargetResolved(target: string, viaLabel: boolean, opts: HerdrRunOptions): () => Promise<boolean> {
|
|
527
|
+
if (viaLabel) return async () => true
|
|
528
|
+
return async () => {
|
|
529
|
+
const panes = await listHerdrPanes(opts)
|
|
530
|
+
return panes.some((p) => p.pane_id === target)
|
|
531
|
+
}
|
|
532
|
+
}
|
|
533
|
+
|
|
311
534
|
/**
|
|
312
535
|
* Steer a herdr pane: type `message` via `herdr pane send-text`, then submit a
|
|
313
536
|
* real Enter via `herdr pane send-keys … Enter` unless `submit: false`. Same
|
|
314
537
|
* two-step semantics as the tmux path: if the literal step succeeds but the
|
|
315
538
|
* submit step fails, the text is left on the pane unsubmitted and the thrown
|
|
316
539
|
* TideError names which step failed.
|
|
540
|
+
*
|
|
541
|
+
* Execution is steer-gated (EP152 wave-2 W1): live-resolved target +
|
|
542
|
+
* ACTIVE_CONTROLLER posture + interactive TTY (or approval-fronted override)
|
|
543
|
+
* — the same 3-part boundary as `tide operator send --run`. Plan builders
|
|
544
|
+
* stay ungated (dry-run is the default posture of the covenant).
|
|
317
545
|
*/
|
|
318
546
|
export async function sendKeysViaHerdr(
|
|
319
547
|
pane: string,
|
|
@@ -322,6 +550,12 @@ export async function sendKeysViaHerdr(
|
|
|
322
550
|
): Promise<TideHerdrSendKeysResult> {
|
|
323
551
|
// resolveTarget validates caller-supplied ids and trusts label-resolved ones.
|
|
324
552
|
const target = await resolveTarget(pane, opts)
|
|
553
|
+
const gate = acceptGateOverrides(opts.gate)
|
|
554
|
+
await requireSteerGate({
|
|
555
|
+
...gate,
|
|
556
|
+
target,
|
|
557
|
+
resolveTarget: gate.resolveTarget ?? herdrTargetResolved(target, opts.paneLabel !== undefined, opts),
|
|
558
|
+
})
|
|
325
559
|
const plan = makeHerdrSendKeysPlan(target, message, opts.submit ?? true, opts.paneLabel)
|
|
326
560
|
const runner = makeRunner(opts)
|
|
327
561
|
const bin = resolveHerdrBin()
|
|
@@ -362,13 +596,28 @@ export async function renameHerdrPane(
|
|
|
362
596
|
await runHerdr(["pane", "rename", target, label], opts)
|
|
363
597
|
}
|
|
364
598
|
|
|
365
|
-
|
|
599
|
+
export interface HerdrRunInPaneOptions extends HerdrTargetOptions {
|
|
600
|
+
/** Steer-gate probe overrides — see HerdrSendKeysOptions.gate. */
|
|
601
|
+
gate?: SteerGateOverrides
|
|
602
|
+
}
|
|
603
|
+
|
|
604
|
+
/**
|
|
605
|
+
* `herdr pane run <id> <command>` — send the text and a real Enter in one
|
|
606
|
+
* request. Steer-gated like sendKeysViaHerdr (W1-adjacent: same mutation
|
|
607
|
+
* power, same boundary — an ungated `pane run` would make the gate decorative).
|
|
608
|
+
*/
|
|
366
609
|
export async function runInHerdrPane(
|
|
367
610
|
pane: string,
|
|
368
611
|
command: string,
|
|
369
|
-
opts:
|
|
612
|
+
opts: HerdrRunInPaneOptions = {},
|
|
370
613
|
): Promise<void> {
|
|
371
614
|
const target = await resolveTarget(pane, opts)
|
|
615
|
+
const gate = acceptGateOverrides(opts.gate)
|
|
616
|
+
await requireSteerGate({
|
|
617
|
+
...gate,
|
|
618
|
+
target,
|
|
619
|
+
resolveTarget: gate.resolveTarget ?? herdrTargetResolved(target, opts.paneLabel !== undefined, opts),
|
|
620
|
+
})
|
|
372
621
|
await runHerdr(["pane", "run", target, command], opts)
|
|
373
622
|
}
|
|
374
623
|
|
package/src/index.ts
CHANGED
|
@@ -2,6 +2,23 @@ export * from "./types"
|
|
|
2
2
|
export * from "./socket"
|
|
3
3
|
export * from "./client"
|
|
4
4
|
export * from "./herdr"
|
|
5
|
+
// steer-gate: explicit exports — trustSteerGateProbes/acceptGateOverrides are
|
|
6
|
+
// deliberately NOT on the package surface (W10a: the test seam must be a
|
|
7
|
+
// direct-module import, never a consumer API).
|
|
8
|
+
export {
|
|
9
|
+
STEER_BOUNDARY,
|
|
10
|
+
resolveNavigatorDir,
|
|
11
|
+
readNavigatorPosture,
|
|
12
|
+
evaluateSteerGate,
|
|
13
|
+
requireSteerGate,
|
|
14
|
+
} from "./steer-gate"
|
|
15
|
+
export type {
|
|
16
|
+
SteerPostureMode,
|
|
17
|
+
SteerPosture,
|
|
18
|
+
SteerGateOverrides,
|
|
19
|
+
SteerGateInputs,
|
|
20
|
+
SteerGateDecision,
|
|
21
|
+
} from "./steer-gate"
|
|
5
22
|
export type {
|
|
6
23
|
EpisodeLaneTopology,
|
|
7
24
|
TideLaneCheckpoint,
|
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
// Steer-layer approval gate for @miadi/tide — the TypeScript port of the
|
|
2
|
+
// Python runtime's 3-part guarded-send gate (EP152 wave-2 W1; adversarial
|
|
3
|
+
// finding: sendKeys/sendKeysViaHerdr executed with no posture, no TTY, no
|
|
4
|
+
// approval artifact while `tide operator send --run` enforced all three).
|
|
5
|
+
//
|
|
6
|
+
// Python source of record (runtime/tide-runtime):
|
|
7
|
+
// terminal_send.py SEND_BOUNDARY — the covenant string, reproduced below
|
|
8
|
+
// cli.py operator_send / _require_controller_execution — enforcement order:
|
|
9
|
+
// 1. resolution_status == "resolved" (target visible in LIVE inventory)
|
|
10
|
+
// 2. cfg.mode == NavigatorMode.ACTIVE_CONTROLLER (wire value "controller"
|
|
11
|
+
// in ${MIADI_HOME|~/.miadi/navigator}/config.yml; observer default)
|
|
12
|
+
// 3. stdin.isatty() OR TIDE_ALLOW_NON_INTERACTIVE_RUN=1 (Tide Studio /
|
|
13
|
+
// approval-queue-fronted services set the env after their own review)
|
|
14
|
+
// config.py _controller_ttl_expired — a controller lease older than
|
|
15
|
+
// controller.ttl_minutes (default 30, 0 = no expiry) counts as observer.
|
|
16
|
+
// Python persists that downgrade when IT loads config; this reader cannot
|
|
17
|
+
// write, so it applies the same expiry arithmetic on every read.
|
|
18
|
+
//
|
|
19
|
+
// The gate is multiplexer-agnostic: callers (tmux client.ts, herdr herdr.ts)
|
|
20
|
+
// compute target liveness their own way and pass the probes in. Every probe
|
|
21
|
+
// is injectable (the test seam); none of the injection points can DISABLE the
|
|
22
|
+
// gate — they only answer its three questions.
|
|
23
|
+
|
|
24
|
+
import { readFileSync } from "node:fs"
|
|
25
|
+
import { homedir } from "node:os"
|
|
26
|
+
import { join } from "node:path"
|
|
27
|
+
|
|
28
|
+
import { TideError } from "./errors"
|
|
29
|
+
|
|
30
|
+
/** Verbatim covenant string from terminal_send.py (SEND_BOUNDARY). */
|
|
31
|
+
export const STEER_BOUNDARY =
|
|
32
|
+
"explicit target, reviewed message source, dry-run by default, " +
|
|
33
|
+
"ACTIVE_CONTROLLER + interactive local TTY required for send"
|
|
34
|
+
|
|
35
|
+
/** Wire values from tide_runtime.models.NavigatorMode ("controller", not "active_controller"). */
|
|
36
|
+
export type SteerPostureMode = "observer" | "controller" | "unknown"
|
|
37
|
+
|
|
38
|
+
export interface SteerPosture {
|
|
39
|
+
/** Effective mode after TTL arithmetic — an expired controller lease reads as "observer". */
|
|
40
|
+
mode: SteerPostureMode
|
|
41
|
+
/** Where the posture came from (config path, or "default: observer" when absent). */
|
|
42
|
+
source: string
|
|
43
|
+
enabled_at?: string
|
|
44
|
+
ttl_minutes?: number
|
|
45
|
+
/** True when config said "controller" but the lease exceeded ttl_minutes. */
|
|
46
|
+
expired?: boolean
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Injectable probes answering the gate's three questions. Absent probes fall
|
|
51
|
+
* back to the real host: config.yml posture, process.stdin TTY, process.env.
|
|
52
|
+
* `resolveTarget` has NO default — liveness is multiplexer-specific and the
|
|
53
|
+
* calling transport must supply it.
|
|
54
|
+
*/
|
|
55
|
+
export interface SteerGateOverrides {
|
|
56
|
+
readPosture?: () => SteerPosture | Promise<SteerPosture>
|
|
57
|
+
isInteractive?: () => boolean
|
|
58
|
+
env?: Record<string, string | undefined>
|
|
59
|
+
/** Override the transport's liveness probe (tests / pre-verified callers). */
|
|
60
|
+
resolveTarget?: () => boolean | Promise<boolean>
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
export interface SteerGateInputs extends SteerGateOverrides {
|
|
64
|
+
/** Human-readable target, only used in refusal reasons. */
|
|
65
|
+
target: string
|
|
66
|
+
/** Is the target visible in the LIVE multiplexer inventory right now? */
|
|
67
|
+
resolveTarget: () => boolean | Promise<boolean>
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export interface SteerGateDecision {
|
|
71
|
+
allowed: boolean
|
|
72
|
+
/** Every failed check, in Python enforcement order; empty when allowed. */
|
|
73
|
+
reasons: string[]
|
|
74
|
+
posture: SteerPosture
|
|
75
|
+
target_resolved: boolean
|
|
76
|
+
interactive_tty: boolean
|
|
77
|
+
non_interactive_override: boolean
|
|
78
|
+
boundary: string
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function expandHome(p: string): string {
|
|
82
|
+
if (p === "~") return homedir()
|
|
83
|
+
if (p.startsWith("~/")) return join(homedir(), p.slice(2))
|
|
84
|
+
return p
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** `${MIADI_HOME || ~/.miadi/navigator}` — mirrors tide_runtime.paths.get_config_dir(). */
|
|
88
|
+
export function resolveNavigatorDir(env: Record<string, string | undefined> = process.env): string {
|
|
89
|
+
const override = env.MIADI_HOME?.trim()
|
|
90
|
+
return override ? expandHome(override) : join(homedir(), ".miadi", "navigator")
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
const QUOTE = /^['"]|['"]$/g
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Read `mode:` and the `controller:` lease block from config.yml. NOT a YAML
|
|
97
|
+
* parser — a line reader for exactly the two keys tide writes via
|
|
98
|
+
* yaml.safe_dump(default_flow_style=False): a top-level scalar and one
|
|
99
|
+
* two-key nested block. Anything unreadable degrades to the Python default
|
|
100
|
+
* (observer), never to controller.
|
|
101
|
+
*/
|
|
102
|
+
export function readNavigatorPosture(env: Record<string, string | undefined> = process.env): SteerPosture {
|
|
103
|
+
const dir = resolveNavigatorDir(env)
|
|
104
|
+
const path = join(dir, "config.yml")
|
|
105
|
+
let text: string
|
|
106
|
+
try {
|
|
107
|
+
text = readFileSync(path, "utf8")
|
|
108
|
+
} catch {
|
|
109
|
+
return { mode: "observer", source: `default: observer (no readable ${path})` }
|
|
110
|
+
}
|
|
111
|
+
let rawMode: string | undefined
|
|
112
|
+
let ttl: number | undefined
|
|
113
|
+
let enabledAt: string | undefined
|
|
114
|
+
let inController = false
|
|
115
|
+
for (const line of text.split("\n")) {
|
|
116
|
+
const topLevel = /^[^\s#]/.test(line)
|
|
117
|
+
if (topLevel) inController = /^controller:\s*$/.test(line)
|
|
118
|
+
const mode = line.match(/^mode:\s*(.+?)\s*$/)
|
|
119
|
+
if (mode) rawMode = mode[1].replace(QUOTE, "")
|
|
120
|
+
if (inController && !topLevel) {
|
|
121
|
+
const t = line.match(/^\s+ttl_minutes:\s*(.+?)\s*$/)
|
|
122
|
+
if (t) ttl = Number(t[1].replace(QUOTE, ""))
|
|
123
|
+
const e = line.match(/^\s+enabled_at:\s*(.+?)\s*$/)
|
|
124
|
+
if (e) enabledAt = e[1].replace(QUOTE, "")
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
const mode: SteerPostureMode =
|
|
128
|
+
rawMode === "controller" ? "controller" : rawMode === "observer" || rawMode === undefined ? "observer" : "unknown"
|
|
129
|
+
const posture: SteerPosture = { mode, source: path }
|
|
130
|
+
if (enabledAt !== undefined) posture.enabled_at = enabledAt
|
|
131
|
+
if (ttl !== undefined && Number.isFinite(ttl)) posture.ttl_minutes = ttl
|
|
132
|
+
// config.py _controller_ttl_expired: controller + ttl>0 + parseable stamp
|
|
133
|
+
// older than the lease ⇒ effective observer. An unparseable stamp with a
|
|
134
|
+
// positive TTL also expires (fail closed), matching Python's None-parse path.
|
|
135
|
+
if (mode === "controller") {
|
|
136
|
+
const ttlMin = posture.ttl_minutes ?? 30
|
|
137
|
+
if (ttlMin > 0) {
|
|
138
|
+
const enabled = Date.parse(posture.enabled_at ?? "")
|
|
139
|
+
if (Number.isNaN(enabled) || Date.now() - enabled > ttlMin * 60_000) {
|
|
140
|
+
posture.mode = "observer"
|
|
141
|
+
posture.expired = true
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
return posture
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* Answer the three gate questions. Never throws — the decision carries every
|
|
150
|
+
* failed check so cockpits can show the whole story at once (the Python CLI
|
|
151
|
+
* exits on the first failure; a JSON boundary wants all of them).
|
|
152
|
+
*/
|
|
153
|
+
export async function evaluateSteerGate(inputs: SteerGateInputs): Promise<SteerGateDecision> {
|
|
154
|
+
const env = inputs.env ?? process.env
|
|
155
|
+
const posture = await (inputs.readPosture ? inputs.readPosture() : readNavigatorPosture(env))
|
|
156
|
+
const interactive = inputs.isInteractive ? inputs.isInteractive() : process.stdin.isTTY === true
|
|
157
|
+
const override = env.TIDE_ALLOW_NON_INTERACTIVE_RUN === "1"
|
|
158
|
+
let resolved = false
|
|
159
|
+
try {
|
|
160
|
+
resolved = await inputs.resolveTarget()
|
|
161
|
+
} catch {
|
|
162
|
+
resolved = false // an unreachable inventory cannot prove a live target
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
const reasons: string[] = []
|
|
166
|
+
if (!resolved) {
|
|
167
|
+
reasons.push(
|
|
168
|
+
`steer target ${inputs.target} is not currently resolved in the live multiplexer inventory — ` +
|
|
169
|
+
"list panes/terminals and retry with a visible target",
|
|
170
|
+
)
|
|
171
|
+
}
|
|
172
|
+
if (posture.mode !== "controller") {
|
|
173
|
+
reasons.push(
|
|
174
|
+
`steer execution requires ACTIVE_CONTROLLER posture (mode: controller); current posture is ` +
|
|
175
|
+
`"${posture.mode}"${posture.expired ? " (controller lease expired)" : ""} — ` +
|
|
176
|
+
"run `tide mode controller` from a local interactive terminal first",
|
|
177
|
+
)
|
|
178
|
+
}
|
|
179
|
+
if (!interactive && !override) {
|
|
180
|
+
reasons.push(
|
|
181
|
+
"steer execution requires an interactive local terminal (TTY), or TIDE_ALLOW_NON_INTERACTIVE_RUN=1 " +
|
|
182
|
+
"set by an approval-queue-fronted service after its own review",
|
|
183
|
+
)
|
|
184
|
+
}
|
|
185
|
+
return {
|
|
186
|
+
allowed: reasons.length === 0,
|
|
187
|
+
reasons,
|
|
188
|
+
posture,
|
|
189
|
+
target_resolved: resolved,
|
|
190
|
+
interactive_tty: interactive,
|
|
191
|
+
non_interactive_override: override,
|
|
192
|
+
boundary: STEER_BOUNDARY,
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/** Evaluate and THROW a TideError naming every failed check when refused. */
|
|
197
|
+
export async function requireSteerGate(inputs: SteerGateInputs): Promise<SteerGateDecision> {
|
|
198
|
+
const decision = await evaluateSteerGate(inputs)
|
|
199
|
+
if (!decision.allowed) {
|
|
200
|
+
throw new TideError(`steer gate refused (${STEER_BOUNDARY}): ${decision.reasons.join("; ")}`)
|
|
201
|
+
}
|
|
202
|
+
return decision
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
// ── Trusted-override brand (EP152 wave-2 W10a) ──────────────────────────────
|
|
206
|
+
//
|
|
207
|
+
// The injectable probes are a test seam, and a seam is a channel: any caller
|
|
208
|
+
// that answers all three questions affirmatively — or merely smuggles
|
|
209
|
+
// `env: {TIDE_ALLOW_NON_INTERACTIVE_RUN:"1"}` in JSON-derived options — walks
|
|
210
|
+
// through the gate (W8 adversarial finding, verified live). Overrides are
|
|
211
|
+
// therefore only ACCEPTED when branded by trustSteerGateProbes(), which is
|
|
212
|
+
// deliberately NOT re-exported from the package surface (src/index.ts): tests
|
|
213
|
+
// and first-party wiring reach it via a direct module import; JSON cannot
|
|
214
|
+
// carry the brand (a module-private Symbol on a non-enumerable property), so
|
|
215
|
+
// request-derived gate options are structurally refused.
|
|
216
|
+
|
|
217
|
+
const TRUSTED_PROBES = Symbol("miadi.tide.steer-gate.trusted-probes")
|
|
218
|
+
|
|
219
|
+
/** Brand probe overrides as trusted. NOT exported from the package surface — import from the module directly (test seam / first-party wiring only). */
|
|
220
|
+
export function trustSteerGateProbes(overrides: SteerGateOverrides): SteerGateOverrides {
|
|
221
|
+
const branded: SteerGateOverrides = { ...overrides }
|
|
222
|
+
Object.defineProperty(branded, TRUSTED_PROBES, { value: true, enumerable: false })
|
|
223
|
+
return branded
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
function isTrustedSteerGateProbes(gate: SteerGateOverrides): boolean {
|
|
227
|
+
return (gate as Record<PropertyKey, unknown>)[TRUSTED_PROBES] === true
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
/**
|
|
231
|
+
* Admission check for `opts.gate` at the transport boundary: absent → real
|
|
232
|
+
* host probes; branded → accepted; anything else → loud refusal (a gate
|
|
233
|
+
* override that reaches a steer verb without the brand is either a bug or an
|
|
234
|
+
* injection — both deserve a named failure, not a silent bypass or ignore).
|
|
235
|
+
*/
|
|
236
|
+
export function acceptGateOverrides(gate: SteerGateOverrides | undefined): SteerGateOverrides {
|
|
237
|
+
if (gate === undefined) return {}
|
|
238
|
+
if (!isTrustedSteerGateProbes(gate)) {
|
|
239
|
+
throw new TideError(
|
|
240
|
+
"steer gate overrides refused: not branded by trustSteerGateProbes() — " +
|
|
241
|
+
"request-derived or untrusted gate options cannot answer the gate's questions",
|
|
242
|
+
)
|
|
243
|
+
}
|
|
244
|
+
return gate
|
|
245
|
+
}
|