eve-hub 0.16.39 → 0.16.41

package/github-connector.mjs

@@ -1,3 +1,9 @@
 // The Vercel Connect connector that holds the workspace human's GitHub token (the eve-hub-github
-// App). The bots' `git__gh` (prepare.mjs) asks it for the human's token, so they act as the human.
+// App). The bots' `git__gh` (prepare.mjs) and main's tracker-prs schedule (schedules/tracker-prs-run.mjs)
+// ask it for the same subject, so both act as the human. Its own module so a schedule can import it
+// without prepare.mjs's build-time imports.
 export const GITHUB_CONNECTOR = "github/eve-hub-github";
+
+// The subject eve's connections resolve for a hub turn (channels/eve-roster-user.ts: principal
+// `roster:<human>`, authenticator `roster`, no issuer of its own, so eve uses the authenticator).
+export const rosterSubject = (human) => ({ type: "user", id: `roster:${human}`, issuer: "roster" });

package/kit-modules.json

@@ -10,6 +10,7 @@
   "memory/team",
   "memory/workspace",
   "schedules/prune",
+  "schedules/tracker-prs",
   "schedules/wake",
   "skills/deep-dive",
   "skills/fanout",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-hub",
-  "version": "0.16.39",
+  "version": "0.16.41",
   "license": "Apache-2.0",
   "description": "Bot-side code shared by every hub agent: registry tools, the roster hook, the eve channel, the host sandbox and browser, and model helpers.",
   "type": "module",

package/schedules/tracker-prs-run.mjs

