feat: count the agents on an entry, and answer to on/off

An hour of agentic work is an hour times however many engines ran in it, so an
entry now carries `agents` (default 1) and reports `agentHours` in --json.
@profullstack/billing multiplies by it when the rate says to
($100/hour/agent/upto:4) and ignores it when the rate is flat.

--agents takes a whole number. `auto` is refused with a message saying why:
moshcode reads the count off its own herd and passes the result, and this
package has no herd to ask. Silently treating "auto" as 1 would under-bill
every entry it appeared on.

`start` also answers to `on` and `stop` to `off`, so muscle memory from other
timers works and moshcode's own /timer wording keeps meaning what it meant.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KVUZsx4WBZK5rnJJFGgwF5

Author: ralyodio

AGENTS.md

@@ -42,6 +42,8 @@ Everything `--json` returns is built from this shape:
   "billable": true,
   "rate": null,
   "agent": "claude-opus-5",
+  "agents": 1,
+  "agentHours": 1.5,
   "notes": "",
   "meta": {}
 }
@@ -59,6 +61,11 @@ ID=$(timer start acme --task "refactor auth" --json | jq -r .started.id)
 timer stop --id "$ID" --json
 ```
 
+`--agents N` records how many engines were working during the entry, which is
+what an agent-priced rate multiplies by. It takes a whole number: `auto` is
+rejected rather than silently treated as 1, because this package has no herd to
+count and under-billing quietly is worse than an error.
+
 Several clocks may run at once, which is the point: parallel agents each track
 their own work and do not stop each other. Use `--switch` only if you mean to
 close everyone else's clock.

README.md

@@ -36,7 +36,7 @@ you start a clock.
 
 | Command | What it does |
 | --- | --- |
-| `start <project> [task…]` | Start a clock. `--at 09:15`, `--at -20m`, `--tag`, `--note`, `--rate`, `--switch` |
+| `start <project> [task…]` | Start a clock. `--at 09:15`, `--at -20m`, `--tag`, `--note`, `--rate`, `--agents N`, `--switch` |
 | `stop [id]` | Stop the newest clock, an id, `--project <p>`, or `--all` |
 | `status` | Running clocks and today's total |
 | `log [project]` | List entries in a window |
@@ -65,6 +65,23 @@ A window compares against the entry's **start**, and `--until` is exclusive. An
 entry that runs past midnight therefore belongs to the day it began on — which
 is what keeps a total from being counted twice.
 
+### Counting agents
+
+An hour of agentic work is an hour times however many engines ran in it, so an
+entry carries an agent count:
+
+```sh
+timer start acme refactor auth --agents 4
+timer add acme code review --duration 45m --agents 2
+```
+
+`@profullstack/billing` multiplies by it when the rate says to
+(`$100/hour/agent/upto:4`), and ignores it when the rate is flat. It defaults to
+1, so you can ignore the whole idea until you need it.
+
+`start` is also spelled `on` and `stop` is also spelled `off`, so muscle memory
+from other timers works.
+
 ### Billable and not
 
 Every entry is billable unless you say otherwise with `--no-billable`. Reports
@@ -97,7 +114,9 @@ timer log --today --json
 ```
 
 `--meta '{"pr":42}'` hangs your own identifiers off an entry, and they survive
-round-trip unchanged.
+round-trip unchanged. `--agents N` records how many engines were working, which
+is what an agent-priced rate multiplies by; it takes a number, not `auto`, since
+this package has no herd to count.
 
 There is more detail, including the entry schema, in [AGENTS.md](AGENTS.md).
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/timer",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "A time tracker for the terminal and for agents — start a clock against a project, stop it, and get billable hours back as text or JSON.",
   "keywords": ["timer", "time-tracking", "timesheet", "billable", "hours", "cli", "agent", "freelance"],

src/cli.mjs

@@ -24,7 +24,7 @@ import {
 } from "./entries.mjs";
 import { formatDuration, hours, parseMoment, resolveWindow, shortStamp } from "./time.mjs";
 
