@integrity-labs/agt-cli 0.20.9 → 0.21.1

package/mcp/direct-chat-channel.js

@@ -13871,12 +13871,18 @@ var TERMINAL_EMOJI = {
   completed: "\u2705",
   failed: "\u274C"
 };
-function formatWallClock(ms) {
-  const d = new Date(ms);
-  const hh = String(d.getUTCHours()).padStart(2, "0");
-  const mm = String(d.getUTCMinutes()).padStart(2, "0");
-  const ss = String(d.getUTCSeconds()).padStart(2, "0");
-  return `${hh}:${mm}:${ss} UTC`;
+function formatWallClock(ms, timeZone) {
+  const fmt = new Intl.DateTimeFormat("en-GB", {
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false,
+    timeZone,
+    timeZoneName: "short"
+  });
+  const parts = fmt.formatToParts(new Date(ms));
+  const get = (t) => parts.find((p) => p.type === t)?.value ?? "";
+  return `${get("hour")}:${get("minute")}:${get("second")} ${get("timeZoneName")}`;
 }
 function renderProgressMarkdown(state) {
   const lines = [];

package/mcp/slack-channel.js

@@ -14333,12 +14333,18 @@ var TERMINAL_EMOJI = {
   completed: "\u2705",
   failed: "\u274C"
 };
-function formatWallClock(ms) {
-  const d = new Date(ms);
-  const hh = String(d.getUTCHours()).padStart(2, "0");
-  const mm = String(d.getUTCMinutes()).padStart(2, "0");
-  const ss = String(d.getUTCSeconds()).padStart(2, "0");
-  return `${hh}:${mm}:${ss} UTC`;
+function formatWallClock(ms, timeZone) {
+  const fmt = new Intl.DateTimeFormat("en-GB", {
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false,
+    timeZone,
+    timeZoneName: "short"
+  });
+  const parts = fmt.formatToParts(new Date(ms));
+  const get = (t) => parts.find((p) => p.type === t)?.value ?? "";
+  return `${get("hour")}:${get("minute")}:${get("second")} ${get("timeZoneName")}`;
 }
 function renderHeaderLine(state) {
   if (state.terminal) {

package/mcp/telegram-channel.js

@@ -13863,7 +13863,7 @@ var StdioServerTransport = class {
 
 // src/telegram-channel.ts
 import https from "https";
-import { createHash, randomUUID } from "crypto";
+import { createHash, randomUUID as randomUUID2 } from "crypto";
 import {
   closeSync,
   createWriteStream,
@@ -14820,6 +14820,430 @@ function createObservedChatClient(args) {
   };
 }
 
+// src/progress-tools.ts
+import { randomUUID } from "crypto";
+
+// src/progress-handle.ts
+async function startProgressHandle(opts) {
+  const now = opts.now ?? (() => Date.now());
+  const setTimer = opts.setTimer ?? ((cb, ms) => setTimeout(cb, ms));
+  const clearTimer = opts.clearTimer ?? ((id) => clearTimeout(id));
+  const debounceMs = opts.debounceMs ?? 1e3;
+  const onPostTerminalUpdate = opts.onPostTerminalUpdate ?? defaultPostTerminalWarn;
+  const state = {
+    initialLabel: opts.initialLabel,
+    mode: opts.initialMode ?? "working",
+    lastChangeAt: now()
+  };
+  let lastFlushAt = 0;
+  let pendingTimer = null;
+  let inFlight = null;
+  let terminal = false;
+  async function doFlush() {
+    while (inFlight) await inFlight;
+    if (pendingTimer != null) {
+      clearTimer(pendingTimer);
+      pendingTimer = null;
+    }
+    lastFlushAt = now();
+    const promise = opts.flush(snapshotState());
+    inFlight = promise.then(
+      () => {
+        inFlight = null;
+      },
+      (err) => {
+        inFlight = null;
+        throw err;
+      }
+    );
+    await inFlight;
+  }
+  function snapshotState() {
+    return {
+      initialLabel: state.initialLabel,
+      mode: state.mode,
+      stepLabel: state.stepLabel,
+      stepNumber: state.stepNumber ? { ...state.stepNumber } : void 0,
+      detail: state.detail,
+      lastChangeAt: state.lastChangeAt,
+      terminal: state.terminal ? { ...state.terminal } : void 0
+    };
+  }
+  function applyUpdate(next) {
+    if (next.mode !== void 0) state.mode = next.mode;
+    if (next.stepLabel !== void 0) state.stepLabel = next.stepLabel;
+    if (next.stepNumber !== void 0) state.stepNumber = { ...next.stepNumber };
+    if (next.detail !== void 0) state.detail = next.detail;
+    state.lastChangeAt = now();
+  }
+  async function scheduleOrFlush() {
+    const elapsed = now() - lastFlushAt;
+    if (elapsed >= debounceMs) {
+      await doFlush();
+      return;
+    }
+    if (pendingTimer != null) return;
+    const remaining = debounceMs - elapsed;
+    pendingTimer = setTimer(() => {
+      pendingTimer = null;
+      void doFlush().catch(() => {
+      });
+    }, remaining);
+  }
+  lastFlushAt = now();
+  await opts.flush(snapshotState());
+  return {
+    snapshot: snapshotState,
+    async update(next) {
+      if (terminal) {
+        const peeked = snapshotState();
+        Object.assign(peeked, {
+          mode: next.mode ?? peeked.mode,
+          stepLabel: next.stepLabel ?? peeked.stepLabel,
+          stepNumber: next.stepNumber ?? peeked.stepNumber,
+          detail: next.detail ?? peeked.detail
+        });
+        try {
+          onPostTerminalUpdate(peeked);
+        } catch (err) {
+          console.warn(
+            "[progress-handle] onPostTerminalUpdate threw \u2014 swallowed to keep update() non-throwing:",
+            err
+          );
+        }
+        return;
+      }
+      applyUpdate(next);
+      await scheduleOrFlush();
+    },
+    async complete(summary) {
+      if (terminal) return;
+      terminal = true;
+      state.terminal = { kind: "completed", message: summary };
+      state.lastChangeAt = now();
+      await doFlush();
+    },
+    async fail(reason) {
+      if (terminal) return;
+      terminal = true;
+      state.terminal = { kind: "failed", message: reason };
+      state.lastChangeAt = now();
+      await doFlush();
+    },
+    isTerminal: () => terminal
+  };
+}
+function defaultPostTerminalWarn(state) {
+  console.warn(
+    `[progress-handle] update() called after terminal transition (${state.terminal?.kind}) \u2014 ignored.`
+  );
+}
+
+// src/progress-tools.ts
+var ProgressToolRegistry = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.toolNames = {
+      start: `${opts.prefix}_progress_start`,
+      update: `${opts.prefix}_progress_update`,
+      complete: `${opts.prefix}_progress_complete`,
+      fail: `${opts.prefix}_progress_fail`
+    };
+  }
+  handles = /* @__PURE__ */ new Map();
+  toolNames;
+  /** Tool definitions to splice into the MCP ListToolsRequest response. */
+  getDefinitions() {
+    const { surfaceDescription, startArgsSchema } = this.opts;
+    const debounceMs = this.opts.debounceMs ?? 1e3;
+    const debounceText = debounceMs === 1e3 ? "per second" : `every ${debounceMs}ms`;
+    return [
+      {
+        name: this.toolNames.start,
+        description: `Post a "still working" anchor to ${surfaceDescription} and return a progress_id. The anchor message updates in place as you call ${this.toolNames.update} \u2014 operators see one message that ticks forward instead of a flood of new ones. Always end with ${this.toolNames.complete} or ${this.toolNames.fail}; otherwise the anchor lingers as "working" until the stale-state sweep flips it. Opt-in \u2014 only call this for tasks that will take more than a few seconds.`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            label: {
+              type: "string",
+              description: 'Short top-line label for the task (e.g. "diagnose vigil"). Stays constant for the lifetime of this progress anchor.'
+            },
+            initial_mode: {
+              type: "string",
+              enum: ["thinking", "working", "waiting"],
+              description: 'Initial mode emoji \u2014 defaults to "working".'
+            },
+            ...startArgsSchema.properties
+          },
+          required: ["label", ...startArgsSchema.required]
+        }
+      },
+      {
+        name: this.toolNames.update,
+        description: `Update the progress anchor in place. The state machine debounces calls to one ${surfaceDescription} API call ${debounceText}, so spamming this every step is safe \u2014 only the latest pending state will paint. Any subset of fields can be passed; omitted ones retain their previous value.`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            progress_id: { type: "string", description: "The progress_id returned from start." },
+            step_label: { type: "string", description: 'Short label for the current step (e.g. "Querying CloudWatch logs").' },
+            step_current: { type: "number", description: "1-based step counter \u2014 current." },
+            step_total: { type: "number", description: "Total steps if known. Omit for open-ended progress." },
+            mode: { type: "string", enum: ["thinking", "working", "waiting"] },
+            detail: { type: "string", description: "Free-text detail line under the step label." }
+          },
+          required: ["progress_id"]
+        }
+      },
+      {
+        name: this.toolNames.complete,
+        description: `Mark the progress anchor as \u2705 completed. Flushes any pending debounced state before painting the terminal banner \u2014 the operator never sees a stale "Step N" beside the \u2705. After this, the handle is dead; further updates are no-ops.`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            progress_id: { type: "string" },
+            summary: { type: "string", description: "Optional one-line summary of what was achieved." }
+          },
+          required: ["progress_id"]
+        }
+      },
+      {
+        name: this.toolNames.fail,
+        description: `Mark the progress anchor as \u274C failed. Always include a one-sentence reason \u2014 the operator can't tell *why* from emoji alone. Same flush-then-paint behaviour as complete.`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            progress_id: { type: "string" },
+            reason: { type: "string", description: "One-sentence failure reason." }
+          },
+          required: ["progress_id", "reason"]
+        }
+      }
+    ];
+  }
+  /**
+   * Dispatch a CallToolRequest. Returns `undefined` if the tool name
+   * isn't one of ours (so the caller can keep walking its dispatch
+   * chain). Returns a tool result otherwise.
+   */
+  async handle(name, args) {
+    if (name === this.toolNames.start) return this.handleStart(args);
+    if (name === this.toolNames.update) return this.handleUpdate(args);
+    if (name === this.toolNames.complete) return this.handleComplete(args);
+    if (name === this.toolNames.fail) return this.handleFail(args);
+    return void 0;
+  }
+  /** Live count of in-flight handles. Exposed for tests + diagnostics. */
+  size() {
+    return this.handles.size;
+  }
+  async handleStart(args) {
+    const label = typeof args.label === "string" ? args.label : null;
+    if (!label) return errResult(`${this.toolNames.start}: 'label' must be a non-empty string`);
+    if ("initial_mode" in args && !isMode(args.initial_mode)) {
+      return errResult(
+        `${this.toolNames.start}: 'initial_mode' must be one of 'thinking', 'working', or 'waiting'`
+      );
+    }
+    for (const k of this.opts.startArgsSchema.required) {
+      if (typeof args[k] !== "string" || args[k].length === 0) {
+        return errResult(`${this.toolNames.start}: '${k}' must be a non-empty string`);
+      }
+    }
+    const initialMode = isMode(args.initial_mode) ? args.initial_mode : void 0;
+    const progressId = randomUUID();
+    try {
+      const flush = this.opts.createFlush(args);
+      const handle = await startProgressHandle({
+        initialLabel: label,
+        initialMode,
+        flush,
+        debounceMs: this.opts.debounceMs ?? 1e3
+      });
+      this.handles.set(progressId, handle);
+      return okResult(JSON.stringify({ progress_id: progressId }));
+    } catch (err) {
+      return errResult(`${this.toolNames.start} failed: ${err.message ?? String(err)}`);
+    }
+  }
+  async handleUpdate(args) {
+    const id = typeof args.progress_id === "string" ? args.progress_id : null;
+    if (!id) return errResult(`${this.toolNames.update}: 'progress_id' must be a string`);
+    const handle = this.handles.get(id);
+    if (!handle) return errResult(`${this.toolNames.update}: unknown progress_id (already terminated, or never started)`);
+    if ("mode" in args && !isMode(args.mode)) {
+      return errResult(
+        `${this.toolNames.update}: 'mode' must be one of 'thinking', 'working', or 'waiting'`
+      );
+    }
+    if (typeof args.step_total === "number" && typeof args.step_current !== "number") {
+      return errResult(
+        `${this.toolNames.update}: 'step_total' requires 'step_current'`
+      );
+    }
+    const next = {};
+    if (typeof args.step_label === "string") next.stepLabel = args.step_label;
+    if (typeof args.step_current === "number") {
+      next.stepNumber = {
+        current: args.step_current,
+        ...typeof args.step_total === "number" ? { total: args.step_total } : {}
+      };
+    }
+    if (isMode(args.mode)) next.mode = args.mode;
+    if (typeof args.detail === "string") next.detail = args.detail;
+    try {
+      await handle.update(next);
+      return okResult("ok");
+    } catch (err) {
+      return errResult(`${this.toolNames.update} failed: ${err.message ?? String(err)}`);
+    }
+  }
+  async handleComplete(args) {
+    const id = typeof args.progress_id === "string" ? args.progress_id : null;
+    if (!id) return errResult(`${this.toolNames.complete}: 'progress_id' must be a string`);
+    const handle = this.handles.get(id);
+    if (!handle) return errResult(`${this.toolNames.complete}: unknown progress_id`);
+    const summary = typeof args.summary === "string" ? args.summary : void 0;
+    try {
+      await handle.complete(summary);
+      this.handles.delete(id);
+      return okResult("ok");
+    } catch (err) {
+      return errResult(`${this.toolNames.complete} failed: ${err.message ?? String(err)}`);
+    }
+  }
+  async handleFail(args) {
+    const id = typeof args.progress_id === "string" ? args.progress_id : null;
+    if (!id) return errResult(`${this.toolNames.fail}: 'progress_id' must be a string`);
+    const reason = typeof args.reason === "string" ? args.reason : null;
+    if (!reason) return errResult(`${this.toolNames.fail}: 'reason' must be a non-empty string`);
+    const handle = this.handles.get(id);
+    if (!handle) return errResult(`${this.toolNames.fail}: unknown progress_id`);
+    try {
+      await handle.fail(reason);
+      this.handles.delete(id);
+      return okResult("ok");
+    } catch (err) {
+      return errResult(`${this.toolNames.fail} failed: ${err.message ?? String(err)}`);
+    }
+  }
+};
+function okResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+function errResult(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+function isMode(value) {
+  return value === "thinking" || value === "working" || value === "waiting";
+}
+
+// src/telegram-progress.ts
+var MODE_EMOJI = {
+  thinking: "\u{1F4AD}",
+  working: "\u{1F6E0}\uFE0F",
+  waiting: "\u23F3"
+};
+var TERMINAL_EMOJI = {
+  completed: "\u2705",
+  failed: "\u274C"
+};
+function formatWallClock(ms, timeZone) {
+  const fmt = new Intl.DateTimeFormat("en-GB", {
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false,
+    timeZone,
+    timeZoneName: "short"
+  });
+  const parts = fmt.formatToParts(new Date(ms));
+  const get = (t) => parts.find((p) => p.type === t)?.value ?? "";
+  return `${get("hour")}:${get("minute")}:${get("second")} ${get("timeZoneName")}`;
+}
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function renderProgressHtml(state) {
+  const lines = [];
+  if (state.terminal) {
+    const banner = state.terminal.kind === "completed" ? "Done" : "Failed";
+    lines.push(`${TERMINAL_EMOJI[state.terminal.kind]} <b>${banner}</b> \u2014 ${escapeHtml(state.initialLabel)}`);
+    if (state.terminal.message) lines.push(escapeHtml(state.terminal.message));
+    const verb = state.terminal.kind === "completed" ? "completed" : "failed";
+    lines.push(`<i>${verb}: ${formatWallClock(state.lastChangeAt)}</i>`);
+    return lines.join("\n");
+  }
+  lines.push(`${MODE_EMOJI[state.mode]} <b>Working on:</b> ${escapeHtml(state.initialLabel)}`);
+  if (state.stepNumber || state.stepLabel) {
+    const parts = [];
+    if (state.stepNumber) {
+      if (state.stepNumber.total != null) {
+        parts.push(`<b>Step ${state.stepNumber.current} of ${state.stepNumber.total}</b>`);
+      } else {
+        parts.push(`<b>Step ${state.stepNumber.current}</b>`);
+      }
+    }
+    if (state.stepLabel) parts.push(escapeHtml(state.stepLabel));
+    lines.push(parts.join(": "));
+  }
+  if (state.detail) lines.push(`<i>${escapeHtml(state.detail)}</i>`);
+  lines.push(`<i>last update: ${formatWallClock(state.lastChangeAt)}</i>`);
+  return lines.join("\n");
+}
+var TelegramApiError = class extends Error {
+  constructor(endpoint, apiError) {
+    super(`Telegram ${endpoint} failed: ${apiError}`);
+    this.endpoint = endpoint;
+    this.apiError = apiError;
+    this.name = "TelegramApiError";
+  }
+};
+function isMessageNotModified(description) {
+  if (!description) return false;
+  return /message is not modified/i.test(description);
+}
+function createTelegramProgressFlush(opts) {
+  let anchorMessageId = null;
+  return async function flush(state) {
+    const text = renderProgressHtml(state);
+    if (anchorMessageId == null) {
+      const body = {
+        chat_id: opts.chatId,
+        text,
+        parse_mode: "HTML",
+        disable_notification: true
+      };
+      if (opts.messageThreadId != null) body.message_thread_id = opts.messageThreadId;
+      if (opts.replyToMessageId != null) body.reply_to_message_id = opts.replyToMessageId;
+      const res = await opts.callImpl("sendMessage", body);
+      if (!res.ok || !res.result?.message_id) {
+        throw new TelegramApiError("sendMessage", res.description ?? "missing message_id");
+      }
+      anchorMessageId = res.result.message_id;
+      opts.onAnchorPosted?.(res.result.message_id);
+      return;
+    }
+    try {
+      const res = await opts.callImpl("editMessageText", {
+        chat_id: opts.chatId,
+        message_id: anchorMessageId,
+        text,
+        parse_mode: "HTML"
+      });
+      if (!res.ok) {
+        if (isMessageNotModified(res.description)) return;
+        throw new TelegramApiError("editMessageText", res.description ?? "unknown");
+      }
+    } catch (err) {
+      if (opts.onApiError && err instanceof TelegramApiError) {
+        await opts.onApiError(err);
+        return;
+      }
+      throw err;
+    }
+  };
+}
+
 // src/pending-reminder-schedule.ts
 var REMINDER_SCHEDULE_MS = [5, 10, 20].map((m) => m * 6e4);
 var MAX_REMINDERS = REMINDER_SCHEDULE_MS.length;
@@ -15050,7 +15474,7 @@ async function handleRestartCommand(opts) {
       ts: Date.now(),
       reply: { chat_id: opts.chatId, message_id: opts.messageId }
     };
-    const tmpPath = `${flagPath}.${process.pid}.${randomUUID()}.tmp`;
+    const tmpPath = `${flagPath}.${process.pid}.${randomUUID2()}.tmp`;
     writeFileSync2(tmpPath, JSON.stringify(flag) + "\n", "utf8");
     renameSync2(tmpPath, flagPath);
     process.stderr.write(
@@ -15619,8 +16043,42 @@ var mcp = new Server(
     ].join(" ")
   }
 );
