@mndrk/agx 2.3.3 → 2.4.1

package/cloud-runtime/standalone/apps/local/lib/tracker/recap.ts

@@ -0,0 +1,246 @@
+import { promises as fs } from "fs";
+import os from "os";
+import path from "path";
+import { runCliResponse } from "@/lib/cli-runner";
+import { listTrackerRuns } from "./tracker-run-store";
+import type { TrackerItem } from "./types";
+
+// ---------------------------------------------------------------------------
+// Storage
+// ---------------------------------------------------------------------------
+
+const LATEST_FILENAME = "latest.md";
+const MAX_RETAINED = 10;
+
+function agxHome(): string {
+  return process.env.AGX_HOME ?? path.join(os.homedir(), ".agx");
+}
+
+function recapsDir(trackerType: string, itemId: string): string {
+  return path.join(agxHome(), "tracker", trackerType, itemId, "recaps");
+}
+
+function timestampedName(): string {
+  return new Date().toISOString().replace(/[:.]/g, "-") + ".md";
+}
+
+export interface RecapFile {
+  content: string;
+  filePath: string;
+  generatedAt: Date;
+}
+
+async function writeRecap(
+  trackerType: string,
+  itemId: string,
+  content: string
+): Promise<RecapFile> {
+  const dir = recapsDir(trackerType, itemId);
+  await fs.mkdir(dir, { recursive: true });
+
+  const filename = timestampedName();
+  const filePath = path.join(dir, filename);
+  await fs.writeFile(filePath, content, "utf8");
+
+  const latestPath = path.join(dir, LATEST_FILENAME);
+  try {
+    await fs.unlink(latestPath);
+  } catch {
+    /* first time */
+  }
+  await fs.symlink(filename, latestPath);
+
+  const entries = await fs.readdir(dir);
+  const old = entries
+    .filter((n) => n.endsWith(".md") && n !== LATEST_FILENAME)
+    .sort()
+    .reverse()
+    .slice(MAX_RETAINED);
+  for (const n of old) {
+    try {
+      await fs.unlink(path.join(dir, n));
+    } catch {
+      /* ignore */
+    }
+  }
+
+  const stat = await fs.stat(filePath);
+  return { content, filePath, generatedAt: stat.mtime };
+}
+
+export async function readLatestRecap(
+  trackerType: string,
+  itemId: string
+): Promise<RecapFile | null> {
+  const latestPath = path.join(recapsDir(trackerType, itemId), LATEST_FILENAME);
+  try {
+    const stat = await fs.stat(latestPath);
+    const content = await fs.readFile(latestPath, "utf8");
+    return { content, filePath: latestPath, generatedAt: stat.mtime };
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Generator
+// ---------------------------------------------------------------------------
+
+const ITEM_RECAP_SYSTEM = [
+  "You are writing a short recap of a tracker ticket.",
+  "Output raw markdown only — no JSON, no fences around the whole response.",
+  "Keep it 100–250 words.",
+  "Cover: what the ticket is about, what's been attempted (if anything), and what's open.",
+  "Write in plain prose. No headings above h3.",
+].join("\n");
+
+const GROUP_RECAP_SYSTEM = [
+  "You are writing a short recap of a group of tracker tickets (e.g. a cycle or sprint).",
+  "Output raw markdown only — no JSON, no fences around the whole response.",
+  "Keep it 150–350 words.",
+  "Cover: overall progress, what's done, what's in progress, and what's remaining.",
+  "Mention individual tickets by identifier when relevant.",
+  "Write in plain prose. No headings above h3.",
+].join("\n");
+
+export interface ItemContext {
+  identifier: string;
+  title: string;
+  status: string;
+  assignee?: string;
+  description?: string;
+  tickets?: TrackerItem[];
+}
+
+export async function generateRecap(
+  trackerType: string,
+  itemId: string,
+  item: ItemContext
+): Promise<void> {
+  const isGroup = !!item.tickets;
+
+  const priorRuns = await listTrackerRuns({
+    issueId: itemId,
+    trackerType,
+    limit: 10,
+  });
+  const priorRunLines = priorRuns
+    .map(
+      (run) =>
+        `- ${run.status}: ${run.sessionTitle ?? run.issueTitle} (${run.agentName})`
+    )
+    .join("\n");
+
+  let prompt: string;
+
+  if (isGroup && item.tickets) {
+    const ticketLines = item.tickets
+      .map(
+        (t) =>
+          `- ${t.identifier}: ${t.title} [${t.status}]${t.assignee ? ` (${t.assignee.name})` : ""}`
+      )
+      .join("\n");
+
+    prompt = [
+      `Group: ${item.title}`,
+      "",
+      `Tickets (${item.tickets.length}):`,
+      ticketLines,
+      "",
+      priorRunLines ? `Prior sessions:\n${priorRunLines}` : "No prior sessions.",
+      "",
+      "Write the recap now.",
+    ].join("\n");
+  } else {
+    prompt = [
+      `Ticket: ${item.identifier} — ${item.title}`,
+      `Status: ${item.status}`,
+      item.assignee ? `Assignee: ${item.assignee}` : null,
+      item.description ? `\nDescription:\n${item.description}` : null,
+      "",
+      priorRunLines ? `Prior sessions:\n${priorRunLines}` : "No prior sessions.",
+      "",
+      "Write the recap now.",
+    ]
+      .filter(Boolean)
+      .join("\n");
+  }
+
+  let output = "";
+  await runCliResponse({
+    provider: "claude",
+    model: null,
+    prompt,
+    systemContext: isGroup ? GROUP_RECAP_SYSTEM : ITEM_RECAP_SYSTEM,
+    onDelta: (chunk) => {
+      output += chunk;
+    },
+  });
+
+  const trimmed = output.trim();
+  if (!trimmed) {
+    throw new Error("Recap generation returned empty output");
+  }
+
+  await writeRecap(trackerType, itemId, trimmed);
+}
+
+// ---------------------------------------------------------------------------
+// Runner (in-memory queue, one job per item)
+// ---------------------------------------------------------------------------
+
+export type RecapJobStatus = "queued" | "running" | "failed";
+
+export interface RecapJobState {
+  status: RecapJobStatus;
+  startedAt: number;
+  error?: string;
+}
+
+const state = new Map<string, RecapJobState>();
+const FAILURE_HOLD_MS = 60_000;
+
+function key(trackerType: string, itemId: string): string {
+  return `${trackerType}:${itemId}`;
+}
+
+async function run(
+  trackerType: string,
+  itemId: string,
+  item: ItemContext
+): Promise<void> {
+  const k = key(trackerType, itemId);
+  state.set(k, { status: "running", startedAt: Date.now() });
+  try {
+    await generateRecap(trackerType, itemId, item);
+    state.delete(k);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    state.set(k, { status: "failed", startedAt: Date.now(), error: message });
+    setTimeout(() => {
+      const current = state.get(k);
+      if (current?.status === "failed") state.delete(k);
+    }, FAILURE_HOLD_MS);
+  }
+}
+
+export function enqueueRecap(
+  trackerType: string,
+  itemId: string,
+  item: ItemContext
+): RecapJobState {
+  const k = key(trackerType, itemId);
+  const existing = state.get(k);
+  if (existing && existing.status !== "failed") return existing;
+  const next: RecapJobState = { status: "queued", startedAt: Date.now() };
+  state.set(k, next);
+  void Promise.resolve().then(() => run(trackerType, itemId, item));
+  return next;
+}
+
+export function getRecapJob(
+  trackerType: string,
+  itemId: string
+): RecapJobState | null {
+  return state.get(key(trackerType, itemId)) ?? null;
+}

package/cloud-runtime/standalone/apps/local/lib/tracker/registry.ts

@@ -0,0 +1,32 @@
+import type { TrackerAdapter } from "./tracker-adapter";
+
+const adapters: Map<string, TrackerAdapter> = new Map();
+
+export function registerAdapter(adapter: TrackerAdapter): void {
+  if (adapters.has(adapter.type)) {
+    throw new Error(`Tracker adapter "${adapter.type}" is already registered`);
+  }
+  adapters.set(adapter.type, adapter);
+}
+
+export function getAdapter(type: string): TrackerAdapter {
+  const adapter = adapters.get(type);
+  if (!adapter) {
+    throw new Error(
+      `Unknown tracker type: "${type}". Available: ${listAdapterTypes().join(", ")}`
+    );
+  }
+  return adapter;
+}
+
+export function getAdapterOrNull(type: string): TrackerAdapter | null {
+  return adapters.get(type) ?? null;
+}
+
+export function listAdapterTypes(): string[] {
+  return [...adapters.keys()];
+}
+
+export function listAdapters(): TrackerAdapter[] {
+  return [...adapters.values()];
+}

package/cloud-runtime/standalone/apps/local/lib/tracker/route-helpers.ts

@@ -0,0 +1,27 @@
+import "@/lib/tracker"; // Ensure adapters are registered
+
+import { getAdapter, listAdapterTypes } from "@/lib/tracker/registry";
+import type { TrackerAdapter } from "@/lib/tracker/tracker-adapter";
+
+export function resolveAdapter(trackerType: string | null): TrackerAdapter {
+  if (!trackerType) {
+    throw new Error(`Missing tracker type. Available: ${listAdapterTypes().join(", ")}`);
+  }
+  return getAdapter(trackerType);
+}
+
+export function badRequest(message: string): Response {
+  return Response.json({ error: message }, { status: 400 });
+}
+
+export function notFound(message: string): Response {
+  return Response.json({ error: message }, { status: 404 });
+}
+
+export function unauthorized(message = "Not connected"): Response {
+  return Response.json({ error: message }, { status: 401 });
+}
+
+export function serverError(message: string): Response {
+  return Response.json({ error: message }, { status: 500 });
+}

package/cloud-runtime/standalone/apps/local/lib/{linear-scripted-session.ts → tracker/scripted-session.ts}

@@ -3,15 +3,15 @@ import "server-only";
 import { LOCAL_USER } from "@/lib/auth-mode";
 import { loadDbParticipants } from "@/lib/agent-participants";
 import {
-  buildLinearExecutionPrompt,
-  renderLinearExecutionPromptTemplate,
-  type LinearExecutionPromptInput,
-} from "@/lib/linear-execution-prompt";
+  buildTrackerExecutionPrompt,
+  renderTrackerExecutionPromptTemplate,
+  type TrackerExecutionPromptInput,
+} from "@/lib/tracker/tracker-execution-prompt";
 import {
-  createLinearRun,
-  updateLinearRun,
-  type LinearRunRecord,
-} from "@/lib/linear-run-store";
+  createTrackerRun,
+  updateTrackerRun,
+  type TrackerRunRecord,
+} from "@/lib/tracker/tracker-run-store";
 import { readLatestRecap } from "@/src/linear-recap/storage";
 import { createChatRun, saveMessages } from "@/lib/history-store";
 import { ensureOrchestratorRuntime } from "@/lib/orchestrator/runtime";
