@allocator-one/harness-cli 1.14.0 → 1.15.0

package/dist/{server-75QJASTY.js → server-O7CX2ZCC.js}

@@ -4,20 +4,27 @@ import {
   CLI_VERSION,
   CONDITION_KINDS,
   Client,
+  GATE_OWNER_ROLES,
   HttpError,
   IDEMPOTENCY_KEY_FORMAT,
+  JOBS_MAX_LIMIT,
+  JOB_STATES,
+  JOB_STATUS_ALIASES,
   MAX_IDEMPOTENCY_KEY_BYTES,
   PLAN_EXECUTORS,
   RELATION_CREATE_TYPES,
   RELATION_UPDATE_TYPES,
+  STEER_MAX_CHARACTERS,
   TransportError,
   UsageError,
   activity,
   archive,
+  assignments,
   blocked,
   close,
   comment,
   comments,
+  conditionList,
   create,
   deleteComment,
   dep,
@@ -27,7 +34,14 @@ import {
   docUpdate,
   editComment,
   errorDetails,
+  explainExpertRefusal,
   gateSet,
+  jobCancel,
+  jobContinue,
+  jobPause,
+  jobShow,
+  jobSteer,
+  jobsList,
   labelCreate,
   labelDelete,
   labelList,
@@ -47,6 +61,9 @@ import {
   planHold,
   planRelease,
   planShow,
+  procedureRun,
+  procedureSave,
+  procedureShow,
   projectCreate,
   projectList,
   projectShow,
@@ -59,6 +76,7 @@ import {
   resolveConfig,
   search,
   show,
+  skillsList,
   stateAdd,
   stateDelete,
   stateOrder,
@@ -68,11 +86,13 @@ import {
   teamList,
   teamRename,
   teamSetDefault,
+  toolsList,
+  toolsSearch,
   update,
   upload,
   userList,
   workflowStates
-} from "./chunk-F2YVTB2A.js";
+} from "./chunk-I2S2JVCQ.js";
 
 // src/mcp/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -95,8 +115,11 @@ function toolError(message) {
   return { content: [{ type: "text", text: message }], isError: true };
 }
 async function run(work) {
+  let token = "";
   try {
-    const output = await work(context());
+    const ctx = context();
+    token = ctx.config.token;
+    const output = await work(ctx);
     const content = [{ type: "text", text: JSON.stringify(output.json) }];
     if (output.notice !== void 0 && output.notice !== "") {
       content.push({ type: "text", text: output.notice.trimEnd() });
@@ -106,7 +129,8 @@ async function run(work) {
       return { content, isError: true };
     }
     return { content };
-  } catch (error) {
+  } catch (caught) {
+    const error = explainExpertRefusal(caught, token);
     if (error instanceof NeedsLoginError) return toolError(error.message);
     if (error instanceof HttpError) {
       return toolError(`${error.message} (HTTP ${error.status})${errorDetails(error.body)}`);
@@ -125,9 +149,14 @@ var identifier = z.string().describe("issue identifier, e.g. IO-123");
 var commentId = z.string().uuid().describe("comment UUID from issue_show or comment_list");
 var dateField = z.string().optional().describe('YYYY-MM-DD; "" clears the date');
 var planCondition = z.object({
-  kind: z.enum(CONDITION_KINDS),
+  kind: z.enum(CONDITION_KINDS).optional().describe("not_before, gate or event; optional with gate"),
   not_before: z.string().optional().describe("not_before: an ISO 8601 UTC instant"),
-  label: z.string().optional().describe("gate: what a person ticks, e.g. Finance sign-off"),
+  gate: z.string().optional().describe("shorthand for kind gate with this key; the label defaults to it, e.g. finance-sign-off"),
+  key: z.string().optional().describe("gate: a stable lowercase slug (a-z, 0-9 and -), unique among the step's gates; gate_set takes it"),
+  label: z.string().optional().describe("gate: what a person ticks, e.g. Finance sign-off; defaults to the key"),
+  owner: z.string().nullable().optional().describe(
+    `gate: who ticks it. role:<role> (${GATE_OWNER_ROLES.join(", ")}), user:<id or email> (a member who can use Operator) or expert:<email> (an outside expert, never a member's email). Only the owner ticks an owned gate, and nobody names an owner they would hold themselves (owner_is_actor). null or absent: no owner`
+  ),
   event: z.string().optional().describe("event: deal_stage_changed, opportunity_stage_changed, form_submitted or investment_executed"),
   subject_id: z.string().optional().describe("event: the record the event is about (one you can read)"),
   target_id: z.string().optional().describe("event: the stage or status a stage change must reach")
@@ -168,6 +197,125 @@ var planStepEdit = z.object({
   key: z.string().nullable().optional().describe("the step's new key")
 }).passthrough();
 var idempotencyKey = z.string().min(1).max(MAX_IDEMPOTENCY_KEY_BYTES).regex(IDEMPOTENCY_KEY_FORMAT, "must use printable ASCII without leading or trailing spaces");
+var OPERATOR_APPROVAL_NOTE = "Approval happens in the app: give a person the approval_url (pending_approval.url on job_show); no tool approves a change set. By reference only, never the objective's text.";
+var OPERATOR_JOB_TOOLS = [
+  {
+    name: "jobs_list",
+    description: "List the Operator jobs the caller sees in the workbench, newest first: state, waiting_on (approval, person, reconciliation, verification or delivery), objective_kind, owner, plan step, window, and the workbench url and approval_url. " + OPERATOR_APPROVAL_NOTE + " Pages by cursor; all follows every page, and a second text item says when older jobs exist.",
+    readOnly: true,
+    shape: {
+      status: z.array(z.enum([...JOB_STATES, ...JOB_STATUS_ALIASES])).min(1).optional().describe("job states, or the aliases open (not done), waiting and done"),
+      mine: z.boolean().optional().describe("only jobs the caller owns"),
+      limit: z.number().int().min(1).max(JOBS_MAX_LIMIT).optional().describe("jobs per page (default 20)"),
+      all: z.boolean().optional().describe("follow every page")
+    },
+    handler: (ctx, args) => jobsList(ctx, {
+      status: args["status"] === void 0 ? void 0 : args["status"].join(","),
+      mine: args["mine"],
+      limit: args["limit"],
+      all: args["all"]
+    })
+  },
+  {
+    name: "job_show",
+    description: "One Operator job by reference: state and waiting_on, plan version, progress (stage, situation, needs_viewer), window (remaining and budget, in ms), spend in cents, blockers, pending_approval with its url, grant, verification status, effect counts, artifact links, pinned skill identity, people, saved procedures and viewer_can. " + OPERATOR_APPROVAL_NOTE + " Poll it to follow a job: it has ended when state is completed, failed or cancelled, and a person has to act exactly when waiting_on is set; a job paused with no waiting_on resumes by itself.",
+    readOnly: true,
+    shape: { id: z.string().uuid().describe("Operator job UUID, from jobs_list") },
+    handler: (ctx, args) => jobShow(ctx, args["id"])
+  }
+];
+var OPERATOR_CONTROL_NOTE = "Not idempotent: never retry it on your own; when an error says the outcome is unknown (a timeout, a dropped connection or a 5xx), read the job with job_show before trying again. Approving stays in the app: no tool approves a change set. Returns the job as job_show does, by reference only.";
+var jobId = z.string().uuid().describe("Operator job UUID, from jobs_list");
+var OPERATOR_CONTROL_TOOLS = [
+  {
+    name: "job_steer",
+    description: "Steer an Operator job as Steer does in the app: posts the instruction in the job's room, attributed to the caller. The job's owner and collaborators may steer, wherever the app offers it (not a finished, failed or awaiting-approval job). Work the instruction changes needs a fresh approval: earlier approvals stop applying to it. Steering a running job stops its current run so it can take the instruction. " + OPERATOR_CONTROL_NOTE,
+    readOnly: false,
+    idempotent: false,
+    shape: {
+      id: jobId,
+      instruction: z.string().min(1).describe(
+        `what to change, in plain language: 1 to ${STEER_MAX_CHARACTERS} characters once trimmed`
+      )
+    },
+    handler: (ctx, args) => jobSteer(ctx, args["id"], args["instruction"])
+  },
+  {
+    name: "job_cancel",
+    description: "Cancel an Operator job as Cancel does in the app; only the job's execution principal may. It cannot be undone, but committed effects stay committed: the job's effects still count them, and staged ones that never ran count as unknown. " + OPERATOR_CONTROL_NOTE,
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
+    shape: { id: jobId },
+    handler: (ctx, args) => jobCancel(ctx, args["id"])
+  },
+  {
+    name: "job_pause",
+    description: "Pause a running Operator job as Pause does in the app; only the job's execution principal may. Holds it for a person without resetting its active-time budget; continuing it runs it again. " + OPERATOR_CONTROL_NOTE,
+    readOnly: false,
+    idempotent: false,
+    shape: { id: jobId },
+    handler: (ctx, args) => jobPause(ctx, args["id"])
+  }
+];
+var NOT_IDEMPOTENT = 'Not idempotent: never retry it automatically, not after a timeout or a 5xx either. An "Outcome unknown" error may have landed and says what to check before calling again; only "cannot reach the API" means the request never reached the server, so nothing changed.';
+var OPERATOR_LIFECYCLE_TOOLS = [
+  {
+    name: "job_continue",
+    description: "Continue an Operator job, as Continue does in the app: opens a new audited window for a job that ran out of time or waits on a person, or retries a failed run or verification. Only the job's execution principal may. Returns the job as job_show does. Approval still happens in the app, at its approval_url. " + NOT_IDEMPOTENT,
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    shape: { id: z.string().uuid().describe("Operator job UUID, from jobs_list") },
+    handler: (ctx, args) => jobContinue(ctx, args["id"])
+  },
+  {
+    name: "job_changes",
+    description: "An Operator job's latest change set by reference: its manifest id, version, status, digest, plan version, maximum effect count, and each action's type, version, order, effect count, required capability ids and digest; never values or targets. change_set is null while the job has proposed nothing. Beside it, the job's state, waiting_on, workbench url and approval_url: review and approve in the app, at that link.",
+    readOnly: true,
+    shape: { id: z.string().uuid().describe("Operator job UUID, from jobs_list") },
+    handler: (ctx, args) => jobShow(ctx, args["id"], { changes: true })
+  },
+  {
+    name: "procedure_save",
+    description: "Save a completed Operator job whose work was verified as a versioned procedure, as Save procedure does in the app. Only the job's owner can. Returns the procedure as procedure_show does, or only its id and url when it can't be read back. Saving again saves another procedure. " + NOT_IDEMPOTENT,
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    shape: {
+      job_id: z.string().uuid().describe("Operator job UUID, from jobs_list"),
+      name: z.string().trim().min(1).describe("the procedure's name; trimmed and cut to 200 characters")
+    },
+    handler: (ctx, args) => procedureSave(ctx, args["job_id"], args["name"])
+  },
+  {
+    name: "procedure_show",
+    description: "One saved Operator procedure: its name, source job_id and job_url (the app), current_version, each version's recipe_digest, capability_ids and action_roster, and the parameter_schema a run of the current version takes (scoped_inputs.required naming contact_reconciliation means a run needs group_id and source_resource_id). Never a version's recipe or anything the saved job read.",
+    readOnly: true,
+    shape: { id: z.string().uuid().describe("Operator procedure UUID, from job_show's procedures") },
+    handler: (ctx, args) => procedureShow(ctx, args["id"])
+  },
+  {
+    name: "procedure_run",
+    description: "Run a saved Operator procedure as a new job, as Rerun does in the app: fresh inputs, the caller's own current rights, and a change set that needs its own approval in the app. Nothing of the saved job carries over. Returns the new job as job_show does, or only its id and url when it can't be read back; give a person its approval_url. " + NOT_IDEMPOTENT,
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    shape: {
+      id: z.string().uuid().describe("Operator procedure UUID"),
+      version: z.number().int().min(1).optional().describe("the version expected to be current; the run is refused if it no longer is (default: the current one)"),
+      parameters: z.record(z.unknown()).optional().describe("values for the procedure's parameter_schema (procedure_show), default {}"),
+      group_id: z.string().min(1).optional().describe("the contact group to reconcile, when scoped_inputs require it"),
+      source_resource_id: z.string().min(1).optional().describe("the uploaded file to reconcile against, when scoped_inputs require it")
+    },
+    handler: (ctx, args) => procedureRun(ctx, args["id"], {
+      version: args["version"],
+      parameters: args["parameters"],
+      group: args["group_id"],
+      source: args["source_resource_id"]
+    })
+  }
+];
 var TOOLS = [
   // ── Issues ──
   {
@@ -222,7 +370,7 @@ var TOOLS = [
   },
   {
     name: "activity_list",
-    description: "Mixed issue activity: comments, creation, state and assignee changes. Returns the newest page unless all=true.",
+    description: "Mixed issue activity: comments, creation, state and assignee changes, wait-condition events, and field changes (priority, labels, parent, title, description, archived) with from/to values. actor_label, when set, is the agent or CLI label a write was made under. Returns the newest page unless all=true.",
     readOnly: true,
     shape: {
       id: identifier,
@@ -723,7 +871,7 @@ var TOOLS = [
   // ── Plans and gates ──
   {
     name: "plan_create",
-    description: "Create a plan: a root issue and up to 99 steps, created in one transaction or not at all, and held until a person releases it (plan_release). Steps refer to each other by key: parent (containment) and blocked_by (dependencies). executor operator files a step in the organization's Operator team, where only the plan driver claims it; a person's step goes to its team (or the plan's). conditions are wait conditions (not_before, gate, event). An invalid plan writes nothing and the error lists every violation by step key. Reuse idempotency_key when retrying.",
+    description: "Create a plan: a root issue and up to 99 steps, created in one transaction or not at all, and held until a person releases it (plan_release). Steps refer to each other by key: parent (containment) and blocked_by (dependencies). executor operator files a step in the organization's Operator team, where only the plan driver claims it; a person's step goes to its team (or the plan's). conditions are wait conditions (not_before, gate, event); a gate may carry a key (gate: <key> is shorthand) and an owner, who alone ticks it. An invalid plan writes nothing and the error lists every violation by step key. Reuse idempotency_key when retrying.",
     readOnly: false,
     shape: {
       team: z.string().optional().describe("team key for the root and people's steps; defaults to HARNESS_TEAM"),
@@ -734,7 +882,7 @@ var TOOLS = [
   },
   {
     name: "plan_show",
-    description: "A plan's status, budgets, current revision and spend estimate, and its whole tree root first: each step's key, executor, parent, state, ready flag, held flag (edited since release), in_revision and wait conditions, plus the blocks edges between steps.",
+    description: "A plan's status, budgets, current revision and spend estimate, and its whole tree root first: each step's key, executor, parent, state, ready flag, held flag (edited since release), in_revision, wait conditions (a gate's key and owner) and waiting_for (each open gate's owner and holders, the people who can tick it: [] when nobody can, null when unowned or not known), plus the blocks edges between steps.",
     readOnly: true,
     shape: { id: planId },
     handler: (ctx, args) => planShow(ctx, args["id"])
@@ -779,15 +927,35 @@ var TOOLS = [
   },
   {
     name: "gate_set",
-    description: "Satisfy (satisfied true) or un-satisfy (false) a gate wait condition on an issue, found by its label or condition id (issue_show lists conditions). Needs staff standing in the organization.",
+    description: "Satisfy (satisfied true) or un-satisfy (false) a gate wait condition on an issue, found by its key, label or condition id (condition_list and issue_show list conditions). Needs staff standing in the organization or a place in its plan's room; only an owned gate's owner ticks it, and its owner or staff untick it. Anyone else gets a 403 naming the owner. An outside expert's pxc_ credential ticks the gates it owns on a step assigned to it (assignment_list); any other step is 404.",
     readOnly: false,
     shape: {
       issue: identifier,
-      gate: z.string().describe("the gate's label, or its condition id"),
+      gate: z.string().describe("the gate's key, its label, or its condition id"),
       satisfied: z.boolean()
     },
     handler: (ctx, args) => gateSet(ctx, args["issue"], args["gate"], args["satisfied"])
   },
+  {
+    name: "condition_list",
+    description: "An issue's wait conditions (not_before, gate, event), oldest first: each one's id, kind, a gate's key, label and owner, and whether, when and by whom it was satisfied. gate_set ticks a gate. With an outside expert's pxc_ credential: only the gates it owns on a step assigned to it, in the expert view (owner as {kind, role}, satisfied_by as {kind: you|role|expert|member}); any other step is 404.",
+    readOnly: true,
+    shape: { issue: identifier },
+    handler: (ctx, args) => conditionList(ctx, args["issue"])
+  },
+  {
+    name: "assignment_list",
+    description: "An outside expert's own assignments, for their pxc_ credential: expert ({id, role}), plan ({id, status} or null), and assignments, each step assigned to them with its identifier, title, state, due_date, description (null when Operator runs the step), open_blockers (a count) and the gates on it they own. gate_set ticks one. A pxc_ credential reaches only this, condition_list and gate_set: every other tool is refused as expert_bound_credential. Any other credential is refused as expert_credential_required.",
+    readOnly: true,
+    shape: {},
+    handler: (ctx) => assignments(ctx)
+  },
+  // ── Operator jobs (CLI-43) ──
+  ...OPERATOR_JOB_TOOLS,
+  // ── Operator job controls (CLI-46) ──
+  ...OPERATOR_CONTROL_TOOLS,
+  // ── Operator job lifecycle (CLI-47) ──
+  ...OPERATOR_LIFECYCLE_TOOLS,
   // ── Uploads ──
   {
     name: "upload",
@@ -795,25 +963,52 @@ var TOOLS = [
     readOnly: false,
     shape: { path: z.string().describe("local file path") },
     handler: (ctx, args) => upload(ctx, args["path"])
+  },
+  // ── Operator's catalog (CLI-44) ──
+  {
+    name: "tools_search",
+    description: "Browse or search what Operator can use now in this organization: only capabilities that are switched on appear. Without query, the index in id order (25 a page); with query, a keyword search ranked by score (15 a page). domain narrows either to one domain. Each capability carries its domain, summary, description, mode, effect and kind: read, write, or send (a write delivered beyond the platform). Write and send capabilities, and any proposal, always need a person's approval in the app before they take effect; nothing here runs or approves anything. A page that isn't the last comes with a notice naming the next cursor; all=true follows every page.",
+    readOnly: true,
+    shape: {
+      query: z.string().optional().describe("search terms, at most 200 bytes; omit to browse the index"),
+      domain: z.string().optional().describe("only this capability domain, e.g. crm"),
+      cursor: z.string().optional().describe("the next page's cursor, from the previous call's notice"),
+      all: z.boolean().optional().describe("follow every page")
+    },
+    handler: (ctx, args) => {
+      const opts = { domain: args["domain"], cursor: args["cursor"], all: args["all"] };
+      return args["query"] === void 0 ? toolsList(ctx, opts) : toolsSearch(ctx, args["query"], opts);
+    }
+  },
+  {
+    name: "skills_list",
+    description: "The organization's skills assigned to Operator, in title order: each skill's id, title, invocation_name and content_sha256. A skill's content and description are never exposed.",
+    readOnly: true,
+    shape: {},
+    handler: (ctx) => skillsList(ctx)
   }
 ];
-function buildServer() {
-  const server = new McpServer({ name: "harness", version: CLI_VERSION });
+function buildServer(name = "harness") {
+  const server = new McpServer({ name, version: CLI_VERSION });
   for (const tool of TOOLS) {
     server.registerTool(
       tool.name,
       {
         description: tool.description,
         inputSchema: tool.shape,
-        annotations: { readOnlyHint: tool.readOnly }
+        annotations: {
+          readOnlyHint: tool.readOnly,
+          ...tool.destructive === void 0 ? {} : { destructiveHint: tool.destructive },
+          ...tool.idempotent === void 0 ? {} : { idempotentHint: tool.idempotent }
+        }
       },
       ((args) => run((ctx) => tool.handler(ctx, args)))
     );
   }
   return server;
 }
-async function startMcpServer() {
-  const server = buildServer();
+async function startMcpServer(name = "harness") {
+  const server = buildServer(name);
   await server.connect(new StdioServerTransport());
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allocator-one/harness-cli",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "CLI and MCP server for Harness, allocator.one's issue tracker",
   "type": "module",
   "license": "MIT",
@@ -26,6 +26,7 @@
     "typecheck": "tsc --noEmit",
     "pretest": "npm run build",
     "test": "vitest run",
+    "package:operator": "node scripts/operator-package.mjs ./build/operator",
     "codegen": "openapi-typescript spec/openapi.json -o src/generated/api.ts",
     "spec:refresh": "node scripts/spec-refresh.mjs",
     "prepublishOnly": "npm run build"