@tiangong-ai/cli 0.0.21 → 0.0.23

package/AGENTS.md

@@ -15,8 +15,8 @@ checkPaths:
   - .docpact/config.yaml
   - docs/agents/**
   - src/**
-lastReviewedAt: 2026-08-06
-lastReviewedCommit: f5d031588a8eb2694573b8c3c83ff07c6ecd2b6f
+lastReviewedAt: 2026-08-08
+lastReviewedCommit: c55eab450de73bed783c7417c43db20ef56c0c43
 ---
 
 # Tiangong AI CLI Contract
@@ -36,6 +36,7 @@ This repository owns the Tiangong AI command-line interface.
 
 ## Current Command Surface
 
+- `tiangong-ai --version`
 - `tiangong-ai doctor`
 - `tiangong-ai kb ingest`
 - `tiangong-ai kb ingest bulk`

package/README.md

@@ -12,8 +12,8 @@ checkPaths:
   - package.json
   - bin/**
   - src/**
-lastReviewedAt: 2026-08-04
-lastReviewedCommit: 7429c2ab92509920a2728dc38685ad5c4f2c8f13
+lastReviewedAt: 2026-08-07
+lastReviewedCommit: 5d942d487a7c4592de80e0ac64ac6741c6836942
 ---
 
 # Tiangong AI CLI
@@ -26,11 +26,19 @@ Package: `@tiangong-ai/cli` Executable: `tiangong-ai` Node: `>=24`
 npm install
 npm run build
 node ./bin/tiangong-ai.js --help
+node ./bin/tiangong-ai.js --version
 ```
 
 Use Node `24.x`; this package declares `>=24 <25` and includes `.nvmrc` for
 compatible version managers.
 
+After installation, print the package version with either top-level flag:
+
+```bash
+tiangong-ai --version
+tiangong-ai -v
+```
+
 ## KB Ingest
 
 Required environment:
@@ -195,6 +203,18 @@ file, and budget confirmation when `maxCostUsd` exceeds
 ```bash
 tiangong-ai research workspace init /absolute/path/to/workspace \
   --mode production-research
+tiangong-ai research capability catalog \
+  --path /absolute/path/to/workspace \
+  --workspace /absolute/path/to/workspace --json
+# Run the returned pinned project installation plan outside the research runtime.
+tiangong-ai research capability configure \
+  --profile internet-research \
+  --workspace /absolute/path/to/workspace --json
+tiangong-ai research capability credential set \
+  --id brave.search.api-key --from-env BRAVE_SEARCH_API_KEY \
+  --workspace /absolute/path/to/workspace --json
+tiangong-ai research capability doctor --live \
+  --workspace /absolute/path/to/workspace --json
 tiangong-ai research project preflight \
   --workspace /absolute/path/to/workspace \
   --question "How do advanced GPU process nodes change environmental resource burdens?" \
@@ -206,6 +226,27 @@ tiangong-ai research project init gpu-resource-impact \
   --confirm-budget --json
 ```
 
+Production admission requires at least one locked external capability with
+`brokered-network` and `discoveryScopes: ["public-internet"]`; an input plan or
+local files alone cannot represent internet coverage. The machine-readable
+catalog contains only external Skills and reports every required, enhanced,
+and conditional recommendation; exact source commit and whole-tree hash; a
+pinned installer version and checkout/install plan; credential requirements;
+and installed, configured, locked, and live provider status. Installation is
+never performed by the research runtime. It also reports the other Skills
+evaluated from the pinned upstream package and why each is not selected:
+custom question-specific admission, query assistance without evidence, or an
+execution model that the bounded GET broker does not authorize.
+
+The default `internet-research` profile selects Brave Web Search and News
+Search. `internet-research-with-context` additionally selects the
+subscription-dependent LLM Context endpoint, while
+`internet-research-with-media` also selects image and video discovery. A
+provider-plan or authentication failure blocks the selected profile instead of
+silently dropping a Skill. `credential set` reads the value only from the
+explicit owner environment name and stores it under the declared logical ID;
+the value is never returned or journaled.
+
 The requirements object declares `dimensions`, `sourceTypes`, `minSources`,
 `minFullTextSources`, `minDatedSources`, and optional inclusive
 `publicationDateFrom` / `publicationDateTo` boundaries (`YYYY-MM-DD` or
@@ -226,7 +267,11 @@ routes use the same agent family.
 
 Research execution requires `/usr/bin/sandbox-exec` on macOS or Bubblewrap
 (`bwrap`) on Linux. Windows can inspect and configure workspaces but does not
-execute research packages.
+execute research packages. That outer platform sandbox is the execution
+boundary. Codex is therefore started with its nested sandbox disabled: nesting
+Seatbelt on macOS can cancel MCP calls even though the process is already
+confined. Shell and unified-exec tools remain disabled, as do undeclared Codex
+integrations.
 
 Add immutable local evidence, verify the workspace, and execute ready work:
 
@@ -237,7 +282,7 @@ tiangong-ai research project input add gpu-resource-impact \
   --role primary
 tiangong-ai research workspace doctor --workspace /absolute/path/to/workspace
 tiangong-ai research workspace doctor --workspace /absolute/path/to/workspace \
-  --agent-smoke
+  --agent-smoke --capability-smoke
 tiangong-ai research run --workspace /absolute/path/to/workspace \
   --project gpu-resource-impact --progress-jsonl
 tiangong-ai research status --workspace /absolute/path/to/workspace --json
@@ -279,9 +324,15 @@ facts.
 Total, per-package, output, repair, broker-response bytes, estimated broker
 context tokens, context items, wall-time, output-count, output-size, and attempt
 limits live in `.tiangong-research/config.json`.
+New workspaces reserve 500,000 total tokens by default, including 200,000 for
+discovery; the remaining package defaults are 55,000 for analysis, 60,000 for
+synthesis, and 120,000 for review. These are admission ceilings rather than a
+target spend and can be lowered only when the resulting pre-call reservations
+still fit.
 Before an agent starts, the runtime reserves the package token and conservative
 price budget. The call-level check accounts for prompt and schema bytes at
 three bytes per token, repeats input allowance for every permitted API turn,
+adds the maximum bounded broker context for every permitted discovery turn,
 and adds primary output plus a potential isolated repair's input and output;
 insufficient package or remaining project budget prevents invocation. The
 provider cost cap is the current package reservation, not the remaining
@@ -292,7 +343,9 @@ schema tool, uses one plain-JSON turn, and remains subject to the CLI schema and
 semantic validators. Current Codex and Claude CLI adapters report
 output usage only after execution, so preflight identifies
 `outputTokenLimitEnforcement` as `post-execution`; captured bytes provide a
-separate process bound, and over-limit output fails without promotion.
+separate process bound. Discovery capture allowance includes the bounded MCP
+tool contexts as well as the requested model output, and over-limit output fails
+without promotion.
 Preflight also reports per-stage `maxTurns` and `turnLimitEnforcement`: Claude
 receives a provider-side turn cap, while the current Codex CLI exposes no such
 flag, so its turn allowance is reservation guidance plus post-execution
@@ -315,7 +368,12 @@ context, broker objects, and registered local input hashes before recording
 their safe locators. Capsule deletion therefore does not delete the durable
 review chain.
 
-Discovery alone may use the capability broker and workspace-read tools.
+Discovery receives only the capability broker as an execution tool. The CLI
+embeds the exact staged capability manifest and each external Skill's top-level
+`SKILL.md` in the prompt, so the producer does not need filesystem or shell
+access and cannot execute provider examples directly. Broker responses include
+the exact bounded context inline with the hash-bound receipt; raw objects remain
+in the permanent evidence store for audit.
 Analyze and synthesize receive bounded, hash-verified prior-stage artifacts in
 their prompt with tools disabled. Review is also tool-free and limited to the
 two turns required by the structured-output protocol:
@@ -329,8 +387,31 @@ dimension is usable but incomplete; a missing dimension or unmet declared
 minimum blocks downstream work. Qualitative gaps remain visible without
 silently changing those mechanical fields.
 
-Method skills are declared in `.tiangong-research/capabilities.json` with
-absolute skill paths and explicit permissions, then frozen before execution:
+Method Skills are external to this project. Recommended evidence Skills are
+selected through `research capability configure`; an owner-selected database,
+domain index, or other external method is admitted from an absolute reviewed
+definition:
+
+```bash
+tiangong-ai research capability import \
+  --definition /absolute/path/to/external-capability.json \
+  --workspace /absolute/path/to/workspace --json
+```
+
+`research capability catalog --json` returns the authoritative custom
+definition template. Its source must identify an external git, registry, or
+local artifact with an immutable reference, explicit `expectedTreeSha256`, and
+license. Git references must be full 40-character commits; registry references
+must be exact versions; local references must equal
+`sha256:<expectedTreeSha256>`. Every source type must match the installed whole
+tree before a lock can be written. Skill trees reject symlinks and excessive
+file counts/sizes. Project-owned Tiangong Skills are rejected as imported
+evidence providers. Configure/import refuses to rewrite the lock if any
+existing capability has drifted; restore it or explicitly update its source
+identity and expected hash first.
+
+External Skills use absolute paths and explicit permissions, then freeze
+before execution:
 
 ```bash
 tiangong-ai research capability lock --workspace /absolute/path/to/workspace
@@ -341,7 +422,14 @@ A capability using `brokered-network` must declare exact `allowedHosts` and may
 declare an `http` policy with one exact `accept` value,
 `allowedContentTypes`, `maxResponseBytes`, and `maxItems`. Its optional
 `coverage` block declares dimensions, source types, full-text availability,
-and publication-date availability for the preflight gap report.
+publication-date availability, and named discovery scopes for the preflight gap
+report. Mark `requiredForDiscovery: true` for every public index or
+owner-whitelisted database the question must exercise. Downstream work is
+blocked unless each such capability produces its own verified broker receipt;
+another local file cannot substitute for it. The current evidence broker
+authorizes bounded GET endpoints only. A non-network external method-guidance
+Skill stages reviewed instructions but does not grant an undeclared tool or
+service call.
 Optional credentials declare logical IDs, exact host scopes, header names, and
 prefixes. Put only the logical value map in `.tiangong-research/.env`:
 
@@ -349,9 +437,21 @@ prefixes. Put only the logical value map in `.tiangong-research/.env`:
 TIANGONG_RESEARCH_CAPABILITY_CREDENTIALS_JSON={"source.example.api":"owner-provided-value"}
 ```
 
+Prefer the non-echoing configuration command over hand editing:
+
+```bash
+tiangong-ai research capability credential set \
+  --id source.example.api --from-env OWNER_DATABASE_API_KEY \
+  --workspace /absolute/path/to/workspace --json
+```
+
 The broker injects declared credentials only for admitted HTTPS hosts. Agent
 processes do not receive this variable. Keep the file owner-only (`chmod 600`)
-and use `research workspace doctor` before a run. The broker preserves a
+and run `research capability doctor --live` plus production
+`research workspace doctor --agent-smoke --capability-smoke` before a run.
+Capability doctor retries only one 429 response with bounded `Retry-After`
+backoff; deterministic 4xx, missing subscription, authentication, drift, and
+content-type failures stop explicitly. The broker preserves a
 sanitized non-2xx excerpt, safe request ID, and `Retry-After`; it supports JSON
 Pointer extraction, bounded item and estimated-token views, and an explicit
 public-response cache. For a JSON collection, use the returned

package/dist/cli.d.ts

@@ -3,6 +3,7 @@ export type { CliIO, Output } from "./io.js";
 export { parseArgs } from "./args.js";
 export { DEFAULT_API_BASE_URL, DEFAULT_API_PATH_PREFIX } from "./kb/config.js";
 export { resolveCollectionSelector } from "./kb/selector.js";
+export declare const CLI_VERSION: string;
 export declare const DEFAULT_BULK_POLL_INTERVAL_SECONDS = 30;
 export declare const DEFAULT_BULK_PIPELINE_HEALTH_POLL_INTERVAL_SECONDS = 60;
 export declare function runCli(argv: string[], io: CliIO): Promise<number>;

package/dist/cli.js

@@ -6,10 +6,11 @@ import { basename, dirname, extname, isAbsolute, join, posix as pathPosix, relat
 import { setTimeout as sleep } from "node:timers/promises";
 import { deflateRawSync, inflateRawSync } from "node:zlib";
 import sharp from "sharp";
+import packageMetadata from "../package.json" with { type: "json" };
 import { getBoolean, getNonNegativeInteger, getPositiveInteger, getString, nonNegativeIntegerValue, parseArgs, positiveIntegerValue, positiveNumberValue, } from "./args.js";
 import { isObject, responseData, stringField } from "./data.js";
 import { firstEnv, loadDotenv } from "./env.js";
-import { CliError, HttpError } from "./errors.js";
+import { CliError, HttpError, toErrorPayload } from "./errors.js";
 import { jsonRequest } from "./http.js";
 import { runEducationCommand } from "./education/commands.js";
 import { collectionKey, collectionPath, listCollections, resolveCollection, resolveSelectorFields, } from "./kb/client.js";
@@ -18,11 +19,13 @@ import { runCourseFulltextCommand } from "./kb/course-fulltext.js";
 import { readBulkPipelineHealth } from "./kb/pipeline-health.js";
 import { resolveCollectionSelector } from "./kb/selector.js";
 import { batchDocumentStatuses, getDocumentStatus } from "./kb/status.js";
-import { write } from "./io.js";
+import { stringifyJson, write } from "./io.js";
 import { runResearchCommand } from "./research/commands.js";
+import { configuredResearchSecrets, sanitizeResearchText, sanitizeResearchValue, } from "./research/workspace/sanitization.js";
 export { parseArgs } from "./args.js";
 export { DEFAULT_API_BASE_URL, DEFAULT_API_PATH_PREFIX } from "./kb/config.js";
 export { resolveCollectionSelector } from "./kb/selector.js";
+export const CLI_VERSION = packageMetadata.version;
 const DEFAULT_RETRIES = 3;
 const DEFAULT_BULK_WINDOW_SIZE = 100;
 const DEFAULT_BULK_TOP_UP_MAX = 50;
@@ -55,6 +58,10 @@ const BULK_SUPPORTED_EXTENSIONS = new Set([
 ]);
 export async function runCli(argv, io) {
     try {
+        if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v")) {
+            write(io.stdout, `${CLI_VERSION}\n`);
+            return 0;
+        }
         loadDotenv(io.env);
         if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
             write(io.stdout, topHelp());
@@ -132,7 +139,18 @@ export async function runCli(argv, io) {
     }
     catch (error) {
         if (error instanceof CliError) {
-            write(io.stderr, `${error.message}\n`);
+            if (argv[0] === "research") {
+                const secrets = configuredResearchSecrets(io.env);
+                if (argv.includes("--json")) {
+                    write(io.stderr, stringifyJson(sanitizeResearchValue(toErrorPayload(error), secrets), true));
+                }
+                else {
+                    write(io.stderr, `${sanitizeResearchText(error.message, secrets)}\n`);
+                }
+            }
+            else {
+                write(io.stderr, `${error.message}\n`);
+            }
             return error.exitCode;
         }
         throw error;
@@ -2699,6 +2717,10 @@ Usage:
   tiangong-ai research search --input <request.json>|--query <query> [--sources default|all|sci|report|patent|esg]
   tiangong-ai education search --input <request.json>|--query <query> [--sources default|all|course|edu|textbook]
 
+Options:
+  -h, --help      Show this help.
+  -v, --version   Show the CLI version.
+
 Run "tiangong-ai kb --help" for KB options.
 Run "tiangong-ai research --help" for research options.
 Run "tiangong-ai education --help" for education options.