cyber-mux 0.1.0 → 0.4.0

package/dist/agent.d.mts

@@ -0,0 +1,66 @@
+import { t as Exec } from "./exec-B81m4yjz.mjs";
+import { d as MuxTarget, n as AgentStatus, o as MuxAdapter, r as AgentWaitOptions, t as AgentLifecycle } from "./mux-CoYDrk3v.mjs";
+//#region src/agent.d.ts
+/**
+ * An agent-lifecycle wait asked of a backend that has no native agent-state primitive (`agent wait`
+ * on tmux, wezterm or zellij). An absent `agentLifecycle` seam member is a REFUSAL, never a guess: a
+ * wait built from `read()` polling would silently disagree with herdr's own state derivation on the
+ * same question, and a wait has no truthful degrade the way a snapshot does — so a backend that cannot
+ * answer is refused rather than emulated.
+ *
+ * PORTABLE and exit-code-free by design, the exact mirror of `CaptureUnsupportedError`. The DECISION
+ * to refuse is the library's and lives in `deriveAgentWait`, the one place that sees the adapter — how
+ * the refusal SURFACES (the exit code, the fix hint, the exact sentence) is the CLI's, which catches
+ * this and re-raises its own `backend-unsupported` error. `backend` names the backend so the caller
+ * composes the message without re-deriving it; the terse `message` is a factual log line.
+ */
+declare class AgentLifecycleUnsupportedError extends Error {
+  readonly backend: string;
+  constructor(backend: string);
+}
+/**
+ * Wait for the target pane's agent to reach one of `opts.until` (or the backend's default set) through
+ * the adapter — the surface-independent orchestrator `agent wait` drives, and the single home of the
+ * agent-wait refusal. The optional `agentLifecycle` seam is where a backend says whether it has a
+ * native wait at all; a backend without it is refused HERE (`AgentLifecycleUnsupportedError`), BEFORE
+ * any exec, because `waitForState` never sees the adapter and so cannot make that call. A backend that
+ * HAS the capability delegates to it unchanged.
+ *
+ * Mirrors `deriveRegionCapture` (`template-capture.ts`) exactly: the orchestrator is the one place that
+ * sees the adapter, so it is the one place the emulate-or-refuse decision can be made.
+ */
+declare function deriveAgentWait(adapter: MuxAdapter, exec: Exec, target: MuxTarget, opts: AgentWaitOptions): AgentStatus;
+/**
+ * The `agent` subpath facade with its `Exec` and backend BOUND — the exec-bound parallel of
+ * `worktreeApi`/`templateApi`. `agentApi(env, deps?)` resolves the backend adapter from `env` ONCE
+ * (`resolveMuxAdapter`, defaulting `exec` to `nodeExec`) and exposes `supported`/`status`/`wait` with
+ * the seams already threaded, so a caller never re-plumbs an adapter or a runner into them.
+ *
+ * It ADDS no logic of its own: `supported` reads the very capability presence `deriveAgentWait` gates
+ * on, `status` reads the same `LivePane.agentStatus` the listing already carries (for one pane rather
+ * than redefining it), and `wait` routes THROUGH `deriveAgentWait` — so the emulate-or-refuse decision
+ * stays specified once and enforced once, with no second refusal path here that could drift from it.
+ */
+interface AgentApi {
+  /** Whether this backend reports agent-lifecycle state at all (herdr yes; tmux/wezterm/zellij no). */
+  supported(): boolean;
+  /** A pane's current agent state, or `undefined` when the backend has no feed (absent-not-false). */
+  status(target: MuxTarget): AgentStatus | undefined;
+  /**
+   * Block until the pane's agent reaches one of `opts.until` (or the backend's default set); throws
+   * `AgentLifecycleUnsupportedError` naming the backend on one without the capability, via
+   * `deriveAgentWait`. A bare `wait(target)` takes herdr's own defaults (`opts ?? {}`).
+   */
+  wait(target: MuxTarget, opts?: AgentWaitOptions | undefined): AgentStatus;
+}
+/**
+ * Bind the agent-lifecycle capability to an environment and runner once, returning an `AgentApi` whose
+ * methods no longer take an `Exec`. `deps.exec` defaults to `nodeExec`; `env` is bound like
+ * `resolveMux(env)` because it is what the probe resolves the backend from.
+ */
+declare function agentApi(env: NodeJS.ProcessEnv, deps?: {
+  exec?: Exec | undefined;
+} | undefined): AgentApi;
+//#endregion
+export { AgentApi, type AgentLifecycle, AgentLifecycleUnsupportedError, type AgentStatus, type AgentWaitOptions, agentApi, deriveAgentWait };
+//# sourceMappingURL=agent.d.mts.map

