@humwick/server 0.130.1 → 0.130.2

package/README.md

@@ -77,6 +77,11 @@ claude plugin install agent-relay@agent-relay
 
 **Codex** (requires Bun + Codex CLI):
 
+First run `codex login` in the same home you will use for the runner. For Claude,
+run `claude auth login` and complete the standalone CLI’s first-run setup. Runners
+check that login before becoming ready. Setup errors appear on the dashboard and
+are returned when sending a message.
+
 ```bash
 bun install -g @humwick/runner@latest
 codex-humwick --cwd /path/to/project

package/docs/guides/tools-administration.md

@@ -82,3 +82,7 @@ List, inspect, apply, reconcile or test profile service access through Relay, or
 ## relay_prompt
 
 Read or change versioned prompt text with `operation`: `list`, `get`, `history`, `edit`, `restore`, or `adopt`. Supply `slug` except for list. `list` pages slug, title, version, status and a short description; `get` returns the complete template. Edits supply `template`; restore supplies `version`. All writes require the last read `expectedVersion` and accept an optional `reason`. Conflicts return status 409 and `current`. The actor is the user or the single agent identified by the credential; request bodies cannot set it. The tool uses `agent:write`, belongs to the `prompts` group, and is available only with `HUMWICK_VERSIONED_PROMPTS=1`. Reads expose `source`, `fallbackReason`, and `warning` when bundled text replaces an unavailable DB value. CLI: `humwick prompts`; write JSON via `--file` or `--stdin`.
+
+## relay_project_profile_instructions
+
+Read project additions to a profile with `operation: get`, `projectId` and `profile`. An unset addition has empty `template` and `version: 0`. Use `set` with `template` and the last read `expectedVersion`; empty text removes the addition from context. `history` returns revision texts for comparison with actor, time and reason. `restore` takes a historical `version` and current `expectedVersion`, appending a new revision. Stale writes return 409 with `current`. `list` accepts either projectId (all profiles) or profile (all projects). Reads need `agent:read`; writes also need `agent:write`. The tool belongs to `prompts`. Text applies after the global charter to launches and context resets in that project, including roles extending the profile. The limit is 16000 characters; control bytes are rejected. Invalid stored text is skipped at launch with a named warning.

package/docs/guides/tools-coordination.md

@@ -200,6 +200,7 @@ Coordinator-only (#3045): after a workflow escalation (a bound hit, a failed or
 - `step`: Where to re-enter: a declared step, land (an explicit override of the review verdict) or, after the land, ci-main. Default: the step that escalated.
 - `note`: Your decision for the step's agent (what to fix, what to ignore).
 - `pins`: Per-step pins { <step>: { provider?, model?, effort?, orchestratorId?, profile? } }. Each field set wins over the YAML step's same field, which wins over the role file, which wins over the Task's dispatch policy. A provider pin wins over the step's crossProvider. A model pin needs its provider (here or in the YAML). `profile` replaces the base profile the step's role extends (e.g. worker-gui for a UI builder). An invalid pin for its host fails the call before anything spawns.
+- `pause`: true pauses a running run, false unpauses it (#3757); pass only `runId` and, to pause, `note` as the required reason. A paused run keeps its agents, workspace and history; a working step agent is not interrupted, but the run goes past no seam (no step spawns, no delivery is routed, no review starts, no land is armed) and escalates nothing. Its step deadline, backstop and land wait stand still and continue with the time they had left on unpause. A delivery made while paused is routed on unpause. relay_workflow_get shows `paused` {by, at, reason}; you get a notice on pause and unpause, and your next context generation lists your team's paused runs. Cancel still ends a paused run.
 
 ## relay_workflow_start
 

package/docs/guides/tools-tasks.md

@@ -76,6 +76,8 @@ Confirm a #1456 carry-pending Task: assert the delivered change discarded by a m
 
 ## relay_task_create
 
+`onDeploy` is an optional follow-up of up to 500 characters. It appears under the Task in the deploy notice. Set it through MCP/HTTP create or `humwick task create --title TEXT --intent TEXT --on-deploy TEXT`.
+
 Create a durable deliverable Task (#834). Owns execution telemetry (status, stage, gates, branch, commits, deps); references GitHub issue(s) for intent/spec. Optionally seed issue refs and dependencies. Returns id, status, issue refs and review-hold state; pass verbose:true for the full Task.
 
 - `label`: alias for title; concise task label
@@ -86,6 +88,7 @@ Create a durable deliverable Task (#834). Owns execution telemetry (status, stag
 - `doneWhen`: exit predicate / acceptance for execution
 - `repo`: owner/repo for the task's project/repository
 - `branch`: optional branch ref to seed on the task
+- `paths`: repo-relative files or folders the Task touches; a project spawn policy's `taskPaths` matches them (#3736)
 - `issueRefs`: Issue(s) this Task delivers or references (see relation): #n, owner/repo#n, GitHub URL, or issue_<id>. Linked issues are hydrated into a task-bound spawn's first-turn brief, so pass the ref instead of pasting the spec. Aliases accepted: refs, issues, issue, issueRef, externalKey, issueNumber. A bare #n resolves against defaultRepo, else the Task's repo, else your own project's repo.
 - `relation`: Issue relation: delivers authorizes auto-close at land; references only links/hydrates the spec. Omitted relations resolve from the current Task type at land: delivers for build/ui/refactor/debug/mechanical (or an omitted type with a build-like bound profile), references for research/design (use research), review and ops. Unset type derives from the bound profile: software-design, reviewer, isolated-research and ops-assistant reference; other profiles default to build. Inferred refs always store references. Applies to every issue in this call; re-add with a relation to change it, or omit relation to preserve an existing explicit one.
 - `defaultRepo`: owner/repo for bare #n issue refs
@@ -138,6 +141,8 @@ List a Task's append-only event timeline (status, stage, gate, dependency, ref,
 
 ## relay_task_list
 
+Use `{teamId, deliverableStage:"awaiting-deploy", mine:false}` for the team's landed or deploying Tasks that have not reached deployed. Results include each Task's optional `onDeploy` follow-up.
+
 List Task awareness rows, optionally filtered by execution status, deliverable stage, team, project, or repo. `brief` is id/label/status only; the default lean rows omit paragraph titles and raw timestamps; `full`/verbose:true preserve the complete legacy summary shape. Defaults to your own Tasks (created by you, assigned to you, or owned by a coordinator role you hold); pass `mine:false` for every Task. `inFlight:true` drops done/canceled rows. Lean/brief rows page within the list budget, blocked/validating Tasks first.
 
 - `mine`: Default true: only the caller's own Tasks. false lists every Task.
@@ -222,10 +227,13 @@ Coordinator-only: add/update a Task validation item by stable id. open waits for
 
 ## relay_task_update
 
+Set `onDeploy` to replace the follow-up; an empty string clears it. CLI: `humwick task update T123 --on-deploy TEXT`. The Task drawer also shows and edits this field.
+
 Update a deliverable Task's editable fields (title/label, intent, complexity, context, latest steer, doneWhen, dispatch, team, project/repo).
 
 - `taskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
 - `terminalStage`: null clears the override and restores the repo default.
