@polygraph/codex-plugin 0.4.34 → 0.4.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/.codex-plugin/plugin.json +12 -10
  2. package/README.md +3 -3
  3. package/assets/polygraph-icon.png +0 -0
  4. package/assets/polygraph-light.svg +18 -0
  5. package/assets/polygraph.svg +18 -0
  6. package/package.json +3 -2
  7. package/skills/await-polygraph-ci/SKILL.md +47 -24
  8. package/skills/polygraph/SKILL.md +35 -3
  9. package/skills/session-start/SKILL.md +78 -0
package/.codex-plugin/plugin.json CHANGED
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "name": "polygraph",
3
- "version": "0.4.34",
4
- "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
3
+ "version": "0.4.36",
4
+ "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
5
5
  "author": {
6
6
  "name": "Narwhal Technologies Inc",
7
7
  "email": "hello@nrwl.io",
8
8
  "url": "https://nx.dev"
9
9
  },
10
- "homepage": "https://nx.dev/features/polygraph",
10
+ "homepage": "https://docs.trypolygraph.com/",
11
11
  "repository": "https://github.com/nrwl/polygraph-skills",
12
12
  "license": "UNLICENSED",
13
13
  "keywords": [
@@ -23,20 +23,22 @@
23
23
  "hooks": "./hooks/hooks.json",
24
24
  "interface": {
25
25
  "displayName": "Polygraph",
26
- "shortDescription": "Multi-repo coordination skills for Codex.",
27
- "longDescription": "Coordinate work across repositories with Polygraph session setup, delegation, and CI monitoring skills.",
26
+ "shortDescription": "Cross-repo visibility and persistent memory for Codex agents.",
27
+ "longDescription": "Give Codex the Polygraph meta-harness: repository graph context, resumable agent sessions, linked PR and CI state, and workflows for coordinating work across repo boundaries when needed.",
28
28
  "developerName": "Narwhal Technologies Inc",
29
29
  "category": "Productivity",
30
30
  "capabilities": [
31
31
  "Read",
32
32
  "Write"
33
33
  ],
34
- "websiteURL": "https://nx.dev/features/polygraph",
34
+ "websiteURL": "https://docs.trypolygraph.com/",
35
35
  "defaultPrompt": [
36
- "Use Polygraph to start a multi-repo session for this change.",
37
- "Use Polygraph to monitor CI across all repos in my Polygraph session.",
38
- "Use Polygraph to delegate work to another repo in the session."
36
+ "Start a Polygraph session for this work.",
37
+ "Start a Polygraph session and include the repos related to this change.",
38
+ "Resume or inspect my Polygraph session and summarize the current state."
39
39
  ],
40
- "brandColor": "#0F172A"
40
+ "brandColor": "#F59E0B",
41
+ "composerIcon": "./assets/polygraph-icon.png",
42
+ "logo": "./assets/polygraph-icon.png"
41
43
  }
42
44
  }
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  <p align="center">
2
2
  <picture>
3
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nrwl/nx-ai-agents-config/main/assets/nx-logo-light.svg">
4
- <img src="https://raw.githubusercontent.com/nrwl/nx-ai-agents-config/main/assets/nx-logo.svg" alt="Nx Logo" width="140">
3
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nrwl/polygraph-skills/main/source/assets/polygraph-light.svg">
4
+ <img src="https://raw.githubusercontent.com/nrwl/polygraph-skills/main/source/assets/polygraph.svg" alt="Polygraph Logo" width="140">
5
5
  </picture>
6
6
  </p>
7
7
 
@@ -37,7 +37,7 @@ It detects your AI agent — Claude Code, Codex, OpenCode, and more — and inst
37
37
 
38
38
  ## Skills
39
39
 
40
- - **polygraph** — Comprehensive guidance for multi-repo coordination: session init, delegation, branch pushing, PR creation, and session management
40
+ - **polygraph** — Comprehensive guidance for Polygraph sessions: shared context, repository graph visibility, PR/CI state, delegation, and session management
41
41
  - **await-polygraph-ci** — Wait for CI pipelines to settle across all repos in a session, investigate failures, and present fix options
42
42
  - **get-latest-ci** — One-shot fetch of the latest CI pipeline execution for the current branch
43
43
 