package/dist/agent.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.mts","names":[],"sources":["../src/agent.ts"],"mappings":";;;;;;;;;;;;;;;;cA4Ba,uCAAuC;WACvC;EAAZ,YAAY;;;;;;;;;;;;;iBAiBG,gBACf,SAAS,YACT,MAAM,MACN,QAAQ,WACR,MAAM,mBACJ;;;;;;;;;;;;UAiBc;;EAEhB;;EAEA,OAAO,QAAQ,YAAY;;;;;;EAM3B,KAAK,QAAQ,WAAW,OAAO,+BAA+B;;;;;;;iBAQ/C,SAAS,KAAK,OAAO,YAAY;EAAS,OAAO;gBAAiC"}

package/dist/agent.mjs

@@ -0,0 +1,58 @@
+import { m as nodeExec } from "./worktree-hHuFZkpW.mjs";
+import { r as resolveMuxAdapter } from "./backend-Cif257ji.mjs";
+//#region src/agent.ts
+/**
+* An agent-lifecycle wait asked of a backend that has no native agent-state primitive (`agent wait`
+* on tmux, wezterm or zellij). An absent `agentLifecycle` seam member is a REFUSAL, never a guess: a
+* wait built from `read()` polling would silently disagree with herdr's own state derivation on the
+* same question, and a wait has no truthful degrade the way a snapshot does — so a backend that cannot
+* answer is refused rather than emulated.
+*
+* PORTABLE and exit-code-free by design, the exact mirror of `CaptureUnsupportedError`. The DECISION
+* to refuse is the library's and lives in `deriveAgentWait`, the one place that sees the adapter — how
+* the refusal SURFACES (the exit code, the fix hint, the exact sentence) is the CLI's, which catches
+* this and re-raises its own `backend-unsupported` error. `backend` names the backend so the caller
+* composes the message without re-deriving it; the terse `message` is a factual log line.
+*/
+var AgentLifecycleUnsupportedError = class extends Error {
+	backend;
+	constructor(backend) {
+		super(`${backend} cannot report agent-lifecycle state`);
+		this.backend = backend;
+		this.name = "AgentLifecycleUnsupportedError";
+	}
+};
+/**
+* Wait for the target pane's agent to reach one of `opts.until` (or the backend's default set) through
+* the adapter — the surface-independent orchestrator `agent wait` drives, and the single home of the
+* agent-wait refusal. The optional `agentLifecycle` seam is where a backend says whether it has a
+* native wait at all; a backend without it is refused HERE (`AgentLifecycleUnsupportedError`), BEFORE
+* any exec, because `waitForState` never sees the adapter and so cannot make that call. A backend that
+* HAS the capability delegates to it unchanged.
+*
+* Mirrors `deriveRegionCapture` (`template-capture.ts`) exactly: the orchestrator is the one place that
+* sees the adapter, so it is the one place the emulate-or-refuse decision can be made.
+*/
+function deriveAgentWait(adapter, exec, target, opts) {
+	const agentLifecycle = adapter.agentLifecycle;
+	if (!agentLifecycle) throw new AgentLifecycleUnsupportedError(adapter.name);
+	return agentLifecycle.waitForState(exec, target, opts);
+}
+/**
+* Bind the agent-lifecycle capability to an environment and runner once, returning an `AgentApi` whose
+* methods no longer take an `Exec`. `deps.exec` defaults to `nodeExec`; `env` is bound like
+* `resolveMux(env)` because it is what the probe resolves the backend from.
+*/
+function agentApi(env, deps) {
+	const exec = deps?.exec ?? nodeExec;
+	const adapter = resolveMuxAdapter(env, exec);
+	return {
+		supported: () => adapter.agentLifecycle !== void 0,
+		status: (target) => adapter.listPanes(exec).find((p) => p.id === target.id)?.agentStatus,
+		wait: (target, opts) => deriveAgentWait(adapter, exec, target, opts ?? {})
+	};
+}
+//#endregion
+export { AgentLifecycleUnsupportedError, agentApi, deriveAgentWait };
+
+//# sourceMappingURL=agent.mjs.map

