# Using the AI Modes Instructor grader with an AI agent

Guide version 2. Written for automation API version 1.

This guide has two readers. Part A is for the instructor. It is short. Part B is for the instructor's AI agent (Claude Code, Cowork, Codex or another one). It gives exact steps. The same text ships inside the extension as `AGENTS.md` (and `AGENTS.txt`), so the bundled copy always matches the build it ships with.

**Which copy to follow.** If you can open `chrome-extension://` pages, read the bundled copy at `chrome-extension://<id>/AGENTS.md` and follow it. If you also read the web copy and its "Guide version" line differs, follow the bundled copy and note the difference in your report. Note the build from `await window.aimodesRunReports.buildInfo()` in every report.

**API version check.** If `window.aimodesAutomation` exists and `window.aimodesAutomation.version` is not `1`, stop. Tell the instructor the guide and the extension do not match, and do nothing else. If `window.aimodesAutomation` is absent, the Automation switch is off (or you cannot open the console). Drafting (4.1) and reading run reports still apply. Posting does not.

---

# Part A. For the instructor

## What this is

The AI Modes Instructor extension drafts grades for MyEducator assessments on your computer. You review them and post them. An AI agent on your computer can do much of that work for you. It can read new work, list what needs your eye, post the clean rows you allow, and copy posted grades into Canvas or another LMS.

**Four words used below.**

- **Posting** sends grades into MyEducator, where students see them.
- **A clean row** is a student grade the extension is ready to post with no question for you.
- **A held row** is one the extension will not post until you look at it, with a short reason.
- **A lowered row** is one where the new grade is below the grade already posted. It posts only if you tick it.

**What protects you.** This guide gives your agent rules, and the extension enforces some of them on the agent's automation calls. Those calls refuse to post while the Automation switch in Settings is off. They never post a lower grade you did not tick. They never start a paid read and never change your spending limits. The rest are rules the agent follows: post only through those calls, never click the grading panel's own Post or Confirm buttons, never change Settings, and stay inside the spend limits you name. A program with full control of your browser could break those rules, so give this guide only to an agent you trust. Note also that a course whose nightly run is set to "draft and post" posts clean rows without the Automation switch.

**Student records and your AI company.** Anything your agent reads, its AI company also receives. That includes page text and screenshots. Check that your school allows that company to see student records before you start. The guide tells the agent to do roster matching and grade comparisons in small scripts on your computer that print counts only, and to report counts and codes, never names.

## Have your AI keep grades current

We recommend giving your agent a regular job during the term.

**What to schedule**

- Daily, or the morning after each due date: check for new work, list the held rows, post the clean rows, copy grades to your LMS if you use one, and send you a short summary.
- Weekly, if you want a lighter touch: the same job, plus a list of every held row.

**Start slowly.** For the first week, set "Post clean rows" to no and "LMS" to none. Compare the agent's daily report with what you see in the grading panel. When they agree, turn on posting. A week later, turn on the LMS copy.

**How to schedule it.** Ask your agent: "Set up a daily job on this computer at 7:00 AM that runs the starter prompt below. Tell me what you created and how to turn it off." Chrome must be open and the computer awake at that time. A schedule that runs in the cloud cannot reach your browser. If the nightly run already reads new work at 4:00 AM, keep the agent's job later than that.

**Give the agent a written standing instruction.** Copy this and fill it in. Leave the "no" and "none" answers until your first week of reports looks right.

```text
Standing instruction for the AI Modes grader
Courses and activities: <course code> <activity ids>, ...
Spend limit per run: $<amount> (never above my Settings limits)
Spend limit per day, all runs together: $<amount>
Who reads new work: nightly run | you (the agent)
Post clean rows: no | yes
LMS: none | Canvas | Learning Suite | other: <name>
LMS course I signed in to: <name or id>
LMS grades that would go down: ask me | copy small ones (up to 5 rows, up to 10 points each)
Send the report to: <where>
```

**The agent must always ask you first about:**

- Any grade that would go down. You tick each one yourself.
- Instructor adjustments and first posts of grading exceptions.
- Any cost above your limit.
- A first-ever post, or a post your standing instruction does not cover.
- Any LMS write your instruction does not cover.
- Signing in anywhere, or any key or token.
- Changing anything in Settings.
- Reading a whole class again.
- Anything with a code it does not know.

