@actionway/cli 0.18.2 → 0.18.4

package/assets/skill/actionway/SKILL.md

@@ -36,6 +36,7 @@ Use the installed `actionway` CLI and its server-backed Capability Registry as t
    - `accepted`: immediately wait on the returned `job.jobRef`.
    - `completed`: consume the returned result.
    - `confirmation: strong`: never treat chat text alone as approval; follow a server-verifiable approval instruction or report that execution cannot continue.
+6. On `E_INSUFFICIENT_BALANCE`, stop the call. When the failure includes `top_up_url`, the user-facing response must render that exact field value as a Markdown link by substituting it into `[Top up Actionway balance](<top_up_url>)`; never leave it only in terminal JSON, replace it with a terminal command, or synthesize a URL for another environment. Ask the user to retry the original task after the top-up is complete.
 
 ## Handle asynchronous jobs
 

package/dist/index.js

@@ -12434,7 +12434,7 @@ var REFRESH_SKEW_S = 30;
 var TOKEN_TIMEOUT_MS = 2e4;
 var DISCOVERY_TIMEOUT_MS = 1e4;
 var SESSION_TIMEOUT_MS = 2e4;
-var DEFAULT_LOGIN_TIMEOUT_MS = 12e4;
+var DEFAULT_LOGIN_TIMEOUT_MS = 12e5;
 function stripSlash(url) {
   return url.replace(/\/+$/, "");
 }
