@actionway/cli-dev 0.0.0-dev.32704160099.89976dd6db2f → 0.0.0-dev.32848766753.0e740c8908f1

package/assets/skill/actionway/references/capabilities/weather-alert.md

@@ -0,0 +1,12 @@
+# Weather Alert (`weather.alert.get`)
+
+Get the current details of one U.S. weather alert by its alert identifier.
+
+- Users ask for it as: get details for a weather alert; 查询一条天气预警的详情; weather alert details; NWS alert details; 天气预警详情.
+- Takes text → returns structured-data. Runs synchronously.
+
+## Indicative price
+
+free
+
+Prices are indicative catalog values refreshed with each skill release. Before calling, Inspect the chosen variant: Inspect's input Schema and USD quote are authoritative.

package/assets/skill/actionway/references/capabilities/weather-alerts.md

@@ -0,0 +1,12 @@
+# Weather Alerts (`weather.alerts.list`)
+
+List active U.S. weather alerts for a state, territory, or marine area.
+
+- Users ask for it as: list active weather alerts for an area; 查询某个地区当前的天气预警; active weather alerts; NWS alerts; 天气预警; 气象预警.
+- Takes text → returns structured-data. Runs synchronously.
+
+## Indicative price
+
+free
+
+Prices are indicative catalog values refreshed with each skill release. Before calling, Inspect the chosen variant: Inspect's input Schema and USD quote are authoritative.

package/dist/index.js

