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

package/server/agent-runs.ts

@@ -0,0 +1,312 @@
+import { randomUUID } from "node:crypto";
+import type { PluginHandlerContext, PluginLifecycleEvents } from "@getpaseo/plugin/server";
+import { type ZodType, z } from "zod";
+import { relativePath } from "../shared/activity";
+import type { Job } from "../shared/live";
+import { lastJsonObject } from "../shared/live";
+
+// Explore and project setup run a read-only agent, wait for it in the background, and read a
+// JSON answer from its last message. Claude ignores outputSchema, so the prompt asks for JSON.
+
+export type Paseo = PluginHandlerContext["paseo"];
+type WorkspaceHandle = Awaited<ReturnType<Paseo["workspaces"]["open"]>>;
+type AgentHandle = ReturnType<Paseo["agents"]["ref"]>;
+export type PermissionRequest = PluginLifecycleEvents["agent.permission_requested"]["request"];
+export type PermissionAnswer = Parameters<AgentHandle["respondToPermission"]>[0]["response"];
+
+export interface InternalRun<T> {
+  paseo: Paseo;
+  workspace: WorkspaceHandle;
+  /** Folder the agent works in; its reads must stay inside. */
+  cwd: string;
+  provider: string;
+  /** Thinking option for the model in `provider`; ignored when another model runs. */
+  effort?: string;
+  title: string;
+  prompt: string;
+  labels: Record<string, string>;
+  schema: ZodType<T>;
+  timeoutMs: number;
+}
+
+interface SnapshotEntry {
+  provider: string;
+  status: string;
+  enabled?: boolean;
+  modes?: readonly { id: string; label?: string }[];
+}
+
+const SAFE_MODES = [/read.?only/i, /^default$/i, /ask/i];
+const UNSAFE_MODE = /bypass|full|yolo|danger/i;
+
+// Never inherit a provider default that skips approvals. Claude's "default" asks before
+// edits, so an edit attempt stops the run. Codex has no read-only mode; "auto" asks on request.
+export function safeModeId(modes: SnapshotEntry["modes"]): string | undefined {
+  for (const pattern of SAFE_MODES) {
+    const match = modes?.find((mode) => pattern.test(mode.id));
+    if (match) return match.id;
+  }
+  return modes?.find((mode) => !UNSAFE_MODE.test(`${mode.id} ${mode.label ?? ""}`))?.id;
+}
+
+const UNSUPPORTED_KEYWORDS = new Set([
+  "$schema",
+  "default",
+  "minLength",
+  "maxLength",
+  "minItems",
+  "maxItems",
+]);
+
+/** JSON schema for strict structured output: every property required, no extras. */
+export function strictJsonSchema(schema: ZodType): Record<string, unknown> {
+  const strip = (node: unknown): unknown => {
+    if (Array.isArray(node)) return node.map(strip);
+    if (!node || typeof node !== "object") return node;
+    return Object.fromEntries(
+      Object.entries(node)
+        .filter(([key]) => !UNSUPPORTED_KEYWORDS.has(key))
+        .map(([key, value]) => [key, strip(value)]),
+    );
+  };
+  return strip(z.toJSONSchema(schema, { io: "output" })) as Record<string, unknown>;
+}
+
+// Some Claude builds search only through the shell, so internal agents may run a short list of
+// commands that read. Anything that writes, runs other programs, or leaves the folder is denied.
+const READ_COMMAND = /^(?:ls|find|rg|grep|cat|head|tail|wc|pwd|git (?:ls-files|grep))(?:\s|$)/;
+const UNSAFE_SHELL =
+  /[`;&<>~$\n\r]|\.\.|\s-(?:exec|execdir|ok|okdir|delete|fprint\w*|fls|O)\b|\s--(?:pre|open-files-in-pager)\b/;
+/** Quoted text the shell does not expand: single quotes, or double quotes without $ or `. */
+const LITERAL = /'[^']*'|"[^"$`\\]*"/g;
+
+function insideFolder(filePath: string, cwd: string): boolean {
+  return filePath.replace(/\/+$/, "") === cwd.replace(/\/+$/, "") || relativePath(filePath, cwd) !== null;
+}
+
+export function readOnlyCommand(command: string, cwd: string): boolean {
+  const text = command.replace(/\s2>\s*\/dev\/null/g, " ").trim();
+  const bare = text.replace(LITERAL, "Q");
+  if (!bare || UNSAFE_SHELL.test(bare)) return false;
+  const outside = text.split(/\s+|=/).some((word) => {
+    const filePath = word.replace(/['"]/g, "");
+    return filePath.startsWith("/") && !insideFolder(filePath, cwd);
+  });
+  return !outside && bare.split("|").every((part) => READ_COMMAND.test(part.trim()));
+}
+
+/** Prompt lines that match what readOnlyAnswer allows. */
+export const READ_ONLY_RULES = [
+  "Read and search only. Do not create, edit, or delete files.",
+  "To find files, use your read and search tools, or these shell commands, one at a time and",
+  "without redirection: ls, find, rg, grep, cat, head, tail, wc, git ls-files, git grep.",
+  "Keep paths inside this folder. Other commands are denied.",
+  "Work alone: do not start subagents or background tasks.",
+];
+
+const DENIED =
+  "Not allowed in this read-only run. Read and search files in this repository only, one " +
+  "command at a time, without redirection.";
+
+/** No one watches internal agents, so the plugin answers their prompts: reads yes, else no. */
+export function readOnlyAnswer(request: PermissionRequest, cwd: string): PermissionAnswer {
+  if (request.kind === "question") {
+    return { behavior: "deny", message: "No one can answer here. Decide yourself and continue." };
+  }
+  const detail = request.detail;
+  const command =
+    detail?.type === "shell" ? detail.command : (request.input as { command?: unknown })?.command;
+  const allowed =
+    request.kind === "tool" &&
+    ((detail?.type === "read" && insideFolder(detail.filePath, cwd)) ||
+      (detail?.type === "search" && detail.toolName !== "web_search") ||
+      (typeof command === "string" && readOnlyCommand(command, cwd)));
+  return allowed ? { behavior: "allow" } : { behavior: "deny", message: DENIED };
+}
+
+function entriesOf(snapshot: unknown): readonly SnapshotEntry[] {
+  const value = snapshot as {
+    entries?: readonly SnapshotEntry[];
+    compactSnapshot?: { entries?: readonly SnapshotEntry[] } | null;
+  };
+  const entries = value.entries ?? [];
+  return entries.length > 0 ? entries : (value.compactSnapshot?.entries ?? []);
+}
+
+/** Uses `preferred` (`provider` or `provider/model`) when ready, else the first ready provider. */
+export async function agentConfigFor(paseo: Paseo, preferred: string) {
+  const entries = entriesOf(await paseo.providers.snapshot()).filter(
+    (entry) => entry.status === "ready" && entry.enabled !== false,
+  );
+  const wanted = preferred.split("/")[0] ?? "";
+  const entry = entries.find((candidate) => candidate.provider === wanted) ?? entries[0];
+  if (!entry) throw new Error("No agent provider is ready on this host");
+  const provider = entry.provider === wanted && preferred.includes("/") ? preferred : entry.provider;
+  const modeId = safeModeId(entry.modes);
+  return { provider, ...(modeId ? { modeId } : {}) };
+}
+
+export async function lastReply(handle: AgentHandle) {
+  const page = await handle.timeline.refetch({
+    direction: "tail",
+    limit: 60,
+    projection: "projected",
+  });
+  for (const entry of [...page.entries].reverse()) {
+    const item = entry.item as { type: string; text?: unknown };
+    if (item.type === "assistant_message" && typeof item.text === "string") return item.text;
+  }
+  return "";
+}
+
+const MAX_STALLS = 20;
+const STALL_DELAY_MS = 500;
+
+// waitForFinish also returns when the agent asks for permission, so answer and keep waiting.
+// A prompt is answered once; while the daemon applies an answer, the loop waits briefly.
+export async function waitUntilIdle(handle: AgentHandle, cwd: string, timeoutMs: number) {
+  const deadline = Date.now() + timeoutMs;
+  const answered = new Set<string>();
+  let stalls = 0;
+  for (;;) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw new Error("The agent did not finish in time");
+    const finish = await handle.waitForFinish(remaining);
+    if (finish.status === "idle") return;
+    if (finish.status !== "permission") {
+      throw new Error(finish.error ?? `The agent stopped with status ${finish.status}`);
+    }
+    const unanswered = (requests: readonly PermissionRequest[] | null | undefined) =>
+      (requests ?? []).filter((request) => !answered.has(request.id));
+    let pending = unanswered(finish.final?.pendingPermissions);
+    if (pending.length === 0) {
+      await handle.refresh();
+      pending = unanswered(handle.pendingPermissions);
+    }
+    if (pending.length === 0) {
+      stalls += 1;
+      if (answered.size === 0 || stalls > MAX_STALLS) {
+        throw new Error("The agent is waiting for input");
+      }
+      await new Promise((resolve) => setTimeout(resolve, STALL_DELAY_MS));
+      continue;
+    }
+    stalls = 0;
+    for (const request of pending) {
+      answered.add(request.id);
+      await handle
+        .respondToPermission({ requestId: request.id, response: readOnlyAnswer(request, cwd) })
+        .catch((error: unknown) => console.error("Linear could not answer a permission", error));
+    }
+  }
+}
+
+/** Waits for an internal agent, reads its JSON answer, and archives it either way. */
+export async function finishInternalRun<T>(
+  handle: AgentHandle,
+  cwd: string,
+  schema: ZodType<T>,
+  timeoutMs: number,
+): Promise<T> {
+  try {
+    await waitUntilIdle(handle, cwd, timeoutMs);
+    const parsed = schema.safeParse(lastJsonObject(await lastReply(handle)));
+    if (!parsed.success) throw new Error("The agent did not return the expected JSON");
+    return parsed.data;
+  } finally {
+    await handle.archive().catch(() => undefined);
+  }
+}
+
+export interface StartedRun<T> {
+  agentId: string;
+  result: Promise<T>;
+}
+
+/** Adds the chosen effort only when the chosen model runs, not a fallback provider. */
+export function withEffort<C extends { provider: string }>(config: C, chosen: string, effort?: string) {
+  const applies = Boolean(effort) && chosen.includes("/") && config.provider === chosen;
+  return applies ? { ...config, thinkingOptionId: effort as string } : config;
+}
+
+export async function startInternalRun<T>(run: InternalRun<T>): Promise<StartedRun<T>> {
+  const config = withEffort(await agentConfigFor(run.paseo, run.provider), run.provider, run.effort);
+  const handle = await run.workspace.agents.create({
+    config,
+    title: run.title,
+    prompt: run.prompt,
+    labels: run.labels,
+    outputSchema: strictJsonSchema(run.schema),
+  });
+  const result = finishInternalRun(handle, run.cwd, run.schema, run.timeoutMs);
+  return { agentId: handle.id, result };
+}
+
+export interface JobStore<T> {
+  get(id: string): { job: Job; value: T | null } | null;
+  start(id: string | null, begin: () => Promise<StartedRun<T>>): Promise<Job>;
+  /** Resolves with the job once it is done or failed; null for an unknown id. */
+  wait(id: string): Promise<Job | null>;
+  /** Drops a finished job, so the next start makes a new run. A running job is kept. */
+  forget(id: string): void;
+}
+
+interface JobRecord<T> {
+  job: Job;
+  value: T | null;
+  settled: Promise<void>;
+}
+
+export function createJobStore<T>(): JobStore<T> {
+  const jobs = new Map<string, JobRecord<T>>();
+  return {
+    get: (id) => {
+      const record = jobs.get(id);
+      return record ? { job: record.job, value: record.value } : null;
+    },
+    forget(id) {
+      if (jobs.get(id)?.job.status !== "running") jobs.delete(id);
+    },
+    async wait(id) {
+      const record = jobs.get(id);
+      if (!record) return null;
+      await record.settled;
+      return record.job;
+    },
+    async start(id, begin) {
+      const job: Job = {
+        id: id ?? randomUUID(),
+        status: "running",
+        agentId: null,
+        error: null,
+        startedAt: new Date().toISOString(),
+      };
+      let settle = () => {};
+      const settled = new Promise<void>((resolve) => {
+        settle = resolve;
+      });
+      const record: JobRecord<T> = { job, value: null, settled };
+      jobs.set(job.id, record);
+      const fail = (error: unknown) => {
+        record.job = {
+          ...record.job,
+          status: "failed",
+          error: error instanceof Error ? error.message : String(error),
+        };
+        settle();
+      };
+      try {
+        const started = await begin();
+        record.job = { ...record.job, agentId: started.agentId };
+        started.result.then((value) => {
+          record.value = value;
+          record.job = { ...record.job, status: "done" };
+          settle();
+        }, fail);
+      } catch (error) {
+        fail(error);
+      }
+      return record.job;
+    },
+  };
+}

package/server/agent-tools.ts

@@ -0,0 +1,240 @@
+import { createHash, randomBytes } from "node:crypto";
+import path from "node:path";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { z } from "zod";
+import {
+  AGENT_TOOLS,
+  agentToolsRpc,
+  childBrief,
+  EditIssueInput,
+  editText,
+  issueText,
+  LINEAR_TOOLS,
+  ReadIssueInput,
+  StartAgentInput,
+  TOOLS_SERVER,
+  taskCount,
+  type ToolScope,
+  ToolScopeSchema,
+  toolPolicy,
+  WaitAgentInput,
+} from "../shared/agent-tools";
+import { AGENT_LABELS } from "../shared/prompts";
+import { lastReply, type Paseo } from "./agent-runs";
+import type { LinearAccess } from "./handlers";
+import { createMcpServer, listenLocal, type McpTool, tool } from "./mcp-http";
+import type { LinearService } from "./queries";
+import { createJsonFile } from "./stores";
+
+// Each launch gets a grant: a random token for the agent's MCP config, and the issue tree it
+// reaches. The file keeps the port and a hash of each token, never the token, so agents keep
+// their tools after a restart.
+
+const MAX_GRANTS = 500;
+
+const GrantSchema = z.object({
+  id: z.string(),
+  hash: z.string(),
+  scope: ToolScopeSchema,
+  /** Only agents started from an issue may start agents, so the tree is one level deep. */
+  canStart: z.boolean(),
+  createdAt: z.string(),
+});
+export type Grant = z.infer<typeof GrantSchema>;
+
+const FileSchema = z.object({ port: z.number().int().nullable(), grants: z.array(GrantSchema) });
+
+const hashOf = (token: string) => createHash("sha256").update(token).digest("hex");
+
+export interface AgentToolsDependencies {
+  access: LinearAccess;
+  dataDirectory: string;
+}
+
+/** The root issue or one of its sub-issues; any other key is refused. */
+async function treeIssue(linear: LinearService, scope: ToolScope, key: string | undefined) {
+  const wanted = (key ?? scope.home).toUpperCase();
+  const root = await linear.getIssue(scope.root);
+  if (wanted === root.identifier.toUpperCase()) return root;
+  if (!root.children.some((child) => child.identifier.toUpperCase() === wanted)) {
+    throw new Error(`${wanted} is not ${root.identifier} or one of its sub-issues.`);
+  }
+  return linear.getIssue(wanted);
+}
+
+export function linearTools(deps: AgentToolsDependencies, paseo: () => Paseo, mint: Mint): McpTool<Grant>[] {
+  const callers = new Map<string, string>();
+  async function callerAgent(api: Paseo, grant: Grant): Promise<string | null> {
+    const known = callers.get(grant.id);
+    if (known) return known;
+    const result = await api.agents.list({ filter: { labels: { [AGENT_LABELS.tools]: grant.id } }, page: { limit: 1 } });
+    const id = result.entries[0]?.agent.id ?? null;
+    if (id) callers.set(grant.id, id);
+    return id;
+  }
+  return [
+    tool({
+      name: "read_issue",
+      description: "Read a Linear issue of your issue tree: status, description with its task list, and sub-issues.",
+      input: ReadIssueInput,
+      async run(input, grant) {
+        const { linear } = await deps.access.connect(grant.scope.keyScope);
+        return issueText(await treeIssue(linear, grant.scope, input.issue));
+      },
+    }),
+    tool({
+      name: "edit_issue",
+      description:
+        "Change the description of a Linear issue of your issue tree. Replace exact text, for example `- [ ] Add the form` with `- [x] Add the form` to check off a task list item.",
+      input: EditIssueInput,
+      run(input, grant) {
+        return deps.access.mutate(grant.scope.keyScope, async (linear) => {
+          const issue = await treeIssue(linear, grant.scope, input.issue);
+          const edited = editText(issue.description ?? "", input.old_text, input.new_text);
+          if ("error" in edited) throw new Error(edited.error);
+          await linear.updateIssue(issue.id, { description: edited.body });
+          const tasks = taskCount(edited.body);
+          const count = tasks.total > 0 ? ` ${tasks.done} of ${tasks.total} task list items are checked.` : "";
+          return `Updated the description of ${issue.identifier}.${count}`;
+        });
+      },
+    }),
+    tool({
+      name: "start_agent",
+      description:
+        "Start a Paseo agent on a sub-issue, in your workspace, on your provider and model. It gets read_issue and edit_issue. Returns its id at once.",
+      input: StartAgentInput,
+      allowed: (grant) => grant.canStart,
+      async run(input, grant) {
+        const api = paseo();
+        const key = input.issue.toUpperCase();
+        const { linear } = await deps.access.connect(grant.scope.keyScope);
+        await treeIssue(linear, grant.scope, key);
+        const parent = await callerAgent(api, grant);
+        const child = await mint({ ...grant.scope, home: key }, false);
+        const { keyScope } = grant.scope;
+        const create = (config: ToolScope["config"]) =>
+          api.workspaces.ref(grant.scope.workspaceId).agents.create({
+            config: { ...config, mcpServers: { [TOOLS_SERVER]: child.server }, toolPolicy: child.toolPolicy },
+            ...(parent ? { parent } : {}),
+            title: input.title,
+            prompt: `${childBrief(key, grant.scope.root)}\n\n${input.prompt}`,
+            labels: {
+              [AGENT_LABELS.issue]: key,
+              [AGENT_LABELS.action]: "implement",
+              ...(keyScope ? { [AGENT_LABELS.project]: keyScope } : {}),
+              [AGENT_LABELS.tools]: child.grantId,
+              [AGENT_LABELS.startedBy]: grant.id,
+            },
+          });
+        const base = grant.scope.config;
+        let note = "";
+        let handle: Awaited<ReturnType<typeof create>>;
+        try {
+          handle = await create(input.thinking ? { ...base, thinkingOptionId: input.thinking } : base);
+        } catch (error) {
+          if (!input.thinking) throw error;
+          handle = await create(base);
+          note = ` The model has no thinking option "${input.thinking}", so it uses yours.`;
+        }
+        return `Started agent ${handle.id} on ${key}.${note} Call wait_agent with agent_id "${handle.id}" to get its result.`;
+      },
+    }),
+    tool({
+      name: "wait_agent",
+      description: "Wait for an agent that start_agent started, and get its last reply. Call it again while the agent works.",
+      input: WaitAgentInput,
+      allowed: (grant) => grant.canStart,
+      async run(input, grant) {
+        const id = input.agent_id;
+        const handle = paseo().agents.ref(id);
+        const snapshot = (await handle.refresh().catch(() => null))?.agent;
+        if (snapshot?.labels?.[AGENT_LABELS.startedBy] !== grant.id) {
+          throw new Error(`Agent ${id} was not started by your start_agent calls.`);
+        }
+        const result = await handle.waitForFinish(input.timeout_seconds * 1000);
+        if (result.status === "timeout") return `Agent ${id} is still working. Call wait_agent again.`;
+        if (result.status === "permission") return `Agent ${id} waits for the user to answer a permission request in Paseo.`;
+        if (result.status === "error") return `Agent ${id} stopped with an error: ${result.error ?? "unknown error"}`;
+        const reply = result.lastMessage ?? (await lastReply(handle));
+        return `Agent ${id} finished.\n\nIts last reply:\n${reply || "(no reply)"}`;
+      },
+    }),
+  ];
+}
+
+type Minted = z.infer<typeof agentToolsRpc.output>;
+type Mint = (scope: ToolScope, canStart: boolean) => Promise<Minted>;
+
+export function registerAgentTools(server: PluginServerContext, deps: AgentToolsDependencies) {
+  const file = createJsonFile(path.join(deps.dataDirectory, "agent-tools.json"), FileSchema, () => ({
+    port: null,
+    grants: [],
+  }));
+  // The SDK hands Paseo to handlers and hooks only. The subprocess has one, so keep the latest.
+  let api: Paseo | null = null;
+  const remember = (_event: unknown, context: { paseo: Paseo }) => {
+    api = context.paseo;
+  };
+  server.on("agent.turn_started", remember);
+  server.on("agent.turn_ended", remember);
+  server.on("agent.created", remember);
+  const paseo = () => {
+    if (!api) throw new Error("Paseo is not ready yet. Try again in a few seconds.");
+    return api;
+  };
+
+  let listening: Promise<number> | null = null;
+  const ensureListening = () => {
+    listening ??= file
+      .read()
+      .then((current) => listenLocal(http, current.port))
+      .then(async (port) => {
+        await file.update((current) => ({ next: { ...current, port }, result: null }));
+        return port;
+      });
+    return listening;
+  };
+  const mint: Mint = async (scope, canStart) => {
+    const port = await ensureListening();
+    const token = randomBytes(32).toString("base64url");
+    const grant: Grant = {
+      id: randomBytes(8).toString("hex"),
+      hash: hashOf(token),
+      scope,
+      canStart,
+      createdAt: new Date().toISOString(),
+    };
+    await file.update((current) => ({ next: { ...current, grants: [...current.grants, grant].slice(-MAX_GRANTS) }, result: null }));
+    return {
+      grantId: grant.id,
+      server: { type: "http", url: `http://127.0.0.1:${port}/mcp`, headers: { Authorization: `Bearer ${token}` } },
+      toolPolicy: toolPolicy(canStart ? [...LINEAR_TOOLS, ...AGENT_TOOLS] : [...LINEAR_TOOLS]),
+    };
+  };
+  const http = createMcpServer<Grant>({
+    name: "paseo-linear",
+    version: "1.0.0",
+    tools: linearTools(deps, paseo, mint),
+    async authorize(token) {
+      const hash = hashOf(token);
+      return (await file.read()).grants.find((grant) => grant.hash === hash) ?? null;
+    },
+  });
+
+  server.handle(agentToolsRpc, async (scope, context) => {
+    api = context.paseo;
+    return mint(scope, true);
+  });
+  // Agents from before a restart call the same port, so listen again when grants exist.
+  void file
+    .read()
+    .then((current) => (current.grants.length > 0 ? ensureListening() : null))
+    .catch((error: unknown) => console.error("Linear MCP could not start", error));
+
+  return () =>
+    new Promise<void>((resolve) => {
+      http.closeAllConnections();
+      http.close(() => resolve());
+    });
+}

package/server/handlers.ts

@@ -37,7 +37,16 @@ function listKey(query: IssueQuery) {
   return { teamId, assignee, status, query: text.trim(), sort, after };
 }
 
-export function registerHandlers(server: PluginServerContext, dependencies: HandlerDependencies) {
+/** Linear access for the sync, explore, and setup handlers. */
+export interface LinearAccess {
+  connect(projectId: ProjectId): Promise<{ linear: LinearService; fingerprint: string }>;
+  mutate<T>(projectId: ProjectId, run: (linear: LinearService) => Promise<T>): Promise<T>;
+}
+
+export function registerHandlers(
+  server: PluginServerContext,
+  dependencies: HandlerDependencies,
+): LinearAccess {
   const { credentials, endpoint } = dependencies;
   const cache =
     dependencies.cache ?? createResponseCache({ maxEntries: 300, maxAgeMs: 24 * 60 * 60 * 1000 });
@@ -169,4 +178,6 @@ export function registerHandlers(server: PluginServerContext, dependencies: Hand
       return { attached: false };
     }
   });
+
+  return { connect, mutate };
 }

