@warren-dean/code-kit 0.19.0 → 0.20.0

package/hooks/mod/register.mjs

@@ -36,6 +36,8 @@ import {
   resultPane,
   settingsView,
   usageSummary,
+  usageForReport,
+  presenceOf,
   withUsage,
 } from './view.mjs';
 import { holdable } from './hold.mjs';
@@ -109,6 +111,7 @@ let pendingSetting = null; // a change waiting for the person's reason: { key, v
 let ledger = {}; // the session's tokens by agent and story (USE-1)
 let rateLimits = []; // the session's limits, as session.measure last gave them
 const agentsSeen = new Map(); // agent id → its $.agent.list() entry, kept once it leaves the list
+const present = new Map(); // agent id (or 'main') → its presence for a hosted team provider (HUBR-6)
 const held = new Map(); // tool_use_id → a call held for the person (HOLD-2)
 const denied = new Map(); // tool_use_id → a call Claude Code's own permission check refused (PERM-1)
 const briefLater = new Set(); // the brief's questions the person put off this session (ASK-4)
@@ -1891,6 +1894,26 @@ export function register(on) {
     $.clock.every(1000, () => {
       if (held.size) $.ui.invalidate('ui.render');
     });
+    // HUBR-3, HUBR-6: with a hosted team provider, the session's agents and its token ledger go to it
+    // every 30 seconds, and the project reports what's new. Nothing runs for a team on GitHub.
+    let pulsing = false;
+    $.clock.every(30_000, async () => {
+      if (pulsing || !model.check?.team?.provider?.adapter) return;
+      pulsing = true;
+      try {
+        const now = await $.clock.now();
+        for (const [k, a] of present) if (now - a.at > 10 * 60_000) present.delete(k);
+        const usage = usageForReport(ledger, (key) => agentsSeen.get(key)?.type ?? null);
+        await $.process.run(['node', cli, 'team', 'pulse', '--session', session], {
+          cwd,
+          stdin: JSON.stringify({ agents: Object.fromEntries(present), usage }),
+        });
+      } catch {
+        // tried again in 30 seconds
+      } finally {
+        pulsing = false;
+      }
+    });
     return next(e);
   });
 
@@ -1957,6 +1980,18 @@ export function register(on) {
       busy.tool = toolLine(e);
       busy.at = calledAt;
     } else if (!e.agentId) leadLast = { tool: toolLine(e), at: calledAt };
+    if (model.check?.team?.provider?.adapter)
+      present.set(
+        e.agentId ?? 'main',
+        presenceOf({
+          agentId: e.agentId,
+          type: agentsSeen.get(e.agentId)?.type,
+          tool: e.tool,
+          lane: busy?.lane,
+          lanes: model.state?.lanes,
+          at: calledAt,
+        }),
+      );
     // MAP-2: the file the call reads or edits glows in the code map, in its lane's colour. An agent
     // first seen on this call has its lane found by its type.
     const touch = touchOf(e, where?.cwd);

package/hooks/mod/register.test.ts

