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

package/client/settings-live.tsx

@@ -0,0 +1,121 @@
+import { type PluginSurfaceProps, useSettings } from "@getpaseo/plugin/client";
+import {
+  SettingsCard,
+  SettingsSection,
+  SettingsSelect,
+  SettingsSwitch,
+} from "@getpaseo/plugin/client/ui";
+import { useCallback, useMemo } from "react";
+import { View } from "react-native";
+import {
+  type LinearSettings,
+  type LiveView,
+  linearSettings,
+  type MappingMode,
+} from "../shared/settings";
+import { useProviders } from "./queries";
+import { type ReadySettings, SaveBar, SettingsGate, useSettingsDraft } from "./settings-fields";
+import type { Theme } from "./ui";
+
+const MAPPING_OPTIONS: readonly { label: string; value: MappingMode }[] = [
+  { label: "Ticket text: free, rough", value: "semantic" },
+  { label: "Explore agent: reads the repo first", value: "explore" },
+];
+const VIEW_OPTIONS: readonly { label: string; value: LiveView }[] = [
+  { label: "Map: files grouped by folder", value: "map" },
+  { label: "Graph: issue, files, and agents as connected nodes", value: "graph" },
+];
+const SAME_AGENT = "";
+
+export function LiveSettings({ theme }: PluginSurfaceProps) {
+  const settings = useSettings(linearSettings);
+  const render = useCallback(
+    (ready: ReadySettings) => <LiveEditor theme={theme} settings={ready} />,
+    [theme],
+  );
+  return (
+    <SettingsGate theme={theme} title="Live" settings={settings}>
+      {render}
+    </SettingsGate>
+  );
+}
+
+type Live = LinearSettings["live"];
+
+function LiveEditor({ theme, settings }: { theme: Theme; settings: ReadySettings }) {
+  const { values, dirty, edit, save, discard } = useSettingsDraft(settings);
+  const providers = useProviders();
+  const live = values.live;
+  const change = useCallback(
+    (patch: Partial<Live>) => edit((current) => ({ ...current, live: { ...current.live, ...patch } })),
+    [edit],
+  );
+  const agentOptions = useMemo(() => {
+    const options = [{ label: "Same agent as the implementer", value: SAME_AGENT }];
+    for (const agent of providers.data ?? []) {
+      for (const model of agent.models) {
+        options.push({ label: `${agent.label} · ${model.label}`, value: `${agent.id}/${model.id}` });
+      }
+    }
+    if (live.exploreProvider && !options.some((option) => option.value === live.exploreProvider)) {
+      options.push({ label: `${live.exploreProvider} · not on this host`, value: live.exploreProvider });
+    }
+    return options;
+  }, [providers.data, live.exploreProvider]);
+
+  return (
+    <View>
+      <SettingsSection title="Linear Live">
+        <SettingsCard>
+          <SettingsSwitch
+            label="Show Linear Live"
+            hint="Track agents started from an issue: sub-issues, todos, and the files they touch."
+            value={live.enabled}
+            onValueChange={(enabled) => change({ enabled })}
+          />
+          <SettingsSelect
+            label="Map files with"
+            hint="Ticket text finds paths named in the issue. The explore agent reads the repository first, and the implement agent starts when the map is ready. It costs provider usage."
+            value={live.mapping}
+            options={MAPPING_OPTIONS}
+            onValueChange={(mapping) => change({ mapping })}
+            disabled={!live.enabled}
+          />
+          <SettingsSelect
+            label="Show files as"
+            hint="The view Linear Live opens with. Switch it in the panel at any time."
+            value={live.view}
+            options={VIEW_OPTIONS}
+            onValueChange={(view) => change({ view })}
+            disabled={!live.enabled}
+          />
+          <SettingsSelect
+            label="Explore and setup agent"
+            hint="It may only read and search the project folder. A faster, cheaper model is usually enough."
+            value={live.exploreProvider}
+            options={agentOptions}
+            onValueChange={(exploreProvider) => change({ exploreProvider })}
+          />
+        </SettingsCard>
+      </SettingsSection>
+      <SettingsSection title="Linear status sync">
+        <SettingsCard>
+          <SettingsSwitch
+            label="Update Linear from agent todos"
+            hint="After each turn, a todo that starts with a sub-issue key moves that sub-issue forward: In Progress, then Done. The parent moves to In Review when every sub-issue is Done. Statuses never move back."
+            value={live.syncTodos}
+            onValueChange={(syncTodos) => change({ syncTodos })}
+          />
+        </SettingsCard>
+      </SettingsSection>
+      <SaveBar
+        theme={theme}
+        dirty={dirty}
+        saving={settings.saving}
+        error={settings.saveError}
+        onSave={() => void save()}
+        onDiscard={discard}
+      />
+    </View>
+  );
+}

package/client/settings-projects.tsx

@@ -21,6 +21,8 @@ import {
   upsertProject,
 } from "../shared/settings";
 import { effectiveKeyScope, KeyScopeProvider } from "./key-scope";
