@duyquangnvx/create-agent-cli 0.31.0 → 0.33.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.33.0 (2026-11-10)
+
+### Changed
+
+- **Breaking:** `ctx.login(name)` returns `Promise<string>`, and the Runtime finds a Login when the Command first asks for it, once per run, no longer before `plan`, `run` or `start`: write `await ctx.login(name)`. A Command that lists a Login and returns before it asks runs on a machine not signed in, and one that asks with none stored fails with `APPROVAL_PENDING` from that call, or with `LOGIN_REQUIRED` in a dry run, which names that Login alone; of Logins asked for at once, only the first one missing starts an Approval. Ask before any effect a rerun must not repeat.
+
+### Fixed
+
+- A Login's device or token endpoint that answers with a body that is not JSON, or with JSON that is no OAuth answer, such as a proxy or a password page in front of the server, fails the run with the new Runtime code `NOT_OAUTH` (exit 3), naming the endpoint and its status in the message and in `details` (`login`, `endpoint`, `status`), where it failed with `INTERNAL` (exit 70). `runtimeCodes.NOT_OAUTH` is exported.
+
+### Upgrade from v0.32.0
+
+- Every call of `ctx.login(name)` becomes `await ctx.login(name)`: a call left without it still type-checks inside a template literal, and sends `[object Promise]` as the token.
+- A Command with an effect before its first `ctx.login` asks first, since the rerun after an Approval starts the Command over.
+
+## v0.32.0 (2026-11-10)
+
+### Added
+
+- A Login in `defineCli({ logins })` may be a function of the run's env that returns its declaration, for a CLI whose user picks its server with a variable: `ctx.login`, its refresh, `login`, `logout` and `doctor`'s row build it from each run's `env`, and an error it throws fails the run before any request. A stored Login is kept per token endpoint and client id, so a token from one server is never sent to another. `LoginSource` and `LoginDeclarations` are exported.
+- A Grant: a Command lists in `grants` the Logins it asks a token for one action from, and `ctx.grant(name, { scope })`, typed to those names, asks the Login's server for an Approval of that scope through the device flow, taking up the one pending for the same scope. Until the person approves it fails with `APPROVAL_PENDING` (exit 75) and the rerun with `--wait 100`; a refused one fails with `APPROVAL_DENIED` and an expired one with `APPROVAL_EXPIRED` and the rerun, both exit 2. The token is given to the run only, never stored or refreshed, and the Login's Secret does not stand in for it. `--wait <seconds>` is a Standard flag of a Command with `grants`, `defineCli` throws on a name the CLI does not declare, and `ctx.grant` throws in a dry run. `GrantOptions` is exported.
+
 ## v0.31.0 (2026-11-10)
 
 ### Added

package/dist/bin.js

@@ -7198,9 +7198,9 @@ const WAIT_FLAG = standardFlag("--wait", {
 	takes: "value",
 	schema: WAIT_SECONDS
 });
-/** Whether `--wait` is a Standard flag of the Command: it is of one that declares a Login. */
+/** Whether `--wait` is a Standard flag of the Command: it is of one that declares a Login or Grant. */
 function takesWait(command) {
-	return (command.logins ?? []).length > 0;
+	return (command.logins ?? []).length > 0 || (command.grants ?? []).length > 0;
 }
 const EFFECT_FLAGS = {
 	read: [JSON_FLAG],
@@ -7815,6 +7815,7 @@ const APPROVAL_PENDING = "APPROVAL_PENDING";
 const APPROVAL_DENIED = "APPROVAL_DENIED";
 const APPROVAL_EXPIRED = "APPROVAL_EXPIRED";
 const LOGIN_REJECTED = "LOGIN_REJECTED";
+const NOT_OAUTH = "NOT_OAUTH";
 function loginStep(name) {
 	return ["login", name];
 }
@@ -7829,12 +7830,39 @@ function loginRequired(names, rerun) {
 		next: [...names.map(loginStep), rerun]
 	});
 }