@@ -0,0 +1,98 @@
+// One tick of main's tracker-prs schedule (schedules/tracker-prs.ts): tracker rows linked to a GitHub PR or issue move to
+// Done when it merged (or an issue closed as completed) and to Dropped when it closed otherwise. The hub lists the refs on
+// rows still open (GET /api/tracker/prs, which reads only the summaries that carry rows) and settles what GitHub said
+// (POST /api/tracker/prs). GitHub is asked in one GraphQL query per 50 refs, as the workspace human: a hosted hub's
+// function asks Vercel Connect for the token the bots' `git__gh` gets; a local hub asks `gh auth token`.
+//
+// Plain JS on purpose: the schedule (TypeScript, bundled by eve) and the tests (plain node) import the same module.
+import { execFile } from "node:child_process";
+import { getToken } from "@vercel/connect";
+import { GITHUB_CONNECTOR, rosterSubject } from "../github-connector.mjs";
+import { registryFetch } from "../registry-fetch.mjs";
+
+export const GITHUB_GRAPHQL_URL = "https://api.github.com/graphql";
+export const REFS_PER_QUERY = 50;
+// The hub gives a schedule 60 s: the token, the queries and the two hub calls fit.
+export const GH_TIMEOUT_MS = 20_000;
+export const TOKEN_TIMEOUT_MS = 5_000;
+
+const REF = /^([A-Za-z0-9][\w.-]*)\/([\w.-]+)#(\d+)$/;
+
+/** The workspace human's GitHub user token. */
+export function githubToken(human, { hosted = Boolean(process.env.VERCEL), connect = getToken, timeoutMs = TOKEN_TIMEOUT_MS } = {}) {
+  if (hosted) {
+    if (!human) return Promise.reject(new Error("the hub names no human to ask GitHub as"));
+    let timer;
+    const deadline = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("Vercel Connect timed out")), timeoutMs); });
+    return Promise.race([connect(GITHUB_CONNECTOR, { subject: rosterSubject(human) }), deadline]).finally(() => clearTimeout(timer));
+  }
+  return new Promise((resolve, reject) => {
+    execFile("gh", ["auth", "token"], { timeout: timeoutMs }, (error, stdout, stderr) => {
+      const token = String(stdout ?? "").trim();
+      if (!error && token) resolve(token);
+      else reject(new Error(`gh auth token: ${String(stderr || error?.message || "no token").trim().slice(0, 300)}`));
+    });
+  });
+}
+
+/** One query naming each ref by alias (`r0`, `r1`, …); refs that aren't `owner/repo#N` are left out. */
+export function stateQuery(refs) {
+  const parts = refs.map((ref, i) => {
+    const [, owner, name, number] = ref.match(REF);
+    return `r${i}: repository(owner: ${JSON.stringify(owner)}, name: ${JSON.stringify(name)}) { issueOrPullRequest(number: ${number}) { __typename ... on PullRequest { state } ... on Issue { state stateReason } } }`;
+  });
+  return `query { ${parts.join(" ")} }`;
+}
+
+/** What a row becomes from GitHub's answer for its ref: "completed", "canceled", or undefined while it is open or unknown. */
+export function settledState(node) {
+  if (!node) return undefined;
+  if (node.__typename === "PullRequest") return node.state === "MERGED" ? "completed" : node.state === "CLOSED" ? "canceled" : undefined;
+  if (node.state !== "CLOSED") return undefined;
+  return node.stateReason === "NOT_PLANNED" || node.stateReason === "DUPLICATE" ? "canceled" : "completed";
+}
+
+/** POST one GraphQL query; a ref GitHub can't answer (gone, no access) comes back null in `data` and is skipped. */
+export async function ghGraphql(query, { token, fetchImpl = fetch, timeoutMs = GH_TIMEOUT_MS }) {
+  const res = await fetchImpl(GITHUB_GRAPHQL_URL, {
+    method: "POST",
+    headers: { authorization: `bearer ${token}`, "content-type": "application/json", "user-agent": "eve-hub-tracker" },
+    body: JSON.stringify({ query }),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const text = await res.text();
+  let body = null;
+  try { body = JSON.parse(text); } catch {}
+  if (res.ok && body?.data) return body.data;
+  throw new Error(`GitHub ${res.status}: ${String(body?.errors?.[0]?.message ?? body?.message ?? text).slice(0, 300)}`);
+}
+
+/** One tick. Returns { asked, moved }. A failed GitHub call throws, so the hub's run history shows it, and nothing is settled. */
+export async function runTrackerPrs({ hub = hubCalls(), token = githubToken, fetchImpl = fetch } = {}) {
+  const { refs, human } = await hub.open();
+  const asked = refs.filter((r) => REF.test(r));
+  if (!asked.length) return { asked: 0, moved: 0 };
+  const key = await token(human);
+  const states = {};
+  for (let i = 0; i < asked.length; i += REFS_PER_QUERY) {
+    const chunk = asked.slice(i, i + REFS_PER_QUERY);
+    const data = await ghGraphql(stateQuery(chunk), { token: key, fetchImpl });
+    chunk.forEach((ref, j) => {
+      const state = settledState(data[`r${j}`]?.issueOrPullRequest);
+      if (state) states[ref] = state;
+    });
+  }
+  if (!Object.keys(states).length) return { asked: asked.length, moved: 0 };
+  const { moved } = await hub.settle(states);
+  return { asked: asked.length, moved };
+}
+
+/** The two hub calls, over the registry's HTTP API as the deployment. */
+export function hubCalls({ fetchImpl } = {}) {
+  const call = async (init) => {
+    const res = await registryFetch("/api/tracker/prs", { ...init, headers: { "content-type": "application/json" } }, { deadlineMs: 10_000, ...(fetchImpl ? { fetchImpl } : {}) });
+    if (!res.ok) throw new Error(`${init.method} /api/tracker/prs: ${res.status} ${(await res.text()).slice(0, 300)}`);
+    return res.json();
+  };
+  return { open: () => call({ method: "GET" }), settle: (states) => call({ method: "POST", body: JSON.stringify({ states }) }) };
+}

package/schedules/tracker-prs.d.ts

@@ -0,0 +1,5 @@
+declare const _default: {
+    cron: string;
+    run(): Promise<void>;
+};
+export default _default;

package/schedules/tracker-prs.js

@@ -0,0 +1,12 @@
+// main's tracker-prs schedule: every 10 minutes, tracker rows linked to a GitHub PR or issue move to Done when it merged
+// and to Dropped when it closed (schedules/tracker-prs-run.mjs).
+import { defineSchedule } from "eve/schedules";
+import { runTrackerPrs } from "./tracker-prs-run.mjs";
+export default defineSchedule({
+    cron: "*/10 * * * *",
+    async run() {
+        const { asked, moved } = await runTrackerPrs();
+        if (moved)
+            console.log(`[hub:tracker-prs] ${moved} of ${asked} rows moved`);
+    },
+});

package/stubs.mjs

@@ -41,6 +41,7 @@ export const MAIN_KIT_FILES = {
   "tools/dash_update.ts": ["Set Dash entries: importance, lane, reason and deferred per thread."],
   "tools/apply_tags.ts": ["Retag threads, merge or rename tags: applies a staged proposal or a new batch directly."],
   // Handler schedules: the hub fires them from its minute clock (registry/schedules.mjs).
+  "schedules/tracker-prs.ts": ["Every 10 minutes: tracker rows linked to a GitHub PR or issue move to Done when it merged and to Dropped when it closed."],
   "schedules/prune.ts": ["Every 10 minutes: one prune pass over what archived or deleted threads leave on disk: worktrees, scratch, their-only uploads, idle bots' traces and workflow runs; unsaved work kept as refs/bundles."],
 };
 
@@ -54,6 +55,7 @@ export const MAIN_KIT_FILES = {
 // restart_hub (the hub's own code), memory (the workspace's files), and main's prune schedule (it cleans the hub machine's disk).
 export const DEPLOYED_KIT_FILES = new Set([
   "channels/eve.ts",
+  "schedules/tracker-prs.ts",
   "skills/onboarding-profile.ts",
   "tools/onboarding_scripts.ts",
   ...["react", "show", "fetch_upload", "update_thread", "list_threads", "read_thread", "post_message"].map((t) => `tools/${t}.ts`),

package/subagent-tiers.mjs

@@ -10,8 +10,8 @@
 // workspace's lead and workers read. The lead chooses a tier from its tool description alone
 // (tierDescription); the fanout skill's report table is generated from `report`. The folder's
 // files themselves are stubs.mjs tierFiles: this module holds only text, so a deployed bot imports nothing else.
-// When the lead hands work to tiers: to run its pieces at once, never to offload one task. The execution template says the same sentence (test/fanout-skill.test.mjs).
-export const ROUTING_RULE = "Fan out work that splits into independent pieces: one tier call per piece, all in one step. A single task stays with you, however long. Judgment always stays with you.";
+// When the lead hands work to tiers: every read, check and specified edit, a single task too, except one or two short tool calls it keeps; independent pieces go out at once. The execution template says the same sentence (test/fanout-skill.test.mjs).
+export const ROUTING_RULE = "Hand every read, check and specified edit to its tier, even one on its own: a test run, a CI log, a read across files, a repo search. Keep a task only when it is one or two tool calls with short output. Fan out work that splits into independent pieces: one tier call per piece, all in one step. Judgment always stays with you.";
 
 // Null prototype: a lookup by a roster name sees only the tiers, never `constructor` or `__proto__`.
 export const SUBAGENT_TIERS = Object.freeze(Object.assign(Object.create(null), {

package/templates/execution.md

@@ -15,7 +15,7 @@
   - Why: every question costs the human a context switch, and most answers are in the code or the history.
 - **Split the work**
   - Do the part your role owns; hand the rest to the role that owns it, because skipping a role skips its check.
-  - Your reader, editor and verifier run on models far cheaper than yours: reading goes to reader, specified edits to editor, pass/fail checks (running tests included) to verifier. When work splits, count the pieces before you route: three files to trace is three readers, two test runs to check is two verifiers. Never merge pieces, and never keep one of them yourself. One question, one edit or one test run, with nothing beside it, is a single task, not a piece. Fan out work that splits into independent pieces: one tier call per piece, all in one step. A single task stays with you, however long. Judgment always stays with you.
+  - Your reader, editor and verifier run on models far cheaper than yours: reading goes to reader, specified edits to editor, pass/fail checks (running tests included) to verifier. When work splits, count the pieces before you route: three files to trace is three readers, two test runs to check is two verifiers. Never merge pieces, and never keep one of them yourself. Hand every read, check and specified edit to its tier, even one on its own: a test run, a CI log, a read across files, a repo search. Keep a task only when it is one or two tool calls with short output. Fan out work that splits into independent pieces: one tier call per piece, all in one step. Judgment always stays with you.
   - Before you hand work to a reader, editor, verifier or `agent` copy, load the `fanout` skill and follow it: the receiver starts with none of your context.
   - A subagent with no commit, push, report or verdict in 30 minutes is stuck: cancel it and finish the work yourself.
 - **Waiting**

package/tools/update_thread.d.ts

@@ -3,6 +3,15 @@ declare const _default: import("eve/tools").ToolDefinition<{
     title?: string | undefined;
     path?: string | null | undefined;
     issueType?: string | undefined;
+    tracker?: {
+        id: string;
+        title: string;
+        state: "backlog" | "canceled" | "completed" | "started" | "unstarted";
+        owner: string;
+        waitsOn?: string | undefined;
+        since?: string | undefined;
+        ref: string;
+    }[] | undefined;
     pathLabel?: string | undefined;
     projectLabel?: string | undefined;
     issueTypeLabel?: string | undefined;
@@ -17,6 +26,15 @@ declare const _default: import("eve/tools").ToolDefinition<{
         title?: string | undefined;
         path?: string | null | undefined;
         issueType?: string | undefined;
+        tracker?: {
+            id: string;
+            title: string;
+            state: "backlog" | "canceled" | "completed" | "started" | "unstarted";
+            owner: string;
+            waitsOn?: string | undefined;
+            since?: string | undefined;
+            ref: string;
+        }[] | undefined;
         pathLabel?: string | undefined;
         projectLabel?: string | undefined;
         issueTypeLabel?: string | undefined;

package/tools/update_thread.js

@@ -10,13 +10,28 @@ import { z } from "zod";
 import { registryFetch } from "../registry-fetch.mjs";
 import { documentUrl } from "../hub-upload.js";
 import { artifactInput, artifactUrl } from "./post_message.js";
+// The hub checks each row again (packages/wire/src/state.ts TrackerRow); this is what the model reads.
+const trackerRow = z.object({
+    id: z.string().describe("Your stable id for the row, unique in the list, e.g. 'server-step-12'. Keep it across rewrites."),
+    title: z.string().describe("What the work is, in a few words, e.g. 'Build server step 12'."),
+    state: z.enum(["backlog", "unstarted", "started", "completed", "canceled"]).describe("started: being worked on now; unstarted: next, ready to start; backlog: needed before the goal is done, not next; completed: done; canceled: dropped."),
+    owner: z.string().describe("Who acts on it: a bot name or the human's handle."),
+    waitsOn: z.string().optional().describe("Who or what it is blocked on, e.g. 'rconti' or 'an eve maintainer'."),
+    since: z.string().optional().describe("With waitsOn: the ISO date the wait began, e.g. '2026-11-03'."),
+    ref: z.string().describe("What the row opens; every row needs one: a post as thr_ID#msg_ID (a hash, never a slash), a PR or issue as owner/repo#N or its github.com URL, or an https URL."),
+});
 export default defineTool({
-    description: "Update a workspace thread you're in: its title, track and issue type, in one call. Retitle when the work's scope has changed and the old title no longer fits: everyone sees a short 'renamed this thread: old → new' line; the history is kept. Keep titles short (at most 80 characters). File it on a path (project/track, e.g. 'web/checkout': the first segment is the project, the second the track) and tag an issue type (the kind of work, e.g. 'feature', 'bugfix', 'infra'). Reuse a project, track and issue type in use whenever one fits. File under the project alone until at least 3 threads share a track. For a new tag, also give its display name (projectLabel, pathLabel or issueTypeLabel, e.g. 'Payments API'). The thread's summary isn't yours to write: the hub derives where it stands from its posts after each one. The reply's `inUse` lists the tags in use with their thread counts and flags a tag no other thread uses; when one in use fits better than yours, call update_thread again with it. Tags a human set by hand stay. DMs and archived threads can't be updated.",
+    description: "Update a workspace thread you're in: its title, track, issue type and tracker, in one call. Retitle when the work's scope has changed and the old title no longer fits: everyone sees a short 'renamed this thread: old → new' line; the history is kept. Keep titles short (at most 80 characters). File it on a path (project/track, e.g. 'web/checkout': the first segment is the project, the second the track) and tag an issue type (the kind of work, e.g. 'feature', 'bugfix', 'infra'). Reuse a project, track and issue type in use whenever one fits. File under the project alone until at least 3 threads share a track. For a new tag, also give its display name (projectLabel, pathLabel or issueTypeLabel, e.g. 'Payments API'). The thread's summary isn't yours to write: the hub derives where it stands from its posts after each one. The reply's `inUse` lists the tags in use with their thread counts and flags a tag no other thread uses; when one in use fits better than yours, call update_thread again with it. Tags a human set by hand stay. DMs and archived threads can't be updated.",
     inputSchema: z.object({
         threadId: z.string().describe("Thread id, e.g. thr_0002 (shown in the [thread: …] header)."),
         title: z.string().optional().describe("New short title, e.g. 'Checkout: retry failed payments'. Omit to leave it."),
         path: z.string().nullable().optional().describe("Path: project, then at most one track, e.g. 'web/checkout' or 'api/billing'. Reuse a path in use (the reply's inUse and list_threads show them); start a track only once at least 3 threads share it. null: back to the project alone. A path a human set by hand stays."),
         issueType: z.string().optional().describe("Issue type tag: the kind of work, e.g. 'feature', 'bugfix', 'infra', 'docs', 'review', 'research'. Lowercase slug."),
+        tracker: z
+            .array(trackerRow)
+            .max(50)
+            .optional()
+            .describe("The thread's whole tracker: every piece of work toward its goal, one row each, drawn as the Artifacts pane's Pending now (started, unstarted), Pending until done (backlog), Done (completed) and Dropped (canceled) lists. Replaces the previous list; [] clears it. Omit to leave it. Keep it current: send the whole list again whenever a row's state, owner or wait changes. A row whose ref is a PR moves to Done or Dropped by itself when the PR merges or closes."),
         pathLabel: z.string().optional().describe("Display name for a new path's last segment, e.g. 'Cart'. Only names a path that has none yet."),
         projectLabel: z.string().optional().describe("Display name for a new project (a path's first segment), shown as its sidebar group, e.g. 'Payments API' for payments-api. Only names a project that has none yet."),
         issueTypeLabel: z.string().optional().describe("Display name for a new issue type tag, e.g. 'Bug fixes' for bugfix. Only names a tag that has none yet."),