@mutagent/cli 0.2.130 → 0.2.132

package/dist/bin/cli.js

@@ -22060,12 +22060,13 @@ In a cloud sandbox launched for a Factory entry, the platform sets these:
 | \`MUTAGENT_SESSION_ID\` | this session's id (\`hs1_…\`) | every \`--session\`, e.g. \`mutagent traces get\` |
 | \`MUTAGENT_SUBJECT_ID\` | the Factory entry the session is bound to | every entry \`<id>\` and \`--subject\` |
 | \`MUTAGENT_STAGE_RUN_ID\` | the stage run the platform opened for this session | \`factory stage finish\`, \`factory stage show\` |
-| \`MUTAGENT_RUN_ID\` | the gateway run, when a gateway routine started the session | \`reports push --run-id\` |
+| \`MUTAGENT_RUN_ID\` | the gateway run, when a gateway routine started the session | nothing: no command reads it |
 
 So in a sandbox you write \`mutagent factory stage finish --state succeeded --json\`
 with no run id, and \`mutagent reports push <run-dir> --json\` with no
 \`--stage-run\`: the server attaches the report to the session's open run, with its
-entry, spec version and build (the checkout's HEAD).
+entry, spec version and build (the checkout's HEAD). A report's run id comes from
+\`--run-id\`, else the report's own render input (its \`runId\`).
 
 Locally none of this exists: pass the entry id, the run id and the build
 (\`--build-target\`, \`--build-rev\`) explicitly. A command that needs one and gets
@@ -22075,7 +22076,10 @@ none fails with \`MISSING_ARGUMENTS\`; it never guesses.
 
 A sandbox session works on one entry. A session launched with
 \`mutagent helix agent … --subject <id> --stage <stage>\` is bound to that entry from
-the start. A session started without one binds on its first Factory write (for
+the start, with the stage run open. One launched with \`--subject <id>\` and no stage
+(an entry session, as the web's "Run in Helix" starts) is bound with no run open: it
+opens the run itself when it starts a stage (see
+[workflows/factory-stages.md](../workflows/factory-stages.md)). A session started without one binds on its first Factory write (for
 example \`mutagent factory add\`). A write to any other entry is refused with
 \`SANDBOX_SCOPE\`, which names the scope and the bound entry; the only exception is
 an entry whose repository matches the sandbox's checkout.
@@ -22092,6 +22096,10 @@ refuses it (\`SANDBOX_CANNOT_LAUNCH\`); a person starts one from a terminal, Des
 When a sandbox session ends, the platform checks its work: specs in sync, stage
 runs finished, reports pushed. If something is missing, the session is woken with
 the list and continues. Finish your runs and push your reports before you stop.
+
+Code changes travel the same way:
+the platform opens the PR with this session's changes when the session ends;
+don't push or open PRs yourself.
 `,
   "workflows/agent-deployment.md": "# Managed agents: check, deploy and run an agent.md folder\n\nUse this journey when the user has an agent folder whose entry file is a\nlowercase `agent.md` (YAML frontmatter, then the standing prompt), optionally\nwith TypeScript tools, skill folders and files. Read `mutagent agent --help` and\nthe leaf's help before the first use; help owns the flags and the JSON shapes.\nThe CLI compiles the tools and packages the folder. Do not write registration\nglue or forward a path on this machine to the server.\n\nThe format, in one paragraph: `name` (the slug), `description`, `model`\n(`provider/model`, as `mutagent helix models` lists it), `thinking`, `tools`,\n`disallowed_tools` and `skills` are the local brief. Deployment settings sit in\none optional `harness:` block: `tools.builtin`, `tools.modules`, `skills`,\n`files`, `bindings.secrets`, `runtime.mode` (`interactive` or `headless`) and\n`runtime.scaffold` (`standard`). A deployed agent gets exactly the tools and\nskills `harness:` declares. `apiVersion`, `kind` and `metadata` are refused.\n\n1. **Check.** `mutagent agent check <agent.md> --json`. No network, no model call,\n   no tool code runs. Fix every diagnostic before going further.\n2. **Run locally, when the user wants to try it.**\n   `mutagent agent run <agent.md> \"<task>\" --json` runs the task with the local\n   Helix binary and this machine's LLM provider key. It is not isolated and\n   creates nothing in the workspace. It takes a file; a slug is refused.\n3. **Deploy.** `mutagent agent deploy <agent.md> [--env <name>] --json`. `--env`\n   names the slot (the agent in that Environment); without it the default slot\n   is used. One server-side operation validates and stores the package as the\n   next revision and activates it. The server refuses, before writing anything:\n   a model outside the workspace model list, an Environment the workspace lacks,\n   a required secret binding, an inline agent that already has the slug, and a\n   server with no sandbox provider that can stage a package. Report the message\n   as the server words it. Show `_directive.renderedCard` verbatim.\n   `--no-activate` stores the revision and leaves the slot on its active one.\n4. **Run the managed agent.**\n   `mutagent helix agent @<slug> [--env <name>] -p \"<task>\"` runs headless;\n   `--rpc` runs interactive. `@<slug>:vN` pins a revision; `@<slug>:latest` runs\n   the newest validated one. The receipt (reference, sessionId: the hs1_ session\n   id, agent, mode) is one JSON line on stderr: keep the reference. `mutagent helix session attach`,\n   `send` (interactive only), `signal`, `checkpoint`, `checkpoints` and\n   `close-input` take it. Restore of a managed agent's session is refused today;\n   start a new run. A person starts a managed agent run (terminal, Desktop, web); from inside a\n   cloud sandbox the platform refuses the launch (`SANDBOX_CANNOT_LAUNCH`): show the refusal as-is.\n5. **Inspect.** `mutagent agent inspect <slug> [--env <name>] --json` shows the\n   revisions, each slot's active revision and the sessions launched from it.\n   `mutagent agent list --json` lists the workspace's managed agents. Both run on\n   a laptop only: inside a cloud sandbox they fail with `SANDBOX_SCOPE`, and the\n   deployment check is `mutagent factory show <entry> --json` instead.\n6. **Roll back or retire.** `mutagent agent activate <slug> --revision vN\n   [--env <name>] --json` makes an older revision active for new runs; running\n   sessions keep theirs. `mutagent agent retire <slug> [--env <name>] --force`\n   disables the slot; `activate` re-enables it. Retire refuses without `--force`\n   in every mode: confirm with the user first.\n\nOn an uncertain deploy or activate (a network error, a 5xx), retry the same\ncommand with the same `--idempotency-key` the error's recovery names; a new key\nis a new request. `mutagent agent inspect --operation <id>` shows the recorded\noutcome of one operation. `pack --output <archive>` writes the archive for\ninspection; the path must be outside the agent folder and replacing a file\nneeds `--force`.\n",
   "workflows/factory-register.md": `---
@@ -22316,6 +22324,11 @@ outcome". Reports are its evidence. The six stages are spec, build, evaluate,
 diagnose, optimize and ship. Read \`mutagent factory stage --help\` before the first
 use.
 
+Reports are discovery, diagnostics, \`--kind evaluator\` (an evaluation) and
+review (the human-in-the-loop calibration of a judge). The spec stage pushes no report: its
+output is the spec version (\`mutagent factory spec push\`, see
+[factory-spec-sync.md](./factory-spec-sync.md)). Record or finish its run without one.
+
 ## P3: a stage in this session
 
 A stage runs here: the user types \`/<stage>\` (\`/evaluate\`) or asks for one;
@@ -22329,6 +22342,13 @@ user confirms). Locally, record it as in P4. In a cloud sandbox:
 3. **Finish the run:** \`mutagent factory stage finish --state succeeded --verdict PASS --json\`.
 4. A session ending with work missing is woken with the list.
 
+**An entry session** is bound to an entry but launched with no stage (the web's
+"Run in Helix", or \`mutagent helix agent … --subject <entry-id>\` with no \`--stage\`):
+no run is open. Its first message names the stage: \`/<stage> …\` means run that stage
+in this session. Open its run with \`mutagent factory stage start --stage <stage> --json\`
+(the entry is the bound one), do the work, then push the report and finish the run
+as in steps 2 and 3.
+
 **Only when the user asks for a separate sandbox, and never from inside a sandbox:**
 \`mutagent helix agent --name <agent> --subject <entry-id> --stage <stage> -p "<task>"\`
 starts a visible child session (\`mutagent helix session list\`, the web); its agent
@@ -22910,9 +22930,11 @@ user which filters were not applied.
 ## In a cloud sandbox
 
 With no filter, the commands read the sandbox's own session (\`MUTAGENT_SESSION_ID\`).
-A run launched for an entry's evaluate, diagnose or optimize stage may also read
-that entry's sessions; the server derives the scope from the launch. Anything else
-is refused with \`TRACES_SCOPE\`: narrow to your own session. See
+A filter that names a client agent (\`--agent\`, \`--skill\`, \`--workflow\`, or a client's
+own session id) reads any client agent's traces in its workspace, with no stage run
+needed. Other Helix sessions stay out of reach, except an entry's sessions for a run
+launched for its evaluate, diagnose or optimize stage. Anything else is refused with
+\`TRACES_SCOPE\`: narrow to your own session or a client agent. See
 [concepts/where-helix-runs.md](../concepts/where-helix-runs.md).
 
 Gateway runs carry the same window: \`mutagent gateway runs --session <hs1_…> --json\`
@@ -27276,7 +27298,8 @@ async function runCloudLaunch(plan, mode) {
       ...plan.preset === undefined ? {} : { preset: plan.preset },
       ...plan.sandboxProvider === undefined ? {} : { sandboxProvider: plan.sandboxProvider },
       ...repositoryFields(plan),
-      ...plan.factory === undefined ? {} : { subject: plan.factory.subject, stage: plan.factory.stage }
+      ...plan.factory === undefined ? {} : { subject: plan.factory.subject },
+      ...plan.factory?.stage === undefined ? {} : { stage: plan.factory.stage }
     }).catch((error) => {
       throw entryRefusal(launchRepositoryRefusal(error));
     });
@@ -27826,7 +27849,7 @@ async function resolveFactoryDefault(name, explicit, usage, conn, env = process.
 var MISSING_TASK_MESSAGE = 'a cloud run needs a task: pass -p "<task>", or --rpc for an interactive session';
 function registerAgentCommand(parent, registration, deps = defaultPlanDeps()) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("agent").description("Run a Helix agent in the cloud, or a managed agent by @slug").argument("[argv...]", "Agent definition, then the task and Helix flags; or @slug[:vN|:latest] for a managed agent").allowUnknownOption(true).allowExcessArguments(true).addOption(new Option("--sandbox <id>", "Run in an existing sandbox, by sandbox id").hideHelp()).option("--preset <name>", "Sandbox preset (not with --sandbox)").option("--sandbox-provider <name>", "Run on this configured sandbox provider").option("--env <name>", "Workspace Environment to load for this run (see mutagent env list)").option("--rpc", "Read JSON commands on stdin; write events on stdout").option("--cwd <path>", "Working directory in the sandbox").option("--repository <owner/name>", "Native brief only: run in a checkout of this GitHub repository (not with --sandbox or --cwd)").option("--branch <name>", "Branch of --repository to check out (default: its default branch)").option("--subject <id>", "Native brief only: bind the session to this Factory entry (with --stage)").option("--stage <stage>", `The platform opens a stage run first (${FACTORY_STAGES.join("|")}); the entry is --subject, else inferred`).addHelpText("after", [
+  parent.command("agent").description("Run a Helix agent in the cloud, or a managed agent by @slug").argument("[argv...]", "Agent definition, then the task and Helix flags; or @slug[:vN|:latest] for a managed agent").allowUnknownOption(true).allowExcessArguments(true).addOption(new Option("--sandbox <id>", "Run in an existing sandbox, by sandbox id").hideHelp()).option("--preset <name>", "Sandbox preset (not with --sandbox)").option("--sandbox-provider <name>", "Run on this configured sandbox provider").option("--env <name>", "Workspace Environment to load for this run (see mutagent env list)").option("--rpc", "Read JSON commands on stdin; write events on stdout").option("--cwd <path>", "Working directory in the sandbox").option("--repository <owner/name>", "Native brief only: run in a checkout of this GitHub repository (not with --sandbox or --cwd)").option("--branch <name>", "Branch of --repository to check out (default: its default branch)").option("--subject <id>", "Native brief only: bind the session to this Factory entry (with or without --stage)").option("--stage <stage>", `The platform opens a stage run first (${FACTORY_STAGES.join("|")}); the entry is --subject, else inferred`).addHelpText("after", [
     "",
     "Examples:",
     '  mutagent helix agent @invoice-pricing --env prod -p "Price three widget units."',
@@ -27837,6 +27860,7 @@ function registerAgentCommand(parent, registration, deps = defaultPlanDeps()) {
     '  mutagent helix agent --name reviewer --env staging -p "check the deploy"',
     '  mutagent helix agent --name reviewer --repository acme/api --branch feat/login -p "review the branch"',
     '  mutagent helix agent --name evaluator --subject invoice-pricing --stage evaluate -p "Evaluate spec version 4"',
+    '  mutagent helix agent --name evaluator --subject invoice-pricing -p "/evaluate spec version 4"',
     "",
     "Managed agents (deployed with mutagent agent deploy):",
     "  @slug runs the slot's active revision; @slug:vN pins revision N; @slug:latest runs the newest validated revision.",
@@ -27850,7 +27874,9 @@ function registerAgentCommand(parent, registration, deps = defaultPlanDeps()) {
     "  The platform opens a stage run, binds the session to the entry and derives the sandbox",
     "  token's scopes from the entry, the stage and its policy. There is no grant flag.",
     "  Without --subject the entry is MUTAGENT_SUBJECT_ID, else the session's, else this checkout's .mutagent/factory.json.",
-    "  Errors: FLAG_CONFLICT (--subject without --stage, or either with @id); MISSING_ARGUMENTS (no entry inferred: pass --subject);",
+    "  --subject without --stage opens an entry session: bound to the entry, no stage run opened;",
+    "  the session runs its stage itself (mutagent factory stage start --stage <stage>).",
+    "  Errors: FLAG_CONFLICT (--subject or --stage with @id); MISSING_ARGUMENTS (no entry inferred: pass --subject);",
     "  ENTRY_NOT_FOUND (run: mutagent factory list); VALIDATION_ERROR (--stage is one of the six stages).",
     "",
     "Definition and task:",
@@ -27952,17 +27978,14 @@ function factoryLaunchRefusal(argv, options) {
   if (isManagedAgentAddress(argv[0])) {
     return new MutagentError("FLAG_CONFLICT", "@id already names the entry it runs as; --subject and --stage are for a native brief.", "Drop --subject and --stage, or pass them with a native brief (--name, --file or --prompt).");
   }
-  if (stage === undefined) {
-    return new MutagentError("FLAG_CONFLICT", "--subject needs --stage <stage>: the stage run is what binds the session to the entry.", "Pass --stage <stage> with --subject <id>");
-  }
-  if (!FACTORY_STAGES.includes(stage)) {
+  if (stage !== undefined && !FACTORY_STAGES.includes(stage)) {
     return new MutagentError("VALIDATION_ERROR", `--stage ${stage} is not one of ${FACTORY_STAGES.join(", ")}.`, `Pass one of: ${FACTORY_STAGES.join(" | ")}`);
   }
   return;
 }
 async function factoryTarget(opts) {
   if (opts.stage === undefined)
-    return;
+    return opts.subject === undefined ? undefined : { subject: opts.subject };
   const subject = await resolveFactoryDefault("subject", opts.subject, { what: "--subject <id>", command: "mutagent helix agent" }, connectPlatform);
   return { subject, stage: opts.stage };
 }
@@ -34275,8 +34298,9 @@ Examples:
 The HTML is never printed; it is served as a file under a sandboxing CSP.
 
 AI Agent Directive:
-  --json returns { report, sessionRef, specVersion, buildRef, renderInput, htmlPath,
-  _links } plus htmlFile when --html was given. An unknown id is REPORT_NOT_FOUND, exit 1.
+  --json returns { report, sessionRef, harnessSessionId, specVersion, buildRef, renderInput,
+  htmlPath, _links } plus htmlFile when --html was given. harnessSessionId is the session id
+  Helix itself used (null when not known); sessionRef is the hs1_ reference. An unknown id is REPORT_NOT_FOUND, exit 1.
 `).action(async (id, options, command) => {
     await runReportsAction(command, async (isJson) => {
       const conn = await connectReports({ sandboxBearer: false });
@@ -34298,7 +34322,7 @@ AI Agent Directive:
       }
       const r = detail.report;
       console.log(chalk53.bold(r.title));
-      for (const [label, value] of Object.entries({ ...row(r), session: detail.sessionRef ?? "", html: links.html })) {
+      for (const [label, value] of Object.entries({ ...row(r), session: detail.sessionRef ?? "", "helix id": detail.harnessSessionId ?? "", html: links.html })) {
         if (label !== "title" && value !== "")
           console.log(`  ${label.padEnd(9)}${value}`);
       }
@@ -34611,6 +34635,16 @@ async function defaultReportKind(renderInput, htmlPath, openStageRunStage) {
   throw new MutagentError("VALIDATION_ERROR", `--kind is required: nothing says what kind of report ${htmlPath} is (no open stage run with a report kind, ` + `no kind in the render input, no ${COMPLETION_FILE} stage). Allowed: ${REPORT_KINDS.join(", ")}.`, `Pass --kind <${REPORT_KINDS.join("|")}>`);
 }
 
+// src/lib/harness-session.ts
+var HARNESS_SESSION_VAR = "PI_SESSION_ID";
+var MAX_LENGTH = 200;
+function harnessSessionField(env = process.env) {
+  const value = env[HARNESS_SESSION_VAR]?.trim();
+  if (value === undefined || value === "" || value.length > MAX_LENGTH)
+    return {};
+  return { harnessSessionId: value };
+}
+
 // src/commands/reports/push.ts
 var PUSH_USAGE = "mutagent reports push <run-dir|report-file> [--kind <diagnostics|discovery|evaluator|hitl>] [--run-id <id>] [--subject <id>] [--session-ref <ref>] [--title <text>] [--render-input <file>] [--replace] [--stage-run <run-id>] [--spec-version <n>] [--build-target <target-id>] [--build-rev <rev>] [--apply-id <id>] [--optimize-run <id> --iteration <n>]";
 async function openStageRunStage(conn, stageRun) {
@@ -34722,6 +34756,7 @@ AI Agent Directive:
         renderInput,
         ...runId === undefined ? {} : { runId },
         ...options.sessionRef === undefined ? {} : { sessionRef: options.sessionRef },
+        ...harnessSessionField(),
         ...options.replace === true ? { replace: true } : {},
         ...links,
         ...optimize
@@ -38584,7 +38619,8 @@ function registerAdd2(factory) {
         ...git === undefined ? {} : { git },
         ...components.length === 0 ? {} : { components },
         ...options.dryRun === true ? { dryRun: true } : {},
-        origin: "cli"
+        origin: "cli",
+        ...harnessSessionField()
       }, "mutagent factory add --help");
       const id = result.entry.id;
       if (!result.dryRun && result.entry.specVersion !== null)
@@ -38918,7 +38954,8 @@ function registerPush(spec) {
         ...components.length === 0 ? {} : { components },
         ...options.message === undefined ? {} : { message: options.message },
         ...options.dryRun === true ? { dryRun: true } : {},
-        origin: "cli"
+        origin: "cli",
+        ...harnessSessionField()
       }, String(base), "mutagent factory spec push --help");
       const version = result.specVersion.id;
       if (!result.dryRun)
@@ -39077,7 +39114,8 @@ function registerStart2(stage) {
         ...fields,
         ...build,
         ...session.source === "explicit" || session.source === "env" ? { session: session.value } : {},
-        origin: "cli"
+        origin: "cli",
+        ...harnessSessionField()
       }, "mutagent factory stage start --help");
       const tips = [`Finish it: mutagent factory stage finish ${arg(result.stageRun.id)} --state succeeded --verdict PASS`];
       if (isJson) {
@@ -39118,7 +39156,8 @@ function registerFinish(stage) {
         ...options.verdict === undefined ? {} : { verdict: options.verdict },
         ...score === undefined ? {} : { score },
         ...options.summary === undefined ? {} : { summary: options.summary },
-        ...options.report === undefined ? {} : { reports: options.report }
+        ...options.report === undefined ? {} : { reports: options.report },
+        ...harnessSessionField()
       }, "mutagent factory stage finish --help");
       if (isJson) {
         output.output({ success: true, stageRun: run, _links: { ...factoryLinks(conn.endpoint, run.entry), stageRun: `/api/factory/stage-runs/${encodeURIComponent(run.id)}` } });
@@ -39171,7 +39210,8 @@ function registerRecord(stage) {
         ...options.report === undefined ? {} : { reports: options.report },
         ...startedAt === undefined ? {} : { startedAt },
         ...endedAt === undefined ? {} : { endedAt },
-        origin: "cli"
+        origin: "cli",
+        ...harnessSessionField()
       }, "mutagent factory stage record --help");
       if (isJson) {
         output.output({ success: true, ...result, ...warningsOf2(recordHint), _links: factoryLinks(conn.endpoint, entryId) });
@@ -39231,7 +39271,9 @@ function registerShow7(stage) {
         return;
       }
       console.log(stageLine(detail.stageRun));
-      console.log(`  Owner: ${detail.stageRun.owner.kind} ${detail.stageRun.owner.id}${detail.stageRun.origin.session === null ? "" : `  Session: ${detail.stageRun.origin.session}`}`);
+      const { origin } = detail.stageRun;
+      const harness = origin.harnessSessionId ?? null;
+      console.log(`  Owner: ${detail.stageRun.owner.kind} ${detail.stageRun.owner.id}${origin.session === null ? "" : `  Session: ${origin.session}`}${harness === null ? "" : `  Helix session: ${harness}`}`);
       for (const report of detail.reports)
         console.log(`  Report: ${report.id}  ${report.title}${report.verdict === null ? "" : `  ${report.verdict}`}`);
       console.log(`  Findings: ${String(detail.findings)}`);
@@ -40578,4 +40620,4 @@ if (process.env.CLI_VERSION) {
 }
 runCli(process.argv.slice(2), cliVersion);
 
-//# debugId=EC8D8A955FE754FB64756E2164756E21
+//# debugId=8D7F27126F75763C64756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutagent/cli",
-  "version": "0.2.130",
+  "version": "0.2.132",
   "description": "Bun-native CLI for the MutagenT AI platform - auth, provider config, and lifecycle-tool installer for AI-native workflows",
   "type": "module",
   "bin": {
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.7.2",
-    "@mutagent/sdk": "0.8.66",
+    "@mutagent/sdk": "0.8.67",
     "@sinclair/typebox": "^0.34.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",