-export const VERSION = "0.1.0";
+export const VERSION = "0.2.0";
 
 /** A bad command line — worth a different exit code than a failed operation. */
 export class UsageError extends Error {
@@ -73,6 +73,8 @@ function serialize(entry, now = new Date()) {
     billable: entry.billable,
     rate: entry.rate,
     agent: entry.agent,
+    agents: entry.agents ?? 1,
+    agentHours: hours(secs * (entry.agents ?? 1)),
     notes: entry.notes,
     meta: entry.meta,
   };
@@ -84,6 +86,7 @@ const ENTRY_COLUMNS = [
   { header: "PROJECT", get: (e) => e.project },
   { header: "TASK", get: (e) => e.task || "-" },
   { header: "TIME", get: (e) => formatDuration(e.seconds), align: "right" },
+  { header: "AGENTS", get: (e) => (e.agents > 1 ? e.agents : "") , align: "right" },
   { header: "TAGS", get: (e) => (e.tags.length ? e.tags.join(",") : "-") },
   { header: "", get: (e) => (e.running ? "running" : (e.billable ? "" : "unbillable")) },
 ];
@@ -107,6 +110,26 @@ function sumOf(rows) {
   return { entries: rows.length, seconds: secs, hours: hours(secs), billableSeconds: billable, billableHours: hours(billable) };
 }
 
+/**
+ * How many agents were working, from --agents.
+ *
+ * A number only. moshcode's `--agents auto` reads the count off its own herd
+ * and passes the result here: this package has no herd to ask, and silently
+ * treating "auto" as 1 would under-bill every entry it appeared on.
+ */
+function agentCount(flags) {
+  if (flags.agents == null) return 1;
+  const n = Number(flags.agents);
+  if (!Number.isFinite(n) || n < 1 || !Number.isInteger(n)) {
+    throw new UsageError(
+      `--agents: "${flags.agents}" is not a whole number of agents`
+      + (String(flags.agents).toLowerCase() === "auto"
+        ? " (this package has no herd to count; pass the number)" : ""),
+    );
+  }
+  return n;
+}
+
 function requireProject(positional, flags) {
   const project = flags.project || positional[0];
   if (!project) throw new UsageError("which project? e.g. timer start acme");
@@ -118,11 +141,11 @@ function requireProject(positional, flags) {
 const COMMANDS = [
   {
     name: "start",
-    aliases: ["begin", "in"],
+    aliases: ["begin", "in", "on"],
     args: "<project> [task words…]",
     summary: "start the clock on a project",
     booleans: ["billable", "switch"],
-    values: ["task", "note", "agent", "rate", "at", "project", "meta"],
+    values: ["task", "note", "agent", "agents", "rate", "at", "project", "meta"],
     multi: ["tag"],
     detail: [
       "Everything after the project name is taken as the task, so you can type",
@@ -154,6 +177,7 @@ const COMMANDS = [
           start: at,
           notes: flags.note || "",
           agent: flags.agent || process.env.TIMER_AGENT || null,
+          agents: agentCount(flags),
           rate: flags.rate,
           billable: flags.billable !== false,
           meta,
@@ -175,7 +199,7 @@ const COMMANDS = [
   },
   {
     name: "stop",
-    aliases: ["out"],
+    aliases: ["out", "off"],
     args: "[id]",
     summary: "stop a running clock",
     booleans: ["all"],
@@ -299,7 +323,7 @@ const COMMANDS = [
     args: "<project> [task words…]",
     summary: "record time you did not clock",
     booleans: ["billable"],
-    values: ["from", "to", "duration", "task", "note", "agent", "rate", "project", "meta"],
+    values: ["from", "to", "duration", "task", "note", "agent", "agents", "rate", "project", "meta"],
     multi: ["tag"],
     detail: [
       "Give any two of --from, --to and --duration; with only --duration the entry",
@@ -338,6 +362,7 @@ const COMMANDS = [
           end: bounds.end,
           notes: flags.note || "",
           agent: flags.agent || process.env.TIMER_AGENT || null,
+          agents: agentCount(flags),
           rate: flags.rate,
           billable: flags.billable !== false,
           meta,
@@ -358,7 +383,7 @@ const COMMANDS = [
     args: "<id>",
     summary: "change an entry",
     booleans: ["billable"],
-    values: ["project", "task", "note", "agent", "rate", "from", "to", "duration", "meta"],
+    values: ["project", "task", "note", "agent", "agents", "rate", "from", "to", "duration", "meta"],
     multi: ["tag"],
     detail: ["Only the fields you name change. --tag replaces the whole tag list."],
     run({ positional, flags, file }) {
@@ -372,6 +397,7 @@ const COMMANDS = [
         if (flags.task != null) e.task = flags.task;
         if (flags.note != null) e.notes = flags.note;
         if (flags.agent != null) e.agent = flags.agent || null;
+        if (flags.agents != null) e.agents = agentCount(flags);
         if (flags.rate != null) e.rate = Number(flags.rate);
         if ("billable" in flags) e.billable = Boolean(flags.billable);
         if (flags.tag) e.tags = [...new Set(flags.tag)];
@@ -459,6 +485,7 @@ const COMMANDS = [
           start: at,
           notes: "",
           agent: source.agent,
+          agents: source.agents ?? 1,
           rate: source.rate,
           billable: source.billable,
           meta: source.meta,

src/entries.mjs

@@ -24,6 +24,7 @@ export function makeEntry({
   end = null,
   notes = "",
   agent = null,
+  agents = 1,
   rate = null,
   billable = true,
   meta = {},
@@ -38,6 +39,11 @@ export function makeEntry({
     end,
     notes: String(notes || ""),
     agent: agent ? String(agent) : null,
+    // How many engines were working during this entry. An hour of agentic work
+    // is an hour times however many agents ran in it, and a rate priced per
+    // agent needs that number per entry - averaging it across a day bills a
+    // two-agent afternoon at the four-agent rate.
+    agents: Math.max(1, Math.round(Number(agents) || 1)),
     rate: rate == null ? null : Number(rate),
     billable: Boolean(billable),
     meta: meta && typeof meta === "object" ? meta : {},