@andrioid/paseo-attention-span 0.0.0-stage → 0.1.0

package/client/coverage-settings.tsx

@@ -0,0 +1,145 @@
+import { type PluginSurfaceProps, useRpc } from "@getpaseo/plugin/client";
+import { SettingsAction, SettingsCard, SettingsRow, SettingsSection, TextInput } from "@getpaseo/plugin/client/ui";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useState } from "react";
+import { Text, View } from "react-native";
+import * as rpc from "../shared/rpc";
+import type { ConfigStatus, CoverageKind } from "../shared/setup";
+import { VIEW_QUERY_KEY } from "./data";
+import { Button, StylesProvider, useStyles } from "./ui";
+
+const COVERAGE_QUERY_KEY = ["attention-span", "coverage"] as const;
+
+// Settings → Plugins → Attention Span: which orgs and repos the lists cover, saved to config.json [SRC-02].
+export function CoverageSettings({ theme, layout }: PluginSurfaceProps) {
+  return (
+    <StylesProvider theme={theme} compact={layout.compact}>
+      <Coverage />
+    </StylesProvider>
+  );
+}
+
+function Coverage() {
+  const styles = useStyles();
+  const queryClient = useQueryClient();
+  const fetchCoverage = useRpc(rpc.getCoverage);
+  const save = useRpc(rpc.setCoverage);
+  const coverage = useQuery({ queryKey: COVERAGE_QUERY_KEY, queryFn: () => fetchCoverage({}) });
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  if (!coverage.data)
+    return (
+      <SettingsSection title="Orgs and repos">
+        <SettingsCard>
+          <SettingsRow label={coverage.error ? "Couldn't read the settings" : "Loading…"} error={coverage.error ? (coverage.error as Error).message : null} />
+        </SettingsCard>
+      </SettingsSection>
+    );
+  const { orgs, repos } = coverage.data;
+  // A file that doesn't parse is left for the person who edited it.
+  if (coverage.data.error)
+    return (
+      <SettingsSection title="Orgs and repos">
+        <SettingsCard>
+          <SettingsRow label="config.json can't be read" hint="Fix the file by hand. Nothing here overwrites it." error={coverage.data.error} />
+        </SettingsCard>
+      </SettingsSection>
+    );
+
+  // Saving refreshes the lists on the daemon; the screen picks them up on its next read.
+  async function persist(next: Pick<ConfigStatus, "orgs" | "repos">) {
+    setSaving(true);
+    setError(null);
+    try {
+      await save(next);
+      queryClient.setQueryData(COVERAGE_QUERY_KEY, { ...coverage.data!, ...next });
+      await queryClient.invalidateQueries({ queryKey: VIEW_QUERY_KEY });
+    } catch (failure) {
+      setError(`Saving failed: ${(failure as Error).message}`);
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  return (
+    <View style={{ gap: 24 }}>
+      <SettingsSection title="Organizations">
+        <SettingsCard>
+          {orgs.map((org) => (
+            <SettingsAction key={org} label={org} actionLabel="Remove" disabled={saving} onPress={() => void persist({ orgs: orgs.filter((other) => other !== org), repos })} />
+          ))}
+          <AddRow kind="org" existing={orgs} disabled={saving} onAdd={(name) => persist({ orgs: [...orgs, name], repos })} />
+        </SettingsCard>
+      </SettingsSection>
+      <SettingsSection title="Repositories">
+        <SettingsCard>
+          {repos.map((repo) => (
+            <SettingsAction key={repo} label={repo} actionLabel="Remove" disabled={saving} onPress={() => void persist({ orgs, repos: repos.filter((other) => other !== repo) })} />
+          ))}
+          <AddRow kind="repo" existing={repos} disabled={saving} onAdd={(name) => persist({ orgs, repos: [...repos, name] })} />
+        </SettingsCard>
+      </SettingsSection>
+      <View style={{ gap: 4 }}>
+        {error ? <Text style={styles.danger}>{error}</Text> : null}
+        <Text style={styles.muted}>
+          {orgs.length || repos.length
+            ? "Attention Span only shows pull requests and issues from the organizations and repositories above. Next up suggests unclaimed issues from them too."
+            : "With none chosen, Attention Span shows everything on GitHub that involves you, and Next up suggests issues from your Paseo projects' repositories."}
+        </Text>
+        {/* Until more moves here, point to the file for the rest. */}
+        <Text style={styles.muted}>Settings are not complete yet. Until then, check out your ~/.config/paseo-attention-span/config.json for more options.</Text>
+      </View>
+    </View>
+  );
+}
+
+// Each name is checked on GitHub before it's saved; GitHub's exact name is what's kept.
+function AddRow({ kind, existing, disabled, onAdd }: { kind: CoverageKind; existing: string[]; disabled: boolean; onAdd: (name: string) => Promise<void> }) {
+  const styles = useStyles();
+  const check = useRpc(rpc.checkCoverage);
+  const [text, setText] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [checking, setChecking] = useState(false);
+  const label = kind === "org" ? "Add an organization" : "Add a repository";
+
+  async function add() {
+    if (!text.trim()) return;
+    setChecking(true);
+    setError(null);
+    try {
+      const result = await check({ kind, name: text });
+      if (result.error !== null) return setError(result.error);
+      if (existing.some((name) => name.toLowerCase() === result.name.toLowerCase())) return setError(`${result.name} is already in the list`);
+      await onAdd(result.name);
+      setText("");
+    } catch (failure) {
+      setError((failure as Error).message);
+    } finally {
+      setChecking(false);
+    }
+  }
+
+  return (
+    <SettingsRow label={label} error={error}>
+      <View style={[styles.row, { flexShrink: 1 }]}>
+        <TextInput
+          accessibilityLabel={label}
+          value={text}
+          onChangeText={(value) => {
+            setText(value);
+            setError(null);
+          }}
+          placeholder={kind === "org" ? "acme" : "acme/shop"}
+          placeholderTextColor={styles.c.foregroundMuted}
+          autoCapitalize="none"
+          autoCorrect={false}
+          editable={!disabled && !checking}
+          onSubmitEditing={() => void add()}
+          style={[styles.input, { minWidth: 160, flexShrink: 1 }]}
+        />
+        <Button label={checking ? "Checking…" : "Add"} variant="calm" disabled={disabled || checking || !text.trim()} onPress={() => void add()} />
+      </View>
+    </SettingsRow>
+  );
+}

package/client/data.ts

@@ -0,0 +1,22 @@
+import { useRpc } from "@getpaseo/plugin/client";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback } from "react";
+import type { AttentionView, FeedId } from "../shared/attention";
+import { getAttention } from "../shared/rpc";
+
+export const VIEW_QUERY_KEY = ["attention-span", "view"] as const;
+
+// The server owns the GitHub refresh schedule; the app only reads its cache [FRESH-01, GH-01].
+export function useAttention() {
+  const fetchAttention = useRpc(getAttention);
+  const queryClient = useQueryClient();
+  const query = useQuery({
+    queryKey: VIEW_QUERY_KEY,
+    queryFn: () => fetchAttention({}),
+    refetchInterval: 60_000,
+  });
+  const setView = useCallback((view: AttentionView) => queryClient.setQueryData(VIEW_QUERY_KEY, view), [queryClient]);
+  // ⟳ fetches only the feed behind the tab I'm on.
+  const refreshNow = useCallback(async (feed: FeedId) => setView(await fetchAttention({ refresh: feed })), [fetchAttention, setView]);
+  return { ...query, setView, refreshNow };
+}

package/client/icons.ts

@@ -0,0 +1,45 @@
+// Tabler icons (MIT, tabler.io) from iconify, drawn with the theme color via currentColor.
+export const ICONS = {
+  pr: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M4 18a2 2 0 1 0 4 0a2 2 0 1 0-4 0M4 6a2 2 0 1 0 4 0a2 2 0 1 0-4 0m12 12a2 2 0 1 0 4 0a2 2 0 1 0-4 0M6 8v8\"/><path d=\"M11 6h5a2 2 0 0 1 2 2v8\"/><path d=\"m14 9l-3-3l3-3\"/></g></svg>" },
+  draft: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M4 18a2 2 0 1 0 4 0a2 2 0 1 0-4 0M4 6a2 2 0 1 0 4 0a2 2 0 1 0-4 0m12 12a2 2 0 1 0 4 0a2 2 0 1 0-4 0M6 8v8m12-5h.01M18 6h.01\"/></svg>" },
+  issue: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M11 12a1 1 0 1 0 2 0a1 1 0 1 0-2 0\"/><path d=\"M3 12a9 9 0 1 0 18 0a9 9 0 1 0-18 0\"/></g></svg>" },
+  bot: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M6 6a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2v4a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2zm6-4v2m-3 8v9m6-9v9M5 16l4-2m6 0l4 2M9 18h6M10 8v.01M14 8v.01\"/></svg>" },
+  reply: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M18 4a3 3 0 0 1 3 3v8a3 3 0 0 1-3 3h-5l-5 3v-3H6a3 3 0 0 1-3-3V7a3 3 0 0 1 3-3z\"/><path d=\"m11 8l-3 3l3 3m5-3H8\"/></g></svg>" },
+  review: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M10 12a2 2 0 1 0 4 0a2 2 0 0 0-4 0\"/><path d=\"M21 12q-3.6 6-9 6t-9-6q3.6-6 9-6t9 6\"/></g></svg>" },
+  ci: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M12 9v4m-1.637-9.409L2.257 17.125a1.914 1.914 0 0 0 1.636 2.871h16.214a1.914 1.914 0 0 0 1.636-2.87L13.637 3.59a1.914 1.914 0 0 0-3.274 0M12 16h.01\"/></svg>" },
+  changes: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M14 3v4a1 1 0 0 0 1 1h4\"/><path d=\"M17 21H7a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h7l5 5v11a2 2 0 0 1-2 2m-5-11v4m-2-2h4m-4 5h4\"/></g></svg>" },
+  merge: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M5 18a2 2 0 1 0 4 0a2 2 0 1 0-4 0M5 6a2 2 0 1 0 4 0a2 2 0 1 0-4 0m10 6a2 2 0 1 0 4 0a2 2 0 1 0-4 0M7 8v8\"/><path d=\"M7 8a4 4 0 0 0 4 4h4\"/></g></svg>" },
+  branch: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M5 18a2 2 0 1 0 4 0a2 2 0 1 0-4 0M5 6a2 2 0 1 0 4 0a2 2 0 1 0-4 0m10 0a2 2 0 1 0 4 0a2 2 0 1 0-4 0M7 8v8m2 2h6a2 2 0 0 0 2-2v-5\"/><path d=\"m14 14l3-3l3 3\"/></g></svg>" },
+  hourglass: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M6.5 7h11m-11 10h11M6 20v-2a6 6 0 1 1 12 0v2a1 1 0 0 1-1 1H7a1 1 0 0 1-1-1\"/><path d=\"M6 4v2a6 6 0 1 0 12 0V4a1 1 0 0 0-1-1H7a1 1 0 0 0-1 1\"/></g></svg>" },
+  pencil: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M4 20h4L18.5 9.5a2.828 2.828 0 1 0-4-4L4 16zm9.5-13.5l4 4\"/></svg>" },
+  replyArrow: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"m9 14l-4-4l4-4\"/><path d=\"M5 10h11a4 4 0 1 1 0 8h-1\"/></g></svg>" },
+  update: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M20 11A8.1 8.1 0 0 0 4.5 9M4 5v4h4m-4 4a8.1 8.1 0 0 0 15.5 2m.5 4v-4h-4\"/></svg>" },
+  close: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M18 6L6 18M6 6l12 12\"/></svg>" },
+  play: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M7 4v16l13-8z\"/></svg>" },
+  github: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M9 19c-4.3 1.4-4.3-2.5-6-3m12 5v-3.5c0-1 .1-1.4-.5-2c2.8-.3 5.5-1.4 5.5-6a4.6 4.6 0 0 0-1.3-3.2a4.2 4.2 0 0 0-.1-3.2s-1.1-.3-3.5 1.3a12.3 12.3 0 0 0-6.2 0C6.5 2.8 5.4 3.1 5.4 3.1a4.2 4.2 0 0 0-.1 3.2A4.6 4.6 0 0 0 4 9.5c0 4.6 2.7 5.7 5.5 6c-.6.6-.6 1.2-.5 2V21\"/></svg>" },
+  dismiss: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M10.585 10.587a2 2 0 0 0 2.829 2.828\"/><path d=\"M16.681 16.673A8.7 8.7 0 0 1 12 18q-5.4 0-9-6q1.908-3.18 4.32-4.674m2.86-1.146A9 9 0 0 1 12 6q5.4 0 9 6q-1 1.665-2.138 2.87M3 3l18 18\"/></g></svg>" },
+  // The plugin's logo in one colour, for the sidebar (assets/logo.svg).
+  logo: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"207 195 585 585\" fill=\"currentColor\"><path d=\"M 562.9 297.9 C 577.2 309.5 586.1 323.3 595.5 338.9 C 599.6 345.7 603.7 352.3 607.9 358.9 C 624.5 384.8 640.6 410.9 656.4 437.3 C 659.6 442.7 662.8 448.1 666.1 453.4 C 667.3 455.5 668.6 457.6 669.8 459.7 C 670.4 460.6 670.9 461.5 671.5 462.5 C 673 465 674.5 467.5 676 470 C 675.7 470.7 675.3 471.3 675 472 C 673.8 470.7 672.5 469.4 671.2 468.1 C 640.6 436.7 605.7 416.8 561.3 415 C 497.3 414.6 443.8 453.2 399 495 C 397.6 496.3 396.2 497.6 394.8 498.9 C 384.5 508.6 374.3 518.3 365 529 C 362.7 531.3 360.3 533.7 358 536 C 355.7 538.7 353.3 541.3 351 544 C 349.4 545.8 347.8 547.5 346.1 549.3 C 342 553.8 338.1 558.5 334.3 563.2 C 331.9 566.1 329.5 568.8 327 571.5 C 322.9 575.9 319.1 580.5 315.3 585.1 C 312.8 588.2 310.2 591.3 307.6 594.3 C 302.9 599.9 298.4 605.5 293.9 611.3 C 290.7 615.4 287.4 619.4 284 623.5 C 279.8 628.6 275.6 633.8 271.5 639 C 248.5 668.5 248.5 668.5 241 671 C 234.5 671.8 229.5 671.7 223.5 668.9 C 219.1 665.2 215.8 661.5 214 656 C 213.3 646.3 216.7 639.9 222.3 632.2 C 223.4 630.8 224.5 629.3 225.6 627.8 C 226.7 626.2 227.8 624.6 229 623 C 231.3 619.7 233.6 616.5 235.9 613.2 C 237.1 611.5 238.2 609.8 239.4 608.1 C 240 607.3 240.6 606.4 241.2 605.6 C 243 603 244.8 600.4 246.6 597.8 C 252 590.2 257.3 582.5 262.6 574.8 C 267.3 568 272 561.3 276.7 554.7 C 282.5 546.5 288.2 538.2 293.9 530 C 297.3 525.1 300.6 520.3 304 515.5 C 305.3 513.6 306.7 511.7 308 509.7 C 364 429.2 364 429.2 366 426.4 C 367.3 424.5 368.7 422.5 370 420.6 C 373.3 415.8 376.7 411 380 406.2 C 388.5 394.1 396.9 381.8 405.2 369.6 C 408 365.5 410.8 361.5 413.6 357.4 C 418.2 350.7 422.7 343.9 427.2 337.1 C 428.4 335.4 429.6 333.6 430.8 331.8 C 432.7 328.9 434.6 326.1 436.5 323.2 C 450.8 302 470.3 287 495.6 281.4 C 520.2 278.3 542.9 282.9 562.9 297.9 Z\"/><path d=\"M 576.8 472.7 C 577.6 472.7 577.6 472.7 581.9 472.7 C 593.2 472.8 603.9 473.3 615 476 C 616.6 476.4 618.2 476.8 619.8 477.2 C 653.1 486.3 682.9 506.7 704 534 C 705.2 535.5 706.4 537 707.7 538.5 C 718.6 552.2 728.7 566.7 739 581 C 740.1 582.5 741.2 584 742.3 585.5 C 748.6 594.2 754.8 602.9 761 611.7 C 765.2 617.8 769.6 623.8 774 629.8 C 781.8 640.7 785.2 647.6 784 661 C 780.2 671 774.4 678.5 765 683.4 C 752.7 689 740.9 689.6 728 685 C 708.8 676.4 695.5 661.4 683 645 C 682.2 644 681.4 642.9 680.5 641.8 C 673.5 632.7 666.7 623.4 660 614 C 657.8 611 655.7 608 653.5 605 C 652.4 603.5 651.4 602 650.3 600.5 C 648.1 597.5 645.9 594.4 643.6 591.4 C 638.8 584.6 633.9 577.9 629.1 571.1 C 610.5 545.1 610.5 545.1 601 535 C 600 533.7 598.9 532.4 597.8 531.1 C 584 516.2 567 505.1 548 498 C 547 497.6 546 497.2 545 496.8 C 532.1 492.2 519.1 491.7 505.6 491.9 C 504.2 491.9 502.8 491.9 501.3 491.9 C 497.9 491.9 494.4 492 491 492 C 499.6 483.4 519 480.2 530.6 477.6 C 531.6 477.3 532.6 477.1 533.6 476.9 C 548 473.7 562 472.6 576.8 472.7 Z\"/><path fill-rule=\"evenodd\" d=\"M 510 543 C 510.5 543.2 510.5 543.2 512.8 544.3 C 530.3 552.9 543.5 569.8 550.4 587.8 C 553.3 597 554.3 605.2 554.3 614.8 C 554.3 615.9 554.3 617 554.4 618.1 C 554.4 639.1 544.4 657.2 530.3 672.2 C 524.8 677.5 518.7 681.3 512 685 C 511.2 685.5 511.2 685.5 506.9 687.8 C 488.9 695.8 468.4 696.2 449.7 689.9 C 427.8 681.2 412.1 665.9 402.5 644.6 C 395.2 626.6 394.4 606.4 401 588 C 404.9 578.8 409.5 570.6 416 563 C 416.9 561.9 417.8 560.7 418.7 559.5 C 442.5 534.3 479.1 528.1 510 543 Z M 465.2 570.6 C 471.2 574.4 474.4 578.4 477 585 C 477.5 591.4 476.9 596.2 474 602 C 468.5 607.4 464.9 609.9 457.2 610.3 C 452.1 610.2 448.4 609.8 444 607 C 436.8 599.4 435.5 596.1 435.6 585.8 C 436.2 580.3 438 577.8 442 574 C 450.1 569 456.1 567.2 465.2 570.6 Z\"/></svg>" },
+  tray: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M4 6a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2z\"/><path d=\"M4 13h3l3 3h4l3-3h3\"/></g></svg>" },
+  nextUp: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"m8 16l2-6l6-2l-2 6z\"/><path d=\"M3 12a9 9 0 1 0 18 0a9 9 0 1 0-18 0m9-9v2m0 14v2m-9-9h2m14 0h2\"/></g></svg>" },
+  claim: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M8 7a4 4 0 1 0 8 0a4 4 0 0 0-8 0m8 12h6m-3-3v6M6 21v-2a4 4 0 0 1 4-4h4\"/></svg>" },
+  bug: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M9 9V8a3 3 0 0 1 6 0v1M8 9h8a6 6 0 0 1 1 3v3a5 5 0 0 1-10 0v-3a6 6 0 0 1 1-3m-5 4h4m10 0h4m-9 7v-6m-8 5l3.35-2M20 19l-3.35-2M4 7l3.75 2.4M20 7l-3.75 2.4\"/></svg>" },
+  feature: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M3 12h1m8-9v1m8 8h1M5.6 5.6l.7.7m12.1-.7l-.7.7M9 16a5 5 0 1 1 6 0a3.5 3.5 0 0 0-1 3a2 2 0 0 1-4 0a3.5 3.5 0 0 0-1-3m.7 1h4.6\"/></svg>" },
+  debt: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M5 21V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2v16l-3-2l-2 2l-2-2l-2 2l-2-2zM9 7h6m-6 4h6m-2 4h2\"/></svg>" },
+  task: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"m9 11l3 3l8-8\"/><path d=\"M20 12v6a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h9\"/></g></svg>" },
+  epic: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M12 4L4 8l8 4l8-4zm-8 8l8 4l8-4M4 16l8 4l8-4\"/></svg>" },
+  clock: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M3 12a9 9 0 1 0 18 0a9 9 0 0 0-18 0\"/><path d=\"M12 7v5l3 3\"/></g></svg>" },
+  history: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M12 8v4l2 2\"/><path d=\"M3.05 11a9 9 0 1 1 .5 4m-.5 5v-5h5\"/></g></svg>" },
+  issueClosed: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M3 12a9 9 0 1 0 18 0a9 9 0 1 0-18 0\"/><path d=\"m9 12l2 2l4-4\"/></g></svg>" },
+  dots: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M4 12a1 1 0 1 0 2 0a1 1 0 1 0-2 0m7 0a1 1 0 1 0 2 0a1 1 0 1 0-2 0m7 0a1 1 0 1 0 2 0a1 1 0 1 0-2 0\"/></svg>" },
+  thumbUp: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M7 11v8a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1v-7a1 1 0 0 1 1-1h3a4 4 0 0 0 4-4V6a2 2 0 0 1 4 0v5h3a2 2 0 0 1 2 2l-1 5a2 3 0 0 1-2 2h-7a3 3 0 0 1-3-3\"/></svg>" },
+  settings: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 0 0 2.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 0 0 1.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 0 0-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 0 0-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 0 0-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 0 0-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 0 0 1.066-2.573c-.94-1.543.826-3.31 2.37-2.37c1 .608 2.296.07 2.572-1.065\"/><path d=\"M9 12a3 3 0 1 0 6 0a3 3 0 0 0-6 0\"/></g></svg>" },
+  reload: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M19.933 13.041a8 8 0 1 1-9.925-8.788c3.899-1 7.935 1.007 9.425 4.747M20 4v5h-5\"/></svg>" },
+  unclaim: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M8 7a4 4 0 1 0 8 0a4 4 0 0 0-8 0M6 21v-2a4 4 0 0 1 4-4h4c.348 0 .686.045 1.009.128M16 19h6\"/></svg>" },
+  square: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M3 5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z\"/></svg>" },
+  squareCheck: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><path fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\" d=\"M3 5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2zm6 7l2 2l4-4\"/></svg>" },
+  // Tabler message-ai: marks actions that start or continue an agent session.
+  agent: { svg: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"><g fill=\"none\" stroke=\"currentColor\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"2\"><path d=\"M8 9h8m-8 4h3.5m-1.506 6.804L8 21v-3H6a3 3 0 0 1-3-3V7a3 3 0 0 1 3-3h12a3 3 0 0 1 3 3v4\"/><path d=\"M14 21v-4a2 2 0 1 1 4 0v4m-4-2h4m3-4v6\"/></g></svg>" },
+} as const;
+
+export type IconName = keyof typeof ICONS;