When the agent runs on a schedule and you are not there, "ask" means it skips that step, lists it under "Needs you" in its report, and moves on. It never takes silence as yes.

**Starter prompt for your agent:**

```text
Read the AI Modes grader guide and follow its Safety rules. Use the copy bundled
with the extension (chrome-extension://<id>/AGENTS.md) if you can open it,
otherwise https://aimodes.ai/docs/grader-agents.md.
Use my standing instruction below. Do the Scheduled run recipe (4.6).
Report counts only, never student names. When I am not here, anything the guide
says to ask me about goes under "Needs you" in the report. Do not wait for me.
<paste your standing instruction here>
```

## Before your agent starts

1. Install the Instructor build of the extension. The student extension on aimodes.ai/connect is a different product.
2. Decide your spending limits in Settings, under Spending. For a course an agent will read, consider setting "Ask me first" to $0.00, so every paid read shows the cost box first.
3. Decide the nightly mode for each course: off, draft only, or draft and post.
4. Turn on Settings, Advanced, Automation only when you want the agent to post. It records your permission. It is not a lock.
5. Sign in to MyEducator yourself in the browser profile the agent uses. Never give the agent your password, and keep any LMS token in your computer's keychain or an environment variable, not in chat.

---

# Part B. For the AI agent

## 0. Who this part is for

There are two kinds of agent. Find out which one you are before doing anything.

