@introspection-sdk/introspection-node 0.13.0 → 0.14.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @introspection-sdk/introspection-node@0.13.0 build /home/runner/work/introspection-js-sdk/introspection-js-sdk/packages/introspection-node
+> @introspection-sdk/introspection-node@0.14.0 build /home/runner/work/introspection-js-sdk/introspection-js-sdk/packages/introspection-node
 > tsc
 

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAuB,KAAK,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,WAAW,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAExE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,mBAAmB;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAE1C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,oBAAoB,CAAC;IAEtD;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,cAAc,GAAG,uBAAuB,CAAC;IAE/D;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;gBAEjB,OAAO,GAAE,0BAA+B;IAgCpD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;WACU,kBAAkB,CAC7B,MAAM,EAAE,yBAAyB,GAAG;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3D,OAAO,CAAC,mBAAmB,CAAC;IAS/B,wCAAwC;IAClC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAKhC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAuB,KAAK,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,WAAW,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGxE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,mBAAmB;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAE1C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,oBAAoB,CAAC;IAEtD;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,cAAc,GAAG,uBAAuB,CAAC;IAE/D;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;gBAEjB,OAAO,GAAE,0BAA+B;IA0CpD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;WACU,kBAAkB,CAC7B,MAAM,EAAE,yBAAyB,GAAG;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3D,OAAO,CAAC,mBAAmB,CAAC;IAS/B,wCAAwC;IAClC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAKhC"}

package/dist/client.js

@@ -17,6 +17,7 @@ import { HttpClient } from "./http.js";
 import { attachRuntimes, } from "./resources/runtimes.js";
 import { attachExperiments, } from "./resources/experiments.js";
 import { attachRecipes } from "./resources/recipes.js";
