@acnlabs/acn-cli 0.14.2 → 1.0.1

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@acnlabs/acn-cli",
-      version: "0.14.2",
+      version: "1.0.1",
       description: "Official CLI for ACN (Agent Collaboration Network) \u2014 zero-integration agent access",
       main: "dist/index.js",
       bin: {
@@ -430,7 +430,10 @@ function joinCommand() {
 // src/commands/heartbeat.ts
 var import_commander3 = require("commander");
 function heartbeatCommand() {
-  return new import_commander3.Command("heartbeat").description("Send a heartbeat to keep this agent online").option("-i, --agent-id <id>", "Agent ID (defaults to value in ~/.acn/config.json)").action(async (opts) => {
+  return new import_commander3.Command("heartbeat").description("Send a heartbeat to keep this agent online").option("-i, --agent-id <id>", "Agent ID (defaults to value in ~/.acn/config.json)").option(
+    "-m, --model <modelId>",
+    "Declare runtime model (Host Catalog id) for Host Pricing prefill \u2014 self-reported (env: ACN_PREFERRED_MODEL)"
+  ).action(async (opts) => {
     const config = loadConfig();
     const agentId = opts.agentId ?? config.agent_id;
     if (!agentId) {
@@ -438,8 +441,11 @@ function heartbeatCommand() {
       process.exit(1);
     }
     try {
-      const res = await acnPost(`/agents/${agentId}/heartbeat`);
-      output(res, `Heartbeat sent for agent ${agentId}`);
+      const model = opts.model && opts.model.trim() || process.env.ACN_PREFERRED_MODEL?.trim() || "";
+      const body = model ? { preferred_model: model.slice(0, 200) } : void 0;
+      const res = await acnPost(`/agents/${agentId}/heartbeat`, body);
+      const modelNote = res.preferred_model ? ` (preferred_model=${res.preferred_model})` : "";
+      output(res, `Heartbeat sent for agent ${agentId}${modelNote}`);
     } catch (err) {
       handleError(err);
     }
@@ -1560,7 +1566,7 @@ function validateChatWritebackOptions(opts) {
   const hasUrl = Boolean(opts.chatCompleteUrl?.trim());
   const hasExec = Boolean(opts.chatCompleteExec?.trim());
   if (hasUrl === hasExec) {
-    return '--chat-writeback requires exactly one of --chat-complete-url or --chat-complete-exec (host returns JSON {"content":"..."}).';
+    return '--chat-writeback requires exactly one of --chat-complete-url or --chat-complete-exec (host returns JSON {"content":"..."} and optional usage).';
   }
   return null;
 }
@@ -1594,6 +1600,59 @@ function extractContent(payload) {
   }
   return null;
 }
+function asNonNegInt(v) {
+  if (typeof v === "number" && Number.isFinite(v) && v >= 0) {
+    return Math.floor(v);
+  }
+  if (typeof v === "string" && v.trim() !== "") {
+    const n = Number(v);
+    if (Number.isFinite(n) && n >= 0) return Math.floor(n);
+  }
+  return null;
+}
+function extractModelId(payload) {
+  const rec = asRecord2(payload);
+  if (!rec) return void 0;
+  const usageRec = asRecord2(rec.usage);
+  for (const raw of [
+    usageRec?.model_id,
+    usageRec?.model,
+    rec.model_id,
+    rec.model
+  ]) {
+    if (typeof raw === "string" && raw.trim()) return raw.trim().slice(0, 200);
+  }
+  return void 0;
+}
+function extractUsage(payload) {
+  const rec = asRecord2(payload);
+  if (!rec) return void 0;
+  const usageRec = asRecord2(rec.usage) ?? rec;
+  const input = asNonNegInt(usageRec.input_tokens) ?? asNonNegInt(usageRec.prompt_tokens);
+  const output2 = asNonNegInt(usageRec.output_tokens) ?? asNonNegInt(usageRec.completion_tokens);
+  if (input === null && output2 === null) return void 0;
+  const out = {
+    input_tokens: input ?? 0,
+    output_tokens: output2 ?? 0
+  };
+  const ms = usageRec.meter_source;
+  if (ms === "peer_self" || ms === "gateway" || ms === "runtime_attested" || ms === "protocol") {
+    out.meter_source = ms;
+  }
+  const modelId = extractModelId(payload);
+  if (modelId) out.model_id = modelId;
+  return out;
+}
+function parseCompletePayload(payload) {
+  const content = extractContent(payload);
+  if (!content) return { ok: false, reason: "complete_missing_content" };
+  const usage = extractUsage(payload);
+  const modelId = extractModelId(payload);
+  const result = { content };
+  if (usage) result.usage = usage;
+  else if (modelId) result.modelId = modelId;
+  return { ok: true, result };
+}
 async function mintAgentJwt(opts, fetchFn = fetch) {
   const now = Math.floor(Date.now() / 1e3);
   if (cachedJwt && cachedJwt.agentId === opts.agentId && cachedJwt.expEpochSec > now + 60) {
@@ -1661,9 +1720,7 @@ async function completeViaHttp(event, opts, deps) {
     } catch {
       return { ok: false, reason: "complete_invalid_json" };
     }
-    const content = extractContent(parsed);
-    if (!content) return { ok: false, reason: "complete_missing_content" };
-    return { ok: true, content };
+    return parseCompletePayload(parsed);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (controller.signal.aborted || /abort|timeout/i.test(msg)) {
@@ -1711,12 +1768,7 @@ function completeViaExec(event, opts, deps) {
       const text = Buffer.concat(stdout).toString("utf-8").trim();
       try {
         const parsed = JSON.parse(text);
-        const content = extractContent(parsed);
-        if (!content) {
-          finish({ ok: false, reason: "complete_missing_content" });
-          return;
-        }
-        finish({ ok: true, content });
+        finish(parseCompletePayload(parsed));
       } catch {
         finish({ ok: false, reason: "complete_invalid_json" });
       }
@@ -1724,7 +1776,7 @@ function completeViaExec(event, opts, deps) {
     child.stdin?.end(body);
   });
 }
-async function postWriteback(event, content, opts, deps) {
+async function postWriteback(event, complete, opts, deps) {
   const chat = event.chat;
   if (!chat) return { ok: false, reason: "no_chat_envelope" };
   if (!isAllowedChatReplyPath(chat.chat_id, chat.reply_path)) {
@@ -1747,6 +1799,24 @@ async function postWriteback(event, content, opts, deps) {
     return { ok: false, reason: "reply_url_origin_mismatch" };
   }
   const timeoutMs = opts.writebackTimeoutMs ?? DEFAULT_WRITEBACK_TIMEOUT_MS;
+  const replyToId = chat.gateway_message_id ?? event.message_id;
+  const body = {
+    content: complete.content,
+    reply_to_id: replyToId
+  };
+  if (complete.usage) {
+    const usageBody = {
+      input_tokens: complete.usage.input_tokens,
+      output_tokens: complete.usage.output_tokens,
+      meter_source: complete.usage.meter_source ?? "peer_self"
+    };
+    if (complete.usage.model_id) {
+      usageBody.model_id = complete.usage.model_id;
+    }
+    body.usage = usageBody;
+  } else if (complete.modelId) {
+    body.usage = { model_id: complete.modelId };
+  }
   const postOnce = async (token) => {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -1757,7 +1827,7 @@ async function postWriteback(event, content, opts, deps) {
           "content-type": "application/json",
           Authorization: `Bearer ${token}`
         },
-        body: JSON.stringify({ content }),
+        body: JSON.stringify(body),
         signal: controller.signal
       });
       if (res.status === 200 || res.status === 201) {
@@ -1813,15 +1883,16 @@ async function handleChatWriteback(event, opts, deps = {}) {
     );
     return { ok: false, reason: completed.reason };
   }
-  const written = await postWriteback(event, completed.content, opts, deps);
+  const written = await postWriteback(event, completed.result, opts, deps);
   if (!written.ok) {
     logFn(
       `[acn listen] chat_writeback_failed chat_id=${event.chat.chat_id} message_id=${event.message_id} reason=${written.reason}`
     );
     return written;
   }
+  const usageNote = completed.result.usage ? ` usage_in=${completed.result.usage.input_tokens} usage_out=${completed.result.usage.output_tokens}` : "";
   logFn(
-    `[acn listen] chat_writeback_ok chat_id=${event.chat.chat_id} message_id=${event.message_id} http=${written.httpStatus}`
+    `[acn listen] chat_writeback_ok chat_id=${event.chat.chat_id} message_id=${event.message_id} http=${written.httpStatus}${usageNote}`
   );
   return written;
 }
@@ -2223,8 +2294,46 @@ function rawToString(data) {
   return Buffer.from(data).toString("utf-8");
 }
 var KEEPALIVE_INTERVAL_MS = 3e4;
+var MODEL_HEARTBEAT_INTERVAL_MS = 15 * 6e4;
 var INITIAL_BACKOFF_MS = 1e3;
 var MAX_BACKOFF_MS = 3e4;
+function resolvePreferredModel(opts) {
+  const env = opts?.env ?? process.env;
+  const fromFlag = opts?.model?.trim();
+  if (fromFlag) return fromFlag.slice(0, 200);
+  const fromEnv = env.ACN_PREFERRED_MODEL?.trim();
+  if (fromEnv) return fromEnv.slice(0, 200);
+  return void 0;
+}
+async function postAgentHeartbeat(opts) {
+  const fetchFn = opts.fetchFn ?? fetch;
+  const origin = opts.baseUrl.replace(/\/+$/, "");
+  const url = `${origin}/api/v1/agents/${opts.agentId}/heartbeat`;
+  const headers = {
+    Authorization: `Bearer ${opts.apiKey}`,
+    "Content-Type": "application/json"
+  };
+  const body = opts.preferredModel && opts.preferredModel.trim() ? JSON.stringify({ preferred_model: opts.preferredModel.trim().slice(0, 200) }) : void 0;
+  try {
+    const res = await fetchFn(url, { method: "POST", headers, body });
+    if (!res.ok) {
+      return { ok: false, reason: `http_${res.status}` };
+    }
+    let preferred;
+    try {
+      const json = await res.json();
+      preferred = json.preferred_model;
+    } catch {
+      preferred = opts.preferredModel ?? null;
+    }
+    return { ok: true, preferred_model: preferred };
+  } catch (err) {
+    return {
+      ok: false,
+      reason: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
 function runListener(cfg) {
   const wsUrl = toWebsocketUrl(cfg.baseUrl, cfg.agentId);
   let backoff = INITIAL_BACKOFF_MS;
@@ -2235,15 +2344,40 @@ function runListener(cfg) {
       headers: { Authorization: `Bearer ${cfg.apiKey}` }
     });
     let keepalive;
+    let modelHeartbeat;
+    const sendModelHeartbeat = () => {
+      if (!cfg.preferredModel || stopped) return;
+      void postAgentHeartbeat({
+        baseUrl: cfg.baseUrl,
+        agentId: cfg.agentId,
+        apiKey: cfg.apiKey,
+        preferredModel: cfg.preferredModel
+      }).then((r) => {
+        if (!r.ok) {
+          console.error(`[acn listen] preferred_model heartbeat failed: ${r.reason}`);
+          return;
+        }
+        console.error(
+          `[acn listen] preferred_model heartbeat ok model=${r.preferred_model ?? cfg.preferredModel}`
+        );
+      });
+    };
     ws.on("open", () => {
       const mode = cfg.runtime ? `runtime=${cfg.runtime.runtime}` : cfg.forward ? `forward=${cfg.forward}` : `exec`;
-      console.error(`[acn listen] connected as ${cfg.agentId} \u2192 ${wsUrl} (${mode})`);
+      const modelNote = cfg.preferredModel ? ` preferred_model=${cfg.preferredModel}` : "";
+      console.error(
+        `[acn listen] connected as ${cfg.agentId} \u2192 ${wsUrl} (${mode})${modelNote}`
+      );
       backoff = INITIAL_BACKOFF_MS;
       keepalive = setInterval(() => {
         if (ws.readyState === import_ws.default.OPEN) {
           ws.send(JSON.stringify({ type: "ping" }));
         }
       }, KEEPALIVE_INTERVAL_MS);
+      if (cfg.preferredModel) {
+        sendModelHeartbeat();
+        modelHeartbeat = setInterval(sendModelHeartbeat, MODEL_HEARTBEAT_INTERVAL_MS);
+      }
     });
     ws.on("message", (data) => {
       let frame;
@@ -2265,6 +2399,7 @@ function runListener(cfg) {
     });
     ws.on("close", (code, reason) => {
       if (keepalive) clearInterval(keepalive);
+      if (modelHeartbeat) clearInterval(modelHeartbeat);
       if (stopped) return;
       if (code === 4401 || code === 4403 || code === 4429) {
         console.error(
@@ -2350,7 +2485,10 @@ function listenCommand() {
     "--chat-complete-timeout <ms>",
     `Host complete timeout in ms (default ${DEFAULT_COMPLETE_TIMEOUT_MS})`,
     String(DEFAULT_COMPLETE_TIMEOUT_MS)
-  ).option("-i, --agent-id <id>", "Agent ID (defaults to config)").action(
+  ).option("-i, --agent-id <id>", "Agent ID (defaults to config)").option(
+    "-m, --model <modelId>",
+    "Declare runtime model (Host Catalog id) on connect + every 15m via REST heartbeat (self-reported; env: ACN_PREFERRED_MODEL)"
+  ).action(
     (opts) => {
       const config = loadConfig();
       const apiKey = config.api_key;
@@ -2440,10 +2578,12 @@ function listenCommand() {
         agentId,
         audience: process.env.ACN_CHAT_JWT_AUDIENCE?.trim() || process.env.AGENTPLANET_JWT_AUDIENCE?.trim()
       });
+      const preferredModel = resolvePreferredModel({ model: opts.model });
       runListener({
         agentId,
         apiKey,
         baseUrl: config.base_url,
+        preferredModel,
         forward: opts.forward,
         exec: opts.exec,
         runtime: opts.runtime ? {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@acnlabs/acn-cli",
-  "version": "0.14.2",
-  "description": "Official CLI for ACN (Agent Collaboration Network) — zero-integration agent access",
+  "version": "1.0.1",
+  "description": "Official CLI for ACN (Agent Collaboration Network) \u2014 zero-integration agent access",
   "main": "dist/index.js",
   "bin": {
     "acn": "dist/index.js"