grok-telegram-bot 2.3.0 → 2.4.0

package/src/grok/plan-approval.ts

@@ -0,0 +1,72 @@
+/**
+ * Grok plan-mode client reverse-requests (`x.ai/exit_plan_mode`,
+ * `x.ai/ask_user_question`).
+ *
+ * When the agent finishes planning it calls the `exit_plan_mode` tool. Grok
+ * intercepts that tool and sends a JSON-RPC **request** to the ACP client
+ * (`x.ai/exit_plan_mode`) so a TUI can show the plan approval UI. The Telegram
+ * bridge has no plan popup — it must answer the reverse-request immediately.
+ *
+ * Without a response (or with method-not-found), Grok fails the tool with:
+ *   "Plan approval could not be completed because the client disconnected."
+ * and plan mode stays Active (`awaiting_plan_approval: true`), blocking edits.
+ */
+
+/**
+ * Method names Grok sends as client reverse-requests for plan / questions.
+ *
+ * Live ACP traffic (verified by smoke test) uses a leading underscore:
+ *   `_x.ai/exit_plan_mode`
+ * The bare `x.ai/…` form is kept for older builds / leader-path aliases.
+ */
+export const EXT_EXIT_PLAN_MODE = "_x.ai/exit_plan_mode";
+export const EXT_EXIT_PLAN_MODE_ALT = "x.ai/exit_plan_mode";
+export const EXT_ASK_USER_QUESTION = "_x.ai/ask_user_question";
+export const EXT_ASK_USER_QUESTION_ALT = "x.ai/ask_user_question";
+
+/**
+ * Auto-approve leaving plan mode so the agent can implement.
+ *
+ * Reverse-request params (ExitPlanModeExtRequest, 3 fields) look like:
+ *   { sessionId, toolCallId, planContent }
+ *
+ * Response shape verified by live smoke (`scripts/smoke-exit-shapes.ts`):
+ *   { outcome: "approved", feedback: "" }
+ * → plan_mode.json becomes `Inactive`.
+ *
+ * Wrong shapes (e.g. `decision: "approved"`, empty `{}`) are treated as
+ * "user wants to revise the plan" and leave plan mode Active.
+ */
+export function autoApproveExitPlanMode(_params?: Record<string, unknown>): Record<string, unknown> {
+  return {
+    outcome: "approved",
+    feedback: "",
+  };
+}
+
+/**
+ * Headless answer for ask_user_question reverse-request: skip the interview so
+ * the agent is not stuck waiting for a TUI that does not exist.
+ *
+ * Externally-tagged enum variant (`SkipInterview`) from AskUserQuestionExtResponse.
+ */
+export function autoSkipAskUserQuestion(_params?: Record<string, unknown>): Record<string, unknown> {
+  return { SkipInterview: null };
+}
+
+/** Normalize method names: strip optional leading underscore for matching. */
+function normMethod(method: string): string {
+  const m = (method || "").trim();
+  return m.startsWith("_") ? m.slice(1) : m;
+}
+
+/** True when the method is a plan-approval reverse-request we must answer. */
+export function isPlanExitMethod(method: string): boolean {
+  const m = normMethod(method);
+  return m === "x.ai/exit_plan_mode" || m.endsWith("/exit_plan_mode");
+}
+
+export function isAskUserQuestionMethod(method: string): boolean {
+  const m = normMethod(method);
+  return m === "x.ai/ask_user_question" || m.endsWith("/ask_user_question");
+}

package/src/grok/session-log.ts

