@pipefy/pipefy-process-coder 0.1.1 → 0.1.2

package/AGENTS.md

@@ -250,6 +250,8 @@ live running. Do not re-derive them. The shapes that bite most often:
 | a field condition testing the field it hides | stored happily, and the **phase form stops opening**. The API validates none of this — not the self-reference, not the operation, not even `not_a_real_operation` |
 | `automationVariables.active` | omitted for the life of the tool, so disabling an automation was a no-op that reported success |
 | `updateAutomation` | works, across every field map dimension. The recipes' delete-and-recreate was inherited, not measured |
+| internal `AutomationActionParams.aiBehaviorParams` | an **object** (`AiBehaviorParams`), the same type the public `aiAgents` read selects. Selected bare, the whole `loadAutomation` document fails validation — so *every* automation in the pipe loads without `action_params`, not only the AI ones. One selection, `AI_BEHAVIOR_PARAMS_SELECTION`, serves both reads |
+| a snapshot's `signedUrl` | `app.pipefy.com/storage/v1/signed/…`, and it can answer **HTTP 500** with Pipefy's own error page while `createRepoSnapshot` and the `UPLOADED` status both succeed — measured on two unrelated pipes, old snapshots and new. A pull falls back to reconstruction rather than write a workspace with no pipe in it; `--no-fallback` refuses instead |
 | iPaaS `IMPORT_FLOW` | migrates the tree it is given; never use it |
 | iPaaS connections | the host marks any credential `ACTIVE` **without validating it** |
 | `POST /app-connections/{id}` | accepts `scope` and `projectIds` and returns 200 ignoring both |
@@ -308,11 +310,20 @@ way `pipe pull` would notice.
 
 All three automation mutations are **public** and were being sent to the internal
 endpoint — inherited from the Change Migrator recipes and never re-checked, which
-made automations the one entity written through an unversioned endpoint with no
-introspection, for no reason. Before adding anything to `registry.ts` with
+made automations the one entity written through an unversioned endpoint, for
+no reason. Before adding anything to `registry.ts` with
 `transport: 'internal'`, introspect the public schema for it. If it genuinely is
 not there, say which public mutation is missing and how that was verified.
 
