@miadi/tide 0.6.10 → 0.6.12

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.
Files changed (2) hide show
  1. package/package.json +1 -1
  2. package/src/client.ts +170 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@miadi/tide",
3
- "version": "0.6.10",
3
+ "version": "0.6.12",
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
@@ -12,6 +12,7 @@
12
12
 
13
13
  import { execFile } from "node:child_process"
14
14
  import { promisify } from "node:util"
15
+ import { existsSync } from "node:fs"
15
16
  import { readFile } from "node:fs/promises"
16
17
  import { join } from "node:path"
17
18
  import { homedir } from "node:os"
@@ -530,6 +531,8 @@ export interface AgentOpenOptions {
530
531
  session: string
531
532
  /** Resume it when it does not run, instead of returning the plan. */
532
533
  run?: boolean
534
+ /** With `run`: the `fingerprint` of the plan the person approved. Another plan does not start. */
535
+ expect?: string
533
536
  timeoutMs?: number
534
537
  }
535
538
 
@@ -553,6 +556,12 @@ export interface TideAgentOpenPlan {
553
556
  target: "" | "new-session" | "new-window"
554
557
  tmux_commands: string[]
555
558
  last_seen: string
559
+ /** A headless call, opened as a conversation without its prompt. */
560
+ headless: boolean
561
+ /** What the person approves; send it back as `expect` with `run`. Empty unless `resume`. */
562
+ fingerprint: string
563
+ /** A run whose plan was not the one approved (`expect`): nothing started, and this is the new plan. */
564
+ changed: boolean
556
565
  executed: boolean
557
566
  }
558
567
 
@@ -565,19 +574,24 @@ export interface TideAgentOpenResult {
565
574
  }
566
575
 
567
576
  export const AGENT_SESSION_KEY = /^[0-9a-f]{8}[0-9a-f-]{0,28}$/
577
+ export const AGENT_PLAN_FINGERPRINT = /^[0-9a-f]{16}$/
568
578
 
569
579
  /**
570
580
  * Open one agent session by its id: the pane it runs in, or resumed in a tmux session of the
571
581
  * name it last ran under (ironsilk ≥ 0.9.70, `tide agents open`). Dry run unless `run`.
572
- * Exit 4 (refused) still prints the plan and comes back as an answer.
582
+ * Exit 4 (refused, or a plan other than `expect`) still prints the plan and comes back as an answer.
573
583
  */
574
584
  export async function openAgentSession(opts: AgentOpenOptions): Promise<TideAgentOpenResult> {
575
585
  const session = opts.session.trim().toLowerCase()
576
586
  if (!AGENT_SESSION_KEY.test(session)) {
577
587
  throw new TideError(`session must be a session id or its first 8 characters or more: ${JSON.stringify(opts.session)}`)
578
588
  }
589
+ if (opts.expect !== undefined && !AGENT_PLAN_FINGERPRINT.test(opts.expect)) {
590
+ throw new TideError(`expect must be a plan fingerprint (16 hex characters): ${JSON.stringify(opts.expect)}`)
591
+ }
579
592
  const args = ["agents", "open", session, "--format", "json"]
580
593
  if (opts.run) args.push("--run")
594
+ if (opts.run && opts.expect) args.push("--expect", opts.expect)
581
595
  const bin = await resolveTideBin()
582
596
  const timeoutMs = opts.timeoutMs ?? 60_000
583
597
  const env = opts.run ? { ...process.env, TIDE_ALLOW_NON_INTERACTIVE_RUN: "1" } : process.env
@@ -1059,6 +1073,119 @@ export async function setSessionTeam(session: string, team: string | null, opts:
1059
1073
  }
1060
1074
  }
1061
1075
 