@@ -26,6 +26,11 @@ interface SessionFile {
   grok_session_id?: string;
   /** Model last used for this session (applied via `grok --model`). */
   model?: string;
+  /**
+   * Short human comment for Running/Sessions cards: live step while working,
+   * AI/local summary when idle. Display-only; not used as agent context.
+   */
+  comment?: string;
 }
 
 export class SessionLog {
@@ -101,6 +106,17 @@ export class SessionLog {
     return this.read(id)?.cwd;
   }
 
+  commentFor(id: string): string | undefined {
+    const c = this.read(id)?.comment?.trim();
+    return c || undefined;
+  }
+
+  setComment(id: string, comment: string): void {
+    const c = comment.trim();
+    if (!c) return;
+    this.update(id, { comment: c });
+  }
+
   // ── event log (history-compatible jsonl) ──────────────────────────────────
 
   private append(id: string, kind: string, data: Record<string, unknown>): void {

package/src/grok/types.ts

@@ -85,23 +85,35 @@ export interface SessionUpdate {
     | "plan"
     | "user_message_chunk"
     | string;
-  content?: ContentBlock;
+  /**
+   * Message chunk body (ContentBlock) OR tool-call content array (ACP standard).
+   * Callers must narrow based on sessionUpdate — use {@link contentText} helper.
+   */
+  content?: ContentBlock | ToolCallContent[] | (ContentBlock & Record<string, unknown>) | unknown;
   toolCallId?: string;
+  /** Human title (sometimes generic "Tool call" from Grok). */
   title?: string;
+  /** Stable tool identity when the agent sends it (ACP RFD / Grok extensions). */
+  name?: string;
+  toolName?: string;
   kind?: string; // "read" | "edit" | "execute" | "search" | ...
   status?: "pending" | "in_progress" | "completed" | "failed" | string;
   rawInput?: Record<string, unknown>;
+  rawOutput?: unknown;
+  /** Some agents use content_blocks instead of content. */
   content_blocks?: ToolCallContent[];
+  locations?: Array<{ path?: string; line?: number }>;
   [k: string]: unknown;
 }
 
 /** A piece of tool-call content (text, diff, etc.). */
 export interface ToolCallContent {
-  type: "content" | "diff" | string;
+  type: "content" | "diff" | "terminal" | string;
   path?: string;
   oldText?: string | null;
   newText?: string;
   content?: ContentBlock;
+  terminalId?: string;
   [k: string]: unknown;
 }
 
@@ -110,6 +122,13 @@ export interface SessionNotificationParams {
   update: SessionUpdate;
 }
 
+/** Safe text extraction when content is a ContentBlock (not a tool content array). */
+export function contentText(content: SessionUpdate["content"]): string | undefined {
+  if (!content || typeof content !== "object" || Array.isArray(content)) return undefined;
+  const t = (content as ContentBlock).text;
+  return typeof t === "string" ? t : undefined;
+}
+
 /** Permission request from the agent (server -> client) — ACP "ask" mode. */
 export interface RequestPermissionParams {
   sessionId: string;

package/src/import/build-import.ts

@@ -0,0 +1,132 @@
+/**
+ * Build a lossless import package: full transcript on disk + priming text for
+ * the first Grok turn so the conversation can continue with full context.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { HistoryEntry } from "../sessions/types.js";
+import { readForeignHistory, type ForeignSessionMeta } from "./history-readers.js";
+import type { ImportSource } from "./sources.js";
+
+/** Inline priming budget — keep under typical model input comfort zone. */
+const INLINE_MAX_CHARS = 100_000;
+/** Per-entry cap when writing the archive file (still very generous). */
+const FILE_ENTRY_MAX = 100_000;
+/** Per-entry cap inside the inline priming block. */
+const INLINE_ENTRY_MAX = 12_000;
+
+export interface ImportPackage {
+  /** Absolute path of the written full-transcript markdown (always present). */
+  transcriptPath: string;
+  /** Priming preamble to inject into the first Grok prompt. */
+  priming: string;
+  /** How many history entries were captured. */
+  entryCount: number;
+  /** Characters written to the transcript file. */
+  transcriptChars: number;
+  /** True when the full transcript did not fit inline (file is authoritative). */
+  truncatedInline: boolean;
+  meta: ForeignSessionMeta;
+  sourceLabel: string;
+}
+
+/**
+ * Extract full history, write a durable transcript under `importsDir`, and
+ * build priming text that references it.
+ */
+export function buildImportPackage(
+  src: ImportSource,
+  meta: ForeignSessionMeta,
+  importsDir: string,
+): ImportPackage {
+  const entries = readForeignHistory(src.format, src.sessionsRoot, meta.sessionId);
+  const fullBody = formatTranscript(entries, FILE_ENTRY_MAX);
+  const transcriptChars = fullBody.length;
+
+  mkdirSync(importsDir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const short = meta.sessionId.replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 12) || "session";
+  const fileName = `${src.id}-${short}-${stamp}.md`;
+  const transcriptPath = join(importsDir, fileName);
+
+  const header = [
+    `# Imported session transcript`,
+    ``,
+    `- **Source tool:** ${src.label} (\`${src.id}\`)`,
+    `- **Source session id:** \`${meta.sessionId}\``,
+    `- **Project:** ${meta.projectName ?? "(unknown)"}`,
+    `- **Working directory:** \`${meta.cwd || "(unknown)"}\``,
+    `- **Title:** ${meta.title}`,
+    `- **Entries:** ${entries.length}`,
+    `- **Imported at:** ${new Date().toISOString()}`,
+    ``,
+    `---`,
+    ``,
+    fullBody || "_(no history entries found on disk)_",
+    ``,
+  ].join("\n");
+
+  writeFileSync(transcriptPath, header, "utf-8");
+
+  const inline = formatTranscript(entries, INLINE_ENTRY_MAX);
+  let truncatedInline = false;
+  let inlineBlock = inline;
+  if (inlineBlock.length > INLINE_MAX_CHARS) {
+    truncatedInline = true;
+    // Keep the *end* of the conversation (most relevant to continue).
+    inlineBlock = inlineBlock.slice(inlineBlock.length - INLINE_MAX_CHARS);
+    const nl = inlineBlock.indexOf("\n");
+    if (nl !== -1) inlineBlock = inlineBlock.slice(nl + 1);
+    inlineBlock = `[…earlier messages omitted inline; full transcript is in the file…]\n\n` + inlineBlock;
+  }
+
+  const priming = [
+    `You are continuing a conversation that was imported from **${src.label}** into Grok.`,
+    `Nothing from the original session must be lost — the complete transcript is on disk.`,
+    ``,
+    `**Source:** ${src.label}`,
+    `**Original session id:** ${meta.sessionId}`,
+    `**Project:** ${meta.projectName ?? "(unknown)"}`,
+    `**Working directory (cwd):** ${meta.cwd || "(unknown)"}`,
+    `**Full transcript file (authoritative, complete):** ${transcriptPath}`,
+    ``,
+    `Instructions:`,
+    `1. Treat the transcript below (and the full file above) as your prior conversation history.`,
+    `2. If anything seems truncated inline, READ the full transcript file before acting.`,
+    `3. Continue seamlessly: same project, same goals, same unfinished work, same decisions.`,
+    `4. Do not restart finished work; do not ask the user to re-explain what is already in the transcript.`,
+    `5. On this first turn only: reply with a short confirmation (project path + one-sentence summary of the task so far) and WAIT for the user's next instruction. Do not make further tool calls yet unless the transcript shows an urgent incomplete action that would leave the workspace broken.`,
+    ``,
+    `=== IMPORTED TRANSCRIPT (${entries.length} entries${truncatedInline ? ", recent slice inline" : ", full inline"}) ===`,
+    inlineBlock || "(empty — see transcript file)",
+    `=== END IMPORTED TRANSCRIPT ===`,
+  ].join("\n");
+
+  return {
+    transcriptPath,
+    priming,
+    entryCount: entries.length,
+    transcriptChars,
+    truncatedInline,
+    meta,
+    sourceLabel: src.label,
+  };
+}
+
+/** Full-fidelity plain-text transcript (no 600-char UI truncation). */
+export function formatTranscript(entries: HistoryEntry[], perEntryMax: number): string {
+  const label: Record<string, string> = {
+    user: "User",
+    assistant: "Assistant",
+    tool: "Tool",
+    system: "System",
+  };
+  return entries
+    .map((e, i) => {
+      let text = e.text ?? "";
+      if (text.length > perEntryMax) text = text.slice(0, perEntryMax) + " …";
+      const tool = e.tool && e.role === "tool" ? ` (${e.tool})` : "";
+      return `### ${i + 1}. ${label[e.role] ?? e.role}${tool}\n${text}`;
+    })
+    .join("\n\n");
+}