@ekzs/cli 0.2.0 → 0.3.0

package/dist/index.js

@@ -3,12 +3,14 @@ import { bootstrapShellEnvironment } from "./lib/shell.js";
 import { Command } from "commander";
 bootstrapShellEnvironment();
 import { isKnownSubcommand, resolveCliSubcommand } from "./lib/commands-i18n.js";
+import { parseLocale } from "./lib/locale.js";
 import { runAgentCommand } from "./commands/agent.js";
 import { runAsk, runInteractiveAsk, resolveQuestion } from "./commands/ask.js";
 import { runDoctor } from "./commands/doctor.js";
 import { runFixCommand } from "./commands/agent.js";
 import { runHealth } from "./commands/health.js";
 import { runScan } from "./commands/scan.js";
+import { runProvidersCommand } from "./commands/providers.js";
 import { runWebhookTest } from "./commands/webhook.js";
 const SUBCOMMANDS = new Set([
     "doctor",
@@ -18,6 +20,7 @@ const SUBCOMMANDS = new Set([
     "agent",
     "fix",
     "ask",
+    "providers",
 ]);
 /** Bare `ekz` or `ekz "natural language task"` → agent. Resolves PT/zh CLI aliases. */
 function normalizeArgv(argv) {
@@ -35,7 +38,7 @@ const program = new Command();
 program
     .name("ekz")
     .description("EKZ CONNECT — e-Kwanza v2.4 coding agent by Alberto Moisés")
-    .version("0.2.0");
+    .version("0.3.0");
 program
     .command("doctor")
     .description("Validate .env and run live credential checks (free)")
@@ -78,18 +81,16 @@ program
 });
 program
     .command("agent")
-    .description("Interactive e-Kwanza agent (requires CURSOR_API_KEY for agent/plan modes)")
+    .description("Interactive e-Kwanza agent (BYOK — configure keys with `ekz providers`)")
     .argument("[task]", "Optional first task — stays interactive after (omit for REPL only)")
     .option("-C, --cwd <path>", "Project directory", process.cwd())
-    .option("--api-key <key>", "Cursor API key (or CURSOR_API_KEY env)")
+    .option("--api-key <key>", "One-off Cursor API key override (agent/plan)")
     .option("-i, --interactive", "Stay in REPL after the first task (default)", true)
     .option("--resume", "Resume last session in this repo")
     .option("--fresh", "Start a new agent session")
     .option("-m, --mode <mode>", "agent | plan | ask (default: agent)")
     .option("--plan", "Shorthand for --mode plan")
     .option("-l, --lang <code>", "Response language: pt (default), en, or zh")
-    .option("--ask-api-key <key>", "EKZ_AGENT_API_KEY for ask mode")
-    .option("--ask-api-url <url>", "Ekz Connect base URL for ask mode")
     .option("--offline", "Ask mode: offline answers only")
     .action(async (task, opts) => {
     try {
@@ -97,8 +98,6 @@ program
             cwd: opts.cwd,
             question: task,
             apiKey: opts.apiKey,
-            askApiKey: opts.askApiKey,
-            askApiUrl: opts.askApiUrl,
             askOffline: opts.offline,
             interactive: opts.interactive,
             resume: opts.resume,
@@ -118,15 +117,13 @@ program
     .description("Auto-audit and fix e-Kwanza integration in your repo")
     .argument("[hint]", "Optional extra context")
     .option("-C, --cwd <path>", "Project directory", process.cwd())
-    .option("--api-key <key>", "Cursor API key (or CURSOR_API_KEY env)")
+    .option("--api-key <key>", "One-off Cursor API key override (agent/plan)")
     .option("-i, --interactive", "Stay in REPL after fix pass (default)", true)
     .option("--resume", "Resume last session")
     .option("--fresh", "Start a new agent session")
     .option("-m, --mode <mode>", "agent | plan | ask (default: agent)")
     .option("--plan", "Shorthand for --mode plan")
     .option("-l, --lang <code>", "Response language: pt (default), en, or zh")
-    .option("--ask-api-key <key>", "EKZ_AGENT_API_KEY for ask mode")
-    .option("--ask-api-url <url>", "Ekz Connect base URL for ask mode")
     .option("--offline", "Ask mode: offline answers only")
     .action(async (hint, opts) => {
     try {
@@ -137,14 +134,27 @@ program
         process.exitCode = 1;
     }
 });
+program
+    .command("providers")
+    .alias("provedores")
+    .alias("fornecedores")
+    .description("Configure LLM API keys (BYOK) — stored in ~/.ekz/providers.json")
+    .option("-l, --lang <code>", "Menu language: pt (default), en, or zh")
+    .action(async (opts) => {
+    try {
+        await runProvidersCommand({ locale: opts.lang });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+    }
+});
 program
     .command("ask")
-    .description("Remote Q&A via Ekz Connect API — no local file edits")
+    .description("BYOK Q&A — no local file edits (configure keys with `ekz providers`)")
     .argument("[question]", "Your question")
     .option("-C, --cwd <path>", "Project directory", process.cwd())
-    .option("--api-key <key>", "EKZ_AGENT_API_KEY")
-    .option("--api-url <url>", "Ekz Connect base URL")
-    .option("--offline", "Deterministic answer without API")
+    .option("--offline", "Deterministic answer without LLM")
     .option("-i, --interactive", "Stay in ask REPL after the first question", false)
     .option("-l, --lang <code>", "Response language: pt (default), en, or zh")
     .action(async (question, opts) => {
@@ -152,8 +162,6 @@ program
         if (opts.interactive && !question?.trim()) {
             await runInteractiveAsk({
                 cwd: opts.cwd,
-                apiKey: opts.apiKey,
-                apiUrl: opts.apiUrl,
                 offline: opts.offline,
                 locale: opts.lang,
             });
@@ -163,15 +171,12 @@ program
         await runAsk({
             cwd: opts.cwd,
             question: q,
-            apiKey: opts.apiKey,
-            apiUrl: opts.apiUrl,
             offline: opts.offline,
+            locale: parseLocale(opts.lang) ?? "pt",
         });
         if (opts.interactive) {
             await runInteractiveAsk({
                 cwd: opts.cwd,
-                apiKey: opts.apiKey,
-                apiUrl: opts.apiUrl,
                 offline: opts.offline,
                 locale: opts.lang,
             });

package/dist/lib/commands-i18n.d.ts

@@ -1,5 +1,14 @@
 import type { EkzLocale } from "./locale.js";
-export type CliCommandId = "doctor" | "health" | "scan" | "webhook" | "agent" | "fix" | "ask";
+export type ProvidersCommandLabels = {
+    cli: string;
+    repl: string;
+    cliAliases: string[];
+    replAliases: string[];
+};
+export declare function providersCommandLabels(locale: EkzLocale): ProvidersCommandLabels;
+export declare function providersSetupHint(locale: EkzLocale): string;
+export declare function isProvidersMetaCommand(token: string): boolean;
+export type CliCommandId = "doctor" | "health" | "scan" | "webhook" | "agent" | "fix" | "ask" | "providers";
 export declare function resolveCliSubcommand(token: string): string;
 export declare function isKnownSubcommand(token: string): boolean;
 export declare const SPLASH_TOOLS: Record<EkzLocale, Array<{
@@ -10,6 +19,8 @@ export declare function formatSplashTool(locale: EkzLocale, tool: {
     label: string;
     hint?: string;
 }): string;
+/** One-line summary of all CLI tools for help text. */
+export declare function formatCliToolsSummary(locale: EkzLocale): string;
 export declare function splashSessionLines(locale: EkzLocale): string[];
 export declare function splashHelpHint(locale: EkzLocale): string;
 export declare function welcomeMessage(locale: EkzLocale, name: string, resumed: boolean): string;

package/dist/lib/commands-i18n.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands-i18n.d.ts","sourceRoot":"","sources":["../../src/lib/commands-i18n.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,SAAS,GACT,OAAO,GACP,KAAK,GACL,KAAK,CAAC;AA0CV,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK1D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED,eAAO,MAAM,YAAY,EAAE,MAAM,CAC/B,SAAS,EACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA6BxC,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAGlG;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,EAAE,CAkB9D;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAIxD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAQxF;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,CAMvF;AAED,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAyBpD,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI5D"}
+{"version":3,"file":"commands-i18n.d.ts","sourceRoot":"","sources":["../../src/lib/commands-i18n.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,MAAM,sBAAsB,GAAG;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,sBAAsB,CAuBhF;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAS5D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,SAAS,GACT,OAAO,GACP,KAAK,GACL,KAAK,GACL,WAAW,CAAC;AAoDhB,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK1D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED,eAAO,MAAM,YAAY,EAAE,MAAM,CAC/B,SAAS,EACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgCxC,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAGlG;AAED,uDAAuD;AACvD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAE/D;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,EAAE,CAU9D;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAIxD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAQxF;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,CAMvF;AAED,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkCpD,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI5D"}

package/dist/lib/commands-i18n.js

@@ -1,3 +1,40 @@
+export function providersCommandLabels(locale) {
+    if (locale === "pt") {
+        return {
+            cli: "ekz provedores",
+            repl: "/provedores",
+            cliAliases: ["fornecedores", "providers", "chaves"],
+            replAliases: ["/fornecedores", "/providers", "/chaves"],
+        };
+    }
+    if (locale === "zh") {
+        return {
+            cli: "ekz 供应商",
+            repl: "/供应商",
+            cliAliases: ["providers", "提供商", "模型"],
+            replAliases: ["/providers", "/提供商", "/模型"],
+        };
+    }
+    return {
+        cli: "ekz providers",
+        repl: "/providers",
+        cliAliases: ["provider"],
+        replAliases: ["/provider"],
+    };
+}
+export function providersSetupHint(locale) {
+    const labels = providersCommandLabels(locale);
+    if (locale === "pt") {
+        return `Nenhum provider activo. Corre \`${labels.cli}\` ou \`${labels.repl}\` e cola a tua API key.`;
+    }
+    if (locale === "zh") {
+        return `未配置 provider。运行 \`${labels.cli}\` 或 \`${labels.repl}\` 并粘贴 API key。`;
+    }
+    return `No active provider. Run \`${labels.cli}\` or \`${labels.repl}\` and paste your API key.`;
+}
+export function isProvidersMetaCommand(token) {
+    return resolveReplMetaCommand(token) === "providers";
+}
 const EN_SUBCOMMANDS = new Set([
     "doctor",
     "health",
@@ -6,6 +43,7 @@ const EN_SUBCOMMANDS = new Set([
     "agent",
     "fix",
     "ask",
+    "providers",
 ]);
 /** Map localized CLI tokens (and English) to canonical subcommand ids. */
 const CLI_ALIASES = {
@@ -29,6 +67,15 @@ const CLI_ALIASES = {
     ask: "ask",
     perguntar: "ask",
     pergunta: "ask",
+    providers: "providers",
+    provider: "providers",
+    fornecedores: "providers",
+    provedores: "providers",
+    chaves: "providers",
+    modelos: "providers",
+    供应商: "providers",
+    提供商: "providers",
+    模型: "providers",
     诊断: "doctor",
     凭证: "health",
     扫描: "scan",
@@ -56,6 +103,7 @@ export const SPLASH_TOOLS = {
         { label: "corrigir", hint: "fix" },
         { label: "agente", hint: "agent" },
         { label: "perguntar", hint: "ask" },
+        { label: "provedores", hint: "BYOK" },
     ],
     en: [
         { label: "doctor" },
@@ -65,6 +113,7 @@ export const SPLASH_TOOLS = {
         { label: "fix" },
         { label: "agent" },
         { label: "ask" },
+        { label: "providers", hint: "BYOK" },
     ],
     zh: [
         { label: "诊断", hint: "doctor" },
@@ -74,31 +123,28 @@ export const SPLASH_TOOLS = {
         { label: "修复", hint: "fix" },
         { label: "代理", hint: "agent" },
         { label: "问答", hint: "ask" },
+        { label: "供应商", hint: "BYOK" },
     ],
 };
 export function formatSplashTool(locale, tool) {
-    if (!tool.hint || locale === "en")
+    if (!tool.hint)
         return tool.label;
     return `${tool.label} · ${tool.hint}`;
 }
+/** One-line summary of all CLI tools for help text. */
+export function formatCliToolsSummary(locale) {
+    return SPLASH_TOOLS[locale].map((t) => `ekz ${formatSplashTool(locale, t)}`).join(" · ");
+}
 export function splashSessionLines(locale) {
+    const p = providersCommandLabels(locale);
+    const providersLine = `${p.repl} · ${p.cli}`;
     if (locale === "pt") {
-        return [
-            "/guardar <nome>",
-            "/retomar · /retomar 2",
-            "ekz --resume",
-            "ekz --fresh",
-        ];
+        return [providersLine, "/guardar <nome>", "/retomar · /retomar 2", "ekz --resume", "ekz --fresh"];
     }
     if (locale === "zh") {
-        return [
-            "/保存 <名称>",
-            "/恢复 · /恢复 2",
-            "ekz --resume",
-            "ekz --fresh",
-        ];
+        return [providersLine, "/保存 <名称>", "/恢复 · /恢复 2", "ekz --resume", "ekz --fresh"];
     }
-    return ["/save <name>", "/resume · /resume 2", "ekz --resume", "ekz --fresh"];
+    return [providersLine, "/save <name>", "/resume · /resume 2", "ekz --resume", "ekz --fresh"];
 }
 export function splashHelpHint(locale) {
     if (locale === "pt")
@@ -149,6 +195,15 @@ export const REPL_META_ALIASES = {
     save: "save",
     guardar: "save",
     保存: "save",
+    providers: "providers",
+    provider: "providers",
+    fornecedores: "providers",
+    provedores: "providers",
+    chaves: "providers",
+    modelos: "providers",
+    供应商: "providers",
+    提供商: "providers",
+    模型: "providers",
 };
 export function resolveReplMetaCommand(token) {
     const raw = token.trim().toLowerCase().replace(/^\//, "");

package/dist/lib/composer-model.d.ts

@@ -6,5 +6,5 @@ export type ComposerModelSelection = {
     }>;
     label: string;
 };
-export declare function resolveComposerModel(env?: NodeJS.ProcessEnv): ComposerModelSelection;
+export declare function resolveComposerModel(env?: NodeJS.ProcessEnv, modelOverride?: string): ComposerModelSelection;
 //# sourceMappingURL=composer-model.d.ts.map

package/dist/lib/composer-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composer-model.d.ts","sourceRoot":"","sources":["../../src/lib/composer-model.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9C,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,sBAAsB,CAkBjG"}
+{"version":3,"file":"composer-model.d.ts","sourceRoot":"","sources":["../../src/lib/composer-model.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAAG;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9C,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,aAAa,CAAC,EAAE,MAAM,GACrB,sBAAsB,CAkBxB"}

package/dist/lib/composer-model.js

@@ -1,5 +1,5 @@
-export function resolveComposerModel(env = process.env) {
-    const raw = env.EKZ_AGENT_MODEL?.trim() || "composer-2.5-fast";
+export function resolveComposerModel(env = process.env, modelOverride) {
+    const raw = modelOverride?.trim() || env.EKZ_AGENT_MODEL?.trim() || "composer-2.5-fast";
     const wantFast = raw.endsWith("-fast") ||
         env.EKZ_AGENT_FAST === "true" ||
         (env.EKZ_AGENT_FAST !== "false" && raw === "composer-2.5-fast");

package/dist/lib/help.js

@@ -1,4 +1,4 @@
-import { SPLASH_TOOLS } from "./commands-i18n.js";
+import { formatCliToolsSummary, providersCommandLabels } from "./commands-i18n.js";
 import { MODE_LABELS } from "./mode.js";
 import { c, muted } from "./theme.js";
 function sectionTitle(locale, key) {
@@ -39,9 +39,11 @@ export function buildHelpSections(locale, currentMode) {
                 modeLine("ask"),
                 currentMode ? `Current mode: ${currentMode}` : "",
             ].filter(Boolean);
+    const p = providersCommandLabels(locale);
     const repl = locale === "pt"
         ? [
             "Escreve perguntas ou tarefas em linguagem natural.",
+            `${p.repl} · ${p.cli} (BYOK)`,
             "/ajuda · /help",
             "/modo agente|plan|ask · /mode agent|plan|ask",
             "/idioma pt · /lang pt|en|zh",
@@ -52,6 +54,7 @@ export function buildHelpSections(locale, currentMode) {
         : locale === "zh"
             ? [
                 "用自然语言提问或描述任务。",
+                `${p.repl} · ${p.cli} (BYOK)`,
                 "/帮助 · /help · /ajuda",
                 "/模式 代理|plan|ask · /mode agent|plan|ask",
                 "/语言 pt · /lang pt|en|zh",
@@ -61,6 +64,7 @@ export function buildHelpSections(locale, currentMode) {
             ]
             : [
                 "Type questions or tasks in natural language.",
+                `${p.repl} · ${p.cli} (BYOK)`,
                 "/help · /ajuda · /帮助",
                 "/mode agent|plan|ask",
                 "/lang pt · /lang en · /lang zh",
@@ -68,15 +72,11 @@ export function buildHelpSections(locale, currentMode) {
                 "/doctor · /scan (quick diagnostics)",
                 "exit · quit · sair",
             ];
-    const cliTools = locale === "pt"
-        ? SPLASH_TOOLS.pt.map((t) => `ekz ${t.label} (${t.hint ?? t.label})`).join(" · ")
-        : locale === "zh"
-            ? SPLASH_TOOLS.zh.map((t) => `ekz ${t.label} (${t.hint ?? t.label})`).join(" · ")
-            : "ekz doctor · ekz health · ekz scan · ekz webhook · ekz fix · ekz agent · ekz ask";
+    const cliTools = formatCliToolsSummary(locale);
     const cli = locale === "pt"
         ? [
             "ekz · ekz agente [tarefa] · ekz corrigir [dica]",
-            "ekz perguntar [pergunta] · ekz diagnóstico · ekz credenciais",
+            "ekz perguntar [pergunta] · ekz provedores · ekz diagnóstico",
             "ekz analisar · ekz webhook <url>",
             "ekz --modo agente|plan|ask (ou --mode)",
             cliTools,
@@ -84,33 +84,34 @@ export function buildHelpSections(locale, currentMode) {
         : locale === "zh"
             ? [
                 "ekz · ekz 代理 [任务] · ekz 修复 [提示]",
-                "ekz 问答 [问题] · ekz 诊断 · ekz 凭证",
+                "ekz 问答 [问题] · ekz 供应商 · ekz 诊断",
                 "ekz 扫描 · ekz webhook <url>",
                 "ekz --mode 代理|plan|ask (或 --plan)",
                 cliTools,
             ]
             : [
                 "ekz · ekz agent [task] · ekz fix [hint]",
-                "ekz ask [question] · ekz doctor · ekz health",
+                "ekz ask [question] · ekz providers · ekz doctor",
                 "ekz scan · ekz webhook <url>",
                 "ekz --mode agent|plan|ask",
+                cliTools,
             ];
     const flags = locale === "pt"
         ? [
             "--mode agent|plan|ask · --plan (atalho para plan)",
             "--resume · --fresh · --lang pt|en|zh",
-            "-C, --cwd <path> · --api-key <chave>",
+            "-C, --cwd <path> · --api-key <key> (Cursor one-off override)",
         ]
         : locale === "zh"
             ? [
                 "--mode agent|plan|ask · --plan (plan 快捷方式)",
                 "--resume · --fresh · --lang pt|en|zh",
-                "-C, --cwd <path> · --api-key <key>",
+                "-C, --cwd <path> · --api-key <key> (Cursor one-off override)",
             ]
             : [
                 "--mode agent|plan|ask · --plan (shorthand for plan)",
                 "--resume · --fresh · --lang pt|en|zh",
-                "-C, --cwd <path> · --api-key <key>",
+                "-C, --cwd <path> · --api-key <key> (Cursor one-off override)",
             ];
     const scope = locale === "pt"
         ? ["Só integração e-Kwanza v2.4. Outras áreas do repo são só leitura."]

package/dist/lib/providers/agent-runner.d.ts

@@ -0,0 +1,12 @@
+import { type EkzLocale } from "../locale.js";
+import { type EkzMode } from "../mode.js";
+import { type ResolvedCredentials } from "./credentials.js";
+export declare function runByokAgentTurn(options: {
+    cwd: string;
+    task: string;
+    creds: ResolvedCredentials;
+    locale: EkzLocale;
+    mode: EkzMode;
+}): Promise<boolean>;
+export declare function usesCursorSdk(creds: ResolvedCredentials): boolean;
+//# sourceMappingURL=agent-runner.d.ts.map

package/dist/lib/providers/agent-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runner.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/agent-runner.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AA+L5D,wBAAsB,gBAAgB,CAAC,OAAO,EAAE;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,mBAAmB,CAAC;IAC3B,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,OAAO,CAAC,CAgCnB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAEjE"}

package/dist/lib/providers/agent-runner.js

@@ -0,0 +1,167 @@
+import { resolve } from "path";
+import { buildAgentPrompt, buildBootstrapContext } from "../context.js";
+import { fail } from "../output.js";
+import { toolDone, toolError, toolRunning } from "../theme.js";
+import { AGENT_TOOL_DEFINITIONS, executeAgentTool } from "./tools.js";
+const MAX_TOOL_ROUNDS = 24;
+function planInstruction(mode) {
+    if (mode === "plan") {
+        return "You are in **plan mode**: output a clear numbered plan first. Only call write_file after the plan is clear.";
+    }
+    if (mode === "ask") {
+        return "You are in **ask mode**: answer only. Do not call write_file or run_command.";
+    }
+    return "You are in **agent mode**: use tools to inspect and fix the e-Kwanza integration.";
+}
+async function openAiAgentLoop(creds, cwd, messages, enableTools) {
+    const base = (creds.baseUrl ?? "https://api.openai.com/v1").replace(/\/$/, "");
+    const url = base.endsWith("/chat/completions") ? base : `${base}/chat/completions`;
+    for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+        const headers = { "Content-Type": "application/json" };
+        if (creds.apiKey && creds.apiKey !== "ollama") {
+            headers.Authorization = `Bearer ${creds.apiKey}`;
+        }
+        const body = {
+            model: creds.model,
+            messages,
+            temperature: 0.2,
+        };
+        if (enableTools)
+            body.tools = AGENT_TOOL_DEFINITIONS;
+        const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
+        const data = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            throw new Error(data.error?.message ?? `Provider error (${res.status})`);
+        const message = data.choices?.[0]?.message;
+        if (!message)
+            throw new Error("Empty response from provider.");
+        const toolCalls = message.tool_calls ?? [];
+        if (!toolCalls.length) {
+            const text = message.content?.trim();
+            if (!text)
+                throw new Error("Empty response from provider.");
+            return text;
+        }
+        messages.push({
+            role: "assistant",
+            content: message.content ?? null,
+            tool_calls: toolCalls,
+        });
+        for (const call of toolCalls) {
+            process.stdout.write(toolRunning(call.function.name));
+            let args = {};
+            try {
+                args = JSON.parse(call.function.arguments || "{}");
+            }
+            catch {
+                args = {};
+            }
+            try {
+                const result = await executeAgentTool(cwd, call.function.name, args);
+                process.stdout.write(toolDone(call.function.name));
+                messages.push({ role: "tool", tool_call_id: call.id, content: result });
+            }
+            catch (err) {
+                process.stdout.write(toolError(call.function.name));
+                messages.push({
+                    role: "tool",
+                    tool_call_id: call.id,
+                    content: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    throw new Error("Tool loop exceeded maximum rounds.");
+}
+async function anthropicAgentLoop(creds, cwd, system, messages, enableTools) {
+    const tools = enableTools
+        ? AGENT_TOOL_DEFINITIONS.map((t) => ({
+            name: t.function.name,
+            description: t.function.description,
+            input_schema: t.function.parameters,
+        }))
+        : undefined;
+    for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+        const res = await fetch("https://api.anthropic.com/v1/messages", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": creds.apiKey,
+                "anthropic-version": "2023-06-01",
+            },
+            body: JSON.stringify({
+                model: creds.model,
+                max_tokens: 8192,
+                system,
+                messages,
+                ...(tools ? { tools } : {}),
+            }),
+        });
+        const data = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            throw new Error(data.error?.message ?? `Anthropic error (${res.status})`);
+        const blocks = data.content ?? [];
+        const textParts = blocks.filter((b) => b.type === "text").map((b) => b.text ?? "");
+        const toolUses = blocks.filter((b) => b.type === "tool_use");
+        messages.push({ role: "assistant", content: blocks });
+        if (!toolUses.length || data.stop_reason === "end_turn") {
+            const text = textParts.join("").trim();
+            if (!text && !toolUses.length)
+                throw new Error("Empty response from Anthropic.");
+            if (text)
+                return text;
+        }
+        if (!toolUses.length) {
+            return textParts.join("").trim() || "(done)";
+        }
+        const toolResults = [];
+        for (const tool of toolUses) {
+            const name = tool.name ?? "unknown";
+            process.stdout.write(toolRunning(name));
+            try {
+                const result = await executeAgentTool(cwd, name, tool.input ?? {});
+                process.stdout.write(toolDone(name));
+                toolResults.push({ type: "tool_result", tool_use_id: tool.id ?? name, content: result });
+            }
+            catch (err) {
+                process.stdout.write(toolError(name));
+                toolResults.push({
+                    type: "tool_result",
+                    tool_use_id: tool.id ?? name,
+                    content: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        messages.push({ role: "user", content: toolResults });
+    }
+    throw new Error("Tool loop exceeded maximum rounds.");
+}
+export async function runByokAgentTurn(options) {
+    const cwd = resolve(options.cwd);
+    const ctx = await buildBootstrapContext(cwd);
+    const prompt = buildAgentPrompt(options.task, ctx, options.locale);
+    const system = `${planInstruction(options.mode)}\n\n${prompt.split("## Task")[0] ?? prompt}`;
+    const userTask = `## Task\n${options.task}`;
+    const enableTools = options.mode !== "ask";
+    try {
+        if (options.creds.definition.kind === "anthropic") {
+            const text = await anthropicAgentLoop(options.creds, cwd, system, [{ role: "user", content: userTask }], enableTools);
+            console.log("\n" + text);
+            return true;
+        }
+        const messages = [
+            { role: "system", content: system },
+            { role: "user", content: userTask },
+        ];
+        const text = await openAiAgentLoop(options.creds, cwd, messages, enableTools);
+        console.log("\n" + text);
+        return true;
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+        return false;
+    }
+}
+export function usesCursorSdk(creds) {
+    return creds.definition.kind === "cursor";
+}

package/dist/lib/providers/catalog.d.ts

@@ -0,0 +1,15 @@
+export type ProviderKind = "cursor" | "openai-compatible" | "anthropic";
+export type ProviderId = "cursor" | "openai" | "anthropic" | "deepseek" | "kimi" | "groq" | "mistral" | "google" | "ollama";
+export type ProviderDefinition = {
+    id: ProviderId;
+    name: string;
+    kind: ProviderKind;
+    description: string;
+    defaultModel: string;
+    defaultBaseUrl?: string;
+    keyHint: string;
+    docsUrl: string;
+};
+export declare const PROVIDER_CATALOG: ProviderDefinition[];
+export declare function getProviderDefinition(id: string): ProviderDefinition | undefined;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/lib/providers/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/lib/providers/catalog.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,mBAAmB,GAAG,WAAW,CAAC;AAExE,MAAM,MAAM,UAAU,GAClB,QAAQ,GACR,QAAQ,GACR,WAAW,GACX,UAAU,GACV,MAAM,GACN,MAAM,GACN,SAAS,GACT,QAAQ,GACR,QAAQ,CAAC;AAEb,MAAM,MAAM,kBAAkB,GAAG;IAC/B,EAAE,EAAE,UAAU,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,kBAAkB,EAyFhD,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAEhF"}