@@ -12521,7 +12521,15 @@ async function fetchCliOAuthConfig(gateway, fetchImpl = fetch) {
     signal: AbortSignal.timeout(DISCOVERY_TIMEOUT_MS)
   });
   if (!response.ok) {
-    throw new Error(`Actionway login configuration is unavailable (${response.status})`);
+    let detail = "";
+    try {
+      const body2 = await response.json();
+      const code = typeof body2?.error?.code === "string" ? body2.error.code : "";
+      const message = typeof body2?.error?.message === "string" ? body2.error.message : "";
+      detail = [code, message].filter(Boolean).join(": ");
+    } catch {
+    }
+    throw new Error(`Actionway login configuration is unavailable (${response.status}${detail ? `; ${detail}` : ""})`);
   }
   const body = await response.json();
   if (typeof body !== "object" || body === null || !("issuer" in body) || typeof body.issuer !== "string" || !("client_id" in body) || typeof body.client_id !== "string" || !body.issuer.trim() || !body.client_id.trim()) {
@@ -12694,14 +12702,21 @@ async function waitForCode(state, timeoutMs) {
   const port = server.address().port;
   const timer = setTimeout(() => {
     rejectCode(
-      new CliError("E_BACKEND", `login timed out after ${Math.round(timeoutMs / 1e3)} seconds`, "run `actionway login` again")
+      new CliError(
+        "E_BACKEND",
+        `login timed out after ${Math.round(timeoutMs / 1e3)} seconds`,
+        "run `actionway login` again and ask the user to finish the browser sign-in promptly; pass --timeout-seconds <n> to allow more time"
+      )
     );
     server.close();
   }, timeoutMs);
   return {
     redirectUri: `http://127.0.0.1:${port}/callback`,
     code: code.finally(() => clearTimeout(timer)),
-    close: () => new Promise((resolve3) => server.listening ? server.close(() => resolve3()) : resolve3())
+    close: () => {
+      clearTimeout(timer);
+      return new Promise((resolve3) => server.listening ? server.close(() => resolve3()) : resolve3());
+    }
   };
 }
 async function readJsonObject(response) {
@@ -12720,8 +12735,14 @@ async function tokenRequest(issuer, body, fetchImpl) {
   });
   const value = await readJsonObject(response);
   if (!response.ok || typeof value.access_token !== "string") {
-    const message = typeof value.error_description === "string" ? value.error_description : "token request failed";
-    throw new CliError("E_BACKEND", message);
+    const code = typeof value.error === "string" ? value.error : "";
+    const description = typeof value.error_description === "string" ? value.error_description : "";
+    const message = [code, description].filter(Boolean).join(": ") || "token request failed";
+    throw new CliError(
+      "E_BACKEND",
+      message,
+      code === "invalid_client" ? "the client_id/issuer pair does not belong to one Actionway environment: clear ACTIONWAY_OAUTH_CLIENT_ID and ACTIONWAY_OAUTH_ISSUER (or drop --client-id/--issuer) and run `actionway login` again to rediscover both; if no overrides are set, the stored credentials are stale \u2014 run `actionway logout` then `actionway login`" : void 0
+    );
   }
   return {
     accessToken: value.access_token,
@@ -12796,19 +12817,44 @@ async function login(options = {}) {
   const onNotice = options.onNotice ?? ((message) => process.stderr.write(`${message}
 `));
   const gateway = resolveGatewayUrl(options.gateway, env);
+  const gatewaySource = options.gateway?.trim() ? "flag" : (env.ACTIONWAY_GATEWAY_URL ?? "").trim() ? "env" : "default";
   let clientId = options.clientId?.trim() || (env.ACTIONWAY_OAUTH_CLIENT_ID ?? "").trim();
   let issuer = options.issuer?.trim() || (env.ACTIONWAY_OAUTH_ISSUER ?? "").trim();
+  const clientIdSource = options.clientId?.trim() ? "flag" : (env.ACTIONWAY_OAUTH_CLIENT_ID ?? "").trim() ? "env" : "discovery";
+  const issuerSource = options.issuer?.trim() ? "flag" : (env.ACTIONWAY_OAUTH_ISSUER ?? "").trim() ? "env" : "discovery";
+  const authContext = () => ({
+    gateway_url: gateway,
+    gateway_source: gatewaySource,
+    ...issuer ? { issuer } : {},
+    issuer_source: issuerSource,
+    ...clientId ? { client_id: clientId } : {},
+    client_id_source: clientIdSource
+  });
+  const withAuthContext = (error) => {
+    if (error instanceof CliError) {
+      throw new CliError(error.code, error.message, error.hint, { ...error.extra ?? {}, auth_context: authContext() });
+    }
+    throw error;
+  };
+  if (!!clientId !== !!issuer) {
+    throw new CliError(
+      "E_SCHEMA",
+      "client_id and issuer overrides must be provided together",
+      "pass both --client-id and --issuer (or set both ACTIONWAY_OAUTH_CLIENT_ID and ACTIONWAY_OAUTH_ISSUER), or neither to use discovery",
+      { auth_context: authContext() }
+    );
+  }
   if (!clientId || !issuer) {
     let discovered;
     try {
       discovered = await fetchCliOAuthConfig(gateway, fetchImpl);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new CliError(
+      return withAuthContext(new CliError(
         "E_BACKEND",
         `login failed: ${message}`,
-        "retry later or pass --client-id and --issuer explicitly"
-      );
+        "check auth_context.gateway_url is the intended Actionway environment (unset ACTIONWAY_GATEWAY_URL or fix --gateway if not) and run `actionway login` again; if the gateway is correct, the environment is misconfigured \u2014 report this error to the user instead of retrying (passing both --client-id and --issuer explicitly remains available as a temporary override)"
+      ));
     }
     clientId ||= discovered.clientId;
     issuer ||= discovered.issuer;
@@ -12865,6 +12911,8 @@ ${authorizeUrl}`);
     };
     saveCredentials(credentials, env);
     return { credentials, account };
+  } catch (error) {
+    return withAuthContext(error);
   } finally {
     await callback.close();
   }
@@ -12917,7 +12965,7 @@ function failFromError2(err, fallbackHint) {
   });
 }
 function registerAuthCommands(program2) {
-  program2.command("login").description("Authenticate with Actionway in the browser (Clerk OAuth with PKCE).").option("--gateway <url>", "Actionway public origin").option("--client-id <id>", "Actionway OAuth client id (default: discovered from the public origin)").option("--issuer <url>", "Actionway OAuth issuer (default: discovered from the public origin)").option("--timeout-seconds <n>", "how long to wait for browser authentication").option("--no-browser", "print the authorize URL instead of opening a browser").action(async (opts) => {
+  program2.command("login").description("Authenticate with Actionway in the browser (Clerk OAuth with PKCE).").option("--gateway <url>", "Actionway public origin").option("--client-id <id>", "Actionway OAuth client id (must be paired with --issuer; default: both discovered from the public origin)").option("--issuer <url>", "Actionway OAuth issuer (must be paired with --client-id; default: both discovered from the public origin)").option("--timeout-seconds <n>", "how long to wait for browser authentication").option("--no-browser", "print the authorize URL instead of opening a browser").action(async (opts) => {
     try {
       const { credentials, account } = await login({
         ...opts.gateway ? { gateway: opts.gateway } : {},
@@ -13335,7 +13383,10 @@ async function captureInstallStarted(input) {
       {
         method: "POST",
         headers: { Accept: "application/json", "Content-Type": "application/json" },
-        body: JSON.stringify({ installSessionId: input.installSessionId })
+        body: JSON.stringify({
+          installSessionId: input.installSessionId,
+          installSource: input.installSource
+        })
       },
       ANALYTICS_TIMEOUT_MS,
       input.fetchImpl ?? fetch
@@ -13348,6 +13399,7 @@ async function captureInstallStarted(input) {
 async function requestCliInstallSession(input) {
   const url = new URL(`${stripSlash2(input.gateway)}/api/auth/cli-session`);
   url.searchParams.set("install_session_id", input.installSessionId);
+  url.searchParams.set("install_source", input.installSource);
   let response;
   try {
     response = await fetchWithTimeout(
@@ -13393,6 +13445,7 @@ async function connectInstallSession(input) {
     gateway,
     accessToken: credentials.access_token,
     installSessionId: input.installSessionId,
+    installSource: input.installSource,
     fetchImpl
   });
 }
@@ -13410,15 +13463,20 @@ function failFromError3(err) {
 function registerInitCommand(program2) {
   program2.command("init").description(
     "Complete browser authentication and stage the Actionway Skill for your agent to install. The CLI never writes into an agent's own configuration directory."
-  ).option("--gateway <url>", "Actionway public origin").option("--client-id <id>", "Actionway OAuth client id").option("--issuer <url>", "Actionway OAuth issuer").option("--timeout-seconds <n>", "how long to wait for browser authentication").option("--install-session-id <uuid>", "onboarding install session id").option("--no-browser", "print the authorize URL instead of opening a browser").addOption(new Option("--skill-only").hideHelp()).action(async (opts) => {
+  ).option("--gateway <url>", "Actionway public origin").option("--client-id <id>", "Actionway OAuth client id (must be paired with --issuer)").option("--issuer <url>", "Actionway OAuth issuer (must be paired with --client-id)").option("--timeout-seconds <n>", "how long to wait for browser authentication").option("--install-session-id <uuid>", "onboarding install session id").option("--no-browser", "print the authorize URL instead of opening a browser").addOption(new Option("--skill-only").hideHelp()).action(async (opts) => {
     try {
       const skill = materializeSkill();
       if (opts.skillOnly) {
         ok({ skill });
       }
+      const installSource = opts.installSessionId ? "website_prompt" : "manual_init";
       const installSessionId = resolveInstallSessionId(opts.installSessionId);
       const initGateway = initGatewayUrl(opts.gateway, process.env);
-      await captureInstallStarted({ gateway: initGateway, installSessionId });
+      await captureInstallStarted({
+        gateway: initGateway,
+        installSessionId,
+        installSource
+      });
       let loginStarted = false;
       if (!whoamiSnapshot()) {
         loginStarted = true;
@@ -13433,7 +13491,8 @@ function registerInitCommand(program2) {
       }
       const account = await connectInstallSession({
         ...opts.gateway ? { explicitGateway: opts.gateway } : {},
-        installSessionId
+        installSessionId,
+        installSource
       });
       const snapshot = whoamiSnapshot();
       ok({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actionway/cli",
-  "version": "0.18.2",
+  "version": "0.18.4",
   "description": "actionway CLI 的本地端壳：Clerk OAuth 鉴权 + cli-core 共享命令面 + init / update / skill 物化 / 版本三链路（终端用户本地 Codex / Claude Code 使用）",
   "type": "module",
   "bin": {