@evident-ai/cli 3.1.1-dev.14c6359 → 3.1.1-dev.186f6ef

package/README.md

@@ -85,6 +85,7 @@ Options:
 
 - `-a, --agent [id]` — Runner ID to connect to. Optional when `EVIDENT_AGENT_KEY`
   is set (the runner is then resolved automatically from the key).
+- `--runner [id]` — Alias for `--agent` (preferred name; wins if both are given).
 - `-p, --port <port>` — OpenCode port (default: `4096`).
 - `--log-level <level>` — Log verbosity: `debug | info | warn | error` (default:
   `info`). Env: `EVIDENT_LOG_LEVEL`.
@@ -105,15 +106,18 @@ targets the **production** Evident platform by default.
 
 ## Environment variables
 
-- `EVIDENT_AGENT_KEY` — A runner key. When set, `evident run` authenticates as
-  that runner and resolves the runner ID automatically, so `--agent` is not
-  required. Ideal for CI/CD.
+- `EVIDENT_RUNNER_KEY` — A runner key. When set, `evident run` authenticates as
+  that runner and resolves the runner ID automatically, so `--runner`/`--agent`
+  is not required. Ideal for CI/CD. Preferred name; wins over `EVIDENT_AGENT_KEY`
+  if both are set.
+- `EVIDENT_AGENT_KEY` — Alias for `EVIDENT_RUNNER_KEY` (still fully supported).
 - `EVIDENT_TOKEN` — A user token used for authentication (alternative to a
   keychain login from `evident login`).
 - `EVIDENT_API_URL` — Override the API base URL (equivalent to `--endpoint`).
 - `EVIDENT_TUNNEL_URL` — Override the tunnel relay URL (equivalent to `--tunnel`).
 
-Authentication precedence for `run`: `EVIDENT_AGENT_KEY` → `EVIDENT_TOKEN` →
+Authentication precedence for `run`: `EVIDENT_RUNNER_KEY`/`EVIDENT_AGENT_KEY`
+(tied; `EVIDENT_RUNNER_KEY` wins if both are set) → `EVIDENT_TOKEN` →
 credentials stored by `evident login`. For the URL flags, an explicit
 `--endpoint` / `--tunnel` flag wins over the matching environment variable, which
 in turn overrides the production default.
@@ -150,6 +154,8 @@ For CI or unattended use, set `EVIDENT_AGENT_KEY` and omit `--agent`:
 EVIDENT_AGENT_KEY=<agent-key> evident run --idle-timeout 30
 ```
 
+(`EVIDENT_RUNNER_KEY` is equivalent and the preferred name — use whichever you like.)
+
 ## How it works
 
 ```

package/dist/index.js

