cruo-agent 0.1.1 → 0.1.3

package/README.md

@@ -60,6 +60,28 @@ Run it from the repository the agent should work on. If that repository needs
 installing before its tests will run, add `--prepare 'npm ci'` or whatever your
 equivalent is — a fresh checkout has your source and none of your dependencies.
 
+Checkouts go under `~/.cruo-work/<agent>`, one directory per agent, so **running
+several agents at once needs no extra flags**. `--worktree-root` overrides it if
+you want them somewhere else; pointing two agents at one root is safe too, since
+the sweep that clears abandoned checkouts at startup only removes ones too old
+for any run to still be inside.
+
+## When it stops doing anything
+
+A supervisor sitting idle costs nothing — it is a database query on a timer. If
+the *harness* refuses to work, though, the supervisor says so and slows down:
+
+```
+! the harness is refusing to work: the account's spend limit is reached
+  No card is charged for this, and polling backs off until it changes.
+```
+
+That distinction matters more than it looks. A refusal is a fact about your
+account, not about the card, so those runs are **not** counted against the
+card's `--max-attempts` — otherwise one billing problem would quietly set aside
+every issue the agent was holding, and you would come back to a board that had
+given up on work nobody abandoned.
+
 ## Common options
 
 | flag | |
@@ -74,7 +96,7 @@ equivalent is — a fresh checkout has your source and none of your dependencies
 | `--harness-timeout <seconds>` | kill a run that wedges (default 600) |
 | `--max-attempts <n>` | give up on a card after n unproductive runs (default 3) |
 
-The full list, and what each is for: <https://cruo.space/agents>
+The full list, and what each is for: <https://cruo.space/docs#agents>
 
 ## Running it somewhere that is not your laptop
 

package/dist/VERSION

@@ -1 +1 @@
-0.1.1
+0.1.3

package/dist/cli.js

@@ -15185,7 +15185,7 @@ var init_zod = __esm({
 });
 
 // ../../packages/core/dist/schemas.js