package/assets/polygraph-icon.png ADDED
Binary file
package/assets/polygraph-light.svg ADDED
@@ -0,0 +1,18 @@
1
+ <svg width="643" height="137" viewBox="0 0 643 137" fill="none" xmlns="http://www.w3.org/2000/svg">
2
+ <path d="M200.11 110.941V34.0205H233.89C242.64 34.0205 249.346 36.4232 254.008 41.2285C258.598 45.9621 260.893 51.8073 260.893 58.7642C260.893 66.0798 258.598 71.9609 254.008 76.4076C249.418 80.8543 243.142 83.0777 235.181 83.0777H216.247V110.941H200.11ZM216.247 47.5758V70.383H232.384C236.401 70.383 239.485 69.3789 241.636 67.3708C243.788 65.2909 244.864 62.4579 244.864 58.8718C244.864 55.2858 243.788 52.5245 241.636 50.588C239.485 48.5799 236.472 47.5758 232.599 47.5758H216.247Z" fill="white" style="fill:white;fill-opacity:1;"/>
3
+ <path d="M309.528 104.271C304.149 109.794 297.227 112.555 288.764 112.555C280.301 112.555 273.38 109.794 268.001 104.271C262.622 98.677 259.933 91.72 259.933 83.4004C259.933 75.0808 262.622 68.1597 268.001 62.6372C273.38 57.0429 280.301 54.2458 288.764 54.2458C297.227 54.2458 304.149 57.0429 309.528 62.6372C314.907 68.1597 317.596 75.0808 317.596 83.4004C317.596 91.72 314.907 98.677 309.528 104.271ZM288.764 101.367C293.139 101.367 296.546 99.7528 298.985 96.5253C301.495 93.2262 302.75 88.8512 302.75 83.4004C302.75 77.9496 301.495 73.5746 298.985 70.2755C296.546 66.9763 293.139 65.3267 288.764 65.3267C284.318 65.3267 280.875 66.9763 278.437 70.2755C275.998 73.5029 274.779 77.8779 274.779 83.4004C274.779 88.8512 275.998 93.2262 278.437 96.5253C280.875 99.7528 284.318 101.367 288.764 101.367Z" fill="white" style="fill:white;fill-opacity:1;"/>
4
+ <path d="M321.385 110.941V34.0205H336.016V110.941H321.385Z" fill="white" style="fill:white;fill-opacity:1;"/>
5
+ <path d="M415.932 129.768C408.473 129.768 402.485 128.262 397.966 125.25C393.52 122.237 390.902 118.006 390.113 112.555H404.636C406.071 116.643 409.764 118.687 415.717 118.687C423.893 118.687 427.982 114.85 427.982 107.176V101.151H427.659C423.858 105.455 419.052 107.606 413.243 107.606C406.716 107.606 401.014 105.204 396.137 100.398C391.332 95.593 388.929 89.2098 388.929 81.2488C388.929 73.0726 391.153 66.546 395.6 61.6689C400.046 56.7202 405.784 54.2458 412.813 54.2458C419.483 54.2458 424.575 56.6843 428.089 61.5614H428.304V55.752H442.397V106.746C442.397 113.918 440.21 119.512 435.835 123.528C431.388 127.688 424.754 129.768 415.932 129.768ZM415.717 95.8798C420.092 95.8798 423.356 94.4813 425.507 91.6842C427.659 88.8871 428.735 85.301 428.735 80.926C428.735 76.6228 427.587 73.0726 425.292 70.2755C423.069 67.4066 419.841 65.9722 415.61 65.9722C411.88 65.9722 408.868 67.3349 406.573 70.0603C404.349 72.7857 403.238 76.4435 403.238 81.0336C403.238 85.6955 404.349 89.3532 406.573 92.0069C408.868 94.5889 411.916 95.8798 415.717 95.8798Z" fill="white" style="fill:white;fill-opacity:1;"/>
6
+ <path d="M462.684 55.752V64.5736H463.007C464.728 61.3462 466.629 58.9794 468.709 57.4733C470.789 55.8954 473.406 55.1065 476.562 55.1065C478.068 55.1065 479.216 55.2499 480.005 55.5368V68.339H479.682C474.733 67.8369 470.753 68.9128 467.74 71.5664C464.728 74.2201 463.222 78.3799 463.222 84.0459V110.941H448.591V55.752H462.684Z" fill="white" style="fill:white;fill-opacity:1;"/>
7
+ <path d="M516.253 110.941C515.536 110.009 514.962 107.965 514.532 104.809H514.316C512.739 107.176 510.73 109.005 508.292 110.296C505.853 111.587 502.447 112.232 498.072 112.232C492.262 112.232 487.6 110.762 484.086 107.821C480.572 104.881 478.815 100.721 478.815 95.3419C478.815 89.7477 480.751 85.6596 484.624 83.0777C488.497 80.424 493.948 78.5951 500.976 77.591C506.14 76.8738 509.655 76.1566 511.519 75.4394C513.384 74.6504 514.316 73.2877 514.316 71.3513C514.316 69.3431 513.528 67.7652 511.95 66.6177C510.372 65.3984 508.077 64.7888 505.065 64.7888C498.394 64.7888 494.844 67.3708 494.414 72.5347H481.397C481.612 67.299 483.728 62.9599 487.744 59.5173C491.76 56.0747 497.57 54.3534 505.172 54.3534C520.664 54.3534 528.41 61.131 528.41 74.6863V102.765C528.41 106.925 529.055 109.471 530.346 110.403V110.941H516.253ZM501.622 102.012C505.638 102.012 508.794 100.972 511.089 98.8921C513.456 96.8122 514.639 94.3378 514.639 91.469V83.1852C513.061 84.1176 509.655 85.1934 504.419 86.4127C500.259 87.3451 497.319 88.4209 495.597 89.6401C493.876 90.7877 493.015 92.5807 493.015 95.0192C493.015 99.6811 495.884 102.012 501.622 102.012Z" fill="white" style="fill:white;fill-opacity:1;"/>
8
+ <path d="M534.484 129.015V55.752H548.577V62.6372H548.9C552.988 57.0429 558.403 54.2458 565.145 54.2458C572.388 54.2458 578.198 56.9354 582.573 62.3144C586.948 67.6935 589.135 74.7222 589.135 83.4004C589.135 92.2938 586.948 99.3942 582.573 104.702C578.198 109.937 572.424 112.555 565.252 112.555C558.08 112.555 552.773 109.937 549.33 104.702H549.115V129.015H534.484ZM562.132 100.398C565.862 100.398 568.802 98.928 570.954 95.9874C573.177 93.0469 574.289 88.9946 574.289 83.8307C574.289 78.3082 573.249 73.9691 571.169 70.8134C569.089 67.6576 565.898 66.0798 561.594 66.0798C557.219 66.0798 553.992 67.7294 551.912 71.0285C549.832 74.256 548.792 78.5234 548.792 83.8307C548.792 88.9229 549.94 92.9751 552.235 95.9874C554.53 98.928 557.829 100.398 562.132 100.398Z" fill="white" style="fill:white;fill-opacity:1;"/>
9
+ <path d="M607.348 34.0205V62.9599H607.67C609.75 59.9476 612.009 57.7601 614.448 56.3974C616.958 54.963 620.042 54.2458 623.7 54.2458C629.366 54.2458 633.956 56.1823 637.47 60.0552C640.985 63.8564 642.742 68.8052 642.742 74.9015V110.941H628.111V77.0531C628.111 74.0408 627.25 71.6023 625.529 69.7376C623.879 67.8728 621.548 66.9404 618.536 66.9404C615.309 66.9404 612.619 68.1238 610.467 70.4906C608.387 72.8574 607.348 75.9056 607.348 79.635V110.941H592.716V34.0205H607.348Z" fill="white" style="fill:white;fill-opacity:1;"/>
10
+ <path d="M310.497 128.8V117.33H348.587C354.054 117.33 356.788 114.828 356.788 109.826C356.788 107.396 355.385 102.43 352.579 94.9259L337.688 55.7996H353.119L361.32 80.5617L364.881 92.5676H365.097C366.104 87.9225 367.183 83.9205 368.334 80.5617L376.103 55.7996H390.887L371.738 112.184C369.58 118.473 367.12 122.941 364.387 125.3C361.725 127.729 357.564 129.014 352.097 129.014L310.497 128.8Z" fill="url(#paint0_linear_1470_2067)"/>
11
+ <path d="M96.7786 53.7941C97.9048 55.7445 100.72 55.7445 101.846 53.794L132.059 1.46337C132.867 0.0640056 134.656 -0.41546 136.055 0.39246L145.627 5.91882C147.027 6.72673 147.506 8.51606 146.698 9.91541L116.486 62.2464C115.36 64.1969 116.767 66.635 119.02 66.635L150.269 66.6349C151.884 66.6349 153.194 67.9448 153.194 69.5606L153.194 80.6134C153.194 82.2292 151.884 83.5391 150.269 83.5391L119.02 83.5392C116.767 83.5392 115.36 85.9773 116.486 87.9278L138.571 126.181C139.379 127.581 138.9 129.37 137.5 130.178L127.929 135.704C126.529 136.512 124.74 136.033 123.932 134.633L101.846 96.3799C100.72 94.4294 97.9049 94.4294 96.7788 96.3799L81.1539 123.443C80.346 124.842 78.5566 125.321 77.1573 124.513L67.5853 118.987C66.1859 118.179 65.7065 116.39 66.5144 114.99L82.1394 87.9274C83.2655 85.9769 81.8579 83.5388 79.6057 83.5388L2.92574 83.539C1.3099 83.539 -1.67575e-06 82.2291 0 80.6133L1.14625e-05 69.5606C1.31383e-05 67.9447 1.3099 66.6349 2.92574 66.6349L79.6055 66.6348C81.8577 66.6348 83.2653 64.1967 82.1392 62.2462L66.5144 35.1833C65.7065 33.784 66.186 31.9946 67.5853 31.1867L77.1573 25.6603C78.5567 24.8524 80.346 25.3319 81.1539 26.7312L96.7786 53.7941Z" fill="#F59E0B" style="fill:#F59E0B;fill:color(display-p3 0.9608 0.6196 0.0431);fill-opacity:1;"/>
12
+ <defs>
13
+ <linearGradient id="paint0_linear_1470_2067" x1="340.27" y1="122.652" x2="313.266" y2="122.652" gradientUnits="userSpaceOnUse">
14
+ <stop stop-color="white" style="stop-color:white;stop-opacity:1;"/>
15
+ <stop offset="1" stop-color="white" stop-opacity="0" style="stop-color:none;stop-opacity:0;"/>
16
+ </linearGradient>
17
+ </defs>
18
+ </svg>
package/assets/polygraph.svg ADDED
@@ -0,0 +1,18 @@
1
+ <svg width="643" height="137" viewBox="0 0 643 137" fill="none" xmlns="http://www.w3.org/2000/svg">
2
+ <path d="M200.11 110.941V34.0205H233.89C242.64 34.0205 249.346 36.4232 254.008 41.2285C258.598 45.9621 260.893 51.8073 260.893 58.7642C260.893 66.0798 258.598 71.9609 254.008 76.4076C249.418 80.8543 243.142 83.0777 235.181 83.0777H216.247V110.941H200.11ZM216.247 47.5758V70.383H232.384C236.401 70.383 239.485 69.3789 241.636 67.3708C243.788 65.2909 244.864 62.4579 244.864 58.8718C244.864 55.2858 243.788 52.5245 241.636 50.588C239.485 48.5799 236.472 47.5758 232.599 47.5758H216.247Z" fill="#0A0A0A" style="fill:#0A0A0A;fill:color(display-p3 0.0392 0.0392 0.0392);fill-opacity:1;"/>
3
+ <path d="M309.528 104.271C304.149 109.794 297.227 112.555 288.764 112.555C280.301 112.555 273.38 109.794 268.001 104.271C262.622 98.677 259.933 91.72 259.933 83.4004C259.933 75.0808 262.622 68.1597 268.001 62.6372C273.38 57.0429 280.301 54.2458 288.764 54.2458C297.227 54.2458 304.149 57.0429 309.528 62.6372C314.907 68.1597 317.596 75.0808 317.596 83.4004C317.596 91.72 314.907 98.677 309.528 104.271ZM288.764 101.367C293.139 101.367 296.546 99.7528 298.985 96.5253C301.495 93.2262 302.75 88.8512 302.75 83.4004C302.75 77.9496 301.495 73.5746 298.985 70.2755C296.546 66.9763 293.139 65.3267 288.764 65.3267C284.318 65.3267 280.875 66.9763 278.437 70.2755C275.998 73.5029 274.779 77.8779 274.779 83.4004C274.779 88.8512 275.998 93.2262 278.437 96.5253C280.875 99.7528 284.318 101.367 288.764 101.367Z" fill="#0A0A0A" style="fill:#0A0A0A;fill:color(display-p3 0.0392 0.0392 0.0392);fill-opacity:1;"/>
4
+ <path d="M321.385 110.941V34.0205H336.016V110.941H321.385Z" fill="#0A0A0A" style="fill:#0A0A0A;fill:color(display-p3 0.0392 0.0392 0.0392);fill-opacity:1;"/>
5
+ <path d="M415.932 129.768C408.473 129.768 402.485 128.262 397.966 125.25C393.52 122.237 390.902 118.006 390.113 112.555H404.636C406.071 116.643 409.764 118.687 415.717 118.687C423.893 118.687 427.982 114.85 427.982 107.176V101.151H427.659C423.858 105.455 419.052 107.606 413.243 107.606C406.716 107.606 401.014 105.204 396.137 100.398C391.332 95.593 388.929 89.2098 388.929 81.2488C388.929 73.0726 391.153 66.546 395.6 61.6689C400.046 56.7202 405.784 54.2458 412.813 54.2458C419.483 54.2458 424.575 56.6843 428.089 61.5614H428.304V55.752H442.397V106.746C442.397 113.918 440.21 119.512 435.835 123.528C431.388 127.688 424.754 129.768 415.932 129.768ZM415.717 95.8798C420.092 95.8798 423.356 94.4813 425.507 91.6842C427.659 88.8871 428.735 85.301 428.735 80.926C428.735 76.6228 427.587 73.0726 425.292 70.2755C423.069 67.4066 419.841 65.9722 415.61 65.9722C411.88 65.9722 408.868 67.3349 406.573 70.0603C404.349 72.7857 403.238 76.4435 403.238 81.0336C403.238 85.6955 404.349 89.3532 406.573 92.0069C408.868 94.5889 411.916 95.8798 415.717 95.8798Z" fill="#0A0A0A" style="fill:#0A0A0A;fill:color(display-p3 0.0392 0.0392 0.0392);fill-opacity:1;"/>
6
+ <path d="M462.684 55.752V64.5736H463.007C464.728 61.3462 466.629 58.9794 468.709 57.4733C470.789 55.8954 473.406 55.1065 476.562 55.1065C478.068 55.1065 479.216 55.2499 480.005 55.5368V68.339H479.682C474.733 67.8369 470.753 68.9128 467.74 71.5664C464.728 74.2201 463.222 78.3799 463.222 84.0459V110.941H448.591V55.752H462.684Z" fill="#0A0A0A" style="fill:#0A0A0A;fill:color(display-p3 0.0392 0.0392 0.0392);fill-opacity:1;"/>
7
+ <path d="M516.253 110.941C515.536 110.009 514.962 107.965 514.532 104.809H514.316C512.739 107.176 510.73 109.005 508.292 110.296C505.853 111.587 502.447 112.232 498.072 112.232C492.262 112.232 487.6 110.762 484.086 107.821C480.572 104.881 478.815 100.721 478.815 95.3419C478.815 89.7477 480.751 85.6596 484.624 83.0777C488.497 80.424 493.948 78.5951 500.976 77.591C506.14 76.8738 509.655 76.1566 511.519 75.4394C513.384 74.6504 514.316 73.2877 514.316 71.3513C514.316 69.3431 513.528 67.7652 511.95 66.6177C510.372 65.3984 508.077 64.7888 505.065 64.7888C498.394 64.7888 494.844 67.3708 494.414 72.5347H481.397C481.612 67.299 483.728 62.9599 487.744 59.5173C491.76 56.0747 497.57 54.3534 505.172 54.3534C520.664 54.3534 528.41 61.131 528.41 74.6863V102.765C528.41 106.925 529.055 109.471 530.346 110.403V110.941H516.253ZM501.622 102.012C505.638 102.012 508.794 100.972 511.089 98.8921C513.456 96.8122 514.639 94.3378 514.639 91.469V83.1852C513.061 84.1176 509.655 85.1934 504.419 86.4127C500.259 87.3451 497.319 88.4209 495.597 89.6401C493.876 90.7877 493.015 92.5807 493.015 95.0192C493.015 99.6811 495.884 102.012 501.622 102.012Z" fill="#0A0A0A" style="fill:#0A0A0A;fill:color(display-p3 0.0392 0.0392 0.0392);fill-opacity:1;"/>
8
+ <path d="M534.484 129.015V55.752H548.577V62.6372H548.9C552.988 57.0429 558.403 54.2458 565.145 54.2458C572.388 54.2458 578.198 56.9354 582.573 62.3144C586.948 67.6935 589.135 74.7222 589.135 83.4004C589.135 92.2938 586.948 99.3942 582.573 104.702C578.198 109.937 572.424 112.555 565.252 112.555C558.08 112.555 552.773 109.937 549.33 104.702H549.115V129.015H534.484ZM562.132 100.398C565.862 100.398 568.802 98.928 570.954 95.9874C573.177 93.0469 574.289 88.9946 574.289 83.8307C574.289 78.3082 573.249 73.9691 571.169 70.8134C569.089 67.6576 565.898 66.0798 561.594 66.0798C557.219 66.0798 553.992 67.7294 551.912 71.0285C549.832 74.256 548.792 78.5234 548.792 83.8307C548.792 88.9229 549.94 92.9751 552.235 95.9874C554.53 98.928 557.829 100.398 562.132 100.398Z" fill="#0A0A0A" style="fill:#0A0A0A;fill:color(display-p3 0.0392 0.0392 0.0392);fill-opacity:1;"/>
9
+ <path d="M607.348 34.0205V62.9599H607.67C609.75 59.9476 612.009 57.7601 614.448 56.3974C616.958 54.963 620.042 54.2458 623.7 54.2458C629.366 54.2458 633.956 56.1823 637.47 60.0552C640.985 63.8564 642.742 68.8052 642.742 74.9015V110.941H628.111V77.0531C628.111 74.0408 627.25 71.6023 625.529 69.7376C623.879 67.8728 621.548 66.9404 618.536 66.9404C615.309 66.9404 612.619 68.1238 610.467 70.4906C608.387 72.8574 607.348 75.9056 607.348 79.635V110.941H592.716V34.0205H607.348Z" fill="#0A0A0A" style="fill:#0A0A0A;fill:color(display-p3 0.0392 0.0392 0.0392);fill-opacity:1;"/>
10
+ <path d="M310.497 128.8V117.33H348.587C354.054 117.33 356.788 114.828 356.788 109.826C356.788 107.396 355.385 102.43 352.579 94.9259L337.688 55.7996H353.119L361.32 80.5617L364.881 92.5676H365.097C366.104 87.9225 367.183 83.9205 368.334 80.5617L376.103 55.7996H390.887L371.738 112.184C369.58 118.473 367.12 122.941 364.387 125.3C361.725 127.729 357.564 129.014 352.097 129.014L310.497 128.8Z" fill="url(#paint0_linear_1470_2069)"/>
11
+ <path d="M96.7786 53.7941C97.9048 55.7445 100.72 55.7445 101.846 53.794L132.059 1.46337C132.867 0.0640056 134.656 -0.41546 136.055 0.39246L145.627 5.91882C147.027 6.72673 147.506 8.51606 146.698 9.91541L116.486 62.2464C115.36 64.1969 116.767 66.635 119.02 66.635L150.269 66.6349C151.884 66.6349 153.194 67.9448 153.194 69.5606L153.194 80.6134C153.194 82.2292 151.884 83.5391 150.269 83.5391L119.02 83.5392C116.767 83.5392 115.36 85.9773 116.486 87.9278L138.571 126.181C139.379 127.581 138.9 129.37 137.5 130.178L127.929 135.704C126.529 136.512 124.74 136.033 123.932 134.633L101.846 96.3799C100.72 94.4294 97.9049 94.4294 96.7788 96.3799L81.1539 123.443C80.346 124.842 78.5566 125.321 77.1573 124.513L67.5853 118.987C66.1859 118.179 65.7065 116.39 66.5144 114.99L82.1394 87.9274C83.2655 85.9769 81.8579 83.5388 79.6057 83.5388L2.92574 83.539C1.3099 83.539 -1.67575e-06 82.2291 0 80.6133L1.14625e-05 69.5606C1.31383e-05 67.9447 1.3099 66.6349 2.92574 66.6349L79.6055 66.6348C81.8577 66.6348 83.2653 64.1967 82.1392 62.2462L66.5144 35.1833C65.7065 33.784 66.186 31.9946 67.5853 31.1867L77.1573 25.6603C78.5567 24.8524 80.346 25.3319 81.1539 26.7312L96.7786 53.7941Z" fill="#F59E0B" style="fill:#F59E0B;fill:color(display-p3 0.9608 0.6196 0.0431);fill-opacity:1;"/>
12
+ <defs>
13
+ <linearGradient id="paint0_linear_1470_2069" x1="340.27" y1="122.652" x2="313.266" y2="122.652" gradientUnits="userSpaceOnUse">
14
+ <stop stop-color="#0A0A0A" style="stop-color:#0A0A0A;stop-color:color(display-p3 0.0392 0.0392 0.0392);stop-opacity:1;"/>
15
+ <stop offset="1" stop-color="#0A0A0A" stop-opacity="0" style="stop-color:none;stop-opacity:0;"/>
16
+ </linearGradient>
17
+ </defs>
18
+ </svg>
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@polygraph/codex-plugin",
3
- "version": "0.4.34",
4
- "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
3
+ "version": "0.4.36",
4
+ "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
5
5
  "license": "UNLICENSED",
