@blxzer/cursor-trellis 0.3.4 → 0.3.5

package/dist/commands/sdk/run.d.ts

@@ -0,0 +1,42 @@
+export type SdkRunMode = "mock" | "live";
+export interface SdkRunOptions {
+    task: string;
+    campaign: string;
+    mode: SdkRunMode;
+    prompt?: string;
+    cwd?: string;
+    rpcUrl?: string;
+    token?: string;
+    noRpc?: boolean;
+    /** When set, write dogfood under this absolute path instead of <task>/research/ */
+    evidencePath?: string;
+}
+export interface SdkRunResult {
+    ok: boolean;
+    runId: string;
+    mode: SdkRunMode;
+    taskPath: string;
+    evidencePath: string;
+    rpc: {
+        attempted: boolean;
+        ok: boolean;
+        url?: string;
+        detail: string;
+    };
+    agent: {
+        status: string;
+        result: string;
+    };
+    errors: string[];
+}
+/**
+ * Build the Agent prompt for SDK RUN. Always prepends an explicit --task binding
+ * block so SessionStart "Selected task: none" cannot be misread as unbound.
+ */
+export declare function buildSdkRunPrompt(taskPath: string, userPrompt?: string): string;
+/**
+ * Minimal Trellis SDK RUN: bind explicit task path, run mock/live agent, write dogfood, emit RPC.
+ */
+export declare function runSdkRun(options: SdkRunOptions): Promise<SdkRunResult>;
+export declare function runSdkRunCommand(options: SdkRunOptions): Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/dist/commands/sdk/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/commands/sdk/run.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE;QACH,SAAS,EAAE,OAAO,CAAC;QACnB,EAAE,EAAE,OAAO,CAAC;QACZ,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,KAAK,EAAE;QACL,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAqBD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAeR;AAyKD;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAkE7E;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,CAuBjB"}

package/dist/commands/sdk/run.js

