@actionway/cli 0.17.0 → 0.17.1

package/README.md

@@ -0,0 +1,51 @@
+# @actionway/cli — 本地端壳（bin: `actionway`）
+
+actionway CLI 的本地端壳（迁移文档 `docs/DL_TO_ACTIONWAY_CLI_MIGRATION.md` §3.2 / §3.4）：
+终端用户在自己机器上的 Coding Agent（Codex / Claude Code）通过它调用 Actionway 能力。
+
+- **auth 唯一途径：Clerk OAuth（PKCE）**。issuer / client_id 运行时从
+  `{public origin}/api/auth/cli-config` 发现；浏览器授权走随机 `127.0.0.1` 回调端口；
+  凭据存 `~/.actionway/credentials.json`（0600 owner-only 文件，可用
+  `ACTIONWAY_CONFIG_DIR` 重定向）。CLI 从不打印或存储 OAuth client secret。
+- **命令面 = 明码写出的注册表**（无 profile flag、无运行期分叉）：
+  - `tools search / inspect / call` 是长尾 capability 的规范发现与执行面；
+  - 高频 typed command 继续提供参数与文件 UX，但投影到同一个 Tool Call；
+  - `account usage / wallet / transactions` 只读 Actionway Business 数据；
+  - 本壳另有 `init` / `update` / `login` / `logout` / `whoami`，cli-core
+    继续提供 wait/poll 与已冻结的共享 typed commands。
+- **计费零逻辑**：报价、扣费、错误面裁剪全在 gateway；本壳只透传。旧
+  stock download 直连 CDN、Gateway 无法观察结局，因此在阶段二的
+  command-level 计费编排完成前明确 fail-closed，不把迁移缺口当免费能力。
+- **版本三链路**（与 pi-mono dl 的 actionway profile 同构）：
+  1. 输出注入 —— 每个成功 JSON 输出带 `cli_version` + `skill_source`，
+     本地缓存显示有新版时追加 `notes` 更新提示（update 命令自身输出带
+     `update_available` 时跳过，防更新循环）；
+  2. HTTP header —— 请求捎带 `x-actionway-cli-version`，响应的
+     `x-actionway-cli-latest` / `x-actionway-cli-min` 喂本地缓存；
+  3. registry —— `actionway update --check` 查 npm（24h 缓存），
+     `actionway update` 全局安装新版并 re-exec 刷新物化 skill。
+- **skill 物化**：`actionway init` 把 `assets/skill/actionway` 拷到
+  `~/.actionway/skill/actionway` 并把 CLI 版本盖进 SKILL.md frontmatter
+  `metadata.version`；
+  Agent 从该路径自取安装——CLI 从不写入任何 Agent 自己的配置目录。包内
+  Skill 不复制 capability catalog；未知或长尾需求走 Search → Inspect → Call，
+  `confirmation_required` 必须由用户确认后恢复同一个 `call_ref`。
+
+```bash
+pnpm cli init            # 浏览器授权 + 物化 skill（首次安装入口）
+pnpm cli whoami          # 用户友好登录摘要 + 本地凭据快照（不出网）
+pnpm cli logout          # 删除本机凭据；重复执行也是成功的幂等操作
+pnpm cli update --check  # 查新版（24h 缓存）
+pnpm cli -- tools search "generate a product image"
+pnpm cli -- tools inspect media.image.generate
+pnpm cli -- account usage
+pnpm cli -- generate-video --print-schema
+```
+
+发布 bundle 会把 cli-core 打进带 shebang 的 `dist/index.js`；`pnpm build`
+生成该产物，`pnpm pack` 的 tarball 可由 Node 直接执行。手动发布由统一的
+`.github/workflows/release.yml` 负责：勾选 `actionway_cli`（可单独选择，也可与 Worker 组合）并选择版本 bump 后，
+workflow 以 npm 已发布的最高版本为基线生成下一版本，构建当前仓库的
+tarball，验证真实 npm install 后的 `.bin/actionway`、`--help`、`--version`
+和 `logout`，再发布到 `latest`。`@actionway/sandbox-cli` 继续独立于本地 CLI；
+其 iLands rollout 尚未接入 Production Release，保留单独的手动发布 workflow。