@@ -645,14 +645,27 @@ var EventTypes = {
   // CLI lifecycle
   CLI_STARTED: "cli.started",
   CLI_COMMAND: "cli.command",
-  CLI_ERROR: "cli.error"
+  CLI_ERROR: "cli.error",
+  // Deprecation telemetry (#412) — usage of the old `--agent`/`EVIDENT_AGENT_KEY`
+  // names instead of the preferred `--runner`/`EVIDENT_RUNNER_KEY` (#409).
+  DEPRECATED_AGENT_FLAG_USED: "cli.deprecated_agent_flag_used",
+  DEPRECATED_AGENT_KEY_ENV_USED: "cli.deprecated_agent_key_env_used"
 };
 
 // src/lib/auth.ts
 async function getAuthCredentials() {
+  const runnerKey = process.env.EVIDENT_RUNNER_KEY;
   const agentKey = process.env.EVIDENT_AGENT_KEY;
+  if (runnerKey) {
+    return {
+      token: runnerKey,
+      authType: "agent_key",
+      keySource: "runner_key",
+      notice: agentKey ? "Both EVIDENT_RUNNER_KEY and EVIDENT_AGENT_KEY are set; using EVIDENT_RUNNER_KEY." : void 0
+    };
+  }
   if (agentKey) {
-    return { token: agentKey, authType: "agent_key" };
+    return { token: agentKey, authType: "agent_key", keySource: "agent_key" };
   }
   const userToken = process.env.EVIDENT_TOKEN;
   if (userToken) {
@@ -2511,7 +2524,7 @@ var ChannelDriver = class {
   }
   /**
    * Fetch ONE inbound image's bytes through Evident's WI-6 endpoint
-   * (`GET {apiUrl}/agents/{agentId}/attachments/{messageId}/{index}`) using the
+   * (`GET {apiUrl}/runners/{agentId}/attachments/{messageId}/{index}`) using the
    * existing authenticated fetch, and base64-encode into a
    * `data:<mime>;base64,<…>` URL for the opencode `file` part's `url`.
    *
@@ -2524,7 +2537,7 @@ var ChannelDriver = class {
   async fetchAttachmentDataUrl(messageId, index, mime) {
     try {
       const res = await this.fetchImpl(
-        `${this.apiUrl}/agents/${this.agentId}/attachments/${messageId}/${index}`,
+        `${this.apiUrl}/runners/${this.agentId}/attachments/${messageId}/${index}`,
         { headers: { Authorization: this.getAuthHeader() } }
       );
       if (!res.ok) {
@@ -3790,7 +3803,7 @@ var ChannelDriver = class {
   // Evident API calls (combinedAuth thread routes)
   async getPendingConversations() {
     const res = await this.fetchImpl(
-      `${this.apiUrl}/agents/${this.agentId}/conversations/pending`,
+      `${this.apiUrl}/runners/${this.agentId}/conversations/pending`,
       {
         headers: { Authorization: this.getAuthHeader() }
       }
@@ -3808,7 +3821,7 @@ var ChannelDriver = class {
   }
   async getPendingMessages(conversationId) {
     const res = await this.fetchImpl(
-      `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/messages?status=pending`,
+      `${this.apiUrl}/runners/${this.agentId}/threads/${conversationId}/messages?status=pending`,
       { headers: { Authorization: this.getAuthHeader() } }
     );
     this.assertAuth(res, "fetching pending messages");
@@ -3832,7 +3845,7 @@ var ChannelDriver = class {
    */
   async getProcessingMessages() {
     const res = await this.fetchImpl(
-      `${this.apiUrl}/agents/${this.agentId}/conversations/processing`,
+      `${this.apiUrl}/runners/${this.agentId}/conversations/processing`,
       { headers: { Authorization: this.getAuthHeader() } }
     );
     this.assertAuth(res, "fetching processing messages");
@@ -3869,7 +3882,7 @@ var ChannelDriver = class {
    */
   async markProcessing(conversationId, messageId, sessionId, opencodeMessageId, title) {
     const res = await this.fetchImpl(
-      `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
+      `${this.apiUrl}/runners/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
       {
         method: "PATCH",
         headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
@@ -3918,7 +3931,7 @@ var ChannelDriver = class {
    */
   async markDone(conversationId, messageId, sessionId, opencodeMessageId, title, usage) {
     const res = await this.fetchImpl(
-      `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
+      `${this.apiUrl}/runners/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
       {
         method: "PATCH",
         headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
@@ -3953,7 +3966,7 @@ var ChannelDriver = class {
     await this.callWithRetry(
       "marking message as failed",
       () => this.fetchImpl(
-        `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
+        `${this.apiUrl}/runners/${this.agentId}/threads/${conversationId}/messages/${messageId}`,
         {
           method: "PATCH",
           headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
@@ -3980,7 +3993,7 @@ var ChannelDriver = class {
   async postSignal(conversationId, messageId, signal, extra) {
     try {
       const res = await this.fetchImpl(
-        `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/messages/${messageId}/signal`,
+        `${this.apiUrl}/runners/${this.agentId}/threads/${conversationId}/messages/${messageId}/signal`,
         {
           method: "POST",
           headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
@@ -4009,7 +4022,7 @@ var ChannelDriver = class {
   }
   async persistSession(conversationId, sessionId) {
     const res = await this.fetchImpl(
-      `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}`,
+      `${this.apiUrl}/runners/${this.agentId}/threads/${conversationId}`,
       {
         method: "PATCH",
         headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
@@ -4035,7 +4048,7 @@ var ChannelDriver = class {
       await this.callWithRetry(
         "reporting interactive event",
         () => this.fetchImpl(
-          `${this.apiUrl}/agents/${this.agentId}/threads/${conversationId}/interactive-event`,
+          `${this.apiUrl}/runners/${this.agentId}/threads/${conversationId}/interactive-event`,
           {
             method: "POST",
             headers: { Authorization: this.getAuthHeader(), "Content-Type": "application/json" },
@@ -4278,7 +4291,7 @@ async function resolveAgentIdFromKey(authHeader) {
 async function notifyAgentDisconnected(agentId, authHeader) {
   const apiUrl = getApiUrlConfig();
   try {
-    const response = await fetch(`${apiUrl}/agents/${agentId}/disconnect`, {
+    const response = await fetch(`${apiUrl}/runners/${agentId}/disconnect`, {
       method: "POST",
       headers: { Authorization: authHeader }
     });
@@ -4297,7 +4310,7 @@ async function notifyAgentDisconnected(agentId, authHeader) {
 async function getAgentInfo(agentId, authHeader) {
   const apiUrl = getApiUrlConfig();
   try {
-    const response = await fetch(`${apiUrl}/agents/${agentId}`, {
+    const response = await fetch(`${apiUrl}/runners/${agentId}`, {
       headers: { Authorization: authHeader }
     });
     if (response.status === 401) {
@@ -4684,7 +4697,7 @@ async function run(options) {
     return;
   }
   const state = {
-    agentId: options.agent || "",
+    agentId: options.runner || options.agent || "",
     agentName: null,
     port: options.port ?? 4096,
     conversationFilter: options.conversation ?? null,
@@ -4706,6 +4719,14 @@ async function run(options) {
     sessionCleanupTimers: [],
     authHeader: ""
   };
+  if (!options.runner && options.agent) {
+    telemetry.info(
+      EventTypes.DEPRECATED_AGENT_FLAG_USED,
+      "Deprecated --agent flag used instead of --runner",
+      { command: "run" },
+      state.agentId
+    );
+  }
   if (state.idleTimeout === null && (process.env.GITHUB_ACTIONS || process.env.CI)) {
     log2(
       state,
@@ -4734,7 +4755,9 @@ async function run(options) {
       if (!interactive) {
         printError("Authentication required");
         blank();
-        console.log(chalk6.dim("Set EVIDENT_AGENT_KEY environment variable for CI"));
+        console.log(
+          chalk6.dim("Set EVIDENT_RUNNER_KEY (or EVIDENT_AGENT_KEY) environment variable for CI")
+        );
         console.log(chalk6.dim("Or run `evident login` for interactive authentication"));
         blank();
         process.exit(1);
@@ -4748,6 +4771,20 @@ async function run(options) {
       );
     }
     state.authHeader = getAuthHeader(credentials2);
+    if (credentials2.notice) {
+      log2(state, credentials2.notice, "warn");
+      if (state.interactive && !state.json) {
+        logActivity(state, { type: "info", level: "warn", message: credentials2.notice });
+      }
+    }
+    if (credentials2.keySource === "agent_key") {
+      telemetry.info(
+        EventTypes.DEPRECATED_AGENT_KEY_ENV_USED,
+        "Deprecated EVIDENT_AGENT_KEY env var used instead of EVIDENT_RUNNER_KEY",
+        { command: "run" },
+        state.agentId
+      );
+    }
     if (!state.agentId) {
       if (credentials2.authType === "agent_key") {
         const resolved = await resolveAgentIdFromKey(state.authHeader);
@@ -4765,9 +4802,15 @@ async function run(options) {
           process.exit(1);
         }
       } else {
-        printError("--agent is required when not using EVIDENT_AGENT_KEY");
+        printError(
+          "--runner (or --agent) is required when not using EVIDENT_RUNNER_KEY or EVIDENT_AGENT_KEY"
+        );
         blank();
-        console.log(chalk6.dim("Either provide --agent <id> or set EVIDENT_AGENT_KEY"));
+        console.log(
+          chalk6.dim(
+            "Either provide --runner/--agent <id> or set EVIDENT_RUNNER_KEY/EVIDENT_AGENT_KEY"
+          )
+        );
         blank();
         process.exit(1);
       }
@@ -4982,7 +5025,7 @@ async function run(options) {
     }
     telemetry.error(EventTypes.CLI_ERROR, `Run command failed: ${message}`, {
       command: "run",
-      agentId: options.agent
+      agentId: options.runner || options.agent
     });
     await shutdownTelemetry();
     process.exit(1);
@@ -5007,7 +5050,7 @@ program.name("evident").description("Run OpenCode locally and connect it to Evid
 program.command("login").description("Authenticate with Evident").option("--token", "Use token-based authentication (for CI/CD)").option("--no-browser", "Do not open the browser automatically").action(login);
 program.command("logout").description("Remove stored credentials for the current endpoint").option("--all", "Remove stored credentials for all endpoints").action((options) => logout({ all: options.all }));
 program.command("whoami").description("Show the currently logged in user").action(whoami);
-program.command("run").description("Connect to Evident and process messages").option("-a, --agent [id]", "Runner ID to connect to (optional when EVIDENT_AGENT_KEY is set)").option("-p, --port <port>", "OpenCode port (default: 4096)", "4096").option(
+program.command("run").description("Connect to Evident and process messages").option("-a, --agent [id]", "Runner ID to connect to (optional when EVIDENT_AGENT_KEY is set)").option("--runner [id]", "Alias for --agent (preferred name; wins if both are given)").option("-p, --port <port>", "OpenCode port (default: 4096)", "4096").option(
   "--log-level <level>",
   "Log verbosity: debug | info | warn | error (default: info). Env: EVIDENT_LOG_LEVEL"
 ).option("-v, --verbose", "Alias for --log-level debug (ignored if --log-level is set)").option("-c, --conversation <id>", "Process only this specific conversation").option("--idle-timeout <seconds>", "Exit after N seconds idle").option("--json", "Output in JSON format").option(
@@ -5023,6 +5066,7 @@ program.command("run").description("Connect to Evident and process messages").op
   (options) => {
     run({
       agent: options.agent,
+      runner: options.runner,
       port: parseInt(options.port, 10),
       // Raw string — validation/precedence is single-sourced in run.ts's
       // resolveLogLevel (flag > -v > EVIDENT_LOG_LEVEL > info).