+import { ProjectSetup } from "./project-init";
+import { AccessSection } from "./settings-access";
 import { type PaseoProjectOption, useAuthStatus, useCatalog, useProjects } from "./queries";
 import {
   MultilineField,
@@ -120,6 +122,12 @@ function ProjectEditor({ theme, settings }: { theme: Theme; settings: ReadySetti
   }
   return (
     <View>
+      <AccessSection
+        access={values.access}
+        saved={settings.values.access}
+        projects={projects.data}
+        edit={edit}
+      />
       <SettingsSection title="Project">
         <SettingsCard>
           <SettingsSelect
@@ -132,6 +140,7 @@ function ProjectEditor({ theme, settings }: { theme: Theme; settings: ReadySetti
         </SettingsCard>
       </SettingsSection>
       <TeamsSection config={config} change={change} />
+      <ProjectSetup theme={theme} config={config} change={change} />
       <InstructionsSection theme={theme} config={config} change={change} />
       {AGENT_ACTIONS.map((action) => (
         <ActionSection key={action} theme={theme} action={action} config={config} change={change} />

package/index.client.tsx

@@ -1,7 +1,11 @@
 import type { PluginClientContext } from "@getpaseo/plugin/client";
 import { LinearPanel, LinearScreen } from "./client/browser";
 import { openPluginScreen, registerScreen } from "./client/compat";
+import { gateAgentPanel } from "./client/access";
+import { LivePanel } from "./client/live-panel";
+import { contributeComposerPills } from "./client/pill";
 import { ConnectionSettings } from "./client/settings-connection";
+import { LiveSettings } from "./client/settings-live";
 import { ProjectSettings } from "./client/settings-projects";
 import { PromptSettings } from "./client/settings-prompts";
 import { focusIssue, panelScope, SCREEN_SCOPE, updateBrowser } from "./client/store";
@@ -11,6 +15,7 @@ import { ISSUE_CARD_KIND, IssueCardSchema, LINEAR_IDENTIFIER } from "./shared/li
 
 const SCREEN_ID = "linear";
 const PANEL_ID = "issues";
+const LIVE_PANEL_ID = "live";
 
 export default function contribute(client: PluginClientContext) {
   client.addAttachmentSource(issueAttachments);
@@ -40,6 +45,19 @@ export default function contribute(client: PluginClientContext) {
     icon: "MessageSquare",
     Component: PromptSettings,
   });
+  client.addWorkspacePanel({
+    id: LIVE_PANEL_ID,
+    title: "Linear Live",
+    icon: "Radar",
+    context: "agent",
+    Component: gateAgentPanel(LivePanel),
+  });
+  client.addSettingsScreen({
+    id: "live",
+    title: "Live",
+    icon: "Radar",
+    Component: LiveSettings,
+  });
   client.addSettingsScreen({
     id: "projects",
     title: "Projects",
@@ -77,6 +95,26 @@ export default function contribute(client: PluginClientContext) {
       openPanel(PANEL_ID);
     },
   });
+  client.addCommandCenterItem({
+    id: "open-live",
+    title: "Linear: Open Linear Live",
+    icon: "Radar",
+    keywords: ["linear", "live", "progress", "map"],
+    context: "agent",
+    onSelect({ openPanel }) {
+      openPanel(LIVE_PANEL_ID);
+    },
+  });
+  client.addCommandCenterItem({
+    id: "setup-project",
+    title: "Linear: Set up project prompts",
+    icon: "Sparkles",
+    keywords: ["linear", "init", "setup", "agents.md", "guidelines"],
+    context: "global",
+    onSelect({ openSettings }) {
+      openSettings("projects");
+    },
+  });
   client.addCommandCenterItem({
     id: "settings",
     title: "Linear: Settings",
@@ -107,5 +145,5 @@ export default function contribute(client: PluginClientContext) {
     schema: IssueCardSchema,
     Component: IssueCardRow,
   });
-  return () => {};
+  return contributeComposerPills(client);
 }

package/index.server.ts

@@ -1,12 +1,32 @@
+import path from "node:path";
 import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { createCredentialStore, defaultCredentialPath } from "./server/credentials";
 import { registerHandlers } from "./server/handlers";
-import { linearSettings } from "./shared/settings";
+import { registerInit } from "./server/init";
+import { registerLive } from "./server/live";
+import { createLaunchQueue, createMapStore } from "./server/stores";
+import { registerSync } from "./server/sync";
+import { accessRpc, type LinearSettings, linearSettings } from "./shared/settings";
 
 export default function contribute(server: PluginServerContext) {
-  server.registerSettings(linearSettings);
-  registerHandlers(server, {
-    credentials: createCredentialStore({ file: defaultCredentialPath() }),
+  const settings = server.registerSettings(linearSettings);
+  const readSettings = async (): Promise<LinearSettings | null> => {
+    const state = await settings.read();
+    return state.status === "ready" ? state.values : null;
+  };
+  const credentialPath = defaultCredentialPath();
+  const access = registerHandlers(server, {
+    credentials: createCredentialStore({ file: credentialPath }),
+  });
+  const dataDirectory = path.dirname(credentialPath);
+  const maps = createMapStore(path.join(dataDirectory, "live-maps.json"));
+  const launches = createLaunchQueue(path.join(dataDirectory, "pending-launches.json"));
+  registerLive(server, { access, maps, launches, readSettings });
+  registerSync(server, { access, readSettings });
+  registerInit(server, { readSettings });
+  server.handle(accessRpc, async () => {
+    const values = await readSettings();
+    return values?.access ?? linearSettings.schema.parse({}).access;
   });
   return () => {};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yannelli/paseo-linear-plugin",
-  "version": "1.0.1",
+  "version": "1.1.0-beta.0",
   "description": "Browse and triage Linear issues in Paseo and start agents from them",
   "license": "Apache-2.0",
   "type": "module",

package/server/agent-runs.ts

@@ -0,0 +1,299 @@
+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;
+  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 } : {}) };
+}
+
+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>;
+}
+
+export async function startInternalRun<T>(run: InternalRun<T>): Promise<StartedRun<T>> {
+  const config = await agentConfigFor(run.paseo, run.provider);
+  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>;
+}
+
+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;
+    },
+    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/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,64 @@
+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 || "",
+        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 };
+  });
+}