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

package/server/knowledge.ts

@@ -0,0 +1,157 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import {
+  knowledgeGetRpc,
+  knowledgeInspectRpc,
+  type ProjectBrief,
+  type ProjectKnowledge,
+  ProjectKnowledgeSchema,
+  topFolders,
+} from "../shared/knowledge";
+import type { Paseo } from "./agent-runs";
+import { inspectProject } from "./inspect";
+import { createJsonFile, type JsonFile } from "./stores";
+
+/** Knowledge older than this is inspected again before use; summaries carry over. */
+export const KNOWLEDGE_MAX_AGE_MS = 6 * 60 * 60_000;
+
+export interface KnowledgeProject {
+  projectId: string;
+  rootPath: string;
+}
+
+/** What the setup agent learned: a line on the project and one per area. */
+export interface KnowledgeNotes {
+  summary: string;
+  areas: readonly { path: string; summary: string }[];
+}
+
+export interface KnowledgeService {
+  get(projectId: string): Promise<ProjectKnowledge | null>;
+  /** Saved knowledge, inspected again when missing, stale, or from another folder. */
+  ensure(project: KnowledgeProject): Promise<ProjectKnowledge>;
+  /** Inspects now. Runs for one project share one inspection. */
+  inspect(project: KnowledgeProject): Promise<ProjectKnowledge>;
+  annotate(projectId: string, notes: KnowledgeNotes): Promise<void>;
+}
+
+type Inspect = (rootPath: string, projectId: string) => Promise<ProjectKnowledge>;
+
+function areaPath(value: string): string {
+  const trimmed = value.trim().replace(/^(?:\.\/)+/, "").replace(/^\/+|\/+$/g, "");
+  return trimmed === "" || trimmed === "." ? "" : `${trimmed}/`;
+}
+
+/** One file per project beside the key file, so each loads only when used. */
+export function createKnowledge(
+  directory: string,
+  inspect: Inspect = inspectProject,
+  now = () => Date.now(),
+): KnowledgeService {
+  const files = new Map<string, JsonFile<ProjectKnowledge | null>>();
+  const running = new Map<string, Promise<ProjectKnowledge>>();
+  const fileFor = (projectId: string) => {
+    let file = files.get(projectId);
+    if (!file) {
+      const name = createHash("sha256").update(projectId).digest("hex").slice(0, 32);
+      file = createJsonFile(path.join(directory, `${name}.json`), ProjectKnowledgeSchema.nullable(), () => null);
+      files.set(projectId, file);
+    }
+    return file;
+  };
+  const get = async (projectId: string) => {
+    const known = await fileFor(projectId).read();
+    return known?.projectId === projectId ? known : null;
+  };
+
+  function inspectNow(project: KnowledgeProject): Promise<ProjectKnowledge> {
+    const existing = running.get(project.projectId);
+    if (existing) return existing;
+    const work = (async () => {
+      const fresh = await inspect(project.rootPath, project.projectId);
+      return fileFor(project.projectId).update((previous) => {
+        const summaries = new Map((previous?.areas ?? []).map((area) => [area.path, area.summary]));
+        const next: ProjectKnowledge = {
+          ...fresh,
+          areas: fresh.areas.map((area) => ({ ...area, summary: summaries.get(area.path) ?? area.summary })),
+          summary: previous?.summary ?? fresh.summary,
+          summarizedAt: previous?.summarizedAt ?? fresh.summarizedAt,
+        };
+        return { next, result: next };
+      });
+    })().finally(() => running.delete(project.projectId));
+    running.set(project.projectId, work);
+    return work;
+  }
+
+  return {
+    get,
+    inspect: inspectNow,
+    async ensure(project) {
+      const known = await get(project.projectId);
+      const age = known ? now() - Date.parse(known.inspectedAt) : Number.POSITIVE_INFINITY;
+      if (known && known.rootPath === project.rootPath && age < KNOWLEDGE_MAX_AGE_MS) return known;
+      // A failed inspection keeps the saved knowledge rather than losing it.
+      return inspectNow(project).catch((error: unknown) => {
+        if (known) return known;
+        throw error;
+      });
+    },
+    async annotate(projectId, notes) {
+      await fileFor(projectId).update((current) => {
+        if (!current) return { next: current, result: undefined };
+        const summaries = new Map(notes.areas.map((area) => [areaPath(area.path), area.summary.trim()]));
+        const next: ProjectKnowledge = {
+          ...current,
+          summary: notes.summary.trim() || current.summary,
+          summarizedAt: new Date(now()).toISOString(),
+          areas: current.areas.map((area) => ({ ...area, summary: summaries.get(area.path) || area.summary })),
+        };
+        return { next, result: undefined };
+      });
+    },
+  };
+}
+
+export function toBrief(knowledge: ProjectKnowledge): ProjectBrief {
+  const { files, ...rest } = knowledge;
+  return { ...rest, folders: topFolders(files) };
+}
+
+/** A Paseo project on this host; the client names only an id, never a folder. */
+export async function findProject(paseo: Paseo, projectId: string): Promise<KnowledgeProject | null> {
+  const { projects } = await paseo.projects.list();
+  const project = projects.find((entry) => entry.projectId === projectId);
+  return project ? { projectId, rootPath: project.projectRootPath } : null;
+}
+
+/** Knowledge for prompts and maps; null when the project is unknown or cannot be read. */
+export async function knowledgeFor(
+  paseo: Paseo,
+  knowledge: KnowledgeService,
+  projectId: string | null,
+): Promise<ProjectKnowledge | null> {
+  if (!projectId) return null;
+  try {
+    const project = await findProject(paseo, projectId);
+    return project ? await knowledge.ensure(project) : await knowledge.get(projectId);
+  } catch (error) {
+    console.error(`Linear could not inspect project ${projectId}`, error);
+    return null;
+  }
+}
+
+export function registerKnowledge(server: PluginServerContext, knowledge: KnowledgeService) {
+  async function requireProject(paseo: Paseo, projectId: string) {
+    const project = await findProject(paseo, projectId);
+    if (!project) throw new Error("That project is not on this host");
+    return project;
+  }
+  server.handle(knowledgeGetRpc, async ({ projectId }, { paseo }) => ({
+    knowledge: toBrief(await knowledge.ensure(await requireProject(paseo, projectId))),
+  }));
+  server.handle(knowledgeInspectRpc, async ({ projectId }, { paseo }) => ({
+    knowledge: toBrief(await knowledge.inspect(await requireProject(paseo, projectId))),
+  }));
+}

