@zvndev/circular-mcp 0.1.3 → 0.1.4

package/README.md

@@ -72,9 +72,10 @@ Steps come in three kinds:
 - **ACTION**: you do it, then tick it with `circular_complete_step` and real
   evidence in `proof` (test output, a diff summary, a link).
 - **REVIEW**: a human gate. `circular_complete_step` answers **403** for these,
-  always: an agent may never sign off its own review. While the process review
-  gate is parked, open REVIEW steps do not block `done`; leave them unticked and
-  post proof/commentary instead.
+  always: an agent may never sign off its own review. Enrolled runner connections
+  cannot mark done with open stored REVIEW or AUTOMATION steps, even when paused.
+  Legacy callers retain the configured legacy process-gate policy (currently
+  off); an unticked review is never an agent approval. Post proof/commentary.
 - **AUTOMATION**: ticked by its own CI/GitHub signal, not by hand.
 
 `circular_get_next_work` deliberately **does not reserve** the issue it returns.
@@ -82,6 +83,30 @@ Reservations live in `circular_claim_issue_work`, keyed by a stable request id
 for safe retry after a lost response. Several candidates come back so two agents
 pulling at the same moment can pick another candidate if a reservation loses.
 
+## MCP tools versus an always-on computer
+
+Adding this stdio connector makes tools available to an agent. It does not
+start a provider, register a worker, or install a background service. Circular's
+cloud durably queues assignments, mentions and workflow events. An explicitly
+enrolled **foreground local runner** polls its addressed deliveries and launches
+the installed Codex or Claude CLI on that computer, one job at a time. Its
+connection and provider subscription stay private to that computer.
+
+Use the [public connection docs](https://gocircular.dev/docs) after
+browser login (or importing an admin-created workspace-agent connection), linking
+the project repository, and connecting the local checkout. Keep `circular runner
+start --connection CONNECTION_ID` running; an OS service is a separate explicit
+operator setup, never an automatic side effect of installing MCP or Desktop.
+
+`runner register --allow-circular-tools` explicitly permits unattended use of
+the runner's generated Circular MCP tools. `--allow-write` separately permits
+local code edits within the grant/profile ceiling. Neither flag grants access
+to unrelated MCP servers or lets an agent approve human-only steps. A runner
+works its already leased delivery rather than pulling unrelated `next-work`
+candidates. Registration requires the explicit Circular tool opt-in to avoid
+provider approval prompts stranding headless work. Use an interactive agent if
+you do not want unattended tool calls.
+
 ## Authentication
 
 Identical to the CLI. The normal path is managed browser sign-in:

package/lib/server.mjs

@@ -21,18 +21,20 @@ const SUPPORTED_PROTOCOL_VERSIONS = new Set([
   "2024-11-05",
 ]);
 
-export const SERVER_INFO = { name: "circular-mcp", version: "0.1.3" };
+export const SERVER_INFO = { name: "circular-mcp", version: "0.1.4" };
 
 /**
  * The briefing every client sees on connect. This is the only onboarding an
  * agent gets before it starts calling tools, so it states the model (pull-based,
- * Circular never executes anything), the loop, and the two absolute rules.
+ * cloud coordination versus explicitly enrolled local execution), the loop,
+ * and the two absolute rules.
  */
 export const INSTRUCTIONS = [
-  "Circular is the source of truth for planning and task management. Circular is the brain; your agent is the hands. It never runs your agent and never executes work: you pull work, do it on your own machine, and write the result back.",
-  "Work is PULLED, never pushed. Call circular_get_next_work to find out what to do and whether you are allowed to do it, and read each candidate's `situation.disposition` before acting. Only `ready_for_you` and `no_process` are yours to pick up.",
+  "Circular is the source of truth for planning and task management. Its cloud queues work and stores context and proof; it does not host agent execution or sell inference. Interactive agents pull work themselves. A separately enrolled foreground runner polls addressed deliveries and starts the installed Codex or Claude CLI on its own computer, using that computer's private, scoped connection and provider subscription.",
+  "MCP supplies tools; adding this connector does not start a worker or install an OS service. For interactive work, call circular_get_next_work and read each candidate's `situation.disposition`; only `ready_for_you` and `no_process` are yours to pick up. An enrolled runner already owns a specific delivery: stay on that task instead of pulling or claiming unrelated candidates.",
   AGENT_LOOP_SUMMARY,
-  "Two rules are absolute. First, an API key can NEVER complete a REVIEW step; review is the human sign-off, refused for every api_key caller including the agent that did the work. Leave REVIEW steps unticked: they no longer hold the issue open, so do the ACTION steps, record your proof, and close the issue when the work is done. Second, never invent, reorder, or edit the step ladder; it comes from the team's Process. Record proof on the step it belongs to with circular_complete_step, using the stepId exactly as returned.",
+  "Two rules are absolute. First, an API key can NEVER complete a REVIEW step; review is the human sign-off, refused for every api_key caller including the agent that did the work. Enrolled runner agents cannot mark done while stored REVIEW or AUTOMATION steps remain open or unreadable, even when their computer is paused and the legacy process gate is disabled. Legacy callers still follow the server's configured completion policy; do not assume an open review always blocks them or that they may approve it. Post proof and leave human-only steps unticked. Second, never invent, reorder, or edit the step ladder; it comes from the team's Process. Record proof on the step it belongs to with circular_complete_step, using the stepId exactly as returned.",
+  "Runner opt-ins are separate: --allow-write permits local repository edits within the grant/profile ceiling; registration requires --allow-circular-tools to explicitly permit unattended use of the generated Circular MCP tools. Neither flag authorizes another account, repository, unrelated MCP server or human approval. A runner handles one job at a time and no background service is installed automatically.",
   "Do not create local Markdown TODO, PLAN, status, or handoff files as a parallel tracker. Use circular_plan_tasks for plans and circular_comment_issue for updates, handoffs, and narrative proof. Markdown is only for durable product documentation or an artifact the user explicitly requested.",
 ].join(" ");
 

package/lib/tools.mjs

@@ -30,7 +30,9 @@ export const AGENT_LOOP_SUMMARY =
   "(6) circular_complete_step with real proof for each ACTION step you finish, " +
   "(7) circular_comment_issue for the narrative handoff, " +
   "(8) circular_release_issue_work_claim when you stop holding the lane, " +
-  "(9) circular_update_issue to done once the work is finished.";
+  "(9) circular_update_issue to done only when the server's completion policy permits it; " +
+  "enrolled runner agents must wait for stored human REVIEW and AUTOMATION gates. " +
+  "This candidate-pull loop is for interactive agents; a runner stays on its already leased delivery.";
 
 /** Drop undefined keys so we never send `"priority": undefined`. */
 function prune(obj) {
@@ -109,8 +111,8 @@ export const TOOLS = [
   {
     name: "circular_get_next_work",
     description:
-      "THE pull primitive: ask Circular what to work on. Circular never pushes work to you and never " +
-      "runs your agent, so this is how work reaches you. " +
+      "The interactive pull primitive: ask Circular what to work on. An enrolled local runner " +
+      "instead polls addressed deliveries and starts its installed provider; it must stay on its leased task. " +
       "WHEN: at the start of every work cycle, and again after you finish an issue. " +
       "RETURNS: `actor` (who Circular thinks you are, including `canCompleteReviewSteps`), `limit`, " +
       "and `candidates`, highest priority first, with done, cancelled and blocked issues already " +
@@ -119,13 +121,14 @@ export const TOOLS = [
       "READ `situation.disposition` BEFORE ACTING. It is one of: " +
       "`ready_for_you` (the current step is an open ACTION step you may complete: proceed), " +
       "`waiting_on_human_review` (the current step is a REVIEW step no API key can tick: leave it " +
-      "unticked, but it does not block the issue, so finish the work and close it), " +
+      "unticked and post a handoff; enrolled runner agents cannot close it before human review), " +
       "`waiting_on_automation` (an AUTOMATION step, ticked by its own signal, not by you: skip it), " +
       "`assigned_to_someone_else` (the current step names another person, team, or agent: skip it), " +
       "`process_complete` (every step ticked; it only needs closing), " +
       "`no_process` (no ladder: do the work, comment, set it to done), " +
       "`ladder_unreadable` (the stored steps cannot be parsed, so Circular refuses step edits on " +
-      "this issue: do not try to repair the ladder, but the issue can still be closed). " +
+      "this issue: do not try to repair the ladder; enrolled runner agents cannot close it, " +
+      "while legacy callers follow the configured completion policy). " +
       "`situation.currentStep` gives the open step's id, kind, `assignment`, `assignedTo`, " +
       "`canComplete`, and a `refusal` reason when you may not complete it. " +
       "IT DOES NOT RESERVE the issue: several agents can be handed the same candidate. Reserve by " +
@@ -287,15 +290,15 @@ export const TOOLS = [
     name: "circular_update_issue",
     description:
       "Update an issue's status, priority, title, description, or assignee. This is also how you " +
-      "CLAIM work: set " +
-      "status to in_progress the moment you pick a candidate up, because circular_get_next_work does " +
-      "not claim and another agent may be holding the same one. " +
+      "record progress, not reserve work: use circular_claim_issue_work for an interactive claim, " +
+      "then set status to in_progress. circular_get_next_work does not claim; a runner already holds its addressed delivery. " +
       "WHEN: in_progress on pickup; done once the whole ladder is finished. " +
       "REFUSES with 409: moving to done while any blocking issue is still open. That is the " +
       "dependency graph working, not an obstacle to route around: post your proof, leave a comment, " +
       "and pick up something that is not blocked. " +
-      "An open REVIEW step no longer refuses done. It stays unticked, because no API key may " +
-      "complete one, but it does not hold the issue open. " +
+      "Enrolled runner agents also receive 409 for open stored REVIEW or AUTOMATION steps or an unreadable ladder, " +
+      "even if their computer is paused. Legacy callers follow PROCESS_REVIEW_GATE_ENABLED, currently off; " +
+      "an open REVIEW step alone does not block those callers while that legacy gate is off. No API key may complete a REVIEW step. " +
       "Setting status to cancelled is never gated, because abandoning work must always be possible. " +
       "Returns the updated issue.",
     inputSchema: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/circular-mcp",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Dependency-free stdio MCP server for the Circular Agent API — plan work into Circular as tracked tasks and subtasks.",
   "keywords": [
     "circular",