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

package/client/graph-labels.ts

@@ -0,0 +1,147 @@
+import { type LabelRequest, labelBox, labelSides, type Placed, type Point, placeLabels } from "../shared/graph-geometry";
+import { folderCenters, type Graph, type GraphNode } from "../shared/graph-model";
+import type { IssueDetail } from "../shared/linear";
+import { todoStatus } from "../shared/todo-sync";
+import type { IssueProgress } from "./live-issues";
+
+// Which labels the graph shows and where: issues first, then folder names, then the files the
+// agent works on, then touched files. A label that fits nowhere is hidden.
+
+const SIZES = { issue: 46, subissue: 32 } as const;
+export const HOVER_GAP = 22;
+
+/** About how wide a cursor caption draws. */
+export const captionWidth = (text: string | null) => (text ? Math.min(190, text.length * 6.2 + 18) : 0);
+const MAX_LABEL = 170;
+
+export function nodeSize(node: GraphNode): number {
+  if (node.kind !== "file") return SIZES[node.kind];
+  const touched = node.tile && node.tile.touch !== "none";
+  return touched ? (node.tile?.touch === "read" ? 12 : 14) : 9;
+}
+
+function clip(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
+}
+
+export interface Label {
+  left: number;
+  top: number;
+  width: number;
+  lines: readonly [string, string | null];
+}
+
+export interface FolderLabel {
+  folder: string;
+  left: number;
+  top: number;
+  width: number;
+}
+
+export interface LabelInput {
+  graph: Graph;
+  positions: ReadonlyMap<string, Placed>;
+  issue: IssueDetail;
+  progress: IssueProgress;
+  selected: string | null;
+  /** Nodes a running agent works on. */
+  working: ReadonlySet<string>;
+  /** Where each agent hovers, with the width of its caption and the side it shows on. */
+  cursors: readonly { at: Point; caption: number; flip: boolean }[];
+  width: number;
+  height: number;
+  /** Zoomed in, so files no agent touched get labels too when they fit. */
+  every?: boolean;
+}
+
+function linesOf(node: GraphNode, input: LabelInput): readonly [string, string | null] {
+  if (node.kind === "issue") return [node.label, clip(input.issue.title, 34)];
+  if (node.kind === "file") return [node.label, null];
+  const child = input.issue.children.find((entry) => entry.identifier.toUpperCase() === node.label);
+  const todos = input.progress.groups.get(node.label) ?? [];
+  const done = todos.filter((todo) => todoStatus(todo) === "completed").length;
+  const counts = todos.length > 0 ? `  ${done}/${todos.length}` : "";
+  const folded = node.folded > 0 ? `  +${node.folded}` : "";
+  return [`${node.label}${counts}${folded}`, clip(child?.title ?? "", 26)];
+}
+
+const textWidth = (text: string, perChar: number) => Math.min(MAX_LABEL, text.length * perChar + 4);
+
+export function graphLabels(input: LabelInput): { nodes: Map<string, Label>; folders: FolderLabel[] } {
+  const { graph, positions, selected, working } = input;
+  const order = (node: GraphNode) =>
+    node.id === selected
+      ? 0
+      : node.kind === "issue"
+        ? 1
+        : node.kind === "subissue"
+          ? 2
+          : working.has(node.id)
+            ? 4
+            : (node.tile?.touch ?? "none") !== "none"
+              ? 5
+              : 6;
+  const wanted = graph.nodes.filter((node) => input.every || order(node) < 6).sort((a, b) => order(a) - order(b));
+  const lines = new Map<string, readonly [string, string | null]>();
+  const requests: LabelRequest[] = [];
+  const push = (node: GraphNode) => {
+    const at = positions.get(node.id);
+    if (!at) return;
+    const text = linesOf(node, input);
+    const perChar = node.kind === "issue" ? 7.4 : 6.2;
+    const width = Math.max(textWidth(text[0], perChar), text[1] ? textWidth(text[1], 5.6) : 0);
+    const height = text[1] ? 28 : 14;
+    const spotsFor = (w: number, h: number) =>
+      labelSides(at.side).map((side) => labelBox({ ...at, side }, nodeSize(node) / 2, w, h));
+    const short = textWidth(text[0], perChar);
+    lines.set(node.id, text);
+    requests.push({
+      id: node.id,
+      width,
+      height,
+      spots: spotsFor(width, height),
+      fallback: text[1] ? { width: short, height: 14, spots: spotsFor(short, 14) } : undefined,
+    });
+  };
+  for (const node of wanted.filter((entry) => order(entry) <= 2)) push(node);
+  // Folder names sit above each neighborhood, after the issues and before single files.
+  const folderIds = new Map<string, string>();
+  for (const center of folderCenters(graph, positions)) {
+    const name = center.folder === "." ? "/" : `${center.folder}/`;
+    const width = textWidth(name, 6);
+    const id = `folder:${center.folder}`;
+    folderIds.set(id, center.folder);
+    requests.push({ id, width, height: 14, spots: [{ left: center.x - width / 2, top: center.top - 30 }, { left: center.x - width / 2, top: center.y - 7 }] });
+  }
+  for (const node of wanted.filter((entry) => order(entry) > 2)) push(node);
+  const shapes: { at: Point; radius: number }[] = graph.nodes.flatMap((node) => {
+    const at = positions.get(node.id);
+    return at ? [{ at, radius: nodeSize(node) / 2 }] : [];
+  });
+  // Keep labels out from under the agents and their captions, as a row of small circles.
+  for (const cursor of input.cursors) {
+    shapes.push({ at: cursor.at, radius: 16 });
+    for (let offset = 24; offset < cursor.caption + 24; offset += 14) {
+      shapes.push({ at: { x: cursor.at.x + (cursor.flip ? -offset : offset), y: cursor.at.y }, radius: 10 });
+    }
+  }
+  const sizes = new Map(requests.map((request) => [request.id, request]));
+  const nodes = new Map<string, Label>();
+  const folders: FolderLabel[] = [];
+  for (const [id, box] of placeLabels(requests, input.width, input.height, shapes)) {
+    const request = sizes.get(id) as LabelRequest;
+    const folder = folderIds.get(id);
+    if (folder !== undefined) {
+      folders.push({ folder, left: box.left, top: box.top, width: request.width });
+      continue;
+    }
+    const text = lines.get(id) ?? ["", null];
+    nodes.set(id, {
+      left: box.left,
+      top: box.top,
+      width: (box.short ? request.fallback?.width : request.width) ?? 0,
+      lines: box.short ? [text[0], null] : text,
+    });
+  }
+  return { nodes, folders };
+}