package/assets/skill/actionway/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: actionway
+description: Use the local Actionway CLI to discover, inspect, price, and call Actionway capabilities; continue asynchronous jobs or confirmed calls; read Actionway account usage, wallet, and transactions; authenticate; or update the CLI. Trigger when a local Agent can complete a task through `actionway`, when a `job_ref` or `call_ref` must be continued, or when the user asks about Actionway tools or account data.
+metadata:
+  version: "0.0.0-dev"
+---
+
+# Actionway
+
+Use the installed `actionway` CLI and its server-backed Capability Registry as the source of truth. Do not memorize a complete command catalog, Schema, provider list, or price table in this Skill.
+
+## Prepare
+
+1. Run Actionway commands with network access and permission to read `~/.actionway`. If a sandboxed command reports `E_NOT_AUTHENTICATED` for an already logged-in user, rerun the same command with host permission before starting login again.
+2. If the user supplied a pending `job_ref`, skip updating and immediately run `actionway wait --job-ref=<uuid>`.
+3. Otherwise, once per Agent session, run `actionway update --check`. Continue with the installed CLI if the check is unavailable. If an update is available, run `actionway update` before starting a new call, then refresh this Skill from the returned `skill_source` for the next Agent session.
+4. Compare this Skill's `metadata.version` with successful command output `cli_version`. If they differ, replace the installed Actionway Skill with the directory at `skill_source`, tell the user once that the refreshed instructions apply from the next session, and continue the current task. Follow any output `notes`, especially minimum-version instructions.
+5. Run `actionway whoami`. On a genuine `E_NOT_AUTHENTICATED`, run `actionway init`, ask the user only to approve access in the browser, and install the staged Skill from `skill.source`. Never request, print, copy, or expose credentials.
+
+## Choose the command path
+
+- For an unknown, ambiguous, or long-tail capability, run `actionway tools search "<natural-language intent>"`. Use its filters only when the task supplies real constraints. Do not dump or preload the whole catalog.
+- If Search returns `clarification_required`, ask its bounded question. If it returns candidates, choose only a supported `tool_ref` and run `actionway tools inspect <tool_ref>` before the generic call. Inspect is the authority for the current input Schema, variants, effects, guidance, and Actionway USD price.
+- `actionway search` is the Web Search business capability. Capability discovery is always `actionway tools search`.
+- Use a high-frequency typed command only when `actionway --help` exposes an exact fit. Read `actionway <command> --help` and, when available, `--print-schema`; typed commands are parameter/file conveniences over the same Tool Call, confirmation, billing, and Job path.
+- For account questions, use only the requested read command: `actionway account usage`, `actionway account wallet`, or `actionway account transactions`.
+
+## Inspect and call
+
+1. Build arguments that match the inspected Schema exactly. Use the inspected canonical variant ID, never a guessed provider/model alias. For small objects use `--input-json`; for large or generated objects use `--input-file` or stdin.
+2. Run one command at a time. A generic call is `actionway tools call <tool_ref> [--variant <id>] --input-json '<object>'`. Reuse one stable `--idempotency-key` when retrying the same request.
+3. Parse stdout as structured JSON. Preserve a failure's `code`, `message`, `hint`, and safe details. Do not call internal binaries, endpoints, or unsupported flags.
+4. Treat server-projected pricing as authoritative. Show the current USD quote and effects when the user asks about price or when confirmation is required. Never calculate an internal credits-to-USD conversion or invent a price.
+5. Handle call status exactly:
+   - `confirmation_required`: do not execute or resume automatically. Present the server plan's capability/variant, effects, Usage label, and USD quote, then ask the user. On rejection, stop. On changed inputs, make a new call. On approval, run only `actionway tools call --resume <call_ref>`.
+   - `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.
+
+## Handle asynchronous jobs
+
+1. Preserve the full UUID `job_ref` returned by submit.
+2. If a typed command returns pending, or a Tool Call returns `accepted`, immediately run `actionway wait --job-ref=<uuid>` in the same Agent turn.
+3. Let `actionway wait` poll internally. Do not create a background process or a shell `sleep`, `for`, or `while` polling loop.
+4. If stderr emits a `long_wait` event after ten minutes, tell the user once that processing continues and they may come back later. Continue waiting unless the user asks to stop.
+5. If the wait is interrupted or times out, run `actionway wait` again with the same `job_ref`. Use `actionway poll` only for a one-shot diagnostic snapshot.
+6. Consume the terminal payload returned by `actionway wait` as the result. Do not wait for a server callback or for a prior Agent session to resume.
+
+Do not resubmit the original capability call or typed command merely because a job is still pending. Keep using its original `job_ref`.
+
+## Deliver artifacts
+
+- Download terminal `assets` into an `outputs/` directory under the current task using stable, descriptive filenames.
+- Present the downloaded local files to the user. Do not return only remote URLs when a downloadable artifact is available.
+- If downloading fails, preserve the terminal payload and `job_ref`; never resubmit generation to recover a file transfer.

package/assets/skill/actionway/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Actionway"
+  short_description: "Discover and run Actionway capabilities"
+  default_prompt: "Use $actionway to discover the right capability, inspect its current schema and price, and complete this task with the local Actionway CLI."