@standardagents/skill 0.45.4 → 0.45.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/skill",
-  "version": "0.45.4",
+  "version": "0.45.6",
   "private": false,
   "publishConfig": {
     "access": "public",

package/skills/agentbuilder/SKILL.md

@@ -28,7 +28,7 @@ For deeper reference material that this skill links to, see:
 - Specification: https://standardagentspec.org/llms.txt
 - Builder docs: https://docs.standardagents.ai/llms.txt
 
-> If the `agents/*/AGENTS.md` files don't exist in your project yet, run `pnpm exec agents scaffold` to create them.
+> If the `agents/*/AGENTS.md` files don't exist in your project yet, run `pnpm exec agents scaffold` to create them. To replace existing guides with the current versions, run `pnpm exec agents scaffold --force`. That command also runs the normal scaffold stages (`vite.config`, `package.json`, registry settings, `tsconfig.json`) and resets the `builder()` entry in `vite.config` to a call with no options, so copy any `builder()` options first. It prints each replacement before it writes, and it keeps application files.
 
 ## The specification comes first
 
@@ -73,7 +73,7 @@ Every agent has exactly two explicit sides, and each side is backed by exactly o
 Name its `sessionStop` tool. Name its `sessionFail` tool. Set a finite `maxSessionTurns` (the spec makes the cap optional; this skill makes it required practice for prompt × prompt). Give side B a real, non-redundant job. If you cannot say in one sentence what tool call ends the session, the agent is not designed yet. → [Session boundary discipline](#session-boundary-discipline)
 
 **4. Pick models from `current-models` only.**
-Never invent model strings from memory. Run `pnpm exec agents current-models`, choose by category, then run `pnpm exec agents available-models --provider=<name>` to confirm the exact string. → [Model selection](#model-selection)
+Never invent model strings from memory. Run `pnpm exec agents current-models`, choose by category, then run `pnpm exec agents available-models --provider=<name>` to confirm the exact string. Both work in a project that holds only the Standard Agents account key. → [Model selection](#model-selection)
 
 **5. Research every third-party API before writing the tool.**
 Fetch the official current docs. Confirm auth, base URL, endpoint paths, payload shapes, rate limits, error codes. Do not write a tool from memory of how an API "usually" works. APIs change. → [API research checklist](#api-research-checklist)
@@ -584,7 +584,7 @@ conversion contract.
 
 1. Run `pnpm exec agents current-models` to see the curated category list (e.g. `extra_reasoning`, `fast_tool_calls`, `writing`, `image_generation`, `tiny`).
 2. Choose the category that fits the role (table below).
-3. Run `pnpm exec agents available-models --provider=<name>` to confirm the exact provider model string.
+3. Run `pnpm exec agents available-models --provider=<name>` to confirm the exact provider model string. The command uses the provider's own key when the project has one. Otherwise it uses the project's Standard Agents account key (`STANDARD_AGENTS_API_KEY` in `.dev.vars`), so a project created by `agents init` needs no provider key. `<name>` is an installed provider package (`openai`, `anthropic`, ...) or a provider defined in `agents/providers/`, which always uses the key and base URL its own definition declares. If the command exits 1, read its message: it names the missing key or the failed request. Do not guess an ID in its place.
 4. Define the model in `agents/models/<name>.ts` using `defineModel`.
 5. Take `capabilities` from the provider (`POST /api/models/capabilities` with `{provider, modelId}`, or the admin model picker) — **never guess them, and never flatter the model.** The runtime's vision filter trusts `supportsImages`: declare it `true` on a text-only model and generated-image attachments ship to the provider as raw base64 that gets tokenized as *text* — a ~1MB PNG becomes ~1.2M input tokens and every turn after the first image hard-fails with "input too long". Declared `false`, images become a small placeholder in requests while stored history keeps the real files.
 
@@ -1137,6 +1137,43 @@ Undeclared thread-only env keys are treated as write-only secrets when scanned f
 
 ---
 
+## Platform terms
+
+If `git push` prints lines that start with `remote: Standard Agents:`, the platform stored the push but started no build. Tell the user what the lines say. For the terms notice, the user runs `npx @standardagents/cli@latest terms accept`. An acceptance starts no build: the command lists the deploy that waits and starts it (with `--agree`, with no second question). To start it later, run `npx @standardagents/cli@latest builds retry` on the pushed branch.
+
+The platform can ask an account member to accept updated terms.
+
+```bash
+npx @standardagents/cli@latest terms            # documents, versions, URLs, accepted or not
+npx @standardagents/cli@latest terms accept     # asks the person in a terminal
+```
+
+**Rule: you never accept terms for the user on your own decision.** Acceptance
+is a legal agreement by the signed-in person. Without a terminal,
+`terms accept` exits with code 2 and records nothing. It prints both document
+links, the acknowledgement sentence, and the command that accepts the versions
+it showed:
+
+```bash
+npx @standardagents/cli@latest terms accept --agree --terms-version <version> --privacy-version <version>
+```
+
+Show the user those two links and that sentence exactly as printed. Run the
+printed command, with its versions unchanged, only after the user says yes in
+this conversation. `--agree` needs both version options. If a document changed
+after the user reviewed it, the command exits with code 2 again, records
+nothing, and prints the current documents with a new command. Show the user the
+new links and ask again. Never copy the new versions into the command without a
+new yes.
+
+Add `--json` for stable output; a code 2 result holds the command in
+`accept_command`. Exit codes: 0 success, 1 failure, 2
+confirmation needed, 3 not signed in (the user runs
+`npx @standardagents/cli@latest login`, the one sign-in command, in any directory).
+After acceptance the command lists each deploy that started.
+
+---
+
 ## Production diagnostics & stuck threads
 
 A thread that shows "working" forever has a precise signature: a request log
@@ -1153,9 +1190,10 @@ destination.
 
 ### `agents diag` (CLI)
 
-All subcommands accept `--endpoint <instance-url>` and `--token <api-key>`
-(defaults: `$STANDARD_AGENTS_INSTANCE_URL` / `$STANDARD_AGENTS_INSTANCE_TOKEN`,
-falling back to `http://localhost:5173` for local dev). The token must belong
+All subcommands read `$STANDARD_AGENTS_INSTANCE_URL` and
+`$STANDARD_AGENTS_INSTANCE_TOKEN` (falling back to `http://localhost:5173` for
+local dev). Set the token in the environment: `--token <api-key>` is accepted,
+but an argument is visible to other users in the process list. The token must belong
 to a user with the `logs` permission (admin keys qualify; customer `api`-role
 keys do not).
 
@@ -1168,6 +1206,15 @@ agents diag tail 050d96f1             # live-tail the log stream — are bytes f
 agents diag revive 050d96f1           # run a watchdog check NOW: finalize + resume
 ```
 
+Every subcommand accepts `--json`: stdout then holds one JSON document
+(`diag tail --json` prints one frame per line), and errors go to stderr. A
+failure exits 1 and prints `{ "error": { "code", "message", "status",
+"request_id" } }`. `diag threads` reports how many threads it could not read
+(`unreadable` in JSON); `diag threads --stuck` exits 1 when it could not read
+every thread. Exit 0 means the scan was complete, not that the instance is
+healthy: read the returned threads to see whether any are stuck. `diag tail`
+exits 1 when the stream closes abnormally.
+
 ### Interpretation guide
 
 - `diag instance` → `builder version` answers "is the fix deployed?" without
@@ -1196,6 +1243,42 @@ All three are gated by the `logs` permission on hosted deployments.
 
 ---
 
+## After a push
+
+A project on Standard Agents hosting deploys from git: the platform builds each pushed commit. A push that git accepts is not a deploy, and the build can fail after the push. Check every push with the CLI. The commands use the project key in `.dev.vars`, or the account sign-in from `npx @standardagents/cli@latest login`, which is saved once for the machine; `agents rollback` and `agents redeploy` need that sign-in. Each command accepts `--json` and never prompts.
+
+```bash
+agents deploy                              # push, then follow the build; exits 0 only when the commit was deployed
+agents builds                              # recent builds: id, status, environment, commit, branch
+agents builds status                       # the build of the checked-out commit
+agents builds status --commit <sha>        # the build of another commit
+agents builds status <build> --wait        # wait for a running build to end
+agents builds logs <build>                 # the build log
+agents builds logs <build> --follow        # stream the log of a running build
+agents builds retry <build> --wait         # start a failed build again and wait for it
+agents rollback --yes --wait               # make the earlier production build live again
+agents redeploy                            # deploy the live build again after an environment change
+```
+
+Without a global install, use `npx @standardagents/cli@latest <command>`.
+
+1. After `git push`, run `agents builds status --wait`. It waits while the build is `queued`, `building`, or `deploying`.
+2. When the status is `failed`, read `agents builds logs`, fix the cause in a new commit, and push again. Use `agents builds retry` only when the failure was not caused by the code.
+3. When production is broken after a build went live, run `agents rollback --yes --wait`, then fix the code in a new commit. Rollback applies to production only.
+
+| Exit code | Meaning | Next step |
+| --- | --- | --- |
+| 0 | Done. For a wait: the commit was deployed. | None. |
+| 1 | The build failed, or the platform refused the request. | Read `agents builds logs`. |
+| 2 | The command line, the checkout, or the named build is not usable. | Read the message. |
+| 3 | Not signed in, or the command needs an account sign-in. | Ask the user to run `npx @standardagents/cli@latest login`. |
+| 4 | The platform needs the terms accepted before it builds. | Ask the user to run `npx @standardagents/cli@latest terms accept`. It starts the refused build after the acceptance; `npx @standardagents/cli@latest builds retry` starts it later. |
+| 5 | The time limit passed while the build was still in progress. | Run `agents builds status --wait` again, or raise `--timeout <seconds>`. |
+
+Only a person can sign in or accept the terms. Do not try to do either for the user.
+
+---
+
 ## Implementation checking
 
 When you edit `agents/`, `prompts/`, `handlers/`, `models/`, `tools/`, `hooks/`, or `worker/`, validate before claiming the change is done.
@@ -1203,16 +1286,15 @@ When you edit `agents/`, `prompts/`, `handlers/`, `models/`, `tools/`, `hooks/`,
 Validation order:
 
 1. Read `package.json` and prefer project scripts if they exist.
-2. Refresh Cloudflare types:
-   - use `pnpm cf-typegen` if that script exists
-   - otherwise run `npx wrangler types`
-3. Regenerate Standard Agents Builder types by starting the dev server:
+2. Generate the project's types by starting the dev server. This is the only type-generation command:
    - usually `pnpm dev`, `npm run dev`, or equivalent
+   - the dev server writes `.agents/types.d.ts` and `.agents/virtual-module.d.ts` when it starts, and again after each change under `agents/`; the type checker fails while they are missing
+   - do not run `wrangler types`: a generated project has no Wrangler config, because the `builder()` plugin generates the Cloudflare configuration
    - do not run the `build` script of a generated project; it stops with a message on purpose, because builds run on the Standard Agents platform
-4. Run the project's type checker:
-   - prefer `pnpm type-check` / `npm run type-check` if present
+3. Run the project's type checker:
+   - prefer the project's script: `pnpm typecheck` / `npm run typecheck` in a generated project, or `type-check` if that is the script name
    - otherwise use the installed checker directly: `pnpm exec vue-tsc --build`, `pnpm exec tsc -b`, or `pnpm exec tsc --noEmit`
-5. If any validation step cannot run, state exactly what is missing.
+4. If any validation step cannot run, state exactly what is missing.
 
 ## Hosting