package/client/launch-choices.ts

@@ -2,7 +2,7 @@ import { usePaseo } from "@getpaseo/plugin/client";
 import { useQuery } from "@tanstack/react-query";
 import { useCallback, useMemo, useState } from "react";
 import type { IssueDetail } from "../shared/linear";
-import type { AgentAction, LinearSettings } from "../shared/settings";
+import { type AgentAction, type LinearSettings, projectEnabled } from "../shared/settings";
 import { type AgentPicks, resolveAgent } from "./agent-options";
 import { loadAgentPreferences } from "./agent-preferences";
 import {
@@ -41,7 +41,15 @@ export function useLaunchChoices(input: {
   target: TargetWorkspace | null;
 }) {
   const { issue, settings, action } = input;
-  const projects = useProjects();
+  const allProjects = useProjects();
+  // Projects where Linear is off are not offered as launch targets.
+  const projects = useMemo(
+    () => ({
+      ...allProjects,
+      data: allProjects.data?.filter((entry) => projectEnabled(settings.access, entry.projectId)),
+    }),
+    [allProjects, settings.access],
+  );
   const providers = useProviders();
   const { target } = input;
   const prNumber = action === "review" ? pullRequestNumber(issue) : null;
@@ -54,10 +62,13 @@ export function useLaunchChoices(input: {
   const [placementChoice, setPlacementChoice] = useState<Placement | null>(null);
   const [picks, setPicks] = useState<AgentPicks>(NO_PICKS);
   const [remembered] = useState(loadAgentPreferences);
-  const projectId =
+  const preferredId =
     projectChoice ??
     defaultProjectId({ target, teamId: issue.team.id, settings, projects: projects.data });
-  const project = projects.data?.find((entry) => entry.projectId === projectId) ?? null;
+  const project =
+    projects.data?.find((entry) => entry.projectId === preferredId) ??
+    (projectChoice ? null : (projects.data?.[0] ?? null));
+  const projectId = project?.projectId ?? preferredId;
   const placements = useMemo(
     () =>
       placementOptions({

package/client/launch-guidance.tsx

@@ -0,0 +1,86 @@
+import { useSettings } from "@getpaseo/plugin/client";
+import { useCallback, useMemo, useState } from "react";
+import { Switch, Text, View } from "react-native";
+import {
+  GUIDANCE_KEYS,
+  type Guidance,
+  GuidanceSchema,
+  linearSettings,
+  type ProjectConfig,
+  withProjectGuidance,
+} from "../shared/settings";
+import type { PaseoProjectOption } from "./queries";
+import type { Theme } from "./ui";
+
+// Launch options that add instructions to the prompt. Each project keeps its own choices, so
+// the next launch in the project starts with them.
+
+const DEFAULT_GUIDANCE = GuidanceSchema.parse({});
+
+const COPY: Record<(typeof GUIDANCE_KEYS)[number], { label: string; hint: string }> = {
+  updateLinear: {
+    label: "Keep Linear updated",
+    hint: "The agent edits the issue description and checks off task list items as it works, with the plugin's Linear tools. It posts no comments. Todos start with issue keys, so status sync can move each sub-issue.",
+  },
+  subagentKeys: {
+    label: "Subagents state their issue key",
+    hint: "Subagents open with the key of the issue they work on and state the new key when it changes. Claude agents also get a hook that tells each subagent.",
+  },
+  paseoSubagents: {
+    label: "Hand off work to Paseo agents",
+    hint: "The agent starts one Paseo agent for each sub-issue with the plugin's tools, on its own provider and model. Each one checks off its own items, and Linear Live shows its work.",
+  },
+};
+
+/** The project's guidance, changed locally at once and saved to the project in the background. */
+export function useProjectGuidance(project: PaseoProjectOption | null, config: ProjectConfig | null) {
+  const settings = useSettings(linearSettings);
+  const [edits, setEdits] = useState<Record<string, Guidance>>({});
+  const guidance = (project ? edits[project.projectId] : undefined) ?? config?.guidance ?? DEFAULT_GUIDANCE;
+  const change = useCallback(
+    (key: (typeof GUIDANCE_KEYS)[number], value: boolean) => {
+      if (!project) return;
+      const next = { ...guidance, [key]: value };
+      setEdits((current) => ({ ...current, [project.projectId]: next }));
+      if (settings.status === "ready") void settings.save(withProjectGuidance(settings.values, project, next), settings.revision);
+    },
+    [project, guidance, settings],
+  );
+  return { guidance, change };
+}
+
+export function GuidanceToggles(props: {
+  theme: Theme;
+  guidance: Guidance;
+  onChange(key: (typeof GUIDANCE_KEYS)[number], value: boolean): void;
+}) {
+  const { colors } = props.theme;
+  const styles = useMemo(
+    () => ({
+      row: { flexDirection: "row" as const, alignItems: "center" as const, gap: 10, paddingVertical: 4 },
+      body: { flex: 1, gap: 2 },
+      label: { color: colors.foreground, fontSize: 14 },
+      hint: { color: colors.foregroundMuted, fontSize: 12 },
+      track: { true: colors.accent, false: colors.surface2 },
+    }),
+    [colors],
+  );
+  return (
+    <View>
+      {GUIDANCE_KEYS.map((key) => (
+        <View key={key} style={styles.row}>
+          <View style={styles.body}>
+            <Text style={styles.label}>{COPY[key].label}</Text>
+            <Text style={styles.hint}>{COPY[key].hint}</Text>
+          </View>
+          <Switch
+            accessibilityLabel={COPY[key].label}
+            value={props.guidance[key]}
+            onValueChange={(value) => props.onChange(key, value)}
+            trackColor={styles.track}
+          />
+        </View>
+      ))}
+    </View>
+  );
+}

package/client/launch-plan.ts

@@ -1,3 +1,4 @@
+import type { RpcOutput } from "@getpaseo/plugin";
 import { usePaseo, useRpc } from "@getpaseo/plugin/client";
 import { useMutation } from "@tanstack/react-query";
 import {
@@ -7,8 +8,11 @@ import {
   updateIssueRpc,
   type WorkflowState,
 } from "../shared/linear";
+import { agentHooksRpc } from "../shared/agent-hooks";
+import { agentToolsRpc, TOOLS_SERVER } from "../shared/agent-tools";
+import { launchAfterExploreRpc } from "../shared/live";
 import { AGENT_LABELS, agentTitle } from "../shared/prompts";
-import type { AgentAction, Isolation, LinearSettings } from "../shared/settings";
+import type { AgentAction, Guidance, Isolation, LinearSettings } from "../shared/settings";
 import { type AgentSelection, agentConfig } from "./agent-options";
 import { rememberLaunch } from "./agent-preferences";
 import type { PaseoProjectOption } from "./queries";
@@ -141,6 +145,27 @@ export interface LaunchRequest {
   started: WorkflowState | null;
   /** The Paseo project whose Linear key loaded the issue. */
   keyScope: string | null;
+  /** Maps the files with the read-only explore agent first, then starts the agent. */
+  explore: boolean;
+  /** Guidance options; for Claude some also add hooks. */
+  guidance: Guidance;
+}
+
+type AgentTools = RpcOutput<typeof agentToolsRpc>;
+
+/** The config with the plugin's MCP server, whose token only reaches this issue tree. */
+export function withLinearTools<C extends object>(config: C, tools: Pick<AgentTools, "server" | "toolPolicy"> | null) {
+  if (!tools) return config;
+  return { ...config, mcpServers: { [TOOLS_SERVER]: tools.server }, toolPolicy: tools.toolPolicy };
+}
+
+/** The issue's guidance needs the MCP tools: Linear edits, or agents started on sub-issues. */
+export const needsLinearTools = (guidance: Guidance) => guidance.updateLinear || guidance.paseoSubagents;
+
+/** The config with the issue's Claude Code hooks, loaded as a plugin with --plugin-dir. */
+export function withHookPlugin<C extends object>(config: C, pluginDir: string | null) {
+  if (!pluginDir) return config;
+  return { ...config, providerOptions: { extraArgs: { "plugin-dir": pluginDir } } };
 }
 
 export type Paseo = ReturnType<typeof usePaseo>;
@@ -213,16 +238,71 @@ export function useLaunchAgent() {
   const paseo = usePaseo();
   const updateIssue = useRpc(updateIssueRpc);
   const attachCard = useRpc(attachIssueCardRpc);
+  const launchAfterExplore = useRpc(launchAfterExploreRpc);
+  const prepareHooks = useRpc(agentHooksRpc);
+  const prepareTools = useRpc(agentToolsRpc);
   return useMutation({
     mutationFn: async (request: LaunchRequest) => {
       const { issue, action } = request;
       const workspace = await openWorkspace(paseo, request);
-      const agent = await workspace.agents.create({
-        config: agentConfig(request.agent),
+      const state = request.patch.stateId && request.started ? request.started : issue.state;
+      const card = {
+        identifier: issue.identifier,
+        title: issue.title,
+        url: issue.url,
+        stateName: state.name,
+        stateColor: state.color,
+        action,
+      };
+      // Hooks are a Claude Code feature; a failure to write them never blocks the launch.
+      const hooks =
+        request.agent.agent.id === "claude"
+          ? await prepareHooks({
+              issue: {
+                identifier: issue.identifier,
+                title: issue.title,
+                children: issue.children.map(({ identifier, title }) => ({ identifier, title })),
+              },
+              guidance: request.guidance,
+            }).catch(() => null)
+          : null;
+      const config = agentConfig(request.agent);
+      // Without the tools the agent still starts; its prompt then names tools it does not have.
+      const tools = needsLinearTools(request.guidance)
+        ? await prepareTools({
+            root: issue.identifier,
+            home: issue.identifier,
+            keyScope: request.keyScope,
+            workspaceId: workspace.id,
+            config,
+          }).catch(() => null)
+        : null;
+      const agent = {
+        config: withLinearTools(withHookPlugin(config, hooks?.pluginDir ?? null), tools),
         title: agentTitle(action, issue),
         prompt: request.prompt,
-        labels: { [AGENT_LABELS.issue]: issue.identifier, [AGENT_LABELS.action]: action },
-      });
+        labels: {
+          [AGENT_LABELS.issue]: issue.identifier,
+          [AGENT_LABELS.action]: action,
+          ...(request.keyScope ? { [AGENT_LABELS.project]: request.keyScope } : {}),
+          ...(tools ? { [AGENT_LABELS.tools]: tools.grantId } : {}),
+        },
+      };
+      // The daemon starts the agent once the map is ready, so agentId is null until then.
+      let agentId: string | null;
+      if (request.explore && action === "implement") {
+        const launched = await launchAfterExplore({
+          workspaceId: workspace.id,
+          identifier: issue.identifier,
+          keyScope: request.keyScope,
+          agent,
+          card,
+        });
+        agentId = launched.agentId;
+      } else {
+        agentId = (await workspace.agents.create(agent)).id;
+        void attachCard({ agentId, card }).catch(() => undefined);
+      }
       lastProjectByTeam.set(issue.team.id, request.project.projectId);
       rememberLaunch({
         agent: request.agent.agent.id,
@@ -238,17 +318,7 @@ export function useLaunchAgent() {
           warning = errorMessage(error);
         }
       }
-      const state = request.patch.stateId && request.started ? request.started : issue.state;
-      const card = {
-        identifier: issue.identifier,
-        title: issue.title,
-        url: issue.url,
-        stateName: state.name,
-        stateColor: state.color,
-        action,
-      };
-      void attachCard({ agentId: agent.id, card }).catch(() => undefined);
-      return { agentId: agent.id, warning };
+      return { agentId, workspaceId: workspace.id, warning };
     },
   });
 }

package/client/launch.tsx

@@ -15,6 +15,7 @@ import { modeIcon, optionLabel } from "./agent-options";
 import { useKeyScope } from "./key-scope";
 import { type LaunchChoices, useLaunchChoices } from "./launch-choices";
 import { Chip, Field, Toggle } from "./launch-fields";
+import { GuidanceToggles, useProjectGuidance } from "./launch-guidance";
 import { linearPatch, type TargetWorkspace, useLaunchAgent } from "./launch-plan";
 import { ModelBrowser } from "./model-browser";
 import { PickerModal } from "./pickers";
@@ -157,6 +158,7 @@ function LaunchComposer(props: LaunchPageProps & { issue: IssueDetail; settings:
   // Null until the user types. Until then the prompt follows the template and options.
   const [customPrompt, setCustomPrompt] = useState<string | null>(null);
   const { projectConfig } = choices;
+  const { guidance, change: changeGuidance } = useProjectGuidance(choices.project, projectConfig);
   const generated = useMemo(
     () =>
       composePrompt({
@@ -166,8 +168,9 @@ function LaunchComposer(props: LaunchPageProps & { issue: IssueDetail; settings:
         project: projectConfig,
         includeComments,
         extraInstructions: "",
+        guidance,
       }),
-    [action, issue, settings, projectConfig, includeComments],
+    [action, issue, settings, projectConfig, includeComments, guidance],
   );
   const prompt = customPrompt ?? generated;
   const styles = useMemo(() => {
@@ -271,15 +274,21 @@ function LaunchComposer(props: LaunchPageProps & { issue: IssueDetail; settings:
         patch,
         started,
         keyScope,
+        guidance,
+        explore: settings.live.enabled && settings.live.mapping === "explore",
       },
       {
-        onSuccess: ({ agentId, warning }) => {
+        onSuccess: ({ agentId, workspaceId, warning }) => {
           void queries.invalidateQueries({ queryKey: ["linear"] });
+          const started = agentId
+            ? "Agent started."
+            : "Mapping files first. The agent starts when the map is ready.";
           if (warning) {
-            toast.show(`Agent started. Linear was not updated: ${warning}`, { variant: "warning" });
-          } else toast.show("Agent started", { variant: "success" });
+            toast.show(`${started} Linear was not updated: ${warning}`, { variant: "warning" });
+          } else toast.show(started, { variant: "success" });
           onStarted();
-          navigation?.openAgent({ agentId });
+          if (agentId) navigation?.openAgent({ agentId });
+          else navigation?.openWorkspace({ workspaceId });
         },
       },
     );
@@ -296,6 +305,7 @@ function LaunchComposer(props: LaunchPageProps & { issue: IssueDetail; settings:
     issue,
     prompt,
     keyScope,
+    guidance,
     queries,
     toast,
     onStarted,
@@ -438,6 +448,10 @@ function LaunchComposer(props: LaunchPageProps & { issue: IssueDetail; settings:
             />
           ) : null}
         </View>
+        <View style={styles.group}>
+          <SectionLabel theme={theme}>Agent guidance</SectionLabel>
+          <GuidanceToggles theme={theme} guidance={guidance} onChange={changeGuidance} />
+        </View>
         {launch.error ? (
           <Text accessibilityRole="alert" style={styles.error}>
             {errorMessage(launch.error)}