+- `paths`: replaces the Task's repo-relative paths; `[]` clears them.
 
 ## relay_task_withdraw_land
 

package/docs/guides/workflows.md

@@ -183,6 +183,64 @@ Uncommitted edits and changes on a feature branch do not change the workflow tha
 reviews that branch. The run records the source and commit it used. A running run
 keeps its resolved definition; start a new run to pick up a later definition.
 
+## Limit who a project's agents can spawn
+
+Commit `.agent-relay/spawn-policy.json` to make your project's rules enforced, not
+just written down. Humwick reads it from the default branch, like workflows and
+roles, and checks it on every spawn into the project. This includes spawns made
+directly, through Task dispatch, from the dashboard, by workflow steps and by
+sub-coordinators. This example says that a coordinator or sub-coordinator spawns
+only a project role or the `QA` profile. It also says that a Task touching
+`src/manuscripts/love-exe/` runs only through the `story-build-review` workflow:
+
+```json
+{
+  "version": 1,
+  "rules": [
+    {
+      "name": "love-exe-story",
+      "when": { "taskPaths": ["src/manuscripts/love-exe/**"] },
+      "require": { "workflow": "story-build-review" },
+      "hint": "love-exe chapters run only through story-build-review: spawn with the taskId and Humwick starts it."
+    },
+    {
+      "name": "project-roles",
+      "when": { "spawner": ["coordinator", "sub-coordinator"] },
+      "require": { "roles": ["writer", "editor", "builder", "reviewer"], "profiles": ["QA"] },
+      "hint": "Spawn a role from .agent-relay/roles, or the QA profile."
+    }
+  ]
+}
+```
+
+A rule applies when every `when` condition holds. A condition holds when any one of
+its listed values matches. A rule without `when` applies to every spawn.
+
+| Condition | Matches |
+| --- | --- |
+| `taskTags` | the spawn's Task has one of these tags |
+| `taskPaths` | one of the Task's `paths` matches a glob; `dir/**` also matches `dir` |
+| `spawner` | `coordinator` (any agent spawning directly), `sub-coordinator`, `workflow` (a run's step) or `operator` (the dashboard or a person) |
+
+Set a Task's `paths` (repo-relative files or folders) with `relay_task_create` or
+`relay_task_update`. Each rule has a `hint` and either `deny: true` or a `require`:
+
+- `roles` and `profiles` list what the spawn may name. A role spawn must name a
+  listed role; a profile spawn must name a listed profile. Names match without
+  regard to case, and by canonical profile name: the retired `default-relay` is
+  `worker`, and a spawn that names no profile gets `worker`. So a list with
+  `worker` admits `default-relay` and an omitted profile, and a list without
+  `worker` refuses both (the refusal says `profile worker`). Listing `default-relay`
+  is the same as listing `worker`.
+- `workflow` sends the Task's work through that workflow. Spawning for the Task
+  starts it, whatever the Task's type, and only that run's steps may spawn for it.
+  Passing `workflow:false` is refused.
+
+A refused spawn fails before anything launches. The error names the rule, what it
+allows and the hint. A spawn receipt lists the rules that applied in `spawnPolicy`.
+A project without the file is not limited. If the file is invalid or cannot be
+read, Humwick logs one warning with the reason and limits nothing until it is fixed.
+
 ## Resume work that needs a decision
 
 An `escalated` run is waiting for its coordinator to resolve the reported cause.

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Humwick API",
-    "version": "0.130.1",
+    "version": "0.130.2",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",
@@ -8335,6 +8335,45 @@
         ]
       }
     },
