@calltelemetry/openclaw-linear 0.6.0 → 0.7.0

package/src/pipeline/planner.ts

@@ -0,0 +1,282 @@
+/**
+ * planner.ts — Orchestration for the project planning pipeline.
+ *
+ * Manages the interview-style planning flow:
+ * - initiatePlanningSession: enters planning mode for a project
+ * - handlePlannerTurn: processes each user comment during planning
+ * - runPlanAudit: validates the plan before finalizing
+ */
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { LinearAgentApi } from "../api/linear-api.js";
+import { runAgent } from "../agent/agent.js";
+import {
+  type PlanningSession,
+  registerPlanningSession,
+  updatePlanningSession,
+  endPlanningSession,
+  setPlanningCache,
+} from "./planning-state.js";
+import {
+  setActivePlannerContext,
+  clearActivePlannerContext,
+  buildPlanSnapshot,
+  auditPlan,
+} from "../tools/planner-tools.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PlannerContext {
+  api: OpenClawPluginApi;
+  linearApi: LinearAgentApi;
+  pluginConfig?: Record<string, unknown>;
+}
+
+interface PlannerPrompts {
+  system: string;
+  interview: string;
+  audit_prompt: string;
+  welcome: string;
+}
+
+// ---------------------------------------------------------------------------
+// Prompt loading
+// ---------------------------------------------------------------------------
+
+function loadPlannerPrompts(pluginConfig?: Record<string, unknown>): PlannerPrompts {
+  const defaults: PlannerPrompts = {
+    system: "You are a product planning specialist. Interview the user about features and create Linear issues.",
+    interview: "Project: {{projectName}}\n\nPlan:\n{{planSnapshot}}\n\nUser said: {{userMessage}}\n\nContinue planning.",
+    audit_prompt: "Run audit_plan for {{projectName}}.",
+    welcome: "Entering planning mode for **{{projectName}}**. What are the main feature areas?",
+  };
+
+  try {
+    const customPath = pluginConfig?.promptsPath as string | undefined;
+    let raw: string;
+
+    if (customPath) {
+      const resolved = customPath.startsWith("~")
+        ? customPath.replace("~", process.env.HOME ?? "")
+        : customPath;
+      raw = readFileSync(resolved, "utf-8");
+    } else {
+      const pluginRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
+      raw = readFileSync(join(pluginRoot, "prompts.yaml"), "utf-8");
+    }
+
+    const parsed = parseYaml(raw) as any;
+    if (parsed?.planner) {
+      return {
+        system: parsed.planner.system ?? defaults.system,
+        interview: parsed.planner.interview ?? defaults.interview,
+        audit_prompt: parsed.planner.audit_prompt ?? defaults.audit_prompt,
+        welcome: parsed.planner.welcome ?? defaults.welcome,
+      };
+    }
+  } catch { /* use defaults */ }
+
+  return defaults;
+}
+
+function renderTemplate(template: string, vars: Record<string, string>): string {
+  let result = template;
+  for (const [key, value] of Object.entries(vars)) {
+    result = result.replaceAll(`{{${key}}}`, value);
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Planning initiation
+// ---------------------------------------------------------------------------
+
+export async function initiatePlanningSession(
+  ctx: PlannerContext,
+  projectId: string,
+  rootIssue: { id: string; identifier: string; title: string; team?: { id: string } },
+): Promise<void> {
+  const { api, linearApi, pluginConfig } = ctx;
+  const configPath = pluginConfig?.planningStatePath as string | undefined;
+
+  // Fetch project metadata
+  const project = await linearApi.getProject(projectId);
+  const teamId = rootIssue.team?.id ?? project.teams?.nodes?.[0]?.id;
+  if (!teamId) throw new Error(`Cannot determine team for project ${projectId}`);
+
+  // Fetch team states for reference
+  await linearApi.getTeamStates(teamId);
+
+  // Register session
+  const session: PlanningSession = {
+    projectId,
+    projectName: project.name,
+    rootIssueId: rootIssue.id,
+    rootIdentifier: rootIssue.identifier,
+    teamId,
+    status: "interviewing",
+    startedAt: new Date().toISOString(),
+    turnCount: 0,
+  };
+
+  await registerPlanningSession(projectId, session, configPath);
+  setPlanningCache(session);
+
+  api.logger.info(`Planning: initiated session for ${project.name} (${rootIssue.identifier})`);
+
+  // Post welcome comment
+  const prompts = loadPlannerPrompts(pluginConfig);
+  const welcomeMsg = renderTemplate(prompts.welcome, {
+    projectName: project.name,
+    rootIdentifier: rootIssue.identifier,
+  });
+  await linearApi.createComment(rootIssue.id, welcomeMsg);
+}
+
+// ---------------------------------------------------------------------------
+// Interview turn
+// ---------------------------------------------------------------------------
+
+const FINALIZE_PATTERN = /\b(finalize\s+plan|finalize|done\s+planning|approve\s+plan|plan\s+looks\s+good)\b/i;
+const ABANDON_PATTERN = /\b(abandon|cancel\s+planning|stop\s+planning|exit\s+planning)\b/i;
+
+export async function handlePlannerTurn(
+  ctx: PlannerContext,
+  session: PlanningSession,
+  input: { issueId: string; commentBody: string; commentorName: string },
+): Promise<void> {
+  const { api, linearApi, pluginConfig } = ctx;
+  const configPath = pluginConfig?.planningStatePath as string | undefined;
+
+  // Detect finalization intent
+  if (FINALIZE_PATTERN.test(input.commentBody)) {
+    await runPlanAudit(ctx, session);
+    return;
+  }
+
+  // Detect abandon intent
+  if (ABANDON_PATTERN.test(input.commentBody)) {
+    await endPlanningSession(session.projectId, "abandoned", configPath);
+    await linearApi.createComment(
+      session.rootIssueId,
+      `Planning mode ended for **${session.projectName}**. Session abandoned.`,
+    );
+    api.logger.info(`Planning: session abandoned for ${session.projectName}`);
+    return;
+  }
+
+  // Increment turn count
+  const newTurnCount = session.turnCount + 1;
+  await updatePlanningSession(session.projectId, { turnCount: newTurnCount }, configPath);
+
+  // Build plan snapshot
+  const issues = await linearApi.getProjectIssues(session.projectId);
+  const planSnapshot = buildPlanSnapshot(issues);
+
+  // Build comment history (last 10 comments on root issue)
+  let commentHistory = "";
+  try {
+    const details = await linearApi.getIssueDetails(session.rootIssueId);
+    commentHistory = details.comments?.nodes
+      ?.map((c) => `**${c.user?.name ?? "Unknown"}:** ${c.body.slice(0, 300)}`)
+      .join("\n\n") ?? "";
+  } catch { /* best effort */ }
+
+  // Build prompt
+  const prompts = loadPlannerPrompts(pluginConfig);
+  const taskPrompt = renderTemplate(prompts.interview, {
+    projectName: session.projectName,
+    rootIdentifier: session.rootIdentifier,
+    planSnapshot,
+    turnCount: String(newTurnCount),
+    commentHistory,
+    userMessage: input.commentBody,
+  });
+
+  // Set planner context for tools
+  setActivePlannerContext({
+    linearApi,
+    projectId: session.projectId,
+    teamId: session.teamId,
+  });
+
+  try {
+    const sessionId = `planner-${session.rootIdentifier}-turn-${newTurnCount}`;
+    const agentId = (pluginConfig?.defaultAgentId as string) ?? "default";
+
+    api.logger.info(`Planning: turn ${newTurnCount} for ${session.projectName}`);
+
+    const result = await runAgent({
+      api,
+      agentId,
+      sessionId,
+      message: `${prompts.system}\n\n${taskPrompt}`,
+    });
+
+    // Post agent response as comment
+    if (result.output) {
+      await linearApi.createComment(session.rootIssueId, result.output);
+    }
+  } finally {
+    clearActivePlannerContext();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Plan audit
+// ---------------------------------------------------------------------------
+
+export async function runPlanAudit(
+  ctx: PlannerContext,
+  session: PlanningSession,
+): Promise<void> {
+  const { api, linearApi, pluginConfig } = ctx;
+  const configPath = pluginConfig?.planningStatePath as string | undefined;
+
+  api.logger.info(`Planning: running audit for ${session.projectName}`);
+
+  // Run deterministic audit
+  const issues = await linearApi.getProjectIssues(session.projectId);
+  const result = auditPlan(issues);
+
+  if (result.pass) {
+    // Build final summary
+    const snapshot = buildPlanSnapshot(issues);
+    const warningsList = result.warnings.length > 0
+      ? `\n\n**Warnings:**\n${result.warnings.map((w) => `- ${w}`).join("\n")}`
+      : "";
+
+    await linearApi.createComment(
+      session.rootIssueId,
+      `## Plan Approved\n\n` +
+      `The plan for **${session.projectName}** passed all checks.\n\n` +
+      `**${issues.length} issues** created with valid dependency graph.${warningsList}\n\n` +
+      `### Final Plan\n${snapshot}\n\n` +
+      `---\n*Planning mode complete. Project is ready for implementation dispatch.*`,
+    );
+
+    await endPlanningSession(session.projectId, "approved", configPath);
+    api.logger.info(`Planning: session approved for ${session.projectName}`);
+  } else {
+    // Post problems and keep planning
+    const problemsList = result.problems.map((p) => `- ${p}`).join("\n");
+    const warningsList = result.warnings.length > 0
+      ? `\n\n**Warnings:**\n${result.warnings.map((w) => `- ${w}`).join("\n")}`
+      : "";
+
+    await linearApi.createComment(
+      session.rootIssueId,
+      `## Plan Audit Failed\n\n` +
+      `The following issues need attention before the plan can be approved:\n\n` +
+      `**Problems:**\n${problemsList}${warningsList}\n\n` +
+      `Please address these issues, then say "finalize plan" again.`,
+    );
+
+    api.logger.info(`Planning: audit failed for ${session.projectName} (${result.problems.length} problems)`);
+  }
+}

package/src/pipeline/planning-state.test.ts

@@ -0,0 +1,236 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  readPlanningState,
+  writePlanningState,
+  registerPlanningSession,
+  updatePlanningSession,
+  getPlanningSession,
+  endPlanningSession,
+  isInPlanningMode,
+  setPlanningCache,
+  clearPlanningCache,
+  getActivePlanningByProjectId,
+  type PlanningSession,
+  type PlanningState,
+} from "./planning-state.js";
+
+function tmpStatePath(): string {
+  const dir = mkdtempSync(join(tmpdir(), "claw-ps-"));
+  return join(dir, "state.json");
+}
+
+function makePlanningSession(overrides?: Partial<PlanningSession>): PlanningSession {
+  return {
+    projectId: "proj-1",
+    projectName: "Test Project",
+    rootIssueId: "issue-uuid-1",
+    rootIdentifier: "PLAN-100",
+    teamId: "team-uuid-1",
+    status: "interviewing",
+    startedAt: new Date().toISOString(),
+    turnCount: 0,
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Read / Write
+// ---------------------------------------------------------------------------
+
+describe("readPlanningState", () => {
+  it("returns empty state when file missing", async () => {
+    const p = tmpStatePath();
+    const state = await readPlanningState(p);
+    expect(state.sessions).toEqual({});
+    expect(state.processedEvents).toEqual([]);
+  });
+
+  it("reads back written state", async () => {
+    const p = tmpStatePath();
+    const session = makePlanningSession();
+    const data: PlanningState = {
+      sessions: { "proj-1": session },
+      processedEvents: ["evt-1"],
+    };
+    await writePlanningState(data, p);
+    const state = await readPlanningState(p);
+    expect(state.sessions["proj-1"]).toBeDefined();
+    expect(state.sessions["proj-1"].projectId).toBe("proj-1");
+    expect(state.processedEvents).toEqual(["evt-1"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Register
+// ---------------------------------------------------------------------------
+
+describe("registerPlanningSession", () => {
+  it("registers and reads back", async () => {
+    const p = tmpStatePath();
+    const session = makePlanningSession();
+    await registerPlanningSession("proj-1", session, p);
+    const state = await readPlanningState(p);
+    const found = getPlanningSession(state, "proj-1");
+    expect(found).not.toBeNull();
+    expect(found!.projectId).toBe("proj-1");
+    expect(found!.projectName).toBe("Test Project");
+    expect(found!.status).toBe("interviewing");
+  });
+
+  it("overwrites existing session for same projectId", async () => {
+    const p = tmpStatePath();
+    const session1 = makePlanningSession({ projectName: "First" });
+    const session2 = makePlanningSession({ projectName: "Second" });
+    await registerPlanningSession("proj-1", session1, p);
+    await registerPlanningSession("proj-1", session2, p);
+    const state = await readPlanningState(p);
+    const found = getPlanningSession(state, "proj-1");
+    expect(found).not.toBeNull();
+    expect(found!.projectName).toBe("Second");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Update
+// ---------------------------------------------------------------------------
+
+describe("updatePlanningSession", () => {
+  it("increments turnCount", async () => {
+    const p = tmpStatePath();
+    await registerPlanningSession("proj-1", makePlanningSession({ turnCount: 2 }), p);
+    const updated = await updatePlanningSession("proj-1", { turnCount: 3 }, p);
+    expect(updated.turnCount).toBe(3);
+    const state = await readPlanningState(p);
+    expect(getPlanningSession(state, "proj-1")!.turnCount).toBe(3);
+  });
+
+  it("updates status", async () => {
+    const p = tmpStatePath();
+    await registerPlanningSession("proj-1", makePlanningSession(), p);
+    const updated = await updatePlanningSession("proj-1", { status: "plan_review" }, p);
+    expect(updated.status).toBe("plan_review");
+    const state = await readPlanningState(p);
+    expect(getPlanningSession(state, "proj-1")!.status).toBe("plan_review");
+  });
+
+  it("throws on missing session", async () => {
+    const p = tmpStatePath();
+    await expect(
+      updatePlanningSession("no-such-project", { turnCount: 1 }, p),
+    ).rejects.toThrow("No planning session for project no-such-project");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Get
+// ---------------------------------------------------------------------------
+
+describe("getPlanningSession", () => {
+  it("returns session by projectId", async () => {
+    const p = tmpStatePath();
+    await registerPlanningSession("proj-1", makePlanningSession(), p);
+    const state = await readPlanningState(p);
+    const session = getPlanningSession(state, "proj-1");
+    expect(session).not.toBeNull();
+    expect(session!.projectId).toBe("proj-1");
+  });
+
+  it("returns null for unknown projectId", async () => {
+    const p = tmpStatePath();
+    const state = await readPlanningState(p);
+    const session = getPlanningSession(state, "unknown-proj");
+    expect(session).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// End
+// ---------------------------------------------------------------------------
+
+describe("endPlanningSession", () => {
+  it("sets status to approved", async () => {
+    const p = tmpStatePath();
+    await registerPlanningSession("proj-1", makePlanningSession(), p);
+    await endPlanningSession("proj-1", "approved", p);
+    const state = await readPlanningState(p);
+    const session = getPlanningSession(state, "proj-1");
+    expect(session).not.toBeNull();
+    expect(session!.status).toBe("approved");
+  });
+
+  it("sets status to abandoned", async () => {
+    const p = tmpStatePath();
+    await registerPlanningSession("proj-1", makePlanningSession(), p);
+    await endPlanningSession("proj-1", "abandoned", p);
+    const state = await readPlanningState(p);
+    const session = getPlanningSession(state, "proj-1");
+    expect(session).not.toBeNull();
+    expect(session!.status).toBe("abandoned");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isInPlanningMode
+// ---------------------------------------------------------------------------
+
+describe("isInPlanningMode", () => {
+  it("true for interviewing", async () => {
+    const p = tmpStatePath();
+    await registerPlanningSession("proj-1", makePlanningSession({ status: "interviewing" }), p);
+    const state = await readPlanningState(p);
+    expect(isInPlanningMode(state, "proj-1")).toBe(true);
+  });
+
+  it("true for plan_review", async () => {
+    const p = tmpStatePath();
+    await registerPlanningSession("proj-1", makePlanningSession({ status: "plan_review" }), p);
+    const state = await readPlanningState(p);
+    expect(isInPlanningMode(state, "proj-1")).toBe(true);
+  });
+
+  it("false for approved", async () => {
+    const p = tmpStatePath();
+    await registerPlanningSession("proj-1", makePlanningSession({ status: "approved" }), p);
+    const state = await readPlanningState(p);
+    expect(isInPlanningMode(state, "proj-1")).toBe(false);
+  });
+
+  it("false for abandoned", async () => {
+    const p = tmpStatePath();
+    await registerPlanningSession("proj-1", makePlanningSession({ status: "abandoned" }), p);
+    const state = await readPlanningState(p);
+    expect(isInPlanningMode(state, "proj-1")).toBe(false);
+  });
+
+  it("false for missing project", async () => {
+    const p = tmpStatePath();
+    const state = await readPlanningState(p);
+    expect(isInPlanningMode(state, "no-such-project")).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// In-memory cache
+// ---------------------------------------------------------------------------
+
+describe("setPlanningCache / getActivePlanningByProjectId", () => {
+  beforeEach(() => {
+    clearPlanningCache("cache-proj-1");
+  });
+
+  it("round-trip in-memory + clearPlanningCache", () => {
+    const session = makePlanningSession({ projectId: "cache-proj-1" });
+    setPlanningCache(session);
+    const cached = getActivePlanningByProjectId("cache-proj-1");
+    expect(cached).not.toBeNull();
+    expect(cached!.projectId).toBe("cache-proj-1");
+    expect(cached!.projectName).toBe("Test Project");
+
+    clearPlanningCache("cache-proj-1");
+    const cleared = getActivePlanningByProjectId("cache-proj-1");
+    expect(cleared).toBeNull();
+  });
+});