+The internal endpoint is unversioned, but it **does** answer introspection
+(`__type(name:)` worked on it live) — this file used to say it did not. So a
+query sent there can be checked against its schema like any other. Every read
+query the internal adapter sends lives in `READ_QUERIES` (internal.ts), and
+`pipe doctor` validates each one with ids that match nothing: a document the
+schema refuses comes back with `errors` and no `data`, a valid one with `data`
+and a not-found. That is how the bare-`aiBehaviorParams` drift would have shown
+up before a user's pull did. Add a new internal read there, never a write.
+
 ### Probing is not free on this platform
 
 Two separate incidents from the same wrong assumption — that schema validation

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,11 @@
+Pipefy Process Coder
+Copyright 2026 Pipefy, Inc.
+
+This product includes software developed at Pipefy (https://www.pipefy.com).
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use the files in this repository except in compliance with the License.
+
+The "Pipefy" name, logo, and brand assets are trademarks of Pipefy, Inc.
+and are NOT licensed under the Apache License 2.0. Use of the Pipefy
+trademarks is subject to Pipefy's brand guidelines and prior authorization.

package/README.md

@@ -697,7 +697,7 @@ research/snap.json  the pipe <pipeId> fixture every test runs against
 | `pipe doctor` | capabilities, missing mutations, internal-API status |
 | `pipe skills` | the agent skills this install ships with; `install` hands off to `npx skills add` |
 | `pipe create <name>` | create an empty pipe and pull it, ready to be built from files |
-| `pipe pull <id>` | pull into a workspace; `--depth`, `--reuse-snapshot`, `--from-file` |
+| `pipe pull <id>` | pull into a workspace; `--depth`, `--reuse-snapshot`, `--no-fallback`, `--from-file` |
 | `pipe export <id>` | one repo as a single payload, no workspace, no token needed to consume |
 | `pipe validate` | offline shape + integrity |
 | `pipe diff` | baseline, live, or cross-repo; `--html`, `--open`, `--json` |
@@ -823,4 +823,8 @@ A successful pipe apply rewrites your files. It adopts each created entity's rea
 [] - Check the baseline is not stale before planning: compare the pulled version id against the live one, and refuse to propose deletions when the pipe has moved since the pull. A stale baseline turns someone else's changes into a diff — seen live, where a verification diff listed five changes made elsewhere as deletions the workspace wanted
 [] - pipe pull inside a workspace pulls the pipes automatically
 [] - One design point worth stating
-Each repo still applies independently — own plan file, own pre-apply snapshot, own verify. That's deliberate: they're separate repos with separate baselines, and a failure in one must not roll back or abandon another that already succeeded. So it's a loop over the real thing, not a merged mega-plan. Exit code is the worst of them. --plan and --resume stay single-repo, since a saved plan belongs to exactly one.
+Each repo still applies independently — own plan file, own pre-apply snapshot, own verify. That's deliberate: they're separate repos with separate baselines, and a failure in one must not roll back or abandon another that already succeeded. So it's a loop over the real thing, not a merged mega-plan. Exit code is the worst of them. --plan and --resume stay single-repo, since a saved plan belongs to exactly one.
+
+## License
+
+Apache-2.0 — see [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE). Copyright 2026 Pipefy, Inc. The Pipefy name, logo and brand assets are trademarks of Pipefy, Inc. and are not covered by the license.

package/dist/cli.js

@@ -129,12 +129,9 @@ const main = async () => {
      * question behind the version check.
      */
     if (parsed.command === '--version' || parsed.command === '-V' || parsed.command === 'version') {
-        const { readFile } = await import('node:fs/promises');
         const { fileURLToPath } = await import('node:url');
-        const { dirname, join } = await import('node:path');
-        const here = dirname(fileURLToPath(import.meta.url));
-        const pkg = JSON.parse(await readFile(join(here, '..', 'package.json'), 'utf8'));
-        out(`${pkg.name} ${pkg.version}`);
+        const { PACKAGE_NAME, TOOL_VERSION } = await import("./version.js");
+        out(`${PACKAGE_NAME} ${TOOL_VERSION}`);
         out(dim(`  node    ${process.version} (needs >=22.18 for native type stripping)`));
         out(dim(`  running ${fileURLToPath(import.meta.url)}`));
         return 0;
@@ -164,6 +161,18 @@ const main = async () => {
     const code = await cmd.run(parsed);
     return typeof code === 'number' ? code : 0;
 };
+/**
+ * A reader that stops early — `pipe doctor | head`, a pager quit — closes the
+ * pipe, and the next write raised an unhandled EPIPE with a Node stack trace.
+ * The reader has what it wanted; there is no one left to tell.
+ */
+for (const stream of [process.stdout, process.stderr]) {
+    stream.on('error', (e) => {
+        if (e.code === 'EPIPE')
+            process.exit(process.exitCode ?? 0);
+        throw e;
+    });
+}
 main()
     .then((code) => {
     process.exitCode = code;

package/dist/commands/misc.js

@@ -36,11 +36,14 @@ export const login = async (p) => {
     const token = str(p, 'token');
     // ── the intended path: delegate to the toolkit's OAuth flow ───────────────
     if (!token) {
-        const { inspectToolkit, runToolkitLogin, INSTALL_HINT } = await import("../pipefy/toolkit.js");
+        const { inspectToolkit, runToolkitLogin, INSTALL_HINT, UPGRADE_HINT } = await import("../pipefy/toolkit.js");
         const toolkit = await inspectToolkit();
         if (!toolkit.installed) {
             throw new UserError('the Pipefy AI toolkit is not installed, so there is no browser login to run', `${INSTALL_HINT} — or use \`pipe login --token <token>\` for a personal API token`);
         }
+        if (!toolkit.usable) {
+            throw new UserError(`the Pipefy AI toolkit is installed but this tool cannot use it: ${toolkit.error}`, `${UPGRADE_HINT} — or use \`pipe login --token <token>\` for a personal API token`);
+        }
         step('running `pipefy auth login` (browser sign-in)');
         const code = await runToolkitLogin(bool(p, 'device') ? ['--device'] : []);
         if (code !== 0) {
@@ -91,7 +94,7 @@ export const doctorHelp = `pipe doctor [--repo <pipeId>]
   With --repo it also probes that pipe's read paths.`;
 export const doctor = async (p) => {
     const { resolveCredential } = await import("../config.js");
-    const { inspectToolkit, toolkitAuthStatus, INSTALL_HINT } = await import("../pipefy/toolkit.js");
+    const { inspectToolkit, toolkitAuthStatus, INSTALL_HINT, UPGRADE_HINT } = await import("../pipefy/toolkit.js");
     out(bold('endpoints'));
     out(`  graphql   ${ENDPOINTS.graphql}`);
     out(`  internal  ${ENDPOINTS.internal}`);
@@ -99,9 +102,18 @@ export const doctor = async (p) => {
     out(bold('credential'));
     const toolkit = await inspectToolkit();
     const credential = await resolveCredential();
-    out(`  toolkit   ${toolkit.installed ? green('installed') : red('not installed')}` +
-        (toolkit.installed ? dim(`  ${toolkit.cliPath ?? toolkit.interpreter}`) : dim(`  ${INSTALL_HINT}`)));
-    if (toolkit.installed) {
+    if (!toolkit.installed) {
+        out(`  toolkit   ${red('not installed')}${dim(`  ${INSTALL_HINT}`)}`);
+    }
+    else if (!toolkit.usable) {
+        out(`  toolkit   ${yellow('installed, unusable')}${dim(`  ${toolkit.cliPath ?? toolkit.interpreter}`)}`);
+        out(`            ${dim(toolkit.error)}`);
+        out(`            ${dim(UPGRADE_HINT)}`);
+    }
+    else {
+        out(`  toolkit   ${green('installed')}${dim(`  ${toolkit.cliPath ?? toolkit.interpreter}`)}`);
+    }
+    if (toolkit.installed && toolkit.usable) {
         const status = await toolkitAuthStatus();
         if (status) {
             const identity = status['identity'];
@@ -118,7 +130,11 @@ export const doctor = async (p) => {
         dim(credential?.detail ? `  ${credential.detail}` : ''));
     if (!credential) {
         info('');
-        throw new UserError('no credential', toolkit.installed ? 'run `pipe login` for the browser flow' : `${INSTALL_HINT}, or \`pipe login --token <token>\``);
+        throw new UserError('no credential', !toolkit.installed
+            ? `${INSTALL_HINT}, or \`pipe login --token <token>\``
+            : !toolkit.usable
+                ? `${UPGRADE_HINT}, or \`pipe login --token <token>\``
+                : 'run `pipe login` for the browser flow');
     }
     const net = await connect(p);
     const caps = await net.capabilities();
@@ -158,7 +174,25 @@ export const doctor = async (p) => {
     }
     out('');
     out(bold('internal API'));
-    out(`  status ${net.internal.status === 'ok' ? green('ok') : net.internal.status === 'unavailable' ? red('unavailable') : dim('unknown')}`);
+    // Validates the query documents themselves, with ids that match nothing —
+    // "status unknown" used to be all this said, while every automation read in
+    // a pull was failing on a query the schema had stopped accepting.
+    const checks = await net.internal.checkQueries();
+    if (!checks)
+        out(`  queries   ${red('no answer')}${dim('  the endpoint could not be reached')}`);
+    else {
+        for (const c of checks) {
+            out(`  ${c.ok ? green('ok  ') : red('FAIL')}  ${c.label.padEnd(18)}${c.ok ? '' : ` ${dim(c.message ?? '')}`}`);
+        }
+    }
+    const status = net.internal.status;
+    out(`  status ${status === 'ok'
+        ? green('ok')
+        : status === 'incompatible'
+            ? red('incompatible') + dim('  a query this version of pipe sends is refused — a bug in pipe, worth reporting')
+            : status === 'unavailable'
+                ? red('unavailable')
+                : dim('unknown')}`);
     info(dim('  Unversioned, no compatibility contract (PLAN.md §2.1). When it breaks, automation\n' +
         '  detail and phase-jump editing degrade to unknown rather than failing an apply.'));
     if (!caps.snapshots) {

package/dist/commands/pull.js

@@ -19,6 +19,7 @@ import { baselineFile, paths } from "../workspace/layout.js";
 import { connect } from "./context.js";
 import { RunRecorder, invocation } from "../report/run.js";
 import { pullAndWriteFlows } from "./flows.js";
+import { TOOL } from "../version.js";
 /**
  * `pipe pull <pipeId>` — the read path.
  *
@@ -39,6 +40,7 @@ export const help = `pipe pull <pipeId> [options]
   --org <id>           organization id, for the internal automations query
   --reuse-snapshot     use the newest complete snapshot instead of creating one
   --no-snapshot        force GraphQL reconstruction even if snapshots exist
+  --no-fallback        if a snapshot read fails, fail rather than reconstruct over GraphQL
   --no-internal        skip the internal API (automations and jumps become unknown)
   --label <text>       label the snapshot this pull creates
   --skip-roundtrip     do not run the codec self-check (not recommended)
@@ -57,6 +59,7 @@ export const run = async (p) => {
     const noInternal = bool(p, 'no-internal');
     const reuseSnapshot = bool(p, 'reuse-snapshot');
     const skipRoundTrip = bool(p, 'skip-roundtrip');
+    const noFallback = bool(p, 'no-fallback');
     const label = str(p, 'label');
     const startedAt = new Date();
     const net = await connect(p);
@@ -114,7 +117,28 @@ export const run = async (p) => {
              * relation arrays a pipe's does (VALIDATION.md §3g).
              */
             if (useSnapshots) {
-                env = await readViaSnapshot(net, ref, { reuseSnapshot, label });
+                try {
+                    env = await readViaSnapshot(net, ref, { reuseSnapshot, label });
+                }
+                catch (e) {
+                    /**
+                     * A failed snapshot read falls back to reconstruction rather than
+                     * leaving the repo out. Found live: Pipefy's storage answered every
+                     * signed snapshot URL with HTTP 500 — the creation succeeded, the
+                     * download did not, on every pipe tried — and the pull wrote a
+                     * workspace with no pipe in it. Reconstruction is less complete, and
+                     * says so per group: what it cannot see is `unknown`, never empty, so
+                     * the fallback cannot license a delete.
+                     */
+                    if (noFallback)
+                        throw e;
+                    warn(`snapshot read failed for ${ref.kind} ${ref.id} (${ref.name ?? '?'}): ${e.message} — ` +
+                        'reading it over GraphQL instead (--no-fallback to stop here)');
+                    env = await net.reconstructor.reconstruct(ref.id, {
+                        organizationId: net.organizationId,
+                        noInternal,
+                    });
+                }
             }
             else {
                 env = await net.reconstructor.reconstruct(ref.id, {
@@ -164,6 +188,20 @@ export const run = async (p) => {
     });
     const rootRef = discovery.repos.find((r) => r.id === rootRepoId);
     const outDir = resolve(str(p, 'out') ?? `${slugName(rootRef.name ?? String(rootRepoId))}-workspace`);
+    /**
+     * The root repo is the workspace. Without it there is nothing to validate,
+     * diff or plan against — and writing lock.json and workspace.json anyway
+     * did worse than produce an empty directory: re-pulling into an existing
+     * workspace replaced its lock with one that no longer listed the pipe, so
+     * the next diff had no baseline. This used to finish with exit code 0 and a
+     * "next: pipe validate", which scripts and agents believed.
+     */
+    if (!(await readRepo(rootRef))) {
+        ui.stop();
+        throw new UserError(`could not read the root repo ${rootRepoId}${rootRef.name ? ` (${rootRef.name})` : ''} — nothing was written to ${outDir}`, useSnapshots && noFallback
+            ? 'drop --no-fallback to read it over GraphQL, or run with --verbose for the cause'
+            : 'run with --verbose for the cause');
+    }
     await mkdirp(outDir);
     const lock = emptyLock(rootRepoId, net.organizationId, depth);
     lock.edges = discovery.edges;
@@ -284,7 +322,7 @@ export const run = async (p) => {
         organizationId: net.organizationId,
         depth,
         lastPullSource: sources.size > 1 ? 'mixed' : (sources.values().next().value ?? 'reconstructed'),
-        tool: { name: 'pipefy-process-coder', version: '0.1.0' },
+        tool: { ...TOOL },
     });
     /**
      * Read the closed sets while the client is open. Two queries, and it is what
@@ -492,7 +530,7 @@ const pullFromFile = async (p, fromFile) => {
         organizationId: str(p, 'org') ?? null,
         depth: 0,
         lastPullSource: env.source,
-        tool: { name: 'pipefy-process-coder', version: '0.1.0' },
+        tool: { ...TOOL },
     });
     await writeDocs(outDir, lock, [tree], null, await loadReference(outDir));
     ok(`${rootRef.kind} ${repoIdNum} ${green(rootRef.name ?? '')} — ${tree.phases.length} phases, ` +

package/dist/pipefy/agents.js

@@ -1,4 +1,39 @@
 import { debug } from "../util/log.js";
+/**
+ * The selection under `aiBehaviorParams`, aliased to the snake_case the files
+ * use. Shared with `internal.ts`'s `loadAutomation`, because `AiBehaviorParams`
+ * is the same object type on both endpoints — and the internal query once
+ * selected it bare, as though it were a scalar. GraphQL rejects that before
+ * resolving anything, so every automation in the pipe failed to load, not only
+ * the AI ones. One selection, two call sites, so the two cannot drift apart.
+ */
+export const AI_BEHAVIOR_PARAMS_SELECTION = `{
+  data_source_ids: dataSourceIds
+  instruction
+  referenced_field_ids: referencedFieldIds
+  provider_id: providerId
+  system_provider_id: systemProviderId
+  actions_attributes: actionsAttributes {
+    id
+    name
+    action_type: actionType
+    reference_id: referenceId
+    metadata {
+      destination_phase_id: destinationPhaseId
+      pipe_id: pipeId
+      table_id: tableId
+      email_template_id: emailTemplateId
+      allow_template_modifications: allowTemplateModifications
+      mcp_server_id: mcpServerId
+      tool_name: toolName
+      title
+      emails
+      tool_inputs: toolInputs { name source value field_id: fieldId }
+      fields_attributes: fieldsAttributes { field_id: fieldId input_mode: inputMode value }
+    }
+  }
+  capabilities_attributes: capabilitiesAttributes { capability_type: capabilityType enabled }
+}`;
 const QUERY = `
   query($repoUuid: ID!, $after: String) {
     aiAgents(repoUuid: $repoUuid, first: 50, after: $after) {
@@ -34,33 +69,7 @@ const QUERY = `
               expressions { id field_address operation value structure_id }
             }
             action_params {
-              ai_behavior_params: aiBehaviorParams {
-                data_source_ids: dataSourceIds
-                instruction
-                referenced_field_ids: referencedFieldIds
-                provider_id: providerId
-                system_provider_id: systemProviderId
-                actions_attributes: actionsAttributes {
-                  id
-                  name
-                  action_type: actionType
-                  reference_id: referenceId
-                  metadata {
-                    destination_phase_id: destinationPhaseId
-                    pipe_id: pipeId
-                    table_id: tableId
-                    email_template_id: emailTemplateId
-                    allow_template_modifications: allowTemplateModifications
-                    mcp_server_id: mcpServerId
-                    tool_name: toolName
-                    title
-                    emails
-                    tool_inputs: toolInputs { name source value field_id: fieldId }
-                    fields_attributes: fieldsAttributes { field_id: fieldId input_mode: inputMode value }
-                  }
-                }
-                capabilities_attributes: capabilitiesAttributes { capability_type: capabilityType enabled }
-              }
+              ai_behavior_params: aiBehaviorParams ${AI_BEHAVIOR_PARAMS_SELECTION}
             }
           }
         }

package/dist/pipefy/internal.js

@@ -1,6 +1,120 @@
 import { ENDPOINTS } from "../config.js";
 import { debug, warn } from "../util/log.js";
 import { retry } from "../util/pool.js";
+import { AI_BEHAVIOR_PARAMS_SELECTION } from "./agents.js";
+/**
+ * The internal-API adapter. PLAN.md §2.1 flags this as an unversioned endpoint
+ * with no compatibility contract, so it is isolated here, behind one module,
+ * and every entry point degrades to `null`/`unsupported` rather than throwing.
+ *
+ * Two things live only here — both taken from the Change Migrator recipes,
+ * which have been running them in production:
+ *
+ *  1. Automations. Public `getAutomations` returns a summary; the recipes use
+ *     `loadAutomationToEdit` to get `action_params.field_map`, `searchFor`,
+ *     `responseSchema`, `schedulerCron` and `aiParams` — everything a
+ *     round trip needs and the summary omits.
+ *  2. Phase jumps. `GET/PUT /internal_api/settings/phases/:id`, set-replacing.
+ *
+ * Both accept the same personal API token as the public endpoint, so there is
+ * no session-cookie or CSRF subsystem here.
+ */
+/** Sent by `listAutomations`; module-level so `checkQueries` validates the same text. */
+const LIST_AUTOMATIONS_QUERY = `
+  query getAutomations($orgId: ID!, $repoId: ID) {
+    automations(organizationId: $orgId, repoId: $repoId) {
+      id
+      name
+      action_id
+      event_id
+      created_at
+      active
+      action_repo: action_repo_v2 {
+        __typename
+        ... on Pipe { id }
+        ... on Table { id }
+      }
+      event_repo { __typename id }
+    }
+  }`;
+/** Sent by `loadAutomation`; module-level so `checkQueries` validates the same text. */
+const LOAD_AUTOMATION_QUERY = `
+  query loadAutomationToEdit($id: ID!) {
+    automation(id: $id) {
+      name
+      event_id
+      active
+      event_repo { id }
+      event_params {
+        toPhaseId: to_phase_id
+        fromPhaseId
+        inPhaseId
+        triggerFieldIds
+        kindOfSla
+        triggerAutomationId
+      }
+      action_id
+      action_repo: action_repo_v2 {
+        ... on Pipe { id uuid }
+        ... on Table { id uuid }
+      }
+      scheduler_frequency
+      schedulerCron { minute hour dayOfWeek dayOfMonth month }
+      searchFor { id field operation value }
+      responseSchema
+      action_params {
+        toPhaseId: to_phase_id
+        fieldsMapOrder: fields_map_order
+        email_template_id
+        fieldMap: field_map { fieldId value inputMode }
+        cardId: card_id
+        headers
+        body
+        url
+        httpMethod
+        authenticationKey
+        hasAuthenticationValue
+        authenticationAddTo
+        authenticationType
+        strategy
+        # taskParams is not in the recipe's query, and the omission is not
+        # cosmetic: every send_a_task automation came back with an empty
+        # action_params, so a reconstructed read lost its recipients and
+        # title, and a recreate would have rebuilt it blank. Introspected
+        # from AutomationActionParams on the internal endpoint.
+        taskParams { recipients title }
+        aiParams { fieldIds value skillsIds }
+        aiBehaviorParams ${AI_BEHAVIOR_PARAMS_SELECTION}
+        slaParams {
+          monday { startHour endHour enabled }
+          tuesday { startHour endHour enabled }
+          wednesday { startHour endHour enabled }
+          thursday { startHour endHour enabled }
+          friday { startHour endHour enabled }
+          saturday { startHour endHour enabled }
+          sunday { startHour endHour enabled }
+          timezone
+          holidays { date recurrence description }
+        }
+      }
+      condition {
+        expressions_structure
+        expressions { id field_address operation value structure_id }
+      }
+    }
+  }`;
+/**
+ * Every read query document this adapter sends over GraphQL, with variables
+ * that match nothing. GraphQL validates the document before resolving any of
+ * it, so a query that has drifted from the schema is refused the same way
+ * whichever id it names — and a valid one answers `data` with a not-found
+ * error. No write is in this list, and none may be added: probing is not free
+ * on this platform (AGENTS.md §4).
+ */
+const READ_QUERIES = [
+    { label: 'listAutomations', query: LIST_AUTOMATIONS_QUERY, variables: { orgId: '0', repoId: '0' } },
+    { label: 'loadAutomation', query: LOAD_AUTOMATION_QUERY, variables: { id: '0' } },
+];
 export class InternalApi {
     tokenProvider;
     status = 'unknown';
@@ -14,13 +128,66 @@ export class InternalApi {
         return this.tokenProvider();
     }
     markUnavailable(reason) {
-        this.status = 'unavailable';
+        if (this.status !== 'incompatible')
+            this.status = 'unavailable';
         if (!this.warned) {
             this.warned = true;
             warn(`internal API unavailable (${reason}). Automation details and phase jumps ` +
                 `will be reported as unknown rather than empty — see PLAN.md §2.1.`);
         }
     }
+    /** One answered call does not clear a refused query: that stays visible. */
+    markOk() {
+        if (this.status !== 'incompatible')
+            this.status = 'ok';
+    }
+    markIncompatible(label, reason) {
+        this.status = 'incompatible';
+        if (!this.warned) {
+            this.warned = true;
+            warn(`internal API rejected this tool's ${label} query as invalid (${reason}). ` +
+                `That is a bug in pipe, not an outage — the endpoint changed under it. Automation ` +
+                `details will be reported as unknown rather than empty; \`pipe doctor\` checks every internal query.`);
+        }
+    }
+    /**
+     * Validate every read query against the live schema without reading anything
+     * real. Null when the endpoint itself could not be reached, which says
+     * nothing about the queries.
+     */
+    async checkQueries() {
+        const results = [];
+        for (const { label, query, variables } of READ_QUERIES) {
+            let body;
+            try {
+                this.requestCount++;
+                const res = await fetch(ENDPOINTS.internal, {
+                    method: 'POST',
+                    headers: {
+                        authorization: `Bearer ${await this.bearer()}`,
+                        'content-type': 'application/json',
+                        accept: 'application/json',
+                    },
+                    body: JSON.stringify({ query, variables }),
+                });
+                if (!res.ok) {
+                    debug(`internal query check ${label}: HTTP ${res.status}`);
+                    return null;
+                }
+                body = JSON.parse(await res.text());
+            }
+            catch (e) {
+                debug(`internal query check ${label}: ${e.message}`);
+                return null;
+            }
+            if ('data' in body)
+                results.push({ label, ok: true });
+            else
+                results.push({ label, ok: false, message: (body.errors ?? []).map((e) => e.message).join('; ') || 'no data' });
+        }
+        this.status = results.every((r) => r.ok) ? 'ok' : 'incompatible';
+        return results;
+    }
     /** GraphQL over the internal endpoint. Returns null when the endpoint fails. */
     async gql(query, variables, label) {
         try {
@@ -45,41 +212,30 @@ export class InternalApi {
                 if (body.errors?.length) {
                     const err = new Error(body.errors.map((e) => e.message).join('; '));
                     err.retryable = false;
+                    // No `data` key at all is a document the schema refused, not a
+                    // resolver failing on this one id — see InternalStatus.
+                    err.invalidQuery = !('data' in body);
                     throw err;
                 }
                 return body.data ?? null;
             }, { label });
             if (data)
-                this.status = 'ok';
+                this.markOk();
             return data;
         }
         catch (e) {
             debug(`internal gql ${label} failed: ${e.message}`);
-            this.markUnavailable(`${label}: ${e.message}`);
+            if (e.invalidQuery)
+                this.markIncompatible(label, e.message);
+            else
+                this.markUnavailable(`${label}: ${e.message}`);
             return null;
         }
     }
     // ── Automations ────────────────────────────────────────────────────────────
     /** Recipe `Pipe Data Treatment` step 156. */
     async listAutomations(orgId, repoId) {
-        const q = `
-      query getAutomations($orgId: ID!, $repoId: ID) {
-        automations(organizationId: $orgId, repoId: $repoId) {
-          id
-          name
-          action_id
-          event_id
-          created_at
-          active
-          action_repo: action_repo_v2 {
-            __typename
-            ... on Pipe { id }
-            ... on Table { id }
-          }
-          event_repo { __typename id }
-        }
-      }`;
-        const data = await this.gql(q, { orgId: String(orgId), repoId: String(repoId) }, 'listAutomations');
+        const data = await this.gql(LIST_AUTOMATIONS_QUERY, { orgId: String(orgId), repoId: String(repoId) }, 'listAutomations');
         return data?.automations ?? null;
     }
     /**
@@ -89,72 +245,7 @@ export class InternalApi {
      * cannot avoid the internal API for automations.
      */
     async loadAutomation(id) {
-        const q = `
-      query loadAutomationToEdit($id: ID!) {
-        automation(id: $id) {
-          name
-          event_id
-          active
-          event_repo { id }
-          event_params {
-            toPhaseId: to_phase_id
-            fromPhaseId
-            inPhaseId
-            triggerFieldIds
-            kindOfSla
-            triggerAutomationId
-          }
-          action_id
-          action_repo: action_repo_v2 {
-            ... on Pipe { id uuid }
-            ... on Table { id uuid }
-          }
-          scheduler_frequency
-          schedulerCron { minute hour dayOfWeek dayOfMonth month }
-          searchFor { id field operation value }
-          responseSchema
-          action_params {
-            toPhaseId: to_phase_id
-            fieldsMapOrder: fields_map_order
-            email_template_id
-            fieldMap: field_map { fieldId value inputMode }
-            cardId: card_id
-            headers
-            body
-            url
-            httpMethod
-            authenticationKey
-            hasAuthenticationValue
-            authenticationAddTo
-            authenticationType
-            strategy
-            # taskParams is not in the recipe's query, and the omission is not
-            # cosmetic: every send_a_task automation came back with an empty
-            # action_params, so a reconstructed read lost its recipients and
-            # title, and a recreate would have rebuilt it blank. Introspected
-            # from AutomationActionParams on the internal endpoint.
-            taskParams { recipients title }
-            aiParams { fieldIds value skillsIds }
-            aiBehaviorParams
-            slaParams {
-              monday { startHour endHour enabled }
-              tuesday { startHour endHour enabled }
-              wednesday { startHour endHour enabled }
-              thursday { startHour endHour enabled }
-              friday { startHour endHour enabled }
-              saturday { startHour endHour enabled }
-              sunday { startHour endHour enabled }
-              timezone
-              holidays { date recurrence description }
-            }
-          }
-          condition {
-            expressions_structure
-            expressions { id field_address operation value structure_id }
-          }
-        }
-      }`;
-        const data = await this.gql(q, { id: String(id) }, `loadAutomation ${id}`);
+        const data = await this.gql(LOAD_AUTOMATION_QUERY, { id: String(id) }, `loadAutomation ${id}`);
         return data?.automation ?? null;
     }
     /** Recipe `Apply Changes` step 121. `input` is the AutomationInput variable set. */
@@ -236,7 +327,7 @@ export class InternalApi {
             const d = res.data ?? {};
             const attrs = d.attributes ?? {};
             const targets = attrs.jump_targets ?? d.jump_targets ?? [...(d.next_phase_ids ?? []), ...(d.back_phase_ids ?? [])];
-            this.status = 'ok';
+            this.markOk();
             return {
                 jump_targets: [...new Set(targets.map(Number).filter((n) => Number.isFinite(n)))],
                 phases: (attrs.phases ?? []).map(([id, name, done]) => ({ id: Number(id), name: String(name), done: Boolean(done) })),
@@ -302,7 +393,7 @@ export class InternalApi {
             const want = [...new Set(targetPhaseIds.map(Number))].sort((a, b) => a - b);
             const got = [...new Set(echoed)].sort((a, b) => a - b);
             const ok = want.length === got.length && want.every((v, i) => v === got[i]);
-            this.status = 'ok';
+            this.markOk();
             return ok
                 ? { ok, echoed }
                 : { ok, echoed, error: `echo mismatch: wanted [${want.join(',')}], endpoint reports [${got.join(',')}]` };

package/dist/pipefy/reconstruct.js

@@ -626,6 +626,8 @@ const CAMEL_TO_SNAKE = {
     hasAuthenticationValue: 'has_authentication_value',
     authenticationAddTo: 'authentication_add_to',
     aiParams: 'ai_params',
+    // Its own subfields arrive already aliased to snake_case (AI_BEHAVIOR_PARAMS_SELECTION).
+    aiBehaviorParams: 'ai_behavior_params',
     slaParams: 'sla_params',
     taskParams: 'task_params',
     fieldIds: 'field_ids',

package/dist/pipefy/toolkit.js

@@ -95,41 +95,56 @@ export const inspectToolkit = async () => {
     cachedInterpreter ??= await findInterpreter();
     if (!cachedInterpreter)
         return { installed: false };
-    const credential = await readBearer();
-    if (!credential)
+    const run = await runHelper();
+    if (!run)
         return { installed: false };
+    if ('error' in run) {
+        return { installed: true, usable: false, cliPath: toolkitBinary('pipefy'), interpreter: cachedInterpreter.command, error: run.error };
+    }
     return {
         installed: true,
+        usable: true,
         cliPath: toolkitBinary('pipefy'),
         mcpServerPath: toolkitBinary('pipefy-mcp-server'),
         interpreter: cachedInterpreter.command,
-        credential,
+        credential: run.result,
     };
 };
 /**
- * Ask the toolkit for a bearer. `null` means the toolkit could not be used at
- * all — distinct from a `{ ok: false }` result, which is the toolkit answering
- * that it holds no credential.
+ * Run the helper. `null` means there is nothing to run it with; `{ error }`
+ * means it ran and could not use the toolkit, carrying its own explanation
+ * (the helper prints which `pipefy_auth` version it found and what it lacks).
  */
-export const readBearer = async () => {
+const runHelper = async () => {
     cachedInterpreter ??= await findInterpreter();
     if (!cachedInterpreter)
         return null;
     if (!existsSync(HELPER)) {
         debug(`toolkit helper missing at ${HELPER}`);
-        return null;
+        return { error: `this install of pipe is missing its toolkit helper (${HELPER})` };
     }
     try {
         const { stdout } = await exec(cachedInterpreter.command, [...cachedInterpreter.args, HELPER], { timeout: 60_000, maxBuffer: 1024 * 1024 });
         const parsed = JSON.parse(stdout.trim());
         debug(`toolkit credential: ${parsed.ok ? parsed.source : parsed.reason}`);
-        return parsed;
+        return { result: parsed };
     }
     catch (e) {
-        debug(`toolkit bearer helper failed: ${e.message}`);
-        return null;
+        const err = e;
+        debug(`toolkit bearer helper failed: ${err.message}`);
+        const said = err.stderr?.trim().split(/\r?\n/).filter(Boolean).pop();
+        return { error: said || err.message.split(/\r?\n/)[0] || 'the toolkit helper failed' };
     }
 };
+/**
+ * Ask the toolkit for a bearer. `null` means the toolkit could not be used at
+ * all — distinct from a `{ ok: false }` result, which is the toolkit answering
+ * that it holds no credential.
+ */
+export const readBearer = async () => {
+    const run = await runHelper();
+    return run && 'result' in run ? run.result : null;
+};
 /** Run `pipefy auth login`, inheriting the terminal so the browser flow works. */
 export const runToolkitLogin = async (extraArgs = []) => {
     const cli = toolkitBinary('pipefy');
@@ -155,4 +170,5 @@ export const toolkitAuthStatus = async () => {
         return null;
     }
 };
+export const UPGRADE_HINT = 'reinstall the toolkit: `uv tool install --force --reinstall pipefy-cli` (any pipefy-auth from 0.3.0a1 to 0.5.4b1 on PyPI works)';
 export const INSTALL_HINT = 'install the Pipefy AI toolkit (github.com/pipefy/ai-toolkit): `uv tool install pipefy-cli`, then `pipefy auth login`';

package/dist/pipefy/toolkit_bearer.py

@@ -31,22 +31,63 @@ def _fail(reason: str, message: str) -> int:
 
 
 def main() -> int:
+    # Import the module, then look the names up one by one, so an incompatible
+    # install says which names it lacks and which version it is — rather than
+    # one ImportError that left `pipe doctor` reporting the toolkit as "not
+    # installed" on a machine where it plainly was. Every pipefy-auth release on
+    # PyPI (0.3.0a1 through 0.5.4b1) exports all of these; a field report of
+    # one that lacked ServiceAccountAuth came from an install none of them
+    # explain, so this names what it found instead of guessing why.
     try:
-        from pipefy_auth import (  # noqa: PLC0415
-            AuthSettings,
-            OidcClient,
-            ServiceAccountAuth,
-            StaticTokenAuth,
-            StoredSessionAuth,
-            configure_keychain_backend,
-            ensure_fresh_session,
-            resolve_pipefy_auth,
-        )
-        from pipefy_auth.resolver import ServiceAccount  # noqa: PLC0415
+        import pipefy_auth  # noqa: PLC0415
     except Exception as exc:  # pragma: no cover - environment problem
         print(f"pipefy_auth is not importable: {exc}", file=sys.stderr)
         return 3
 
+    version = getattr(pipefy_auth, "__version__", None)
+    if version is None:
+        try:
+            from importlib.metadata import version as dist_version  # noqa: PLC0415
+
+            version = dist_version("pipefy-auth")
+        except Exception:
+            version = "unknown"
+    where = getattr(pipefy_auth, "__file__", "?")
+
+    # Required for every credential this helper can return.
+    required = (
+        "AuthSettings",
+        "OidcClient",
+        "StaticTokenAuth",
+        "StoredSessionAuth",
+        "ensure_fresh_session",
+        "resolve_pipefy_auth",
+    )
+    missing = [n for n in required if not hasattr(pipefy_auth, n)]
+    if missing:
+        print(
+            f"pipefy_auth {version} at {where} is incompatible: it lacks {', '.join(missing)}",
+            file=sys.stderr,
+        )
+        return 3
+
+    AuthSettings = pipefy_auth.AuthSettings
+    OidcClient = pipefy_auth.OidcClient
+    StaticTokenAuth = pipefy_auth.StaticTokenAuth
+    StoredSessionAuth = pipefy_auth.StoredSessionAuth
+    ensure_fresh_session = pipefy_auth.ensure_fresh_session
+    resolve_pipefy_auth = pipefy_auth.resolve_pipefy_auth
+    # Only a service-account credential needs these, so their absence costs
+    # that one method, not the static token or the browser session.
+    ServiceAccountAuth = getattr(pipefy_auth, "ServiceAccountAuth", None)
+    ServiceAccount = getattr(pipefy_auth, "ServiceAccount", None)
+    if ServiceAccount is None:
+        try:
+            from pipefy_auth.resolver import ServiceAccount  # noqa: PLC0415
+        except Exception:
+            ServiceAccount = None
+    configure_keychain_backend = getattr(pipefy_auth, "configure_keychain_backend", None)
+
     settings = AuthSettings()
 
     # Select the keyring backend before any session read. On Windows the default
@@ -54,10 +95,15 @@ def main() -> int:
     # ~2.5 KB), so machines set `keychain_backend = "file"` — and a reader that
     # skips this looks in the empty store and reports "not signed in" while
     # `pipefy auth status` says otherwise.
-    configure_keychain_backend(settings.keychain_backend)
+    if configure_keychain_backend is not None:
+        configure_keychain_backend(settings.keychain_backend)
 
     service_account = None
-    if settings.service_account_client_id and settings.service_account_client_secret:
+    if (
+        ServiceAccount is not None
+        and settings.service_account_client_id
+        and settings.service_account_client_secret
+    ):
         service_account = ServiceAccount(
             token_url=settings.service_account_url,
             client_id=settings.service_account_client_id,
@@ -107,7 +153,7 @@ def main() -> int:
         )
         return 0
 
-    if isinstance(resolved, ServiceAccountAuth):
+    if ServiceAccountAuth is not None and isinstance(resolved, ServiceAccountAuth):
         # The client-credentials exchange happens here so the secret never
         # crosses the process boundary — only the short-lived bearer does.
         import httpx  # noqa: PLC0415

package/dist/report/run.js

@@ -3,6 +3,7 @@ import { promises as fs } from 'node:fs';
 import { mkdirp, writeFile, writeJson, exists } from "../util/fsx.js";
 import { paths } from "../workspace/layout.js";
 import { integrationsFrom, renderIntegrations } from "./integrations.js";
+import { TOOL } from "../version.js";
 const stamp = (d = new Date()) => d.toISOString().replace(/[:.]/g, '-').replace(/-\d{3}Z$/, 'Z');
 /**
  * The command as typed, for reproduction — with any token elided. `--token` is
@@ -105,7 +106,7 @@ export class RunRecorder {
             id: this.id,
             kind: this.kind,
             command: this.ctx.command,
-            tool: { name: 'pipefy-process-coder', version: '0.1.0' },
+            tool: { ...TOOL },
             startedAt: this.startedAt.toISOString(),
             finishedAt: finished.toISOString(),
             durationMs: finished.getTime() - this.startedAt.getTime(),

package/dist/version.js

@@ -0,0 +1,18 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The tool's identity as recorded in workspace.json and every run.json.
+ *
+ * The version is read from package.json, the same file `pipe --version` reads,
+ * because it used to be a literal `'0.1.0'` in three places that a release did
+ * not touch — so 0.1.1 stamped 0.1.0 on everything it wrote, and the one field
+ * meant to say which build produced a workspace said the wrong one.
+ *
+ * `dist/` mirrors `src/` one-for-one, so `../package.json` from here is the
+ * package root from either tree.
+ */
+const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
+export const PACKAGE_NAME = pkg.name;
+export const TOOL_VERSION = pkg.version;
+export const TOOL = { name: 'pipefy-process-coder', version: TOOL_VERSION };

package/dist/workspace/docs.js

@@ -280,7 +280,7 @@ const CAPABILITIES_MD = (caps) => {
 | \`importRepoSnapshot\` | ${caps.importRepoSnapshot ? 'yes' : 'no'} | Route B is unavailable; writes go through the mutation compiler |
 | internal API | ${caps.internalApi} | automation detail and phase-jump editing depend on it |
 
-${caps.internalApi === 'unavailable' ? '> The internal endpoint did not answer. Automations and phase jumps are reported as **unknown** rather than empty, and any change to them is refused rather than silently skipped.\n' : ''}`
+${caps.internalApi === 'unavailable' ? '> The internal endpoint did not answer. Automations and phase jumps are reported as **unknown** rather than empty, and any change to them is refused rather than silently skipped.\n' : ''}${caps.internalApi === 'incompatible' ? '> The internal endpoint refused one of this tool\'s own queries as invalid — a bug in `pipe`, not an outage. Automations are reported as **unknown** or **partial** rather than empty, and any change to them is refused. `pipe doctor` names the query.\n' : ''}`
         : '';
     return `# Capabilities
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@pipefy/pipefy-process-coder",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Pull a Pipefy pipe to disk as readable JSON, edit it with an agent, diff it, push it back.",
   "type": "module",
-  "license": "UNLICENSED",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Guilherme-CA-Dias/pipefy-process-coder.git"
@@ -15,7 +15,8 @@
     "bin",
     "dist",
     ".agents/skills",
-    "AGENTS.md"
+    "AGENTS.md",
+    "NOTICE"
   ],
   "engines": {
     "node": ">=22.18"