+var TELEGRAM_PROGRESS_TIMEOUT_MS = 5e3;
+var progressRegistry = new ProgressToolRegistry({
+  prefix: "telegram",
+  surfaceDescription: "a Telegram chat",
+  startArgsSchema: {
+    properties: {
+      chat_id: {
+        type: "string",
+        description: "Telegram chat id (from the `chat_id` attribute on the inbound <channel> tag). Numeric ids are passed as strings; the API accepts both."
+      },
+      message_thread_id: {
+        type: "string",
+        description: "Forum topic id (`message_thread_id`) \u2014 pass this if the inbound arrived in a forum topic so the anchor lands in the same topic. Omit for normal chats."
+      },
+      reply_to_message_id: {
+        type: "string",
+        description: "Optional message id to thread the anchor under (typically the inbound message_id from the <channel> tag)."
+      }
+    },
+    required: ["chat_id"]
+  },
+  createFlush: (args) => {
+    const chatId = args.chat_id;
+    const threadId = typeof args.message_thread_id === "string" && args.message_thread_id.length > 0 ? Number(args.message_thread_id) : void 0;
+    const replyTo = typeof args.reply_to_message_id === "string" && args.reply_to_message_id.length > 0 ? Number(args.reply_to_message_id) : void 0;
+    return createTelegramProgressFlush({
+      chatId,
+      messageThreadId: Number.isFinite(threadId) ? threadId : void 0,
+      replyToMessageId: Number.isFinite(replyTo) ? replyTo : void 0,
+      callImpl: (method, body) => telegramApiCall(method, body, TELEGRAM_PROGRESS_TIMEOUT_MS)
+    });
+  }
+});
 mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
+    ...progressRegistry.getDefinitions(),
     {
       name: "telegram.reply",
       description: "Reply to a Telegram chat or specific message",
@@ -15699,6 +16157,8 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
 }));
 mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
   const { name, arguments: args } = req.params;
+  const progressResult = await progressRegistry.handle(name, args ?? {});
+  if (progressResult !== void 0) return progressResult;
   if (name === "telegram.reply" || name === "telegram.send_message") {
     const { chat_id, text, reply_to_message_id } = args;
     if (ALLOWED_CHATS.size > 0 && !ALLOWED_CHATS.has(chat_id)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@integrity-labs/agt-cli",
-  "version": "0.20.9",
+  "version": "0.21.1",
   "description": "Augmented Team CLI — agent provisioning and management",
   "type": "module",
   "engines": {