package/server/live.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { z } from "zod";
 import { relativePath } from "../shared/activity";
+import { knowledgeLines, liveProjectRpc, type ProjectKnowledge, resolvePaths, toAreaRef } from "../shared/knowledge";
 import { type IssueDetail, ISSUE_CARD_KIND } from "../shared/linear";
 import {
   ExploreResultSchema,
@@ -29,6 +30,7 @@ import {
   startInternalRun,
 } from "./agent-runs";
 import type { LinearAccess } from "./handlers";
+import { type KnowledgeService, knowledgeFor } from "./knowledge";
 import { fileLinks } from "./links";
 import { subagentLogs } from "./subagent-logs";
 import type { LaunchQueue, MapStore } from "./stores";
@@ -97,8 +99,9 @@ export async function listDirectories(cwd: string, dirs: readonly string[]) {
   return results;
 }
 
-export function explorePrompt(issue: IssueDetail): string {
+export function explorePrompt(issue: IssueDetail, knowledge: ProjectKnowledge | null = null): string {
   const keys = [issue.identifier, ...issue.children.map((child) => child.identifier)];
+  const map = knowledgeLines(knowledge);
   return [
     `Map this repository for Linear issue ${issue.identifier}: ${issue.title}`,
     "",
@@ -106,6 +109,7 @@ export function explorePrompt(issue: IssueDetail): string {
     "",
     issueSnapshot(issue, { includeComments: false }),
     "",
+    ...(map.length > 0 ? [...map, ""] : []),
     "List the files an engineer will most likely read or change for this issue and each sub-issue.",
     `Include files that will probably be created, at their expected path. List at most ${MAX_EXPLORE_FILES} files.`,
     `Set "issue" to the sub-issue key the file belongs to, or ${issue.identifier} for the whole issue.`,
@@ -138,6 +142,7 @@ export interface LiveDependencies {
   access: LinearAccess;
   maps: MapStore;
   launches: LaunchQueue;
+  knowledge: KnowledgeService;
   readSettings(): Promise<LinearSettings | null>;
 }
 
@@ -159,7 +164,7 @@ export async function startLaunch(workspace: WorkspaceHandle, launch: LaunchInpu
 }
 
 export function registerLive(server: PluginServerContext, dependencies: LiveDependencies) {
-  const { access, maps, launches, readSettings } = dependencies;
+  const { access, maps, launches, knowledge, readSettings } = dependencies;
   const jobs = createJobStore<IssueMap>();
   const recovering = new Map<string, Promise<Job | null>>();
   const recoveredAt = new Map<string, number>();
@@ -230,6 +235,14 @@ export function registerLive(server: PluginServerContext, dependencies: LiveDepe
     return { links: await fileLinks(agent.cwd, files) };
   });
 
+  server.handle(liveProjectRpc, async ({ agentId, paths }, { paseo }) => {
+    const agent = await agentInfo(paseo, agentId);
+    const known = await knowledgeFor(paseo, knowledge, agent.projectId);
+    if (!known) return { areas: [], resolved: [] };
+    const resolved = [...resolvePaths(paths, known.files)].map(([from, to]) => ({ from, to }));
+    return { areas: known.areas.map(toAreaRef), resolved };
+  });
+
   server.handle(clearMapRpc, async ({ agentId }, { paseo }) => {
     const agent = await agentInfo(paseo, agentId);
     const identifier = agent.labels[AGENT_LABELS.issue];
@@ -267,6 +280,8 @@ export function registerLive(server: PluginServerContext, dependencies: LiveDepe
   interface ExploreTarget {
     identifier: string;
     keyScope: string | null;
+    /** Paseo project whose saved knowledge goes into the prompt. */
+    projectId: string | null;
     cwd: string;
     /** Opened only when a new run starts. */
     workspace: () => Promise<WorkspaceHandle>;
@@ -293,6 +308,7 @@ export function registerLive(server: PluginServerContext, dependencies: LiveDepe
       const issue = await linear.getIssue(identifier);
       const labels: Record<string, string> = { [AGENT_LABELS.explore]: identifier };
       if (target.keyScope) labels[AGENT_LABELS.project] = target.keyScope;
+      const known = await knowledgeFor(paseo, knowledge, target.projectId);
       const run = await startInternalRun({
         paseo,
         workspace: await target.workspace(),
@@ -300,7 +316,7 @@ export function registerLive(server: PluginServerContext, dependencies: LiveDepe
         provider: target.provider,
         effort: target.effort,
         title: `Explore ${identifier}`,
-        prompt: explorePrompt(issue),
+        prompt: explorePrompt(issue, known),
         labels,
         schema: ExploreResultSchema,
         timeoutMs: EXPLORE_TIMEOUT_MS,
@@ -326,6 +342,7 @@ export function registerLive(server: PluginServerContext, dependencies: LiveDepe
     const job = await ensureExplore(paseo, {
       identifier,
       keyScope: agent.labels[AGENT_LABELS.project] ?? null,
+      projectId: agent.projectId,
       cwd,
       workspace: async () =>
         workspaceId ? paseo.workspaces.ref(workspaceId) : paseo.workspaces.open(cwd),
@@ -344,6 +361,7 @@ export function registerLive(server: PluginServerContext, dependencies: LiveDepe
     const job = await ensureExplore(paseo, {
       identifier: input.identifier,
       keyScope: input.keyScope,
+      projectId: info.projectId,
       cwd: info.workspaceDirectory ?? info.projectRootPath,
       workspace: async () => workspace,
       provider: settings?.live.exploreProvider || input.agent.config.provider,

package/server/stores.ts

@@ -7,7 +7,7 @@ const MAX_MAPS = 200;
 /** A launch still waiting after this long is dropped, so a stale one never starts by surprise. */
 export const PENDING_LAUNCH_MAX_AGE_MS = 60 * 60_000;
 
-interface JsonFile<T> {
+export interface JsonFile<T> {
   read(): Promise<T>;
   /** Changes run one at a time, so a read, change, and write never interleave. */
   update<R>(change: (current: T) => { next: T; result: R }): Promise<R>;

package/shared/custom-icon.ts

@@ -0,0 +1,148 @@
+import { z } from "zod";
+
+// The user's own plugin icon. The web app draws it as an image, which never runs scripts or
+// loads files; the checks below also refuse such content. Paint recolors every visible pixel,
+// and Solid fills shapes that only have an outline.
+
+export const ICON_PAINTS = ["original", "theme", "accent", "linear", "custom"] as const;
+export type IconPaint = (typeof ICON_PAINTS)[number];
+
+/** Linear's brand indigo, the plugin's own color. */
+export const LINEAR_INDIGO = "#5E6AD2";
+export const MAX_SVG_LENGTH = 64_000;
+export const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+
+export const IconSettingsSchema = z.object({
+  /** Checked SVG markup. Empty uses the built-in icon. */
+  svg: z.string().max(MAX_SVG_LENGTH).default(""),
+  paint: z.enum(ICON_PAINTS).default("original"),
+  /** The color of the custom paint. */
+  color: z.string().regex(HEX_COLOR).default(LINEAR_INDIGO),
+  /** Fill shapes that only have an outline. */
+  solid: z.boolean().default(false),
+});
+export type IconSettings = z.infer<typeof IconSettingsSchema>;
+
+const BLOCKED: readonly (readonly [RegExp, string])[] = [
+  [/<!DOCTYPE|<!ENTITY/i, "The SVG has a DOCTYPE or entities. Export it again without them."],
+  [/<script[\s>/]/i, "The SVG has a script. Use an SVG with shapes only."],
+  [/<foreignObject[\s>/]/i, "The SVG has HTML content. Use an SVG with shapes only."],
+  [/<[^>]*\son[a-z]+\s*=/i, "The SVG has event handlers. Use an SVG with shapes only."],
+  [/[\s:]href\s*=\s*["']\s*(?!#)/i, "The SVG links to other files or images. Use an SVG that has all its shapes inside."],
+  [/url\(\s*["']?\s*(?!#)/i, "The SVG uses files outside it. Use an SVG that has all its shapes inside."],
+  [/@import/i, "The SVG imports styles from another file."],
+];
+
+const ROOT_TAG = /^<svg\b[^>]*>/i;
+const NUMBER = String.raw`(-?[\d.]+(?:e[-+]?\d+)?)`;
+const VIEW_BOX = new RegExp(String.raw`\sviewBox\s*=\s*["']\s*${NUMBER}[\s,]+${NUMBER}[\s,]+${NUMBER}[\s,]+${NUMBER}\s*["']`, "i");
+
+const attribute = (tag: string, name: string) =>
+  new RegExp(String.raw`\s${name}\s*=\s*["']([^"']*)["']`, "i").exec(tag)?.[1]?.trim() ?? null;
+const withoutAttribute = (tag: string, name: string) =>
+  tag.replace(new RegExp(String.raw`\s${name}\s*=\s*(?:"[^"]*"|'[^']*')`, "gi"), "");
+
+/** The root's viewBox as x, y, width, and height, or null without a usable one. */
+export function viewBoxOf(svg: string): [number, number, number, number] | null {
+  const root = ROOT_TAG.exec(svg)?.[0] ?? "";
+  const box = VIEW_BOX.exec(root)?.slice(1, 5).map(Number);
+  if (!box || box.some((value) => !Number.isFinite(value))) return null;
+  const [x = 0, y = 0, width = 0, height = 0] = box;
+  return width > 0 && height > 0 ? [x, y, width, height] : null;
+}
+
+/** Checks pasted or uploaded SVG and returns it ready to save, or why it cannot be used. */
+export function parseIconSvg(text: string): { svg: string } | { error: string } {
+  const svg = text
+    .replace(/^\uFEFF/, "")
+    .replace(/<\?[\s\S]*?\?>/g, "")
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .trim();
+  if (!svg) return { error: "Paste SVG markup or choose an SVG file." };
+  if (svg.length > MAX_SVG_LENGTH) {
+    return { error: `The SVG is too large. Use one under ${Math.round(MAX_SVG_LENGTH / 1000)} KB.` };
+  }
+  if (!/^<svg[\s>]/i.test(svg) || !/<\/svg>$/i.test(svg)) {
+    return { error: "This is not an SVG. It must start with <svg and end with </svg>." };
+  }
+  for (const [pattern, error] of BLOCKED) if (pattern.test(svg)) return { error };
+  const root = ROOT_TAG.exec(svg)?.[0] ?? "";
+  let next = root;
+  if (!viewBoxOf(svg)) {
+    const width = Number(/^([\d.]+)(?:px)?$/.exec(attribute(root, "width") ?? "")?.[1]);
+    const height = Number(/^([\d.]+)(?:px)?$/.exec(attribute(root, "height") ?? "")?.[1]);
+    if (!(width > 0 && height > 0)) return { error: "The SVG needs a viewBox, or a width and height in pixels." };
+    next = withoutAttribute(next, "viewBox").replace(/^<svg/i, `<svg viewBox="0 0 ${width} ${height}"`);
+  }
+  // The image scales to its box from the viewBox, so a fixed size would only crop it.
+  next = withoutAttribute(withoutAttribute(next, "width"), "height");
+  if (!/\sxmlns\s*=/.test(next)) next = next.replace(/^<svg/i, '<svg xmlns="http://www.w3.org/2000/svg"');
+  return { svg: next + svg.slice(root.length) };
+}
+
+/** Keeps a color inside an attribute value; anything else becomes gray. */
+export function safeColor(color: string): string {
+  return /^[#a-z0-9(),.%\s-]+$/i.test(color) ? color.trim() : "#888888";
+}
+
+const FILL_NONE = /(?<![\w-])(fill\s*:\s*)none\b/gi;
+
+/** Fills shapes that only have an outline, with their stroke color or the icon color. */
+export function fillOutlines(svg: string): string {
+  const tags = svg.replace(/<([a-z][\w:.-]*)(\s[^>]*?)?(\/?)>/gi, (tag, name: string, attrs: string | undefined, close: string) => {
+    if (!attrs) return tag;
+    const stroke = attribute(attrs, "stroke") ?? /(?<![\w-])stroke\s*:\s*([^;"']+)/i.exec(attrs)?.[1]?.trim();
+    const fill = stroke && stroke !== "none" ? stroke : "currentColor";
+    const next = attrs.replace(/(\sfill\s*=\s*["'])\s*none\s*(["'])/gi, `$1${fill}$2`).replace(FILL_NONE, `$1${fill}`);
+    return `<${name}${next}${close}>`;
+  });
+  return tags.replace(/(<style\b[^>]*>)([\s\S]*?)(<\/style>)/gi, (_all, open: string, css: string, end: string) =>
+    `${open}${css.replace(FILL_NONE, "$1currentColor")}${end}`,
+  );
+}
+
+const TINT_ID = "paseo-linear-tint";
+
+/** Paints every visible pixel one color and keeps its transparency. */
+export function tint(svg: string, color: string): string {
+  const [x, y, width, height] = viewBoxOf(svg) ?? [0, 0, 24, 24];
+  const filter =
+    `<filter id="${TINT_ID}" filterUnits="userSpaceOnUse" x="${x - width}" y="${y - height}" width="${width * 3}" height="${height * 3}" color-interpolation-filters="sRGB">` +
+    `<feFlood flood-color="${safeColor(color)}"/><feComposite in2="SourceAlpha" operator="in"/></filter>`;
+  return svg
+    .replace(ROOT_TAG, (root) => `${root}<defs>${filter}</defs><g filter="url(#${TINT_ID})">`)
+    .replace(/<\/svg>$/i, "</g></svg>");
+}
+
+export interface IconLook {
+  /** The color `currentColor` takes: the color Paseo gives the icon. */
+  ink: string;
+  /** One color for the whole icon, or null to keep its colors. */
+  paint: string | null;
+  solid: boolean;
+}
+
+/** The SVG to draw for saved markup, or null when it no longer passes the checks. */
+export function iconMarkup(saved: string, look: IconLook): string | null {
+  const parsed = parseIconSvg(saved);
+  if ("error" in parsed) return null;
+  const filled = look.solid ? fillOutlines(parsed.svg) : parsed.svg;
+  const inked = filled.replace(/currentColor/gi, safeColor(look.ink));
+  return look.paint ? tint(inked, look.paint) : inked;
+}
+
+/** The one color a paint gives, or null for the icon's own colors. */
+export function paintColor(icon: IconSettings, colors: { ink: string; accent: string }): string | null {
+  switch (icon.paint) {
+    case "original":
+      return null;
+    case "theme":
+      return colors.ink;
+    case "accent":
+      return colors.accent;
+    case "linear":
+      return LINEAR_INDIGO;
+    case "custom":
+      return icon.color;
+  }
+}

package/shared/knowledge.ts

@@ -0,0 +1,255 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+// Project knowledge: what the daemon learns about a project's files without an agent. It is
+// kept on disk, so explore and setup prompts, ticket-text maps, and Linear Live can use it.
+
+export const AREA_KINDS = ["service", "package", "folder"] as const;
+export type AreaKind = (typeof AREA_KINDS)[number];
+
+export const AreaSchema = z.object({
+  /** Folder with a trailing slash; "" is the repository root. */
+  path: z.string(),
+  name: z.string(),
+  kind: z.enum(AREA_KINDS),
+  /** What the folder holds, from its name, such as "backend" or "tests"; "" when unknown. */
+  role: z.string(),
+  /** Files that define it, such as package.json or Dockerfile. */
+  manifests: z.array(z.string()),
+  /** Files under the folder, at any depth. */
+  files: z.number(),
+  languages: z.array(z.string()),
+  /** One line from the setup agent; "" until it writes one. */
+  summary: z.string(),
+});
+export type Area = z.infer<typeof AreaSchema>;
+
+/** The part of an area the app needs to label files. */
+export const AreaRefSchema = AreaSchema.pick({
+  path: true,
+  name: true,
+  kind: true,
+  role: true,
+  summary: true,
+});
+export type AreaRef = z.infer<typeof AreaRefSchema>;
+
+const CountSchema = z.object({ name: z.string(), files: z.number() });
+
+export const ProjectKnowledgeSchema = z.object({
+  projectId: z.string(),
+  rootPath: z.string(),
+  inspectedAt: z.string(),
+  source: z.enum(["git", "walk"]),
+  /** Repo-relative file paths, sorted, at most MAX_KNOWLEDGE_FILES. */
+  files: z.array(z.string()),
+  fileCount: z.number(),
+  truncated: z.boolean(),
+  areas: z.array(AreaSchema),
+  languages: z.array(CountSchema),
+  /** Files that guide agents and contributors, such as AGENTS.md and CI workflows. */
+  guides: z.array(z.string()),
+  /** Commands the repository defines, such as "npm run check". */
+  commands: z.array(z.string()),
+  /** One line from the setup agent about the project; "" until it writes one. */
+  summary: z.string(),
+  summarizedAt: z.string().nullable(),
+});
+export type ProjectKnowledge = z.infer<typeof ProjectKnowledgeSchema>;
+
+/** What the app gets: everything but the file list, plus file counts per top folder. */
+export const ProjectBriefSchema = ProjectKnowledgeSchema.omit({ files: true }).extend({
+  folders: z.array(CountSchema),
+});
+export type ProjectBrief = z.infer<typeof ProjectBriefSchema>;
+
+export const MAX_KNOWLEDGE_FILES = 20_000;
+export const MAX_RESOLVE_PATHS = 200;
+
+/** Saved knowledge of a project; the daemon inspects the project first when it has none. */
+export const knowledgeGetRpc = defineRpc({
+  name: "linear.knowledge.get",
+  input: z.object({ projectId: z.string().min(1) }),
+  output: z.object({ knowledge: ProjectBriefSchema }),
+});
+
+export const knowledgeInspectRpc = defineRpc({
+  name: "linear.knowledge.inspect",
+  input: z.object({ projectId: z.string().min(1) }),
+  output: z.object({ knowledge: ProjectBriefSchema }),
+});
+
+/** The areas of an agent's project, and ticket paths matched to the project's real files. */
+export const liveProjectRpc = defineRpc({
+  name: "linear.live.project",
+  input: z.object({
+    agentId: z.string().min(1),
+    paths: z.array(z.string()).max(MAX_RESOLVE_PATHS),
+  }),
+  output: z.object({
+    areas: z.array(AreaRefSchema),
+    resolved: z.array(z.object({ from: z.string(), to: z.string() })),
+  }),
+});
+
+export function toAreaRef(area: Area): AreaRef {
+  return { path: area.path, name: area.name, kind: area.kind, role: area.role, summary: area.summary };
+}
+
+/** The deepest area whose folder holds the path. */
+export function areaOf<A extends { path: string }>(path: string, areas: readonly A[]): A | null {
+  let best: A | null = null;
+  for (const area of areas) {
+    if (path.startsWith(area.path) && (!best || area.path.length > best.path.length)) best = area;
+  }
+  return best;
+}
+
+/** Such as "billing-api · service", "server · backend", or "docs". */
+export function areaLabel(area: AreaRef): string {
+  const what = area.role || (area.kind === "folder" ? "" : area.kind);
+  return what && what.toLowerCase() !== area.name.toLowerCase() ? `${area.name} · ${what}` : area.name;
+}
+
+function topFolder(path: string): string {
+  const index = path.indexOf("/");
+  return index < 0 ? "./" : path.slice(0, index + 1);
+}
+
+/** File counts per top folder; "./" counts files at the root. */
+export function topFolders(files: readonly string[]): { name: string; files: number }[] {
+  const counts = new Map<string, number>();
+  for (const file of files) counts.set(topFolder(file), (counts.get(topFolder(file)) ?? 0) + 1);
+  return [...counts]
+    .map(([name, count]) => ({ name, files: count }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Where an off-map file is: its area, or its top folder when the project has no knowledge. */
+export function whereLabel(path: string, areas: readonly AreaRef[]): string {
+  const area = areaOf(path, areas);
+  return area && area.path !== "" ? areaLabel(area) : topFolder(path);
+}
+
+/** Folders to the given depth with their file counts, indented, for prompts. */
+export function folderLines(files: readonly string[], depth = 2, limit = 60): string[] {
+  const counts = new Map<string, number>();
+  for (const file of files) {
+    const parts = file.split("/").slice(0, -1);
+    for (let level = 1; level <= Math.min(depth, parts.length); level += 1) {
+      const dir = `${parts.slice(0, level).join("/")}/`;
+      counts.set(dir, (counts.get(dir) ?? 0) + 1);
+    }
+  }
+  const dirs = [...counts.keys()].sort();
+  if (dirs.length > limit && depth > 1) return folderLines(files, depth - 1, limit);
+  const lines = dirs.slice(0, limit).map((dir) => {
+    const indent = "  ".repeat(dir.split("/").length - 2);
+    return `${indent}${dir} (${counts.get(dir)})`;
+  });
+  if (dirs.length > limit) lines.push(`... ${dirs.length - limit} more folders`);
+  return lines;
+}
+
+function countLine(entries: readonly { name: string; files: number }[]): string {
+  return entries.map((entry) => `${entry.name} ${entry.files}`).join(", ");
+}
+
+/** The project map an agent prompt starts from. Empty without knowledge. */
+export function knowledgeLines(knowledge: ProjectKnowledge | null): string[] {
+  if (!knowledge) return [];
+  const source = knowledge.source === "git" ? "git ls-files" : "a folder walk";
+  const lines = [
+    `Project map from the plugin's inspection (${knowledge.inspectedAt}, by ${source}). Start from`,
+    "it instead of listing the whole repository; files may have changed since.",
+  ];
+  if (knowledge.summary) lines.push(`- Project: ${knowledge.summary}`);
+  const truncated = knowledge.truncated ? ", list truncated" : "";
+  lines.push(`- ${knowledge.fileCount} files${truncated}. Languages: ${countLine(knowledge.languages) || "unknown"}.`);
+  if (knowledge.guides.length > 0) lines.push(`- Guides: ${knowledge.guides.join(", ")}`);
+  if (knowledge.commands.length > 0) lines.push(`- Commands: ${knowledge.commands.join(", ")}`);
+  if (knowledge.areas.length > 0) {
+    lines.push("Areas (services, packages, and main folders):");
+    for (const area of knowledge.areas) {
+      const manifests = area.manifests.length > 0 ? ` [${area.manifests.join(", ")}]` : "";
+      const languages = area.languages.length > 0 ? `, ${area.languages.join("/")}` : "";
+      const summary = area.summary ? `: ${area.summary}` : "";
+      const files = `${area.files} ${area.files === 1 ? "file" : "files"}`;
+      lines.push(`- ${area.path || "./"} ${areaLabel(area)}${manifests}, ${files}${languages}${summary}`);
+    }
+  }
+  lines.push("Folders (file count):", ...folderLines(knowledge.files));
+  return lines;
+}
+
+function byName(files: readonly string[]): Map<string, string[]> {
+  const index = new Map<string, string[]>();
+  for (const file of files) {
+    const name = file.slice(file.lastIndexOf("/") + 1);
+    const known = index.get(name);
+    if (known) known.push(file);
+    else index.set(name, [file]);
+  }
+  return index;
+}
+
+function dirsOf(files: readonly string[]): Set<string> {
+  const dirs = new Set<string>();
+  for (const file of files) {
+    let index = file.indexOf("/");
+    while (index >= 0) {
+      dirs.add(file.slice(0, index + 1));
+      index = file.indexOf("/", index + 1);
+    }
+  }
+  return dirs;
+}
+
+/** Ticket paths matched to real files: "linear.ts" to "server/linear.ts" when only one fits. */
+export function resolvePaths(paths: readonly string[], files: readonly string[]): Map<string, string> {
+  const known = new Set(files);
+  const names = byName(files);
+  let dirs: Set<string> | null = null;
+  const resolved = new Map<string, string>();
+  for (const path of paths) {
+    let matches: string[];
+    if (path.endsWith("/")) {
+      dirs ??= dirsOf(files);
+      if (dirs.has(path)) continue;
+      matches = [...dirs].filter((dir) => dir.endsWith(`/${path}`));
+    } else {
+      if (known.has(path)) continue;
+      const name = path.slice(path.lastIndexOf("/") + 1);
+      matches = (names.get(name) ?? []).filter((file) => file === name || file.endsWith(`/${path}`));
+    }
+    if (matches.length === 1 && matches[0]) resolved.set(path, matches[0]);
+  }
+  return resolved;
+}
+
+const KINDS_SAID = "(?:service|package|app|module|library|lib|worker|folder|directory|dir)";
+
+function escapeRegex(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function aliases(area: AreaRef): string[] {
+  const folder = area.path.replace(/\/$/, "").split("/").pop() ?? "";
+  return [...new Set([area.name, folder])].filter((alias) => alias.length >= 3);
+}
+
+// A service or package counts when its name appears; a plain folder only when the text says
+// "the docs folder" or similar, since folder names like "server" are common words.
+function mentions(text: string, alias: string, plain: boolean): boolean {
+  const word = `(?:^|[^\\w@/.-])${escapeRegex(alias)}(?![\\w@/-])`;
+  if (plain && alias.length >= 4 && new RegExp(word, "i").test(text)) return true;
+  return new RegExp(`${word}\\s+${KINDS_SAID}\\b`, "i").test(text);
+}
+
+/** Areas the text names, other than the whole repository. */
+export function areasIn(text: string, areas: readonly AreaRef[]): AreaRef[] {
+  return areas.filter(
+    (area) =>
+      area.path !== "" && aliases(area).some((alias) => mentions(text, alias, area.kind !== "folder")),
+  );
+}