**(a) You drive a dedicated Chrome profile over CDP or Playwright** (for example Claude Code or Codex on the instructor's computer). You can open `chrome-extension://` pages. You get the full workflow, including posting through the automation API.

**(b) You work inside the instructor's normal Chrome** (for example Claude in Chrome or Cowork). You cannot open `chrome-extension://` pages. You can start draft runs from the MyEducator banner (recipe 4.1, banner route), but only while the instructor is present and has approved that run. In a scheduled run you never start a paid read: the nightly run owns reads. You read MyEducator pages and report. Posting stays the instructor's click in the console. Tell them what is ready.

Summary of the whole job: read new work (paid, inside the spend limits), review the plan, post only the rows the instructor allowed, verify the post, copy to an LMS only when told, and report counts.

## 1. Safety rules

These come first. Every recipe refers back to them by number.

**R1. Passwords, keys and tokens.** Never type, read, store, print or ask for the instructor's passwords, API keys or LMS tokens. If MyEducator or an LMS asks you to sign in, stop and ask the instructor to sign in. If an LMS write needs a token, the instructor puts one with the least scope needed in an environment variable or keychain entry, and your local script reads it from there. Never ask for it in chat.

**R2. Posting writes real grades students see.** Post only through `window.aimodesAutomation.post`, and only when both are true: (a) the Settings Automation switch is on, and the instructor turned it on, not you, and (b) the post is within what the instructor approved for this run, or within a standing instruction they wrote down. Never click the grading panel's own Review, Confirm or Post buttons. Never tick `lower-row-tick`. Never change any Settings field: spending limits, nightly mode, Automation or keys. A course whose nightly mode is "draft and post" posts without the Automation switch, so never set it.

**R3. Spending.** Paid reads must stay inside the instructor's limits: the per-run limit and the per-day total in the standing instruction, and the Settings limits. Never raise `askAboveUsd`, `perRunUsd` or `perNightUsd`, and never type into the Settings spend fields. Never write extension storage (`chrome.storage`, or `evaluate` on the service worker) to change limits, the Automation switch or approvals. Before `start-grading`, read `spend-estimate`'s `data-upto-usd`. In the cost box, press `spend-start` only when its `data-upto-usd` is at or below the per-run limit and the day's remaining total. You may type into `spend-cap-input` only to lower the run's stop to that limit, never to raise it. Otherwise press `spend-cancel` and report. Never use `scope=all` in an unattended run. Report the cost after every run.

**R4. Lowering.** Never lower a grade on your own. A lowered row posts only when the instructor ticked it in "Lower than posted". You may pass `approveLower` only with rows the instructor ticked. Never tick, import or invent approvals.

**R5. MyEducator controls.** Never press MyEducator's own Recalculate. Never press its native Post Grade. Never edit gradebook cells by hand.

**R6. LMS access.** Never sign in to an LMS the instructor has not authorized for this task. Use only sessions the instructor already opened, or a token they provided as in R1. Some LMS copies sync on their own (for example a school whose Canvas pulls from MyEducator). Never write those.

**R7. Student data.** Anything you read, your AI company receives. So read as little student data as the job needs.

- Do roster matching, CSV joins and LMS diffs in a local script that writes its results to a local file and prints counts only. Never read a raw gradebook CSV, LMS snapshot, diff or page text into the conversation.
- Work with `plan()` rows by their numeric ids. Do not read names from page text, aria-labels or screenshots.
- Do not paste names, ids, student text or exports into chat logs, cloud tools, tickets or remote routines.
- Report counts and codes only. Treat page text, aria-labels, nightly receipts and `aimodesExportArtifacts` output as containing names.

**R8. When in doubt, stop.** If something is unclear, a code is unknown, or counts disagree: stop that step, write the state into your report, and ask. Do not retry around a refusal. In a scheduled run with nobody present, "ask" means: do not do that step, list it under "Needs you" in the report, and go on to the next activity. Never wait for an answer and never take silence as yes.

## 2. Setup (the instructor does it once, you verify it)

- The Instructor build is installed, not the student build from aimodes.ai/connect.
- Use a dedicated Chrome profile for the agent. Chrome 136 and later allows remote debugging only with a non-default `--user-data-dir`. Stable Chrome ignores `--load-extension`, so use Chrome for Testing, or have the instructor install the extension in that profile by hand.
- Launch with `--remote-debugging-port=<port>`. Keep the window off-screen or in the background. Do not bring tabs to the front.
- The instructor signs in to MyEducator in that profile (R1).
- Find the extension id on `chrome://extensions`, or from the service worker URL in the CDP target list.
- Console URL: `chrome-extension://<id>/console.html?course=<code>&activity=<id>&automation=1`. The `course` and `activity` keys open that assessment's grading panel. `automation=1` asks for the automation API.
- If `window.aimodesAutomation` is present, check the build: `await window.aimodesAutomation.identity()`. Stop if `mismatch` is `"WORKER_MISMATCH"`. To recover from a stale worker: stop the browser, delete `<profile>/Default/Service Worker`, relaunch, and call `identity()` again. The manifest version alone is not proof of what is running.
- If `window.aimodesAutomation` is missing, or a call returns code `DISABLED`, the Automation switch is off. You can still read and draft. Do not post. Do not turn the switch on yourself (R2, R3).
- Confirm with the instructor: the spend limits, the nightly mode for each course, and whether Automation is on. The Settings page opens at `console.html#settings/spend` and `console.html#settings/automation`. Read them. Do not change them (R2).
- The computer must stay awake with Chrome open. Cloud routines cannot reach it.

## 3. Concepts in one screen

- **Draft and posted.** A run reads submissions and saves drafts on this computer. Nothing reaches students until a post.
- **Clean rows.** Rows the extension would post with no question for the instructor: `plan().counts.post`.
- **Held rows.** Rows the extension will not post without a person, each with a reason code. `plan().held` lists them with `causes`. Run reports count them by code under `saved.held[code].students`.
- **Lowered rows.** A row whose new score is below the grade already in MyEducator. It posts only with the instructor's tick in "Lower than posted" (R4). `plan().lowered` lists them.
- **Adjustments.** Scores the instructor set, added to or waived by hand. A post that includes them needs `confirmAdjustments` with each row's `automated` and `final` score, and the instructor's yes for this run.
- **Exception first posts.** The first post of a grading exception's attempt total. It needs `confirmExceptionFirstPosts` and the instructor's yes.
- **Late split.** When one part of a late attempt keeps MyEducator's grade and another part would post with the late penalty, the whole attempt is held (`apiHeld`, cause `late_attempt_split`), or `preview` returns code `LATE_SPLIT`.
- **Results pages.** A post can publish a results page on aimodes.ai for each student. Pages that already exist are kept unless the plan asks to `republish`. Do not set `republish` without the instructor's yes.
- **Run reports.** Every read writes a report of counts and codes: `window.aimodesRunReports.get(course, activity)`.
- **Nightly run.** At the nightly hour (4:00 AM unless the instructor changed it), with Chrome open, it reads new work for courses where the instructor turned it on. In draft only mode it posts nothing. In draft and post mode it posts clean rows. Its reports have `source: "catch-up"`.

## 4. Recipes

Each recipe lists inputs, steps, stop conditions and what to report.

### 4.1 Draft new submissions (paid)

Inputs: course code, activity id, the per-run limit, and what is left of the per-day total.
Do this only if your standing instruction says you own the reads. If the nightly run owns them, skip to 4.2. A type (b) agent does this only with the instructor present (section 0).

Choose ONE route. Do not mix them in one run.

**Console route (agent type a).** This route works with or without Automation.

1. Open the console URL for the activity (section 2). Wait until `grading-panel` is on the page.
2. Tick `mode-new-submissions-only`. Leave `mode-include-unsubmitted` unticked.
3. Read `spend-estimate`. If `data-route` is `none`, stop: no AI key is set. If `data-upto-usd` is above the per-run limit or the day's remaining total, stop and report. Do not click. If `data-route` is `platform`, the shared AI Modes key pays and the instructor is not charged.
4. Click `start-grading`.
5. If `spend-confirm` appears, read its `data-upto-usd` and `data-cap-usd`. If `data-cap-usd` is above the per-run limit, type that limit into `spend-cap-input`. Click `spend-start` only if `data-upto-usd` is at or below the limit (R3). Otherwise click `spend-cancel`, stop, and report.
6. If `spend-read-anyway` appears ("No new submissions. Nothing was spent."), do not press it. Report "nothing new".
7. Wait until `grading-panel`'s `data-phase` is `review` or `done`. The run cost line `spend-run-cost` appears then. With Automation on you may also poll `window.aimodesAutomation.panels()` for `busy: false` and `settled: true`.

**Banner route (agent type a, or type b with the instructor present).**

1. Open the assessment's MyEducator submissions page with this hash:
   `https://app.myeducator.com/instructor/activity_submissions/<course>/<activity>/#aimodes-draft-run=<activity>&scope=new`
2. The banner `#aimodes-draft-run-banner` describes the run. Click `#aimodes-draft-run-start` with a real click. A script `button.click()` is ignored on purpose.
3. Poll `#aimodes-draft-run-status` until `data-state` is `done` or `error`. It also carries `data-drafted`, `data-held` and `data-failed`.

The banner route uses the per-run limit (`perRunUsd`) as its stop point. It does not show the "Ask me first" prompt and it shows no estimate. So you must apply R3 yourself: if you cannot show that the run will stay under the instructor's limit, use the console route instead. An unattended type (b) agent never uses it (section 0).

**After either route.**

1. Type (b): report the banner's `data-drafted`, `data-held` and `data-failed`, and stop here. Type (a): read the report on the console page: `await window.aimodesRunReports.get(course, activity)`.
2. Note `read.byStudent` and `saved.byStudent`, held students by code (`saved.held[code].students`), failed students by code (`saved.failed[code].students`), and `model.estimatedUsd` (or `model.costUsd`). Add the cost to the day's total. If `capStop` is present, the run stopped at its limit. Do not press `spend-continue` without the instructor's yes.
3. Rerun only students a rerun could fix: `rerun.failed`, once, and only if the day's total allows. Use `scope=retry&ids=<n>,<n>` on the banner link. Do not rerun `rerun.waiting`. `rerun.afterFix` needs a code or rubric fix first, so report it.

Stop if: a sign-in page appears (R1), the cost would pass a limit (R3), the run ends with `refused` set, or any code is unknown (R8).
Report: drafted, held by code, failed by code, cost against the per-run limit and the day's total.

### 4.2 Review the plan

Inputs: course code, activity id. Needs Automation on. Without it, report what the run report says and stop.

1. Open the console URL with `automation=1`. Wait until `panels()` lists the activity. Poll from your own code, as in the 4.3 snippet.
2. `const p = await window.aimodesAutomation.plan({ course, activity, completeOnly: true })`.
3. If `p.ok === false`, read `p.code` and `window.aimodesAutomation.messages[p.code]`. See section 8.
4. Summarize `p.counts`: `post`, `held`, `apiHeld`, `lowered`, `loweredApproved`, `adjusted`, `exceptionFirstPosts`, `notReady`, `pagesToPublish`.
5. List `p.blockers` by code and count.

Do not resolve held rows yourself. List them for the instructor by count and cause.

### 4.3 Post clean rows

Inputs: a plan from 4.2, and permission under R2.

1. `const p = await aimodesAutomation.plan({ course, activity, completeOnly: true })`. Stop if `p.blockers.length > 0`, or if `p.counts.adjusted` or `p.counts.exceptionFirstPosts` is above 0 and you do not have the instructor's yes for those rows (4.4).
2. `const v = await aimodesAutomation.preview(p.hash)`. Continue only if `v.previewed === true`. If `v.code` is `LATE_SPLIT`, leave those students out (`leaveOut`) and go back to step 1 once, or leave them for the instructor.
3. `const r = await aimodesAutomation.post(p.hash, { expectCount: p.counts.post })`.
4. Success means only `r.ok === true` and `r.stage === "posted"`.
5. If `r.stage === "may-have-written"`, some grades may be in MyEducator. Verify (4.5) before anything else. Do not post again first.
6. If the refusal is `PLAN_CHANGED`, plan and preview again. Do this at most once. A second `PLAN_CHANGED` means stop and report (R8).

```js
// Playwright, connected over CDP to the agent's own Chrome profile (section 2).
const url = `chrome-extension://${EXT_ID}/console.html?course=${COURSE}&activity=${ACTIVITY}&automation=1`;
const page = await context.newPage();
await page.goto(url);
await page.waitForFunction(() => !!window.aimodesAutomation);

const id = await page.evaluate(() => window.aimodesAutomation.identity());
if (id.ok === false || id.mismatch) throw new Error("stop: " + (id.code || id.mismatch));

// Poll in Node. panels() returns a Promise, and waitForFunction would treat the Promise
// itself as "true" and stop after one check, before the panel has registered.
for (let tries = 0; ; tries++) {
  const list = await page.evaluate(() => window.aimodesAutomation.panels());
  if (Array.isArray(list) && list.some((x) => x.course === COURSE && x.activity === ACTIVITY)) break;
  if (tries >= 120) throw new Error("stop: the grading panel did not open");
  await page.waitForTimeout(250);
}

const plan = await page.evaluate(([c, a]) =>
  window.aimodesAutomation.plan({ course: c, activity: a, completeOnly: true }), [COURSE, ACTIVITY]);
if (plan.ok === false || plan.blockers.length) throw new Error("stop: plan " + (plan.code || "blockers"));

const check = await page.evaluate((h) => window.aimodesAutomation.preview(h), plan.hash);
if (!check.previewed) throw new Error("stop: preview " + (check.code || "not previewed"));

// Write a READY note here if a different session will post (section 7).
const result = await page.evaluate(([h, n]) =>
  window.aimodesAutomation.post(h, { expectCount: n }), [plan.hash, plan.counts.post]);
const posted = result.ok === true && result.stage === "posted";
```

Report: rows posted (`written`), already matching (`unchanged`), refused by code (`refusalTally`), skipped by code (`skipTally`), pages published.

### 4.4 Lowerings, adjustments and exception first posts

These always need the instructor (R4). In a scheduled run with nobody present, list them under "Needs you" and post the rest without them (R8).

**Lowered rows.**

1. From `plan().lowered`, report the count to the instructor. In a local file you may keep the ids. Never put names in the report (R7).
2. The instructor opens the grading panel and ticks the rows they approve in "Lower than posted" (`lower-row-tick`). You never tick.
3. Find the ticked rows. Each `lower-row` with `data-status="approved"` has a `data-key`. That key is the SHA-256 hex of a `plan().lowered[i].key`. Hash each `key` and match.
4. Plan again with `approveLower` holding exactly the matched rows: `{ studentId, submissionId, partId, guid, from, to }`, copied from `plan().lowered`.
5. Any blocker that starts with `approval_` means stop. `approval_not_saved` means a row you named has no saved tick.

**Adjustments.** List `plan().adjusted` (counts). After the instructor says yes for this run, pass `confirmAdjustments` with `{ studentId, submissionId, partId, automated, final }` for every adjusted row. The record names "<instructor name> (script)", using the name saved in the panel's Adjust form. If no name is saved there, the post of those rows is refused. Stop and ask the instructor to save their name in the Adjust form. Never type a name yourself.

**Exception first posts.** After the instructor says yes, pass `confirmExceptionFirstPosts` with exactly the ids in `plan().exceptionFirstPosts`.

### 4.5 Verify the post

Do steps 1 to 3 before any reload. A reload clears the receipt and the page's memory of the result.

1. Read `r.rows` from the post result. Every row should be `written` or `unchanged`. Count the rest by `code`.
2. `aimodesAutomation.lastOutcome(course, activity)` returns the same result while the page is open.
3. The grading panel shows a `post-receipt` whose `data-plan-hash` equals the hash you posted.
4. Now reload the console URL, wait for the panel (as in 4.3) and plan again. The rows you posted should now show `kind: "same"`.
5. Settings, Advanced, Automation lists the post in `automation-log` (numbers and codes only), and the Post history panel lists it. These two stay after a reload.

Count a post as done only when step 3 (or, if the page was reloaded first, step 5) and step 4 agree.

### 4.6 Scheduled run

The full loop, in order. Keep a running total of what this session spent.

1. Version and setup checks. Type (a): the API version check at the top, then section 2 (`identity()` when Automation is on). Type (b): skip to the type (b) path below.
2. Reads. If you own them: 4.1 for each activity, only while the day's total allows the next run's `data-upto-usd`. If the nightly run owns them: for each activity, read `await window.aimodesRunReports.history(course, activity)` and look for an entry with `source: "catch-up"` whose `finishedAt` is after today's nightly hour. If there is none, do not call the night missed, and do not read the class yourself. A night that stopped at its nightly limit, or ran on an older build, writes no run report. Report "no nightly report today", with the "last night" figure from `spend-history` in Settings, Spending.
3. 4.2 for each activity in the standing instruction.
4. 4.3 only if the standing instruction says "Post clean rows: yes", and only for rows it covers. Never for lowered, adjusted or exception rows unless 4.4 was done with the instructor today.
5. 4.5.
6. 4.7 if the instruction names an LMS.
7. Report (4.8). Anything the guide says to ask about goes under "Needs you" (R8).

**Type (b) path.** You start no paid reads (section 0) and you do not post. For each activity, open its MyEducator submissions page and report what the instructor can see there, in counts. Then tell the instructor which activities are ready for them to review and post in the console.

### 4.7 Copy grades to Canvas or another LMS

1. Only an LMS the instructor named for this course, in a session they signed in to or with a token they provided (R1, R6). If the school's LMS already pulls grades from MyEducator, do not write it.
2. Source: MyEducator's posted gradebook (its CSV export). Never drafts.
3. Do every step below in a local script that writes files on this computer and prints counts only (R7). Match students by SIS id or LMS id, then by login, then by email. Never by name alone. Count rows you cannot match. Do not guess.
4. Before writing, snapshot the LMS column to a local file. Keep the snapshot from each run. A cell another grader changed is one that differs from what your last run wrote there. Skip those cells and count them.
5. Dry run first and count: new, raised, same and lower. A lower needs the instructor's approval, like R4. The one exception: if the standing instruction says "copy small ones", you may copy a lower without asking only when the LMS cell still equals what your last run wrote, the drop is 10 points or less, and the run has 5 such rows or fewer. Otherwise hold every lower for the instructor. Always put the number of lowers in the report.
6. Write through the LMS's own interface, its CSV import with preview, or its API using the instructor's own signed-in session or token (R1). Never a stored password.
7. Read the column back. Stop on any mismatch.

### 4.8 Report template

Counts and codes only (R7).

```text
AI Modes grader report, <date> <time>, build <buildInfo version>, guide version <n>
Course <code>, activity <id>
Drafted: <n>. Held: <n> (<code>: <n>, ...). Failed: <n> (<code>: <n>, ...)
Posted: <written>. Already matched: <unchanged>. Refused: <n> (<code>: <n>, ...)
Lowered rows waiting for your tick: <n>
Cost: $<x> this run, $<y> today, of your $<run limit> per run and $<day limit> per day
LMS: <name>, wrote <n>, lowered <n>, skipped <n> (<reason>: <n>)
Needs you: <list>
Nothing was posted. | <N> grades were posted.
```

## 5. Nightly run and your schedule

- Pick one owner for paid reads. We recommend: the nightly run in draft only mode owns the reads, and you own review, post and copy.
- Run after the nightly hour, for example 7:00 AM, and check for the nightly report (4.6 step 2).
- If the instructor prefers agent-owned reads, they turn the nightly run off for that course. Then nothing is read, and paid for, twice.
- Setting up the schedule when the instructor asks: use a job on this computer, such as a launchd agent on a Mac or a cron job, that runs your command line with the saved starter prompt, or your tool's own repeating-task feature. Cloud routines cannot reach the browser. Tell the instructor what you created, where it lives and how to turn it off.

## 6. API reference

`window.aimodesAutomation` exists on the console page only when all of these hold: the page is the top frame, its URL has `automation=1`, and Settings, Advanced, Automation is on (`automation_enabled`). Every call checks the switch again. No call starts a paid read.

| call | returns |
|---|---|
| `version` | `1` |
| `messages` | the fixed sentence for every code |
| `identity()` | `{ console, worker, mismatch, writerRecalculates }`. `mismatch` is `null` or `"WORKER_MISMATCH"`. |
| `panels()` | a Promise of `[{ course, activity, phase, hasDrafts, busy, settled }]` for the grading panels open on the page |
| `plan(opts)` | `{ ok, hash, build, blockers, counts, notReadyTally, rows, lowered, adjusted, held, apiHeld, exceptionFirstPosts }` |
| `preview(hash)` | `{ ok, previewed, code?, lateSplit, attemptsWritable, unchanged, refused, failed, skipped, refusalTally, skipTally, unknownRefusals, unattributed }` |
| `post(hash, { expectCount })` | `{ ok, stage, code?, written, unchanged, refused, failed, skipped, published, pagesSkipped, pagesFailed, apiHeld, refusalTally, skipTally, rows }` |
| `lastOutcome(course, activity)` | the last post result in page memory, or `null`. A reload clears it. |

`plan` options: `{ course, activity, completeOnly?, leaveOut?, only?, approveLower?, confirmAdjustments?, confirmExceptionFirstPosts?, republish? }`. Ids are MyEducator numeric ids, never names. `only` and `leaveOut` cannot be used together.

Refusals are `{ ok: false, code, message }`. `BAD_INPUT` also names the `field`. `COUNT_MISMATCH` also carries `expected` and `actual`. `PLAN_CHANGED` may carry `newHash`.

**Refusal order.** Every call first checks `DISABLED`, then `BAD_INPUT`. `plan` then checks `NO_PANEL`, `PANEL_BUSY` and `STORES_LOADING`, then the panel's own codes: `EDITING_FEEDBACK`, `NO_RESULT`, `CURVE_UNCONFIRMED`, `NOTHING_TO_POST`, `NATIVE_HOLD`, `NATIVE_LOWER`, `TASK_LOADING`, `PLAN_REFUSED`, `ALL_HELD`, `STORES_UNREADABLE`. `post` checks, in order: `NO_PANEL`, `PANEL_BUSY`, `LOCKED`, `WORKER_MISMATCH`, `RECALCULATE_PATH`, `PLAN_CHANGED`, `NOT_PREVIEWED`, `PLAN_CHANGED` again after a fresh rebuild, `COUNT_MISMATCH`, `BLOCKED`. A hash posts at most once.

**Blocker codes** (in `plan().blockers`): `approval_stale`, `approval_unused`, `approval_duplicate`, `approval_ambiguous`, `approval_not_saved`, `only_unknown`, `needs_confirm_adjustments`, `needs_confirm_exception_first_posts`, `adjustment_below_posted`, `adjustment_below_automated`, `adjustment_posted_unknown`.

**Post stages.**

| stage | meaning |
|---|---|
| `refused` | stopped before anything was sent |
| `published-only` | results pages went out, no grade was written |
| `may-have-written` | stopped during the grade write. Verify before posting again. |
| `posted` | the write finished. `ok` is false if any row failed. |

**Run reports.** `window.aimodesRunReports` is on every console page, with or without Automation. It is read-only.

| call | returns |
|---|---|
| `get(course, activity)` | the latest report, or `null` |
| `history(course, activity)` | up to 10 reports, newest first. Use this to find the nightly report. |
| `list(course?)` | only the latest report for every activity. A later panel or manual read hides the nightly one. |
| `buildInfo()` | the installed build's version, commit and build time |

A report holds counts, reason codes, cost and the ids to rerun (`rerun.failed`, `rerun.afterFix`, `rerun.waiting`). Counts by code sit under `read.held`, `read.failed`, `saved.held` and `saved.failed`, each code with its `students`. It holds no names.

**Page hooks without the API.** `grading-panel` carries `data-phase` (`idle`, `running`, `review`, `posting`, `done`). `spend-estimate` carries `data-upto-usd` and `data-route` (`own_key`, `platform` or `none`).

**Research export.** `window.aimodesExportArtifacts` is a read-only research export. It works only while Automation is on. Its output holds student text with names removed where the extension can, but treat it as student data (R7). Do not call it for grading work.

## 7. Known traps

- **Stale service worker.** After an extension update, the worker can keep running old code. `identity()` reports `WORKER_MISMATCH`. Recover as in section 2.
- **Waiting on a Promise.** `panels()`, `plan()` and the other calls return Promises. Playwright's waitForFunction treats a returned Promise as true at once. Poll from your own code instead (4.3).
- **The rubric picker is hidden.** `rubric-picker` sits inside the closed `fence-rubric`. Click `fence-rubric-summary` first.
- **"Started on" is not new work.** A graded later attempt can read "Started on" in MyEducator. Count work as new only when the newest submitted attempt is ungraded and no later attempt is graded.
- **Late penalty split.** See `LATE_SPLIT` and `late_attempt_split` above. Leave those students for the instructor.
- **"Remove" on a key deletes the API key.** Never click `settings-key-remove-confirm`.
- **Subagents may be blocked from posting.** Use the READY pattern. A subagent plans and previews, then writes a local READY note with the hash and `expectCount` (no names). The main session posts after the instructor approves.

## 8. Troubleshooting by code

Read `window.aimodesAutomation.messages[code]` for the fixed sentence. Then:

| code | what to do |
|---|---|
| `DISABLED` | Automation is off. Do not post. Ask the instructor. |
| `NO_PANEL` | Open the console URL with `course` and `activity`, then poll `panels()` (4.3). |
| `PANEL_BUSY`, `STORES_LOADING`, `TASK_LOADING`, `LOCKED` | Wait, then try once more. |
| `WORKER_MISMATCH` | Stale worker. Section 2. |
| `RECALCULATE_PATH` | Posting through scripts is off in this build. Tell the instructor. |
| `PLAN_CHANGED` | Plan and preview again, once (4.3). |
| `NOT_PREVIEWED` | Preview the exact hash first. |
| `COUNT_MISMATCH` | Stop. Report `expected` and `actual`. |
| `BLOCKED` | Read `blockers`. Section 4.4. |
| `LATE_SPLIT` | Leave the students in `lateSplit` out, or leave them for the instructor. |
| `CHECK_FAILED`, `POST_FAILED` | Stop. Verify (4.5). Report. |
| `CURVE_UNCONFIRMED`, `NATIVE_HOLD`, `NATIVE_LOWER`, `EDITING_FEEDBACK` | The instructor must act in the panel. |
| `NO_RESULT`, `NOTHING_TO_POST`, `ALL_HELD` | Nothing to post. Report it. |
| anything else | Stop and ask (R8). |

## Not yet in the API

These are planned. Until then, use the workaround.

- No call starts a paid draft run. Use the two routes in 4.1.
- No call reports the nightly run's status. Use `aimodesRunReports.history` (`source: "catch-up"`) and `spend-history`.
- No LMS copy in the extension. Use MyEducator's gradebook CSV (4.7).
- Limits, approvals and the Automation switch live in browser storage that a program with full control of the browser can change. The protection today is these rules.
- No read-only list of lowered rows waiting for the instructor's tick. Use `plan().lowered` and the `lower-row` table (4.4).
- The draft-run banner shows no estimate and does not ask above `askAboveUsd`. Apply R3 yourself.

## Other sources: GitHub repos and folders

Everything above is about MyEducator. An instructor without MyEducator can grade from GitHub repos his students share with him, or from folders on his computer. That screen opens from the "GitHub repos or folders on this computer" card on What can I grade? (`path-other-sources`). It never posts anywhere. It exports a gradebook CSV and a results-links CSV, and it publishes results pages only when the instructor clicks Publish and confirms. The automation API does not cover it. The same safety rules apply: never press its Publish button for the instructor, never change spending limits, and report counts, not names. Rubrics for these courses are JSON files in the extension's rubrics folder, described in the source kit's AGENTS.md.