6
6
  "private": false,
7
7
  "author": {
@@ -27,6 +27,7 @@
27
27
  "skills/",
28
28
  "agents/",
29
29
  "hooks/",
30
+ "assets/",
30
31
  ".mcp.json",
31
32
  "README.md",
32
33
  "bin/"
package/skills/await-polygraph-ci/SKILL.md CHANGED
@@ -10,9 +10,30 @@ Wait for all CI pipelines in a Polygraph session to reach a stable state (succee
10
10
 
11
11
  Some Polygraph tools have both MCP and CLI equivalents — use whichever is available in your environment. See the polygraph skill's tool table for the full mapping.
12
12
 
13
+ ## CI status source
14
+
15
+ CI polling uses the polygraph-mcp `show_session` tool, which now carries per-PR CI status directly on each pull request:
16
+
17
+ ```
18
+ show_session(sessionId: "<session-id>")
19
+ ```
20
+
21
+ It returns the full session, including `repositories[]` (for repo display names) and `pullRequests[]`. Each `pullRequests[]` entry has `id`, `repositoryId`, `url`, `branch`, `status` (PR status: `DRAFT` / `OPEN` / `MERGED` / `CLOSED`), and a `ci` object — **`ci` may be absent if the PR has no CI**. When present, `ci` has `status`, `cipeUrl` (non-null ⇒ CIPE; null + `externalCIRuns` ⇒ external CI), `completedAt`, `selfHealingStatus`, and `externalCIRuns[]` (each with `runId`, `name`, `status`, `conclusion`, `url`, and `jobs[]`). Always read `ci` defensively (`pr.ci?.…`).
22
+
23
+ ## Prerequisite: Nx MCP server (CIPE deep-dive + self-healing)
24
+
25
+ CIPE failure investigation (`ci_information`) and applying/rejecting self-healing fixes (`update_self_healing_fix`) are **not** polygraph-mcp tools — they are provided by the **Nx MCP server** (`mcp__plugin_nx_nx-mcp`). Before relying on the Phase 4 CIPE deep-dive or the Phase 5 self-healing actions, install the Nx MCP server and verify it is available.
26
+
27
+ If the Nx MCP server is **not** available, this skill can still:
28
+
29
+ - Monitor CI to a terminal state (Phases 1–3) via `show_session`, and
30
+ - Download and inspect **external-CI** job logs via `get_ci_logs` (a polygraph-mcp tool).
31
+
32
+ But it **cannot** perform CIPE deep-dives (`ci_information`) or apply self-healing fixes (`update_self_healing_fix`) without the Nx MCP server. If nx-mcp is missing, state this limitation to the user explicitly.
33
+
13
34
  ## Phase 1: Session Setup
14
35
 
15
- Fetch the Polygraph session using `show_session`.
36
+ Fetch the session using `show_session` and read per-PR CI status from `pullRequests[]`.
16
37
 
17
38
  **Parameters:**
18
39
 
@@ -23,16 +44,18 @@ show_session(sessionId: "<session-id>")
23
44
  ```
24
45
 
25
46
  1. Record `monitorStartedAt` = current timestamp (epoch millis).
26
- 2. Build a tracking table of all repos with PRs. For each PR, record:
27
- - `repo`: repository name
28
- - `prUrl`: PR URL
29
- - `prStatus`: DRAFT / OPEN / MERGED / CLOSED
30
- - `ciStatus`: from session (may already be a terminal status from a previous run)
31
- - `cipeUrl`: CI pipeline URL (null if none)
32
- - `cipeCompletedAt`: `completedAt` from session (epoch millis, null if CIPE is active or absent)
33
- - `selfHealingStatus`: self-healing fix status (null if none)
47
+ 2. Build a tracking table from `pullRequests[]`. For each PR, map:
48
+ - `repo`: repository display name from the matching `repositories[]` entry by `pr.repositoryId` (fall back to `pr.branch` if not found)
49
+ - `repoId`: `pr.repositoryId` (pass straight to `get_ci_logs`)
50
+ - `prUrl`: `pr.url`
51
+ - `prStatus`: `pr.status` (DRAFT / OPEN / MERGED / CLOSED)
52
+ - `ciStatus`: `pr.ci?.status` (may already be a terminal status from a previous run)
53
+ - `cipeUrl`: `pr.ci?.cipeUrl` (null if none → external CI or no CI)
54
+ - `cipeCompletedAt`: `pr.ci?.completedAt` (epoch millis, null if CIPE is active or absent)
55
+ - `selfHealingStatus`: `pr.ci?.selfHealingStatus` (null if none)
56
+ - `jobs`: `pr.ci?.externalCIRuns?.flatMap(r => r.jobs)` (external-CI job list, used in Phase 4)
34
57
  - `firstSeenAt`: current timestamp
35
- 3. If no PRs found, report "No PRs in session" and exit.
58
+ 3. If `pullRequests[]` is empty, report "No PRs in session" and exit.
36
59
  4. **Stale detection**: For each PR, determine if its CI status is **stale** — meaning it reflects a previous run, not a current one. A PR's CI status is stale if:
37
60
  - `cipeCompletedAt` is non-null AND `cipeCompletedAt < monitorStartedAt` (the CIPE finished before the monitor started)
38
61
  - Mark these PRs as `stale: true`
@@ -52,7 +75,7 @@ show_session(sessionId: "<session-id>")
52
75
  **Each poll iteration:**
53
76
 
54
77
  1. Call `show_session(sessionId: <session-id>)`
55
- 2. Update each tracked PR from the session response: `ciStatus`, `cipeUrl`, `cipeCompletedAt`, and `selfHealingStatus`
78
+ 2. Update each tracked PR from its matching `pullRequests[]` entry (by PR `id` / `repositoryId`): `ciStatus` ← `pr.ci?.status`, `cipeUrl` ← `pr.ci?.cipeUrl`, `cipeCompletedAt` ← `pr.ci?.completedAt`, `selfHealingStatus` ← `pr.ci?.selfHealingStatus`, `prStatus` ← `pr.status`, and `jobs` ← `pr.ci?.externalCIRuns?.flatMap(r => r.jobs)`
56
79
  3. **Clear stale flag**: If a PR was marked `stale: true` and its `cipeCompletedAt` has changed (or become null, meaning a new CIPE is active), clear the stale flag — this PR now has fresh CI data.
57
80
  4. Display status update:
58
81
  ```
@@ -100,20 +123,20 @@ Include self-healing status for any repo that has one.
100
123
 
101
124
  ## Phase 4: Failure Investigation (Child Agent Delegation)
102
125
 
103
- For each repo with `ciStatus: FAILED`, first check the CI data source from `ciStatus[prId]`:
126
+ For each repo with `ciStatus: FAILED`, branch on the PR's `ci` object from `show_session` (`pullRequests[]`):
104
127
 
105
- - **If `cipeUrl` is non-null** → CIPE is authoritative. Delegate investigation using `ci_information`.
106
- - **If `cipeUrl` is null but `externalCIRuns` exists** → external CI only. Examine failed jobs from `externalCIRuns` in the session data and use `get_ci_logs` for log retrieval.
128
+ - **If `pr.ci.cipeUrl` is non-null** → CIPE is authoritative. Delegate investigation using the Nx MCP `ci_information` tool (requires the Nx MCP server — see the prerequisite note above; if nx-mcp is unavailable, report the CIPE URL but note the deep-dive can't run).
129
+ - **If `pr.ci.cipeUrl` is null but `pr.ci.externalCIRuns` exists** → external CI only. Examine failed jobs from `pr.ci.externalCIRuns[].jobs` and use `get_ci_logs(sessionId, repositoryId, jobId)` (a polygraph-mcp tool) for log retrieval, passing `pr.repositoryId` and the failed job's `jobId` straight from the same PR object.
107
130
 
108
131
  **Codex subagent wrapper:** Use `polygraph-delegate-subagent` to keep the Polygraph MCP `spawn_agent` / `show_agent` polling loop out of the main conversation. For each failed repo, launch a Codex `spawn_agent` with `agent_type: "polygraph-delegate-subagent"` and instructions to perform steps 2-4 below for that repo, then collect completed summaries with `wait_agent` when the main flow needs them. In the steps below, `spawn_agent` and `show_agent` refer to the Polygraph MCP tools that belong inside the Codex subagent.
109
132
 
110
- 1. Display known info from the session data before delegating:
133
+ 1. Display known info from the PR's `ci` object before delegating:
111
134
 
112
135
  ```
113
136
  Repository: frontend
114
137
  CI Source: <CIPE or External CI (GitHub Actions)>
115
- CI Pipeline: <cipeUrl from session, or GitHub Actions run URL>
116
- Self-healing: <selfHealingStatus from session, or "None">
138
+ CI Pipeline: <pr.ci.cipeUrl, or GitHub Actions run URL>
139
+ Self-healing: <pr.ci.selfHealingStatus, or "None">
117
140
  Investigating failure details...
118
141
  ```
119
142
 
@@ -121,9 +144,9 @@ For each repo with `ciStatus: FAILED`, first check the CI data source from `ciSt
121
144
 
122
145
  - `sessionId`: the session ID
123
146
  - `repo`: the repository name
124
- - `instruction` (when CIPE exists): Use the `ci_information` tool to investigate the CI failure on this branch. Return a structured summary with: (1) list of failed task IDs with a one-line error summary each, (2) failure category (Build / Test / Lint / E2E / Infra / Other).
125
- - `instruction` (when no CIPE, external CI only): The session data shows external CI failures with these failed jobs: [list jobId + name from `externalCIRuns[].jobs` where `conclusion` is `failure`]. Use `get_ci_logs(sessionId, repoId, jobId)` to save the log for each failed job to a local file, then use the `Read` tool to examine the log file contents. Return a structured summary with: (1) one-line error summary per failed job, (2) failure category (Build / Test / Lint / E2E / Infra / Other), (3) relevant log excerpts.
126
- - `context`: Polygraph session monitoring — investigating CI failure for unified summary. The repository ID for this repo is available from the session data.
147
+ - `instruction` (when CIPE exists): Use the Nx MCP `ci_information` tool to investigate the CI failure on this branch (the Nx MCP server must be installed). Return a structured summary with: (1) list of failed task IDs with a one-line error summary each, (2) failure category (Build / Test / Lint / E2E / Infra / Other).
148
+ - `instruction` (when no CIPE, external CI only): The PR's `ci` object shows external CI failures with these failed jobs: [list `jobId` + `name` from `pr.ci.externalCIRuns[].jobs` where `conclusion` is `failure`]. Use `get_ci_logs(sessionId, repositoryId, jobId)` to save the log for each failed job to a local file, then use the `Read` tool to examine the log file contents. Return a structured summary with: (1) one-line error summary per failed job, (2) failure category (Build / Test / Lint / E2E / Infra / Other), (3) relevant log excerpts.
149
+ - `context`: Polygraph session monitoring — investigating CI failure for unified summary. The repository ID for this repo is the PR's `repositoryId`.
127
150
 
128
151
  Since `spawn_agent` is non-blocking, you can delegate to multiple failed repos in parallel.
129
152
 
@@ -158,7 +181,7 @@ For each repo with `ciStatus: FAILED`, first check the CI data source from `ciSt
158
181
  2. Identify cross-repo dependency issues (e.g., shared-lib build failure blocking frontend)
159
182
  3. Suggest fix order based on dependency graph (upstream repos first)
160
183
  4. Present next actions to the user based on self-healing status:
161
- - If any repo has `selfHealingStatus` with an available fix → offer to **apply self-healing** via `update_self_healing_fix(action: "APPLY")` or **reject** it
184
+ - If any repo has `selfHealingStatus` with an available fix → offer to **apply self-healing** via `update_self_healing_fix(action: "APPLY")` or **reject** it. `update_self_healing_fix` is an **Nx MCP** tool (`mcp__plugin_nx_nx-mcp`) — it requires the Nx MCP server. If nx-mcp is unavailable, report that a fix is available but cannot be applied from here.
162
185
  - If self-healing was already applied → offer to **resume monitoring** to watch the re-triggered CI
163
186
  - **Delegate fixes**: use Polygraph to send fix instructions to child agents (for repos without self-healing or where self-healing was rejected/failed)
164
187
  - **Get more details**: drill into a specific repo's failure
@@ -166,12 +189,12 @@ For each repo with `ciStatus: FAILED`, first check the CI data source from `ciSt
166
189
 
167
190
  ## Notes
168
191
 
169
- - This skill does NOT push code directly. The only write action it may take is applying/rejecting a self-healing fix via `update_self_healing_fix`, which is an Nx Cloud operation (not a local code change).
170
- - Both `ci_information` and `update_self_healing_fix` responses include a `hints` array with contextual guidance (e.g., disclaimers about which CI Attempt was retrieved). Always check and surface non-empty hints.
192
+ - This skill does NOT push code directly. The only write action it may take is applying/rejecting a self-healing fix via `update_self_healing_fix`, an **Nx MCP** tool that performs an Nx Cloud operation (not a local code change) and requires the Nx MCP server.
193
+ - Both `ci_information` and `update_self_healing_fix` are **Nx MCP** tools (`mcp__plugin_nx_nx-mcp`), not polygraph-mcp tools. Their responses include a `hints` array with contextual guidance (e.g., disclaimers about which CI Attempt was retrieved). Always check and surface non-empty hints.
171
194
  - All heavy CI data inspection happens in child agents via `spawn_agent` to keep this context window clean.
172
195
 
173
196
  - On Codex, the delegate-and-poll loop should run inside `polygraph-delegate-subagent`, and the main conversation should use `wait_agent` only when it needs to collect results.
174
197
 
175
- - Child agents can use `get_ci_logs` to save CI job logs to local files, but ONLY when no CIPE exists for the PR (`ciStatus[prId].cipeUrl` is null). When a CIPE exists, logs come from the CIPE system via `ci_information`. Job IDs come from `ciStatus[prId].externalCIRuns[].jobs[].jobId` in the `show_session` response. The tool returns a file path (`logFile`) and size (`sizeBytes`) — use the `Read` tool to examine the log content. Logs can be large (100KB+), so only fetch logs for failed or relevant jobs.
198
+ - Child agents can use `get_ci_logs` to save CI job logs to local files, but ONLY when no CIPE exists for the PR (`pr.ci.cipeUrl` is null). When a CIPE exists, logs come from the CIPE system via the Nx MCP `ci_information` tool. Job IDs come from `pr.ci.externalCIRuns[].jobs[].jobId` in the `show_session` response. The tool returns a file path (`logFile`) and size (`sizeBytes`) — use the `Read` tool to examine the log content. Logs can be large (100KB+), so only fetch logs for failed or relevant jobs.
176
199
  - `spawn_agent` is **non-blocking** — it starts the child agent and returns immediately. Use `show_agent` to poll for results and `stop_agent` to terminate stuck agents.
177
200
  - The `show_session` response is compact and safe to poll from the main agent.
package/skills/polygraph/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: polygraph
3
- description: Guidance for working with Polygraph — repositories, sessions, child agents, PRs, and CI. Use when discovering repositories or how code is consumed across them, starting, joining, resuming, or sharing a Polygraph session, handing off progress, coordinating changes/branches/PRs across repos, delegating tasks to child agents in different repos, or checking CI status and logs. TRIGGER when user mentions "polygraph", resuming or sharing a session, "other repos", "other repositories", "who uses this", "what uses this", "cross-repo", "multi-repo", "consuming this API/endpoint", "dependent repositories", or asks about what other repos are doing with shared code/APIs/endpoints.
3
+ description: Guidance for working with Polygraph sessions, shared/resumable agent context, repository graph visibility, linked PR/CI state, and cross-repo expansion when needed. Use when starting, joining, resuming, inspecting, or sharing a Polygraph session; handing off progress; discovering related repositories; coordinating changes/branches/PRs across repos; delegating tasks to child agents in different repos; or checking CI status and logs. TRIGGER when user mentions "polygraph", resuming or sharing a session, "other repos", "other repositories", "who uses this", "what uses this", "cross-repo", "multi-repo", "consuming this API/endpoint", "dependent repositories", or asks about what other repos are doing with shared code/APIs/endpoints.
4
4
 
5
5
  ---
6
6
 
@@ -23,6 +23,30 @@ Polygraph connects repositories and the agent work happening across them. Its ce
23
23
 
24
24
  **Polygraph operates on the current repo in place.** Starting or joining a session never clones or modifies the repository you are in — you keep working in your real working directory, and `push_branch` pushes your local commits from that checkout. Only *other* repositories are worked on in separate Polygraph-managed clones via `spawn_agent`.
25
25
 
26
+ ## Sandboxing in Polygraph Sessions
27
+
28
+ Polygraph launches agent sessions inside an OS-level sandbox by default. Writes are limited to the repository working tree, the session root (`~/.polygraph/sessions/<session-id>/`), the system temp directory, and a few allowlisted directories; network access is restricted to allowlisted hosts. In practice: binding a listening socket is denied (dev servers fail with `EPERM`), localhost servers are unreachable, and writes outside the allowlist are rejected. The user may not know the session is sandboxed.
29
+
30
+ **Recognize sandbox denials — do not retry or work around them.** When a command fails in a sandbox-shaped way (`EPERM` binding a port, a blocked network host, a denied write to an ordinary path), the sandbox blocked it. Do NOT retry variations, escalate through workarounds, or route the command through `!`-prefixed user commands — those run inside the same sandbox. One failure is enough evidence; stop and inform the user.
31
+
32
+ **Warn before attempting known-blocked operations.** Before starting a dev server, anything else that listens on a port, or an operation that needs writes or network access outside the allowlist, tell the user up front that it will not work while sandboxing is on and offer the options below instead of attempting it.
33
+
34
+ **What to tell the user.** Explain that Polygraph runs this session in a sandbox, then present both options. Each takes effect on the next agent launch, so the Polygraph session must be relaunched afterwards:
35
+
36
+ 1. **Keep the sandbox on and allow the specific operation** (preferred). The sandbox belongs to the agent harness, so exceptions live in harness settings committed to the repository; array settings merge with Polygraph's generated allowlist rather than replacing it. Add writable roots or network access to `.codex/config.toml`:
37
+
38
+ ```toml
39
+ [sandbox_workspace_write]
40
+ network_access = true
41
+ writable_roots = ["<path>"]
42
+ ```
43
+
44
+ The `.codex/` directory is read-only inside the sandbox, so give the user the exact snippet to commit — you cannot apply it yourself.
45
+
46
+ 2. **Turn sandboxing off.** The user quits the agent, runs `polygraph config`, toggles **Agent Options → Codex → sandbox** off (or per-repo under **Repo Options**), and relaunches the Polygraph session. Non-interactive alternative: set `agentOptions.codex.sandbox: false` (or `repoOptions."org/repo".sandbox: false`) in `~/.polygraph/config.json`. Warn that this removes filesystem isolation — the agent can then write anywhere the OS user can.
47
+
48
+ **Never blame the tooling.** A sandbox denial means the environment blocked the operation — not that the repo, tool, or framework is broken. Do not record conclusions like "X is unusable" in memory, session descriptions, or messages based on sandboxed failures.
49
+
26
50
  ## Available Tools
27
51
 
28
52
  Polygraph functionality is available via both MCP tools and CLI commands. Use whichever is available in your current environment.
@@ -63,10 +87,13 @@ Before using Polygraph tools, ensure the CLI is authenticated and an organizatio
63
87
 
64
88
  ### Check Authentication
65
89
 
66
- Use `polygraph whoami` (or the `whoami` MCP tool) to check if the user is currently logged in and which organization is active.
90
+ Use `polygraph whoami` (or the `whoami` MCP tool) before session work to check if the user is currently logged in and which organization is active.
67
91
 
68
92
  - If the user **is logged in** and an org is selected → proceed to the workflow.
69
- - If the user **is not logged in** → use `polygraph auth login` (or the `login` MCP tool) to authenticate. After login, an organization must be selected.
93
+ - If auth is **missing, expired, or no org is selected** → stop session work. Do not keep trying session creation, repository discovery, delegation, or CI checks.
94
+ - Facilitate user reauth through the browser-based login flow, such as `polygraph auth login` (or the `login` MCP tool). In interactive desktop clients, browser reauth is usually user-driven; surface the need clearly and wait for the user to complete it.
95
+ - After login, an organization must be selected. Use `polygraph account select` (or the MCP equivalent) when needed.
96
+ - Re-run `polygraph whoami` (or `whoami`) after reauth and org selection. Continue only after it confirms a valid login and selected organization.
70
97
 
71
98
  ### Select Organization
72
99
 
@@ -109,6 +136,8 @@ In case B, call `add_repo` yourself when exact repo refs were provided; otherwis
109
136
 
110
137
  - For a new session (case C), `start_session` auto-generates a unique session ID. You do NOT need to pass one.
111
138
  - For cases A and B, the session ID already exists; reuse it everywhere — never let `start_session` run in this conversation.
139
+ - The parent conversation is responsible for detecting an existing session ID from current context, the startup banner, or a user-provided session URL/ID, then passing it explicitly to `polygraph-init-subagent`. The init subagent cannot infer parent session context by itself.
140
+ - For a fresh Codex Desktop conversation started with `/polygraph:session-start`, no `sessionId` is expected; launch `polygraph-init-subagent` without `sessionId` so it creates a new session.
112
141
 
113
142
  **Launch `polygraph-init-subagent`** (cases B and C — skip in case A):
114
143
 
@@ -663,3 +692,6 @@ If the session has a description timeline, also display:
663
692
 
664
693
  1. **Use `stop_agent` to clean up** — Stop child agents that are stuck or no longer needed. The child's session is preserved (`sessionPreserved: true`) so the context can be restored later, but after resuming you must wait for explicit user instructions before making changes.
665
694
  1. **Only archive sessions when asked** — Only call `archive_session` when the user explicitly requests it. Archiving hides the session from active lists; it can still be resumed later.
695
+
696
+ 1. **Respect the sandbox** — When a command fails with a sandbox denial (`EPERM` binding a port, blocked host, denied write), stop instead of retrying and point the user to the options in "Sandboxing in Polygraph Sessions": commit harness sandbox settings to the repo, or toggle sandboxing via `polygraph config`.
697
+
package/skills/session-start/SKILL.md ADDED
@@ -0,0 +1,78 @@
1
+ ---
2
+ name: session-start
3
+ description: Start or reconnect a Polygraph session for shared, resumable agent context. Use when the user asks to start a Polygraph session, create session memory, share or resume work context, include related repositories, or inspect an existing session before continuing.
4
+
5
+ ---
6
+
7
+ # Start a Polygraph Session
8
+
9
+ Start or reconnect a Polygraph session so the current work has shared, resumable context: session URL, repository graph visibility, linked PR/CI state, and the option to expand across repository boundaries when needed.
10
+
11
+ ## Codex Routing Rule
12
+
13
+ Use Codex `spawn_agent` with `agent_type: "polygraph-init-subagent"` for session creation or repository discovery. Do NOT call the Polygraph MCP `list_repos` or `start_session` tools directly from the parent conversation. Direct `add_repo` is allowed only when the user gives exact repository refs for an existing session.
14
+
15
+ Do NOT pass `fork_context: true` to Codex `spawn_agent` when `agent_type` is a custom agent.
16
+
17
+ ## Check Authentication First
18
+
19
+ Before session work, the parent conversation must check Polygraph auth with `whoami` or `polygraph whoami`.
20
+
21
+ - If auth is valid and an organization is selected, continue.
22
+ - If auth is missing, expired, or no organization is selected, stop session work. Do not keep trying session creation or discovery.
23
+ - Facilitate user reauth through the browser-based flow, such as `polygraph auth login` or the MCP `login` equivalent. After login, make sure an organization is selected with `polygraph account select` or the MCP equivalent when needed.
24
+ - Re-run `whoami` after reauth. Continue only after it confirms a valid login and selected organization.
25
+
26
+ Do not breeze past auth failures. In Codex Desktop, auth recovery usually requires the user to complete the browser login flow; surface that clearly and wait for it before continuing.
27
+
28
+ ## Parent Session Detection
29
+
30
+ The parent conversation is responsible for detecting an existing Polygraph session ID from the current context, startup banner, or user-provided session URL/ID, then passing that `sessionId` explicitly to `polygraph-init-subagent` when launching it. The init subagent cannot infer the parent's current session context by itself.
31
+
32
+ For a fresh Codex Desktop conversation started with `/polygraph:session-start`, no `sessionId` is expected. Launch `polygraph-init-subagent` without `sessionId` so it creates a new session.
33
+
34
+ ## Decide the Session Path
35
+
36
+ Pick one path before using tools.
37
+
38
+ 1. **Existing session with repos** - If a Polygraph session ID is already in scope and the user did not ask to add repositories, call `show_session` to inspect it and print the session details. Do not create a new session.
39
+ 2. **Existing session, adding exact repository refs** - If a session ID is in scope and the user provided exact refs by ID, short name, full name, GitHub `owner/repo` slug, URL-like slug, or MCP resource syntax, call `add_repo(sessionId, repoIds: [...])` directly. Do not run discovery.
40
+ 3. **Existing session, discovery needed** - If a session ID is in scope but repos need to be discovered or selected, launch `polygraph-init-subagent` with the existing `sessionId` and `userContext`. The subagent must use `add_repo`, not `start_session`.
41
+ 4. **No session in scope** - Launch `polygraph-init-subagent` with `userContext` and no `sessionId`. The subagent will discover related repositories when needed and call `start_session`.
42
+
43
+ Exact refs are not limited to organization repos. Public open-source repos can be added by `owner/repo` slug or URL even if they do not appear in repository discovery.
44
+
45
+ ## Launch the Init Subagent
46
+
47
+ Use this shape when discovery or new-session creation is needed:
48
+
49
+ ```
50
+ spawn_agent(
51
+ agent_type: "polygraph-init-subagent",
52
+ message: """
53
+ Parameters:
54
+ - sessionId: "<existing-session-id-or-omit-for-new-session>"
55
+ - userContext: "<description of what the user wants to do>"
56
+
57
+ The parent conversation detected any existing sessionId from current context, startup banner, or user-provided session URL/ID and passed it explicitly here. The init subagent cannot infer parent session context by itself.
58
+
59
+ If sessionId is provided, reuse that session and use add_repo to attach repositories -- do NOT call start_session. If exact repo refs were provided, pass them directly to add_repo and do NOT call list_repos. If discovery is needed, discover candidates and select relevant repos. If sessionId is omitted, this is a fresh session-start flow; create a new session via start_session. Return a structured summary.
60
+ """
61
+ )
62
+ ```
63
+
64
+ Omit the `sessionId` line when creating a new session. Include it when attaching discovered repos to an existing session. Collect the result with `wait_agent` when the main flow needs the session before proceeding.
65
+
66
+ ## Print the Result
67
+
68
+ When a brand-new session is created, render the session welcome card. Prefer the `session_intro` MCP tool when available; otherwise run `polygraph session intro -s <sessionId>` and print the returned markdown verbatim.
69
+
70
+ For an existing or reconnected session, print:
71
+
72
+ **Session:** POLYGRAPH_SESSION_URL
73
+
74
+ **Repositories in this session:**
75
+
76
+ - REPO_FULL_NAME
77
+
78
+ Use `polygraphSessionUrl` from the session response for `POLYGRAPH_SESSION_URL`, and use repository entries from the session response for `REPO_FULL_NAME`.