@@ -9353,9 +9353,11 @@ var Transport = class {
   authHeader;
   fetchImpl;
   onResponse;
+  requestHeaders;
   constructor(init) {
     this.baseUrl = init.baseUrl.replace(/\/+$/, "");
     this.authHeader = init.authHeader;
+    this.requestHeaders = init.requestHeaders;
     this.fetchImpl = init.fetchImpl ?? fetch;
     this.onResponse = init.onResponse;
   }
@@ -9392,7 +9394,9 @@ var Transport = class {
   }
   async headers(hasBody, opts) {
     const auth = typeof this.authHeader === "function" ? await this.authHeader() : this.authHeader;
+    const requestHeaders = typeof this.requestHeaders === "function" ? await this.requestHeaders() : this.requestHeaders;
     return {
+      ...requestHeaders,
       authorization: auth,
       accept: "application/json",
       "x-actionway-cli-version": getCliVersion(),
@@ -10324,7 +10328,7 @@ function emitUseWaitHint() {
     message: "The job is still pending. Run actionway wait with this job_ref now; never resubmit the job or create a shell polling loop."
   });
 }
-function registerPollCommand(program2, getTransport3) {
+function registerPollCommand(program2, getTransport2) {
   program2.command("poll").description(
     "Run one authenticated status snapshot for recovery or diagnostics. Use actionway wait for normal async completion."
   ).addHelpText(
@@ -10337,7 +10341,7 @@ function registerPollCommand(program2, getTransport3) {
   ).requiredOption("--job-ref <ref>", "the job_ref returned by a previous async submit").action(async (opts) => {
     try {
       const jobRef = validateJobRef(opts.jobRef);
-      const body = await pollJob(jobRef, getTransport3());
+      const body = await pollJob(jobRef, getTransport2());
       if (body.status === "pending") emitUseWaitHint();
       ok({ job_ref: jobRef, ...body });
     } catch (err) {
@@ -10409,7 +10413,7 @@ async function waitForJob(options) {
     await sleep(Math.min(intervalMs, timeoutMs - elapsedMs));
   }
 }
-function registerWaitCommand(program2, getTransport3) {
+function registerWaitCommand(program2, getTransport2) {
   program2.command("wait").description("Wait for an async job and print only its terminal result.").requiredOption("--job-ref <ref>", "the full job_ref returned by the submit command").option("--timeout-seconds <n>", "maximum wait time in seconds (default: 1800)", Number, 1800).addHelpText(
     "after",
     [
@@ -10427,7 +10431,7 @@ function registerWaitCommand(program2, getTransport3) {
           job_ref: jobRef
         });
       }
-      const transport = getTransport3();
+      const transport = getTransport2();
       const terminal = await waitForJob({
         jobRef,
         timeoutMs: opts.timeoutSeconds * 1e3,
@@ -11068,7 +11072,7 @@ function emitCall(response) {
   }
   ok(response);
 }
-function registerToolsCommands(program2, getTransport3) {
+function registerToolsCommands(program2, getTransport2) {
   const tools = program2.command("tools").description("Discover, inspect, and call Actionway capabilities through the canonical Tool protocol.");
   tools.command("search <query>").description("Search the current capability catalog by natural-language intent.").option("--limit <n>", "maximum candidates (1-5)", (value) => Number(value)).option("--domain <id>", "required capability domain; repeatable", values, []).option("--input-modality <name>", "required input modality; repeatable", values, []).option("--output-modality <name>", "required output modality; repeatable", values, []).option("--effect <name>", "required capability effect; repeatable", values, []).option("--max-price-usd <amount>", "maximum fixed Actionway USD price").action(async (query, options) => {
     const filters = {};
@@ -11078,14 +11082,14 @@ function registerToolsCommands(program2, getTransport3) {
     if (Array.isArray(options.effect) && options.effect.length) filters.effects = options.effect;
     if (typeof options.maxPriceUsd === "string") filters.maxPriceUsd = options.maxPriceUsd;
     try {
-      ok(await getTransport3().searchTools({ query, ...options.limit !== void 0 ? { limit: Number(options.limit) } : {}, ...filters }, { retries: 1 }));
+      ok(await getTransport2().searchTools({ query, ...options.limit !== void 0 ? { limit: Number(options.limit) } : {}, ...filters }, { retries: 1 }));
     } catch (error) {
       failTool(error);
     }
   });
   tools.command("inspect <tool_ref>").description("Read the current canonical Schema, variants, effects, guidance, and Actionway USD price.").action(async (toolRef) => {
     try {
-      ok(await getTransport3().inspectTool(toolRef, { retries: 1 }));
+      ok(await getTransport2().inspectTool(toolRef, { retries: 1 }));
     } catch (error) {
       failTool(error);
     }
@@ -11096,7 +11100,7 @@ function registerToolsCommands(program2, getTransport3) {
         if (toolRef || options.variant || options.inputJson || options.inputFile) {
           throw new CliError("E_SCHEMA", "--resume cannot be combined with tool_ref, --variant, or input arguments.");
         }
-        emitCall(await getTransport3().resumeToolCall(options.resume, { retries: 1 }));
+        emitCall(await getTransport2().resumeToolCall(options.resume, { retries: 1 }));
       }
       if (!toolRef) throw new CliError("E_SCHEMA", "tool_ref is required unless --resume is used.");
       const args = await resolveJsonObjectInlineOrFile(options.inputJson, options.inputFile, {
@@ -11104,7 +11108,7 @@ function registerToolsCommands(program2, getTransport3) {
         file: "--input-file"
       });
       if (!options.inputJson && !options.inputFile) throw new CliError("E_SCHEMA", "Use --input-json or --input-file for canonical arguments.");
-      const response = await getTransport3().callTool({
+      const response = await getTransport2().callTool({
         toolRef,
         ...typeof options.variant === "string" ? { variantId: options.variant } : {},
         arguments: args,
@@ -11216,7 +11220,7 @@ function failFromError(err) {
   }
   fail({ code: "E_BACKEND", message: err instanceof Error ? err.message : String(err) });
 }
-function registerAssetCommands(program2, getTransport3) {
+function registerAssetCommands(program2, getTransport2) {
   const asset = program2.command("asset").description("Register / fetch media assets (groups + assets) for downstream generate-* verbs.");
   asset.command("register").description(
     "Create an asset group and register one Image / Video / Audio asset under it; the server assigns the real group_id."
@@ -11258,7 +11262,7 @@ Examples:
           assetType,
           projectName: String(opts.projectName ?? "default")
         },
-        getTransport3()
+        getTransport2()
       );
       ok(res);
     } catch (err) {
@@ -11267,7 +11271,7 @@ Examples:
   });
   asset.command("get").description("Fetch a single asset by id.").requiredOption("--id <id>").action(async (opts) => {
     try {
-      const res = await getTransport3().post(
+      const res = await getTransport2().post(
         ASSET_GET_ENDPOINT,
         { id: String(opts.id) },
         { timeoutMs: ASSET_TIMEOUT_MS, retries: 1 }
@@ -11333,7 +11337,7 @@ async function resolveKnowledgeFilters(params) {
     file: "--filters-file"
   });
 }
-async function executeKnowledgeSearch(input, opts, getTransport3) {
+async function executeKnowledgeSearch(input, opts, getTransport2) {
   if (input.provider && input.domain !== "voice") {
     return {
       kind: "fail",
@@ -11351,7 +11355,7 @@ async function executeKnowledgeSearch(input, opts, getTransport3) {
     };
   }
   try {
-    const res = await getTransport3().post(KNOWLEDGE_SEARCH_ENDPOINT, body, {
+    const res = await getTransport2().post(KNOWLEDGE_SEARCH_ENDPOINT, body, {
       timeoutMs: KNOWLEDGE_TIMEOUT_MS,
       retries: 1
     });
@@ -11376,7 +11380,7 @@ async function executeKnowledgeSearch(input, opts, getTransport3) {
     return { kind: "fail", code: "E_BACKEND", exitCode: 1, message: err instanceof Error ? err.message : String(err) };
   }
 }
-function registerKnowledgeCommands(program2, getTransport3) {
+function registerKnowledgeCommands(program2, getTransport2) {
   const kb = program2.command("knowledge").description("Knowledge-base search across domain libraries (sfx, bgm, visual_style, voice, writing, meme).");
   const filtersFileFlag = {
     flag: "filters-file",
@@ -11449,22 +11453,19 @@ function registerKnowledgeCommands(program2, getTransport3) {
       ...typeof params.k === "number" ? { k: params.k } : {},
       ...Object.keys(filters).length > 0 ? { filters } : {}
     };
-    const outcome = await executeKnowledgeSearch(input, { dryRun: rawOpts.dryRun === true }, getTransport3);
+    const outcome = await executeKnowledgeSearch(input, { dryRun: rawOpts.dryRun === true }, getTransport2);
     emitOutcome(outcome);
   });
 }
 
 // ../cli-core/src/commands/stock-download.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, extname, isAbsolute as isAbsolute2 } from "node:path";
 var DEFAULT_DOWNLOAD_DIR = "/workspace/.stock-media";
 var FETCH_TIMEOUT_MS = 6e4;
 var MAX_DOWNLOAD_BYTES = 200 * 1024 * 1024;
 var ASSET_ID_RE = /^([a-z0-9_-]+):([a-zA-Z0-9_.-]+)$/;
-function stockDownloadAvailable() {
-  return false;
-}
 var MIME_TO_EXT = /* @__PURE__ */ new Map([
   ["image/jpeg", "jpg"],
   ["image/jpg", "jpg"],
@@ -11575,7 +11576,7 @@ async function fetchBytes(url) {
     clearTimeout(timer);
   }
 }
-function registerStockDownload(parent) {
+function registerStockDownload(parent, deps) {
   parent.command("download").description("Fetch a stock-media asset (CDN URL from search result) into /workspace and echo full metadata.").addHelpText(
     "after",
     [
@@ -11585,19 +11586,12 @@ function registerStockDownload(parent) {
       "so the local result retains its source and license metadata."
     ].join("\n")
   ).requiredOption("--asset-id <id>", "<provider>:<native_id> from a search result").requiredOption("--url <url>", "direct CDN URL from search result's download_url").option("--to <path>", `absolute path under /workspace (default: ${DEFAULT_DOWNLOAD_DIR}/<provider>-<id>.<ext>)`).option("--metadata-json <json>", "JSON-encoded metadata object from the search result; echoed back in output").action(async (opts) => {
-    if (!stockDownloadAvailable()) {
-      fail({
-        code: "E_CAPABILITY_NOT_AVAILABLE",
-        message: "stock download is deferred until Gateway command-level billing is available",
-        hint: "do not fetch the asset directly as a workaround; wait for the stage-two stock billing integration"
-      });
-    }
     const { provider, nativeId } = parseAssetId(String(opts.assetId));
     const url = String(opts.url);
     try {
       const parsedUrl = new URL(url);
-      if (parsedUrl.protocol !== "https:" && parsedUrl.protocol !== "http:") {
-        fail({ code: "E_SCHEMA", message: `--url must be http(s); got protocol ${parsedUrl.protocol}` });
+      if (parsedUrl.protocol !== "https:") {
+        fail({ code: "E_SCHEMA", message: `--url must use https; got protocol ${parsedUrl.protocol}` });
       }
     } catch (err) {
       if (err.name === "TypeError") {
@@ -11614,7 +11608,22 @@ function registerStockDownload(parent) {
       const defaultPath = `${DEFAULT_DOWNLOAD_DIR}/${provider}-${nativeId}.${ext}`;
       const destination = explicitDestination ?? validateDestination(void 0, defaultPath);
       await mkdir(dirname(destination), { recursive: true });
-      await writeFile(destination, buf);
+      const temporary = `${destination}.actionway-${jobRef}.tmp`;
+      await writeFile(temporary, buf, { flag: "wx" });
+      try {
+        const transport = deps.getTransport();
+        const body = { provider, native_id: nativeId, url, destination, kind: contentType?.startsWith("video/") ? "video" : "image" };
+        if (deps.projectToolCall) {
+          const response = await transport.callTool({ toolRef: "stock-media.download", arguments: body, idempotencyKey: jobRef, confirmation: { kind: "typed-command" } }, { jobRef, retries: 1 });
+          if (response.status !== "completed") throw new StockDownloadError("stock download authorization did not complete");
+        } else {
+          await transport.post("internal/stock/download", body, { jobRef, retries: 1 });
+        }
+        await rename(temporary, destination);
+      } catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+      }
       ok({
         job_ref: jobRef,
         asset_id: `${provider}:${nativeId}`,
@@ -11896,9 +11905,6 @@ var STOCK_DEFAULT_PROVIDER_ORDER = ["pexels", "pixabay", "openverse"];
 var STOCK_ORIENTATIONS = ["landscape", "portrait", "square"];
 var STOCK_TYPES = ["image", "video"];
 var STOCK_MODES = ["fallback", "fanout"];
-function isStockSearchAvailable() {
-  return false;
-}
 function parsePositiveInt(raw, flag, max) {
   const n = Number(raw);
   if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1 || n > max) {
@@ -11934,88 +11940,15 @@ function parseProviders(csv, type) {
   }
   return enabled;
 }
-function describeProviderFailure(provider, err) {
-  if (err instanceof TransportError) {
-    return {
-      provider,
-      ...err.status !== void 0 ? { status: err.status } : {},
-      reason: `${err.status ?? "transport"}: ${err.message}`
-    };
-  }
-  if (err instanceof Error) return { provider, reason: err.message };
-  return { provider, reason: String(err) };
-}
-function mergeResults(perProvider, limit) {
-  const merged = [];
-  const seen = /* @__PURE__ */ new Set();
-  const cursors = perProvider.map(() => 0);
-  let active = perProvider.filter((arr) => arr.length > 0).length;
-  while (merged.length < limit && active > 0) {
-    active = 0;
-    for (let i = 0; i < perProvider.length; i++) {
-      const arr = perProvider[i];
-      const cursor = cursors[i];
-      if (arr === void 0 || cursor === void 0 || cursor >= arr.length) continue;
-      const r = arr[cursor];
-      cursors[i] = cursor + 1;
-      if (r !== void 0 && !seen.has(r.asset_id)) {
-        seen.add(r.asset_id);
-        merged.push(r);
-        if (merged.length >= limit) break;
-      }
-      if (cursor + 1 < arr.length) active += 1;
-    }
-  }
-  return merged;
-}
-async function searchSequential(enabled, opts, limit, searchFn) {
-  const collected = [];
-  const seen = /* @__PURE__ */ new Set();
-  const queried = [];
-  const failed = [];
-  for (const name of enabled) {
-    queried.push(name);
-    try {
-      const results = await searchFn(name, opts);
-      for (const r of results) {
-        if (!seen.has(r.asset_id)) {
-          seen.add(r.asset_id);
-          collected.push(r);
-          if (collected.length >= limit) break;
-        }
-      }
-    } catch (err) {
-      failed.push(describeProviderFailure(name, err));
-    }
-    if (collected.length >= limit) break;
-  }
-  return { results: collected.slice(0, limit), queried, failed };
-}
-async function searchFanout(enabled, opts, limit, searchFn) {
-  const settled = await Promise.allSettled(enabled.map((n) => searchFn(n, opts)));
-  const perProviderResults = [];
-  const failed = [];
-  for (let i = 0; i < enabled.length; i++) {
-    const r = settled[i];
-    const name = enabled[i];
-    if (r !== void 0 && r.status === "fulfilled") {
-      perProviderResults.push(r.value);
-    } else {
-      perProviderResults.push([]);
-      if (r !== void 0 && name !== void 0) failed.push(describeProviderFailure(name, r.reason));
-    }
-  }
-  return { results: mergeResults(perProviderResults, limit), queried: [...enabled], failed };
-}
-function registerStockSearch(parent, getTransport3) {
+function registerStockSearch(parent, deps) {
   parent.command("search").description(
     "Sequential-fallback search across providers (Pexels -> Pixabay -> Openverse). Use --mode=fanout for parallel."
   ).addHelpText(
     "after",
     [
       "",
-      "Availability:",
-      "  Stage one is fail-closed until Gateway command-level billing orchestration is available.",
+      "Execution:",
+      "  Gateway orchestrates all selected providers and bills the search once.",
       "",
       "Modes:",
       "  fallback (default) - calls Pexels -> Pixabay -> Openverse in order and stops once limit results are collected.",
@@ -12044,13 +11977,6 @@ function registerStockSearch(parent, getTransport3) {
     `search strategy: ${STOCK_MODES.join(" | ")} (default fallback saves API budget)`,
     "fallback"
   ).action(async (opts) => {
-    if (!isStockSearchAvailable()) {
-      fail({
-        code: "E_CAPABILITY_NOT_AVAILABLE",
-        message: "stock search is not available in migration stage one",
-        hint: "Gateway command-level stock billing/orchestration is required before this command can be enabled."
-      });
-    }
     const type = String(opts.type);
     if (!STOCK_TYPES.includes(type)) {
       fail({ code: "E_SCHEMA", message: `--type must be image|video; got ${String(opts.type)}` });
@@ -12067,42 +11993,35 @@ function registerStockSearch(parent, getTransport3) {
     }
     const limit = typeof opts.limit === "number" ? opts.limit : 10;
     const enabled = parseProviders(opts.providers !== void 0 ? String(opts.providers) : void 0, type);
-    const perProviderLimit = mode === "fanout" ? Math.max(1, Math.ceil(limit * 1.5 / enabled.length)) : limit;
     const searchOpts = {
       query: String(opts.query),
       type,
       ...opts.orientation !== void 0 ? { orientation: String(opts.orientation) } : {},
       ...typeof opts.minWidth === "number" ? { minWidth: opts.minWidth } : {},
       ...typeof opts.durationMin === "number" ? { durationMin: opts.durationMin } : {},
-      ...typeof opts.durationMax === "number" ? { durationMax: opts.durationMax } : {},
-      perProviderLimit
+      ...typeof opts.durationMax === "number" ? { durationMax: opts.durationMax } : {}
     };
     const jobRef = randomUUID4();
     try {
-      const transport = getTransport3();
-      const searchFn = (name, o) => {
-        const provider = ALL_PROVIDERS[name];
-        if (!provider) throw new Error(`unknown stock provider: ${name}`);
-        return provider.search(o, transport);
-      };
-      const { results, queried, failed } = mode === "fanout" ? await searchFanout(enabled, searchOpts, limit, searchFn) : await searchSequential(enabled, searchOpts, limit, searchFn);
-      if (results.length === 0 && failed.length > 0 && failed.length === queried.length) {
-        fail({
-          code: "E_BACKEND",
-          message: `all stock-media providers failed for "${String(opts.query)}"`,
-          hint: "check gateway provider routes / quota; see providers_failed for per-provider reason.",
-          extra: { job_ref: jobRef, mode, providers_queried: queried, providers_failed: failed }
-        });
-      }
-      ok({
-        job_ref: jobRef,
+      const transport = deps.getTransport();
+      const body = {
         query: searchOpts.query,
         type,
         mode,
-        results,
-        providers_queried: queried,
-        providers_failed: failed
-      });
+        limit,
+        providers: enabled,
+        ...searchOpts.orientation ? { orientation: searchOpts.orientation } : {},
+        ...searchOpts.minWidth !== void 0 ? { min_width: searchOpts.minWidth } : {},
+        ...searchOpts.durationMin !== void 0 ? { duration_min: searchOpts.durationMin } : {},
+        ...searchOpts.durationMax !== void 0 ? { duration_max: searchOpts.durationMax } : {}
+      };
+      if (deps.projectToolCall) {
+        const response2 = await transport.callTool({ toolRef: "stock-media.search", arguments: body, idempotencyKey: jobRef, confirmation: { kind: "typed-command" } }, { jobRef, retries: 1 });
+        if (response2.status !== "completed") return ok({ ...response2, job_ref: jobRef });
+        return ok({ job_ref: jobRef, ...response2.result });
+      }
+      const response = await transport.post("internal/stock/search", body, { jobRef, retries: 1 });
+      ok({ job_ref: jobRef, ...response });
     } catch (err) {
       if (err instanceof TransportError) {
         fail({ code: err.code, message: err.message, extra: { ...err.extra ?? {}, job_ref: jobRef } });
@@ -12117,10 +12036,11 @@ function registerStockSearch(parent, getTransport3) {
 }
 
 // ../cli-core/src/commands/stock.ts
-function registerStockCommands(program2, getTransport3) {
+function registerStockCommands(program2, depsOrTransport) {
+  const deps = typeof depsOrTransport === "function" ? { getTransport: depsOrTransport } : depsOrTransport;
   const stock = program2.command("stock").description("Search and download public stock media (Pexels / Pixabay / Openverse) for b-roll.");
-  registerStockSearch(stock, getTransport3);
-  registerStockDownload(stock);
+  registerStockSearch(stock, deps);
+  registerStockDownload(stock, deps);
 }
 
 // ../../node_modules/.pnpm/commander@12.1.0/node_modules/commander/esm.mjs
@@ -13092,19 +13012,19 @@ function accountEndpoint(path, options) {
   const query = parameters.toString();
   return `v1/account/${path}${query ? `?${query}` : ""}`;
 }
-async function read(endpoint, getTransport3) {
+async function read(endpoint, getTransport2) {
   try {
-    ok(await getTransport3().getBusiness(endpoint, { retries: 1 }));
+    ok(await getTransport2().getBusiness(endpoint, { retries: 1 }));
   } catch (error) {
     failAccount(error);
   }
 }
-function registerAccountCommands(program2, getTransport3) {
+function registerAccountCommands(program2, getTransport2) {
   const account = program2.command("account").description("Access your Actionway invitation, USD wallet, service usage, and wallet transactions.");
-  account.command("invitation").description("Get or create your permanent invitation code, link, and localized share message.").option("--locale <locale>", "Share-message locale: zh-cn, zh-tw, en, or ja.", "en").action((options) => read(invitationEndpoint(options.locale), getTransport3));
-  account.command("usage").description("Query held, charged, released, and free capability calls.").option("--limit <count>", "Maximum records in this page (1-100).").option("--cursor <cursor>", "Opaque nextCursor returned by the previous page.").option("--from <date>", "Inclusive ISO date or timestamp (UTC for date-only values).").option("--to <date>", "Exclusive ISO date or timestamp (UTC for date-only values).").option("--status <status>", "held, settled, or expired.").option("--service <service-id>", "Exact public serviceId.").option("--pricing-kind <kind>", "priced or free.").action((options) => read(accountEndpoint("usage", options), getTransport3));
-  account.command("wallet").description("Show the current available and held Actionway USD wallet balance.").action(() => read("v1/account/wallet", getTransport3));
-  account.command("transactions").description("Query wallet top-ups, charges, promotions, refunds, and other fund movements.").option("--limit <count>", "Maximum records in this page (1-50).").option("--cursor <cursor>", "Opaque nextCursor returned by the previous page.").option("--from <date>", "Inclusive ISO date or timestamp (UTC for date-only values).").option("--to <date>", "Exclusive ISO date or timestamp (UTC for date-only values).").option("--status <status>", "pending, succeeded, or failed.").option("--kind <kind>", "top_up, charge, refund, dispute, or promotion kind.").action((options) => read(accountEndpoint("transactions", options), getTransport3));
+  account.command("invitation").description("Get or create your permanent invitation code, link, and localized share message.").option("--locale <locale>", "Share-message locale: zh-cn, zh-tw, en, or ja.", "en").action((options) => read(invitationEndpoint(options.locale), getTransport2));
+  account.command("usage").description("Query held, charged, released, and free capability calls.").option("--limit <count>", "Maximum records in this page (1-100).").option("--cursor <cursor>", "Opaque nextCursor returned by the previous page.").option("--from <date>", "Inclusive ISO date or timestamp (UTC for date-only values).").option("--to <date>", "Exclusive ISO date or timestamp (UTC for date-only values).").option("--status <status>", "held, settled, or expired.").option("--service <service-id>", "Exact public serviceId.").option("--pricing-kind <kind>", "priced or free.").action((options) => read(accountEndpoint("usage", options), getTransport2));
+  account.command("wallet").description("Show the current available and held Actionway USD wallet balance.").action(() => read("v1/account/wallet", getTransport2));
+  account.command("transactions").description("Query wallet top-ups, charges, promotions, refunds, and other fund movements.").option("--limit <count>", "Maximum records in this page (1-50).").option("--cursor <cursor>", "Opaque nextCursor returned by the previous page.").option("--from <date>", "Inclusive ISO date or timestamp (UTC for date-only values).").option("--to <date>", "Exclusive ISO date or timestamp (UTC for date-only values).").option("--status <status>", "pending, succeeded, or failed.").option("--kind <kind>", "top_up, charge, refund, dispute, or promotion kind.").action((options) => read(accountEndpoint("transactions", options), getTransport2));
 }
 
 // src/commands/doctor.ts
@@ -13435,6 +13355,35 @@ function materializeSkill(options = {}) {
   };
 }
 
+// src/lib/client-context.ts
+var ACTIONWAY_AGENT_HOST_HEADER = "x-actionway-agent-host";
+var ACTIONWAY_RUNTIME_OS_HEADER = "x-actionway-runtime-os";
+var ACTIONWAY_AGENT_HOSTS = ["codex", "claude_code", "workbuddy"];
+function isActionwayAgentHost(value) {
+  return typeof value === "string" && ACTIONWAY_AGENT_HOSTS.includes(value);
+}
+function detectRuntimeOs(platform = process.platform, env = process.env) {
+  if (platform === "win32") return "windows";
+  if (platform === "darwin") return "macos";
+  if (platform === "linux") {
+    if ((env.WSL_DISTRO_NAME ?? "").trim() || (env.WSL_INTEROP ?? "").trim()) return "wsl";
+    return "linux";
+  }
+  return "other";
+}
+function localClientContext(agentHost, platform = process.platform, env = process.env) {
+  return {
+    ...isActionwayAgentHost(agentHost) ? { agentHost } : {},
+    runtimeOs: detectRuntimeOs(platform, env)
+  };
+}
+function localClientContextHeaders(context) {
+  return {
+    ...context.agentHost ? { [ACTIONWAY_AGENT_HOST_HEADER]: context.agentHost } : {},
+    [ACTIONWAY_RUNTIME_OS_HEADER]: context.runtimeOs
+  };
+}
+
 // src/lib/install-session.ts
 var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 var ANALYTICS_TIMEOUT_MS = 3e3;
@@ -13474,7 +13423,12 @@ async function captureInstallStarted(input) {
       `${stripSlash2(input.gateway)}/api/analytics/install-started`,
       {
         method: "POST",
-        headers: { Accept: "application/json", "Content-Type": "application/json" },
+        headers: {
+          Accept: "application/json",
+          "Content-Type": "application/json",
+          "x-actionway-cli-version": getCliVersion(),
+          ...input.clientContext ? localClientContextHeaders(input.clientContext) : {}
+        },
         body: JSON.stringify({
           installSessionId: input.installSessionId,
           installSource: input.installSource
@@ -13498,7 +13452,12 @@ async function requestCliInstallSession(input) {
       url.toString(),
       {
         method: "GET",
-        headers: { Accept: "application/json", Authorization: `Bearer ${input.accessToken}` }
+        headers: {
+          Accept: "application/json",
+          Authorization: `Bearer ${input.accessToken}`,
+          "x-actionway-cli-version": getCliVersion(),
+          ...input.clientContext ? localClientContextHeaders(input.clientContext) : {}
+        }
       },
       SESSION_TIMEOUT_MS2,
       input.fetchImpl ?? fetch
@@ -13538,6 +13497,7 @@ async function connectInstallSession(input) {
     accessToken: credentials.access_token,
     installSessionId: input.installSessionId,
     installSource: input.installSource,
+    ...input.clientContext ? { clientContext: input.clientContext } : {},
     fetchImpl
   });
 }
@@ -13552,12 +13512,14 @@ function failFromError3(err) {
   }
   fail({ code: "E_BACKEND", message: err instanceof Error ? err.message : String(err) });
 }
-function registerInitCommand(program2) {
+function registerInitCommand(program2, getClientContext = () => ({ runtimeOs: "other" })) {
   const distribution = cliDistribution();
   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 (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 clientContext = getClientContext();
+      const invocation = clientContext.agentHost ? `${distribution.commandName} --agent-host=${clientContext.agentHost}` : distribution.commandName;
       const skill = materializeSkill();
       if (opts.skillOnly) {
         ok({ skill });
@@ -13568,7 +13530,8 @@ function registerInitCommand(program2) {
       await captureInstallStarted({
         gateway: initGateway,
         installSessionId,
-        installSource
+        installSource,
+        clientContext
       });
       let loginStarted = false;
       if (!whoamiSnapshot()) {
@@ -13585,7 +13548,8 @@ function registerInitCommand(program2) {
       const account = await connectInstallSession({
         ...opts.gateway ? { explicitGateway: opts.gateway } : {},
         installSessionId,
-        installSource
+        installSource,
+        clientContext
       });
       const snapshot = whoamiSnapshot();
       ok({
@@ -13595,7 +13559,7 @@ function registerInitCommand(program2) {
         skill,
         workspace_id: account.workspaceId,
         ...snapshot?.user ? { user: snapshot.user } : {},
-        hint: `Actionway is ready. Install the skill from \`skill.source\` into your agent's skill directory, then run \`${distribution.commandName} --help\` to discover supported capabilities.`
+        hint: `Actionway is ready. Install the skill from \`skill.source\` into your agent's skill directory, then run \`${invocation} --help\` to discover supported capabilities.`
       });
     } catch (error) {
       failFromError3(error);
@@ -13744,7 +13708,7 @@ function authFailure(err) {
     extra: { ...err.extra ?? {}, ...err.hint ? { hint: err.hint } : {} }
   });
 }
-function getTransport(env = process.env, fetchImpl) {
+function getTransport(env = process.env, fetchImpl, clientContext) {
   return new Transport({
     baseUrl: resolveTransportBaseUrl(env),
     authHeader: async () => {
@@ -13766,6 +13730,7 @@ function getTransport(env = process.env, fetchImpl) {
       }
       return `Bearer ${creds.access_token}`;
     },
+    ...clientContext ? { requestHeaders: localClientContextHeaders(clientContext) } : {},
     ...fetchImpl ? { fetchImpl } : {},
     onResponse: (res) => {
       const latest = res.headers.get("x-actionway-cli-latest");
@@ -13904,10 +13869,6 @@ function projectTypedToolCall(spec, commandParams, prepared) {
 }
 
 // src/index.ts
-function getTransport2() {
-  return getTransport();
-}
-var actionDeps = { getTransport: getTransport2, projectToolCall: projectTypedToolCall };
 function buildProgram() {
   const distribution = cliDistribution();
   const version = readOwnVersion();
@@ -13915,7 +13876,13 @@ function buildProgram() {
   const program2 = new Command(distribution.commandName);
   program2.version(version);
   program2.description("Actionway CLI: run Actionway media and research capabilities from your local agent.");
-  registerInitCommand(program2);
+  program2.addOption(
+    new Option("--agent-host <host>", "declare the local Agent invoking this command").choices([...ACTIONWAY_AGENT_HOSTS])
+  );
+  const getClientContext = () => localClientContext(program2.opts().agentHost);
+  const getTransport2 = () => getTransport(process.env, void 0, getClientContext());
+  const actionDeps = { getTransport: getTransport2, projectToolCall: projectTypedToolCall };
+  registerInitCommand(program2, getClientContext);
   registerDoctorCommand(program2);
   registerUpdateCommand(program2);
   registerDevelopmentStatusCommand(program2);
@@ -13942,7 +13909,7 @@ function buildProgram() {
   registerPollCommand(program2, getTransport2);
   registerKnowledgeCommands(program2, getTransport2);
   registerAssetCommands(program2, getTransport2);
-  registerStockCommands(program2, getTransport2);
+  registerStockCommands(program2, actionDeps);
   return program2;
 }
 var invokedAsBin = isDirectExecution(import.meta.url);