package/dist/agent.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.mjs","names":[],"sources":["../src/agent.ts"],"sourcesContent":["import { resolveMuxAdapter } from './backend.ts'\nimport { type Exec, nodeExec } from './exec.ts'\nimport type { AgentStatus, AgentWaitOptions, MuxAdapter, MuxTarget } from './mux.ts'\n\n/**\n * The `cyber-mux/agent` subpath — the agent-lifecycle capability's orchestrator and its refusal.\n *\n * The `AgentStatus` type rides out on the `.` barrel (it is part of `LivePane`, and `mux.ts` is\n * re-exported there); the WAIT capability — the `AgentLifecycle` seam plus the emulate-or-refuse\n * decision below — is this subpath alone, kept off the core barrel exactly as `template`'s apply\n * engine is: a capability nobody has to import to drive a pane is not on the surface everybody gets.\n */\n\nexport type { AgentLifecycle, AgentStatus, AgentWaitOptions } from './mux.ts'\n\n/**\n * An agent-lifecycle wait asked of a backend that has no native agent-state primitive (`agent wait`\n * on tmux, wezterm or zellij). An absent `agentLifecycle` seam member is a REFUSAL, never a guess: a\n * wait built from `read()` polling would silently disagree with herdr's own state derivation on the\n * same question, and a wait has no truthful degrade the way a snapshot does — so a backend that cannot\n * answer is refused rather than emulated.\n *\n * PORTABLE and exit-code-free by design, the exact mirror of `CaptureUnsupportedError`. The DECISION\n * to refuse is the library's and lives in `deriveAgentWait`, the one place that sees the adapter — how\n * the refusal SURFACES (the exit code, the fix hint, the exact sentence) is the CLI's, which catches\n * this and re-raises its own `backend-unsupported` error. `backend` names the backend so the caller\n * composes the message without re-deriving it; the terse `message` is a factual log line.\n */\nexport class AgentLifecycleUnsupportedError extends Error {\n\tconstructor(readonly backend: string) {\n\t\tsuper(`${backend} cannot report agent-lifecycle state`)\n\t\tthis.name = 'AgentLifecycleUnsupportedError'\n\t}\n}\n\n/**\n * Wait for the target pane's agent to reach one of `opts.until` (or the backend's default set) through\n * the adapter — the surface-independent orchestrator `agent wait` drives, and the single home of the\n * agent-wait refusal. The optional `agentLifecycle` seam is where a backend says whether it has a\n * native wait at all; a backend without it is refused HERE (`AgentLifecycleUnsupportedError`), BEFORE\n * any exec, because `waitForState` never sees the adapter and so cannot make that call. A backend that\n * HAS the capability delegates to it unchanged.\n *\n * Mirrors `deriveRegionCapture` (`template-capture.ts`) exactly: the orchestrator is the one place that\n * sees the adapter, so it is the one place the emulate-or-refuse decision can be made.\n */\nexport function deriveAgentWait(\n\tadapter: MuxAdapter,\n\texec: Exec,\n\ttarget: MuxTarget,\n\topts: AgentWaitOptions,\n): AgentStatus {\n\tconst agentLifecycle = adapter.agentLifecycle\n\tif (!agentLifecycle) throw new AgentLifecycleUnsupportedError(adapter.name)\n\treturn agentLifecycle.waitForState(exec, target, opts)\n}\n\n/**\n * The `agent` subpath facade with its `Exec` and backend BOUND — the exec-bound parallel of\n * `worktreeApi`/`templateApi`. `agentApi(env, deps?)` resolves the backend adapter from `env` ONCE\n * (`resolveMuxAdapter`, defaulting `exec` to `nodeExec`) and exposes `supported`/`status`/`wait` with\n * the seams already threaded, so a caller never re-plumbs an adapter or a runner into them.\n *\n * It ADDS no logic of its own: `supported` reads the very capability presence `deriveAgentWait` gates\n * on, `status` reads the same `LivePane.agentStatus` the listing already carries (for one pane rather\n * than redefining it), and `wait` routes THROUGH `deriveAgentWait` — so the emulate-or-refuse decision\n * stays specified once and enforced once, with no second refusal path here that could drift from it.\n */\nexport interface AgentApi {\n\t/** Whether this backend reports agent-lifecycle state at all (herdr yes; tmux/wezterm/zellij no). */\n\tsupported(): boolean\n\t/** A pane's current agent state, or `undefined` when the backend has no feed (absent-not-false). */\n\tstatus(target: MuxTarget): AgentStatus | undefined\n\t/**\n\t * Block until the pane's agent reaches one of `opts.until` (or the backend's default set); throws\n\t * `AgentLifecycleUnsupportedError` naming the backend on one without the capability, via\n\t * `deriveAgentWait`. A bare `wait(target)` takes herdr's own defaults (`opts ?? {}`).\n\t */\n\twait(target: MuxTarget, opts?: AgentWaitOptions | undefined): AgentStatus\n}\n\n/**\n * Bind the agent-lifecycle capability to an environment and runner once, returning an `AgentApi` whose\n * methods no longer take an `Exec`. `deps.exec` defaults to `nodeExec`; `env` is bound like\n * `resolveMux(env)` because it is what the probe resolves the backend from.\n */\nexport function agentApi(env: NodeJS.ProcessEnv, deps?: { exec?: Exec | undefined } | undefined): AgentApi {\n\tconst exec = deps?.exec ?? nodeExec\n\tconst adapter = resolveMuxAdapter(env, exec)\n\treturn {\n\t\tsupported: () => adapter.agentLifecycle !== undefined,\n\t\tstatus: (target) => adapter.listPanes(exec).find((p) => p.id === target.id)?.agentStatus,\n\t\twait: (target, opts) => deriveAgentWait(adapter, exec, target, opts ?? {}),\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA4BA,IAAa,iCAAb,cAAoD,MAAM;CACpC;CAArB,YAAY,SAA0B;EACrC,MAAM,GAAG,QAAQ,qCAAqC;EADlC,KAAA,UAAA;EAEpB,KAAK,OAAO;CACb;AACD;;;;;;;;;;;;AAaA,SAAgB,gBACf,SACA,MACA,QACA,MACc;CACd,MAAM,iBAAiB,QAAQ;CAC/B,IAAI,CAAC,gBAAgB,MAAM,IAAI,+BAA+B,QAAQ,IAAI;CAC1E,OAAO,eAAe,aAAa,MAAM,QAAQ,IAAI;AACtD;;;;;;AA+BA,SAAgB,SAAS,KAAwB,MAA0D;CAC1G,MAAM,OAAO,MAAM,QAAQ;CAC3B,MAAM,UAAU,kBAAkB,KAAK,IAAI;CAC3C,OAAO;EACN,iBAAiB,QAAQ,mBAAmB,KAAA;EAC5C,SAAS,WAAW,QAAQ,UAAU,IAAI,CAAC,CAAC,MAAM,MAAM,EAAE,OAAO,OAAO,EAAE,CAAC,EAAE;EAC7E,OAAO,QAAQ,SAAS,gBAAgB,SAAS,MAAM,QAAQ,QAAQ,CAAC,CAAC;CAC1E;AACD"}