package/client/next-up.tsx

@@ -0,0 +1,161 @@
+import { openExternalUrl } from "@getpaseo/plugin/client";
+import { useQuery } from "@tanstack/react-query";
+import { useMemo, useState } from "react";
+import { Pressable, Text, View } from "react-native";
+import { ago } from "../shared/format";
+import type { AgentSummary, NextUpIssue, UnclaimedSource } from "../shared/attention";
+import type { IconName } from "./icons";
+import type { FetchDetails } from "./attention-screen";
+import { ActionSheet, DetailLines, type SheetEntry } from "./sheet";
+import { Button, Meta, SectionHeader, TablerIcon, Toggle, useStyles } from "./ui";
+
+const TYPE_ICONS: Record<string, IconName> = { bug: "bug", feature: "feature", debt: "debt", task: "task", epic: "epic" };
+
+interface Props {
+  assigned: NextUpIssue[];
+  unclaimed: NextUpIssue[];
+  unclaimedFrom: UnclaimedSource;
+  // Scope chips I picked; none means all [NXT-03].
+  selected: string[];
+  onSelect: (scopes: string[]) => void;
+  agents: Record<string, AgentSummary>;
+  busy: string | null;
+  fetchDetails: FetchDetails;
+  onStart: (issue: NextUpIssue, claim: boolean) => void;
+  // Claim without starting, or give an assigned issue back [NXT-07].
+  onClaim: (issue: NextUpIssue, on: boolean) => void;
+  onOpenAgent: (agentId: string) => void;
+}
+
+type RowProps = Omit<Props, "assigned" | "unclaimed" | "unclaimedFrom" | "selected" | "onSelect">;
+
+// Assigned issues first [NXT-06], then unclaimed ones [NXT-01]; both already ranked by the server [NXT-02].
+export function NextUpList({ assigned, unclaimed, unclaimedFrom, selected, onSelect, ...rowProps }: Props) {
+  const styles = useStyles();
+  const scopes = useMemo(() => [...new Set(unclaimed.map((issue) => issue.scope).filter((scope): scope is string => !!scope))].sort(), [unclaimed]);
+  // Filter by the scopes I picked last time [NXT-03]; a picked scope with no issues left is ignored.
+  const active = selected.filter((scope) => scopes.includes(scope));
+  const shown = active.length === 0 ? unclaimed : unclaimed.filter((issue) => issue.scope && active.includes(issue.scope));
+  const toggle = (scope: string) => onSelect(active.includes(scope) ? active.filter((s) => s !== scope) : [...active, scope]);
+
+  return (
+    <View style={{ gap: 24 }}>
+      {assigned.length > 0 ? (
+        <View>
+          <SectionHeader icon="claim" title="Assigned to you" count={assigned.length} />
+          <IssueList issues={assigned} claim={false} {...rowProps} />
+        </View>
+      ) : null}
+      <View>
+        <SectionHeader icon="nextUp" title="Unclaimed" count={shown.length} />
+        {scopes.length > 0 ? (
+          <View style={[styles.wrap, { marginBottom: 10 }]}>
+            <Toggle label="All" active={active.length === 0} onPress={() => onSelect([])} />
+            {scopes.map((scope) => (
+              <Toggle key={scope} label={scope} active={active.includes(scope)} onPress={() => toggle(scope)} />
+            ))}
+          </View>
+        ) : null}
+        {unclaimedFrom === "none" ? (
+          <Text style={styles.text}>No repos to look in. Register a project in Paseo, or set nextUp.repos in config.json.</Text>
+        ) : shown.length === 0 ? (
+          <Text style={styles.text}>No unclaimed issues{active.length ? " in these scopes" : ""}.</Text>
+        ) : (
+          <IssueList issues={shown} claim {...rowProps} />
+        )}
+      </View>
+    </View>
+  );
+}
+
+function IssueList({ issues, claim, ...rowProps }: RowProps & { issues: NextUpIssue[]; claim: boolean }) {
+  const styles = useStyles();
+  return (
+    <View style={styles.card}>
+      {issues.map((issue, index) => (
+        <IssueRow key={issue.key} issue={issue} claim={claim} first={index === 0} {...rowProps} />
+      ))}
+    </View>
+  );
+}
+
+const facts = (issue: NextUpIssue) => [`#${issue.number}`, `${ago(issue.createdAt)} old`, ...[issue.type, issue.priority, issue.effort, issue.scope].filter((v): v is string => !!v)];
+
+// Its main action and ⋯; tapping it opens the sheet with the description, Claim or Unclaim [ATT-06, NXT-07].
+function IssueRow({ issue, claim, first, agents, busy, fetchDetails, onStart, onClaim, onOpenAgent }: RowProps & { issue: NextUpIssue; claim: boolean; first: boolean }) {
+  const styles = useStyles();
+  const [open, setOpen] = useState(false);
+  const agent = agents[issue.key];
+  const startLabel = claim ? "Claim & start" : "Start";
+  return (
+    <View style={[styles.item, first ? null : styles.divider]}>
+      <View style={{ paddingTop: 2 }}>
+        <TablerIcon name={TYPE_ICONS[issue.type?.toLowerCase() ?? ""] ?? "issue"} size={18} color={issue.type === "Bug" ? styles.c.statusDanger : styles.c.foregroundMuted} />
+      </View>
+      <Pressable accessibilityRole="button" accessibilityLabel={`${issue.title}, more`} onPress={() => setOpen(true)} style={styles.body}>
+        <Text style={styles.title} numberOfLines={2}>
+          {issue.title}
+        </Text>
+        <Meta facts={facts(issue)} chips={[]} />
+      </Pressable>
+      <View style={styles.wrap}>
+        {busy === issue.key ? (
+          <Text style={styles.muted}>working…</Text>
+        ) : agent ? (
+          <Button label={styles.compact ? undefined : "Continue"} icon="agent" variant="calm" onPress={() => onOpenAgent(agent.id)} />
+        ) : (
+          // Claim first so teammates see it's taken [NXT-05].
+          <Button label={styles.compact ? undefined : startLabel} accessibilityLabel={`${startLabel} ${issue.title}`} icon="agent" variant="calm" onPress={() => onStart(issue, claim)} />
+        )}
+        <Button icon="dots" variant="ghost" accessibilityLabel="More actions" onPress={() => setOpen(true)} />
+      </View>
+      {open ? <IssueSheet issue={issue} claim={claim} agent={agent} fetchDetails={fetchDetails} onStart={onStart} onClaim={onClaim} onOpenAgent={onOpenAgent} onClose={() => setOpen(false)} /> : null}
+    </View>
+  );
+}
+
+function IssueSheet({
+  issue,
+  claim,
+  agent,
+  fetchDetails,
+  onStart,
+  onClaim,
+  onOpenAgent,
+  onClose,
+}: Pick<Props, "fetchDetails" | "onStart" | "onClaim" | "onOpenAgent"> & { issue: NextUpIssue; claim: boolean; agent?: AgentSummary; onClose: () => void }) {
+  const details = useQuery({
+    queryKey: ["attention-span", "details", issue.key, false],
+    queryFn: () => fetchDetails({ subject: { kind: "issue", repo: issue.repo, number: issue.number }, checks: false }),
+    staleTime: 60_000,
+  });
+  const close = (then: () => void) => () => (onClose(), then());
+  const entries: SheetEntry[] = [
+    agent
+      ? { key: "start", icon: "agent", label: "Continue", detail: "Opens the session started on this issue", onPress: close(() => onOpenAgent(agent.id)) }
+      : {
+          key: "start",
+          icon: "agent",
+          label: claim ? "Claim & start" : "Start",
+          detail: `${claim ? "Assigns you, then an agent" : "An agent"} reads the issue and proposes a plan`,
+          onPress: close(() => onStart(issue, claim)),
+        },
+    claim
+      ? { key: "claim", icon: "claim", label: "Claim", detail: "Assigns you, without starting a session", onPress: close(() => onClaim(issue, true)) }
+      : { key: "unclaim", icon: "unclaim", label: "Unclaim", detail: "Removes you as assignee, so it goes back to Unclaimed", onPress: close(() => onClaim(issue, false)) },
+    { key: "github", icon: "github", label: "Open issue on GitHub", detail: `${issue.repo}#${issue.number}`, onPress: close(() => void openExternalUrl(issue.url)) },
+  ];
+  return (
+    <ActionSheet
+      title={issue.title}
+      onClose={onClose}
+      top={
+        <>
+          <Meta facts={[`${issue.repo}#${issue.number}`, ...facts(issue).slice(1)]} chips={[]} />
+        </>
+      }
+      entries={entries}
+      bottom={<DetailLines details={details.data} loading={details.isLoading} error={details.error} linkedLabel="PR" />}
+    />
+  );
+}