@@ -85,6 +85,7 @@ function project() {
     closed: [] as string[],
     prompts: [] as string[],
     acts: [] as string[][],
+    pulses: [] as any[],
     runs: 0,
     settings: [
       {
@@ -236,6 +237,11 @@ function stub(on: any, w: World) {
       w.acts.push([...argv.slice(2)]);
       return ran(0, JSON.stringify(w.teamSince));
     }
+    if (sub === 'team' && argv[3] === 'pulse') {
+      w.acts.push([...argv.slice(2)]);
+      w.pulses.push(JSON.parse(e.init?.stdin ?? '{}'));
+      return ran(0, '');
+    }
     if (sub === 'team' && ['keep', 'release', 'board', 'reassign'].includes(argv[3])) {
       w.acts.push([...argv.slice(2)]);
       return ran(0, '');
@@ -4430,7 +4436,7 @@ test('a live provider says so in the Team pane, by its own name, and has a Drift
   w.team = {
     ...teamOf('kim'),
     provider: {
-      name: 'the code-kit teams hub',
+      name: 'code-kit hub',
       live: true,
       account: 'kim',
       detail: 'claims, leases and intents as they happen',
@@ -4442,7 +4448,7 @@ test('a live provider says so in the Team pane, by its own name, and has a Drift
   await teamCmd($);
   const ui = await pane($, TEAM);
   expect((await ui.find({ key: 'team-provider' }))?.text).toBe(
-    'Through the code-kit teams hub · live · signed in as kim: claims, leases and intents as they happen',
+    'Through code-kit hub · live · signed in as kim: claims, leases and intents as they happen',
   );
   await press($, 'team-tab-drift', TEAM);
   expect(
@@ -4456,7 +4462,7 @@ test("with a live provider (the hub), the band says when it fell back to GitHub,
   const at = new Date().toISOString();
   w.team = {
     ...teamOf('kim'),
-    fallback: "The code-kit teams hub can't be reached.",
+    fallback: "code-kit hub can't be reached.",
     sessions: [
       {
         login: 'kim',
@@ -4506,7 +4512,7 @@ test("with a live provider (the hub), the band says when it fell back to GitHub,
   expect(w.opened).toEqual([TEAM]);
   const ui = await pane($, TEAM);
   expect((await ui.find({ key: 'team-provider' }))?.text).toMatch(
-    /can't be reached \(The code-kit teams hub can't be reached\.\): claims are checked through GitHub/,
+    /can't be reached \(code-kit hub can't be reached\.\): claims are checked through GitHub/,
   );
   expect((await ui.find({ key: 'team-drift-web/st-9' }))?.text).toMatch(
     /web\/st-9 · kim[\s\S]*blocker · spec docs\/specs\/02-booking\.md: BOOK-2 now holds prices in cents\./,
@@ -4532,6 +4538,41 @@ test('TEAM-12 with a board, the mod syncs it in the background, at most every 10
   expect(syncs()).toBe(2);
 });
 
+test('HUBR-6 with a hosted provider, the mod sends the session agents and token use every 30 seconds', async ($, on) => {
+  const w = project();
+  w.team = teamOf('sam');
+  (w.check as any).team = {
+    techLead: 'alex',
+    provider: {
+      command: 'x',
+      fallback: 'github',
+      adapter: 'hub',
+      url: 'https://h.example',
+      name: 'a hosted provider',
+    },
+  };
+  const clock = await start($, on, w);
+  await $.tool.call({ tool: 'Bash', tool_use_id: 'tu-p', command: 'cat secrets.txt' } as any);
+  await clock.advance(30000);
+  const pulses = () => w.acts.filter((a) => a[0] === 'team' && a[1] === 'pulse');
+  expect(pulses().length).toBe(1);
+  expect(pulses()[0]).toContain('--session');
+  expect(w.pulses[0].agents.main).toMatchObject({ type: 'lead', tool: 'Bash' });
+  // By tool name only: never what the call read or ran.
+  expect(JSON.stringify(w.pulses[0])).not.toMatch(/secrets/);
+  expect(typeof w.pulses[0].usage).toBe('object');
+});
+
+test('HUBR-6 a team on GitHub sends no pulse', async ($, on) => {
+  const w = project();
+  w.team = teamOf('sam');
+  (w.check as any).team = { techLead: 'alex', provider: 'github' };
+  const clock = await start($, on, w);
+  await $.tool.call({ tool: 'Bash', tool_use_id: 'tu-q', command: 'ls' } as any);
+  await clock.advance(60000);
+  expect(w.acts.some((a) => a[0] === 'team' && a[1] === 'pulse')).toBe(false);
+});
+
 test('TRACE-2 a project with more requirements than a list holds still draws its trail', async ($, on) => {
   const w = project();
   w.requirements = Array.from({ length: 134 }, (_, i) => ({

package/hooks/mod/teamview.mjs

@@ -582,12 +582,18 @@ function setupTab(team, config, { Box, Text, Button }, on) {
   const rows = [
     ['Tech lead', team.techLead],
     ['Stale after', `${team.staleDays ?? t.staleDays ?? 3} working days without a push`],
-    ['Intents', `discussions in "${t.intents ?? 'Intents'}"`],
+    // HUBR-7: a hosted provider keeps intents, in Discussions too only when the team mirrors them.
+    [
+      'Intents',
+      typeof t.provider === 'object' && !t.provider.command && !t.intents
+        ? `kept by ${team.provider?.name ?? 'the provider'}`
+        : `discussions in "${t.intents ?? 'Intents'}"`,
+    ],
     [
       'Provider',
       team.provider?.name ?? (typeof t.provider === 'object' ? t.provider.command : 'GitHub'),
     ],
-    ...(typeof t.provider === 'object' && t.provider.fallback
+    ...(typeof t.provider === 'object' && (t.provider.fallback || !t.provider.command)
       ? [['Fallback', 'GitHub, while the provider is down']]
       : []),
     ...(t.board ? [['Board', `${t.board.owner}/${t.board.number}`]] : []),

package/hooks/mod/view.mjs

@@ -1676,6 +1676,42 @@ export function withUsage(ledger, who, usage) {
   };
 }
 
+/**
+ * HUBR-2: the ledger as a report carries it: [{ story, kind, input, output, cache }], each entry's kind
+ * (lead, lane, reviewer, security-reviewer or background) from who made it and `typeOf(key)`, the agent's
+ * type. Tokens only: no prompt, no message.
+ */
+export function usageForReport(ledger, typeOf = () => null) {
+  return Object.fromEntries(
+    Object.entries(ledger).map(([id, e]) => {
+      const type = e.key === 'lead' ? null : typeOf(e.key);
+      const kind =
+        e.key === 'lead'
+          ? 'lead'
+          : e.lane
+            ? 'lane'
+            : type === 'security-reviewer'
+              ? 'security-reviewer'
+              : /(^|:)reviewer$/.test(type ?? '')
+                ? 'reviewer'
+                : 'background';
+      return [
+        id,
+        { story: e.story ?? null, kind, input: e.input, output: e.output, cache: e.cache },
+      ];
+    }),
+  );
+}
+
+/**
+ * HUBR-6: an agent's presence, by tool name and the branch its lane works on (never what it reads or
+ * writes): { type, tool, branch, at }.
+ */
+export function presenceOf({ agentId, type, tool, lane, lanes, at }) {
+  const branch = lane ? (lanes?.find((l) => l.name === lane)?.branch ?? null) : null;
+  return { type: agentId ? (type ?? null) : 'lead', tool: tool ?? null, branch, at };
+}
+
 const total = (e) => e.input + e.output + e.cache;
 const median = (xs) => {
   const s = [...xs].sort((a, b) => a - b);

package/hooks/team-session.mjs

@@ -0,0 +1,57 @@
+// SessionStart and SessionEnd (code-kit spec 21, HUBR-6): when the team's provider is a hosted one, its
+// adapter holds the session's live link (the event stream and the team's state on disk) from start to
+// end, and the session reports the project's facts once as it starts (HUBR-3). Nothing happens in a
+// project whose team works through GitHub, or that has no team.
+import { execFileSync, spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { providerAdapterOf } from './lib/adapters/index.mjs';
+
+let input = {};
+try {
+  input = JSON.parse(readFileSync(0, 'utf8') || '{}');
+} catch {
+  // no input: nothing to start
+}
+const root = process.env.CLAUDE_PROJECT_DIR ?? input.cwd ?? process.cwd();
+const session = String(input.session_id ?? 'session').replace(/[^\w-]/g, '');
+let raw = null;
+try {
+  raw = JSON.parse(readFileSync(join(root, '.claude', 'code-kit.json'), 'utf8'));
+} catch {
+  // not a code-kit project
+}
+const hosted = providerAdapterOf(raw?.team?.provider);
+if (hosted && !hosted.problem) {
+  const { adapter, url } = hosted;
+  if (process.argv[2] === 'start') {
+    // The link lives as long as the Claude Code process that started this hook.
+    let watch = process.ppid;
+    try {
+      watch =
+        Number(
+          execFileSync('ps', ['-o', 'ppid=', '-p', String(process.ppid)], {
+            encoding: 'utf8',
+          }).trim(),
+        ) || process.ppid;
+    } catch {
+      // the hook's own parent, then
+    }
+    adapter.session.start(root, session, watch, url);
+    // The project's facts as the session starts, in the background: the session doesn't wait on it.
+    if (raw.team.report !== false)
+      spawn(
+        process.execPath,
+        [
+          join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'code-kit.mjs'),
+          'team',
+          'pulse',
+          '--session',
+          session,
+        ],
+        { cwd: root, detached: true, stdio: 'ignore' },
+      ).unref();
+  }
+  if (process.argv[2] === 'end') adapter.session.end(root, session);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warren-dean/code-kit",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Keeps AI coding agents inside your project's rules: lanes, layer rules, protected paths and proof before finish, enforced by Claude Code hooks and in CI",
   "license": "MIT",
   "author": "Warren Langeveldt",

package/skills/team-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: team-init
-description: Set up a code-kit project for a team of developers, change its team setup, or make it one developer's again. Asks who the tech lead is, who owns which lanes, when a claim goes stale and where intents go, shows the team section before writing it, checks GitHub is ready (gh signed in, the shared repository, the intents' discussion category), and offers CODEOWNERS, the Project board and a hosted team provider. Use when the person says they work in a team, wants teammates to share the project, wants to change the tech lead or lane owners, wants to stop working as a team, or runs /code-kit:team-init. Not every developer works in a team: never set one up unasked.
+description: Set up a code-kit project for a team of developers, change its team setup, or make it one developer's again. Asks who the tech lead is, who owns which lanes, when a claim goes stale and where intents go, shows the team section before writing it, checks GitHub is ready (gh signed in, the shared repository, the intents' discussion category), offers CODEOWNERS and the Project board, and connects a hosted team provider only when the config already names one. Use when the person says they work in a team, wants teammates to share the project, wants to change the tech lead or lane owners, wants to stop working as a team, or runs /code-kit:team-init. Not every developer works in a team: never set one up unasked.
 ---
 
 # Set up the team
@@ -25,7 +25,7 @@ Ask only what the config can't answer, with the current value as the default on
 - **Tech lead:** whose GitHub handle owns the plan, specs, contracts and principles, agrees or drops intents, and may release or reassign anyone's claim. Default: `me`.
 - **Lane owners:** for each lane, whose sessions build its stories (GitHub handles), or nobody, in which case whoever claims a story first builds it. `git log --format='%an' -- <lane paths> | sort | uniq -c` and CODEOWNERS suggest people, but ask for handles: names in commits aren't handles.
 - **Stale after:** how many working days without a push before a claim is stale (default 3).
-- **Intents category:** the GitHub Discussions category intents go in (default `Intents`).
+- **Intents category:** the GitHub Discussions category intents go in (default `Intents`). Skip it when the config's `team.provider` names a hosted provider (`{ "<name>": "<https address>" }`) and `team.intents` isn't set: that provider keeps the intents.
 - **Back to one developer:** confirm that claims, owners and intents stop applying, and that teammates' sessions lose them too once it's merged.
 
 ## 3. Show, then write
@@ -48,7 +48,7 @@ Each is optional; ask, and do only what they want:
 
 - **CODEOWNERS** (TEAM-11): `team codeowners --write` writes `.github/CODEOWNERS` from the config, so GitHub asks the tech lead and lane owners to review. Then they require code owners' review in a ruleset on the protected branch.
 - **A Project board** (TEAM-12): with a GitHub Project's owner and number, add `"board": { "owner": "<user or organisation>", "number": <n> }` to `team` in the config; the mod then mirrors the plan onto it.
-- **A hosted team provider:** if a plugin for one is installed (its connect skill is in your skills list, such as `/code-kit-teams:connect`), offer it: it makes claims, leases and intents live, shows who's at work where, and checks each push for drift. Its connect skill sets `team.provider`, with GitHub as the fallback. If none is installed, don't mention one.
+- **A hosted team provider, only when the config already names one:** hosted providers are in preview, so never offer or suggest one. When `team.provider` is `{ "<name>": "<https address>" }` (set by hand), connect this machine: run `team provider status`; if it isn't signed in, run `team provider signin` in the background, give the person the code and the GitHub address it prints, and wait (they enter the code in their browser; never ask for a password or token); then `team provider connect`, which checks the provider can see the repository and adds its MCP server to `.mcp.json`. Commit `.mcp.json` with the config.
 
 ## 5. Finish