-var stateCategory, issuePriority, memberRole, projectKey, createProjectInput, createIssueInput, updateIssueInput, moveIssueInput, workflowStateInput, listIssuesFilter;
+var stateCategory, issuePriority, memberRole, projectKey, createProjectInput, estimateHours, createIssueInput, updateIssueInput, moveIssueInput, workflowStateInput, listIssuesFilter;
 var init_schemas3 = __esm({
   "../../packages/core/dist/schemas.js"() {
     "use strict";
@@ -15213,6 +15213,7 @@ var init_schemas3 = __esm({
       description: external_exports.string().trim().max(2e3).optional(),
       leadId: external_exports.string().uuid().optional()
     });
+    estimateHours = external_exports.number().positive().max(9999).multipleOf(0.01).nullish();
     createIssueInput = external_exports.object({
       projectId: external_exports.string().uuid(),
       title: external_exports.string().trim().min(1).max(300),
@@ -15223,6 +15224,7 @@ var init_schemas3 = __esm({
       parentId: external_exports.string().uuid().nullish(),
       dueDate: external_exports.string().date().nullish(),
       // YYYY-MM-DD
+      estimateHours,
       labelIds: external_exports.array(external_exports.string().uuid()).optional()
     });
     updateIssueInput = external_exports.object({
@@ -15230,7 +15232,8 @@ var init_schemas3 = __esm({
       description: external_exports.string().trim().max(2e4).nullish(),
       priority: issuePriority.optional(),
       assigneeId: external_exports.string().uuid().nullish(),
-      dueDate: external_exports.string().date().nullish()
+      dueDate: external_exports.string().date().nullish(),
+      estimateHours
     });
     moveIssueInput = external_exports.object({
       issueId: external_exports.string().uuid(),
@@ -15288,6 +15291,13 @@ var init_identity = __esm({
   }
 });
 
+// ../../packages/core/dist/effort.js
+var init_effort = __esm({
+  "../../packages/core/dist/effort.js"() {
+    "use strict";
+  }
+});
+
 // ../../packages/core/dist/plans.js
 var init_plans = __esm({
   "../../packages/core/dist/plans.js"() {
@@ -15339,6 +15349,7 @@ var init_dist = __esm({
     init_schemas3();
     init_rank();
     init_identity();
+    init_effort();
     init_plans();
     init_mcp_connect();
     init_tree();
@@ -46294,17 +46305,25 @@ async function pollMentions(ctx, identity) {
   );
 }
 async function claim(ctx, hit) {
-  const expiresAt = new Date(Date.now() + options.harnessTimeoutMs + 3e4);
-  const { error: error51 } = await ctx.client.schema("pm").from("issue_claims").upsert(
-    {
-      issue_id: hit.issue.id,
-      claimed_by: ctx.userId,
-      claimed_at: (/* @__PURE__ */ new Date()).toISOString(),
-      expires_at: expiresAt.toISOString()
-    },
-    { onConflict: "issue_id" }
-  );
-  if (error51) log(`  could not claim ${hit.ref}: ${error51.message}`);
+  const ttlMs = options.harnessTimeoutMs + 3e4;
+  const { data, error: error51 } = await ctx.client.schema("public").rpc("claim_issue", {
+    issue: hit.issue.id,
+    ttl_ms: ttlMs
+  });
+  if (error51) {
+    log(`  could not claim ${hit.ref}: ${error51.message} \u2014 leaving it`);
+    return false;
+  }
+  return data === true;
+}
+async function claimedElsewhere(ctx, hits) {
+  if (hits.length === 0) return /* @__PURE__ */ new Set();
+  const { data, error: error51 } = await ctx.client.schema("pm").from("issue_claims").select("issue_id, claimed_by").in("issue_id", hits.map((h) => h.issue.id)).gt("expires_at", (/* @__PURE__ */ new Date()).toISOString()).neq("claimed_by", ctx.userId);
+  if (error51) {
+    log(`  could not read claims: ${error51.message} \u2014 relying on the claim itself`);
+    return /* @__PURE__ */ new Set();
+  }
+  return new Set((data ?? []).map((r) => r.issue_id));
 }
 async function release(ctx, hit) {
   const { error: error51 } = await ctx.client.schema("pm").from("issue_claims").delete().eq("issue_id", hit.issue.id).eq("claimed_by", ctx.userId);
@@ -46442,8 +46461,18 @@ function systemPrompt(ctx, identity, worktree) {
       `survives. A run that ends with uncommitted changes has produced nothing,`,
       `however good the changes were.`,
       ``,
-      `Do not push, and do not merge into any other branch. Publishing is done`,
-      `for you after you exit, by the process that started you.`
+      `Do not push, and do not merge into any other branch. That is not a`,
+      `matter of trust \u2014 you have no push tool, and nothing in this loop`,
+      `merges anything (\`CRA-88\`). Releasing is a person's job.`,
+      ...options.push ? [
+        `Your branch is published for you after you exit, by the process`,
+        `that started you. It is pushed, not merged: somebody still has`,
+        `to review and land it.`
+      ] : [
+        `Your branch stays on this machine. Nothing publishes it, so say`,
+        `on the card which branch holds the work \u2014 that name is the only`,
+        `way anyone finds it.`
+      ]
     ] : [],
     ``,
     `You act on the board through the Cruo MCP tools. Start with get_issue to read the`,
@@ -46634,11 +46663,17 @@ async function tick(ctx, identity, deadTicks) {
     seen.add(h.ref);
     return true;
   });
-  const attemptsByHit = await loadAttempts(ctx, hits);
+  const heldByOthers = await claimedElsewhere(ctx, hits);
+  const free = hits.filter((h) => !heldByOthers.has(h.issue.id));
+  if (heldByOthers.size > 0) {
+    log(`${heldByOthers.size} issue(s) already being worked by someone else`);
+  }
+  const attemptsByHit = await loadAttempts(ctx, free);
   const attemptsFor = (h) => attemptsByHit.get(`${h.reason}:${h.issue.id}`) ?? 0;
-  const actionable = hits.filter((h) => attemptsFor(h) < options.maxAttempts);
+  const actionable = free.filter((h) => attemptsFor(h) < options.maxAttempts);
   if (actionable.length === 0) {
-    if (hits.length > 0) log(`${hits.length} issue(s) waiting, all set aside`);
+    if (free.length > 0) log(`${free.length} issue(s) waiting, all set aside`);
+    else if (heldByOthers.size > 0) log(`nothing free \u2014 everything waiting is claimed`);
     await beat(ctx, { holding: 0, deadTicks, intervalMs: options.intervalMs });
     return { invoked: 0, failedToRun: 0 };
   }
@@ -46667,6 +46702,10 @@ async function tick(ctx, identity, deadTicks) {
     invoked += 1;
     const before = { status: hit.issue.status_id, assignee: hit.issue.assignee_id };
     const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+    if (!await claim(ctx, hit)) {
+      log(`  ${hit.ref} is being worked by another agent \u2014 skipping`);
+      continue;
+    }
     let worktree = null;
     if (worktreeConfig) {
       try {
@@ -46674,12 +46713,12 @@ async function tick(ctx, identity, deadTicks) {
         log(`  ${hit.ref} worktree ${worktree.path} on ${worktree.branch}`);
       } catch (error51) {
         failedToRun += 1;
+        await release(ctx, hit);
         log(`  ${hit.ref} could not prepare a worktree \u2014 not counted against this issue`);
         log(`    ${error51 instanceof Error ? error51.message.split("\n")[0] : String(error51)}`);
         continue;
       }
     }
-    await claim(ctx, hit);
     let run;
     let committed = 0;
     try {
@@ -46793,6 +46832,7 @@ async function main() {
     const swept = await sweep(worktreeConfig, options.harnessTimeoutMs + options.prepareTimeout);
     if (swept.length) log(`  swept ${swept.length} worktree(s) left by an earlier run: ${swept.join(", ")}`);
     if (options.push) log(`  publishing to ${options.pushRemote} after any run that commits`);
+    else log(`  --push is off: branches stay on this machine and reach no remote`);
     if (options.allow === "mcp__cruo") {
       log(`! --worktree with the default --allow gives the harness a checkout it cannot read.`);
       log(`  Widen it, e.g. --allow "mcp__cruo,Read,Glob,Grep,Edit,Write,Bash(git:*),Bash(pnpm:*)"`);
@@ -47006,7 +47046,7 @@ Common options
   --push                 publish the branch after a run that commits
   --interval <seconds>   how often to poll (default 20)
 
-  Full list and what each one is for: https://cruo.space/agents
+  Full list and what each one is for: https://cruo.space/docs#agents
 
 The token comes from CRUO_TOKEN, then --token, then whatever \`login\` stored.
 `;

package/dist/index.js

@@ -34897,6 +34897,7 @@ var createProjectInput = external_exports.object({
   description: external_exports.string().trim().max(2e3).optional(),
   leadId: external_exports.string().uuid().optional()
 });
+var estimateHours = external_exports.number().positive().max(9999).multipleOf(0.01).nullish();
 var createIssueInput = external_exports.object({
   projectId: external_exports.string().uuid(),
   title: external_exports.string().trim().min(1).max(300),
@@ -34907,6 +34908,7 @@ var createIssueInput = external_exports.object({
   parentId: external_exports.string().uuid().nullish(),
   dueDate: external_exports.string().date().nullish(),
   // YYYY-MM-DD
+  estimateHours,
   labelIds: external_exports.array(external_exports.string().uuid()).optional()
 });
 var updateIssueInput = external_exports.object({
@@ -34914,7 +34916,8 @@ var updateIssueInput = external_exports.object({
   description: external_exports.string().trim().max(2e4).nullish(),
   priority: issuePriority.optional(),
   assigneeId: external_exports.string().uuid().nullish(),
-  dueDate: external_exports.string().date().nullish()
+  dueDate: external_exports.string().date().nullish(),
+  estimateHours
 });
 var moveIssueInput = external_exports.object({
   issueId: external_exports.string().uuid(),
@@ -53389,6 +53392,9 @@ function issueDetail(project, issue2, opts = {}) {
   ];
   if (issue2.start_date || issue2.due_date)
     lines.push(`Schedule: ${issue2.start_date ?? "\u2014"} \u2192 ${issue2.due_date ?? "\u2014"}`);
+  lines.push(
+    issue2.estimate_hours == null ? "Estimate: none \u2014 nobody has sized this yet" : `Estimate: ${issue2.estimate_hours}h`
+  );
   if (opts.labels && opts.labels.length)
     lines.push(`Labels: ${opts.labels.map((l) => l.name).join(", ")}`);
   if (opts.parent)
@@ -53420,6 +53426,7 @@ var FIELD_LABEL = {
   status_id: "status",
   parent_id: "parent",
   due_date: "due date",
+  estimate_hours: "estimate",
   start_date: "start date",
   board_rank: "board position",
   gantt_pos: "gantt position"
@@ -53778,6 +53785,7 @@ function registerTools(server, getContext2, options = {}) {
         priority: issuePriority.optional(),
         assignee: external_exports.string().optional().describe("Member email, name, or 'me'"),
         due_date: external_exports.string().optional().describe("YYYY-MM-DD"),
+        estimate_hours: external_exports.number().positive().max(9999).optional().describe("Estimated effort in hours. Omit if you do not know \u2014 an absent estimate reads as unestimated, which is not the same as free."),
         labels: external_exports.array(external_exports.string()).optional().describe("Label names to apply"),
         parent: external_exports.string().optional().describe("Make this a sub-issue of an issue in the same project, e.g. CRU-14")
       }
@@ -53808,6 +53816,7 @@ function registerTools(server, getContext2, options = {}) {
         assignee_id: assignee?.id ?? null,
         parent_id: parentId,
         due_date: args.due_date?.trim() || null,
+        estimate_hours: args.estimate_hours ?? null,
         board_rank: rank,
         gantt_pos: ganttPos,
         created_by: ctx.userId
@@ -53836,7 +53845,7 @@ function registerTools(server, getContext2, options = {}) {
     "update_issue",
     {
       title: "Update issue",
-      description: "Update an issue's title, description, priority, assignee, due date, or parent. Use assignee 'none', due_date '', or parent 'none' to clear.",
+      description: "Update an issue's title, description, priority, assignee, due date, estimate, or parent. Use assignee 'none', due_date '', estimate_hours 0, or parent 'none' to clear.",
       inputSchema: {
         issue: external_exports.string().describe("Issue reference, e.g. CRU-14"),
         title: external_exports.string().min(1).max(300).optional(),
@@ -53844,6 +53853,7 @@ function registerTools(server, getContext2, options = {}) {
         priority: issuePriority.optional(),
         assignee: external_exports.string().optional().describe("Member email/name/'me', or 'none' to clear"),
         due_date: external_exports.string().optional().describe("YYYY-MM-DD, or '' to clear"),
+        estimate_hours: external_exports.number().min(0).max(9999).optional().describe("Estimated effort in hours; 0 clears it back to unestimated"),
         parent: external_exports.string().optional().describe(
           "Issue reference of the parent (same project), e.g. CRU-14, or 'none' to make it top-level"
         )
@@ -53856,6 +53866,8 @@ function registerTools(server, getContext2, options = {}) {
       if (args.description !== void 0) patch.description = String(args.description).trim() || null;
       if (args.priority !== void 0) patch.priority = args.priority;
       if (args.due_date !== void 0) patch.due_date = String(args.due_date).trim() || null;
+      if (args.estimate_hours !== void 0)
+        patch.estimate_hours = args.estimate_hours > 0 ? args.estimate_hours : null;
       if (args.assignee !== void 0) {
         patch.assignee_id = await resolveAssigneeArg(ctx, args.assignee, project);
       }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "cruo-agent",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Run a Cruo agent: it watches your board, picks up the cards you assign it, and works them.",
   "license": "MIT",
-  "homepage": "https://cruo.space/agents",
+  "homepage": "https://cruo.space/docs#agents",
   "keywords": [
     "cruo",
     "agent",
@@ -36,6 +36,6 @@
     "@cruo/mcp": "workspace:*"
   },
   "bugs": {
-    "url": "https://cruo.space/agents"
+    "url": "https://cruo.space/docs#agents"
   }
 }