@yannelli/paseo-linear-plugin 1.1.0-beta.0 → 1.1.0-beta.1

package/shared/activity.ts

@@ -87,6 +87,10 @@ function lineCount(value: string | null): number {
 }
 
 function diffCounts(detail: Record<string, unknown>): { added: number; removed: number } {
+  // Subagent transcripts send counts, not the text.
+  if (typeof detail.added === "number") {
+    return { added: detail.added, removed: typeof detail.removed === "number" ? detail.removed : 0 };
+  }
   const diff = text(detail.unifiedDiff);
   if (diff) {
     let added = 0;
@@ -228,7 +232,7 @@ export function deriveActivity(items: readonly TimelineItemLike[], cwd: string):
       if (path) touch(path, "read", order).reads += 1;
     } else if ((detail.type === "edit" || detail.type === "write") && raw) {
       const write = detail.type === "write";
-      const counts = write
+      const counts = write && typeof detail.added !== "number"
         ? { added: lineCount(text(detail.content)), removed: 0 }
         : diffCounts(detail);
       event.kind = write ? "write" : "edit";

package/shared/agent-hooks.ts

@@ -0,0 +1,68 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+import { GuidanceSchema } from "./settings";
+
+// Claude Code hooks for an agent started from an issue. The daemon writes them as a Claude Code
+// plugin and the launch passes its folder with --plugin-dir, so they never replace the settings
+// Paseo itself passes with --settings. Each hook only prints text; none of them runs project code.
+
+export const IDENTIFIER = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
+
+const HookIssueSchema = z.object({
+  identifier: z.string().regex(IDENTIFIER),
+  title: z.string(),
+  children: z.array(z.object({ identifier: z.string().regex(IDENTIFIER), title: z.string() })).max(100),
+});
+export type HookIssue = z.infer<typeof HookIssueSchema>;
+
+export const agentHooksRpc = defineRpc({
+  name: "linear.agent.hooks",
+  input: z.object({ issue: HookIssueSchema, guidance: GuidanceSchema }),
+  /** Null when no hook applies or the daemon host cannot run them. */
+  output: z.object({ pluginDir: z.string().nullable() }),
+});
+
+/** Single-quotes text for a POSIX shell. */
+export function shellQuote(text: string): string {
+  return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+
+function printHook(event: string, context: string) {
+  const output = { hookSpecificOutput: { hookEventName: event, additionalContext: context } };
+  return { type: "command", command: `printf '%s' ${shellQuote(JSON.stringify(output))}` };
+}
+
+function issueLines(issue: HookIssue): string[] {
+  const lines = [`Linear issue ${issue.identifier}: ${issue.title}`];
+  for (const child of issue.children.slice(0, 30)) lines.push(`- ${child.identifier}: ${child.title}`);
+  return lines;
+}
+
+/** The plugin's hooks.json, or null when no guidance option needs a hook. */
+export function claudeHooks(issue: HookIssue, guidance: z.infer<typeof GuidanceSchema>) {
+  const hooks: Record<string, unknown[]> = {};
+  if (guidance.subagentKeys) {
+    const context = [
+      `You are a subagent for ${issue.identifier}.`,
+      ...issueLines(issue),
+      "Put the key of the issue you work on in the first line of your reply, such as",
+      `"${issue.children[0]?.identifier ?? issue.identifier}: checked the form".`,
+      "If your work moves to another issue, state the new key.",
+    ].join("\n");
+    hooks.SubagentStart = [{ hooks: [printHook("SubagentStart", context)] }];
+  }
+  if (guidance.updateLinear || guidance.subagentKeys || guidance.paseoSubagents) {
+    // After compaction the summary can drop the issue, so restate it.
+    const context = [
+      `You work on ${issue.identifier}. The Linear rules in your first prompt still apply.`,
+      ...issueLines(issue),
+    ].join("\n");
+    hooks.SessionStart = [{ matcher: "compact", hooks: [printHook("SessionStart", context)] }];
+  }
+  return Object.keys(hooks).length > 0 ? { hooks } : null;
+}
+
+/** Claude Code plugin names are lowercase words joined by hyphens. */
+export function hookPluginName(identifier: string): string {
+  return `paseo-linear-${identifier.toLowerCase()}`;
+}

package/shared/agent-tools.ts

@@ -0,0 +1,130 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+import { IDENTIFIER } from "./agent-hooks";
+import type { IssueDetail } from "./linear";
+
+// The plugin's MCP server for agents started from an issue. It gives them Linear tools for
+// their issue tree and a way to start Paseo agents on its sub-issues. The daemon hosts it on
+// 127.0.0.1, and each agent gets its own bearer token.
+
+export const TOOLS_SERVER = "linear";
+/** Children get only the Linear tools, so agents never start agents of their own. */
+export const LINEAR_TOOLS = ["read_issue", "edit_issue"] as const;
+export const AGENT_TOOLS = ["start_agent", "wait_agent"] as const;
+
+export const McpHttpServerSchema = z.object({
+  type: z.literal("http"),
+  url: z.string().min(1),
+  headers: z.record(z.string(), z.string()).optional(),
+});
+
+export const ToolPolicySchema = z.object({
+  preapproved: z.array(z.object({ kind: z.literal("mcp"), server: z.string(), tool: z.string() })),
+});
+
+export const ToolScopeSchema = z.object({
+  /** The issue the launch started from. The tools reach it and its sub-issues. */
+  root: z.string().regex(IDENTIFIER),
+  /** The issue this agent works on, the default for read_issue and edit_issue. */
+  home: z.string().regex(IDENTIFIER),
+  /** The Paseo project whose Linear key loaded the issue. */
+  keyScope: z.string().nullable(),
+  workspaceId: z.string().min(1),
+  /** The agent config that started agents copy. */
+  config: z.object({
+    provider: z.string().min(1),
+    thinkingOptionId: z.string().optional(),
+    modeId: z.string().optional(),
+  }),
+});
+export type ToolScope = z.infer<typeof ToolScopeSchema>;
+
+export const agentToolsRpc = defineRpc({
+  name: "linear.agent.tools",
+  input: ToolScopeSchema,
+  output: z.object({
+    /** Goes in the agent's labels, so a tool call can find the agent that made it. */
+    grantId: z.string(),
+    server: McpHttpServerSchema,
+    toolPolicy: ToolPolicySchema,
+  }),
+});
+
+export function toolPolicy(tools: readonly string[]): z.infer<typeof ToolPolicySchema> {
+  return { preapproved: tools.map((tool) => ({ kind: "mcp" as const, server: TOOLS_SERVER, tool })) };
+}
+
+const IssueKey = z.string().regex(IDENTIFIER);
+
+export const ReadIssueInput = z.object({
+  issue: IssueKey.optional().describe("Issue key, such as ENG-12. The default is the issue you work on."),
+});
+
+export const EditIssueInput = z.object({
+  issue: IssueKey.optional().describe("Issue key, such as ENG-12. The default is the issue you work on."),
+  old_text: z
+    .string()
+    .describe("Exact text of the description to replace. It must occur one time. Use an empty string to add new_text at the end."),
+  new_text: z.string().describe("The text that replaces old_text."),
+});
+
+export const StartAgentInput = z.object({
+  issue: IssueKey.describe("Key of the sub-issue the agent works on."),
+  title: z.string().min(1).max(120).describe("Short title. Start it with the issue key."),
+  prompt: z.string().min(1).describe("The full task. The agent does not see your conversation."),
+  thinking: z
+    .string()
+    .optional()
+    .describe("Thinking option of the agent's model, such as low, medium, or high. The default is yours."),
+});
+
+export const WaitAgentInput = z.object({
+  agent_id: z.string().min(1),
+  timeout_seconds: z.number().int().min(1).max(600).default(50),
+});
+
+/** Replaces the one place where old text occurs. Empty old text adds the new text at the end. */
+export function editText(body: string, oldText: string, newText: string): { body: string } | { error: string } {
+  if (oldText === "") return { body: body.trimEnd() ? `${body.trimEnd()}\n\n${newText}` : newText };
+  const first = body.indexOf(oldText);
+  if (first < 0) return { error: "old_text is not in the description. Read the issue again, because it can change." };
+  if (body.indexOf(oldText, first + 1) >= 0) {
+    return { error: "old_text occurs more than one time. Add nearby lines so that it occurs one time." };
+  }
+  return { body: body.slice(0, first) + newText + body.slice(first + oldText.length) };
+}
+
+/** Counts Markdown task list items, so a reply can say how many are done. */
+export function taskCount(body: string): { done: number; total: number } {
+  const items = [...body.matchAll(/^\s*[-*+] \[([ xX])\]/gm)];
+  return { done: items.filter((item) => item[1] !== " ").length, total: items.length };
+}
+
+/** The issue as text for read_issue. */
+export function issueText(issue: IssueDetail): string {
+  const tasks = taskCount(issue.description ?? "");
+  const lines = [
+    `${issue.identifier}: ${issue.title}`,
+    `Status: ${issue.state.name}`,
+    `URL: ${issue.url}`,
+    tasks.total > 0 ? `Task list: ${tasks.done} of ${tasks.total} checked` : null,
+    "",
+    "Description:",
+    issue.description?.trim() || "(empty)",
+  ];
+  if (issue.children.length > 0) {
+    lines.push("", "Sub-issues:");
+    for (const child of issue.children) lines.push(`- ${child.identifier} [${child.state.name}]: ${child.title}`);
+  }
+  return lines.filter((line) => line !== null).join("\n");
+}
+
+/** Opens the prompt of an agent that start_agent makes. */
+export function childBrief(key: string, root: string): string {
+  const parent = key.toUpperCase() === root.toUpperCase() ? "" : `, a sub-issue of ${root}`;
+  return [
+    `You work on Linear issue ${key}${parent}. Start your first reply with "${key}:".`,
+    `Use the ${TOOLS_SERVER} MCP tools: read_issue shows the issue, and edit_issue changes its description.`,
+    "Check off each task list item you finish by replacing `- [ ]` with `- [x]`. Do not post comments.",
+  ].join("\n");
+}

package/shared/graph-camera.ts

@@ -0,0 +1,93 @@
+import type { Point } from "./graph-geometry";
+import type { Graph } from "./graph-model";
+
+// The graph camera shifts and zooms the canvas, which scales around its center. A canvas
+// point p draws at center + shift + zoom * (p - center). Zoom 1 with no shift shows it all.
+
+export interface Camera {
+  x: number;
+  y: number;
+  zoom: number;
+}
+
+export interface Box {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+
+export const FIT: Camera = { x: 0, y: 0, zoom: 1 };
+export const MIN_ZOOM = 1;
+export const MAX_ZOOM = 4;
+/** Auto mode zooms no further than this, so the nodes around the agents stay in view. */
+const AUTO_ZOOM = 2.5;
+const PAD_X = 90;
+const PAD_Y = 56;
+
+const clamp = (value: number, low: number, high: number) => Math.min(high, Math.max(low, value));
+
+/** Where a canvas point draws in the view. */
+export function project(camera: Camera, at: Point, width: number, height: number): Point {
+  return {
+    x: width / 2 + camera.x + camera.zoom * (at.x - width / 2),
+    y: height / 2 + camera.y + camera.zoom * (at.y - height / 2),
+  };
+}
+
+/** The canvas point that draws at a point of the view. */
+export function unproject(camera: Camera, at: Point, width: number, height: number): Point {
+  return {
+    x: width / 2 + (at.x - width / 2 - camera.x) / camera.zoom,
+    y: height / 2 + (at.y - height / 2 - camera.y) / camera.zoom,
+  };
+}
+
+/** Keeps the zoom in range and the canvas edges at or past the edges of the view. */
+export function clampCamera(camera: Camera, width: number, height: number): Camera {
+  const zoom = clamp(camera.zoom, MIN_ZOOM, MAX_ZOOM);
+  const spanX = ((zoom - 1) * width) / 2;
+  const spanY = ((zoom - 1) * height) / 2;
+  return { zoom, x: clamp(camera.x, -spanX, spanX), y: clamp(camera.y, -spanY, spanY) };
+}
+
+/** Zooms by a factor and keeps the canvas point under `at` where it is. */
+export function zoomAt(camera: Camera, at: Point, factor: number, width: number, height: number): Camera {
+  const zoom = clamp(camera.zoom * factor, MIN_ZOOM, MAX_ZOOM);
+  const cx = width / 2;
+  const cy = height / 2;
+  const px = cx + (at.x - cx - camera.x) / camera.zoom;
+  const py = cy + (at.y - cy - camera.y) / camera.zoom;
+  return clampCamera({ zoom, x: at.x - cx - zoom * (px - cx), y: at.y - cy - zoom * (py - cy) }, width, height);
+}
+
+/** Shows the box as large as fits in the view, up to the auto zoom. */
+export function frameBox(box: Box, width: number, height: number): Camera {
+  const fit = Math.min(width / Math.max(1, box.right - box.left), height / Math.max(1, box.bottom - box.top));
+  const zoom = clamp(fit, MIN_ZOOM, AUTO_ZOOM);
+  const x = zoom * (width / 2 - (box.left + box.right) / 2);
+  const y = zoom * (height / 2 - (box.top + box.bottom) / 2);
+  return clampCamera({ zoom, x, y }, width, height);
+}
+
+// The area auto mode shows: the nodes the running agents work on and their neighbors, with
+// room for labels and cursors. Null when no agent works on a node other than the issue.
+export function focusBox(graph: Graph, positions: ReadonlyMap<string, Point>, targets: Iterable<string>): Box | null {
+  const ids = new Set<string>();
+  for (const target of targets) if (target !== graph.root) ids.add(target);
+  if (ids.size === 0) return null;
+  for (const edge of graph.edges) {
+    if (ids.has(edge.from) && edge.to !== graph.root) ids.add(edge.to);
+    else if (ids.has(edge.to) && edge.from !== graph.root) ids.add(edge.from);
+  }
+  let box: Box | null = null;
+  for (const id of ids) {
+    const at = positions.get(id);
+    if (!at) continue;
+    box = box
+      ? { left: Math.min(box.left, at.x), top: Math.min(box.top, at.y), right: Math.max(box.right, at.x), bottom: Math.max(box.bottom, at.y) }
+      : { left: at.x, top: at.y, right: at.x, bottom: at.y };
+  }
+  if (!box) return null;
+  return { left: box.left - PAD_X, top: box.top - PAD_Y, right: box.right + PAD_X, bottom: box.bottom + PAD_Y };
+}

package/shared/live.ts

@@ -1,5 +1,6 @@
 import { defineRpc } from "@getpaseo/plugin";
 import { z } from "zod";
+import { McpHttpServerSchema, ToolPolicySchema } from "./agent-tools";
 import { IssueCardSchema, WorkflowStateSchema } from "./linear";
 
 // Contracts for Linear Live, todo sync, and project setup. Agents the plugin starts for itself
@@ -42,6 +43,8 @@ export const InitProposalSchema = z.object({
 });
 export type InitProposal = z.infer<typeof InitProposalSchema>;
 
+/** Files an explore run may list; the map and the graph show this many and more. */
+export const MAX_EXPLORE_FILES = 150;
 export const MAX_LIST_DIRS = 40;
 export const MAX_DIR_ENTRIES = 60;
 
@@ -64,6 +67,41 @@ export const linksRpc = defineRpc({
   }),
 });
 
+const SubagentLogSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+  description: z.string(),
+  /** The parent's call that started it, when Claude recorded one. */
+  toolUseId: z.string().nullable(),
+  updatedAt: z.number(),
+  /** Its last reply ended the run. */
+  finished: z.boolean(),
+  items: z.array(
+    z.object({
+      type: z.literal("tool_call"),
+      callId: z.string(),
+      name: z.string(),
+      status: z.enum(["running", "completed", "failed"]),
+      detail: z.record(z.string(), z.unknown()),
+    }),
+  ),
+});
+export type SubagentLog = z.infer<typeof SubagentLogSchema>;
+
+/** Tool calls of the subagents an agent started inside its provider. */
+export const subagentLogsRpc = defineRpc({
+  name: "linear.live.subagents",
+  input: z.object({ agentId: z.string().min(1) }),
+  output: z.object({ runs: z.array(SubagentLogSchema) }),
+});
+
+/** Forgets the saved explore map of the agent's issue, so the map falls back to ticket text. */
+export const clearMapRpc = defineRpc({
+  name: "linear.live.map.clear",
+  input: z.object({ agentId: z.string().min(1) }),
+  output: z.object({ cleared: z.boolean() }),
+});
+
 export const liveMapRpc = defineRpc({
   name: "linear.live.map",
   input: z.object({ identifier: z.string().min(1) }),
@@ -80,6 +118,11 @@ export const LaunchConfigSchema = z.object({
   provider: z.string().min(1),
   thinkingOptionId: z.string().optional(),
   modeId: z.string().optional(),
+  /** Only the folder of the issue's Claude Code hooks; see agent-hooks.ts. */
+  providerOptions: z.object({ extraArgs: z.object({ "plugin-dir": z.string().min(1) }) }).optional(),
+  /** Only the plugin's own MCP server; see agent-tools.ts. */
+  mcpServers: z.object({ linear: McpHttpServerSchema }).optional(),
+  toolPolicy: ToolPolicySchema.optional(),
 });
 
 // The daemon maps the files first and then starts the agent, so closing the app mid-way

package/shared/prompts.ts

@@ -1,5 +1,6 @@
+import { TOOLS_SERVER } from "./agent-tools";
 import type { IssueDetail } from "./linear";
-import type { AgentAction, LinearSettings, ProjectConfig } from "./settings";
+import type { AgentAction, Guidance, LinearSettings, ProjectConfig } from "./settings";
 import { todoConventionLine } from "./todo-sync";
 
 export const DEFAULT_TEMPLATES: Record<AgentAction, string> = {
@@ -112,6 +113,47 @@ export interface ComposePromptInput {
   project: ProjectConfig | null;
   includeComments: boolean;
   extraInstructions: string;
+  /** Launch options that add instructions; the project's saved ones when omitted. */
+  guidance?: Guidance;
+}
+
+/** The instructions each guidance option adds, in prompt order. */
+export function guidanceSections(issue: IssueDetail, guidance: Guidance): string[] {
+  const sections: string[] = [];
+  const example = issue.children[0]?.identifier ?? issue.identifier;
+  if (guidance.updateLinear) {
+    sections.push(
+      [
+        "Keep Linear current while you work:",
+        `- Start each todo with the issue key it is for, such as "${example}: add the form".`,
+        "- Mark a todo in progress when you start it and completed when it is done. Linear Live moves the issue from these todos.",
+        `- Use the ${TOOLS_SERVER} MCP tools: read_issue shows an issue, and edit_issue changes its description.`,
+        "- When you finish a task list item in a description, check it off: replace `- [ ] item` with `- [x] item`.",
+        "- When the plan changes, update the description. Do not post comments.",
+      ].join("\n"),
+    );
+  }
+  if (guidance.subagentKeys) {
+    sections.push(
+      [
+        "When you start a subagent:",
+        `- Begin its description and its prompt with the Linear issue key it works on, such as "${example}: review the form".`,
+        "- Tell it to put that key in the first line of its reply, and to state the new key if its work moves to another issue.",
+      ].join("\n"),
+    );
+  }
+  if (guidance.paseoSubagents) {
+    sections.push(
+      [
+        "Hand off work to Paseo agents, not to your built-in subagent tool:",
+        `- Start each one with the ${TOOLS_SERVER} start_agent tool, one agent for each sub-issue. It runs on your provider and model.`,
+        "- Set its thinking to fit the task: low for search and reading, medium for routine edits, high for design, debugging, and review.",
+        `- Start its title with the issue key, such as "${example}: write the tests". Give the full task in its prompt, because it does not see your conversation.`,
+        "- Call wait_agent for each agent and read its result before you continue.",
+      ].join("\n"),
+    );
+  }
+  return sections;
 }
 
 export function composePrompt(input: ComposePromptInput): string {
@@ -139,6 +181,8 @@ export function composePrompt(input: ComposePromptInput): string {
       `Project steps:\n${steps.map((step, index) => `${index + 1}. ${step}`).join("\n")}`,
     );
   }
+  const guidance = input.guidance ?? project?.guidance;
+  if (guidance) sections.push(...guidanceSections(issue, guidance));
   const extra = input.extraInstructions.trim();
   if (extra) sections.push(`Additional instructions:\n${extra}`);
   return sections.join("\n\n");
@@ -157,6 +201,10 @@ export const AGENT_LABELS = {
   project: "linear.project",
   explore: "linear.explore",
   init: "linear.init",
+  /** The grant of the agent's Linear MCP tools, so a tool call can find its agent. */
+  tools: "linear.tools",
+  /** The grant whose start_agent call made this agent. */
+  startedBy: "linear.started-by",
 } as const;
 
 /** Agents the plugin starts for itself: explore and project setup. */

package/shared/settings.ts

@@ -12,6 +12,18 @@ const ActionOverrideSchema = z.object({
   text: z.string().default(""),
 });
 
+/** Extra instructions the launch adds to the prompt. Saved per project. */
+export const GuidanceSchema = z.object({
+  /** Keep Linear current: todos with sub-issue keys, and comments when a Linear tool exists. */
+  updateLinear: z.boolean().default(false),
+  /** Subagents state the issue key they work on. Claude agents also get a hook that tells them. */
+  subagentKeys: z.boolean().default(false),
+  /** Hand work to Paseo agents on the same provider, with thinking that fits the task. */
+  paseoSubagents: z.boolean().default(false),
+});
+export type Guidance = z.infer<typeof GuidanceSchema>;
+export const GUIDANCE_KEYS = ["updateLinear", "subagentKeys", "paseoSubagents"] as const;
+
 export const ProjectConfigSchema = z.object({
   projectId: z.string(),
   displayName: z.string(),
@@ -21,9 +33,20 @@ export const ProjectConfigSchema = z.object({
   steps: z.array(z.string()).default([]),
   implement: ActionOverrideSchema.prefault({}),
   review: ActionOverrideSchema.prefault({}),
+  guidance: GuidanceSchema.prefault({}),
 });
 export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
 
+/** Settings with a project's guidance saved, adding the project when it has no entry yet. */
+export function withProjectGuidance(
+  values: LinearSettings,
+  project: { projectId: string; displayName: string; rootPath: string },
+  guidance: Guidance,
+): LinearSettings {
+  const known = values.projects.find((entry) => entry.projectId === project.projectId);
+  return { ...values, projects: upsertProject(values, { ...(known ?? emptyProjectConfig(project)), guidance }) };
+}
+
 export const ISOLATIONS = ["worktree", "workspace"] as const;
 export type Isolation = (typeof ISOLATIONS)[number];
 
@@ -31,6 +54,9 @@ export const MAPPING_MODES = ["semantic", "explore"] as const;
 export type MappingMode = (typeof MAPPING_MODES)[number];
 
 export const LIVE_VIEWS = ["map", "graph"] as const;
+/** Auto follows the running agents; fit shows the whole graph. */
+export const GRAPH_CAMERAS = ["auto", "fit"] as const;
+export type GraphCamera = (typeof GRAPH_CAMERAS)[number];
 export type LiveView = (typeof LIVE_VIEWS)[number];
 
 export const linearSettings = defineSettings({
@@ -57,9 +83,14 @@ export const linearSettings = defineSettings({
         enabled: z.boolean().default(true),
         mapping: z.enum(MAPPING_MODES).default("semantic"),
         exploreProvider: z.string().default(""),
+        /** Thinking option of the explore model; empty is the model's default. */
+        exploreEffort: z.string().default(""),
         syncTodos: z.boolean().default(false),
         view: z.enum(LIVE_VIEWS).default("map"),
         issuesCollapsed: z.boolean().default(false),
+        graphCamera: z.enum(GRAPH_CAMERAS).default("auto"),
+        /** The wheel and drags scroll the page instead of moving the graph. */
+        graphLocked: z.boolean().default(false),
       })
       .prefault({}),
     // Where the plugin works: every project, minus or plus per-project switches.