+    "/api/agent-profiles/{name}/project-instructions": {
+      "get": {
+        "operationId": "projectProfileInstructionsRoute",
+        "summary": "List all projects and their additions for one profile",
+        "tags": [
+          "Agent profiles"
+        ],
+        "description": "Project additions follow the global profile charter. Unset text is empty at version 0 and adds no context tokens. Profile aliases resolve to their canonical profile. Reads require agent:read; writes require agent:write. Actors come from the authenticated credential.",
+        "parameters": [
+          {
+            "name": "name",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
     "/api/agent-profiles/tool-groups": {
       "get": {
         "operationId": "getAgentProfileToolGroupsRoute",
@@ -16437,6 +16476,281 @@
         ]
       }
     },
+    "/api/projects/{id}/profile-instructions": {
+      "get": {
+        "operationId": "projectProfileInstructionsRoute",
+        "summary": "List all profile additions for one project",
+        "tags": [
+          "Agent profiles"
+        ],
+        "description": "Project additions follow the global profile charter. Unset text is empty at version 0 and adds no context tokens. Profile aliases resolve to their canonical profile. Reads require agent:read; writes require agent:write. Actors come from the authenticated credential.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
+    "/api/projects/{id}/profile-instructions/{profile}": {
+      "get": {
+        "operationId": "projectProfileInstructionsRoute",
+        "summary": "Read a project profile instruction addition",
+        "tags": [
+          "Agent profiles"
+        ],
+        "description": "Project additions follow the global profile charter. Unset text is empty at version 0 and adds no context tokens. Profile aliases resolve to their canonical profile. Reads require agent:read; writes require agent:write. Actors come from the authenticated credential.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "profile",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      },
+      "put": {
+        "operationId": "projectProfileInstructionsRoute",
+        "summary": "Set project profile instructions with optimistic version checking",
+        "tags": [
+          "Agent profiles"
+        ],
+        "description": "Project additions follow the global profile charter. Unset text is empty at version 0 and adds no context tokens. Profile aliases resolve to their canonical profile. Reads require agent:read; writes require agent:write. Actors come from the authenticated credential.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "profile",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "expectedVersion",
+                  "template"
+                ],
+                "properties": {
+                  "expectedVersion": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "reason": {
+                    "type": "string",
+                    "maxLength": 2000
+                  },
+                  "template": {
+                    "type": "string",
+                    "maxLength": 16000
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "409": {
+            "description": "Stale expectedVersion. current contains the current version and template."
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
+    "/api/projects/{id}/profile-instructions/{profile}/history": {
+      "get": {
+        "operationId": "projectProfileInstructionsRoute",
+        "summary": "Read audited project profile instruction revisions for history and diff",
+        "tags": [
+          "Agent profiles"
+        ],
+        "description": "Project additions follow the global profile charter. Unset text is empty at version 0 and adds no context tokens. Profile aliases resolve to their canonical profile. Reads require agent:read; writes require agent:write. Actors come from the authenticated credential.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "profile",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
+    "/api/projects/{id}/profile-instructions/{profile}/restore": {
+      "post": {
+        "operationId": "projectProfileInstructionsRoute",
+        "summary": "Restore a project profile instruction revision as a new head",
+        "tags": [
+          "Agent profiles"
+        ],
+        "description": "Project additions follow the global profile charter. Unset text is empty at version 0 and adds no context tokens. Profile aliases resolve to their canonical profile. Reads require agent:read; writes require agent:write. Actors come from the authenticated credential.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "profile",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "expectedVersion",
+                  "version"
+                ],
+                "properties": {
+                  "expectedVersion": {
+                    "type": "integer",
+                    "minimum": 0
+                  },
+                  "reason": {
+                    "type": "string",
+                    "maxLength": 2000
+                  },
+                  "version": {
+                    "type": "integer",
+                    "minimum": 1
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "409": {
+            "description": "Stale expectedVersion. current contains the current version and template."
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
     "/api/projects/{id}/checkouts/bind": {
       "post": {
         "operationId": "postProjectBindCheckoutRoute",
@@ -18122,6 +18436,105 @@
         ]
       }
     },
+    "/api/workflows/runs/{runId}/pause": {
+      "post": {
+        "operationId": "postWorkflowRunPauseRoute",
+        "summary": "Pause a workflow run",
+        "tags": [
+          "Other"
+        ],
+        "description": "As relay_workflow_resume with pause:true (#3757): pauses a running run at its next seam. A working step agent is not interrupted; the run spawns no step, routes no delivery, starts no review, arms no land and escalates nothing until unpaused, and its deadlines stand still. `reason` is required (400 without it). A run that is not running refuses (400). Returns the run as GET /api/workflows/runs/:runId shows it, with `paused` {by, at, reason}. Coordinator-only: the run's caller, the Task's coordinators and admins. Requires task:write.",
+        "parameters": [
+          {
+            "name": "runId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "reason"
+                ],
+                "properties": {
+                  "reason": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 2000
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
+    "/api/workflows/runs/{runId}/unpause": {
+      "post": {
+        "operationId": "postWorkflowRunUnpauseRoute",
+        "summary": "Unpause a workflow run",
+        "tags": [
+          "Other"
+        ],
+        "description": "As relay_workflow_resume with pause:false (#3757): unpauses a paused run. Its step deadline, backstop and land wait move by the time it was paused, and a delivery recorded meanwhile is routed. A run that is not paused refuses (400). Returns the run as GET /api/workflows/runs/:runId shows it. Coordinator-only: the run's caller, the Task's coordinators and admins. Requires task:write.",
+        "parameters": [
+          {
+            "name": "runId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {}
+            }
+          }
+        },
+        "security": [
+          {
+            "bearerAuth": []
+          },
+          {
+            "tokenHeader": []
+          },
+          {
+            "tokenQuery": []
+          }
+        ]
+      }
+    },
     "/api/workflows/runs/{runId}/resume": {
       "post": {
         "operationId": "postWorkflowRunResumeRoute",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humwick/server",
-  "version": "0.130.1",
+  "version": "0.130.2",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -84,21 +84,16 @@
   ],
   "dependencies": {
     "age-encryption": "0.3.1",
-    "@humwick/channels-host": "0.130.1",
-    "@humwick/kernel": "0.0.0",
-    "@humwick/offload": "0.0.0",
-    "@humwick/providers": "0.104.7",
-    "@humwick/sdk": "0.2.136",
+    "@humwick/channels-host": "0.130.2",
+    "@humwick/kernel": "0.130.2",
+    "@humwick/offload": "0.130.2",
+    "@humwick/providers": "0.104.8",
+    "@humwick/sdk": "0.2.137",
     "ajv": "^8.20.0",
     "@modelcontextprotocol/sdk": "1.32.0",
     "express": "^5.2.1",
     "busboy": "^1.6.0",
-    "unbash": "6.0.0",
-    "@hono/zod-openapi": "^1.4.0",
-    "hono": "^4.12.0",
-    "zod": "^4.4.3",
-    "jsep": "^1.4.0",
-    "p-queue": "^9.3.3"
+    "unbash": "6.0.0"
   },
   "scripts": {
     "public:gate": "bun run scripts/public-gate.ts",
@@ -223,9 +218,5 @@
   },
   "engines": {
     "bun": ">=1.4.4"
-  },
-  "bundleDependencies": [
-    "@humwick/kernel",
-    "@humwick/offload"
-  ]
+  }
 }