@@ -0,0 +1,245 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { campaignBroadcastTopic } from "@blxzer/cursor-trellis-core/rpc";
+import { resolveRpcToken, resolveRpcUrl, rpcPublish, rpcRegister, } from "../rpc/client.js";
+const DEFAULT_PROMPT = "Trellis SDK RUN (S1 worker): confirm task path binding by restating the absolute taskPath; do not call integrate-child or start-execution --approved; summarize readiness in one short paragraph.";
+function resolveTaskPath(taskArg) {
+    return path.resolve(process.cwd(), taskArg);
+}
+function assertTaskDir(taskPath) {
+    if (!fs.existsSync(taskPath) || !fs.statSync(taskPath).isDirectory()) {
+        throw new Error(`Task path is not a directory: ${taskPath}`);
+    }
+    const prd = path.join(taskPath, "prd.md");
+    if (!fs.existsSync(prd)) {
+        throw new Error(`Task path missing prd.md (refusing unbound SDK RUN; pass --task <dir> that contains prd.md): ${prd}`);
+    }
+}
+/**
+ * Build the Agent prompt for SDK RUN. Always prepends an explicit --task binding
+ * block so SessionStart "Selected task: none" cannot be misread as unbound.
+ */
+export function buildSdkRunPrompt(taskPath, userPrompt) {
+    const absoluteTask = path.resolve(taskPath);
+    const prdPath = path.join(absoluteTask, "prd.md");
+    const instruction = userPrompt?.trim() || DEFAULT_PROMPT;
+    return [
+        "## SDK RUN task binding (authoritative)",
+        `- Bound via CLI \`--task\` (not \`selected_task\` / SessionStart).`,
+        `- taskPath (absolute): \`${absoluteTask}\``,
+        `- prd.md (absolute): \`${prdPath}\``,
+        `- Binding status: **BOUND**.`,
+        `- Do **not** report unbound solely because SessionStart says \`Selected task: none\` — that pointer is irrelevant for SDK RUN.`,
+        "",
+        "## Instructions",
+        instruction,
+    ].join("\n");
+}
+async function runMockAgent(prompt) {
+    return {
+        status: "completed",
+        result: `[mock] SDK RUN accepted prompt (${prompt.length} chars). No @cursor/sdk call. CAP: safe-task/SDK only; no Parent integrate.`,
+    };
+}
+async function runLiveAgent(prompt, cwd) {
+    const apiKey = process.env.CURSOR_API_KEY?.trim();
+    if (!apiKey) {
+        throw new Error([
+            "Live SDK RUN requires CURSOR_API_KEY (and prior user consent to use it).",
+            "Use --mock or omit --live.",
+            "Discovery: run `cstl sdk status` for setup steps (never commit the key).",
+        ].join(" "));
+    }
+    let Agent;
+    try {
+        // Avoid static resolution so mock/CI builds do not require @cursor/sdk installed.
+        const dynamicImport = new Function("specifier", "return import(specifier)");
+        const mod = await dynamicImport("@cursor/sdk");
+        Agent = mod.Agent;
+    }
+    catch {
+        throw new Error("@cursor/sdk is not installed. After explicit consent, add the optional dependency, or use --mock.");
+    }
+    const outcome = await Agent.prompt(prompt, {
+        apiKey,
+        model: { id: "composer-2.5" },
+        local: { cwd },
+    });
+    return {
+        status: outcome.status ?? "unknown",
+        result: outcome.result ?? "",
+    };
+}
+function writeDogfoodEvidence(options) {
+    const dir = path.dirname(options.evidencePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const body = `# SDK RUN dogfood
+
+generated: ${new Date().toISOString()}
+runId: \`${options.result.runId}\`
+mode: \`${options.result.mode}\`
+taskPath: \`${options.result.taskPath}\`
+
+## Agent
+
+- status: \`${options.result.agent.status}\`
+- result:
+
+\`\`\`text
+${options.result.agent.result}
+\`\`\`
+
+## RPC
+
+- attempted: ${options.result.rpc.attempted}
+- ok: ${options.result.rpc.ok}
+- url: ${options.result.rpc.url ?? "(none)"}
+- detail: ${options.result.rpc.detail}
+
+## CAP / HITL
+
+- Claim: SDK / safe-task automation RUN only
+- Does **not** call \`task.py start-execution --approved\` or \`integrate-child\`
+- Not an IDE chat tab
+
+## Errors
+
+${options.result.errors.length === 0
+        ? "(none)"
+        : options.result.errors.map((e) => `- ${e}`).join("\n")}
+`;
+    fs.writeFileSync(options.evidencePath, body, "utf-8");
+}
+async function emitRpcEvents(options) {
+    const from = { kind: "sdk", id: options.runId };
+    const topic = campaignBroadcastTopic(options.campaign);
+    const reg = await rpcRegister({
+        url: options.url,
+        kind: from.kind,
+        id: from.id,
+        campaignId: options.campaign,
+        token: options.token,
+    });
+    if (reg.error) {
+        return {
+            ok: false,
+            detail: `register failed: ${reg.error.code} ${reg.error.message}`,
+        };
+    }
+    const body = {
+        event: "trellis.child.state",
+        taskPath: options.taskPath,
+        mode: options.mode,
+        status: options.status,
+        runId: options.runId,
+        clientKind: "sdk",
+    };
+    const published = await rpcPublish({
+        url: options.url,
+        from,
+        topic,
+        campaignId: options.campaign,
+        body,
+        token: options.token,
+    });
+    if (published.error) {
+        return {
+            ok: false,
+            detail: `publish failed: ${published.error.code} ${published.error.message}`,
+        };
+    }
+    const delivered = typeof published.payload.delivered === "number"
+        ? published.payload.delivered
+        : 0;
+    return {
+        ok: true,
+        detail: `registered sdk:${options.runId}; published ${topic} (delivered=${delivered})`,
+    };
+}
+/**
+ * Minimal Trellis SDK RUN: bind explicit task path, run mock/live agent, write dogfood, emit RPC.
+ */
+export async function runSdkRun(options) {
+    const errors = [];
+    const runId = randomUUID().slice(0, 8);
+    const taskPath = resolveTaskPath(options.task);
+    assertTaskDir(taskPath);
+    const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+    const prompt = buildSdkRunPrompt(taskPath, options.prompt);
+    const evidencePath = options.evidencePath ??
+        path.join(taskPath, "research", "sdk-run-dogfood.md");
+    let agent;
+    if (options.mode === "live") {
+        agent = await runLiveAgent(prompt, cwd);
+    }
+    else {
+        agent = await runMockAgent(prompt);
+    }
+    let rpc = {
+        attempted: false,
+        ok: false,
+        detail: "skipped (--no-rpc)",
+    };
+    if (!options.noRpc) {
+        const url = resolveRpcUrl(options.rpcUrl);
+        const token = resolveRpcToken(options.token);
+        rpc = { attempted: true, ok: false, url, detail: "" };
+        try {
+            const outcome = await emitRpcEvents({
+                url,
+                token,
+                runId,
+                campaign: options.campaign,
+                taskPath,
+                mode: options.mode,
+                status: agent.status,
+            });
+            rpc.ok = outcome.ok;
+            rpc.detail = outcome.detail;
+            if (!outcome.ok) {
+                errors.push(`rpc: ${outcome.detail}`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            rpc.ok = false;
+            rpc.detail = `unavailable: ${message}`;
+            errors.push(`rpc: ${rpc.detail}`);
+        }
+    }
+    const partial = {
+        runId,
+        mode: options.mode,
+        taskPath,
+        evidencePath,
+        rpc,
+        agent,
+        errors,
+    };
+    writeDogfoodEvidence({ evidencePath, result: partial });
+    // RPC degrade is allowed (LAYERED); validation failures already threw.
+    const ok = options.mode === "mock" || agent.status.length > 0;
+    return { ok, ...partial };
+}
+export async function runSdkRunCommand(options) {
+    try {
+        const result = await runSdkRun(options);
+        if (result.ok) {
+            console.log(`SDK RUN OK mode=${result.mode} runId=${result.runId} task=${result.taskPath}`);
+            console.log(`evidence: ${result.evidencePath}`);
+            console.log(`rpc: ${result.rpc.detail}`);
+            if (result.errors.length > 0) {
+                console.warn(`notes: ${result.errors.join("; ")}`);
+            }
+            return 0;
+        }
+        console.error(`SDK RUN FAILED: ${result.errors.join("; ") || "unknown"}`);
+        return 1;
+    }
+    catch (error) {
+        console.error("SDK RUN error:", error instanceof Error ? error.message : error);
+        return 1;
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/commands/sdk/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/commands/sdk/run.ts"],"names":[],"mappings":"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"}

package/dist/commands/sdk/status.d.ts

@@ -0,0 +1,14 @@
+export type SdkStatusResult = {
+    ok: boolean;
+    cwd: string;
+    keyPresent: boolean;
+    capabilitySelected: boolean;
+    sdkModuleResolvable: boolean | null;
+    nextSteps: string[];
+};
+export declare function collectSdkStatus(cwd?: string): Promise<SdkStatusResult>;
+export declare function runSdkStatusCommand(options?: {
+    cwd?: string;
+    json?: boolean;
+}): Promise<number>;
+//# sourceMappingURL=status.d.ts.map

package/dist/commands/sdk/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/commands/sdk/status.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,OAAO,CAAC;IACpB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,mBAAmB,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB,CAAC;AAeF,wBAAsB,gBAAgB,CACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,eAAe,CAAC,CAoC1B;AAED,wBAAsB,mBAAmB,CAAC,OAAO,CAAC,EAAE;IAClD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmClB"}

package/dist/commands/sdk/status.js

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+import { cursorApiKeySetupGuide, hasCursorApiKey, } from "../../utils/cursor-sdk-gate.js";
+import { loadProjectCapabilities } from "../../utils/project-capabilities.js";
+async function probeSdkModuleResolvable() {
+    try {
+        const dynamicImport = new Function("specifier", "return import(specifier)");
+        await dynamicImport("@cursor/sdk");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function collectSdkStatus(cwd = process.cwd()) {
+    const keyPresent = hasCursorApiKey();
+    const selected = loadProjectCapabilities(cwd);
+    const capabilitySelected = selected.includes("cursor-sdk");
+    const sdkModuleResolvable = await probeSdkModuleResolvable();
+    const nextSteps = [];
+    if (!keyPresent) {
+        nextSteps.push("Set CURSOR_API_KEY in this process, then re-run `cstl sdk status` or re-select `cursor-sdk` during init/update.");
+        nextSteps.push("Use `cstl sdk run --task <path> --mock` without a key.");
+    }
+    else {
+        nextSteps.push("Key present. You may enable `cursor-sdk` at init/update and use `cstl sdk run --task <path> --live` after accepting billing/privacy risk.");
+    }
+    if (!capabilitySelected && fs.existsSync(path.join(cwd, ".cstl"))) {
+        nextSteps.push("Project has `.cstl/` but `cursor-sdk` is not in `.cstl/capabilities.json` selected list.");
+    }
+    if (sdkModuleResolvable === false) {
+        nextSteps.push("@cursor/sdk could not be imported from this CLI install; reinstall cursor-trellis / @blxzer/cursor-trellis.");
+    }
+    return {
+        ok: keyPresent,
+        cwd,
+        keyPresent,
+        capabilitySelected,
+        sdkModuleResolvable,
+        nextSteps,
+    };
+}
+export async function runSdkStatusCommand(options) {
+    const cwd = options?.cwd ? path.resolve(options.cwd) : process.cwd();
+    const status = await collectSdkStatus(cwd);
+    if (options?.json) {
+        console.log(JSON.stringify(status, null, 2));
+        return status.keyPresent ? 0 : 1;
+    }
+    console.log("Cursor SDK status");
+    console.log(`  cwd: ${status.cwd}`);
+    console.log(`  CURSOR_API_KEY: ${status.keyPresent ? "present" : "missing"} (value never printed)`);
+    console.log(`  capability cursor-sdk selected: ${status.capabilitySelected ? "yes" : "no"}`);
+    console.log(`  @cursor/sdk importable from CLI: ${status.sdkModuleResolvable === null
+        ? "unknown"
+        : status.sdkModuleResolvable
+            ? "yes"
+            : "no"}`);
+    console.log("  next steps:");
+    for (const step of status.nextSteps) {
+        console.log(`  - ${step}`);
+    }
+    if (!status.keyPresent) {
+        console.log("");
+        console.log(cursorApiKeySetupGuide());
+    }
+    return status.keyPresent ? 0 : 1;
+}
+//# sourceMappingURL=status.js.map

package/dist/commands/sdk/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../../src/commands/sdk/status.ts"],"names":[],"mappings":"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"}

package/dist/templates/common/bundled-skills/smart-search-cli/SKILL.md

@@ -14,18 +14,17 @@ Use the local `smart-search` command as the default execution layer for web rese
 3. If OpenAI-compatible `search` hangs or times out after `doctor` succeeds, run `smart-search diagnose openai-compatible --format markdown` and use its summary/recommendation. This one command tests quick chat plus real search-shape `stream=false` and `stream=true`.
 4. If `doctor` returns `ok: true`, use only `smart-search` CLI subcommands for web research. Do not call Codex native web search in the same task.
 5. For every research question, run a bilingual `smart-search search` pair: one Chinese-source query and one English-source query. Save both JSON outputs.
-6. Use `smart-search search` as the first hop for realtime, broad exploration, community signals, multi-source summaries, and routing metadata. The default broad pass is bilingual, not Zhipu-backed.
-7. Do not use `smart-search zhipu-search` in normal workflows. Zhipu is deprecated and not used by default routing because quota may be unavailable; the command remains only for manual legacy compatibility when the user explicitly asks for it.
-8. Use `smart-search context7-library` / `context7-docs` first for library, SDK, API, framework, or documentation intent.
-9. Use `smart-search exa-search` for official domains, papers, product pages, trusted sites, and low-noise discovery. Do not treat Exa as the universal second hop for every high-risk or verification task.
-10. Use `smart-search search --extra-sources N` for Tavily/Firecrawl horizontal candidates, and `smart-search fetch` for page text that can support final claims.
-11. Use `smart-search exa-similar` when the user gives a representative URL and wants related pages or neighboring sources.
-12. Use `smart-search fetch` when the user gives a URL or a claim depends on page content.
-13. Use `smart-search map` when a documentation site or domain structure matters.
-14. To change the main-search model, use `smart-search config set OPENAI_COMPATIBLE_MODEL ...`.
-15. For current-news, policy, finance, health, or other high-risk facts, do not answer from broad `search.content` alone. Use the bilingual search pair plus intent-specific sources: Context7 for docs/API, Exa for official/trusted domains or papers, then `fetch` key pages and summarize only what fetched text supports.
-16. Use `smart-search research "question" --format json` when the user wants the CLI to run live Deep Research end to end instead of only planning. It executes plan -> discover -> fetch/read -> gap check -> evidence-only synthesis.
-17. Preserve command lines and source URLs in your answer. Prefer citing fetched pages or `primary_sources`; treat `extra_sources` as follow-up candidates, not verified evidence for generated claims.
+6. Use `smart-search search` as the first hop for realtime, broad exploration, community signals, multi-source summaries, and routing metadata. The default broad pass is bilingual via Tavily / Firecrawl when configured.
+7. Use `smart-search context7-library` / `context7-docs` first for library, SDK, API, framework, or documentation intent.
+8. Use `smart-search exa-search` for official domains, papers, product pages, trusted sites, and low-noise discovery. Do not treat Exa as the universal second hop for every high-risk or verification task.
+9. Use `smart-search search --extra-sources N` for Tavily/Firecrawl horizontal candidates, and `smart-search fetch` for page text that can support final claims.
+10. Use `smart-search exa-similar` when the user gives a representative URL and wants related pages or neighboring sources.
+11. Use `smart-search fetch` when the user gives a URL or a claim depends on page content.
+12. Use `smart-search map` when a documentation site or domain structure matters.
+13. To change the main-search model, use `smart-search config set OPENAI_COMPATIBLE_MODEL ...` (or `XAI_MODEL ...` for the xAI route).
+14. For current-news, policy, finance, health, or other high-risk facts, do not answer from broad `search.content` alone. Use the bilingual search pair plus intent-specific sources: Context7 for docs/API, Exa for official/trusted domains or papers, then `fetch` key pages and summarize only what fetched text supports.
+15. Use `smart-search research "question" --format json` when the user wants the CLI to run live Deep Research end to end instead of only planning. It executes plan -> discover -> fetch/read -> gap check -> evidence-only synthesis.
+16. Preserve command lines and source URLs in your answer. Prefer citing fetched pages or `primary_sources`; treat `extra_sources` as follow-up candidates, not verified evidence for generated claims.
 
 ## Deep Research Mode
 
@@ -101,7 +100,6 @@ Allowed `steps[].tool` values are `search`, `exa-search`, `exa-similar`, `contex
 Capability boundaries:
 
 - `search`: broad bilingual discovery and synthesis through `main_search`; inspect `routing_decision`, `provider_attempts`, `fallback_used`, and `source_warning`. Do not treat broad answers as proof for high-risk claims.
-- `zhipu-search`: deprecated manual compatibility command. Do not include it in default plans or workflows unless the user explicitly requests Zhipu.
 - `context7-library` / `context7-docs`: library, SDK, API, framework, and documentation intent. Prefer Context7 before Exa for docs/API questions.
 - `exa-search`: low-noise discovery for official domains, papers, product pages, known domains, and trusted pages. Use it when that boundary fits; it is not the default second hop for every verification task.
 - `exa-similar`: adjacent-source discovery when a known reliable URL is available.
@@ -122,9 +120,10 @@ Default evidence policy is `fetch_before_claim`: key claims in the final answer
 
 Live Deep Research executor:
 
-- `smart-search research QUERY [--budget quick|standard|deep] [--locale-scope cn|en|both] [--evidence-dir PATH] [--fallback auto|off] [--dry-run] [--progress] [--format json|markdown|content] [--output PATH]` runs the staged workflow directly. Use `--dry-run` to preview plan/routing without live providers; `--progress` for stderr stage logs; `--locale-scope cn` or `en` to skip bilingual discovery when cost matters.
+- `smart-search research QUERY [--budget quick|standard|deep] [--locale-scope cn|en|both] [--evidence-dir PATH] [--fallback auto|off] [--dry-run] [--progress] [--timeout SECONDS] [--format json|markdown|content] [--output PATH]` runs the staged workflow directly. Use `--dry-run` to preview plan/routing without live providers; `--progress` for stderr stage logs; `--locale-scope cn` or `en` to skip bilingual discovery when cost matters. Docs/API intent is precision-first (weak language/product tokens alone do not trigger). If docs discovery yields no HTTP evidence, the executor fail-opens to `web_discovery` (`stage_results` may include `fail_open_web_after_docs`). Default `--timeout` is 600 seconds for the full research run.
 - Default `--fallback auto` permits same-capability fallback inside selected routes. Use `--fallback off` only for debugging or deterministic provider checks.
-- Research output includes `final_answer`, `citations`, `evidence_items`, `gap_check`, `provider_attempts`, `fallback_used`, `degraded`, `route_policy_version`, and `evidence_dir`.
+- Research output includes `final_answer`, `citations`, `evidence_items`, `gap_check`, `provider_attempts`, `fallback_used`, `degraded`, `route_policy_version`, `output_schema_version`, and `evidence_dir`.
+- Contract fields for agents: always read `output_schema_version` (currently `1`), `route_policy_version`, `minimum_profile_ok`, and `cache_hit` on attempts/stages. Treat `cache_hit: true` as possibly stale only if the local config model/endpoint changed without process restart — keys include model identity, but process-local TTL still applies. Prefer `doctor --format json` when `minimum_profile_ok` is false (fail-closed).
 - The synthesis is evidence-only. It may cite fetched/read evidence, but it must not cite unfetched discovery candidates as proof.
 - If providers are exhausted or evidence cannot close, return the degraded gaps rather than inventing missing claims.
 
@@ -151,7 +150,7 @@ smart-search research "https://example.com/source" --format json
 
 ## Provider Routing
 
-- `search` builds `main_search` from `OPENAI_COMPATIBLE_API_URL` + `OPENAI_COMPATIBLE_API_KEY`, which registers OpenAI-compatible Chat Completions.
+- `search` builds `main_search` from `XAI_API_KEY` (xAI Responses with server-side `web_search`/`x_search` tools) and/or `OPENAI_COMPATIBLE_API_URL` + `OPENAI_COMPATIBLE_API_KEY` (Chat Completions). One is enough; when both are configured, `SMART_SEARCH_MAIN_SEARCH_ROUTE` (ordered CSV of `xai-responses,openai-compatible`) sets priority, and a single entry disables cross-route fallback.
 - `search` is the default first hop for broad exploration, current synthesis, and routing metadata.
 - OpenAI-compatible relays/gateways use Chat Completions `/chat/completions` through `OPENAI_COMPATIBLE_*`.
 - `OPENAI_COMPATIBLE_STREAM=true` or `search --stream` sets `stream=true` only for OpenAI-compatible `search` and provider-side `fetch`; it is a relay compatibility switch and does not affect URL description or source ranking.
@@ -160,7 +159,7 @@ smart-search research "https://example.com/source" --format json
 - Jina Reader is `web_fetch` only, not a general search provider. `JINA_API_KEY` is required before Jina satisfies the standard minimum profile; anonymous `r.jina.ai` is explicit/experimental fetch behavior.
 - `search` exposes `--validation fast|balanced|strict`, `--fallback auto|off`, and `--providers auto|CSV`. Default validation is `balanced`; fallback only happens within the same capability.
 - `search --validation strict` uses the same bilingual web_search policy as balanced mode when source discovery providers are configured. Strict queries without primary, docs, fetch, or explicit source evidence can still fail with `evidence_error`; use `--extra-sources N`, source-first commands such as `exa-search`, or `fetch` when citable evidence is required.
-- `search` runs bilingual web_search source discovery through Tavily / Firecrawl when configured. Zhipu is deprecated from default routing and is not the first hop for Chinese/current/domestic searches.
+- `search` runs bilingual web_search source discovery through Tavily / Firecrawl when configured.
 - Docs/API/library routing stays explicit keyword intent-based and should prefer Context7 first. Exa is for official-domain or low-noise supplemental discovery, not the default docs answer route.
 - `search` calls Tavily and/or Firecrawl for `extra_sources` only when `--extra-sources N` is greater than 0.
 - With both Tavily and Firecrawl configured, `search --extra-sources N` splits extra sources between them, with Tavily receiving about 60% and Firecrawl the rest.
@@ -170,11 +169,8 @@ smart-search research "https://example.com/source" --format json
 - `map` currently uses Tavily only.
 - `exa-search` and `exa-similar` use Exa only.
 - `context7-library` and `context7-docs` use Context7 only.
-- `zhipu-search` uses Zhipu only and is retained as a deprecated manual compatibility command.
-- `zhipu-search` corresponds to the official Zhipu Web Search API route, using `ZHIPU_API_URL` plus `ZHIPU_SEARCH_ENGINE`; it is not Zhipu Chat Completions `tools=[web_search]`, not Search Agent, and not the MCP Server.
-- `ZHIPU_SEARCH_ENGINE` defaults to `search_std`. Official Web Search API service values include `search_std`, `search_pro`, `search_pro_sogou`, and `search_pro_quark`; keep custom values possible because official services may change.
-- `TAVILY_API_URL` only affects Tavily REST calls and does not proxy Zhipu. Zhipu defaults to `https://open.bigmodel.cn/api` unless `ZHIPU_API_URL` is set.
-- `doctor` tests configured main-search providers, Exa, Tavily, Jina, Zhipu Web Search API, and Context7 connectivity. Firecrawl status currently means the key is configured, not that a live Firecrawl request succeeded.
+- `TAVILY_API_URL` only affects Tavily REST calls.
+- `doctor` tests configured main-search providers, Exa, Tavily, Jina, and Context7 connectivity. Firecrawl status currently means the key is configured, not that a live Firecrawl request succeeded.
 
 ## Evidence Files
 
@@ -270,13 +266,11 @@ Use this when the user wants work that can be inspected, resumed, or audited.
 - Use `smart-search doctor --format json` for agent/script parsing and `smart-search doctor --format markdown` when a human wants a detailed diagnostic report.
 - If `smart-search doctor --format json` returns `ok: false`, follow the `error` field's guidance (`smart-search setup` or `smart-search config set KEY VALUE`); do not silently fall back to native web search.
 - Use `smart-search diagnose openai-compatible --format markdown` when `doctor` succeeds but OpenAI-compatible `search` appears to hang, returns a timeout, or differs between `--stream` and `--no-stream`. It is the beginner-facing one-command report for upstream/relay compatibility.
-- Interactive `smart-search setup` is a language-selecting grouped wizard with arrow-key / Space / Enter provider selection. It guides users through required `main_search`, `docs_search`, and fetch capability. Zhipu is no longer recommended or prompted in the default setup flow.
+- Interactive `smart-search setup` is a language-selecting grouped wizard with arrow-key / Space / Enter provider selection. It guides users through required `main_search`, `docs_search`, and fetch capability.
 - The setup wizard prints beginner filling examples for official-service and relay/pooled-endpoint minimum profiles. Keep that guidance on stderr so stdout remains parseable JSON/Markdown/content output.
 - Use `smart-search setup --lang en` for an English wizard and `smart-search setup --advanced` only when low-level config keys must be shown one by one.
-- Use `smart-search config set ZHIPU_API_KEY ...` only for explicit legacy Zhipu compatibility. Do not set it up for default workflows.
 - Use `smart-search setup --non-interactive --jina-key "key"` to let Jina satisfy `web_fetch`; `JINA_RESPOND_WITH=readerlm-v2` also requires `JINA_API_KEY`.
 - Use `smart-search setup --non-interactive --openai-compatible-stream true` only when an OpenAI-compatible relay benefits from SSE streaming for long requests. Default is true.
-- Interactive setup does not ask for Zhipu by default.
 - Use `TAVILY_API_URL=https://<host>/api/tavily` for Tavily Hikari / pooled endpoints. Root host and `/mcp` inputs are normalized by setup; `/mcp` itself is not the REST base Smart Search should call.
 - `TAVILY_TIMEOUT_SECONDS` controls the Tavily `doctor` connectivity timeout and defaults to `30`. Raise it for slower pooled/community Tavily endpoints before judging the provider unhealthy.
 - Use `FIRECRAWL_API_URL` only for a Firecrawl-compatible REST base. Official default is `https://api.firecrawl.dev/v2`.
@@ -311,11 +305,11 @@ smart-search config set OPENAI_COMPATIBLE_API_URL "https://api.openai.com/v1" --
 smart-search config set OPENAI_COMPATIBLE_API_KEY "key" --format json
 smart-search config set OPENAI_COMPATIBLE_MODEL "model-id" --format json
 smart-search config set OPENAI_COMPATIBLE_STREAM "true" --format json
+smart-search config set XAI_API_KEY "key" --format json
+smart-search config set XAI_MODEL "grok-4.5" --format json
+smart-search config set SMART_SEARCH_MAIN_SEARCH_ROUTE "xai-responses,openai-compatible" --format json
 smart-search config set EXA_API_KEY "key" --format json
 smart-search config set CONTEXT7_API_KEY "key" --format json
-smart-search config set ZHIPU_API_KEY "key" --format json
-smart-search config set ZHIPU_API_URL "https://open.bigmodel.cn/api" --format json
-smart-search config set ZHIPU_SEARCH_ENGINE "search_pro" --format json
 smart-search config set TAVILY_API_URL "https://api.tavily.com" --format json
 smart-search config set TAVILY_TIMEOUT_SECONDS "45" --format json
 smart-search config set FIRECRAWL_API_URL "https://api.firecrawl.dev/v2" --format json
@@ -344,6 +338,18 @@ smart-search d --format markdown
 
 When `smart-search search` returns `ok: false` with `error_type: "network_error"` and an error message containing `timed out`, treat it as a retryable CLI-level timeout, not as a terminal research failure.
 
+### Error contract (U1/U2)
+
+Failed JSON payloads expose a stable triple for Agent/JSON consumers:
+
+| Field | Meaning |
+| --- | --- |
+| `error_type` | Category enum string: `config_error`, `parameter_error`, `network_error`, `evidence_error`, `auth_error`, `rate_limited`, `timeout`, `parse_error`, `quality_error`, `runtime_error` |
+| `error_code` | Stable `SCREAMING_SNAKE` code (defaults from `error_type`, e.g. `CONFIG_ERROR`; specific codes such as `MISSING_API_KEY`, `SEARCH_TIMEOUT` when applicable) |
+| `error` | Default **English** human message (no locale framework; Chinese remains only in interactive setup prompts via existing `_t`) |
+
+CLI exit codes stay mapped from `error_type` only: `parameter_error→2`, `config_error→3`, `network_error`/`evidence_error→4`, other→`5`.
+
 1. Retry up to 3 total attempts with `--timeout 180`, waiting about 5 seconds between attempts.
 2. Use `--format json` and `--output PATH` for each attempt; after each attempt, inspect the saved JSON and stop on the first `"ok": true`.
 3. Use `--extra-sources 1` during retry attempts to keep Tavily/Firecrawl overhead small.
@@ -380,7 +386,7 @@ smart-search fetch "https://example.com/source" --format markdown --output fetch
 - Do not use legacy MCP tool names in prompts, notes, or generated instructions for this workflow.
 - Treat key rotation as a hard safety gate when previous key values were pasted into chat or logs.
 - For provider architecture maintenance, verify the distributable contract rather than the current developer machine's wrappers or local config. Keep fallback same-capability only.
-- `main_search` is OpenAI-compatible Chat Completions configured through `OPENAI_COMPATIBLE_*`. Do not fabricate a second `main_search` provider or reuse another capability's URL/key as a `main_search` fallback.
+- `main_search` is a user choice between xAI Responses (`XAI_*`) and OpenAI-compatible Chat Completions (`OPENAI_COMPATIBLE_*`). Never send xAI server tools (`web_search`, `x_search`) or xAI-only parameters into the OpenAI-compatible route, and never point the xAI route at `/chat/completions`. Do not fabricate additional `main_search` providers or reuse another capability's URL/key as a `main_search` fallback.
 
 ## Supporting Reference