+function loginAsking(name) {
+	return {
+		login: name,
+		subject: `signing in to ${name}`,
+		denied: () => approvalDenied(name),
+		expired: () => approvalExpired(name)
+	};
+}
+/** A Grant's Approval, whose expiry the rerun of the Command heals with a new code. */
+function grantAsking(name, scope, rerun) {
+	const subject = `the grant of ${scope} from ${name}`;
+	return {
+		login: name,
+		subject,
+		denied: () => new CliError({
+			code: APPROVAL_DENIED,
+			message: `the person refused ${subject}`,
+			hint: "ask the person whether to go ahead, and run the Command again only if they agree"
+		}),
+		expired: () => new CliError({
+			code: APPROVAL_EXPIRED,
+			message: `the code for ${subject} expired before it was approved`,
+			hint: "run the Next step for a new code, and pass its link and code to the person",
+			next: [rerun]
+		})
+	};
+}
 /** The wait ran out before the person approved: the same Approval stays pending for the rerun. */
-function approvalPending(name, approval, rerun) {
+function approvalPending({ subject }, approval, rerun) {
 	const { verificationUri, userCode, verificationUriComplete } = approval;
 	return new CliError({
 		code: APPROVAL_PENDING,
-		message: `signing in to ${name} waits for the code ${userCode} to be approved at ${verificationUriComplete ?? verificationUri}`,
+		message: `${subject} waits for the code ${userCode} to be approved at ${verificationUriComplete ?? verificationUri}`,
 		hint: "the person sees only your reply: write the link and the code in it, then run the Next step, which waits for the approval",
 		details: {
 			verificationUri,
@@ -7872,6 +7900,19 @@ function approvalExpired(name) {
 		next: [loginStep(name)]
 	});
 }
+/** An endpoint of a Login that answered as something other than its OAuth server. */
+function notOAuth({ login, url: endpoint }, status, cause) {
+	return new CliError({
+		code: NOT_OAUTH,
+		message: `${endpoint} answered ${status}, which is no OAuth answer`,
+		hint: `${endpoint} does not reach the OAuth server the Login ${login} declares: a proxy or a password page may stand in front of it, or the CLI points at the wrong server; ask whoever runs ${new URL(endpoint).origin} for the URL that reaches it`,
+		details: {
+			login,
+			endpoint,
+			status
+		}
+	}, { cause });
+}
 //#endregion
 //#region ../agent-cli/dist/runtime-codes.js
 const DOCTOR_PROBLEMS = "DOCTOR_PROBLEMS";
@@ -7915,7 +7956,8 @@ const anyCommandErrors = {
 	[APPROVAL_PENDING]: { class: "wait" },
 	[APPROVAL_DENIED]: { class: "operator" },
 	[APPROVAL_EXPIRED]: { class: "operator" },
-	[LOGIN_REJECTED]: { class: "operator" }
+	[LOGIN_REJECTED]: { class: "operator" },
+	[NOT_OAUTH]: { class: "source" }
 };
 /**
 * The Runtime codes only some Commands reach: each Command that throws one, Built-in or the CLI's
@@ -7951,7 +7993,7 @@ function mustDeclare(code, table) {
 //#region ../agent-cli/dist/define-command.js
 /** Throws when the Command's declaration breaks a rule its type cannot express; `label` names it. */
 function checkCommand(command, label, table, logins) {
-	checkLogins(command.logins ?? [], label, logins);
+	checkLogins([...command.logins ?? [], ...command.grants ?? []], label, logins);
 	checkNoStandardFlags(command, label);
 	checkForce(command, label);
 	checkArrayArgLast(label, command.args);
@@ -7999,6 +8041,14 @@ function cliErrorOf(code, init, options) {
 	}, options);
 }
 //#endregion
+//#region ../agent-cli/dist/login/declared.js
+/** The declaration of the Login `name` for a run in `env`. */
+function declaredLogin(logins, name, env) {
+	const login = logins[name];
+	if (login === void 0) throw new Error(`${name} is not a Login the CLI declares`);
+	return typeof login === "function" ? login(env) : login;
+}
+//#endregion
 //#region ../agent-cli/dist/login/store.js
 const storedLoginSchema = object({
 	accessToken: string(),
@@ -8015,16 +8065,20 @@ const approvalSchema = object({
 	interval: number$1()
 });
 const KEY_LENGTH = 16;
-function keyOf({ tokenEndpoint, clientId }) {
-	return createHash("sha256").update(`${tokenEndpoint}\n${clientId}`).digest("hex").slice(0, KEY_LENGTH);
+function keyOf(...parts) {
+	return createHash("sha256").update(parts.join("\n")).digest("hex").slice(0, KEY_LENGTH);
 }
 function loginFilesOf(userFile, login) {
-	const key = keyOf(login);
+	const key = keyOf(login.tokenEndpoint, login.clientId);
 	return {
 		stored: userFile(`login-${key}`, storedLoginSchema),
 		approval: userFile(`approval-${key}`, approvalSchema)
 	};
 }
+/** The Approval pending for a Grant of `scope`, kept apart from the Login's and every other scope's. */
+function grantApprovalOf(userFile, { tokenEndpoint, clientId }, scope) {
+	return userFile(`grant-${keyOf(tokenEndpoint, clientId, scope)}`, approvalSchema);
+}
 /** The file's value, or `undefined` once its `expiresAt` has passed, removing the file then. */
 async function readUnexpired(file, clock) {
 	const value = await file.read();
@@ -8050,9 +8104,12 @@ const errorSchema = object({ error: string() });
 function isoAfter(clock, seconds) {
 	return new Date(clock.now() + seconds * MS_PER_S).toISOString();
 }
-/** POSTs `form` to an OAuth endpoint and parses its JSON answer, whatever its status. */
-async function postForm(fetch, url, form, { ignoreStop } = {}) {
-	const response = await fetch(url, {
+/**
+* POSTs `form` to an OAuth endpoint and parses its JSON answer, whatever its status. A body that
+* is not JSON fails with `NOT_OAUTH`.
+*/
+async function postForm(fetch, endpoint, form, { ignoreStop } = {}) {
+	const response = await fetch(endpoint.url, {
 		method: "POST",
 		once: false,
 		...ignoreStop === void 0 ? {} : { ignoreStop },
@@ -8060,15 +8117,21 @@ async function postForm(fetch, url, form, { ignoreStop } = {}) {
 		body: new URLSearchParams(form)
 	});
 	const text = await response.text();
+	const { status } = response;
 	try {
-		return JSON.parse(text);
+		return {
+			endpoint,
+			status,
+			body: JSON.parse(text)
+		};
 	} catch (error) {
-		throw new Error(`${url} answered ${response.status} with a body that is not JSON`, { cause: error });
+		throw notOAuth(endpoint, status, error);
 	}
 }
-function parsedAnswer(schema, body, url) {
+/** The answer's body as `schema` has it, or a `NOT_OAUTH` for one of another shape. */
+function parsedAnswer(schema, { endpoint, status, body }) {
 	const parsed = schema.safeParse(body);
-	if (!parsed.success) throw new Error(`${url} answered ${JSON.stringify(body)}, not an OAuth answer`);
+	if (!parsed.success) throw notOAuth(endpoint, status);
 	return parsed.data;
 }
 function storedLoginOf({ access_token, refresh_token, expires_in }, clock) {
@@ -8094,8 +8157,12 @@ async function refreshed(name, login, file, refreshToken, ctx) {
 		client_id: login.clientId
 	};
 	return await ctx.runToEnd(`refreshing the Login ${name}`, async () => {
-		const body = await postForm(ctx.fetch, login.tokenEndpoint, form, { ignoreStop: true });
-		const granted = tokenSchema.safeParse(body);
+		const endpoint = {
+			login: name,
+			url: login.tokenEndpoint
+		};
+		const answer = await postForm(ctx.fetch, endpoint, form, { ignoreStop: true });
+		const granted = tokenSchema.safeParse(answer.body);
 		if (granted.success) {
 			const stored = {
 				refreshToken,
@@ -8104,7 +8171,7 @@ async function refreshed(name, login, file, refreshToken, ctx) {
 			await file.write(stored);
 			return stored;
 		}
-		const { error } = parsedAnswer(errorSchema, body, login.tokenEndpoint);
+		const { error } = parsedAnswer(errorSchema, answer);
 		if (error !== "invalid_grant") throw new Error(`${login.tokenEndpoint} refused the refresh of ${name} with ${error}`);
 		await file.remove();
 	});
@@ -8172,11 +8239,12 @@ function tokenScopeOf(ctx) {
 }
 //#endregion
 //#region ../agent-cli/dist/login/doctor-rows.js
-function loginRow(name, login, runAs) {
+function loginRow(name, logins, runAs) {
 	return {
 		name: `login ${name}`,
 		advisory: true,
 		run: async (ctx) => {
+			const login = declaredLogin(logins, name, ctx.env);
 			const set = setSecretOf(login, tokenScopeOf(ctx).secret);
 			if (set !== void 0) return {
 				state: "ok",
@@ -8197,16 +8265,16 @@ function loginRow(name, login, runAs) {
 }
 /** One `doctor` row per Login: where its token comes from, and `login` as the fix with none. */
 function loginRows(logins, runAs) {
-	return Object.entries(logins).map(([name, login]) => loginRow(name, login, runAs));
+	return Object.keys(logins).map((name) => loginRow(name, logins, runAs));
 }
 //#endregion
 //#region ../agent-cli/dist/version.js
 /** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
 function buildStamp() {
 	return {
-		"sha": "7dd915f",
+		"sha": "3716c19",
 		"dirty": false,
-		"builtAt": "2026-11-10T03:40:31.000Z"
+		"builtAt": "2026-11-10T16:12:55.000Z"
 	};
 }
 /** The first line of `--version`: the version, and the commit and time of a stamped build. */
@@ -10050,13 +10118,6 @@ function doctorCommand(cli, launch) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/login/declared.js
-function declaredLogin(logins, name) {
-	const login = logins[name];
-	if (login === void 0) throw new Error(`${name} is not a Login the CLI declares`);
-	return login;
-}
-//#endregion
 //#region ../agent-cli/dist/login/device-flow.js
 const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
 /** RFC 8628 §3.2: the interval when the server gives none. */
@@ -10071,12 +10132,18 @@ const deviceSchema = object({
 	expires_in: number$1(),
 	interval: number$1().optional()
 });
-async function startApproval(login, { fetch, clock }) {
+async function startApproval(name, login, { fetch, clock }) {
 	const form = {
 		client_id: login.clientId,
 		...login.scope === void 0 ? {} : { scope: login.scope }
 	};
-	const device = parsedAnswer(deviceSchema, await postForm(fetch, login.deviceEndpoint, form), login.deviceEndpoint);
+	const answer = await postForm(fetch, {
+		login: name,
+		url: login.deviceEndpoint
+	}, form);
+	const refused = errorSchema.safeParse(answer.body);
+	if (refused.success) throw new Error(`${login.deviceEndpoint} refused the device request with ${refused.data.error}`);
+	const device = parsedAnswer(deviceSchema, answer);
 	return {
 		deviceCode: device.device_code,
 		userCode: device.user_code,
@@ -10086,37 +10153,41 @@ async function startApproval(login, { fetch, clock }) {
 		interval: device.interval ?? DEFAULT_INTERVAL_S
 	};
 }
-async function pollApproval(name, login, { approval, takenUp }, scope, signal) {
+async function pollApproval(asking, login, { approval, takenUp }, scope, signal) {
 	const form = {
 		grant_type: DEVICE_CODE_GRANT,
 		device_code: approval.deviceCode,
 		client_id: login.clientId
 	};
+	const endpoint = {
+		login: asking.login,
+		url: login.tokenEndpoint
+	};
 	let intervalS = approval.interval;
 	for (let first = true;; first = false) {
 		if (!(first && takenUp)) await scope.clock.sleep(intervalS * MS_PER_S, signal);
-		const body = await postForm(scope.fetch, login.tokenEndpoint, form);
-		const granted = tokenSchema.safeParse(body);
+		const answer = await postForm(scope.fetch, endpoint, form);
+		const granted = tokenSchema.safeParse(answer.body);
 		if (granted.success) return storedLoginOf(granted.data, scope.clock);
-		const { error } = parsedAnswer(errorSchema, body, login.tokenEndpoint);
+		const { error } = parsedAnswer(errorSchema, answer);
 		if (error === "slow_down") intervalS += SLOW_DOWN_S;
-		else if (error !== "authorization_pending") throw refusal(name, login, error);
+		else if (error !== "authorization_pending") throw refusal(asking, login, error);
 	}
 }
 /** The error a token endpoint's answer other than pending or slow down ends the polling with. */
-function refusal(name, login, error) {
-	if (error === "access_denied") return approvalDenied(name);
-	if (error === "expired_token" || error === "invalid_grant") return approvalExpired(name);
+function refusal(asking, login, error) {
+	if (error === "access_denied") return asking.denied();
+	if (error === "expired_token" || error === "invalid_grant") return asking.expired();
 	return /* @__PURE__ */ new Error(`${login.tokenEndpoint} refused the device code with ${error}`);
 }
 function endsApproval(error) {
 	return error instanceof CliError && (error.code === "APPROVAL_DENIED" || error.code === "APPROVAL_EXPIRED");
 }
 /** Takes up the pending Approval, or asks for one and keeps it as a User file, and prints its code. */
-async function askedApproval(login, files, scope) {
-	const pending = await readUnexpired(files.approval, scope.clock);
-	const approval = pending ?? await startApproval(login, scope);
-	if (pending === void 0) await files.approval.write(approval);
+async function askedApproval(name, login, file, scope) {
+	const pending = await readUnexpired(file, scope.clock);
+	const approval = pending ?? await startApproval(name, login, scope);
+	if (pending === void 0) await file.write(approval);
 	scope.progress(`open ${approval.verificationUriComplete ?? approval.verificationUri} and approve code ${approval.userCode}`);
 	return {
 		approval,
@@ -10125,28 +10196,39 @@ async function askedApproval(login, files, scope) {
 }
 /** The `APPROVAL_PENDING` of the pending Approval, or of a new one, without polling it. */
 async function pendingApproval(name, login, files, scope, rerun) {
-	const { approval } = await askedApproval(login, files, scope);
-	return approvalPending(name, approval, rerun);
+	const { approval } = await askedApproval(name, login, files.approval, scope);
+	return approvalPending(loginAsking(name), approval, rerun);
 }
 /**
-* Polls the pending Approval, or a new one, until the person approves, and stores the Login. A run
-* that stops first leaves the Approval for the next.
+* Polls the Approval pending in `file`, or a new one, until the person approves, removing it once
+* refused or expired. An approved one stays until what it granted is kept, so a cut-off run loses nothing.
 */
-async function signIn(name, login, files, scope, { waitS, rerun }) {
-	const asked = await askedApproval(login, files, scope);
+async function approved(asking, login, file, scope, { waitS, rerun }) {
+	const asked = await askedApproval(asking.login, login, file, scope);
 	const wait = scope.deadline(waitS * MS_PER_S);
-	let stored;
+	let granted;
 	try {
-		stored = await pollApproval(name, login, asked, scope, wait);
+		granted = await pollApproval(asking, login, asked, scope, wait);
 	} catch (error) {
-		if (wait.aborted && !scope.signal.aborted) throw approvalPending(name, asked.approval, rerun);
-		if (endsApproval(error)) await files.approval.remove();
+		if (wait.aborted && !scope.signal.aborted) throw approvalPending(asking, asked.approval, rerun);
+		if (endsApproval(error)) await file.remove();
 		throw error;
 	}
+	return granted;
+}
+/** Polls the pending Approval, or a new one, until the person approves, and stores the Login. */
+async function signIn(name, login, files, scope, wait) {
+	const stored = await approved(loginAsking(name), login, files.approval, scope, wait);
 	await files.stored.write(stored);
 	await files.approval.remove();
 	return stored;
 }
+/** Polls the Approval of the Grant's scope, or a new one, until the person approves: its token. */
+async function grant(asking, login, file, scope, wait) {
+	const { accessToken } = await approved(asking, login, file, scope, wait);
+	await file.remove();
+	return accessToken;
+}
 //#endregion
 //#region ../agent-cli/dist/built-ins/login-name.js
 /** The Login a `login` or `logout` run names, or the only one; with several, the name is needed. */
@@ -10231,7 +10313,7 @@ function logoutCommand(cli, logins, names) {
 				cliName: cli.name,
 				command: "logout"
 			}, given, names);
-			const login = declaredLogin(logins, name);
+			const login = declaredLogin(logins, name, ctx.env);
 			return {
 				login: name,
 				stored: await loginFilesOf(ctx.userFile, login).stored.read() !== void 0,
@@ -10240,7 +10322,7 @@ function logoutCommand(cli, logins, names) {
 			};
 		},
 		apply: async ({ login: name, secret }, ctx) => {
-			const login = declaredLogin(logins, name);
+			const login = declaredLogin(logins, name, ctx.env);
 			const file = loginFilesOf(ctx.userFile, login).stored;
 			const stored = await file.read();
 			const kept = secret === void 0 ? {} : { secret };
@@ -10317,7 +10399,7 @@ function loginCommand(cli, logins, names) {
 				cliName: cli.name,
 				command: "login"
 			}, given, names);
-			const login = declaredLogin(logins, name);
+			const login = declaredLogin(logins, name, ctx.env);
 			const token = await currentTokenOf(login, tokenScopeOf(ctx));
 			const stored = await readStored(loginFilesOf(ctx.userFile, login).stored, ctx.clock);
 			return {
@@ -10329,7 +10411,7 @@ function loginCommand(cli, logins, names) {
 		},
 		apply: async ({ login: name, wait, found }, ctx) => {
 			if (found !== void 0) return found;
-			const login = declaredLogin(logins, name);
+			const login = declaredLogin(logins, name, ctx.env);
 			const files = loginFilesOf(ctx.userFile, login);
 			const stored = await readStored(files.stored, ctx.clock);
 			if (stored?.refreshToken !== void 0 && await refreshed(name, login, files.stored, stored.refreshToken, ctx) !== void 0) return {
@@ -12179,68 +12261,106 @@ function approvalRerun(ctx) {
 		add: [WAIT_FLAG.flag, String(100)]
 	});
 }
-async function tokensOf(names, logins, ctx, waitS) {
-	const found = await Promise.all(names.map(async (name) => {
-		const login = declaredLogin(logins, name);
-		return {
-			name,
-			token: ctx.dryRun ? await currentTokenOf(login, tokenScopeOf(ctx)) : await freshTokenOf(name, login, ctx)
-		};
+/** The token of the Login `name`, signing in first, for at most `waitS` seconds, when none is found. */
+async function tokenOf(name, logins, ctx, waitS) {
+	const login = declaredLogin(logins, name, ctx.env);
+	const found = ctx.dryRun ? await currentTokenOf(login, tokenScopeOf(ctx)) : await freshTokenOf(name, login, ctx);
+	if (found === void 0 && ctx.dryRun) throw loginRequired([name], ctx.rerun());
+	const token = found ?? storedToken(await signIn(name, login, loginFilesOf(ctx.userFile, login), ctx, {
+		waitS,
+		rerun: approvalRerun(ctx)
 	}));
-	const missing = found.flatMap(({ name, token }) => token === void 0 ? [name] : []);
-	if (missing.length > 0 && ctx.dryRun) throw loginRequired(missing, ctx.rerun());
-	const tokens = /* @__PURE__ */ new Map();
-	for (const { name, token } of found) {
-		if (token !== void 0) {
-			tokens.set(name, token);
-			continue;
-		}
-		const login = declaredLogin(logins, name);
-		const stored = await signIn(name, login, loginFilesOf(ctx.userFile, login), ctx, {
-			waitS,
-			rerun: approvalRerun(ctx)
-		});
-		tokens.set(name, storedToken(stored));
-	}
 	ctx.signal.throwIfAborted();
-	return tokens;
+	return token;
+}
+/**
+* `ctx.login`, which finds each Login once, when first asked, and the tokens it gave. A Login it
+* fails to find fails every Login asked for after it the same way.
+*/
+function loggingIn(ctx, names, logins, waitS) {
+	const asked = /* @__PURE__ */ new Map();
+	const given = /* @__PURE__ */ new Map();
+	let turn = Promise.resolve();
+	const find = async (name, earlier) => {
+		await earlier;
+		const token = await tokenOf(name, logins, ctx, waitS);
+		given.set(name, token);
+		return token;
+	};
+	const login = async (name) => {
+		if (!names.includes(name)) undeclaredLogin(name);
+		const asking = asked.get(name) ?? find(name, turn);
+		asked.set(name, asking);
+		turn = asking;
+		return (await asking).value;
+	};
+	return {
+		login,
+		given
+	};
 }
 /** The Login a `LOGIN_REJECTED` names in `details.login`, or the Command's only one. */
-function rejectedName(rejected, tokens) {
+function rejectedName(rejected, names) {
 	const { details } = rejected;
 	if (typeof details === "object" && details !== null && "login" in details) return typeof details.login === "string" ? details.login : void 0;
-	const [only, ...rest] = tokens.keys();
+	const [only, ...rest] = names;
 	return rest.length === 0 ? only : void 0;
 }
 /**
 * What a run whose Command threw `error` fails with: a `LOGIN_REJECTED` of a stored Login drops
 * it for a new Approval, one of a Secret's token fails as the operator's to fix.
 */
-async function afterRejection(error, tokens, logins, ctx) {
+async function afterRejection(error, { names, given }, logins, ctx) {
 	if (!(error instanceof CliError && error.code === "LOGIN_REJECTED")) return error;
-	const name = rejectedName(error, tokens);
-	const token = name === void 0 ? void 0 : tokens.get(name);
-	if (name === void 0 || token === void 0) return new Error(`the Command threw ${LOGIN_REJECTED} naming no Login it declares in details.login`, { cause: error });
-	const login = declaredLogin(logins, name);
+	const name = rejectedName(error, names);
+	const token = name === void 0 ? void 0 : given.get(name);
+	if (name === void 0 || token === void 0) return new Error(`the Command threw ${LOGIN_REJECTED} naming no Login ctx.login gave it in details.login`, { cause: error });
+	const login = declaredLogin(logins, name, ctx.env);
 	if (token.source.kind === "secret" && login.secret !== void 0) return secretRejected(name, login.secret, error);
 	const files = loginFilesOf(ctx.userFile, login);
 	await files.stored.remove();
 	if (ctx.dryRun) return loginRequired([name], ctx.rerun());
 	return await pendingApproval(name, login, files, ctx, approvalRerun(ctx));
 }
+/** `ctx.grant`: polls the Approval of `scope` for at most `waitS` seconds, and keeps no token. */
+function granting(ctx, grants, logins, waitS) {
+	return async (name, { scope }) => {
+		if (!grants.includes(name)) undeclaredGrant(name);
+		if (ctx.dryRun) throw new Error(`ctx.grant("${name}") in a dry run, which asks for nothing: ask in apply`);
+		const login = {
+			...declaredLogin(logins, name, ctx.env),
+			scope
+		};
+		return await grant(grantAsking(name, scope, ctx.rerun({ remove: [WAIT_FLAG.flag] })), login, grantApprovalOf(ctx.userFile, login, scope), ctx, {
+			waitS,
+			rerun: approvalRerun(ctx)
+		});
+	};
+}
 /**
-* Runs `work` with a `ctx` whose `login` gives each named Login's token, signing in first, for at
-* most `waitS` seconds, where one is missing. A `LOGIN_REJECTED` from `work` drops the stored Login.
+* Runs `work` with a `ctx` whose `login` finds a named Login's token when first asked, signing in
+* first, for at most `waitS` seconds, where it is missing, and whose `grant` asks for a Grant. A
+* `LOGIN_REJECTED` from `work` drops the stored Login.
 */
-async function withLogins(ctx, names, logins, waitS, work) {
-	const tokens = names.length === 0 ? /* @__PURE__ */ new Map() : await tokensOf(names, logins, ctx, waitS ?? 0);
-	const loggedIn = derived(ctx, { login: (name) => tokens.get(name)?.value ?? undeclaredLogin(name) });
+async function withLogins(ctx, { logins: names, grants }, logins, waitS, work) {
+	const { login, given } = loggingIn(ctx, names, logins, waitS ?? 0);
+	const loggedIn = derived(ctx, {
+		login,
+		grant: granting(ctx, grants, logins, waitS ?? 0)
+	});
 	try {
 		return await work(loggedIn);
 	} catch (error) {
-		throw await afterRejection(error, tokens, logins, ctx);
+		throw await afterRejection(error, {
+			names,
+			given
+		}, logins, ctx);
 	}
 }
+/** `ctx.grant` of a name the Command does not declare in `grants`, which only a cast reaches. */
+function undeclaredGrant(name) {
+	throw new Error(`ctx.grant("${name}") names a Login the Command does not declare in grants`);
+}
 /** `ctx.login` of a name the Command does not declare, which only a cast reaches. */
 function undeclaredLogin(name) {
 	throw new Error(`ctx.login("${name}") names a Login the Command does not declare`);
@@ -12300,7 +12420,10 @@ async function execute(command, input, unlogged, run) {
 		envFile,
 		fileError
 	}, unlogged.rerun());
-	return await withLogins(unlogged, command.logins ?? [], run.logins, run.flags.wait, (ctx) => executeLoggedIn(command, input, ctx, run));
+	return await withLogins(unlogged, {
+		logins: command.logins ?? [],
+		grants: command.grants ?? []
+	}, run.logins, run.flags.wait, (ctx) => executeLoggedIn(command, input, ctx, run));
 }
 async function executeLoggedIn(command, input, ctx, { flags, commandLine, started, outputs: runOutputs }) {
 	if (command.rows !== void 0) {
@@ -12539,7 +12662,8 @@ function contextOf(scope, control, { command, flags, project, deliver, latestRel
 	return {
 		...portsBase,
 		secret,
-		login: undeclaredLogin,
+		login: async (name) => undeclaredLogin(name),
+		grant: async (name) => undeclaredGrant(name),
 		userFile: scope.userFile,
 		fail: cliErrorOf,
 		deadline: (ms, options) => control.deadline(ms, options),
@@ -12898,7 +13022,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.31.0",
+	version: "0.33.0",
 	description: "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
 	type: "module",
 	engines: { "node": ">=22.12.0" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duyquangnvx/create-agent-cli",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
   "type": "module",
   "engines": {
@@ -21,7 +21,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@duyquangnvx/agent-cli": "0.31.0",
+    "@duyquangnvx/agent-cli": "0.33.0",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },