@miadi/tide 0.6.9 → 0.6.11

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 +95 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@miadi/tide",
3
- "version": "0.6.9",
3
+ "version": "0.6.11",
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
@@ -523,6 +523,101 @@ export async function openCompanion(opts: CompanionOpenOptions): Promise<TideCom
523
523
  }
524
524
  }
525
525
 
526
+ // ── Open one agent session by its id (jgwill/Miadi#868) ─────────────────────
527
+
528
+ export interface AgentOpenOptions {
529
+ /** A Claude session id, or its first 8 characters or more. */
530
+ session: string
531
+ /** Resume it when it does not run, instead of returning the plan. */
532
+ run?: boolean
533
+ /** With `run`: the `fingerprint` of the plan the person approved. Another plan does not start. */
534
+ expect?: string
535
+ timeoutMs?: number
536
+ }
537
+
538
+ /** `tide agents open --format json`: where the session runs, or how it is resumed. */
539
+ export interface TideAgentOpenPlan {
540
+ session_id: string
541
+ /** `running`: `pane_id` is its pane and nothing starts. `resume`: the plan. `refused`: `reason` says why. */
542
+ state: "running" | "resume" | "refused"
543
+ reason: string
544
+ kind: string
545
+ name: string
546
+ cwd: string
547
+ launch_alias: string
548
+ /** The tmux session it runs in, or the one it is resumed in. */
549
+ tmux_session: string
550
+ /** The pane it runs in; after a run, the pane it was resumed in. */
551
+ pane_id: string
552
+ command: string[]
553
+ how: string
554
+ /** `new-session`, or `new-window` in a session of its name that exists. */
555
+ target: "" | "new-session" | "new-window"
556
+ tmux_commands: string[]
557
+ last_seen: string
558
+ /** A headless call, opened as a conversation without its prompt. */
559
+ headless: boolean
560
+ /** What the person approves; send it back as `expect` with `run`. Empty unless `resume`. */
561
+ fingerprint: string
562
+ /** A run whose plan was not the one approved (`expect`): nothing started, and this is the new plan. */
563
+ changed: boolean
564
+ executed: boolean
565
+ }
566
+
567
+ export interface TideAgentOpenResult {
568
+ /** 0 an answer (running, a plan, or resumed), 4 refused, 2 the controller gate or an unknown session, 1 tmux failed. */
569
+ exitCode: number
570
+ plan: TideAgentOpenPlan | null
571
+ /** The runtime's own words when it printed no JSON. */
572
+ message?: string
573
+ }
574
+
575
+ export const AGENT_SESSION_KEY = /^[0-9a-f]{8}[0-9a-f-]{0,28}$/
576
+ export const AGENT_PLAN_FINGERPRINT = /^[0-9a-f]{16}$/
577
+
578
+ /**
579
+ * Open one agent session by its id: the pane it runs in, or resumed in a tmux session of the
580
+ * name it last ran under (ironsilk ≥ 0.9.70, `tide agents open`). Dry run unless `run`.
581
+ * Exit 4 (refused, or a plan other than `expect`) still prints the plan and comes back as an answer.
582
+ */
583
+ export async function openAgentSession(opts: AgentOpenOptions): Promise<TideAgentOpenResult> {
584
+ const session = opts.session.trim().toLowerCase()
585
+ if (!AGENT_SESSION_KEY.test(session)) {
586
+ throw new TideError(`session must be a session id or its first 8 characters or more: ${JSON.stringify(opts.session)}`)
587
+ }
588
+ if (opts.expect !== undefined && !AGENT_PLAN_FINGERPRINT.test(opts.expect)) {
589
+ throw new TideError(`expect must be a plan fingerprint (16 hex characters): ${JSON.stringify(opts.expect)}`)
590
+ }
591
+ const args = ["agents", "open", session, "--format", "json"]
592
+ if (opts.run) args.push("--run")
593
+ if (opts.run && opts.expect) args.push("--expect", opts.expect)
594
+ const bin = await resolveTideBin()
595
+ const timeoutMs = opts.timeoutMs ?? 60_000
596
+ const env = opts.run ? { ...process.env, TIDE_ALLOW_NON_INTERACTIVE_RUN: "1" } : process.env
597
+ const startedAt = Date.now()
598
+ const parse = (stdout: string): TideAgentOpenPlan | null => {
599
+ try {
600
+ const plan = JSON.parse(stdout) as TideAgentOpenPlan
601
+ return plan && typeof plan === "object" && typeof plan.state === "string" ? plan : null
602
+ } catch {
603
+ return null
604
+ }
605
+ }
606
+ try {
607
+ const res = await pExecFile(bin, args, { timeout: timeoutMs, env, maxBuffer: 1024 * 1024 })
608
+ return { exitCode: 0, plan: parse(res.stdout) }
609
+ } catch (err) {
610
+ const e = err as { code?: unknown; killed?: boolean; stdout?: string; stderr?: string }
611
+ if (typeof e.code === "number" && !e.killed) {
612
+ const plan = parse(e.stdout ?? "")
613
+ return plan
614
+ ? { exitCode: e.code, plan }
615
+ : { exitCode: e.code, plan: null, message: `${e.stdout ?? ""}${e.stderr ?? ""}`.trim() }
616
+ }
617
+ throw classifyExecFailure(bin, args, err, Date.now() - startedAt, timeoutMs)
618
+ }
619
+ }
620
+
526
621
  // ── Direct send-keys (simple, robust steer transport) ───────────────────────
527
622
  //
528
623
  // The operator cockpit's primary steer path. Instead of the heavier reviewed