+import { DEV_TARGET_HEADER, resolveDevTarget } from "./dev-target.js";
 /**
  * Introspection REST client.
  *
@@ -61,20 +62,29 @@ export class IntrospectionClient {
     constructor(options = {}) {
         const token = options.token || process.env.INTROSPECTION_TOKEN || "";
         const advanced = options.advanced || {};
-        this.advancedOptions = advanced;
         const baseApiUrl = advanced.baseApiUrl ||
             process.env.INTROSPECTION_BASE_API_URL ||
             "https://api.introspection.dev";
         if (!token) {
             sdkLogger.warn("IntrospectionClient: No token provided. REST calls will fail.");
         }
+        // INTROSPECTION_DEV_TARGET rides every request as a header so it reaches
+        // the paths a runner cannot: a bare `POST /v1/tasks` with a dev API key
+        // mints its JWT from the key row and has no per-request claim to carry.
+        // Merged first, so an explicit `additionalHeaders` entry still wins, and
+        // stored on advancedOptions so the Runner's own DP client inherits it.
+        const devTarget = resolveDevTarget();
+        const additionalHeaders = devTarget
+            ? { [DEV_TARGET_HEADER]: devTarget, ...advanced.additionalHeaders }
+            : advanced.additionalHeaders;
+        this.advancedOptions = { ...advanced, additionalHeaders };
         // CP HTTP client — talks to the customer-facing API with the customer
         // API key. Runners get their own HttpClient instances pointed at the
         // `deployment.endpoint` returned by `/v1/runtimes/{id}/run`.
         this.cpHttp = new HttpClient({
             apiUrl: baseApiUrl,
             token,
-            additionalHeaders: advanced.additionalHeaders,
+            additionalHeaders: this.advancedOptions.additionalHeaders,
             fetch: advanced.fetch,
         });
         this.runtimes = attachRuntimes(this, this.cpHttp);

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,EAAE,mBAAmB,EAAkC,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EACL,cAAc,GAGf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,iBAAiB,GAGlB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,aAAa,EAAmB,MAAM,wBAAwB,CAAC;AAExE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,mBAAmB;IAC9B,2EAA2E;IAClE,MAAM,CAAa;IAC5B,mFAAmF;IAC1E,eAAe,CAAkB;IAE1C;;;;OAIG;IACM,QAAQ,CAAqC;IAEtD;;OAEG;IACM,WAAW,CAA2C;IAE/D;;;;OAIG;IACM,OAAO,CAAa;IAE7B,YAAY,UAAsC,EAAE;QAClD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,EAAE,CAAC;QACrE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;QACxC,IAAI,CAAC,eAAe,GAAG,QAAQ,CAAC;QAChC,MAAM,UAAU,GACd,QAAQ,CAAC,UAAU;YACnB,OAAO,CAAC,GAAG,CAAC,0BAA0B;YACtC,+BAA+B,CAAC;QAElC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,SAAS,CAAC,IAAI,CACZ,+DAA+D,CAChE,CAAC;QACJ,CAAC;QAED,sEAAsE;QACtE,qEAAqE;QACrE,6DAA6D;QAC7D,IAAI,CAAC,MAAM,GAAG,IAAI,UAAU,CAAC;YAC3B,MAAM,EAAE,UAAU;YAClB,KAAK;YACL,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;YAC7C,KAAK,EAAE,QAAQ,CAAC,KAAK;SACtB,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,GAAG,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,CAAC,WAAW,GAAG,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACxD,IAAI,CAAC,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAE1C,SAAS,CAAC,IAAI,CAAC,wCAAwC,UAAU,EAAE,CAAC,CAAC;IACvE,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAC7B,MAA4D;QAE5D,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC3D,OAAO,IAAI,mBAAmB,CAAC;YAC7B,KAAK,EAAE,YAAY;YACnB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,QAAQ,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE;SACjE,CAAC,CAAC;IACL,CAAC;IAED,wCAAwC;IACxC,KAAK,CAAC,QAAQ;QACZ,kEAAkE;QAClE,gDAAgD;QAChD,SAAS,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;CACF"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,EAAE,mBAAmB,EAAkC,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EACL,cAAc,GAGf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,iBAAiB,GAGlB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,aAAa,EAAmB,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,mBAAmB;IAC9B,2EAA2E;IAClE,MAAM,CAAa;IAC5B,mFAAmF;IAC1E,eAAe,CAAkB;IAE1C;;;;OAIG;IACM,QAAQ,CAAqC;IAEtD;;OAEG;IACM,WAAW,CAA2C;IAE/D;;;;OAIG;IACM,OAAO,CAAa;IAE7B,YAAY,UAAsC,EAAE;QAClD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,EAAE,CAAC;QACrE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;QACxC,MAAM,UAAU,GACd,QAAQ,CAAC,UAAU;YACnB,OAAO,CAAC,GAAG,CAAC,0BAA0B;YACtC,+BAA+B,CAAC;QAElC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,SAAS,CAAC,IAAI,CACZ,+DAA+D,CAChE,CAAC;QACJ,CAAC;QAED,yEAAyE;QACzE,wEAAwE;QACxE,wEAAwE;QACxE,yEAAyE;QACzE,uEAAuE;QACvE,MAAM,SAAS,GAAG,gBAAgB,EAAE,CAAC;QACrC,MAAM,iBAAiB,GAAG,SAAS;YACjC,CAAC,CAAC,EAAE,CAAC,iBAAiB,CAAC,EAAE,SAAS,EAAE,GAAG,QAAQ,CAAC,iBAAiB,EAAE;YACnE,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC;QAC/B,IAAI,CAAC,eAAe,GAAG,EAAE,GAAG,QAAQ,EAAE,iBAAiB,EAAE,CAAC;QAE1D,sEAAsE;QACtE,qEAAqE;QACrE,6DAA6D;QAC7D,IAAI,CAAC,MAAM,GAAG,IAAI,UAAU,CAAC;YAC3B,MAAM,EAAE,UAAU;YAClB,KAAK;YACL,iBAAiB,EAAE,IAAI,CAAC,eAAe,CAAC,iBAAiB;YACzD,KAAK,EAAE,QAAQ,CAAC,KAAK;SACtB,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,GAAG,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,CAAC,WAAW,GAAG,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACxD,IAAI,CAAC,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAE1C,SAAS,CAAC,IAAI,CAAC,wCAAwC,UAAU,EAAE,CAAC,CAAC;IACvE,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAC7B,MAA4D;QAE5D,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC3D,OAAO,IAAI,mBAAmB,CAAC;YAC7B,KAAK,EAAE,YAAY;YACnB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,QAAQ,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE;SACjE,CAAC,CAAC;IACL,CAAC;IAED,wCAAwC;IACxC,KAAK,CAAC,QAAQ;QACZ,kEAAkE;QAClE,gDAAgD;QAChD,SAAS,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;CACF"}

package/dist/dev-target.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Development-target resolution — which `introspection dev` server this
+ * process's tasks should reach.
+ *
+ * Two developers can run `introspection dev` against one shared Runtime. A
+ * task created by a shared application credential carries no developer, so the
+ * platform cannot tell their machines apart; the caller names one instead.
+ * `introspection dev` prints the value to set:
+ *
+ * ```
+ * serving as: roland
+ * for your app: INTROSPECTION_DEV_TARGET=roland
+ * ```
+ *
+ * Carried as a header rather than on the runner's `caller` payload: `caller`
+ * is descriptive metadata the platform never acts on, and a target is a
+ * per-request selector the platform does act on. Keeping them apart is what
+ * lets `caller` stay a free-form bag, and it is the only transport that
+ * reaches a bare `POST /v1/tasks` with a dev API key, whose JWT is minted from
+ * the key row with no per-request input path.
+ *
+ * Deliberately env-only, with no `os.userInfo()` fallback. Defaulting to the
+ * local username would be zero-config on a laptop and wrong everywhere else: a
+ * process running in a shared development deployment under an account like
+ * `node` would silently name a machine nobody is serving and fail closed,
+ * where today it reaches the one connected dev server. The CLI defaults to the
+ * username because it is naming *itself* and always runs on the developer's
+ * machine; this names *someone else's* machine and can run anywhere.
+ *
+ * Inert outside development: the Data Plane consults a target only on the
+ * development pin path, so a stray value in staging or production is ignored.
+ */
+/** Header carrying the target on requests that have no runner to ride. */
+export declare const DEV_TARGET_HEADER = "x-introspection-dev-target";
+/** The env var `introspection dev` prints and both the CLI and SDK read. */
+export declare const DEV_TARGET_ENV = "INTROSPECTION_DEV_TARGET";
+/**
+ * The development target for this process, or `undefined` when unset.
+ *
+ * Percent-encoded, because the value becomes an HTTP header and a header is
+ * bytes: a login name like `andré` is not transmissible as-is, and a runtime
+ * that lets it through sends latin-1 bytes the server would read back as a
+ * different string. Encoding here is lossless and costs nothing for the
+ * ordinary ASCII name, which encodes to itself.
+ *
+ * Safe to send encoded because the Data Plane decodes before it normalizes,
+ * so `andré` and `andr%C3%A9` land on the same target as the `--as andré`
+ * the CLI advertises over protobuf, where no encoding is needed.
+ *
+ * Read through `globalThis.process` so the module stays importable from
+ * non-Node runtimes that share this package's build.
+ */
+export declare function resolveDevTarget(): string | undefined;
+//# sourceMappingURL=dev-target.d.ts.map