1076
+ // ── A session on a team (jgwill/Miadi#936) ─────────────────────────────────
1077
+ //
1078
+ // `mct new` (@miadi/chronicle-tui) is the one path that starts a session on a team, for a person at
1079
+ // a terminal, in the chronicle browser and from the cockpit: the session, its team declared before
1080
+ // the agent starts, the agent named after it, the primer pasted once it is ready. These two run
1081
+ // it with --json: `teamStartChoices` reads what a start is chosen from, `startTeamSession` asks
1082
+ // for the plan, and with `run` starts the plan whose fingerprint was shown.
1083
+
1084
+ export interface TeamStartTeam {
1085
+ id: string
1086
+ name: string | null
1087
+ level: string | null
1088
+ human_lead: string | null
1089
+ agent_lead: string | null
1090
+ sessions: string[]
1091
+ folders: string[]
1092
+ name_patterns: string[]
1093
+ summary: string | null
1094
+ }
1095
+
1096
+ export interface TeamStartLaunch {
1097
+ launch: string
1098
+ bypass: boolean
1099
+ }
1100
+
1101
+ export interface TeamStartChoices {
1102
+ file: string | null
1103
+ error?: string
1104
+ teams: TeamStartTeam[]
1105
+ launches: TeamStartLaunch[]
1106
+ }
1107
+
1108
+ export interface TeamSessionOptions extends TideRunOptions {
1109
+ team: string
1110
+ session: string
1111
+ cwd: string
1112
+ /** A name `teamStartChoices` offers, or null for a shell alone. */
1113
+ launch: string | null
1114
+ remote?: boolean
1115
+ /** The first prompt, pasted once the agent is ready. */
1116
+ prompt?: string | null
1117
+ /** Start it; without this the answer is the plan. */
1118
+ run?: boolean
1119
+ /** With `run`: the fingerprint of the plan that was shown. */
1120
+ expect?: string
1121
+ }
1122
+
1123
+ export interface TeamSessionAnswer {
1124
+ state: "ready" | "refused" | "changed" | "started"
1125
+ reason?: string
1126
+ team?: { id: string; name: string | null }
1127
+ session?: string
1128
+ cwd?: string
1129
+ launch?: string | null
1130
+ agent?: string | null
1131
+ bypass?: boolean
1132
+ remote?: boolean
1133
+ primer?: boolean
1134
+ commands?: string[]
1135
+ fingerprint?: string
1136
+ pane?: string | null
1137
+ primer_file?: string | null
1138
+ }
1139
+
1140
+ /** `MIADI_MCT_BIN`, else the checkout the app itself runs from, else `mct` on PATH. */
1141
+ function resolveMct(): { bin: string; prefix: string[] } {
1142
+ const named = process.env.MIADI_MCT_BIN?.trim()
1143
+ if (named) return { bin: named, prefix: [] }
1144
+ const checkout = join(process.cwd(), "packages", "chronicle-tui", "dist", "mct.js")
1145
+ if (existsSync(checkout)) return { bin: process.execPath, prefix: [checkout] }
1146
+ return { bin: "mct", prefix: [] }
1147
+ }
1148
+
1149
+ /** Run `mct`, keeping its JSON whatever it exits with: a refusal is exit 4 and still an answer. */
1150
+ async function runMct<T>(args: string[], timeoutMs: number): Promise<T> {
1151
+ const { bin, prefix } = resolveMct()
1152
+ const startedAt = Date.now()
1153
+ let stdout: string
1154
+ let stderr = ""
1155
+ try {
1156
+ ;({ stdout } = await pExecFile(bin, [...prefix, ...args], { timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024 }))
1157
+ } catch (err) {
1158
+ const e = err as ExecFileFailure & { code?: unknown; killed?: boolean; stdout?: string }
1159
+ if (typeof e.code !== "number" || e.killed) throw classifyExecFailure(bin, args, err, Date.now() - startedAt, timeoutMs)
1160
+ stdout = String(e.stdout ?? "")
1161
+ stderr = String(e.stderr ?? "")
1162
+ }
1163
+ try {
1164
+ return JSON.parse(stdout) as T
1165
+ } catch {
1166
+ const said = `${stderr}${stdout}`.trim().split("\n")[0]
1167
+ if (/Unknown option|Unexpected list/.test(said)) throw new TideError(`${[bin, ...prefix].join(" ")} is older than @miadi/chronicle-tui 0.23.0: ${said}`)
1168
+ throw new TideError(said || `${bin} gave no answer to ${args.join(" ")}`)
1169
+ }
1170
+ }
1171
+
1172
+ /** The teams, in their own words, and what this host may launch: `mct list --json`. */
1173
+ export function teamStartChoices(opts: TideRunOptions = {}): Promise<TeamStartChoices> {
1174
+ return runMct<TeamStartChoices>(["list", "--json"], opts.timeoutMs ?? 10_000)
1175
+ }
1176
+
1177
+ /** The plan to start a session on a team, or with `run` the session started and its pane: `mct new --json`. */
1178
+ export function startTeamSession(opts: TeamSessionOptions): Promise<TeamSessionAnswer> {
1179
+ const args = ["new", opts.team, opts.session, "--cwd", opts.cwd, "--json"]
1180
+ if (opts.launch === null) args.push("--no-launch")
1181
+ else args.push("--launch", opts.launch)
1182
+ if (opts.remote && opts.launch !== null) args.push("--remote")
1183
+ if (opts.prompt && opts.launch !== null) args.push("--prompt", opts.prompt)
1184
+ if (!opts.run) args.push("--dry-run")
1185
+ else if (opts.expect) args.push("--expect", opts.expect)
1186
+ return runMct<TeamSessionAnswer>(args, opts.timeoutMs ?? 30_000)
1187
+ }
1188
+
1062
1189
  // ── Drafts being prepared (jgwill/Miadi#691, Episode 548 S2 and H3) ─────────