@@ -20,7 +20,7 @@ import { getQueue, QUEUE_NAMES } from "@/lib/queue/boss";
 import { normalizeProjectSlug, resolveProjectContext } from "@/lib/chat/project-context";
 import type { GroupMessage } from "@/lib/types";
 
-export interface ScriptedLinearSessionIssueInput {
+export interface ScriptedTrackerSessionIssueInput {
   id: string;
   identifier: string;
   title: string;
@@ -28,33 +28,38 @@ export interface ScriptedLinearSessionIssueInput {
   assignee?: string | null;
 }
 
-export interface StartScriptedLinearSessionInput {
+export interface StartScriptedTrackerSessionInput {
+  trackerType: string;
   projectId?: string | null;
   projectSlug?: string | null;
-  issue: ScriptedLinearSessionIssueInput;
+  issue: ScriptedTrackerSessionIssueInput;
   agentId: string;
   scriptName?: string | null;
   scriptPrompt?: string | null;
 }
 
-export interface StartedScriptedLinearSession {
-  run: LinearRunRecord;
+export interface StartedScriptedTrackerSession {
+  run: TrackerRunRecord;
   chatRunId: string;
   userMessageId: string;
 }
 
-export async function startScriptedLinearSession(
-  input: StartScriptedLinearSessionInput
-): Promise<StartedScriptedLinearSession> {
+/**
+ * Start a scripted tracker session.
+ * The pipeline is tracker-agnostic — it operates on canonical item fields.
+ */
+export async function startScriptedTrackerSession(
+  input: StartScriptedTrackerSessionInput
+): Promise<StartedScriptedTrackerSession> {
   const participants = await loadDbParticipants();
   const agent = participants.find((participant) => participant.id === input.agentId) ?? null;
   if (!agent) {
-    throw new Error(`Agent "${input.agentId}" could not be resolved for scripted Linear work.`);
+    throw new Error(`Agent "${input.agentId}" could not be resolved for scripted tracker work.`);
   }
 
   const latestRecap = await readLatestRecap(input.issue.id);
 
-  let run = await createLinearRun({
+  let run = await createTrackerRun({
     projectId: input.projectId ?? null,
     projectSlug: input.projectSlug ?? null,
     issueId: input.issue.id,
@@ -69,7 +74,7 @@ export async function startScriptedLinearSession(
   });
 
   try {
-    const promptInput: LinearExecutionPromptInput = {
+    const promptInput: TrackerExecutionPromptInput = {
       issue: {
         identifier: input.issue.identifier,
         title: input.issue.title,
@@ -81,11 +86,11 @@ export async function startScriptedLinearSession(
         recapContent: latestRecap?.content ?? null,
       },
     };
-    const { prompt: defaultPrompt, promptPrefix } = buildLinearExecutionPrompt(promptInput);
+    const { prompt: defaultPrompt, promptPrefix } = buildTrackerExecutionPrompt(promptInput);
     const customScriptPrompt = input.scriptPrompt?.trim() ?? "";
     const customScriptName = input.scriptName?.trim() ?? "";
     const prompt = customScriptPrompt
-      ? renderLinearExecutionPromptTemplate(customScriptPrompt, promptInput).trim() || defaultPrompt
+      ? renderTrackerExecutionPromptTemplate(customScriptPrompt, promptInput).trim() || defaultPrompt
       : defaultPrompt;
     const effectivePromptPrefix = customScriptPrompt
       ? `${promptPrefix}ACTIVE SESSION SCRIPT\n- Name: ${customScriptName || "Custom script"}\n\n`
@@ -100,7 +105,7 @@ export async function startScriptedLinearSession(
     });
 
     run =
-      (await updateLinearRun({
+      (await updateTrackerRun({
         id: run.id,
         chatRunId,
         rootMessageId: userMessageId,
@@ -112,7 +117,7 @@ export async function startScriptedLinearSession(
       userMessageId,
     };
   } catch (error) {
-    await updateLinearRun({
+    await updateTrackerRun({
       id: run.id,
       status: "failed",
       error: error instanceof Error ? error.message : String(error),

package/cloud-runtime/standalone/apps/local/lib/tracker/tracker-adapter.ts

@@ -0,0 +1,64 @@
+import type { ComponentType } from "react";
+import type {
+  TrackerItem,
+  TrackerItemDetail,
+  TrackerFilters,
+  TrackerItemUpdate,
+  TrackerGroup,
+  TrackerStatusOption,
+  TrackerAssignee,
+  TrackerActivity,
+  ConnectionStatus,
+  TokenResult,
+  PaginatedResult,
+} from "./types";
+
+export interface McpServerConfig {
+  name: string;
+  // stdio command style
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  // remote SSE style
+  url?: string;
+  headers?: Record<string, string>;
+}
+
+export interface TrackerAdapter {
+  /** Unique identifier for this tracker type, e.g. 'linear' or 'jira' */
+  type: string;
+  /** Human-readable name, e.g. 'Linear' or 'Jira Cloud' */
+  displayName: string;
+  /** Icon component to render in the sidebar and headers */
+  icon: ComponentType<{ className?: string }>;
+
+  // Auth
+  getAuthUrl(projectId: string): string;
+  handleCallback(projectId: string, code: string): Promise<TokenResult>;
+  getStatus(projectId: string): Promise<ConnectionStatus>;
+  disconnect(projectId: string): Promise<void>;
+
+  // Items (mandatory)
+  listItems(projectId: string, filters: TrackerFilters): Promise<PaginatedResult<TrackerItem>>;
+  getItem(projectId: string, itemId: string): Promise<TrackerItemDetail>;
+  updateItem(projectId: string, itemId: string, update: TrackerItemUpdate): Promise<TrackerItem>;
+  addComment(projectId: string, itemId: string, body: string): Promise<void>;
+  getActivity(projectId: string, itemId: string): Promise<TrackerActivity[]>;
+
+  // Grouping (optional — return empty arrays if not supported)
+  listGroups(projectId: string): Promise<TrackerGroup[]>;
+  listStatuses(projectId: string): Promise<TrackerStatusOption[]>;
+  listAssignees(projectId: string): Promise<TrackerAssignee[]>;
+
+  // API-key connect (optional — adapters that only support OAuth can throw)
+  handleApiKeyConnect?(projectId: string, apiKey: string): Promise<void>;
+
+  // Token delivery from external OAuth broker (e.g. agx-web)
+  handleTokenDelivery?(projectId: string, params: Record<string, string>): Promise<void>;
+
+  // MCP (optional)
+  getMcpConfig?(projectId: string): McpServerConfig;
+
+  // UI customization (optional)
+  renderGroupLabel?(group: TrackerGroup): string;
+}

package/cloud-runtime/standalone/apps/local/lib/{linear-execution-prompt.ts → tracker/tracker-execution-prompt.ts}

@@ -1,36 +1,40 @@
-export interface LinearExecutionIssueContext {
+// Tracker-agnostic execution prompt builder.
+// Inlined from the deleted linear-execution-prompt.ts. The language is
+// already tracker-agnostic (references "issue tracker" instead of "Linear").
+
+export interface TrackerExecutionIssueContext {
   identifier: string;
   title: string;
   status?: string | null;
   assignee?: string | null;
 }
 
-export interface LinearExecutionProjectRepoContext {
+export interface TrackerExecutionProjectRepoContext {
   name: string;
   path?: string | null;
   notes?: string | null;
 }
 
-export interface LinearExecutionProjectContext {
+export interface TrackerExecutionProjectContext {
   name?: string | null;
   slug?: string | null;
-  repos?: LinearExecutionProjectRepoContext[] | null;
+  repos?: TrackerExecutionProjectRepoContext[] | null;
 }
 
-export interface LinearExecutionRuntimeContext {
+export interface TrackerExecutionRuntimeContext {
   knowledgeBaseRoot?: string | null;
   issueKnowledgePath?: string | null;
   isolatedWorktreePath?: string | null;
   recapContent?: string | null;
 }
 
-export interface LinearExecutionPromptInput {
-  issue: LinearExecutionIssueContext;
-  project?: LinearExecutionProjectContext | null;
-  runtime?: LinearExecutionRuntimeContext | null;
+export interface TrackerExecutionPromptInput {
+  issue: TrackerExecutionIssueContext;
+  project?: TrackerExecutionProjectContext | null;
+  runtime?: TrackerExecutionRuntimeContext | null;
 }
 
-export interface ResolvedLinearExecutionContext {
+export interface ResolvedTrackerExecutionContext {
   issue: {
     identifier: string;
     title: string;
@@ -41,7 +45,7 @@ export interface ResolvedLinearExecutionContext {
     name: string;
     slug: string;
     label: string;
-    repos: LinearExecutionProjectRepoContext[];
+    repos: TrackerExecutionProjectRepoContext[];
   };
   runtime: {
     knowledgeBaseRoot: string;
@@ -59,7 +63,7 @@ function slugifySegment(value: string, fallback: string): string {
   return slug || fallback;
 }
 
-function toProjectSlug(project?: LinearExecutionProjectContext | null): string {
+function toProjectSlug(project?: TrackerExecutionProjectContext | null): string {
   const explicitSlug = String(project?.slug ?? "").trim();
   if (explicitSlug) {
     return slugifySegment(explicitSlug, "project");
@@ -73,7 +77,7 @@ function toProjectSlug(project?: LinearExecutionProjectContext | null): string {
   return "project";
 }
 
-function toProjectLabel(project?: LinearExecutionProjectContext | null): string {
+function toProjectLabel(project?: TrackerExecutionProjectContext | null): string {
   const name = String(project?.name ?? "").trim();
   const slug = String(project?.slug ?? "").trim();
 
@@ -89,7 +93,7 @@ function toProjectLabel(project?: LinearExecutionProjectContext | null): string
   return "current project";
 }
 
-function formatRepositories(repos?: LinearExecutionProjectRepoContext[] | null): string {
+function formatRepositories(repos?: TrackerExecutionProjectRepoContext[] | null): string {
   if (!repos || repos.length === 0) {
     return "- Use the active project context to discover the right repository or workspace; do not hardcode paths.";
   }
@@ -112,11 +116,11 @@ function formatRepositories(repos?: LinearExecutionProjectRepoContext[] | null):
     .join("\n");
 }
 
-export function buildLinearExecutionPrompt(input: LinearExecutionPromptInput): {
+export function buildTrackerExecutionPrompt(input: TrackerExecutionPromptInput): {
   prompt: string;
   promptPrefix: string;
 } {
-  const context = resolveLinearExecutionContext(input);
+  const context = resolveTrackerExecutionContext(input);
   const issueIdentifier = context.issue.identifier;
   const issueTitle = context.issue.title;
   const issueStatus = context.issue.status;
@@ -137,7 +141,7 @@ export function buildLinearExecutionPrompt(input: LinearExecutionPromptInput): {
     [
       "TERMINOLOGY NOTE",
       "- \"Ticket\" / \"issue\" = the work item you are executing (from Linear, Jira, etc.)",
-      "- \"Task\" in this project's UI = a scheduled or manual background task (cron jobs, automations) — NOT this ticket.",
+      "- \"Task\" in this project's UI = a scheduled or manual background task (cron jobs, automations) \u2014 NOT this ticket.",
       "- Do not confuse scheduled tasks with the ticket you are working on.",
     ].join("\n"),
     [
@@ -186,9 +190,9 @@ export function buildLinearExecutionPrompt(input: LinearExecutionPromptInput): {
   };
 }
 
-export function resolveLinearExecutionContext(
-  input: LinearExecutionPromptInput
-): ResolvedLinearExecutionContext {
+export function resolveTrackerExecutionContext(
+  input: TrackerExecutionPromptInput
+): ResolvedTrackerExecutionContext {
   const issueIdentifier = input.issue.identifier.trim() || "TICKET-ID";
   const issueTitle = input.issue.title.trim() || "Untitled ticket";
   const issueStatus = String(input.issue.status ?? "").trim() || "Unknown";
@@ -225,11 +229,11 @@ export function resolveLinearExecutionContext(
   };
 }
 
-export function renderLinearExecutionPromptTemplate(
+export function renderTrackerExecutionPromptTemplate(
   template: string,
-  input: LinearExecutionPromptInput
+  input: TrackerExecutionPromptInput
 ): string {
-  const context = resolveLinearExecutionContext(input);
+  const context = resolveTrackerExecutionContext(input);
   const values: Record<string, string> = {
     "ticket.identifier": context.issue.identifier,
     "ticket.title": context.issue.title,