package/server/init.ts

@@ -0,0 +1,65 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { type InitProposal, InitProposalSchema, initStartRpc, initStatusRpc } from "../shared/live";
+import { AGENT_LABELS } from "../shared/prompts";
+import type { LinearSettings } from "../shared/settings";
+import { createJobStore, READ_ONLY_RULES, startInternalRun } from "./agent-runs";
+
+export function initPrompt(rootPath: string): string {
+  return [
+    `Set up Linear agent prompts for the repository at ${rootPath}.`,
+    "",
+    ...READ_ONLY_RULES,
+    "",
+    "Read the guidance the repository gives agents and contributors: AGENTS.md, CLAUDE.md and",
+    "similar files, CONTRIBUTING, the README, package scripts or build files, CI workflows, pull",
+    "request templates, commit conventions, and the test setup.",
+    "",
+    "Then write:",
+    "- instructions: up to 12 short lines an agent must follow here: commands, conventions, limits.",
+    '- steps: 3 to 8 short checks an agent runs before it finishes, such as "Run npm run check".',
+    "- implement: extra guidance for implementing an issue in this repository, or an empty string.",
+    "- review: extra guidance for reviewing a change in this repository, or an empty string.",
+    "Use only facts you found in the repository. Do not repeat generic advice.",
+    "",
+    "Reply with only a JSON object in a ```json block:",
+    '{"instructions":"...","steps":["..."],"implement":"...","review":"..."}',
+  ].join("\n");
+}
+
+export interface InitDependencies {
+  readSettings(): Promise<LinearSettings | null>;
+}
+
+export function registerInit(server: PluginServerContext, dependencies: InitDependencies) {
+  const jobs = createJobStore<InitProposal>();
+
+  server.handle(initStartRpc, async ({ projectId, rootPath }, { paseo }) => {
+    // Only known Paseo projects can be set up, so the client cannot point an agent anywhere.
+    const { projects } = await paseo.projects.list();
+    const project = projects.find((entry) => entry.projectId === projectId);
+    if (!project || project.projectRootPath !== rootPath) {
+      throw new Error("That project is not on this host");
+    }
+    const settings = await dependencies.readSettings();
+    const job = await jobs.start(null, async () =>
+      startInternalRun({
+        paseo,
+        workspace: await paseo.workspaces.open(rootPath),
+        cwd: rootPath,
+        provider: settings?.live.exploreProvider || settings?.launch.provider || "",
+        effort: settings?.live.exploreProvider ? settings.live.exploreEffort : "",
+        title: `Set up Linear prompts for ${project.projectDisplayName}`,
+        prompt: initPrompt(rootPath),
+        labels: { [AGENT_LABELS.init]: projectId },
+        schema: InitProposalSchema,
+        timeoutMs: 20 * 60_000,
+      }),
+    );
+    return { job };
+  });
+
+  server.handle(initStatusRpc, async ({ jobId }) => {
+    const record = jobs.get(jobId);
+    return { job: record?.job ?? null, proposal: record?.value ?? null };
+  });
+}