package/dist/dev-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-target.d.ts","sourceRoot":"","sources":["../src/dev-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,+BAA+B,CAAC;AAE9D,4EAA4E;AAC5E,eAAO,MAAM,cAAc,6BAA6B,CAAC;AAkBzD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAOrD"}

package/dist/dev-target.js

@@ -0,0 +1,71 @@
+/**
+ * Development-target resolution — which `introspection dev` server this
+ * process's tasks should reach.
+ *
+ * Two developers can run `introspection dev` against one shared Runtime. A
+ * task created by a shared application credential carries no developer, so the
+ * platform cannot tell their machines apart; the caller names one instead.
+ * `introspection dev` prints the value to set:
+ *
+ * ```
+ * serving as: roland
+ * for your app: INTROSPECTION_DEV_TARGET=roland
+ * ```
+ *
+ * Carried as a header rather than on the runner's `caller` payload: `caller`
+ * is descriptive metadata the platform never acts on, and a target is a
+ * per-request selector the platform does act on. Keeping them apart is what
+ * lets `caller` stay a free-form bag, and it is the only transport that
+ * reaches a bare `POST /v1/tasks` with a dev API key, whose JWT is minted from
+ * the key row with no per-request input path.
+ *
+ * Deliberately env-only, with no `os.userInfo()` fallback. Defaulting to the
+ * local username would be zero-config on a laptop and wrong everywhere else: a
+ * process running in a shared development deployment under an account like
+ * `node` would silently name a machine nobody is serving and fail closed,
+ * where today it reaches the one connected dev server. The CLI defaults to the
+ * username because it is naming *itself* and always runs on the developer's
+ * machine; this names *someone else's* machine and can run anywhere.
+ *
+ * Inert outside development: the Data Plane consults a target only on the
+ * development pin path, so a stray value in staging or production is ignored.
+ */
+/** Header carrying the target on requests that have no runner to ride. */
+export const DEV_TARGET_HEADER = "x-introspection-dev-target";
+/** The env var `introspection dev` prints and both the CLI and SDK read. */
+export const DEV_TARGET_ENV = "INTROSPECTION_DEV_TARGET";
+/**
+ * Percent-encode to RFC 3986, so the three SDKs put identical bytes on the
+ * wire for the same target.
+ *
+ * `encodeURIComponent` leaves `!'()*` alone where Python's `quote(safe="")`
+ * and the Rust client encode them. The Data Plane decodes before it
+ * normalizes, so either form routes — but a header that differs by which
+ * client sent it is a debugging trap for no benefit.
+ */
+function encodeTarget(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+/**
+ * The development target for this process, or `undefined` when unset.
+ *
+ * Percent-encoded, because the value becomes an HTTP header and a header is
+ * bytes: a login name like `andré` is not transmissible as-is, and a runtime
+ * that lets it through sends latin-1 bytes the server would read back as a
+ * different string. Encoding here is lossless and costs nothing for the
+ * ordinary ASCII name, which encodes to itself.
+ *
+ * Safe to send encoded because the Data Plane decodes before it normalizes,
+ * so `andré` and `andr%C3%A9` land on the same target as the `--as andré`
+ * the CLI advertises over protobuf, where no encoding is needed.
+ *
+ * Read through `globalThis.process` so the module stays importable from
+ * non-Node runtimes that share this package's build.
+ */
+export function resolveDevTarget() {
+    const env = globalThis.process?.env;
+    const raw = env?.[DEV_TARGET_ENV];
+    const trimmed = raw?.trim();
+    return trimmed ? encodeTarget(trimmed) : undefined;
+}
+//# sourceMappingURL=dev-target.js.map

package/dist/dev-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-target.js","sourceRoot":"","sources":["../src/dev-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,iBAAiB,GAAG,4BAA4B,CAAC;AAE9D,4EAA4E;AAC5E,MAAM,CAAC,MAAM,cAAc,GAAG,0BAA0B,CAAC;AAEzD;;;;;;;;GAQG;AACH,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC,OAAO,CACtC,UAAU,EACV,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CACxD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,GAAG,GACP,UACD,CAAC,OAAO,EAAE,GAAG,CAAC;IACf,MAAM,GAAG,GAAG,GAAG,EAAE,CAAC,cAAc,CAAC,CAAC;IAClC,MAAM,OAAO,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC;IAC5B,OAAO,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACrD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@introspection-sdk/introspection-node",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "license": "Apache-2.0",
   "description": "Introspection observability SDK for Node.js",
   "engines": {
@@ -32,29 +32,29 @@
     }
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.215",
-    "@anthropic-ai/sdk": "^0.112.3",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.220",
+    "@anthropic-ai/sdk": "^0.115.0",
     "@earendil-works/pi-agent-core": "^0.80.10",
     "@earendil-works/pi-ai": "^0.80.10",
-    "@google/genai": "^2.12.0",
+    "@google/genai": "^2.13.0",
     "@langchain/core": "^1.2.3",
-    "@mastra/core": "^1.51.0",
-    "@mastra/observability": "^1.16.1",
+    "@mastra/core": "^1.52.1",
+    "@mastra/observability": "^1.16.2",
     "@openai/agents": "^0.13.5",
-    "@opentelemetry/api-logs": "^0.220.0",
-    "@opentelemetry/context-async-hooks": "^2.9.0",
-    "@opentelemetry/core": "^2.9.0",
-    "@opentelemetry/exporter-logs-otlp-proto": "^0.220.0",
-    "@opentelemetry/exporter-trace-otlp-proto": "^0.220.0",
-    "@opentelemetry/resources": "^2.9.0",
-    "@opentelemetry/sdk-logs": "^0.220.0",
-    "@opentelemetry/sdk-trace-base": "^2.9.0",
-    "@opentelemetry/sdk-trace-node": "^2.9.0",
+    "@opentelemetry/api-logs": "^0.221.0",
+    "@opentelemetry/context-async-hooks": "^2.10.0",
+    "@opentelemetry/core": "^2.10.0",
+    "@opentelemetry/exporter-logs-otlp-proto": "^0.221.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.221.0",
+    "@opentelemetry/resources": "^2.10.0",
+    "@opentelemetry/sdk-logs": "^0.221.0",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@opentelemetry/sdk-trace-node": "^2.10.0",
     "@opentelemetry/semantic-conventions": "^1.43.0",
     "@types/node": "^22.20.1",
-    "ai": "^6.0.230",
+    "ai": "^6.0.235",
     "eslint": "^9.39.5",
-    "openai": "^6.48.0",
+    "openai": "^6.49.0",
     "typescript": "5.9.3",
     "@repo/eslint-config": "0.0.0",
     "@repo/typescript-config": "0.0.0"
@@ -139,10 +139,10 @@
     "@opentelemetry/api": "^1.9.1",
     "https-proxy-agent": "^7.0.6",
     "proxy-from-env": "^2.1.0",
-    "@introspection-sdk/http": "0.13.0",
-    "@introspection-sdk/types": "0.13.0",
-    "@introspection-sdk/introspection-proxy": "0.13.0",
-    "@introspection-sdk/introspection-pi": "0.13.0"
+    "@introspection-sdk/http": "0.14.0",
+    "@introspection-sdk/introspection-pi": "0.14.0",
+    "@introspection-sdk/introspection-proxy": "0.14.0",
+    "@introspection-sdk/types": "0.14.0"
   },
   "scripts": {
     "lint": "eslint . --max-warnings 0",

package/src/client.ts

@@ -28,6 +28,7 @@ import {
   type ExperimentsApi,
 } from "./resources/experiments.js";
 import { attachRecipes, type RecipesApi } from "./resources/recipes.js";
+import { DEV_TARGET_HEADER, resolveDevTarget } from "./dev-target.js";
 
 /**
  * Introspection REST client.
@@ -77,7 +78,6 @@ export class IntrospectionClient {
   constructor(options: IntrospectionClientOptions = {}) {
     const token = options.token || process.env.INTROSPECTION_TOKEN || "";
     const advanced = options.advanced || {};
-    this.advancedOptions = advanced;
     const baseApiUrl =
       advanced.baseApiUrl ||
       process.env.INTROSPECTION_BASE_API_URL ||
@@ -89,13 +89,24 @@ export class IntrospectionClient {
       );
     }
 
+    // INTROSPECTION_DEV_TARGET rides every request as a header so it reaches
+    // the paths a runner cannot: a bare `POST /v1/tasks` with a dev API key
+    // mints its JWT from the key row and has no per-request claim to carry.
+    // Merged first, so an explicit `additionalHeaders` entry still wins, and
+    // stored on advancedOptions so the Runner's own DP client inherits it.
+    const devTarget = resolveDevTarget();
+    const additionalHeaders = devTarget
+      ? { [DEV_TARGET_HEADER]: devTarget, ...advanced.additionalHeaders }
+      : advanced.additionalHeaders;
+    this.advancedOptions = { ...advanced, additionalHeaders };
+
     // CP HTTP client — talks to the customer-facing API with the customer
     // API key. Runners get their own HttpClient instances pointed at the
     // `deployment.endpoint` returned by `/v1/runtimes/{id}/run`.
     this.cpHttp = new HttpClient({
       apiUrl: baseApiUrl,
       token,
-      additionalHeaders: advanced.additionalHeaders,
+      additionalHeaders: this.advancedOptions.additionalHeaders,
       fetch: advanced.fetch,
     });
 

package/src/dev-target.ts

@@ -0,0 +1,79 @@
+/**
+ * Development-target resolution — which `introspection dev` server this
+ * process's tasks should reach.
+ *
+ * Two developers can run `introspection dev` against one shared Runtime. A
+ * task created by a shared application credential carries no developer, so the
+ * platform cannot tell their machines apart; the caller names one instead.
+ * `introspection dev` prints the value to set:
+ *
+ * ```
+ * serving as: roland
+ * for your app: INTROSPECTION_DEV_TARGET=roland
+ * ```
+ *
+ * Carried as a header rather than on the runner's `caller` payload: `caller`
+ * is descriptive metadata the platform never acts on, and a target is a
+ * per-request selector the platform does act on. Keeping them apart is what
+ * lets `caller` stay a free-form bag, and it is the only transport that
+ * reaches a bare `POST /v1/tasks` with a dev API key, whose JWT is minted from
+ * the key row with no per-request input path.
+ *
+ * Deliberately env-only, with no `os.userInfo()` fallback. Defaulting to the
+ * local username would be zero-config on a laptop and wrong everywhere else: a
+ * process running in a shared development deployment under an account like
+ * `node` would silently name a machine nobody is serving and fail closed,
+ * where today it reaches the one connected dev server. The CLI defaults to the
+ * username because it is naming *itself* and always runs on the developer's
+ * machine; this names *someone else's* machine and can run anywhere.
+ *
+ * Inert outside development: the Data Plane consults a target only on the
+ * development pin path, so a stray value in staging or production is ignored.
+ */
+
+/** Header carrying the target on requests that have no runner to ride. */
+export const DEV_TARGET_HEADER = "x-introspection-dev-target";
+
+/** The env var `introspection dev` prints and both the CLI and SDK read. */
+export const DEV_TARGET_ENV = "INTROSPECTION_DEV_TARGET";
+
+/**
+ * Percent-encode to RFC 3986, so the three SDKs put identical bytes on the
+ * wire for the same target.
+ *
+ * `encodeURIComponent` leaves `!'()*` alone where Python's `quote(safe="")`
+ * and the Rust client encode them. The Data Plane decodes before it
+ * normalizes, so either form routes — but a header that differs by which
+ * client sent it is a debugging trap for no benefit.
+ */
+function encodeTarget(value: string): string {
+  return encodeURIComponent(value).replace(
+    /[!'()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
+/**
+ * The development target for this process, or `undefined` when unset.
+ *
+ * Percent-encoded, because the value becomes an HTTP header and a header is
+ * bytes: a login name like `andré` is not transmissible as-is, and a runtime
+ * that lets it through sends latin-1 bytes the server would read back as a
+ * different string. Encoding here is lossless and costs nothing for the
+ * ordinary ASCII name, which encodes to itself.
+ *
+ * Safe to send encoded because the Data Plane decodes before it normalizes,
+ * so `andré` and `andr%C3%A9` land on the same target as the `--as andré`
+ * the CLI advertises over protobuf, where no encoding is needed.
+ *
+ * Read through `globalThis.process` so the module stays importable from
+ * non-Node runtimes that share this package's build.
+ */
+export function resolveDevTarget(): string | undefined {
+  const env = (
+    globalThis as { process?: { env?: Record<string, string | undefined> } }
+  ).process?.env;
+  const raw = env?.[DEV_TARGET_ENV];
+  const trimmed = raw?.trim();
+  return trimmed ? encodeTarget(trimmed) : undefined;
+}