@mutagent/cli 0.2.123 → 0.2.125

package/dist/bin/cli.js

@@ -22127,7 +22127,10 @@ before the first use.
    name, targets, components) and wait for the user's yes. Never run \`factory add\`
    without it. Then register:
    \`mutagent factory add <agentspec-file> --json\`. The file's git remote, path and
-   HEAD commit are read from its checkout and recorded as v1.
+   HEAD commit are read from its checkout and recorded as v1. When the spec sets
+   \`spec.traceSource\` (a trace-source id from \`mutagent integrations sources list\`),
+   the entry's trace source is set to it; \`traceSourceUpdate\` reports the outcome, and
+   a refusal there (its \`code\`) leaves the entry registered: tell the user the code.
 4. **Show the result.** Render \`_directive.renderedCard\` verbatim, then
    \`mutagent factory show <id> --json\` to show the targets and the spec version.
 5. **Record the spec stage**: \`mutagent factory stage record --stage spec --state succeeded --spec-version <n> --json\`
@@ -22260,7 +22263,10 @@ the version this checkout last wrote (\`spec get --out\`) or pushed. Read
 2. **Validate.** \`mutagent factory spec push <id> <file> --dry-run --json\`.
 3. **Confirm with the user**, then push with a reason:
    \`mutagent factory spec push <id> <file> --message "<why>" --json\`.
-   The git commit defaults to HEAD when the file is tracked and unmodified.
+   The git commit defaults to HEAD when the file is tracked and unmodified. A
+   \`spec.traceSource\` that differs from the entry's is then set on the entry
+   (\`traceSourceUpdate\`); if that step is refused (in a sandbox: \`PERMISSION_DENIED\`),
+   the push still stands: report the code, do not push again.
 4. Show \`_directive.renderedCard\` verbatim: it names the new version.
 
 Targets and components update from the spec; there is no separate update command.
@@ -27418,6 +27424,7 @@ import { factoryListFactoryEntries } from "@mutagent/sdk/funcs/factory-list-fact
 import { factoryListFactorySpecVersions } from "@mutagent/sdk/funcs/factory-list-factory-spec-versions.js";
 import { factoryListFactoryStageRuns } from "@mutagent/sdk/funcs/factory-list-factory-stage-runs.js";
 import { factoryPushFactorySpec } from "@mutagent/sdk/funcs/factory-push-factory-spec.js";
+import { factorySetFactoryEntryTraceSource } from "@mutagent/sdk/funcs/factory-set-factory-entry-trace-source.js";
 
 // src/lib/platform-sdk.ts
 import { HTTPClient as HTTPClient3, Mutagent as Mutagent3 } from "@mutagent/sdk";
@@ -27661,6 +27668,7 @@ var factoryApi = {
   specVersions: (c, id, query, help) => sdkJson(c, (sdk) => factoryListFactorySpecVersions(sdk, { id, ...query }), help),
   specVersion: (c, id, version, help) => sdkJson(c, (sdk) => factoryGetFactorySpecVersion(sdk, { id, version, raw: true }), help),
   pushSpec: (c, id, body, ifMatch, help) => sdkJson(c, (sdk) => factoryPushFactorySpec(sdk, { id, ...ifMatch === undefined ? {} : { ifMatch }, body }), help),
+  setTraceSource: (c, id, traceSource, help) => sdkJson(c, (sdk) => factorySetFactoryEntryTraceSource(sdk, { id, body: { traceSource } }), help),
   sync: (c, id, query, help) => sdkJson(c, (sdk) => factoryGetFactorySyncState(sdk, { id, ...query }), help),
   createStageRun: (c, id, body, help) => sdkJson(c, (sdk) => factoryCreateFactoryStageRun(sdk, { id, body: stageRunBody(body) }), help),
   listStageRuns: (c, id, query, help) => sdkJson(c, (sdk) => factoryListFactoryStageRuns(sdk, { id, ...query }), help),
@@ -36788,6 +36796,56 @@ import { Command as Command30 } from "commander";
 import chalk66 from "chalk";
 init_errors();
 
+// src/lib/factory-trace-source.ts
+init_errors();
+function specTraceSource(spec) {
+  const value = spec.parsed.spec?.traceSource;
+  return typeof value === "string" ? value : undefined;
+}
+async function applySpecTraceSource(conn, entryId, wanted, current, opts) {
+  if (wanted === undefined)
+    return;
+  let previous;
+  try {
+    previous = await current();
+    if (previous === wanted)
+      return { state: "unchanged", traceSource: wanted, previous };
+    if (opts.dryRun)
+      return { state: "would-set", traceSource: wanted, previous };
+    const answer = await factoryApi.setTraceSource(conn, entryId, wanted, opts.help);
+    return { state: "set", traceSource: answer.traceSource ?? wanted, previous };
+  } catch (error) {
+    if (!(error instanceof MutagentError))
+      throw error;
+    return {
+      state: "refused",
+      traceSource: wanted,
+      ...previous === undefined ? {} : { previous },
+      code: error.code,
+      error: error.message,
+      ...error.suggestion === undefined ? {} : { suggestedAction: error.suggestion }
+    };
+  }
+}
+function describeTraceSourceUpdate(update, written) {
+  const was = update.previous === undefined ? "" : ` (was ${update.previous ?? "the Mutagent store"})`;
+  switch (update.state) {
+    case "set":
+      return { warn: false, text: `Trace source set to ${update.traceSource}${was}` };
+    case "unchanged":
+      return { warn: false, text: `Trace source is already ${update.traceSource}` };
+    case "would-set":
+      return { warn: false, text: `Would set the trace source to ${update.traceSource}${was}; nothing was sent` };
+    case "refused":
+      return { warn: true, text: `${written} stands; setting the trace source to ${update.traceSource} was refused: ${update.code ?? "ERROR"}: ${update.error ?? ""}` };
+  }
+}
+function traceSourceTips(update) {
+  if (update?.state !== "refused")
+    return [];
+  return [`Trace source not set (${update.code ?? "ERROR"}); the spec write stands.${update.suggestedAction === undefined ? "" : ` ${update.suggestedAction}`}`];
+}
+
 // src/lib/factory-local.ts
 init_dist();
 init_errors();
@@ -37742,7 +37800,8 @@ var SpecSchema = closed({
   workflow: Type.Optional(WorkflowBodySchema),
   targets: Type.Array(TargetSchema),
   evaluation: EvaluationSchema,
-  decisionsRef: Type.Optional(Str())
+  decisionsRef: Type.Optional(Str()),
+  traceSource: Type.Optional(Str())
 });
 var agentSpecRootProps = {
   apiVersion: Type.Literal(AGENTSPEC_API_VERSION),
@@ -38497,7 +38556,8 @@ function registerAdd2(factory) {
       "The spec is validated here (AgentSpec 0.3.0) before anything is sent. A system's",
       "spec.multiAgent.members[].specRef files are read for their metadata.id, resolved from",
       "the spec file's folder (stdin and --spec: the working directory). The git remote, path",
-      "and HEAD commit are read from the file's checkout."
+      "and HEAD commit are read from the file's checkout. spec.traceSource, when set, is then set on",
+      "the entry; a refusal of that step is reported in traceSourceUpdate by its code, and the entry stays."
     ],
     examples: [
       "mutagent factory add agents/invoice-pricing/agentspec.yaml --json",
@@ -38529,17 +38589,27 @@ function registerAdd2(factory) {
       const id = result.entry.id;
       if (!result.dryRun && result.entry.specVersion !== null)
         writeBase(checkoutRoot(spec.input.file), id, result.entry.specVersion.id, spec.input.file);
+      const traceSourceUpdate = await applySpecTraceSource(conn, id, specTraceSource(spec), () => Promise.resolve(result.entry.traceSource ?? null), { dryRun: result.dryRun, help: "mutagent factory add --help" });
+      const entry = traceSourceUpdate?.state === "set" ? { ...result.entry, traceSource: traceSourceUpdate.traceSource } : result.entry;
       const links = factoryLinks(conn.endpoint, id);
       const tips = [
         `Next spec change: mutagent factory spec push ${arg(id)} <file>`,
-        `Record work on it: mutagent factory stage record ${arg(id)} --stage <s> --state <s>`
+        `Record work on it: mutagent factory stage record ${arg(id)} --stage <s> --state <s>`,
+        ...traceSourceTips(traceSourceUpdate)
       ];
       if (isJson) {
-        output.output({ success: true, dryRun: result.dryRun, entry: result.entry, _links: links, _directive: { tips } });
+        output.output({ success: true, dryRun: result.dryRun, entry, ...traceSourceUpdate === undefined ? {} : { traceSourceUpdate }, _links: links, _directive: { tips } });
         return;
       }
       output.success(result.dryRun ? `Valid: would register ${id} (${result.entry.kind}); nothing was written` : `Registered ${id} (${result.entry.kind}), spec v${String(result.entry.specVersion?.id ?? 1)}`);
       console.log(`  ${links.ui}`);
+      if (traceSourceUpdate !== undefined) {
+        const line = describeTraceSourceUpdate(traceSourceUpdate, `The registration of ${id}`);
+        if (line.warn)
+          output.warn(line.text);
+        else
+          output.info(line.text);
+      }
       for (const tip of tips)
         output.info(tip);
     });
@@ -38805,7 +38875,11 @@ function registerStatus(spec) {
 }
 function registerPush(spec) {
   spec.command("push").description("Validate an agentspec and record it as the entry's next spec version").argument("[id]", "The entry id; must equal the file's metadata.id (in a sandbox with only the file: the bound entry)").argument("[agentspec-file]", "Path, or - for stdin (not with --spec)").option("--spec <yaml>", "Raw YAML text instead of a file").option("--base <n>", "The spec version this file was made from (default: the one recorded in this checkout)").option("--git-commit <sha>", "Commit the file came from (default: HEAD, when the file is tracked and unmodified)").option("--message <text>", "Why it changed").option("--dry-run", "Validate only; nothing is written").addHelpText("after", leafHelp({
-    notes: ["Components (spec.multiAgent.members[]), their pins and targets[] update from the spec; the git location comes from the checkout."],
+    notes: [
+      "Components (spec.multiAgent.members[]), their pins and targets[] update from the spec; the git location comes from the checkout.",
+      "spec.traceSource, when it differs from the entry's, is then set on the entry; a refusal of that step",
+      "(e.g. PERMISSION_DENIED in a sandbox) is reported in traceSourceUpdate by its code, and the push stands."
+    ],
     examples: [
       'mutagent factory spec push support-triage agents/support-triage/agentspec.yaml --message "Add refund-agent v3" --json',
       "mutagent factory spec push invoice-pricing agentspec.yaml --base 6 --json",
@@ -38849,9 +38923,11 @@ function registerPush(spec) {
       const version = result.specVersion.id;
       if (!result.dryRun)
         writeBase(root, entryId, version, spec.input.file);
-      const tips = [`Stage runs and reports you record next resolve to v${String(version)}`];
+      const help = "mutagent factory spec push --help";
+      const traceSourceUpdate = await applySpecTraceSource(conn, entryId, specTraceSource(spec), async () => (await factoryApi.getEntry(conn, entryId, help)).traceSource, { dryRun: result.dryRun, help });
+      const tips = [`Stage runs and reports you record next resolve to v${String(version)}`, ...traceSourceTips(traceSourceUpdate)];
       if (isJson) {
-        output.output({ success: true, ...result, sync: result.dryRun ? "unchanged" : "in-sync", _links: factoryLinks(conn.endpoint, entryId), _directive: { tips } });
+        output.output({ success: true, ...result, sync: result.dryRun ? "unchanged" : "in-sync", ...traceSourceUpdate === undefined ? {} : { traceSourceUpdate }, _links: factoryLinks(conn.endpoint, entryId), _directive: { tips } });
         return;
       }
       if (result.dryRun)
@@ -38862,6 +38938,13 @@ function registerPush(spec) {
         output.success(`Pushed ${entryId} v${String(version)} (base v${String(base)})`);
       for (const change of result.components.changed)
         output.info(`Pin moved: ${change.id} v${String(change.pinned.from ?? "—")} → v${String(change.pinned.to)}`);
+      if (traceSourceUpdate !== undefined) {
+        const line = describeTraceSourceUpdate(traceSourceUpdate, `The push (v${String(version)})`);
+        if (line.warn)
+          output.warn(line.text);
+        else
+          output.info(line.text);
+      }
     });
   });
 }
@@ -40495,4 +40578,4 @@ if (process.env.CLI_VERSION) {
 }
 runCli(process.argv.slice(2), cliVersion);
 
-//# debugId=32FCAEC612A7F6F964756E2164756E21
+//# debugId=EC8D8A955FE754FB64756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutagent/cli",
-  "version": "0.2.123",
+  "version": "0.2.125",
   "description": "Bun-native CLI for the MutagenT AI platform - auth, provider config, and lifecycle-tool installer for AI-native workflows",
   "type": "module",
   "bin": {