package/client/sessions.ts

@@ -0,0 +1,202 @@
+import type { usePaseo } from "@getpaseo/plugin/client";
+import type { AgentSummary, Target } from "../shared/attention";
+import { type AttentionConfig, codeRepoFor, githubRepoOf, type SessionKind } from "../shared/config";
+
+type Paseo = ReturnType<typeof usePaseo>;
+
+// Labels tie an agent to the item it works on [ATT-07, SES-03].
+export const LABEL = "attention-span";
+export const ITEM_LABEL = "attention-span-item";
+// Sessions started under the plugin's earlier names, "GitHub attention" and "GitHub inbox".
+const OLD_LABELS = ["github-attention", "github-inbox"];
+
+// Agents started from Attention Span, keyed by item.
+export async function itemAgents(paseo: Paseo): Promise<Record<string, AgentSummary>> {
+  const labels = [LABEL, ...OLD_LABELS];
+  const lists = await Promise.all(labels.map((label) => paseo.agents.list({ filter: { labels: { [label]: "1" } } })));
+  const byItem: Record<string, AgentSummary> = {};
+  for (const { agent } of lists.flatMap((list) => list.entries)) {
+    const key = labels.map((label) => agent.labels?.[`${label}-item`]).find(Boolean);
+    if (!key || agent.archivedAt) continue;
+    byItem[key] = {
+      id: agent.id,
+      status: agent.status,
+      requiresAttention: !!agent.requiresAttention,
+      title: agent.title ?? null,
+      workspaceId: agent.workspaceId ?? null,
+    };
+  }
+  return byItem;
+}
+
+export interface ProjectMatch {
+  projectId: string;
+  rootPath: string;
+}
+
+export interface GitHubProject extends ProjectMatch {
+  repo: string;
+}
+
+// Registered Paseo projects with a GitHub remote, by "owner/name".
+export async function githubProjects(paseo: Paseo): Promise<GitHubProject[]> {
+  const { projects } = await paseo.projects.list();
+  return projects.flatMap((project) => {
+    const repo = githubRepoOf(project.projectKey);
+    return repo ? [{ repo, projectId: project.projectId, rootPath: project.projectRootPath }] : [];
+  });
+}
+
+// The local checkout is the registered Paseo project with the repo's GitHub remote [SES-05].
+export async function findProject(paseo: Paseo, repo: string): Promise<ProjectMatch | null> {
+  return (await githubProjects(paseo)).find((project) => project.repo.toLowerCase() === repo.toLowerCase()) ?? null;
+}
+
+export interface Checkout {
+  repo: string;
+  project: ProjectMatch | null;
+  // Where a new branch for an issue starts.
+  baseBranch?: string;
+}
+
+// The item's own repo, or for an issue the repo its code lives in [SES-05, SES-07].
+export async function findCheckout(
+  paseo: Paseo,
+  config: Pick<AttentionConfig, "codeRepos">,
+  target: Target,
+  defaultBranch: (repo: string) => Promise<string | null>,
+): Promise<Checkout> {
+  const repo = target.kind === "issue" ? codeRepoFor(config, target.repo) : target.repo;
+  const project = await findProject(paseo, repo);
+  if (repo.toLowerCase() === target.repo.toLowerCase()) return { repo, project, baseBranch: target.defaultBranch };
+  return { repo, project, baseBranch: project ? ((await defaultBranch(repo)) ?? undefined) : undefined };
+}
+
+export function noProjectMessage(checkout: Checkout, target: Target): string {
+  const where = checkout.repo === target.repo ? checkout.repo : `${checkout.repo}, where ${target.repo}'s code lives,`;
+  return `No Paseo project has ${where} as its GitHub remote. Add the repository as a project first.`;
+}
+
+export interface WorkspaceChoice {
+  id: string;
+  name: string;
+}
+
+// Existing workspaces of the project that have the PR's branch checked out.
+export async function branchWorkspaces(paseo: Paseo, projectId: string, branch: string | undefined): Promise<WorkspaceChoice[]> {
+  if (!branch) return [];
+  const { entries } = await paseo.workspaces.list();
+  return entries
+    .filter((workspace) => workspace.projectId === projectId && workspace.gitRuntime?.currentBranch === branch && !workspace.archivingAt)
+    .map((workspace) => ({ id: workspace.id, name: workspace.title ?? workspace.name }));
+}
+
+export interface ProfileChoice {
+  id: string;
+  name: string;
+}
+
+export async function listProfiles(paseo: Paseo): Promise<ProfileChoice[]> {
+  const { config } = await paseo.config.get();
+  return (config.agentProfiles ?? []).map((profile) => ({ id: profile.id, name: profile.name }));
+}
+
+type AgentConfig = Parameters<Paseo["agents"]["create"]>[0]["config"];
+
+// The profile configured for the session type, then "default", then Paseo's defaults [SES-01, SES-06].
+export async function resolveAgentConfig(
+  paseo: Paseo,
+  kind: SessionKind,
+  config: AttentionConfig,
+  profileId?: string,
+): Promise<{ agent: AgentConfig; label: string }> {
+  const { config: daemon } = await paseo.config.get();
+  const profiles = daemon.agentProfiles ?? [];
+  const byName = (name: string | undefined) =>
+    name ? profiles.find((p) => p.id === name || p.name.toLowerCase() === name.toLowerCase()) : undefined;
+  const profile = profileId ? byName(profileId) : (byName(config.profiles[kind]) ?? byName(config.profiles.default));
+
+  const snapshot = await paseo.providers.snapshot();
+  const providers = snapshot.entries.filter((entry) => entry.status === "ready" && entry.enabled);
+  const defaultModel = (provider: string) => {
+    const entry = providers.find((candidate) => candidate.provider === provider);
+    return (entry?.models ?? []).find((model) => model.isDefault)?.id ?? entry?.models?.[0]?.id;
+  };
+
+  if (profile) {
+    const model = profile.model ?? defaultModel(profile.provider);
+    return {
+      label: profile.name,
+      agent: {
+        provider: model ? `${profile.provider}/${model}` : profile.provider,
+        modeId: profile.modeId,
+        thinkingOptionId: profile.thinkingOptionId,
+        featureValues: profile.featureValues,
+      },
+    };
+  }
+  const fallback = providers.find((entry) => defaultModel(entry.provider));
+  if (!fallback) throw new Error("No agent provider is ready on this host.");
+  return {
+    label: `Paseo default (${fallback.label})`,
+    agent: { provider: `${fallback.provider}/${defaultModel(fallback.provider)}`, modeId: fallback.defaultModeId ?? undefined },
+  };
+}
+
+function slug(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 40);
+}
+
+export interface StartSession {
+  itemKey: string;
+  kind: SessionKind;
+  target: Target;
+  prompt: string;
+  config: AttentionConfig;
+  checkout: Checkout;
+  profileId?: string;
+  workspaceId?: string; // an existing workspace; otherwise a new worktree
+}
+
+// A new worktree: checkout-pr for PRs, branch-off from the default branch for issues.
+export async function startSession(paseo: Paseo, input: StartSession): Promise<string> {
+  const { target, checkout } = input;
+  const project = checkout.project;
+  if (!project) throw new Error(noProjectMessage(checkout, target));
+  const { agent: agentConfig } = await resolveAgentConfig(paseo, input.kind, input.config, input.profileId);
+  const title = `${target.kind === "pr" ? "PR" : "Issue"} ${target.number}: ${target.title}`.slice(0, 120);
+
+  const workspace = input.workspaceId
+    ? paseo.workspaces.ref(input.workspaceId)
+    : await paseo.workspaces.create({
+        title,
+        source:
+          target.kind === "pr"
+            ? {
+                kind: "worktree",
+                cwd: project.rootPath,
+                projectId: project.projectId,
+                action: "checkout",
+                checkoutSource: { kind: "change_request", forge: "github", number: target.number },
+              }
+            : {
+                kind: "worktree",
+                cwd: project.rootPath,
+                projectId: project.projectId,
+                action: "branch-off",
+                baseBranch: checkout.baseBranch,
+                branchName: `issue-${target.number}-${slug(target.title)}`,
+              },
+      });
+  const agent = await workspace.agents.create({
+    config: agentConfig,
+    title,
+    prompt: input.prompt,
+    labels: { [LABEL]: "1", [ITEM_LABEL]: input.itemKey },
+  });
+  return agent.id;
+}