1063
1190
  //
1064
1191
  // `tide drafts list --json` prints one object per open draft, without its words.
@@ -1261,3 +1388,45 @@ export async function unreadyDraft(ref: string, opts: TideRunOptions & { by?: st
1261
1388
  const closed = /^tide\.draft\.unreadied\s+([0-9a-f]+)/.exec(line)?.[1]
1262
1389
  return { id: closed ?? id.replace(/^draft:/, ""), line }
1263
1390
  }
1391
+
1392
+ /** A draft's words, for its author alone (Episode 548 PT1). */
1393
+ export interface TideDraftWords {
1394
+ id: string
1395
+ version: number
1396
+ text: string
1397
+ }
1398
+
1399
+ /** A draft id as `tide drafts list` prints it: hex, exact. */
1400
+ const DRAFT_ID_EXACT = /^[0-9a-f]{4,64}$/
1401
+
1402
+ /**
1403
+ * The words of one open draft: `tide drafts list --json --text`, keeping the one row
1404
+ * whose id is exactly `id`. Null when tide holds no such open draft. The other rows'
1405
+ * words are dropped here, and nothing of any row is logged or put in an error: a
1406
+ * failure carries tide's stderr, never its stdout.
1407
+ */
1408
+ export async function draftWords(id: string, opts: TideRunOptions = {}): Promise<TideDraftWords | null> {
1409
+ if (!DRAFT_ID_EXACT.test(id)) throw new TideError(`"${id}" is not a draft id: hex, as tide drafts list prints it`)
1410
+ const bin = await resolveTideBin()
1411
+ const args = ["drafts", "list", "--json", "--text"]
1412
+ const timeoutMs = opts.timeoutMs ?? 15_000
1413
+ const startedAt = Date.now()
1414
+ let stdout: string
1415
+ try {
1416
+ ;({ stdout } = await pExecFile(bin, args, { timeout: timeoutMs, cwd: opts.cwd, maxBuffer: 16 * 1024 * 1024 }))
1417
+ } catch (err) {
1418
+ throw classifyExecFailure(bin, args, err, Date.now() - startedAt, timeoutMs)
1419
+ }
1420
+ for (const line of stdout.split("\n")) {
1421
+ if (!line.includes(`"${id}"`)) continue
1422
+ let row: Record<string, unknown>
1423
+ try {
1424
+ row = JSON.parse(line) as Record<string, unknown>
1425
+ } catch {
1426
+ continue
1427
+ }
1428
+ if (row.id !== id || typeof row.text !== "string") continue
1429
+ return { id, version: typeof row.version === "number" ? row.version : 0, text: row.text }
1430
+ }
1431
+ return null
1432
+ }