glimmervoid 0.38.2 → 0.40.0

package/README.md

@@ -76,7 +76,7 @@ Declare another agent under `customAgents` in `config.json` with an `id`, `label
 
 ## Features
 
-- **Focus view.** A rail of every session on the left, the selected session's live terminal in the middle, its changes on the right.
+- **Focus view.** A rail of every session on the left, the selected session's live terminal in the middle, its changes on the right. The top of the rail counts what needs you, and `Cmd/Alt+J` jumps straight to the next one from any tab.
 - **A worktree per agent.** Every session in a git repo gets its own worktree, so agents never step on your checkout or each other. Review the diff and merge with one click while the agent keeps working. A conflicted merge parks, and **Resolve in session** hands it back to the agent that wrote it.
 - **Exact status.** Hooks report every state change and the terminal title fills the gaps. The screen is never scraped ([how](#how-status-detection-works)).
 - **Notifications.** Browser notifications when a session needs input, finishes or fails, with your own alert sounds if you like (drop `.ogg`, `.mp3`, `.wav`, `.m4a` or `.webm` files into `~/.glimmervoid/sounds/`). Telegram covers you when no dashboard is open.

package/dist/bin/glimmervoid.js

@@ -2,12 +2,13 @@
 import { o as nodePtyRebuildHint, r as firstLine, t as probeNodePty } from "../chunks/node-pty-preflight-C8QIlrtU.js";
 import { i as errorText } from "../chunks/text-DoirglWV.js";
 import { a as packageRoot } from "../chunks/runtime-paths-BkeftE60.js";
-import { t as AGENT_API_VERBS } from "../chunks/session-BlT68ppa.js";
+import { t as AGENT_API_VERBS } from "../chunks/session-BwB43SCa.js";
 import { i as execSync } from "../chunks/child-process-safe-CbQnyh7D.js";
+import { r as agentCommandHelpLines } from "../chunks/agent-api-core-DDrJQEdE.js";
 import { t as renderTable } from "../chunks/ascii-figure-core-pDAwtlKO.js";
 import { n as glimmervoidHomeDir, t as decideConfigPath } from "../chunks/config-path-core-DFt-TemS.js";
-import { i as parseCommandLine, r as gitDoctorRows, t as probeGitVersion } from "../chunks/git-version-rWZjF2Px.js";
-import { i as guardrailsDoctorRows, r as probeGuardrailsDependencies } from "../chunks/guardrails-deps-Cb-ki4EU.js";
+import { i as parseCommandLine, r as gitDoctorRows, t as probeGitVersion } from "../chunks/git-version-CJQMfxtZ.js";
+import { i as guardrailsDoctorRows, r as probeGuardrailsDependencies } from "../chunks/guardrails-deps-CLxK4J-g.js";
 import { i as pnpmGlobalBinDir, n as npmGlobalBinDir, r as onPath, t as formatPathNotice } from "../chunks/path-doctor-C23VAqeu.js";
 import fs from "node:fs";
 import path from "node:path";
@@ -35,21 +36,9 @@ Editor integration (Visions):
   visions relay       Run the Visions LSP relay on stdio (an editor's LSP client starts this)
 
 Inside a Glimmervoid session:
-  spawn <prompt>      Start a sibling session on that prompt
-  attention <note>    Flag this session as needing the operator
-  board               List the live sessions
-  push                Land this session's commits on the integration branch and push it
-  edit <path>         Open a text file for the operator to edit in the dashboard
-  limits              List which of these commands answer here and what the guardrails block
-  factory status      Print each factory intent's tickets, state, last reason and next action
-  factory retry <id>  Reopen the parked tickets of a factory intent
-  factory setup       Prove and save the factory checks of this session's repository
-  factory queue <file> Queue a factory intent (a spec cut.ts file or Factory tab request) on this session's repository
+${agentCommandHelpLines().join("\n")}
   ssh-sign            Sign a commit with the operator's forwarded ssh agent (git runs this)
 
-Experimental:
-  kg [command]        Typed knowledge and task graph (Settings > Lanes > Knowledge graph)
-
 Options:
   --port <number>     Server port (default: 3000)
   --config <path>     Config file (default: ~/.glimmervoid/config.json)
@@ -70,47 +59,49 @@ if (commandLine.kind === "version") {
 }
 if (commandLine.globalOptions.configPath) process.env.GLIMMERVOID_CONFIG = commandLine.globalOptions.configPath;
 if (commandLine.globalOptions.port) process.env.GLIMMERVOID_PORT = commandLine.globalOptions.port;
-var SUBCOMMAND_RUNNERS = new Map([
+var OWN_SUBCOMMAND_RUNNERS = [
 	["doctor", async () => {
 		await runDoctor();
 		return 0;
 	}],
 	["pair", async (subcommandArgs) => {
-		const { runPairCli } = await import("../chunks/pair-cli-DNp8i5L4.js");
+		const { runPairCli } = await import("../chunks/pair-cli-CsOVTQGJ.js");
 		return runPairCli(subcommandArgs);
 	}],
 	["agent", async (subcommandArgs) => {
-		const { runAgentSetupCli } = await import("../chunks/agent-setup-cli-DmMfCw5O.js");
+		const { runAgentSetupCli } = await import("../chunks/agent-setup-cli-CeBBwKuL.js");
 		return runAgentSetupCli(subcommandArgs);
 	}],
-	["kg", async (subcommandArgs) => {
-		const { runKnowledgeGraphCommand } = await import("../chunks/knowledge-graph-cli-ByUJoKw_.js");
-		return runKnowledgeGraphCommand(subcommandArgs);
-	}],
 	["settings", async (subcommandArgs) => {
-		const { runSettingsCommand } = await import("../chunks/settings-cli-BbzxCyG5.js");
-		return runSettingsCommand(subcommandArgs);
+		const { runSettingsCli } = await import("../chunks/settings-cli-DkkbK-dj.js");
+		return runSettingsCli(subcommandArgs);
 	}],
 	["visions", async (subcommandArgs) => {
 		const { runVisionsCli } = await import("../chunks/visions-cli-CYujESdJ.js");
 		return runVisionsCli(subcommandArgs);
 	}],
 	["ssh-sign", async (subcommandArgs) => {
-		const { runSshSignCli } = await import("../chunks/ssh-sign-cli-C74BGTQS.js");
+		const { runSshSignCli } = await import("../chunks/ssh-sign-cli-CYeKRevK.js");
 		return runSshSignCli(subcommandArgs);
-	}],
-	["factory", async (subcommandArgs) => {
-		const { runAgentApiCli } = await import("../chunks/agent-api-cli-BDu1CxZf.js");
-		return runAgentApiCli(["factory", ...subcommandArgs]);
-	}],
-	...AGENT_API_VERBS.map((verb) => [verb, async (subcommandArgs, subcommandName) => {
-		const { runAgentApiCli } = await import("../chunks/agent-api-cli-BDu1CxZf.js");
-		return runAgentApiCli([subcommandName, ...subcommandArgs]);
-	}])
-]);
+	}]
+];
+var ownSubcommandNames = new Set(OWN_SUBCOMMAND_RUNNERS.map(([name]) => name));
+var SUBCOMMAND_RUNNERS = new Map([...OWN_SUBCOMMAND_RUNNERS, ...AGENT_API_VERBS.filter((verb) => !ownSubcommandNames.has(verb)).map((verb) => [verb, async (subcommandArgs, subcommandName) => {
+	const { runAgentApiCli } = await import("../chunks/agent-api-cli-BBech5lF.js");
+	return runAgentApiCli([subcommandName, ...subcommandArgs]);
+}])]);
+var AGENT_INSTALL_COMMAND_BY_ID = {
+	"claude-code": "npm install -g @anthropic-ai/claude-code",
+	codex: "npm install -g @openai/codex"
+};
+function missingAgentText(agentId) {
+	const installCommand = AGENT_INSTALL_COMMAND_BY_ID[agentId];
+	if (!installCommand) return "not found on PATH";
+	return `not found on PATH; install with: ${installCommand}`;
+}
 async function printSessionLimits() {
 	if (!process.env["GLIMMERVOID_AGENT_URL"]) return;
-	const { sessionLimitsHelpLines } = await import("../chunks/agent-api-cli-BDu1CxZf.js");
+	const { sessionLimitsHelpLines } = await import("../chunks/agent-api-cli-BBech5lF.js");
 	const limitsLines = await sessionLimitsHelpLines();
 	console.log(`\n${limitsLines.join("\n")}`);
 }
@@ -167,7 +158,7 @@ async function readDeclaredCustomAgents() {
 		declared: [],
 		error: null
 	};
-	const { loadConfigFile } = await import("../chunks/config-store-MAVQhGMh.js");
+	const { loadConfigFile } = await import("../chunks/config-store-BZpN2djp.js");
 	try {
 		const loaded = loadConfigFile(decided.path, { exitOnError: false });
 		if (!loaded.config) return {
@@ -243,15 +234,15 @@ async function runDoctor() {
 	}
 	switchSection("Agents");
 	try {
-		const { listAgentIds, describeAgentResolvability, setCustomAgents } = await import("../chunks/adapters-DDjC7_vG.js");
+		const { listAgentIds, describeAgentResolvability, setCustomAgents } = await import("../chunks/adapters-CXQfLoyj.js");
 		const declaredCustomAgents = await readDeclaredCustomAgents();
 		if (declaredCustomAgents.error) line("config", declaredCustomAgents.error);
 		setCustomAgents(declaredCustomAgents.declared);
 		for (const id of listAgentIds()) {
 			const { label, path: resolvedPath } = describeAgentResolvability(id);
-			line(`${id} (${label})`, resolvedPath ?? "not found on PATH");
+			line(`${id} (${label})`, resolvedPath ?? missingAgentText(id));
 		}
-		const { inspectGrokAgentSetup } = await import("../chunks/agent-setup-cli-DmMfCw5O.js");
+		const { inspectGrokAgentSetup } = await import("../chunks/agent-setup-cli-CeBBwKuL.js");
 		const grokSetup = inspectGrokAgentSetup();
 		line("grok hook setup", `${grokSetup.classification}: ${grokSetup.filePath}`);
 	} catch (err) {
@@ -268,7 +259,7 @@ async function runDoctor() {
 	try {
 		const { resolvePackageBin } = await import("../chunks/runtime-paths-DSmormp7.js");
 		const { execFileSync } = await import("../chunks/child-process-safe-ChRmWAJP.js");
-		const { inspectGrokAgentSetup } = await import("../chunks/agent-setup-cli-DmMfCw5O.js");
+		const { inspectGrokAgentSetup } = await import("../chunks/agent-setup-cli-CeBBwKuL.js");
 		const binPath = resolvePackageBin("cc-safety-net", "cc-safety-net");
 		line("Sane YOLO", binPath || "not installed");
 		if (binPath) line("cc-safety-net version", execFileSync(process.execPath, [binPath, "--version"], {

package/dist/chunks/{adapters-CAHxZYT3.js → adapters-B6tbX3Aj.js}

@@ -1,12 +1,13 @@
 import { o as relayPath } from "./runtime-paths-BkeftE60.js";
 import { r as execFileSync } from "./child-process-safe-CbQnyh7D.js";
+import "./control-messages-DpBaniJi.js";
+import { o as supervisionLine } from "./session-routes-DNJzsckH.js";
 import { n as resolveAgentCommand, t as buildAgentSpawnCommand } from "./spawn-command-Cc40FiZI.js";
 import { s as rawTextOr } from "./coerce-NSst8oRP.js";
 import { r as nextBackoffMs } from "./backoff-DjVpfHk7.js";
-import { l as supervisionLine } from "./session-routes-CT1JrjoT.js";
-import { c as buildAgentEnv, i as isSpinnerChar, n as classifyAgentTitle, r as isBrailleChar, t as grok } from "./grok-B6bsCgdd.js";
+import { i as isSpinnerChar, n as classifyAgentTitle, r as isBrailleChar, s as buildAgentEnv, t as grok } from "./grok-BLzhApwT.js";
 import { t as buildHookCommand } from "./hook-command-core-qTNK-xMF.js";
-import "./contracts-HVCEJfxs.js";
+import "./contracts-CloExMlS.js";
 import { n as mergeCodexPreToolUse, t as HOOK_TOOLS } from "./hook-tools-Dl7-r2Eb.js";
 import fs from "node:fs";
 import path from "node:path";
@@ -204,13 +205,6 @@ var claudeCode = {
 };
 //#endregion
 //#region server/usage/core/usage-scan-core.ts
-function laneSpendStatus({ isTrackingEnabled, scan }) {
-	if (!isTrackingEnabled) return "tracking-off";
-	if (scan === null) return "scanner-missing";
-	if (scan.lastOutcome === "io-failed") return "read-failing";
-	if (!scan.isHistoryCaughtUp || scan.lastOutcome === null) return "catching-up";
-	return "known";
-}
 function scopedClaudeRoots(scopeDirs, claudeDirs) {
 	if (!scopeDirs || scopeDirs.length === 0) return null;
 	const isInside = (candidate, parent) => candidate.startsWith(`${parent}${path.sep}`);
@@ -473,9 +467,11 @@ function mayContributeHooks(configText) {
 function userConfigFolders(env) {
 	return codexHomes(env, null);
 }
-function buildHookArgs({ relayPath = RELAY_PATH, events = HOOK_EVENTS, bypassHookTrust = false, hookTools = [], hookToolRelayPath = HOOK_TOOL_RELAY_PATH } = {}) {
+var TOML_LITERAL_STRING_FORBIDDEN = /[\x00-\x08\x0a-\x1f\x27\x7f]/;
+function buildHookArgs({ relayPath = RELAY_PATH, events = HOOK_EVENTS, bypassHookTrust = false, hookTools = [], hookToolRelayPath = HOOK_TOOL_RELAY_PATH, userHooks = [] } = {}) {
 	const args = bypassHookTrust ? [TRUST_BYPASS_FLAG] : [];
 	const preToolUseGroups = [];
+	const groupsByEvent = /* @__PURE__ */ new Map();
 	for (const event of events) {
 		const command = buildHookCommand(relayPath, event);
 		if (!command) return null;
@@ -483,13 +479,30 @@ function buildHookArgs({ relayPath = RELAY_PATH, events = HOOK_EVENTS, bypassHoo
 			preToolUseGroups.push(`{hooks=[{type='command',command='${command}'}]}`);
 			continue;
 		}
-		args.push("-c", `hooks.${event}=[{hooks=[{type='command',command='${command}'}]}]`);
+		groupsByEvent.set(event, [`{hooks=[{type='command',command='${command}'}]}`]);
 	}
 	const groups = hookTools.flatMap((tool) => {
 		const group = HOOK_TOOLS[tool.id].codexGroup(tool, hookToolRelayPath);
 		return group ? [group] : [];
 	});
-	args.push(...mergeCodexPreToolUse([...preToolUseGroups, ...groups]));
+	preToolUseGroups.push(...groups);
+	for (const hook of userHooks) {
+		if (!hook.enabled || hook.type !== "command" || !hook.command) continue;
+		if (TOML_LITERAL_STRING_FORBIDDEN.test(hook.command) || hook.matcher !== void 0 && TOML_LITERAL_STRING_FORBIDDEN.test(hook.matcher)) {
+			console.warn(`[codex] hook ${hook.id} skipped: command or matcher cannot be expressed as a TOML literal string`);
+			continue;
+		}
+		const group = `{${hook.matcher === void 0 ? "" : `matcher='${hook.matcher}',`}hooks=[{type='command',command='${hook.command}'}]}`;
+		if (hook.event === "PreToolUse") {
+			preToolUseGroups.push(group);
+			continue;
+		}
+		const eventGroups = groupsByEvent.get(hook.event) ?? [];
+		eventGroups.push(group);
+		groupsByEvent.set(hook.event, eventGroups);
+	}
+	for (const [event, eventGroups] of groupsByEvent) args.push("-c", `hooks.${event}=[${eventGroups.join(",")}]`);
+	args.push(...mergeCodexPreToolUse(preToolUseGroups));
 	return args;
 }
 var hooks = {
@@ -790,4 +803,4 @@ function resetCommandCache() {
 	resolvedCommands.clear();
 }
 //#endregion
-export { shouldPersistWarehouse as A, isUsageFile as C, resolveProjectsDirs as D, projectDirCandidates as E, claudeCode as M, scopedClaudeRoots as O, grokRootCandidates as S, passOutcome as T, continuationDelayMs as _, describeAgentResolvability as a, expandTilde as b, isKnownAgentId as c, resolveAdapter as d, setCustomAgents as f, codexSessionIdFromPath as g, codexRootCandidates as h, customAgentFingerprint as i, splitLines as j, shouldEvaluateDespiteIoFailures as k, listAgentIds as l, codexHomes as m, cachedAgentResolvability as n, getAdapter as o, codexFallbackRoots as p, commandFor as r, hookProfileOf as s, DEFAULT_AGENT_ID as t, resetCommandCache as u, decideFileRead as v, laneSpendStatus as w, grokHomes as x, dedupeCodexFiles as y };
+export { splitLines as A, isUsageFile as C, scopedClaudeRoots as D, resolveProjectsDirs as E, shouldEvaluateDespiteIoFailures as O, grokRootCandidates as S, projectDirCandidates as T, continuationDelayMs as _, describeAgentResolvability as a, expandTilde as b, isKnownAgentId as c, resolveAdapter as d, setCustomAgents as f, codexSessionIdFromPath as g, codexRootCandidates as h, customAgentFingerprint as i, claudeCode as j, shouldPersistWarehouse as k, listAgentIds as l, codexHomes as m, cachedAgentResolvability as n, getAdapter as o, codexFallbackRoots as p, commandFor as r, hookProfileOf as s, DEFAULT_AGENT_ID as t, resetCommandCache as u, decideFileRead as v, passOutcome as w, grokHomes as x, dedupeCodexFiles as y };

package/dist/chunks/{adapters-DDjC7_vG.js → adapters-CXQfLoyj.js}

@@ -1 +1 @@
-export { a as describeAgentResolvability, l as listAgentIds, f as setCustomAgents } from "./adapters-CAHxZYT3.js";
+export { a as describeAgentResolvability, l as listAgentIds, f as setCustomAgents } from "./adapters-B6tbX3Aj.js";

package/dist/chunks/agent-api-cli-BBech5lF.js

@@ -0,0 +1 @@
+export { t as askAgentApi, r as runAgentApiCli, i as sessionLimitsHelpLines } from "./agent-api-cli-BNHJTmNW.js";

package/dist/chunks/{agent-api-cli-B5Tm0wXO.js → agent-api-cli-BNHJTmNW.js}

@@ -1,21 +1,19 @@
 import { t as errorCode } from "./text-DoirglWV.js";
-import { a as AgentDispatchRequest, f as AgentTicketRequest, l as AgentFactoryStatusRequest, n as AGENT_URL_ENV, s as AgentFactoryRetryRequest, u as AgentLimitsReply } from "./session-BlT68ppa.js";
+import { n as AGENT_URL_ENV, o as AgentLimitsReply } from "./session-BwB43SCa.js";
+import { i as formatSessionLimits } from "./session-routes-DNJzsckH.js";
+import { l as isAgentApiVerb, t as AGENT_COMMAND_HELP } from "./agent-api-core-DDrJQEdE.js";
 import { i as resolveHookTarget } from "./hook-relay-core-DA_bz2KA.js";
 import { n as decideGuardrailsProxy } from "./guardrails-proxy-core-BI3rdY-m.js";
-import { n as isRecord } from "./coerce-NSst8oRP.js";
 import { t as parseJsonOrNull } from "./json-core-dfa_7Fak.js";
-import { a as formatSessionLimits } from "./session-routes-CT1JrjoT.js";
-import { g as isOrchestratorAgentVerb, h as isAgentApiVerb } from "./agent-api-core-B_mUSenR.js";
-import { readFileSync } from "node:fs";
 import path from "node:path";
 import http from "node:http";
 //#region server/agent-api-cli.ts
 var AGENT_PATH_PREFIX = "/agent/";
 var HELP_LIMITS_TIMEOUT_MS = 2e3;
 var HELP_LIMITS_UNKNOWN_LINE = "This session: Glimmervoid did not report its limits, so run glimmervoid limits to see why";
-function ticketBody(rest) {
-	const parsed = AgentTicketRequest.safeParse({ workId: rest[0] });
-	return parsed.success ? parsed.data : null;
+function pullRequestBody(rest) {
+	const pullRequest = rest.join(" ").trim();
+	return pullRequest ? { pr: pullRequest } : null;
 }
 var BODY_BUILDERS = {
 	spawn: (rest) => {
@@ -33,41 +31,15 @@ var BODY_BUILDERS = {
 		return docPath ? { path: path.resolve(docPath) } : null;
 	},
 	limits: () => ({}),
-	dispatch: (rest) => {
-		const parsed = AgentDispatchRequest.safeParse(rest[0] === "--ready" ? { readyIntent: rest[1] } : { workId: rest[0] });
-		return parsed.success ? parsed.data : null;
-	},
-	reopen: (rest) => ticketBody(rest),
-	cancel: (rest) => ticketBody(rest),
-	"factory-status": (rest) => {
-		if (rest.length === 0) return {};
-		if (rest.length !== 2 || rest[0] !== "--project") return null;
-		const parsed = AgentFactoryStatusRequest.safeParse({ projectId: rest[1] });
-		return parsed.success ? parsed.data : null;
-	},
-	"factory-retry": (rest) => {
-		if (rest.length !== 1) return null;
-		const parsed = AgentFactoryRetryRequest.safeParse({ intentId: rest[0] });
-		return parsed.success ? parsed.data : null;
-	},
-	"factory-setup": (rest) => rest.length === 0 ? {} : null,
-	"factory-queue": (rest) => {
-		if (rest.length !== 1) return null;
-		const intent = parseJsonOrNull(readFileSync(rest[0], "utf8"));
-		if (!isRecord(intent)) return null;
-		const { name: _name, type: _type, requestId: _requestId, projectId: _projectId, ...request } = intent;
-		return request;
-	}
+	review: pullRequestBody,
+	reviews: () => ({}),
+	prs: () => ({}),
+	"link-pr": pullRequestBody,
+	settings: ([command, settingPath]) => ({
+		command,
+		...settingPath === void 0 ? {} : { path: settingPath }
+	})
 };
-var FACTORY_USAGE = Object.freeze({
-	"factory-status": "status [--project <projectId>]",
-	"factory-retry": "retry <intentId>",
-	"factory-setup": "setup",
-	"factory-queue": "queue <intent.json>"
-});
-function isFactoryVerb(verb) {
-	return verb in FACTORY_USAGE;
-}
 function bodySaysOk(text) {
 	try {
 		const parsed = JSON.parse(text);
@@ -82,13 +54,6 @@ function limitsLines(replyText) {
 	return formatSessionLimits(limits.data);
 }
 function printableReply(verb, replyText) {
-	if (isFactoryVerb(verb)) {
-		const reply = parseJsonOrNull(replyText);
-		if (typeof reply !== "object" || reply === null) return replyText;
-		if ("text" in reply && typeof reply.text === "string") return reply.text;
-		if ("error" in reply && typeof reply.error === "string") return reply.error;
-		return replyText;
-	}
 	if (verb !== "limits") return replyText;
 	return limitsLines(replyText)?.join("\n") ?? replyText;
 }
@@ -188,13 +153,6 @@ async function sessionLimitsHelpLines({ timeoutMs = HELP_LIMITS_TIMEOUT_MS } = {
 	}
 }
 async function runAgentApiCli(args) {
-	if (args[0] === "factory") {
-		if (!(`factory-${args[1]}` in FACTORY_USAGE)) {
-			console.error(`glimmervoid factory: expected ${Object.values(FACTORY_USAGE).join(", or ")}`);
-			return 1;
-		}
-		return runAgentApiCli([`factory-${args[1]}`, ...args.slice(2)]);
-	}
 	const verb = args[0];
 	if (!verb || !isAgentApiVerb(verb)) {
 		console.error(`glimmervoid: ${verb || "that"} is not an agent command`);
@@ -202,29 +160,12 @@ async function runAgentApiCli(args) {
 	}
 	const body = BODY_BUILDERS[verb](args.slice(1));
 	if (!body) {
-		if (isFactoryVerb(verb)) {
-			console.error(`glimmervoid factory: expected ${FACTORY_USAGE[verb]}`);
-			return 1;
-		}
-		if (isOrchestratorAgentVerb(verb)) {
-			console.error(`glimmervoid ${verb}: expected a work id matching wrk-[0-9a-f]{16}`);
-			return 1;
-		}
-		if (verb === "edit") {
-			console.error("glimmervoid edit: this command needs a file path, for example \"glimmervoid edit drafts/post.md\"");
-			return 1;
-		}
-		console.error(`glimmervoid ${verb}: this command needs text, for example "glimmervoid ${verb} check the failing test"`);
-		return 1;
-	}
-	const rawUrl = process.env[AGENT_URL_ENV];
-	if (!rawUrl) {
-		console.error(`glimmervoid: ${AGENT_URL_ENV} is not set, so this is not a Glimmervoid session`);
+		console.error(AGENT_COMMAND_HELP[verb].missingArgumentHint ?? `glimmervoid ${verb}: this command needs an argument`);
 		return 1;
 	}
-	const target = verbEndpoint(rawUrl, verb);
+	const target = sessionEndpoint(verb);
 	if (!target.ok) {
-		console.error(`glimmervoid: ${AGENT_URL_ENV} must be a loopback http url under ${AGENT_PATH_PREFIX}, so nothing was sent`);
+		console.error(target.error);
 		return 1;
 	}
 	const reply = await postToAgentIngress({
@@ -235,5 +176,31 @@ async function runAgentApiCli(args) {
 	console.log(printableReply(verb, reply.text));
 	return reply.hasSuccessStatus && bodySaysOk(reply.text) ? 0 : 1;
 }
+function sessionEndpoint(verb) {
+	const rawUrl = process.env[AGENT_URL_ENV];
+	if (!rawUrl) return {
+		ok: false,
+		error: `glimmervoid: ${AGENT_URL_ENV} is not set, so this is not a Glimmervoid session`
+	};
+	const target = verbEndpoint(rawUrl, verb);
+	if (!target.ok) return {
+		ok: false,
+		error: `glimmervoid: ${AGENT_URL_ENV} must be a loopback http url under ${AGENT_PATH_PREFIX}, so nothing was sent`
+	};
+	return target;
+}
+async function askAgentApi(verb, body) {
+	const target = sessionEndpoint(verb);
+	if (!target.ok) return {
+		ok: false,
+		error: target.error
+	};
+	const reply = await postToAgentIngress({
+		endpoint: target.endpoint,
+		token: target.token,
+		body
+	});
+	return parseJsonOrNull(reply.text);
+}
 //#endregion
-export { runAgentApiCli as n, sessionLimitsHelpLines as r, postToAgentIngress as t };
+export { sessionLimitsHelpLines as i, postToAgentIngress as n, runAgentApiCli as r, askAgentApi as t };